diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml index b07ee331ff..3dc5bb33e2 100644 --- a/en_US.ISO8859-1/articles/committers-guide/article.sgml +++ b/en_US.ISO8859-1/articles/committers-guide/article.sgml @@ -1,2256 +1,2257 @@ %man; %authors; %mailing-lists; ]>
Committer Guide The FreeBSD Documentation Project - $FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.68 2001/05/29 19:29:25 gsutter Exp $ + $FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.69 2001/06/02 05:45:59 dd Exp $ 1999 2000 2001 The FreeBSD Documentation Project This document provides information for the FreeBSD committer community. All new committers should read this document before they start, and existing committers are strongly encouraged to review it from time to time. Administrative Details Main Repository Host freefall.FreeBSD.org Login Methods &man.ssh.1; Main CVSROOT /home/ncvs Main CVS Repository Meisters &a.jdp; and &a.peter; as well as &a.asami; for ports/ Mailing List developers@FreeBSD.org, cvs-committers@FreeBSD.org Noteworthy CVS Tags RELENG_3 (3.x-STABLE), RELENG_4 (4.x-STABLE), HEAD (-CURRENT) It is required that you use &man.ssh.1; or &man.telnet.1; with Kerberos 5 to connect to the repository hosts. These are generally more secure than plain &man.telnet.1; or &man.rlogin.1; since credential negotiation will always be encrypted. All traffic is encrypted by default with &man.ssh.1;. With utilities like &man.ssh-agent.1; and &man.scp.1; also available, &man.ssh.1; is also far more convenient. If you do not know anything about &man.ssh.1;, please see . CVS Operations It is assumed that you are already familiar with the basic operation of CVS. The CVS Repository Meisters (Peter Wemm and John Polstra) are the owners of the CVS repository and are responsible for any and all direct modification of it for the purposes of cleanup or fixing some grievous abuse of CVS by a committer. No one else should attempt to touch the repository directly. Should you cause some repository accident, say a bad cvs import or tag operation, do not attempt to fix it yourself! Mail or call John or Peter immediately and report the problem to one of them instead. The only ones allowed to directly fiddle the repository bits are the repomeisters. Satoshi Asami is also a repomeister for the ports/ portion of the tree. CVS operations are usually done by logging into freefall, making sure the CVSROOT environment variable is set to /home/ncvs, and then doing the appropriate check-out/check-in operations. If you wish to add something which is wholly new (like contrib-ified sources, etc), a script called easy-import is also provided for making the process easier. It automatically adds the new module entry, does the appropriate thing with cvs import, etc. – just run it without arguments and it will prompt you for everything it needs to know. Note that when you use CVS on freefall, you should set your umask to 2, as well as setting the CVSUMASK environment variable to 2. This ensures that any new files created by cvs add will have the correct permissions. If you add a file or directory and discover that the file in the repository has incorrect permissions (specifically, all files in the repository should be group writable by group ncvs), contact one of the repository meisters as described below. If you are familiar with remote CVS and consider yourself pretty studly with CVS in general, you can also do CVS operations directly from your own machine and local working sources. Just remember to set CVS_RSH to ssh so that you are using a relatively secure and reliable transport. If you have no idea what any of the above even means, on the other hand, then please stick with logging into freefall and applying your diffs with &man.patch.1;. If you need to use CVS add and delete operations in a manner that is effectively a mv operation, then a repository copy is in order rather than your CVS add and delete. In a repository copy, a CVS Meister will copy the file(s) to their new name and/or location and let you know when it is done. The purpose of a repository copy is to preserve file change history, or logs. We in the FreeBSD Project greatly value the change history CVS gives to the project. CVS reference information, tutorials, and FAQs can also be found at: http://www.cvshome.org/docs/index.html &a.des; also supplied the following mini primer for CVS. Check out a module with the co or checkout command. &prompt.user; cvs checkout shazam This checks out a copy of the shazam module. If there is no shazam module in the modules file, it looks for a top-level directory named shazam instead. Useful <command>cvs checkout</command> options Don't create empty directories Check out a single level, no subdirectories Check out revision, branch or tag rev Check out the sources as they were on date date
Practical FreeBSD examples: Check out the miscfs module, which corresponds to src/sys/miscfs: &prompt.user; cvs co miscfs You now have a directory named miscfs with subdirectories CVS, deadfs, devfs, and so on. One of these (linprocfs) is empty. Check out the same files, but with full path: &prompt.user; cvs co src/sys/miscfs You now have a directory named src, with subdirectories CVS and sys. src/sys has subdirectories CVS and miscfs, etc. Check out the same files, but prunes empty directories: &prompt.user; cvs co -P miscfs You now have a directory named miscfs with subdirectories CVS, deadfs, devfs... but note that there is no linprocfs subdirectory, because there are no files in it. Check out the directory miscfs, but none of the subdirectories: &prompt.root; cvs co -l miscfs You now have a directory named miscfs with just one subdirectory named CVS. Check out the miscfs module as it is in the 4.x branch: &prompt.user; cvs co -rRELENG_4 miscfs You can modify the sources and commit along this branch. Check out the miscfs module as it was in 3.4-RELEASE. &prompt.user; cvs co -rRELENG_3_4_0_RELEASE miscfs You will not be able to commit modifications, since RELENG_3_4_0_RELEASE is a point in time, not a branch. Check out the miscfs module as it was on Jan 15 2000. &prompt.user; cvs co -D'01/15/2000' miscfs You will not be able to commit modifications. Check out the miscfs module as it was one week agao. &prompt.user; cvs co -D'last week' miscfs You will not be able to commit modifications. Note that cvs stores metadata in subdirectories named CVS. Arguments to and are sticky, which means cvs will remember them later, e.g. when you do a cvs update. Check the status of checked-out files with the status command. &prompt.user; cvs status shazam This displays the status of the shazam file or of every file in the shazam directory. For every file, the status is given as one of: Up-to-date File is up-to-date and unmodified. Needs Patch File is unmodified, but there's a newer revision in the repository. Locally Modified File is up-to-date, but modified. Needs Merge File is modified, and there's a newer revision in the repository. File had conflicts on merge There were conflicts the last time this file was updated, and they haven't been resolved yet. You'll also see the local revision and date, the revision number of the newest applicable version (newest applicable because if you have a sticky date, tag or branch, it may not be the actual newest revision), and any sticky tags, dates or options. Once you've checked something out, update it with the update command. &prompt.user; cvs update shazam This updates the shazam file or the contents of the shazam directory to the latest version along the branch you checked out. If you checked out a point in time, does nothing unless the tags have moved in the repository or some other weird stuff is going on. Useful options, in addition to those listed above for checkout: Check out any additional missing directories. Update to head of main branch. More magic (see below). If you checked out a module with or , running cvs update with a different or argument or with will select a new branch, revision or date. The option clears all sticky tags, dates or revisions whereas and set new ones. Theoretically, specifying HEAD as argument to will give you the same result as , but that's just theory. The option is useful if: somebody has added subdirectories to the module you've checked out after you checked it out. you checked out with , and later change your mind and want to check out the subdirectories as well. you deleted some subdirectories and want to check them all back out. Watch the output of the cvs update with care. The letter in front of each file name indicates what was done with it: U The file was updated with no trouble. P The file was updated with no trouble (you'll only see this when working against a remote repo). M The file had been modified, and was merged with no conflicts. C The file had been modified, and was merged with conflicts. Merging is what happens if you check out a copy of some source code, modify it, then someone else commits a change, and you run cvs update. CVS notices that you've made local changes, and tries to merge your changes with the changes between the version you originally checked out and the one you updated to. If the changed are to separate portions of the file, it'll almost always work fine (though the result might not be syntactically or semantically correct). CVS will print an 'M' in front of every locally modified file even if there is no newer version in the repository, so cvs update is handy for getting a summary of what you've changed locally. If you get a C, then your changes conflicted with the changes in the repository (the changes were to the same lines, or neighboring lines, or you changed the local file so much that cvs can't figure out how to apply the repository's changes). You'll have to go through the file manually and resolve the conflicts; they'll be marked with rows of <, = and > signs. For every conflict, there'll be a marker line with seven < signs and the name of the file, followed by a chunk of what your local file contained, followed by a separator line with seven = signs, followed by the corresponding chunk in the repository version, followed by a marker line with seven > signs and the revision number you updated to. The option is slightly voodoo. It updates the local file to the specified revision as if you used , but it does not change the recorded revision number or branch of the local file. It's not really useful except when used twice, in which case it will merge the changes between the two specified versions into the working copy. For instance, say you commit a change to shazam/shazam.c in -CURRENT and later want to MFC it. The change you want to MFC was revision 1.15: Check out the -STABLE version of the shazam module: &prompt.user; cvs co -rRELENG_4 shazam Apply the changes between rev 1.14 and 1.15: &prompt.user; cvs update -j1.14 -j1.15 shazam/shazam.c You'll almost certainly get a conflict because - of the $Id: article.sgml,v 1.69 2001-06-02 05:45:59 dd Exp $ (or in FreeBSD's case, + of the $Id: article.sgml,v 1.70 2001-06-03 21:39:50 dd Exp $ (or in FreeBSD's case, $FreeBSD$) lines, so you'll have to edit the file to resolve the conflict (remove the marker lines and - the second $Id: article.sgml,v 1.69 2001-06-02 05:45:59 dd Exp $ line, leaving the original - $Id: article.sgml,v 1.69 2001-06-02 05:45:59 dd Exp $ line intact). + the second $Id: article.sgml,v 1.70 2001-06-03 21:39:50 dd Exp $ line, leaving the original + $Id: article.sgml,v 1.70 2001-06-03 21:39:50 dd Exp $ line intact). View differences between the local version and the repository version with the diff command. &prompt.user; cvs diff shazam shows you every modification you've made to the shazam file or module. Useful <command>cvs diff</command> options Uses the unified diff format. Shows missing or added files.
You always want to use , since unified diffs are much easier to read than almost any other diff format (in some circumstances, context diffs may be better, but they're much bulkier). A unified diff consists of a series of hunks. Each hunk begins with a line that starts with two @ signs and specifies where in the file the differences are and how many lines they span. This is followed by a number of lines; some (preceded by a blank) are context; some (preceded by a - sign) are outtakes and some (preceded by a +) are additions. You can also diff against a different version than the one you checked out by specifying a version with or as in checkout or update, or even view the diffs between two arbitrary versions (with no regard for what you have locally) by specifying two versions with or . View log entries with the log command. &prompt.user; cvs log shazam See who did what with the annotate command. This command shows you each line of the specified file or files, along with which user most recently changed that line. &prompt.user; cvs annotate shazam Add new files with the add command. Create the file, cvs add it, then cvs commit it. Similarly, you can add new directories by creating them and then cvs adding them. Note that you don't need to commit directories. Remove obsolete files with the remove command. Remove the file, then cvs rm it, then cvs commit it. Commit with the commit or checkin command. Useful <command>cvs commit</command> options Force a commit of an unmodified file. Specify a commit message on the command line rather than invoking an editor.
Use the option if you realize that you left out important information from the commit message. Good commit messages are important. They tell others why you did the changes you did, not just right here and now, but months or years from now when someone wonders why some seemingly illogical or inefficient piece of code snuck into your source file. It's also an invaluable aid to deciding which changes to MFC and which not to MFC. Don't waste space in the commit messages explaining what you did. That's what cvs diff is for. Instead, tell us why you did it. Avoid committing several unrelated changes in one go. It makes merging difficult, and also makes it harder to determine which change is the culprit if a bug crops up. Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made. Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small groups of files) with tailored commit messages. Before committing, always: verify which branch you're committing to, using cvs status. review your diffs, using cvs diff Also, ALWAYS specify which files to commit explicitly on the command line, so you don't accidentally commit other files than the ones you intended - cvs commit with no arguments will commit every modification in your current working directory and every subdirectory. Additional tips and tricks: You can place commonly used options in your ~/.cvsrc, like this: cvs -z3 diff -Nu update -Pd checkout -P This example says: always use compression level 3 when talking to a remote server. This is a life-saver when working over a slow connection. always use the (show added or removed files) and (unified diff format) options to &man.diff.1;. always use the (prune empty directories) and (check out new directories) options when updating. always use the (prune empty directories) option when checking out. Use Eivind Eklund's cdiff script to view unidiffs. It's a wrapper for &man.less.1; that adds ANSI color codes to make hunk headers, outtakes and additions stand out; context and garbage are unmodified. It also expands tabs properly (tabs often look wrong in diffs because of the extra character in front of each line). http://people.FreeBSD.org/~eivind/cdiff Simply use it instead of &man.more.1; or &man.less.1;: &prompt.user; cvs diff -Nu shazam | cdiff Alternatively some editors like &man.vim.1; (ports/editors/vim5) have color support and when used as a pager with color syntax highlighting switched on will highlight many types of file, including diffs, patches, and cvs/rcs logs. &prompt.user; echo "syn on" >> ~/.vimrc &prompt.user; cvs diff -Nu shazam | vim - &prompt.user; cvs log shazam | vim - CVS is old, arcane, crufty and buggy, and sometimes exhibits non-deterministic behavior which some claim as proof that it's actually merely the Newtonian manifestation of a sentient transdimensional entity. It's not humanly possible to know its every quirk inside out, so don't be afraid to ask the resident AI (cvs@FreeBSD.org) for help when you screw up. Don't leave the cvs commit command in commit message editing mode for too long (more than 2-3 minutes). It locks the directory you are working with and will prevent other developers from committing into the same directory. If you have to type a long commit message, type it before executing cvs commit, and insert it into the commit message. Conventions and Traditions As a new committer there are a number of things you should do first. Add yourself to the Developers section of the Handbook and remove yourself from the Additional Contributors section. This is a relatively easy task, but remains a good first test of your CVS skills. Add an entry for yourself to www/en/news/newsflash.sgml. Look for the other entries that look like A new committer and follow the format. If you have a PGP or GnuPG key, you may want to add it to doc/en_US.ISO_8859-1/books/handbook/pgpkeys. Some people also add an entry for themselves to ports/astro/xearth/files/freebsd.committers.markers. Introduce yourself to the other committers, otherwise no one will have any idea who you are or what you are working on. You do not have to write a comprehensive biography, just write a paragraph or two about who you are and what you plan to be working on as a committer in FreeBSD. Email this to developers@FreeBSD.org and you will be on your way! Log into hub.FreeBSD.org and create a /var/forward/user (where user is your username) file containing the e-mail address where you want mail addressed to yourusername@FreeBSD.org to be forwarded. This includes all of the commit messages as well as any other mail addressed to cvs-committers@FreeBSD.org and developers@FreeBSD.org. Really large mailboxes which have taken up permanent residence on hub often get accidently truncated without warning, so forward it or read it and you will not lose it. All new committers also have a mentor assigned to them for the first few months. Your mentor is more or less responsible for explaining anything which is confusing to you and is also responsible for your actions during this initial period. If you make a bogus commit, it is only going to embarrass your mentor and you should probably make it a policy to pass at least your first few commits by your mentor before committing it to the repository. All commits should go to -CURRENT first before being merged to -STABLE. No major new features or high-risk modifications should be made to the -STABLE branch. Developer Relations If you are working directly on your own code or on code which is already well established as your responsibility, then there is probably little need to check with other committers before jumping in with a commit. If you see a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. If, however, you are about to modify something which is clearly being actively maintained by someone else (and it is only by watching the cvs-committers mailing list that you can really get a feel for just what is and is not) then consider sending the change to them instead, just as you would have before becoming a committer. For ports, you should contact the listed MAINTAINER in the Makefile. For other parts of the repository, if you are unsure who the active maintainer might be, it may help to scan the output of cvs log to see who has committed changes in the past. &a.fenner; has written a nice shell script that can help determine who the active maintainer might be. It lists each person who has committed to a given file along with the number of commits each person has made. It can be found on freefall at ~fenner/bin/whodid. If your queries go unanswered or the committer otherwise indicates a lack of proprietary interest in the area affected, go ahead and commit it. If you are unsure about a commit for any reason at all, have it reviewed by -hackers before committing. Better to have it flamed then and there rather than when it is part of the CVS repository. If you do happen to commit something which results in controversy erupting, you may also wish to consider backing the change out again until the matter is settled. Remember – with CVS we can always change it back. GNATS The FreeBSD Project utilizes GNATS for tracking bugs and change requests. Be sure that if you commit a fix or suggestion found in a GNATS PR, you use edit-pr pr-number on freefall to close it. It is also considered nice if you take time to close any PRs associated with your commits, if appropriate. You can also make use of &man.send-pr.1; yourself for proposing any change which you feel should probably be made, pending a more extensive peer-review first. You can find out more about GNATS at: http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html http://www.FreeBSD.org/support.html http://www.FreeBSD.org/send-pr.html &man.send-pr.1; You can run a local copy of GNATS, and then integrate the FreeBSD GNATS tree in to it using CVSup. Then you can run GNATS commands locally, or use other interfaces, such as tkgnats. This lets you query the PR database without needing to be connected to the Internet. Using a local GNATS tree If you are not already downloading the GNATS tree, add this line to your supfile, and re-sup. Note that since GNATS is not under CVS control it has no tag, so if you are adding it to your existing supfile it should appear before any tag= entry as these remain active once set. gnats release=current prefix=/usr This will place the FreeBSD GNATS tree in /usr/gnats. You can use a refuse file to control which categories to receive. For example, to only receive docs PRs, put this line in /usr/local/etc/cvsup/sup/refuse The precise path depends on the *default base setting in your supfile. . gnats/[a-ce-z]* The rest of these examples assume you have only supped the docs category. Adjust them as necessary, depending on the categories you are synching. Install the GNATS port from ports/databases/gnats. This will place the various GNATS directories under $PREFIX/share/gnats. Symlink the GNATS directories you are supping under the version of GNATS you have installed. &prompt.root; cd /usr/local/share/gnats/gnats-db &prompt.root; ln -s /usr/gnats/docs Repeat as necessary, depending on how many GNATS categories you are synching. Update the GNATS categories file with these categories. The file is $PREFIX/share/gnats/gnats-db/gnats-adm/categories. # This category is mandatory pending:Category for faulty PRs:gnats-admin: # # FreeBSD categories # docs:Documentation Bug:nik: Run $PREFIX/libexec/gnats/gen-index to recreate the GNATS index. The output has to be redirected to $PREFIX/share/gnats/gnats-db/gnats-adm/index. You can do this periodically from &man.cron.8;, or run &man.cvsup.1; from a shell script that does this as well. &prompt.root; /usr/local/libexec/gnats/gen-index \ > /usr/local/share/gnats/gnats-db/gnats-adm/index Test the configuration by querying the PR database. This command shows open docs PRs. &prompt.root; query-pr -c docs -s open Other interfaces, like ports/databases/tkgnats should also work nicely. Pick a PR and close it. This procedure only works to allow you to view and query the PRs locally. To edit or close them you will still have to log in to freefall and do it from there. Who's Who Besides Peter Wemm and John Polstra, the repository meisters, there are other FreeBSD project members whom you will probably get to know in your role as a committer. Briefly, and by no means all-inclusively, these are: &a.asami; Satoshi is the Ports Wraith, meaning that he has ultimate authority over any modifications to the ports collection or the ports skeleton makefiles. He is also the one responsible for administering ports freezes before the releases. &a.ru; - Ruslan is Mr mdoc(7). If you are writing a man page and need + Ruslan is Mister &man.mdoc.7;. If you are writing a + man page and need some advice on the structure, or the markup, ask Ruslan. &a.bde; Bruce is the Style Police-Meister. When you do a commit that could have been done better, Bruce will be there to tell you. Be thankful that someone is. Bruce is also very knowledgeable on the various standards applicable to FreeBSD. &a.gallatin; &a.mjacob; &a.dfr; &a.obrien; These are the primary developers and overseers of the DEC Alpha AXP platform. &a.dg; David is the overseer of the VM system. If you have a VM system change in mind, coordinate it with David. &a.jkh; Jordan is the release engineer. He is responsible for setting release deadlines and controlling the release process. During code freezes, he also has final authority on all changes to the system for whichever branch is pending release status. If there is something you want merged from -CURRENT to -STABLE (whatever values those may have at any given time), he is also the one to talk to about it. &a.bmah; Bruce is keeper of the release notes (src/release/texts/* or src/release/doc/*, as appropriate). If you commit a change that you think is worthy of mention in the release notes, please make sure Bruce knows about it. Better still, send him a patch with your suggested commentary for the release notes. &a.obrien; David is the unofficial src/contrib-Meister. If you have something significant you'd like to do there, you should probably coordinate it with David first. Please consult him before importing into src/contrib if you have never done this before in the FreeBSD CVS repository. Also if you need to commit to something you do not maintain in src/contrib and it is unclear who the maintainer / point of contact is. (It is also not a bad idea to consult David if you need to make a non-import commit to something you maintain in src/contrib and you are new to how FreeBSD does things.) &a.brian; Official maintainer of /usr/sbin/ppp. &a.wollman; If you need advice on obscure network internals or aren't sure of some potential change to the networking subsystem you have in mind, Garrett is someone to talk to. Garrett is also very knowledgeable on the various standards applicable to FreeBSD. &a.committers; cvs-committers is the entity that CVS uses to send you all your commit messages. You should never send email directly to this list. You should only send replies to this list when they are short and are directly related to a commit. &a.developers; developers is all committers. This list was created to be a forum for the committers "community" issues. Examples are Core voting, announcements, etc... developers@FreeBSD.org is not intended as a place for code reviews or a replacement for arch@FreeBSD.org or audit@FreeBSD.org. In fact using it as such hurts the FreeBSD Project as it gives a sense of a closed list where general decisions affecting all of the FreeBSD using community are made with out being "open". SSH Quick-Start Guide If you are using FreeBSD 4.0 or later, OpenSSH is included in the base system. If you are using an earlier release, update and install one of the SSH ports. In general, you will probably want to get OpenSSH from the port in /usr/ports/security/openssh. You may also wish to check out the original ssh1 in /usr/ports/security/ssh, but make certain you pay attention to its license. Note that both of these ports cannot be installed at the same time. If you do not wish to type your password in every time you use &man.ssh.1;, and you use RSA keys to authenticate, &man.ssh-agent.1; is there for your convenience. If you want to use &man.ssh-agent.1;, make sure that you run it before running other applications. X users, for example, usually do this from their .xsession or .xinitrc file. See &man.ssh-agent.1; for details. Generate a key pair using &man.ssh-keygen.1;. The key pair will wind up in the $HOME/.ssh directory. Send your public key ($HOME/.ssh/identity.pub) to the person setting you up as a committer so it can be put into your authorized_keys file in your home directory on freefall (i.e. $HOME/.ssh/authorized_keys). Now you should be able to use &man.ssh-add.1; for authentication once per session. This will prompt you for your private key's pass phrase, and then store it in your authentication agent (&man.ssh-agent.1;). If you no longer wish to have your key stored in the agent, issuing ssh-add -d will remove it. Test by doing something such as ssh freefall.FreeBSD.org ls /usr. For more information, see /usr/ports/security/openssh, &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and &man.scp.1;. The FreeBSD Committers' Big List of Rules Respect other committers. Respect other contributors. Discuss any significant change before committing. Respect existing maintainers (if listed in the MAINTAINER field in Makefile or in the MAINTAINER file in the top-level directory). Never touch the repository directly. Ask a Repomeister. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion. Changes go to -CURRENT before -STABLE unless specifically permitted by the release engineer or unless they're not applicable to -CURRENT. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in -CURRENT for at least 3 days before merging so that it can be given sufficient testing. The release engineer has the same authority over the -STABLE branch as outlined for the maintainer in rule #5. Don't fight in public with other committers; it looks bad. If you must strongly disagree about something, do so only in private. Respect all code freezes and read the committers mailing list in a timely manner so you know when a code freeze is in effect. When in doubt on any procedure, ask first! Test your changes before committing them. Don't commit to anything under the src/contrib, src/crypto, and src/sys/contrib trees without explicit approval from the respective maintainer(s). As noted, breaking some of these rules can be grounds for suspension or, upon repeated offense, permanent removal of commit privileges. Three or more members of core acting in unison, have the power to temporarily suspend commit privileges until -core as a whole has the chance to review the issue. In case of an emergency (a committer doing damage to the repository), a temporary suspension may also be done by the repository meisters or any other member of core who may happen to be awake at the time. Only core as a whole has the authority to suspend commit privileges for any significant length of time or to remove them permanently, the latter generally only being done after consultation with committers. This rule does not exist to set core up as a bunch of cruel dictators who can dispose of committers as casually as empty soda cans, but to give the project a kind of safety fuse. If someone is seriously out of control, it's important to be able to deal with this immediately rather than be paralyzed by debate. In all cases, a committer whose privileges are suspended or revoked is entitled to a hearing, the total duration of the suspension being determined at that time. A committer whose privileges are suspended may also request a review of the decision after 30 days and every 30 days thereafter (unless the total suspension period is less than 30 days). A committer whose privileges have been revoked entirely may request a review after a period of 6 months have elapsed. This review policy is strictly informal and, in all cases, core reserves the right to either act on or disregard requests for review if they feel their original decision to be the right one. In all other aspects of project operation, core is a subset of committers and is bound by the same rules. Just because someone is in core doesn't mean that they have special dispensation to step outside of any of the lines painted here; core's special powers only kick in when it acts as a group, not on an individual basis. As individuals, we are all committers first and core second. Details Respect other committers. This means that you need to treat other committers as the peer-group developers that they are. Despite our occasional attempts to prove the contrary, one doesn't get into committers by being stupid and nothing rankles more than being treated that way by one of your peers. Whether we always feel respect for one another or not (and everyone has off days), we still have to treat other committers with respect at all times or the whole team structure rapidly breaks down. Being able to work together long term is this project's greatest asset, one far more important than any set of changes to the code, and turning arguments about code into issues that affect our long-term ability to work harmoniously together is just not worth the trade-off by any conceivable stretch of the imagination. To comply with this rule, don't send email when you're angry or otherwise behave in a manner which is likely to strike others as needlessly confrontational. First calm down, then think about how to communicate in the most effective fashion for convincing the other person(s) that your side of the argument is correct, don't just blow off some steam so you can feel better in the short term at the cost of a long-term flame war. Not only is this very bad energy economics, but repeated displays of public aggression which impair our ability to work well together will be dealt with severely by the project leadership and may result in suspension or termination of your commit privileges. That's never an option which the project's leadership enjoys in the slightest, but unity comes first. No amount of code or good advice is worth trading that away. Respect other contributors. You weren't always a committer. At one time you were a contributor. Remember that at all times. Remember what it was like trying to get help and attention. Don't forget that your work as a contributor time was very important to you. Remember what it was like. Don't discourage, belittle, or demean contributors. Treat them with respect. They are our committers in waiting. They are every bit as important to the project as committers. Their contributions are as valid and as important as your own. After all, you made many contributions before you became a committer. Always remember that. Consider the points raised under 'Respect other committers' and apply them also to contributors. Discuss any significant change before committing. The CVS repository is not where changes should be initially submitted for correctness or argued over, that should happen first in the mailing lists and then committed only once something resembling consensus has been reached. This doesn't mean that you have to ask permission before correcting every obvious syntax error or man page misspelling, simply that you should try to develop a feel for when a proposed change isn't quite such a no-brainer and requires some feedback first. People really don't mind sweeping changes if the result is something clearly better than what they had before, they just don't like being surprised by those changes. The very best way of making sure that you're on the right track is to have your code reviewed by one or more other committers. When in doubt, ask for review! Respect existing maintainers if listed. Many parts of FreeBSD aren't owned in the sense that any specific individual will jump up and yell if you commit a change to their area, but it still pays to check first. One convention we use is to put a maintainer line in the Makefile for any package or subtree which is being actively maintained by one or more people; see http://www.FreeBSD.org/handbook/policies.html for documentation on this. Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer. In cases where the maintainer-ship of something isn't clear, you can also look at the CVS logs for the file(s) in question and see if someone has been working recently or predominantly in that area. Other areas of FreeBSD fall under the control of someone who manages an overall category of FreeBSD evolution, such as internationalization or networking. See http://www.FreeBSD.org/handbook/staff-who.html for more information on this. Never touch the repository directly. Ask a Repomeister. This is pretty clear - you're not allowed to make direct modifications to the CVS repository, period. In case of difficulty, ask one of the repository meisters by sending mail to cvs@FreeBSD.org and simply wait for them to fix the problem and get back to you. Do not attempt to fix the problem yourself! If you're thinking about putting down a tag or doing a new import of code on a vendor branch, you might also find it useful to ask for advice first. A lot of people get this wrong the first few times and the consequences are expensive in terms of files touched and angry CVSup/CTM folks who are suddenly getting a lot of changes sent over unnecessarily. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer Security related changes may override a maintainer's wishes at the Security Officer's discretion. This may be hard to swallow in times of conflict (when each side is convinced that they're in the right, of course) but CVS makes it unnecessary to have an ongoing dispute raging when it's far easier to simply reverse the disputed change, get everyone calmed down again and then try and figure out how best to proceed. If the change turns out to be the best thing after all, it can be easily brought back. If it turns out not to be, then the users didn't have to live with the bogus change in the tree while everyone was busily debating its merits. People very very rarely call for back-outs in the repository since discussion generally exposes bad or controversial changes before the commit even happens, but on such rare occasions the back-out should be done without argument so that we can get immediately on to the topic of figuring out whether it was bogus or not. Changes go to -CURRENT before -STABLE unless specifically permitted by the release engineer or unless they're not applicable to -CURRENT. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in -CURRENT for at least 3 days before merging so that it can be given sufficient testing. The release engineer has the same authority over the -STABLE branch as outlined in rule #5. This is another don't argue about it issue since it's the release engineer who is ultimately responsible (and gets beaten up) if a change turns out to be bad. Please respect this and give the release engineer your full cooperation when it comes to the -STABLE branch. The management of -STABLE may frequently seem to be overly conservative to the casual observer, but also bear in mind the fact that conservatism is supposed to be the hallmark of -STABLE and different rules apply there than in -CURRENT. There's also really no point in having -CURRENT be a testing ground if changes are merged over to -STABLE immediately. Changes need a chance to be tested by the -CURRENT developers, so allow some time to elapse before merging unless the -STABLE fix is critical, time sensitive or so obvious as to make further testing unnecessary (spelling fixes to manpages, obvious bug/typo fixes, etc.) In other words, apply common sense. Don't fight in public with other committers; it looks bad. If you must strongly disagree about something, do so only in private. This project has a public image to uphold and that image is very important to all of us, especially if we are to continue to attract new members. There will be occasions when, despite everyone's very best attempts at self-control, tempers are lost and angry words are exchanged, and the best we can do is try and minimize the effects of this until everyone has cooled back down. That means that you should not air your angry words in public and you should not forward private correspondence to public mailing lists or aliases. What people say one-to-one is often much less sugar-coated than what they would say in public, and such communications therefore have no place there - they only serve to inflame an already bad situation. If the person sending you a flame-o-gram at least had the grace to send it privately, then have the grace to keep it private yourself. If you feel you are being unfairly treated by another developer, and it is causing you anguish, bring the matter up with core rather than taking it public. We will do our best to play peace makers and get things back to sanity. In cases where the dispute involves a change to the codebase and the participants do not appear to be reaching an amicable agreement, core may appoint a mutually-agreeable 3rd party to resolve the dispute. All parties involved must then agree to be bound by the decision reached by this 3rd party. Respect all code freezes and read the committers mailing list on a timely basis so you know when they are. Committing changes during a code freeze is a really big mistake and committers are expected to keep up-to-date on what's going on before jumping in after a long absence and committing 10 megabytes worth of accumulated stuff. People who abuse this on a regular basis will have their commit privileges suspended until they get back from the FreeBSD Happy Reeducation Camp we run in Greenland. When in doubt on any procedure, ask first! Many mistakes are made because someone is in a hurry and just assumes they know the right way of doing something. If you have not done it before, chances are good that you do not actually know the way we do things and really need to ask first or you are going to completely embarrass yourself in public. There's no shame in asking how in the heck do I do this? We already know you are an intelligent person; otherwise, you would not be a committer. Test your changes before committing them. This may sound obvious, but if it really were so obvious then we probably wouldn't see so many cases of people clearly not doing this. If your changes are to the kernel, make sure you can still compile both GENERIC and LINT. If your changes are anywhere else, make sure you can still make world. If your changes are to a branch, make sure your testing occurs with a machine which is running that code. If you have a change which also may break another architecture, be sure and test on all supported architectures. Currently, this is only the x86 and the Alpha so it's pretty easy to do. If you need to test on the AXP, your account on beast.FreeBSD.org will let you compile and test Alpha binaries/kernels/etc. As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available. Don't commit to anything under the src/contrib, src/crypto, and src/sys/contrib trees without explicit approval from the respective maintainer(s). The trees mentioned above are for contributed software usually imported onto a vendor branch. Committing something there, even if it doesn't take the file off the vendor branch, may cause unnecessary headaches for those responsible for maintaining that particular piece of software. Thus, unless you have explicit approval from the maintainer (or you are the maintainer), do not commit there! Please note that this doesn't mean you shouldn't try to improve the software in question; you are still more than welcome to do so. Ideally, you should submit your patches to the vendor. If your changes are FreeBSD-specific, talk to the maintainer; they may be willing to apply them locally. But whatever you do, do not commit there by yourself! Contact the &a.core; if you wish to take up maintainership of an unmaintained part of the tree. Other Suggestions When committing documentation changes, use a spell checker before committing. :) For all SGML docs, you should also verify that your formatting directives are correct by running make lint. For all on-line manual pages, run manck (from ports) over the man page to verify all of the cross references and file references are correct and that the man page has all of the appropriate MLINKs installed. Do not mix style fixes with new functionality. A style fix is any change which does not modify the functionality of the code. Mixing the changes obfuscates the functionality change when using cvs diff, which can hide any new bugs. Do not include whitespace changes with content changes in commits to doc/ or www/. The extra clutter in the diffs makes the translators' job much more difficult. Instead, make any style or whitespace changes in separate commits that are clearly labeled as such in the commit message. Ports Specific FAQ Adding a New Port How do I add a new port? First, please read the section about repository copy. The easiest way to add a new port is to use the addport script on freefall. It will add a port from the directory you specify, determining the category automatically from the port Makefile. It will also add an entry to the CVSROOT/modules file and the port's category Makefile. It was written by &a.mharo; and &a.will;, but Will is the current maintainer so please send questions/patches about addport to him. Any other things I need to know when I add a new port? Check the port, preferably to make sure it compiles and packages correctly. This is the recommended sequence: &prompt.root; make install &prompt.root; make package &prompt.root; make deinstall &prompt.root; pkg_add package you built above &prompt.root; make deinstall &prompt.root; make reinstall &prompt.root; make package The Porters Handbook contains more detailed instructions. Use &man.portlint.1; to check the syntax of the port. You don't necessarily have to eliminate all warnings but make sure you have fixed the simple ones. If the port came from a submitter who has not contributed to the project before, add that person's name to the Handbook's Additional Contributors section. Close the PR if the port came in as a PR. To close a PR, just do edit-pr PR# on freefall and change the state from open to closed. You will be asked to enter a log message and then you are done. Repository Copies When do we need a repository copy? When you want to add a port that is related to any port that is already in the tree in a separate directory, please send mail to the ports manager asking about it. Here related means it is a different version or a slightly modified version. Examples are print/ghostscript* (different versions) and x11-wm/windowmaker* (English-only and internationalized version). Another example is when a port is moved from one subdirectory to another, or when you want to change the name of a directory because the author(s) renamed their software even though it is a descendant of a port already in a tree. When do we not need a repository copy? When there is no history to preserve. If a port is added into a wrong category and is moved immediately, it suffices to simply cvs remove the old one and addport the new one. What do I need to do? Send mail to the ports manager, who will do a copy from the old location/name to the new location/name. You will then get a notice, at which point you are expected to perform the following: cvs remove the old port (if necessary) Adjust the parent (category) Makefile Update CVSROOT/modules If other ports depend on the updated port, change their Makefiles' dependency lines If the port changed categories, modify the CATEGORIES line of the port's Makefile accordingly Ports Freeze What is a ports freeze? Before a release, it is necessary to restrict commits to the ports tree for a short period of time while the packages and the release itself are being built. This is to ensure consistency among the various parts of the release, and is called the ports freeze. How long is a ports freeze? Usually an hour or two. What does it mean to me? During the ports freeze, you are not allowed to commit anything to the tree without explicit approval from the ports manager. Explicit approval here means either of the following: You asked the ports manager and got a reply saying, Go ahead and commit it. The ports manager sent a mail to you or the mailing lists during the ports freeze pointing out that the port is broken and has to be fixed. Note that you do not have implicit permission to fix a port during the freeze just because it is broken. How do I know when the ports freeze starts? The ports manager will send out warning messages to the freebsd-ports@FreeBSD.org and cvs-committers@FreeBSD.org mailing lists announcing the start of the impending release, usually two or three weeks in advance. The exact starting time will not be determined until a few days before the actual release. This is because the ports freeze has to be synchronized with the release, and it is usually not known until then when exactly the release will be rolled. When the freeze starts, there will be another announcement to the cvs-committers@FreeBSD.org list, of course. How do I know when the ports freeze ends? A few hours after the release, the ports manager will send out a mail to the freebsd-ports@FreeBSD.org and cvs-committers@FreeBSD.org mailing lists announcing the end of the ports freeze. Note that the release being cut does not automatically end the freeze. We have to make sure there will not be any last minute snafus that result in an immediate re-rolling of the release. Miscellaneous Questions How do I know if my port is building correctly or not? First, go check http://bento.FreeBSD.org/~asami/errorlogs/. There you will find error logs from the latest package building runs on 3-stable, 4-stable and 5-current. However, just because the port doesn't show up there doesn't mean it's building correctly. (One of the dependencies may have failed, for instance.) Here are the relevant directories on bento, so feel free to dig around. /a/asami/portbuild/3/errors error logs from latest 3-stable run /logs all logs from latest 3-stable run /packages packages from latest 3-stable run /bak/errors error logs from last complete 3-stable run /bak/logs all logs from last complete 3-stable run /bak/packages packages from last complete 3-stable run /4/errors error logs from latest 4-stable run /logs all logs from latest 4-stable run /packages packages from latest 4-stable run /bak/errors error logs from last complete 4-stable run /bak/logs all logs from last complete 4-stable run /bak/packages packages from last complete 4-stable run /5/errors error logs from latest 5-current run /logs all logs from latest 5-current run /packages packages from latest 5-current run /bak/errors error logs from last complete 5-current run /bak/logs all logs from last complete 5-current run /bak/packages packages from last complete 5-current run Basically, if the port shows up in packages, or it is in logs but not in errors, it built fine. (The errors directories are what you get from the web page.) I added a new port. Do I need to add it to the INDEX? No. The ports manager will regenerate the INDEX and commit it every few days. Are there any other files I'm not allowed to touch? Any file directly under ports/, or any file under a subdirectory that starts with an uppercase letter (Mk/, Tools/, etc.). In particular, the ports manager is very protective of ports/Mk/bsd.port*.mk so don't commit changes to those files unless you want to face his wra(i)th. Miscellaneous Questions Why are trivial or cosmetic changes to files on a vendor branch a bad idea? From now on, every new vendor release of that file will need to have patches merged in by hand. From now on, every new vendor release of that file will need to have patches verified by hand. The option doesn't work very well. Ask &a.obrien; for horror stories. How do I add a new file to a CVS branch? To add a file onto a branch, simply checkout or update to the branch you want to add to and then add the file using cvs add as you normally would. For example, if you wanted to MFC the file src/sys/alpha/include/smp.h from HEAD to RELENG_4 and it does not exist in RELENG_4 yet, you would use the following steps: MFC'ing a New File &prompt.user; cd sys/alpha/include &prompt.user; cvs update -rRELENG_4 cvs update: Updating . U clockvar.h U console.h ... &prompt.user; cvs update -kk -Ap smp.h > smp.h =================================================================== Checking out smp.h RCS: /usr/cvs/src/sys/alpha/include/smp.h,v VERS: 1.1 *************** &prompt.user; cvs add smp.h cvs add: scheduling file `smp.h' for addition on branch `RELENG_4' cvs add: use 'cvs commit' to add this file permanently &prompt.user; cvs commit What meta information should I include in a commit message? As well as including an informative message with each commit you may need to include some additional information as well. This information consists of one or more lines containing the the key word or phrase, a colon, tabs for formatting, and then the additional information. The key words or phrases are: PR: The problem report (if any) which is affected (typically, by being closed) by this commit. Submitted by: The name and e-mail address of the person that submitted the fix. Reviewed by: The name and e-mail address of the person or people that reviewed the change. If a patch was submitted to a mailing list for review, and the review was favourable, then just include the list name. Approved by: The name and e-mail address of the person or people that approved the change. It is customary to get prior approval for a commit if it is to an area of the tree to which you do not usually commit. In addition, during the run up to a new release all commits must be approved by the release engineer. If these are your first commits then you should have passed them past your mentor first for approval, and you should list your mentor. Obtained from: The name of the project (if any) from which the code was obtained. Commit log for a commit based on a PR You want to commit a change based on a PR submitted by John Smith containing a patch. The end of the commit message should look something like this. ... PR: foo/12345 Submitted by: John Smith <John.Smith@example.com> Commit log for a commit needing review You want to change the virtual memory system. You have posted patches to the appropriate mailing list (in this case, freebsd-arch) and the changes have been approved. ... Reviewed by: -arch Commit log for a commit needing approval You want to commit a change to a section of the tree with a MAINTAINER assigned. You have collaborated with the listed MAINTAINER, who has told you to go ahead and commit. ... Approved by: abc Where abc is the account name of the person who approved. Commit log for a commit bringing in code from OpenBSD You want to commit some code based on work done in the OpenBSD project. ... Obtained from: OpenBSD In some cases you may need to combine some of these. Consider the situation where a user has submitted a PR containing code from the NetBSD project. You are looking at the PR, but it's not an area of the tree you normally work in, so you've decided to get the change reviewed by the arch mailing list. The extra information to include in the commit would look something like PR: foo/54321 Submitted by: John Smith <John.Smith@example.com> Reviewed by: -arch Obtained from: NetBSD
diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml index 8f037fafe4..c6836a8c5c 100644 --- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml @@ -1,2906 +1,2906 @@ Security Much of this chapter has been taken from the &man.security.7; man page, originally written by &a.dillon;. Synopsis The following chapter will provide a basic introduction to system security concepts, some general good rules of thumb, and some advanced topics such as S/Key, OpenSSL, Kerberos, and others. Introduction Security is a function that begins and ends with the system administrator. While all BSD UNIX multi-user systems have some inherent security, the job of building and maintaining additional security mechanisms to keep those users honest is probably one of the single largest undertakings of the sysadmin. Machines are only as secure as you make them, and security concerns are ever competing with the human necessity for convenience. UNIX systems, in general, are capable of running a huge number of simultaneous processes and many of these processes operate as servers – meaning that external entities can connect and talk to them. As yesterday's mini-computers and mainframes become today's desktops, and as computers become networked and internetworked, security becomes an ever bigger issue. Security is best implemented through a layered onion approach. In a nutshell, what you want to do is to create as many layers of security as are convenient and then carefully monitor the system for intrusions. You do not want to overbuild your security or you will interfere with the detection side, and detection is one of the single most important aspects of any security mechanism. For example, it makes little sense to set the schg flags (see &man.chflags.1;) on every system binary because while this may temporarily protect the binaries, it prevents an attacker who has broken in from making an easily detectable change that may result in your security mechanisms not detecting the attacker at all. System security also pertains to dealing with various forms of attack, including attacks that attempt to crash or otherwise make a system unusable but do not attempt to break root. Security concerns can be split up into several categories: Denial of service attacks. User account compromises. Root compromise through accessible servers. Root compromise via user accounts. Backdoor creation. A denial of service attack is an action that deprives the machine of needed resources. Typically, D.O.S. attacks are brute-force mechanisms that attempt to crash or otherwise make a machine unusable by overwhelming its servers or network stack. Some D.O.S. attacks try to take advantages of bugs in the networking stack to crash a machine with a single packet. The latter can only be fixed by applying a bug fix to the kernel. Attacks on servers can often be fixed by properly specifying options to limit the load the servers incur on the system under adverse conditions. Brute-force network attacks are harder to deal with. A spoofed-packet attack, for example, is nearly impossible to stop short of cutting your system off from the internet. It may not be able to take your machine down, but it can fill up internet pipe. A user account compromise is even more common then a D.O.S. attack. Many sysadmins still run standard telnetd, rlogind, rshd, and ftpd servers on their machines. These servers, by default, do not operate over encrypted connections. The result is that if you have any moderate-sized user base, one or more of your users logging into your system from a remote location (which is the most common and convenient way to login to a system) will have his or her password sniffed. The attentive system admin will analyze his remote access logs looking for suspicious source addresses even for successful logins. One must always assume that once an attacker has access to a user account, the attacker can break root. However, the reality is that in a well secured and maintained system, access to a user account does not necessarily give the attacker access to root. The distinction is important because without access to root the attacker cannot generally hide his tracks and may, at best, be able to do nothing more then mess with the user's files or crash the machine. User account compromises are very common because users tend not to take the precautions that sysadmins take. System administrators must keep in mind that there are potentially many ways to break root on a machine. The attacker may know the root password, the attacker may find a bug in a root-run server and be able to break root over a network connection to that server, or the attacker may know of a bug in an suid-root program that allows the attacker to break root once he has broken into a user's account. If an attacker has found a a way to break root on a machine, the attacker may not have a need to install a backdoor. Many of the root holes found and closed to date involve a considerable amount of work by the attacker to cleanup after himself, so most attackers install backdoors. Backdoors provide the attacker with a way to easily regain root access to the system, but it also gives the smart system administrator a convenient way to detect the intrusion. Making it impossible for an attacker to install a backdoor may actually be detrimental to your security because it will not close off the hole the attacker found to break in the first place. Security remedies should always be implemented with a multi-layered onion peel approach and can be categorized as follows: Securing root and staff accounts. Securing root – root-run servers and suid/sgid binaries. Securing user accounts. Securing the password file. Securing the kernel core, raw devices, and filesystems. Quick detection of inappropriate changes made to the system. Paranoia. The next section of this chapter will cover the above bullet items in greater depth. Securing FreeBSD The sections that follow will cover the methods of securing your FreeBSD system that were mentioned in the last section of this chapter. Securing the root account and staff accounts First off, do not bother securing staff accounts if you have not secured the root account. Most systems have a password assigned to the root account. The first thing you do is assume that the password is always compromised. This does not mean that you should remove the password. The password is almost always necessary for console access to the machine. What it does mean is that you should not make it possible to use the password outside of the console or possibly even with the &man.su.1; command. For example, make sure that your pty's are specified as being unsecure in the /etc/ttys file so that direct root logins via telnet or rlogin are disallowed. If using other login services such as sshd, make sure that direct root logins are disabled there as well. Consider every access method – services such as FTP often fall through the cracks. Direct root logins should only be allowed via the system console. Of course, as a sysadmin you have to be able to get to root, so we open up a few holes. But we make sure these holes require additional password verification to operate. One way to make root accessible is to add appropriate staff accounts to the wheel group (in /etc/group). The staff members placed in the wheel group are allowed to su to root. You should never give staff members native wheel access by putting them in the wheel group in their password entry. Staff accounts should be placed in a staff group, and then added to the wheel group via the /etc/group file. Only those staff members who actually need to have root access should be placed in the wheel group. It is also possible, when using an authentication method such as kerberos, to use kerberos' .k5login file in the root account to allow a &man.ksu.1; to root without having to place anyone at all in the wheel group. This may be the better solution since the wheel mechanism still allows an intruder to break root if the intruder has gotten hold of your password file and can break into a staff account. While having the wheel mechanism is better then having nothing at all, it is not necessarily the safest option. An indirect way to secure the root account is to secure your staff accounts by using an alternative login access method and *'ing out the crypted password for the staff accounts. This way an intruder may be able to steal the password file but will not be able to break into any staff accounts (or, indirectly, root, even if root has a crypted password associated with it). Staff members get into their staff accounts through a secure login mechanism such as &man.kerberos.1; or &man.ssh.1; using a private/public key pair. When you use something like kerberos, you generally must secure the machines which run the kerberos servers and your desktop workstation. When you use a public/private key pair with ssh, you must generally secure the machine you are logging in from (typically your workstation), but you can also add an additional layer of protection to the key pair by password protecting the keypair when you create it with &man.ssh-keygen.1;. Being able to * out the passwords for staff accounts also guarantees that staff members can only login through secure access methods that you have setup. You can thus force all staff members to use secure, encrypted connections for all of their sessions which closes an important hole used by many intruders: That of sniffing the network from an unrelated, less secure machine. The more indirect security mechanisms also assume that you are logging in from a more restrictive server to a less restrictive server. For example, if your main box is running all sorts of servers, your workstation should not be running any. In order for your workstation to be reasonably secure you should run as few servers as possible, up to and including no servers at all, and you should run a password-protected screen blanker. Of course, given physical access to a workstation an attacker can break any sort of security you put on it. This is definitely a problem that you should consider but you should also consider the fact that the vast majority of break-ins occur remotely, over a network, from people who do not have physical access to your workstation or servers. Using something like kerberos also gives you the ability to disable or change the password for a staff account in one place and have it immediately effect all the machine the staff member may have an account on. If a staff member's account gets compromised, the ability to instantly change his password on all machines should not be underrated. With discrete passwords, changing a password on N machines can be a mess. You can also impose re-passwording restrictions with kerberos: not only can a kerberos ticket be made to timeout after a while, but the kerberos system can require that the user choose a new password after a certain period of time (say, once a month). Securing Root-run Servers and SUID/SGID Binaries The prudent sysadmin only runs the servers he needs to, no more, no less. Be aware that third party servers are often the most bug-prone. For example, running an old version of imapd or popper is like giving a universal root ticket out to the entire world. Never run a server that you have not checked out carefully. Many servers do not need to be run as root. For example, the ntalk, comsat, and finger daemons can be run in special user sandboxes. A sandbox isn't perfect unless you go to a large amount of trouble, but the onion approach to security still stands: If someone is able to break in through a server running in a sandbox, they still have to break out of the sandbox. The more layers the attacker must break through, the lower the likelihood of his success. Root holes have historically been found in virtually every server ever run as root, including basic system servers. If you are running a machine through which people only login via sshd and never login via telnetd or rshd or rlogind, then turn off those services! FreeBSD now defaults to running ntalkd, comsat, and finger in a sandbox. Another program which may be a candidate for running in a sandbox is &man.named.8;. /etc/defaults/rc.conf includes the arguments necessary to run named in a sandbox in a commented-out form. Depending on whether you are installing a new system or upgrading an existing system, the special user accounts used by these sandboxes may not be installed. The prudent sysadmin would research and implement sandboxes for servers whenever possible. There are a number of other servers that typically do not run in sandboxes: sendmail, popper, imapd, ftpd, and others. There are alternatives to some of these, but installing them may require more work then you are willing to perform (the convenience factor strikes again). You may have to run these servers as root and rely on other mechanisms to detect break-ins that might occur through them. The other big potential root hole in a system are the suid-root and sgid binaries installed on the system. Most of these binaries, such as rlogin, reside in /bin, /sbin, /usr/bin, or /usr/sbin. While nothing is 100% safe, the system-default suid and sgid binaries can be considered reasonably safe. Still, root holes are occasionally found in these binaries. A root hole was found in Xlib in 1998 that made xterm (which is typically suid) vulnerable. It is better to be safe then sorry and the prudent sysadmin will restrict suid binaries that only staff should run to a special group that only staff can access, and get rid of (chmod 000) any suid binaries that nobody uses. A server with no display generally does not need an xterm binary. Sgid binaries can be almost as dangerous. If an intruder can break an sgid-kmem binary the intruder might be able to read /dev/kmem and thus read the crypted password file, potentially compromising any passworded account. Alternatively an intruder who breaks group kmem can monitor keystrokes sent through pty's, including pty's used by users who login through secure methods. An intruder that breaks the tty group can write to almost any user's tty. If a user is running a terminal program or emulator with a keyboard-simulation feature, the intruder can potentially generate a data stream that causes the user's terminal to echo a command, which is then run as that user. Securing User Accounts User accounts are usually the most difficult to secure. While you can impose Draconian access restrictions on your staff and * out their passwords, you may not be able to do so with any general user accounts you might have. If you do have sufficient control then you may win out and be able to secure the user accounts properly. If not, you simply have to be more vigilant in your monitoring of those accounts. Use of ssh and kerberos for user accounts is more problematic due to the extra administration and technical support required, but still a very good solution compared to a crypted password file. Securing the Password File The only sure fire way is to * out as many passwords as you can and use ssh or kerberos for access to those accounts. Even though the crypted password file (/etc/spwd.db) can only be read by root, it may be possible for an intruder to obtain read access to that file even if the attacker cannot obtain root-write access. Your security scripts should always check for and report changes to the password file (see Checking file integrity below). Securing the Kernel Core, Raw Devices, and Filesystems If an attacker breaks root he can do just about anything, but there are certain conveniences. For example, most modern kernels have a packet sniffing device driver built in. Under FreeBSD it is called the bpf device. An intruder will commonly attempt to run a packet sniffer on a compromised machine. You do not need to give the intruder the capability and most systems should not have the bpf device compiled in. But even if you turn off the bpf device, you still have /dev/mem and /dev/kmem to worry about. For that matter, the intruder can still write to raw disk devices. Also, there is another kernel feature called the module loader, &man.kldload.8;. An enterprising intruder can use a KLD module to install his own bpf device or other sniffing device on a running kernel. To avoid these problems you have to run the kernel at a higher secure level, at least securelevel 1. The securelevel can be set with a sysctl on the kern.securelevel variable. Once you have set the securelevel to 1, write access to raw devices will be denied and special chflags flags, such as schg, will be enforced. You must also ensure that the schg flag is set on critical startup binaries, directories, and script files – everything that gets run up to the point where the securelevel is set. This might be overdoing it, and upgrading the system is much more difficult when you operate at a higher secure level. You may compromise and run the system at a higher secure level but not set the schg flag for every system file and directory under the sun. Another possibility is to simply mount / and /usr read-only. It should be noted that being too draconian in what you attempt to protect may prevent the all-important detection of an intrusion. Checking File Integrity: Binaries, Configuration Files, Etc. When it comes right down to it, you can only protect your core system configuration and control files so much before the convenience factor rears its ugly head. For example, using chflags to set the schg bit on most of the files in / and /usr is probably counterproductive because while it may protect the files, it also closes a detection window. The last layer of your security onion is perhaps the most important – detection. The rest of your security is pretty much useless (or, worse, presents you with a false sense of safety) if you cannot detect potential incursions. Half the job of the onion is to slow down the attacker rather then stop him in order to give the detection side of the equation a chance to catch him in the act. The best way to detect an incursion is to look for modified, missing, or unexpected files. The best way to look for modified files is from another (often centralized) limited-access system. Writing your security scripts on the extra-secure limited-access system makes them mostly invisible to potential attackers, and this is important. In order to take maximum advantage you generally have to give the limited-access box significant access to the other machines in the business, usually either by doing a read-only NFS export of the other machines to the limited-access box, or by setting up ssh keypairs to allow the limit-access box to ssh to the other machines. Except for its network traffic, NFS is the least visible method – allowing you to monitor the filesystems on each client box virtually undetected. If your limited-access server is connected to the client boxes through a switch, the NFS method is often the better choice. If your limited-access server is connected to the client boxes through a hub or through several layers of routing, the NFS method may be too insecure (network-wise) and using ssh may be the better choice even with the audit-trail tracks that ssh lays. Once you give a limit-access box at least read access to the client systems it is supposed to monitor, you must write scripts to do the actual monitoring. Given an NFS mount, you can write scripts out of simple system utilities such as &man.find.1; and &man.md5.1;. It is best to physically md5 the client-box files boxes at least once a day, and to test control files such as those found in /etc and /usr/local/etc even more often. When mismatches are found relative to the base md5 information the limited-access machine knows is valid, it should scream at a sysadmin to go check it out. A good security script will also check for inappropriate suid binaries and for new or deleted files on system partitions such as / and /usr. When using ssh rather then NFS, writing the security script is much more difficult. You essentially have to scp the scripts to the client box in order to run them, making them visible, and for safety you also need to scp the binaries (such as find) that those scripts use. The ssh daemon on the client box may already be compromised. All in all, using ssh may be necessary when running over unsecure links, but it's also a lot harder to deal with. A good security script will also check for changes to user and staff members access configuration files: .rhosts, .shosts, .ssh/authorized_keys and so forth… files that might fall outside the purview of the MD5 check. If you have a huge amount of user disk space it may take too long to run through every file on those partitions. In this case, setting mount flags to disallow suid binaries and devices on those partitions is a good idea. The nodev and nosuid options (see &man.mount.8;) are what you want to look into. You should probably scan them anyway at least once a week, since the object of this layer is to detect a break-in whether or not the break-in is effective. Process accounting (see &man.accton.8;) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in occurs. Finally, security scripts should process the log files and the logs themselves should be generated in as secure a manner as possible – remote syslog can be very useful. An intruder tries to cover his tracks, and log files are critical to the sysadmin trying to track down the time and method of the initial break-in. One way to keep a permanent record of the log files is to run the system console to a serial port and collect the information on a continuing basis through a secure machine monitoring the consoles. Paranoia A little paranoia never hurts. As a rule, a sysadmin can add any number of security features as long as they do not effect convenience, and can add security features that do effect convenience with some added thought. Even more importantly, a security administrator should mix it up a bit – if you use recommendations such as those given by this document verbatim, you give away your methodologies to the prospective attacker who also has access to this document. Denial of Service Attacks This section covers Denial of Service attacks. A DOS attack is typically a packet attack. While there is not much you can do about modern spoofed packet attacks that saturate your network, you can generally limit the damage by ensuring that the attacks cannot take down your servers. Limiting server forks. Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.). Kernel Route Cache. A common DOS attack is against a forking server that attempts to cause the server to eat processes, file descriptors, and memory until the machine dies. Inetd (see &man.inetd.8;) has several options to limit this sort of attack. It should be noted that while it is possible to prevent a machine from going down it is not generally possible to prevent a service from being disrupted by the attack. Read the inetd manual page carefully and pay specific attention to the , , and options. Note that spoofed-IP attacks will circumvent the option to inetd, so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters. Sendmail has its option which tends to work much better than trying to use sendmail's load limiting options due to the load lag. You should specify a MaxDaemonChildren parameter when you start sendmail high enough to handle your expected load but no so high that the computer cannot handle that number of sendmails without falling on its face. It is also prudent to run sendmail in queued mode () and to run the daemon (sendmail -bd) separate from the queue-runs (sendmail -q15m). If you still want real-time delivery you can run the queue at a much lower interval, such as , but be sure to specify a reasonable MaxDaemonChildren option for that sendmail to prevent cascade failures. Syslogd can be attacked directly and it is strongly recommended that you use the option whenever possible, and the option otherwise. You should also be fairly careful with connect-back services such as tcpwrapper's reverse-identd, which can be attacked directly. You generally do not want to use the reverse-ident feature of tcpwrappers for this reason. It is a very good idea to protect internal services from external access by firewalling them off at your border routers. The idea here is to prevent saturation attacks from outside your LAN, not so much to protect internal services from network-based root compromise. Always configure an exclusive firewall, i.e., firewall everything except ports A, B, C, D, and M-Z. This way you can firewall off all of your low ports except for certain specific services such as named (if you are primary for a zone), ntalkd, sendmail, and other internet-accessible services. If you try to configure the firewall the other way – as an inclusive or permissive firewall, there is a good chance that you will forget to close a couple of services or that you will add a new internal service and forget to update the firewall. You can still open up the high-numbered port range on the firewall to allow permissive-like operation without compromising your low ports. Also take note that FreeBSD allows you to control the range of port numbers used for dynamic binding via the various net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange), which can also ease the complexity of your firewall's configuration. For example, you might use a normal first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then block everything under 4000 off in your firewall (except for certain specific internet-accessible ports, of course). Another common DOS attack is called a springboard attack – to attack a server in a manner that causes the server to generate responses which then overload the server, the local network, or some other machine. The most common attack of this nature is the ICMP ping broadcast attack. The attacker spoofs ping packets sent to your LAN's broadcast address with the source IP address set to the actual machine they wish to attack. If your border routers are not configured to stomp on ping's to broadcast addresses, your LAN winds up generating sufficient responses to the spoofed source address to saturate the victim, especially when the attacker uses the same trick on several dozen broadcast addresses over several dozen different networks at once. Broadcast attacks of over a hundred and twenty megabits have been measured. A second common springboard attack is against the ICMP error reporting system. By constructing packets that generate ICMP error responses, an attacker can saturate a server's incoming network and cause the server to saturate its outgoing network with ICMP responses. This type of attack can also crash the server by running it out of mbuf's, especially if the server cannot drain the ICMP responses it generates fast enough. The FreeBSD kernel has a new kernel compile option called ICMP_BANDLIM which limits the effectiveness of these sorts of attacks. The last major class of springboard attacks is related to certain internal inetd services such as the udp echo service. An attacker simply spoofs a UDP packet with the source address being server A's echo port, and the destination address being server B's echo port, where server A and B are both on your LAN. The two servers then bounce this one packet back and forth between each other. The attacker can overload both servers and their LANs simply by injecting a few packets in this manner. Similar problems exist with the internal chargen port. A competent sysadmin will turn off all of these inetd-internal test services. Spoofed packet attacks may also be used to overload the kernel route cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache sysctl parameters. A spoofed packet attack that uses a random source IP will cause the kernel to generate a temporary cached route in the route table, viewable with netstat -rna | fgrep W3. These routes typically timeout in 1600 seconds or so. If the kernel detects that the cached route table has gotten too big it will dynamically reduce the rtexpire but will never decrease it to less then rtminexpire. There are two problems: The kernel does not react quickly enough when a lightly loaded server is suddenly attacked. The rtminexpire is not low enough for the kernel to survive a sustained attack. If your servers are connected to the internet via a T3 or better it may be prudent to manually override both rtexpire and rtminexpire via &man.sysctl.8;. Never set either parameter to zero (unless you want to crash the machine :-). Setting both parameters to 2 seconds should be sufficient to protect the route table from attack. Access Issues with Kerberos and SSH There are a few issues with both kerberos and ssh that need to be addressed if you intend to use them. Kerberos V is an excellent authentication protocol but there are bugs in the kerberized telnet and rlogin applications that make them unsuitable for dealing with binary streams. Also, by default kerberos does not encrypt a session unless you use the option. ssh encrypts everything by default. ssh works quite well in every respect except that it forwards encryption keys by default. What this means is that if you have a secure workstation holding keys that give you access to the rest of the system, and you ssh to an unsecure machine, your keys becomes exposed. The actual keys themselves are not exposed, but ssh installs a forwarding port for the duration of your login and if a attacker has broken root on the unsecure machine he can utilize that port to use your keys to gain access to any other machine that your keys unlock. We recommend that you use ssh in combination with kerberos whenever possible for staff logins. ssh can be compiled with kerberos support. This reduces your reliance on potentially exposable ssh keys while at the same time protecting passwords via kerberos. ssh keys should only be used for automated tasks from secure machines (something that kerberos is unsuited to). We also recommend that you either turn off key-forwarding in the ssh configuration, or that you make use of the from=IP/DOMAIN option that ssh allows in its authorized_keys file to make the key only usable to entities logging in from specific machines. DES, MD5, and Crypt Parts rewritten and updated by &a.unfurl;, 21 March 2000. Every user on a UNIX system has a password associated with their account. It seems obvious that these passwords need to be known only to the user and the actual operating system. In order to keep these passwords secret, they are encrypted with what is known as a one-way hash, that is, they can only be easily encrypted but not decrypted. In other words, what we told you a moment ago was obvious is not even true: the operating system itself does not really know the password. It only knows the encrypted form of the password. The only way to get the plain-text password is by a brute force search of the space of possible passwords. Unfortunately the only secure way to encrypt passwords when UNIX came into being was based on DES, the Data Encryption Standard. This is not such a problem for users that live in the US, but since the source code for DES could not be exported outside the US, FreeBSD had to find a way to both comply with US law and retain compatibility with all the other UNIX variants that still use DES. The solution was to divide up the encryption libraries so that US users could install the DES libraries and use DES but international users still had an encryption method that could be exported abroad. This is how FreeBSD came to use MD5 as its default encryption method. MD5 is believed to be more secure than DES, so installing DES is offered primarily for compatibility reasons. Recognizing your crypt mechanism It is pretty easy to identify which encryption method FreeBSD is set up to use. Examining the encrypted passwords in the /etc/master.passwd file is one way. Passwords encrypted with the MD5 hash are longer than those with encrypted with the DES hash and also begin with the characters $1$. DES password strings do not have any particular identifying characteristics, but they are shorter than MD5 passwords, and are coded in a 64-character alphabet which does not include the $ character, so a relatively short string which does not begin with a dollar sign is very likely a DES password. The libraries can identify the passwords this way as well. As a result, the DES libraries are able to identify MD5 passwords, and use MD5 to check passwords that were encrypted that way, and DES for the rest. They are able to do this because the DES libraries also contain MD5. Unfortunately, the reverse is not true, so the MD5 libraries cannot authenticate passwords that were encrypted with DES. Identifying which library is being used by the programs on your system is easy as well. Any program that uses crypt is linked against libcrypt which for each type of library is a symbolic link to the appropriate implementation. For example, on a system using the DES versions: &prompt.user; ls -l /usr/lib/libcrypt* lrwxr-xr-x 1 root wheel 13 Mar 19 06:56 libcrypt.a -> libdescrypt.a lrwxr-xr-x 1 root wheel 18 Mar 19 06:56 libcrypt.so.2.0 -> libdescrypt.so.2.0 lrwxr-xr-x 1 root wheel 15 Mar 19 06:56 libcrypt_p.a -> libdescrypt_p.a On a system using the MD5-based libraries, the same links will be present, but the target will be libscrypt rather than libdescrypt. If you have installed the DES-capable crypt library libdescrypt (e.g. by installing the "crypto" distribution), then which password format will be used for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of either des or md5. See the - login.conf(5) manpage for more information about login + &man.login.conf.5; manpage for more information about login capabilities. S/Key S/Key is a one-time password scheme based on a one-way hash function. FreeBSD uses the MD4 hash for compatibility but other systems have used MD5 and DES-MAC. S/Key has been part of the FreeBSD base system since version 1.1.5 and is also used on a growing number of other operating systems. S/Key is a registered trademark of Bell Communications Research, Inc. There are three different sorts of passwords which we will talk about in the discussion below. The first is your usual UNIX-style or Kerberos password; we will call this a UNIX password. The second sort is the one-time password which is generated by the S/Key key program and accepted by the keyinit program and the login prompt; we will call this a one-time password. The final sort of password is the secret password which you give to the key program (and sometimes the keyinit program) which it uses to generate one-time passwords; we will call it a secret password or just unqualified password. The secret password does not have anything to do with your UNIX password; they can be the same but this is not recommended. S/Key secret passwords are not limited to 8 characters like UNIX passwords, they can be as long as you like. Passwords of six or seven word long phrases are fairly common. For the most part, the S/Key system operates completely independently of the UNIX password system. Besides the password, there are two other pieces of data that are important to S/Key. One is what is known as the seed or key and consists of two letters and five digits. The other is what is called the iteration count and is a number between 1 and 100. S/Key creates the one-time password by concatenating the seed and the secret password, then applying the MD4 hash as many times as specified by the iteration count and turning the result into six short English words. These six English words are your one-time password. The login and su programs keep track of the last one-time password used, and the user is authenticated if the hash of the user-provided password is equal to the previous password. Because a one-way hash is used it is impossible to generate future one-time passwords if a successfully used password is captured; the iteration count is decremented after each successful login to keep the user and the login program in sync. When the iteration count gets down to 1 S/Key must be reinitialized. There are four programs involved in the S/Key system which we will discuss below. The key program accepts an iteration count, a seed, and a secret password, and generates a one-time password. The keyinit program is used to initialized S/Key, and to change passwords, iteration counts, or seeds; it takes either a secret password, or an iteration count, seed, and one-time password. The keyinfo program examines the /etc/skeykeys file and prints out the invoking user's current iteration count and seed. Finally, the login and su programs contain the necessary logic to accept S/Key one-time passwords for authentication. The login program is also capable of disallowing the use of UNIX passwords on connections coming from specified addresses. There are four different sorts of operations we will cover. The first is using the keyinit program over a secure connection to set up S/Key for the first time, or to change your password or seed. The second operation is using the keyinit program over an insecure connection, in conjunction with the key program over a secure connection, to do the same. The third is using the key program to log in over an insecure connection. The fourth is using the key program to generate a number of keys which can be written down or printed out to carry with you when going to some location without secure connections to anywhere. Secure connection initialization To initialize S/Key for the first time, change your password, or change your seed while logged in over a secure connection (e.g., on the console of a machine or via ssh), use the keyinit command without any parameters while logged in as yourself: &prompt.user; keyinit Adding unfurl: Reminder - Only use this method if you are directly connected. If you are using telnet or rlogin exit with no password and use keyinit -s. Enter secret password: Again secret password: ID unfurl s/key is 99 to17757 DEFY CLUB PRO NASH LACE SOFT At the Enter secret password: prompt you should enter a password or phrase. Remember, this is not the password that you will use to login with, this is used to generate your one-time login keys. The ID line gives the parameters of your particular S/Key instance; your login name, the iteration count, and seed. When logging in with S/Key, the system will remember these parameters and present them back to you so you do not have to remember them. The last line gives the particular one-time password which corresponds to those parameters and your secret password; if you were to re-login immediately, this one-time password is the one you would use. Insecure connection initialization To initialize S/Key or change your secret password over an insecure connection, you will need to already have a secure connection to some place where you can run the key program; this might be in the form of a desk accessory on a Macintosh, or a shell prompt on a machine you trust. You will also need to make up an iteration count (100 is probably a good value), and you may make up your own seed or use a randomly-generated one. Over on the insecure connection (to the machine you are initializing), use the keyinit -s command: &prompt.user; keyinit -s Updating unfurl: Old key: to17758 Reminder you need the 6 English words from the key command. Enter sequence count from 1 to 9999: 100 Enter new key [default to17759]: s/key 100 to 17759 s/key access password: To accept the default seed (which the keyinit program confusingly calls a key), press return. Then before entering an access password, move over to your secure connection or S/Key desk accessory, and give it the same parameters: &prompt.user; key 100 to17759 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> CURE MIKE BANE HIM RACY GORE Now switch back over to the insecure connection, and copy the one-time password generated by key over to the keyinit program: s/key access password:CURE MIKE BANE HIM RACY GORE ID unfurl s/key is 100 to17759 CURE MIKE BANE HIM RACY GORE The rest of the description from the previous section applies here as well. Generating a single one-time password Once you've initialized S/Key, when you login you will be presented with a prompt like this: &prompt.user; telnet example.com Trying 10.0.0.1... Connected to example.com Escape character is '^]'. FreeBSD/i386 (example.com) (ttypa) login: <username> s/key 97 fw13894 Password: As a side note, the S/Key prompt has a useful feature (not shown here): if you press return at the password prompt, the login program will turn echo on, so you can see what you are typing. This can be extremely useful if you are attempting to type in an S/Key by hand, such as from a printout. Also, if this machine were configured to disallow UNIX passwords over a connection from the source machine, the prompt would have also included the annotation (s/key required), indicating that only S/Key one-time passwords will be accepted. At this point you need to generate your one-time password to answer this login prompt. This must be done on a trusted system that you can run the key command on. (There are versions of the key program from DOS, Windows and MacOS as well.) The key program needs both the iteration count and the seed as command line options. You can cut-and-paste these right from the login prompt on the machine that you are logging in to. On the trusted system: &prompt.user; key 97 fw13894 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: WELD LIP ACTS ENDS ME HAAG Now that you have your one-time password you can continue logging in: login: <username> s/key 97 fw13894 Password: <return to enable echo> s/key 97 fw13894 Password [echo on]: WELD LIP ACTS ENDS ME HAAG Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... This is the easiest mechanism if you have a trusted machine. There is a Java S/Key key applet, The Java OTP Calculator, that you can download and run locally on any Java supporting browser. Generating multiple one-time passwords Sometimes you have have to go places where you do not have access to a trusted machine or secure connection. In this case, it is possible to use the key command to generate a number of one-time passwords before hand to be printed out and taken with you. For example: &prompt.user; key -n 5 30 zz99999 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> 26: SODA RUDE LEA LIND BUDD SILT 27: JILT SPY DUTY GLOW COWL ROT 28: THEM OW COLA RUNT BONG SCOT 29: COT MASH BARR BRIM NAN FLAG 30: CAN KNEE CAST NAME FOLK BILK The requests five keys in sequence, the specifies what the last iteration number should be. Note that these are printed out in reverse order of eventual use. If you are really paranoid, you might want to write the results down by hand; otherwise you can cut-and-paste into lpr. Note that each line shows both the iteration count and the one-time password; you may still find it handy to scratch off passwords as you use them. Restricting use of UNIX passwords Restrictions can be placed on the use of UNIX passwords based on the host name, user name, terminal port, or IP address of a login session. These restrictions can be found in the configuration file /etc/skey.access. The &man.skey.access.5; manual page has more info on the complete format of the file and also details some security cautions to be aware of before depending on this file for security. If there is no /etc/skey.access file (this is the FreeBSD default), then all users will be allowed to use UNIX passwords. If the file exists, however, then all users will be required to use S/Key unless explicitly permitted to do otherwise by configuration statements in the skey.access file. In all cases, UNIX passwords are permitted on the console. Here is a sample configuration file which illustrates the three most common sorts of configuration statements: permit internet 192.168.0.0 255.255.0.0 permit user fnord permit port ttyd0 The first line (permit internet) allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use UNIX passwords. This should not be considered a security mechanism, but rather, a means to remind authorized users that they are using an insecure network and need to use S/Key for authentication. The second line (permit user) allows the specified username, in this case fnord, to use UNIX passwords at any time. Generally speaking, this should only be used for people who are either unable to use the key program, like those with dumb terminals, or those who are uneducable. The third line (permit port) allows all users logging in on the specified terminal line to use UNIX passwords; this would be used for dial-ups. Kerberos Contributed by &a.markm; (based on contribution by &a.md;). Kerberos is a network add-on system/protocol that allows users to authenticate themselves through the services of a secure server. Services such as remote login, remote copy, secure inter-system file copying and other high-risk tasks are made considerably safer and more controllable. The following instructions can be used as a guide on how to set up Kerberos as distributed for FreeBSD. However, you should refer to the relevant manual pages for a complete description. In FreeBSD, the Kerberos is not that from the original 4.4BSD-Lite, distribution, but eBones, which had been previously ported to FreeBSD 1.1.5.1, and was sourced from outside the USA/Canada, and was thus available to system owners outside those countries during the era of restrictive export controls on cryptographic code from the USA. Creating the initial database This is done on the Kerberos server only. First make sure that you do not have any old Kerberos databases around. You should change to the directory /etc/kerberosIV and check that only the following files are present: &prompt.root; cd /etc/kerberosIV &prompt.root; ls README krb.conf krb.realms If any additional files (such as principal.* or master_key) exist, then use the kdb_destroy command to destroy the old Kerberos database, of if Kerberos is not running, simply delete the extra files. You should now edit the krb.conf and krb.realms files to define your Kerberos realm. In this case the realm will be GRONDAR.ZA and the server is grunt.grondar.za. We edit or create the krb.conf file: &prompt.root; cat krb.conf GRONDAR.ZA GRONDAR.ZA grunt.grondar.za admin server CS.BERKELEY.EDU okeeffe.berkeley.edu ATHENA.MIT.EDU kerberos.mit.edu ATHENA.MIT.EDU kerberos-1.mit.edu ATHENA.MIT.EDU kerberos-2.mit.edu ATHENA.MIT.EDU kerberos-3.mit.edu LCS.MIT.EDU kerberos.lcs.mit.edu TELECOM.MIT.EDU bitsy.mit.edu ARC.NASA.GOV trident.arc.nasa.gov In this case, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to not include them for simplicity. The first line names the realm in which this system works. The other lines contain realm/host entries. The first item on a line is a realm, and the second is a host in that realm that is acting as a key distribution center. The words admin server following a hosts name means that host also provides an administrative database server. For further explanation of these terms, please consult the Kerberos man pages. Now we have to add grunt.grondar.za to the GRONDAR.ZA realm and also add an entry to put all hosts in the .grondar.za domain in the GRONDAR.ZA realm. The krb.realms file would be updated as follows: &prompt.root; cat krb.realms grunt.grondar.za GRONDAR.ZA .grondar.za GRONDAR.ZA .berkeley.edu CS.BERKELEY.EDU .MIT.EDU ATHENA.MIT.EDU .mit.edu ATHENA.MIT.EDU Again, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to remove them to simplify things. The first line puts the specific system into the named realm. The rest of the lines show how to default systems of a particular subdomain to a named realm. Now we are ready to create the database. This only needs to run on the Kerberos server (or Key Distribution Center). Issue the kdb_init command to do this: &prompt.root; kdb_init Realm name [default ATHENA.MIT.EDU ]: GRONDAR.ZA You will be prompted for the database Master Password. It is important that you NOT FORGET this password. Enter Kerberos master key: Now we have to save the key so that servers on the local machine can pick it up. Use the kstash command to do this. &prompt.root; kstash Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! This saves the encrypted master password in /etc/kerberosIV/master_key. Making it all run Two principals need to be added to the database for each system that will be secured with Kerberos. Their names are kpasswd and rcmd These two principals are made for each system, with the instance being the name of the individual system. These daemons, kpasswd and rcmd allow other systems to change Kerberos passwords and run commands like rcp, rlogin and rsh. Now let's add these entries: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: passwd Instance: grunt <Not found>, Create [y] ? y Principal: passwd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? y Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: rcmd Instance: grunt <Not found>, Create [y] ? Principal: rcmd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Creating the server file We now have to extract all the instances which define the services on each machine. For this we use the ext_srvtab command. This will create a file which must be copied or moved by secure means to each Kerberos client's /etc/kerberosIV directory. This file must be present on each server and client, and is crucial to the operation of Kerberos. &prompt.root; ext_srvtab grunt Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Generating 'grunt-new-srvtab'.... Now, this command only generates a temporary file which must be renamed to srvtab so that all the server can pick it up. Use the mv command to move it into place on the original system: &prompt.root; mv grunt-new-srvtab srvtab If the file is for a client system, and the network is not deemed safe, then copy the client-new-srvtab to removable media and transport it by secure physical means. Be sure to rename it to srvtab in the client's /etc/kerberosIV directory, and make sure it is mode 600: &prompt.root; mv grumble-new-srvtab srvtab &prompt.root; chmod 600 srvtab Populating the database We now have to add some user entries into the database. First let's create an entry for the user jane. Use the kdb_edit command to do this: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: <Not found>, Create [y] ? y Principal: jane, Instance: , kdc_key_ver: 1 New Password: <---- enter a secure password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Testing it all out First we have to start the Kerberos daemons. NOTE that if you have correctly edited your /etc/rc.conf then this will happen automatically when you reboot. This is only necessary on the Kerberos server. Kerberos clients will automagically get what they need from the /etc/kerberosIV directory. &prompt.root; kerberos & Kerberos server starting Sleep forever on error Log file is /var/log/kerberos.log Current Kerberos master key version is 1. Master key entered. BEWARE! Current Kerberos master key version is 1 Local realm: GRONDAR.ZA &prompt.root; kadmind -n & KADM Server KADM0.0A initializing Please do not use 'kill -9' to kill this job, use a regular kill instead Current Kerberos master key version is 1. Master key entered. BEWARE! Now we can try using the kinit command to get a ticket for the id jane that we created above: &prompt.user; kinit jane MIT Project Athena (grunt.grondar.za) Kerberos Initialization for "jane" Password: Try listing the tokens using klist to see if we really have them: &prompt.user; klist Ticket file: /tmp/tkt245 Principal: jane@GRONDAR.ZA Issued Expires Principal Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.GRONDAR.ZA@GRONDAR.ZA Now try changing the password using passwd to check if the kpasswd daemon can get authorization to the Kerberos database: &prompt.user; passwd realm GRONDAR.ZA Old password for jane: New Password for jane: Verifying password New Password for jane: Password changed. Adding <command>su</command> privileges Kerberos allows us to give each user who needs root privileges their own separate supassword. We could now add an id which is authorized to su to root. This is controlled by having an instance of root associated with a principal. Using kdb_edit we can create the entry jane.root in the Kerberos database: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: root <Not found>, Create [y] ? y Principal: jane, Instance: root, kdc_key_ver: 1 New Password: <---- enter a SECURE password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short! Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Now try getting tokens for it to make sure it works: &prompt.root; kinit jane.root MIT Project Athena (grunt.grondar.za) Kerberos Initialization for "jane.root" Password: Now we need to add the user to root's .klogin file: &prompt.root; cat /root/.klogin jane.root@GRONDAR.ZA Now try doing the su: &prompt.user; su Password: and take a look at what tokens we have: &prompt.root; klist Ticket file: /tmp/tkt_root_245 Principal: jane.root@GRONDAR.ZA Issued Expires Principal May 2 20:43:12 May 3 04:43:12 krbtgt.GRONDAR.ZA@GRONDAR.ZA Using other commands In an earlier example, we created a principal called jane with an instance root. This was based on a user with the same name as the principal, and this is a Kerberos default; that a <principal>.<instance> of the form <username>.root will allow that <username> to su to root if the necessary entries are in the .klogin file in root's home directory: &prompt.root; cat /root/.klogin jane.root@GRONDAR.ZA Likewise, if a user has in their own home directory lines of the form: &prompt.user; cat ~/.klogin jane@GRONDAR.ZA jack@GRONDAR.ZA This allows anyone in the GRONDAR.ZA realm who has authenticated themselves to jane or jack (via kinit, see above) access to rlogin to jane's account or files on this system (grunt) via rlogin, rsh or rcp. For example, Jane now logs into another system, using Kerberos: &prompt.user; kinit MIT Project Athena (grunt.grondar.za) Password: %prompt.user; rlogin grunt Last login: Mon May 1 21:14:47 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Or Jack logs into Jane's account on the same machine (Jane having set up the .klogin file as above, and the person in charge of Kerberos having set up principal jack with a null instance: &prompt.user; kinit &prompt.user; rlogin grunt -l jane MIT Project Athena (grunt.grondar.za) Password: Last login: Mon May 1 21:16:55 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Firewalls Contributed by &a.gpalmer; and Alex Nash. Firewalls are an area of increasing interest for people who are connected to the Internet, and are even finding applications on private networks to provide enhanced security. This section will hopefully explain what firewalls are, how to use them, and how to use the facilities provided in the FreeBSD kernel to implement them. People often think that having a firewall between your internal network and the Big Bad Internet will solve all your security problems. It may help, but a poorly setup firewall system is more of a security risk than not having one at all. A firewall can add another layer of security to your systems, but it cannot stop a really determined cracker from penetrating your internal network. If you let internal security lapse because you believe your firewall to be impenetrable, you have just made the crackers job that much easier. What is a firewall? There are currently two distinct types of firewalls in common use on the Internet today. The first type is more properly called a packet filtering router, where the kernel on a multi-homed machine chooses whether to forward or block packets based on a set of rules. The second type, known as a proxy server, relies on daemons to provide authentication and to forward packets, possibly on a multi-homed machine which has kernel packet forwarding disabled. Sometimes sites combine the two types of firewalls, so that only a certain machine (known as a bastion host) is allowed to send packets through a packet filtering router onto an internal network. Proxy services are run on the bastion host, which are generally more secure than normal authentication mechanisms. FreeBSD comes with a kernel packet filter (known as IPFW), which is what the rest of this section will concentrate on. Proxy servers can be built on FreeBSD from third party software, but there is such a variety of proxy servers available that it would be impossible to cover them in this document. Packet filtering routers A router is a machine which forwards packets between two or more networks. A packet filtering router has an extra piece of code in its kernel which compares each packet to a list of rules before deciding if it should be forwarded or not. Most modern IP routing software has packet filtering code within it that defaults to forwarding all packets. To enable the filters, you need to define a set of rules for the filtering code so it can decide if the packet should be allowed to pass or not. To decide whether a packet should be passed on, the code looks through its set of rules for a rule which matches the contents of this packets headers. Once a match is found, the rule action is obeyed. The rule action could be to drop the packet, to forward the packet, or even to send an ICMP message back to the originator. Only the first match counts, as the rules are searched in order. Hence, the list of rules can be referred to as a rule chain. The packet matching criteria varies depending on the software used, but typically you can specify rules which depend on the source IP address of the packet, the destination IP address, the source port number, the destination port number (for protocols which support ports), or even the packet type (UDP, TCP, ICMP, etc). Proxy servers Proxy servers are machines which have had the normal system daemons (telnetd, ftpd, etc) replaced with special servers. These servers are called proxy servers as they normally only allow onward connections to be made. This enables you to run (for example) a proxy telnet server on your firewall host, and people can telnet in to your firewall from the outside, go through some authentication mechanism, and then gain access to the internal network (alternatively, proxy servers can be used for signals coming from the internal network and heading out). Proxy servers are normally more secure than normal servers, and often have a wider variety of authentication mechanisms available, including one-shot password systems so that even if someone manages to discover what password you used, they will not be able to use it to gain access to your systems as the password instantly expires. As they do not actually give users access to the host machine, it becomes a lot more difficult for someone to install backdoors around your security system. Proxy servers often have ways of restricting access further, so that only certain hosts can gain access to the servers, and often they can be set up so that you can limit which users can talk to which destination machine. Again, what facilities are available depends largely on what proxy software you choose. What does IPFW allow me to do? IPFW, the software supplied with FreeBSD, is a packet filtering and accounting system which resides in the kernel, and has a user-land control utility, &man.ipfw.8;. Together, they allow you to define and query the rules currently used by the kernel in its routing decisions. There are two related parts to IPFW. The firewall section allows you to perform packet filtering. There is also an IP accounting section which allows you to track usage of your router, based on similar rules to the firewall section. This allows you to see (for example) how much traffic your router is getting from a certain machine, or how much WWW (World Wide Web) traffic it is forwarding. As a result of the way that IPFW is designed, you can use IPFW on non-router machines to perform packet filtering on incoming and outgoing connections. This is a special case of the more general use of IPFW, and the same commands and techniques should be used in this situation. Enabling IPFW on FreeBSD As the main part of the IPFW system lives in the kernel, you will need to add one or more options to your kernel configuration file, depending on what facilities you want, and recompile your kernel. See reconfiguring the kernel for more details on how to recompile your kernel. There are currently three kernel configuration options relevant to IPFW: options IPFIREWALL Compiles into the kernel the code for packet filtering. options IPFIREWALL_VERBOSE Enables code to allow logging of packets through &man.syslogd.8;. Without this option, even if you specify that packets should be logged in the filter rules, nothing will happen. options IPFIREWALL_VERBOSE_LIMIT=10 Limits the number of packets logged through &man.syslogd.8; on a per entry basis. You may wish to use this option in hostile environments in which you want to log firewall activity, but do not want to be open to a denial of service attack via syslog flooding. When a chain entry reaches the packet limit specified, logging is turned off for that particular entry. To resume logging, you will need to reset the associated counter using the &man.ipfw.8; utility: &prompt.root; ipfw zero 4500 Where 4500 is the chain entry you wish to continue logging. Previous versions of FreeBSD contained an IPFIREWALL_ACCT option. This is now obsolete as the firewall code automatically includes accounting facilities. Configuring IPFW The configuration of the IPFW software is done through the &man.ipfw.8; utility. The syntax for this command looks quite complicated, but it is relatively simple once you understand its structure. There are currently four different command categories used by the utility: addition/deletion, listing, flushing, and clearing. Addition/deletion is used to build the rules that control how packets are accepted, rejected, and logged. Listing is used to examine the contents of your rule set (otherwise known as the chain) and packet counters (accounting). Flushing is used to remove all entries from the chain. Clearing is used to zero out one or more accounting entries. Altering the IPFW rules The syntax for this form of the command is: ipfw -N command index action log protocol addresses options There is one valid flag when using this form of the command: -N Resolve addresses and service names in output. The command given can be shortened to the shortest unique form. The valid commands are: add Add an entry to the firewall/accounting rule list delete Delete an entry from the firewall/accounting rule list Previous versions of IPFW used separate firewall and accounting entries. The present version provides packet accounting with each firewall entry. If an index value is supplied, it used to place the entry at a specific point in the chain. Otherwise, the entry is placed at the end of the chain at an index 100 greater than the last chain entry (this does not include the default policy, rule 65535, deny). The log option causes matching rules to be output to the system console if the kernel was compiled with IPFIREWALL_VERBOSE. Valid actions are: reject Drop the packet, and send an ICMP host or port unreachable (as appropriate) packet to the source. allow Pass the packet on as normal. (aliases: pass and accept) deny Drop the packet. The source is not notified via an ICMP message (thus it appears that the packet never arrived at the destination). count Update packet counters but do not allow/deny the packet based on this rule. The search continues with the next chain entry. Each action will be recognized by the shortest unambiguous prefix. The protocols which can be specified are: all Matches any IP packet icmp Matches ICMP packets tcp Matches TCP packets udp Matches UDP packets The address specification is: from address/maskport to address/maskport via interface You can only specify port in conjunction with protocols which support ports (UDP and TCP). The is optional and may specify the IP address or domain name of a local IP interface, or an interface name (e.g. ed0) to match only packets coming through this interface. Interface unit numbers can be specified with an optional wildcard. For example, ppp* would match all kernel PPP interfaces. The syntax used to specify an address/mask is: address or address/mask-bits or address:mask-pattern A valid hostname may be specified in place of the IP address. is a decimal number representing how many bits in the address mask should be set. e.g. specifying 192.216.222.1/24 will create a mask which will allow any address in a class C subnet (in this case, 192.216.222) to be matched. is an IP address which will be logically AND'ed with the address given. The keyword any may be used to specify any IP address. The port numbers to be blocked are specified as: port,port,port… to specify either a single port or a list of ports, or port-port to specify a range of ports. You may also combine a single range with a list, but the range must always be specified first. The options available are: frag Matches if the packet is not the first fragment of the datagram. in Matches if the packet is on the way in. out Matches if the packet is on the way out. ipoptions spec Matches if the IP header contains the comma separated list of options specified in spec. The supported list of IP options are: ssrr (strict source route), lsrr (loose source route), rr (record packet route), and ts (time stamp). The absence of a particular option may be denoted with a leading !. established Matches if the packet is part of an already established TCP connection (i.e. it has the RST or ACK bits set). You can optimize the performance of the firewall by placing established rules early in the chain. setup Matches if the packet is an attempt to establish a TCP connection (the SYN bit set is set but the ACK bit is not). tcpflags flags Matches if the TCP header contains the comma separated list of flags. The supported flags are fin, syn, rst, psh, ack, and urg. The absence of a particular flag may be indicated by a leading !. icmptypes types Matches if the ICMP type is present in the list types. The list may be specified as any combination of ranges and/or individual types separated by commas. Commonly used ICMP types are: 0 echo reply (ping reply), 3 destination unreachable, 5 redirect, 8 echo request (ping request), and 11 time exceeded (used to indicate TTL expiration as with &man.traceroute.8;). Listing the IPFW rules The syntax for this form of the command is: ipfw -a -t -N l There are three valid flags when using this form of the command: -a While listing, show counter values. This option is the only way to see accounting counters. -t Display the last match times for each chain entry. The time listing is incompatible with the input syntax used by the &man.ipfw.8; utility. -N Attempt to resolve given addresses and service names. Flushing the IPFW rules The syntax for flushing the chain is: ipfw flush This causes all entries in the firewall chain to be removed except the fixed default policy enforced by the kernel (index 65535). Use caution when flushing rules, the default deny policy will leave your system cut off from the network until allow entries are added to the chain. Clearing the IPFW packet counters The syntax for clearing one or more packet counters is: ipfw zero index When used without an index argument, all packet counters are cleared. If an index is supplied, the clearing operation only affects a specific chain entry. Example commands for ipfw This command will deny all packets from the host evil.crackers.org to the telnet port of the host nice.people.org: &prompt.root ipfw add deny tcp from evil.crackers.org to nice.people.org 23 The next example denies and logs any TCP traffic from the entire crackers.org network (a class C) to the nice.people.org machine (any port). &prompt.root; ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org If you do not want people sending X sessions to your internal network (a subnet of a class C), the following command will do the necessary filtering: &prompt.root; ipfw add deny tcp from any to my.org/28 6000 setup To see the accounting records: &prompt.root; ipfw -a list or in the short form &prompt.root; ipfw -a l You can also see the last time a chain entry was matched with: &prompt.root; ipfw -at l Building a packet filtering firewall The following suggestions are just that: suggestions. The requirements of each firewall are different and we cannot tell you how to build a firewall to meet your particular requirements. When initially setting up your firewall, unless you have a test bench setup where you can configure your firewall host in a controlled environment, it is strongly recommend you use the logging version of the commands and enable logging in the kernel. This will allow you to quickly identify problem areas and cure them without too much disruption. Even after the initial setup phase is complete, I recommend using the logging for `deny' as it allows tracing of possible attacks and also modification of the firewall rules if your requirements alter. If you use the logging versions of the accept command, it can generate large amounts of log data as one log line will be generated for every packet that passes through the firewall, so large ftp/http transfers, etc, will really slow the system down. It also increases the latencies on those packets as it requires more work to be done by the kernel before the packet can be passed on. syslogd with also start using up a lot more processor time as it logs all the extra data to disk, and it could quite easily fill the partition /var/log is located on. You should enable your firewall from /etc/rc.conf.local or /etc/rc.conf. The associated man page explains which knobs to fiddle and lists some preset firewall configurations. If you do not use a preset configuration, ipfw list will output the current ruleset into a file that you can pass to rc.conf. If you do not use /etc/rc.conf.local or /etc/rc.conf to enable your firewall, it is important to make sure your firewall is enabled before any IP interfaces are configured. The next problem is what your firewall should actually do! This is largely dependent on what access to your network you want to allow from the outside, and how much access to the outside world you want to allow from the inside. Some general rules are: Block all incoming access to ports below 1024 for TCP. This is where most of the security sensitive services are, like finger, SMTP (mail) and telnet. Block all incoming UDP traffic. There are very few useful services that travel over UDP, and what useful traffic there is is normally a security threat (e.g. Suns RPC and NFS protocols). This has its disadvantages also, since UDP is a connectionless protocol, denying incoming UDP traffic also blocks the replies to outgoing UDP traffic. This can cause a problem for people (on the inside) using external archie (prospero) servers. If you want to allow access to archie, you'll have to allow packets coming from ports 191 and 1525 to any internal UDP port through the firewall. ntp is another service you may consider allowing through, which comes from port 123. Block traffic to port 6000 from the outside. Port 6000 is the port used for access to X11 servers, and can be a security threat (especially if people are in the habit of doing xhost + on their workstations). X11 can actually use a range of ports starting at 6000, the upper limit being how many X displays you can run on the machine. The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063. Check what ports any internal servers use (e.g. SQL servers, etc). It is probably a good idea to block those as well, as they normally fall outside the 1-1024 range specified above. Another checklist for firewall configuration is available from CERT at http://www.cert.org/tech_tips/packet_filtering.html As stated above, these are only guidelines. You will have to decide what filter rules you want to use on your firewall yourself. We cannot accept ANY responsibility if someone breaks into your network, even if you follow the advice given above. OpenSSL As of FreeBSD 4.0, the OpenSSL toolkit is a part of the base system. OpenSSL provides a general-purpose cryptography library, as well as the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols. However, one of the algorithms (specifically IDEA) included in OpenSSL is protected by patents in the USA and elsewhere, and is not available for unrestricted use. IDEA is included in the OpenSSL sources in FreeBSD, but it is not built by default. If you wish to use it, and you comply with the license terms, enable the MAKE_IDEA switch in /etc/make.conf and rebuild your sources using 'make world'. Today, the RSA algorithm is free for use in USA and other countries. In the past it was protected by a patent. Source Code Installations OpenSSL is part of the src-crypto and src-secure cvsup collections. See the Obtaining FreeBSD section for more information about obtaining and updating FreeBSD source code. IPsec Contributed by &a.shin;, 5 March 2000. The IPsec mechanism provides secure communication either for IP layer and socket layer communication. This section should explain how to use them. For implementation details, please refer to The Developers' Handbook. The current IPsec implementation supports both transport mode and tunnel mode. However, tunnel mode comes with some restrictions. http://www.kame.net/newsletter/ has more comprehensive examples. Please be aware that in order to use this functionality, you must have the following options compiled into your kernel: options IPSEC #IP security options IPSEC_ESP #IP security (crypto; define w/IPSEC) Transport mode example with IPv4 Let's setup security association to deploy a secure channel between HOST A (10.2.3.4) and HOST B (10.6.7.8). Here we show a little complicated example. From HOST A to HOST B, only old AH is used. From HOST B to HOST A, new AH and new ESP are combined. Now we should choose algorithm to be used corresponding to "AH"/"new AH"/"ESP"/"new ESP". Please refer to the &man.setkey.8; man page to know algorithm names. Our choice is MD5 for AH, new-HMAC-SHA1 for new AH, and new-DES-expIV with 8 byte IV for new ESP. Key length highly depends on each algorithm. For example, key length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1, and 8 for new-DES-expIV. Now we choose "MYSECRETMYSECRET", "KAMEKAMEKAMEKAMEKAME", "PASSWORD", respectively. OK, let's assign SPI (Security Parameter Index) for each protocol. Please note that we need 3 SPIs for this secure channel since three security headers are produced (one for from HOST A to HOST B, two for from HOST B to HOST A). Please also note that SPI MUST be greater than or equal to 256. We choose, 1000, 2000, and 3000, respectively. (1) HOST A ------> HOST B (1)PROTO=AH ALG=MD5(RFC1826) KEY=MYSECRETMYSECRET SPI=1000 (2.1) HOST A <------ HOST B <------ (2.2) (2.1) PROTO=AH ALG=new-HMAC-SHA1(new AH) KEY=KAMEKAMEKAMEKAMEKAME SPI=2000 (2.2) PROTO=ESP ALG=new-DES-expIV(new ESP) IV length = 8 KEY=PASSWORD SPI=3000 Now, let's setup security association. Execute &man.setkey.8; on both HOST A and B: &prompt.root; setkey -c add 10.2.3.4 10.6.7.8 ah-old 1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ; add 10.6.7.8 10.2.3.4 ah 2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ; add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ; ^D Actually, IPsec communication doesn't process until security policy entries will be defined. In this case, you must setup each host. At A: &prompt.root; setkey -c spdadd 10.2.3.4 10.6.7.8 any -P out ipsec ah/transport/10.2.3.4-10.6.7.8/require ; ^D At B: &prompt.root; setkey -c spdadd 10.6.7.8 10.2.3.4 any -P out ipsec esp/transport/10.6.7.8-10.2.3.4/require ; spdadd 10.6.7.8 10.2.3.4 any -P out ipsec ah/transport/10.6.7.8-10.2.3.4/require ; ^D HOST A --------------------------------------> HOST E 10.2.3.4 10.6.7.8 | | ========== old AH keyed-md5 ==========> <========= new AH hmac-sha1 =========== <========= new ESP des-cbc ============ Transport mode example with IPv6 Another example using IPv6. ESP transport mode is recommended for TCP port number 110 between Host-A and Host-B. ============ ESP ============ | | Host-A Host-B fec0::10 -------------------- fec0::11 Encryption algorithm is blowfish-cbc whose key is "kamekame", and authentication algorithm is hmac-sha1 whose key is "this is the test key". Configuration at Host-A: &prompt.root; setkey -c <<EOF spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec esp/transport/fec0::10-fec0::11/use ; spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec esp/transport/fec0::11-fec0::10/use ; add fec0::10 fec0::11 esp 0x10001 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; add fec0::11 fec0::10 esp 0x10002 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; EOF and at Host-B: &prompt.root; setkey -c <<EOF spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec esp/transport/fec0::11-fec0::10/use ; spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec esp/transport/fec0::10-fec0::11/use ; add fec0::10 fec0::11 esp 0x10001 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; add fec0::11 fec0::10 esp 0x10002 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; EOF Note the direction of SP. Tunnel mode example with IPv4 Tunnel mode between two security gateways Security protocol is old AH tunnel mode, i.e. specified by RFC1826, with keyed-md5 whose key is "this is the test" as authentication algorithm. ======= AH ======= | | Network-A Gateway-A Gateway-B Network-B 10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24 Configuration at Gateway-A: &prompt.root; setkey -c <<EOF spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec ah/tunnel/172.16.0.1-172.16.0.2/require ; spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec ah/tunnel/172.16.0.2-172.16.0.1/require ; add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any -A keyed-md5 "this is the test" ; add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any -A keyed-md5 "this is the test" ; EOF If port number field is omitted such above then "[any]" is employed. `-m' specifies the mode of SA to be used. "-m any" means wild-card of mode of security protocol. You can use this SA for both tunnel and transport mode. and at Gateway-B: &prompt.root; setkey -c <<EOF spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec ah/tunnel/172.16.0.2-172.16.0.1/require ; spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec ah/tunnel/172.16.0.1-172.16.0.2/require ; add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any -A keyed-md5 "this is the test" ; add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any -A keyed-md5 "this is the test" ; EOF Making SA bundle between two security gateways AH transport mode and ESP tunnel mode is required between Gateway-A and Gateway-B. In this case, ESP tunnel mode is applied first, and AH transport mode is next. ========== AH ========= | ======= ESP ===== | | | | | Network-A Gateway-A Gateway-B Network-B fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64 Tunnel mode example with IPv6 Encryption algorithm is 3des-cbc, and authentication algorithm for ESP is hmac-sha1. Authentication algorithm for AH is hmac-md5. Configuration at Gateway-A: &prompt.root; setkey -c <<EOF spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ; spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ; add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel -E 3des-cbc "kamekame12341234kame1234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport -A hmac-md5 "this is the test" ; add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel -E 3des-cbc "kamekame12341234kame1234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport -A hmac-md5 "this is the test" ; EOF Making SAs with the different end ESP tunnel mode is required between Host-A and Gateway-A. Encryption algorithm is cast128-cbc, and authentication algorithm for ESP is hmac-sha1. ESP transport mode is recommended between Host-A and Host-B. Encryption algorithm is rc5-cbc, and authentication algorithm for ESP is hmac-md5. ================== ESP ================= | ======= ESP ======= | | | | | Host-A Gateway-A Host-B fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2 Configuration at Host-A: &prompt.root; setkey -c <<EOF spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ; spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ; add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001 -m transport -E cast128-cbc "12341234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002 -E rc5-cbc "kamekame" -A hmac-md5 "this is the test" ; add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003 -m transport -E cast128-cbc "12341234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004 -E rc5-cbc "kamekame" -A hmac-md5 "this is the test" ; EOF OpenSSH Contributed by &a.chern;, April 21, 2001. Secure shell is a set of network connectivity tools used to access remote machines securely. It can be used as a direct replacement for rlogin, rsh, rcp, and telnet. Additionaly, any other TCP/IP connections can be tunnelled/forwarded securely through ssh. ssh encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks. OpenSSH is maintained by the OpenBSD project, and is based upon SSH v1.2.12 with all the recent bug fixes and updates. It is compatible with both SSH protocols 1 and 2. OpenSSH has been in the base system since FreeBSD 4.0. Advantages of using OpenSSH Normally, when using &man.telnet.1; or &man.rlogin.1;, data is sent over the network in an clear, un-encrypted form. Network sniffers anywhere in between the client and server can steal your user/password information or data transferred in your session. OpenSSH offers a variety of authentication and encryption methods to prevent this from happening. Enabling sshd Be sure to make the following additions to your rc.conf file: sshd_enable="YES" This will load the ssh daemon the next time your system inializes. Alternatively, you can simply run the sshd daemon. SSH client The &man.ssh.1; utility works similarly to &man.rlogin.1;. &prompt.root ssh user@foobardomain.com Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)? yes Host 'foobardomain.com' added to the list of known hosts. user@foobardomain.com's password: ******* The login will continue just as it would have if a session was created using rlogin or telnet. SSH utilizes a key fingerprint system for verifying the authenticity of the server when the client connects. The user is prompted to enter 'yes' only during the first time connecting. Future attempts to login are all verified against the saved fingerprint key. The SSH client will alert you if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in ~/.ssh/known_hosts Secure copy The scp command works similarly to rcp; it copies a file to or from a remote machine, except in a secure fashion. &prompt.root scp user@foobardomain.com:/COPYRIGHT COPYRIGHT user@foobardomain.com's password: COPYRIGHT 100% |*****************************| 4735 00:00 &prompt.root Since the fingerprint was already saved for this host in the previous example, it is verified when using scp here. Configuration The system-wide configuration files for both the OpenSSH daemon and client reside within the /etc/ssh directory. ssh_config configures the client settings, while sshd_config configures the daemon. ssh-keygen Instead of using passwords, &man.ssh-keygen.1; can be used to generate RSA keys to authenticate a user. &prompt.user ssh-keygen Initializing random number generator... Generating p: .++ (distance 66) Generating q: ..............................++ (distance 498) Computing the keys... Key generation complete. Enter file in which to save the key (/home/user/.ssh/identity): Enter passphrase: Enter the same passphrase again: Your identification has been saved in /home/user/.ssh/identity. ... &man.ssh-keygen.1; will create a public and private key pair for use in authentication. The private key is stored in ~/.ssh/identity, whereas the public key is stored in ~/.ssh/identity.pub. The public key must be placed in ~/.ssh/authorized_keys of the remote machine in order for the setup to work. This will allow connection to the remote machine based upon RSA authentication instead of passwords. If a passphrase is used in &man.ssh-keygen.1;, the user will be prompted for a password each time in order to use the private key. &man.ssh-agent.1; and &man.ssh-add.1; are utilities used in managing multiple passworded private keys. SSH Tunneling OpenSSH has the ability to create a tunnel to encapsulate another protocol in an encrypted session. The following command tells &man.ssh.1; to create a tunnel for telnet. &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.bar.com &prompt.user; -2 this forces &man.ssh.1 to use version 2 of the protocol. (Do not use if you are working with older ssh servers) -N indicates no command, or tunnel only. If ommitted, &man.ssh.1; would initiate a normal session. -f forces &man.ssh.1; to run in the background. -L indicates a local tunnel in localport:localhost:remoteport fashion. foo.bar.com is the remote/target SSH server. An SSH tunnel works by creating a listen socket on the specified local host and port. It then forwards any connection to the local host/port via the SSH connection to the remote machine on the specified remote port. In the example, port 5023 on localhost is being forwarded to port 23 on the remote machine. Since 23 is telnet, this would create a secure telnet session through an SSH tunnel. This can be used to wrap any number of insecure TCP protocols such as smtp, pop3, ftp, etc. A typical SSH Tunnel &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.foobar.com user@mailserver.foobar.com's password: ***** &prompt.user; telnet localhost 5025 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 220 mailserver.foobar.com ESMTP This can be used in conjunction with an &man.ssh-keygen.1; and additional user accounts to create a more seamless/hassle-free SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a seperate user. Further Reading OpenSSH &man.ssh.1; &man.scp.1; &man.ssh-keygen.1; &man.ssh-agent.1; &man.ssh-add.1; &man.sshd.8; &man.sftp-server.8; diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml index f425e7553e..e694c885cc 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml @@ -1,4480 +1,4482 @@ %man; %bookinfo; %authors; %mailing-lists; ]> FreeBSD Porter's Handbook The FreeBSD Documentation Project April 2000 2000 The FreeBSD Documentation Project &bookinfo.legalnotice; Making a port yourself So, now 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 bsd.port.mk. This file uses a non-standard tab setting. Emacs and Vim should recognize the setting on loading the file. Both vi and ex 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 enough, but we will see. 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 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 three description files that are required for any port, whether they actually package or not. They are pkg-comment, pkg-descr, and pkg-plist, and their pkg- prefix distinguishes them from other files. <filename>pkg-comment</filename> This is the 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: A cat chasing a mouse all over the screen <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; man 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. 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. The latter one helps the committers a lot, who use scripts for the ports-work. One more time, do not include the original source distfile, the work directory, or the package you built with make package. In the past, we asked you to upload new port submissions in our ftp site (ftp.FreeBSD.org). This is no longer recommended as read access is turned off on the incoming/ directory of that site due to the large amount of pirated software showing up there. We will look at your port, get back to you if necessary, and put it in the tree. Your name will also appear in the list of “Additional FreeBSD contributors” in the FreeBSD Handbook and other files. Isn't that great?!? :-) 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: <short description of the port>” for new ports and “Update port: <category>/<port> <short description of the update>” for port updates. If you stick to this scheme, the chance that one takes a look at your PR soon is much bigger. 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 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/, 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 touch extract! 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. 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). Make sure you set MASTER_SITES to reflect your choice. If you cannot find somewhere convenient and reliable to put the distfile we can “house” it ourselves on ftp.FreeBSD.org. 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 for no good reason, consider putting the distfile in your home page and listing it as the first MASTER_SITES. This 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 diff for later feeding to patch. 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). 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, then 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). 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 CD-ROMs 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. <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. PORTREVISION is increased each time a change is made to the FreeBSD port which significantly affects the content or stucture 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 FreeBSD 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 behaviour 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 effect 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 no package was 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 someone, somewhere, would benefit from having (either because of an enhancement, fix, or by virtue that the new package will actually work for them). If yes, the PORTREVISION should be bumped so that automated tools (e.g. pkg_version) will highlight the fact that a new package is available. <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 is never 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 (2000801), but the ,1 suffix is treated specially by automated tools and found to be greater than the implied suffix ",0" on the earlier package) 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. <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, use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. <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 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 when 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>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 CD-ROM. Please take a look at the existing 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 the categories section 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. <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, and we are even planning to add support for automatically determining the closest master site and fetching from there! 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 archives 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>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. Note that 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. <makevar>MAINTAINER</makevar> Set your mail-address here. Please. :-) For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section. Dependencies Many ports depend on other ports. There are five 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 behaviour 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 pkg_add 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= ${PREFIX}/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 in to the package so that pkg_add 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>DEPENDS</makevar> If there is a dependency that does not fall into either of the above four 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. Common dependency variables 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=yes if your port requires GNU autoconf to be run. Define USE_QT=yes 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. 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 the to get to 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 behaviour 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. Optional dependencies Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to decide which configuration should be built. Supporting these properly will make uses happy, and effectively provide 2 or more ports for the price of one. The easiest of these to use is WITHOUT_X11. If the port can be built both with and without X support, then it should normally be built with X support. If WITHOUT_X11 is defined, then the version that does not have X support should be built. Various parts of GNOME have such knobs, though they are slightly more difficult to use. The variables to use in the Makefile are WANT_* and HAVE_*. If the application can be built both with or without one of the dependencies listed below, then the Makefile should set WANT_PKG, and should build the version that uses PKG if HAVE_PKG is defined. The WANT_* variables currently supported this way are WANT_GLIB, WANT_GTK, WANT_ESOUND, WANT_IMLIB, and WANT_GNOME. 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=yes. This implies GNU_CONFIGURE, and will cause autoconf to be run before configure. 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 deinstallation will not cause the system to still believe the library is there. If you need, you can override default location where the new library is installed by defining 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. <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 Makefiles, 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>REQUIRES_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 to use 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 is new to XFree86 release 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 The new version of texinfo (included in 2.2.2-RELEASE and onwards) contains a utility called install-info to add and delete entries to the dir file. If your port installs any info documents, please follow these instructions so your port/package will correctly update the user's PREFIX/info/dir file. (Sorry for the length of this section, but is it imperative to weave all the info files together. If done correctly, it will produce a beautiful listing, so please bear with me! First, this is what you (as a porter) need to know &prompt.user; install-info --help install-info [OPTION]... [INFO-FILE [DIR-FILE]] Install INFO-FILE in the Info directory file DIR-FILE. Options: --delete Delete existing entries in INFO-FILE; don't insert any new entries. : --entry=TEXT Insert TEXT as an Info directory entry. : --section=SEC Put this file's entries in section SEC of the directory. : This program will not actually install info files; it merely inserts or deletes entries in the dir file. Here's a seven-step procedure to convert ports to use install-info. editors/emacs will be used as an example. Look at the texinfo sources and make a patch to insert @dircategory and @direntry statements to files that do not have them. This is part of my patch: --- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 +++ ./man/vip.texi Tue May 20 01:28:33 1997 @@ -2,6 +2,10 @@ @setfilename ../info/vip @settitle VIP +@dircategory The Emacs editor and associated tools +@direntry +* VIP: (vip). A VI-emulation for Emacs. +@end direntry @iftex @finalout : The format should be self-explanatory. Many authors leave a dir file in the source tree that contains all the entries you need, so look around before you try to write your own. Also, make sure you look into related ports and make the section names and entry indentations consistent (we recommend that all entry text start at the 4th tab stop). Note that you can put only one info entry per file because of a bug in install-info --delete that deletes only the first entry if you specify multiple entries in the @direntry section. You can give the dir entries to install-info as arguments ( and ) instead of patching the texinfo sources. This probably is not a good idea for ports because you need to duplicate the same information in three places (Makefile and @exec/@unexec of pkg-plist; see below). However, if you have Japanese (or other multibyte encoding) info files, you will have to use the extra arguments to install-info because makeinfo cannot handle those texinfo sources. (See Makefile and pkg-plist of japanese/skk for examples on how to do this). Go back to the port directory and do a make clean; make and verify that the info files are regenerated from the texinfo sources. Since the texinfo sources are newer than the info files, they should be rebuilt when you type make; but many Makefiles do not include correct dependencies for info files. In emacs' case, it was necessary to patch the main Makefile.in so it would descend into the man subdirectory to rebuild the info pages. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Tue Apr 15 00:15:28 1997 @@ -184,7 +184,7 @@ # Subdirectories to make recursively. `lisp' is not included # because the compiled lisp files are part of the distribution # and you cannot remake them without installing Emacs first. -SUBDIR = lib-src src +SUBDIR = lib-src src man # The makefiles of the directories in $SUBDIR. SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile --- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 +++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 @@ -66,6 +66,7 @@ ${srcdir}/gnu1.texi \ ${srcdir}/glossary.texi +all: info info: $(INFO_TARGETS) dvi: $(DVI_TARGETS) The second hunk was necessary because the default target in the man subdir is called info, while the main Makefile wants to call all. The installation of the info info file was also removed because we already have one with the same name in /usr/share/info (that patch is not shown here). If there is a place in the Makefile that is installing the dir file, delete it. Your port may not be doing it. Also, remove any commands that are otherwise mucking around with the dir file. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Mon Apr 14 23:38:07 1997 @@ -368,14 +368,8 @@ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ then \ (cd ${infodir}; \ - if [ -f dir ]; then \ - if [ ! -f dir.old ]; then mv -f dir dir.old; \ - else mv -f dir dir.bak; fi; \ - fi; \ cd ${srcdir}/info ; \ - (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \ - (cd $${thisdir}; chmod a+r ${infodir}/dir); \ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ (cd $${thisdir}; \ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ chmod a+r ${infodir}/$$f); \ (This step is only necessary if you are modifying an existing port.) Take a look at pkg-plist and delete anything that is trying to patch up info/dir. They may be in pkg-install or some other file, so search extensively. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/04/15 06:32:12 @@ -15,9 +15,6 @@ man/man1/emacs.1.gz man/man1/etags.1.gz man/man1/ctags.1.gz -@unexec cp %D/info/dir %D/info/dir.bak -info/dir -@unexec cp %D/info/dir.bak %D/info/dir info/cl info/cl-1 info/cl-2 Add a post-install target to the Makefile to call install-info with the installed info files. (It is no longer necessary to create the dir file yourself; install-info automatically creates this file if it does not exist.) Index: Makefile =================================================================== RCS file: /usr/cvs/ports/editors/emacs/Makefile,v retrieving revision 1.26 diff -u -r1.26 Makefile --- Makefile 1996/11/19 13:14:40 1.26 +++ Makefile 1997/05/20 10:25:09 1.28 @@ -20,5 +20,8 @@ post-install: .for file in emacs-19.34 emacsclient etags ctags b2m strip ${PREFIX}/bin/${file} .endfor +.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode + install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir +.endfor .include <bsd.port.mk> Edit pkg-plist and add equivalent @exec statements and also @unexec for pkg_delete. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/05/20 10:25:12 1.17 @@ -16,7 +14,14 @@ man/man1/etags.1.gz man/man1/ctags.1.gz +@unexec install-info --delete %D/info/emacs %D/info/dir : +@unexec install-info --delete %D/info/ccmode %D/info/dir info/cl info/cl-1 @@ -87,6 +94,18 @@ info/viper-3 info/viper-4 +@exec install-info %D/info/emacs %D/info/dir : +@exec install-info %D/info/ccmode %D/info/dir libexec/emacs/19.34/i386--freebsd/cvtmail libexec/emacs/19.34/i386--freebsd/digest-doc The @unexec install-info --delete commands have to be listed before the info files themselves so they can read the files. Also, the @exec install-info commands have to be after the info files and the @exec command that creates the the dir file. Test and admire your work. :-). Check the dir file before and after each step. 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 pkg_add 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 pkg_add you can do this via the pkg-install script. This script will automatically be added to the package, and will be run twice by pkg_add. 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-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/deinstallation time to determine whether or not installation/deinstallation should proceed. 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., 2.2.7). %%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). 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 man pages) will be done between the do-install and post-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 do-install. Also, if your port needs to edit the resulting file, do so in post-install to a file named TMPPLIST. 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 in to the pkg-* subdirectory). Here is a list of variable names and their default values. (PKGDIR defaults to ${MASTERDIR}.) Variable Default value COMMENT ${PKGDIR}/pkg-comment 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. Licensing Problems Some software packages have restrictive licenses or can be in violation of the law in some countries (such as violating a patent). What we can do with them varies a lot, depending on the exact wordings of the respective licenses. 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 or CD-ROM. If in doubt, please contact the &a.ports;. There are two variables you can set in the Makefile to handle the situations that arise frequently: If the port has a “do not sell for profit” type of license, set the variable NO_CDROM to a string describing the reason why. We will make sure such ports will not go into the CD-ROM come release time. The distfile and package will still be available via ftp. If the resulting package needs to be built uniquely for each site, or the resulting binary package cannot be distributed due to licensing; set the variable NO_PACKAGE to a string describing the reason why. We will make sure such packages will not go on the ftp site, nor into the CD-ROM come release time. The distfile will still be included on both however. If the port has legal restrictions on who can use it (e.g., patented stuff) or has a “no commercial use” license, set the variable RESTRICTED to be the string describing the reason why. For such ports, the distfiles/packages will not be available even from our ftp sites. The GNU General Public License (GPL), both version 1 and 2, should not be a problem for ports. If you are a committer, make sure you update the ports/LEGAL file too. Upgrading When you notice that a port is out of date compared to the latest version from the original authors, first make sure you have the latest port. You can find them in the ports/ports-current directory of the ftp mirror sites. You may also use CVSup to keep your whole ports collection up-to-date, as described in the Handbook. The next step is to send a mail to the maintainer, if one is listed in the port's Makefile. 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). If the maintainer asks you to do the upgrade or there is not any such person to begin with, please make the upgrade and send the recursive diff (either unified or context diff is fine, but port committers appear to prefer unified diff more) of the new and old ports directories to us (e.g., if your modified port directory is called superedit and the original as in our tree is superedit.bak, then send us the result of diff -ruN superedit.bak superedit). Please examine the output to make sure all the changes make sense. The best way to send us the diff is by including it via &man.send-pr.1; (category ports). Please mention any added or deleted files in the message, as they have to be explicitly specified to CVS 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. Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! <anchor id="porting-dads">Dos and Don'ts 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. Strip Binaries Do strip binaries. If the original source already strips the binaries, fine; otherwise you should add a post-install rule to to it yourself. Here is an example: post-install: strip ${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. 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 compiling ports from 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 FreeBSD 1.x 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 Berkeleyisms, not FreeBSD changes. In FreeBSD 2.x, __FreeBSD__ is defined to be 2. In earlier versions, it is 1. Later versions will 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 3.x 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 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 semctl(2) change + 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 mount(2) change + 3.0-CURRENT before &man.mount.2; change 300000 - 3.0-CURRENT after mount(2) change + 3.0-CURRENT after &man.mount.2; change 300001 - 3.0-CURRENT after semctl(2) change + 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 mkstemps() to libc + 3.3-STABLE after adding &man.mkstemp.3; + to libc 330002 3.4-RELEASE 340000 3.4-STABLE 340001 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 dladdr(3) + 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 suser(9) API change + 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 jail(2) + 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 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 setproctitle() moved from + 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 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 setproctitle() moved from + 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 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. 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. 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 pre.mk/post.mk pair or bsd.port.mk only; do not mix these two. 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, same as __FreeBSD_version. PORTOBJFORMAT The object format of the system (aout or elf) 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 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 to the variable NOPORTDOCS so that users can disable it in /etc/make.conf, like this: post-install: .if !defined(NOPORTDOCS) ${MKDIR} ${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif Do not forget to add them to pkg-plist too. (Do not worry about NOPORTDOCS here; there is currently no way for the packages to read variables from /etc/make.conf.) You can also use the pkg-message file to display messages upon installation. See the using pkg-message section for details. pkg-message does not need to be added to pkg-plist. <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. Package information Do include package information, i.e. pkg-comment, pkg-descr, and pkg-plist. Note that these files are not used only for packaging anymore, and are mandatory now, even if NO_PACKAGE is set. RCS strings 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. Recursive diff Using the recurse () option to diff 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=yes and take the diffs of configure.in. 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. <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).) Not hard-coding /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 isn't 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, making the package creation process will complain that it can't 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 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. 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 bode 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 &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 deinstalled. 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 pkg_delete 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 99 and register it below. Look at japanese/Wnn 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 99. majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh 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:/nonexistent wnn:*:69:7:Wnn:/nonexistent:/nonexistent ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent qmaill:*:83:81:QMail user:/var/qmail:/nonexistent qmaild:*:82:81:QMail user:/var/qmail:/nonexistent qmailq:*:85:82:QMail user:/var/qmail:/nonexistent qmails:*:87:82:QMail user:/var/qmail:/nonexistent qmailp:*:84:81:QMail user:/var/qmail:/nonexistent qmailr:*:86:82:QMail user:/var/qmail:/nonexistent msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent 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}. Respect <makevar>CFLAGS</makevar> The port should respect the CFLAGS variable. 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 pkg_delete 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. Portlint Do check your work with portlint before you submit or commit it. 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. Miscellanea The files pkg-comment, 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 [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. Create an empty pkg-plist. &prompt.root; touch pkg-plist Next, create a new set of directories which your port can be installed, and install any dependencies. &prompt.root; mtree -U -f /etc/mtree/BSD.local.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 * -type d) > OLD-DIRS 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 * \! -type d) > pkg-plist You must also add any newly created directories to the packing list. &prompt.root; (cd /var/tmp/port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' >> pkg-plist Finally, you need to tidy up the packing list by hand; it isn't 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. Package Names 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 lots and lots 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. Categories As you already know, ports are classified in several categories. But for this to work, it is important that porters and users understand what each category is for and how we decide what to put in each category. Current list of categories First, this 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. For non-virtual categories, you will find a one-line description in the pkg/COMMENT file in that subdirectory (e.g., archivers/pkg/COMMENT). Category Description afterstep* Ports to support the AfterStep window manager. 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. 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. 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 GNU Object Model Environment (GNOME) Project. graphics Graphics utilities. hebrew Hebrew language support. irc Internet Relay Chat utilities. ipv6* IPv6 related software. japanese Japanese language support. java Java language support. kde* Ports from the K Desktop Environment (KDE) Project. korean Korean language support. lang Programming languages. linux* Linux applications and support utilities. 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. This is the only category that 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! net Miscellaneous networking software. news USENET news software. offix* Ports from the OffiX suite. palm Software support for the 3Com Palm(tm) series. perl5* Ports that require perl version 5 to run. picobsd Ports to support PicoBSD. plan9* Various programs from Plan9. print Printing software. Desktop publishing tools (previewers, etc.) belong here too. python* Software written in python. ruby* Software written in ruby. russian Russian language support. science Scientific ports that don't 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. 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. 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. If your port is an X application, define USE_XLIB (implied by USE_IMAKE) and put it in the appropriate categories. Also, many of them go into other x11-* categories (see below). 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. 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 win over less-specific ones. For instance, an HTML editor should be listed as www editors, not the other way around. Also, you do not need to list net when the port belongs to any of irc, mail, mbone, news, security, or www. 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. 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 send-pr 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. Changes to this document and the ports system If you maintain a lot of ports, you should consider following the &a.ports;. Important changes to the way ports work will be announced there. You can always find more detailed information on the latest changes by looking at the bsd.port.mk CVS log. That is It, Folks! Boy, this sure was a long tutorial, wasn't it? Thanks for following us to here, really. Now that you know how to do a port, have at it and convert everything in the world into ports! That is the easiest way to start contributing to the FreeBSD Project! :-) diff --git a/en_US.ISO_8859-1/articles/committers-guide/article.sgml b/en_US.ISO_8859-1/articles/committers-guide/article.sgml index b07ee331ff..3dc5bb33e2 100644 --- a/en_US.ISO_8859-1/articles/committers-guide/article.sgml +++ b/en_US.ISO_8859-1/articles/committers-guide/article.sgml @@ -1,2256 +1,2257 @@ %man; %authors; %mailing-lists; ]>
Committer Guide The FreeBSD Documentation Project - $FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.68 2001/05/29 19:29:25 gsutter Exp $ + $FreeBSD: doc/en_US.ISO_8859-1/articles/committers-guide/article.sgml,v 1.69 2001/06/02 05:45:59 dd Exp $ 1999 2000 2001 The FreeBSD Documentation Project This document provides information for the FreeBSD committer community. All new committers should read this document before they start, and existing committers are strongly encouraged to review it from time to time. Administrative Details Main Repository Host freefall.FreeBSD.org Login Methods &man.ssh.1; Main CVSROOT /home/ncvs Main CVS Repository Meisters &a.jdp; and &a.peter; as well as &a.asami; for ports/ Mailing List developers@FreeBSD.org, cvs-committers@FreeBSD.org Noteworthy CVS Tags RELENG_3 (3.x-STABLE), RELENG_4 (4.x-STABLE), HEAD (-CURRENT) It is required that you use &man.ssh.1; or &man.telnet.1; with Kerberos 5 to connect to the repository hosts. These are generally more secure than plain &man.telnet.1; or &man.rlogin.1; since credential negotiation will always be encrypted. All traffic is encrypted by default with &man.ssh.1;. With utilities like &man.ssh-agent.1; and &man.scp.1; also available, &man.ssh.1; is also far more convenient. If you do not know anything about &man.ssh.1;, please see . CVS Operations It is assumed that you are already familiar with the basic operation of CVS. The CVS Repository Meisters (Peter Wemm and John Polstra) are the owners of the CVS repository and are responsible for any and all direct modification of it for the purposes of cleanup or fixing some grievous abuse of CVS by a committer. No one else should attempt to touch the repository directly. Should you cause some repository accident, say a bad cvs import or tag operation, do not attempt to fix it yourself! Mail or call John or Peter immediately and report the problem to one of them instead. The only ones allowed to directly fiddle the repository bits are the repomeisters. Satoshi Asami is also a repomeister for the ports/ portion of the tree. CVS operations are usually done by logging into freefall, making sure the CVSROOT environment variable is set to /home/ncvs, and then doing the appropriate check-out/check-in operations. If you wish to add something which is wholly new (like contrib-ified sources, etc), a script called easy-import is also provided for making the process easier. It automatically adds the new module entry, does the appropriate thing with cvs import, etc. – just run it without arguments and it will prompt you for everything it needs to know. Note that when you use CVS on freefall, you should set your umask to 2, as well as setting the CVSUMASK environment variable to 2. This ensures that any new files created by cvs add will have the correct permissions. If you add a file or directory and discover that the file in the repository has incorrect permissions (specifically, all files in the repository should be group writable by group ncvs), contact one of the repository meisters as described below. If you are familiar with remote CVS and consider yourself pretty studly with CVS in general, you can also do CVS operations directly from your own machine and local working sources. Just remember to set CVS_RSH to ssh so that you are using a relatively secure and reliable transport. If you have no idea what any of the above even means, on the other hand, then please stick with logging into freefall and applying your diffs with &man.patch.1;. If you need to use CVS add and delete operations in a manner that is effectively a mv operation, then a repository copy is in order rather than your CVS add and delete. In a repository copy, a CVS Meister will copy the file(s) to their new name and/or location and let you know when it is done. The purpose of a repository copy is to preserve file change history, or logs. We in the FreeBSD Project greatly value the change history CVS gives to the project. CVS reference information, tutorials, and FAQs can also be found at: http://www.cvshome.org/docs/index.html &a.des; also supplied the following mini primer for CVS. Check out a module with the co or checkout command. &prompt.user; cvs checkout shazam This checks out a copy of the shazam module. If there is no shazam module in the modules file, it looks for a top-level directory named shazam instead. Useful <command>cvs checkout</command> options Don't create empty directories Check out a single level, no subdirectories Check out revision, branch or tag rev Check out the sources as they were on date date
Practical FreeBSD examples: Check out the miscfs module, which corresponds to src/sys/miscfs: &prompt.user; cvs co miscfs You now have a directory named miscfs with subdirectories CVS, deadfs, devfs, and so on. One of these (linprocfs) is empty. Check out the same files, but with full path: &prompt.user; cvs co src/sys/miscfs You now have a directory named src, with subdirectories CVS and sys. src/sys has subdirectories CVS and miscfs, etc. Check out the same files, but prunes empty directories: &prompt.user; cvs co -P miscfs You now have a directory named miscfs with subdirectories CVS, deadfs, devfs... but note that there is no linprocfs subdirectory, because there are no files in it. Check out the directory miscfs, but none of the subdirectories: &prompt.root; cvs co -l miscfs You now have a directory named miscfs with just one subdirectory named CVS. Check out the miscfs module as it is in the 4.x branch: &prompt.user; cvs co -rRELENG_4 miscfs You can modify the sources and commit along this branch. Check out the miscfs module as it was in 3.4-RELEASE. &prompt.user; cvs co -rRELENG_3_4_0_RELEASE miscfs You will not be able to commit modifications, since RELENG_3_4_0_RELEASE is a point in time, not a branch. Check out the miscfs module as it was on Jan 15 2000. &prompt.user; cvs co -D'01/15/2000' miscfs You will not be able to commit modifications. Check out the miscfs module as it was one week agao. &prompt.user; cvs co -D'last week' miscfs You will not be able to commit modifications. Note that cvs stores metadata in subdirectories named CVS. Arguments to and are sticky, which means cvs will remember them later, e.g. when you do a cvs update. Check the status of checked-out files with the status command. &prompt.user; cvs status shazam This displays the status of the shazam file or of every file in the shazam directory. For every file, the status is given as one of: Up-to-date File is up-to-date and unmodified. Needs Patch File is unmodified, but there's a newer revision in the repository. Locally Modified File is up-to-date, but modified. Needs Merge File is modified, and there's a newer revision in the repository. File had conflicts on merge There were conflicts the last time this file was updated, and they haven't been resolved yet. You'll also see the local revision and date, the revision number of the newest applicable version (newest applicable because if you have a sticky date, tag or branch, it may not be the actual newest revision), and any sticky tags, dates or options. Once you've checked something out, update it with the update command. &prompt.user; cvs update shazam This updates the shazam file or the contents of the shazam directory to the latest version along the branch you checked out. If you checked out a point in time, does nothing unless the tags have moved in the repository or some other weird stuff is going on. Useful options, in addition to those listed above for checkout: Check out any additional missing directories. Update to head of main branch. More magic (see below). If you checked out a module with or , running cvs update with a different or argument or with will select a new branch, revision or date. The option clears all sticky tags, dates or revisions whereas and set new ones. Theoretically, specifying HEAD as argument to will give you the same result as , but that's just theory. The option is useful if: somebody has added subdirectories to the module you've checked out after you checked it out. you checked out with , and later change your mind and want to check out the subdirectories as well. you deleted some subdirectories and want to check them all back out. Watch the output of the cvs update with care. The letter in front of each file name indicates what was done with it: U The file was updated with no trouble. P The file was updated with no trouble (you'll only see this when working against a remote repo). M The file had been modified, and was merged with no conflicts. C The file had been modified, and was merged with conflicts. Merging is what happens if you check out a copy of some source code, modify it, then someone else commits a change, and you run cvs update. CVS notices that you've made local changes, and tries to merge your changes with the changes between the version you originally checked out and the one you updated to. If the changed are to separate portions of the file, it'll almost always work fine (though the result might not be syntactically or semantically correct). CVS will print an 'M' in front of every locally modified file even if there is no newer version in the repository, so cvs update is handy for getting a summary of what you've changed locally. If you get a C, then your changes conflicted with the changes in the repository (the changes were to the same lines, or neighboring lines, or you changed the local file so much that cvs can't figure out how to apply the repository's changes). You'll have to go through the file manually and resolve the conflicts; they'll be marked with rows of <, = and > signs. For every conflict, there'll be a marker line with seven < signs and the name of the file, followed by a chunk of what your local file contained, followed by a separator line with seven = signs, followed by the corresponding chunk in the repository version, followed by a marker line with seven > signs and the revision number you updated to. The option is slightly voodoo. It updates the local file to the specified revision as if you used , but it does not change the recorded revision number or branch of the local file. It's not really useful except when used twice, in which case it will merge the changes between the two specified versions into the working copy. For instance, say you commit a change to shazam/shazam.c in -CURRENT and later want to MFC it. The change you want to MFC was revision 1.15: Check out the -STABLE version of the shazam module: &prompt.user; cvs co -rRELENG_4 shazam Apply the changes between rev 1.14 and 1.15: &prompt.user; cvs update -j1.14 -j1.15 shazam/shazam.c You'll almost certainly get a conflict because - of the $Id: article.sgml,v 1.69 2001-06-02 05:45:59 dd Exp $ (or in FreeBSD's case, + of the $Id: article.sgml,v 1.70 2001-06-03 21:39:50 dd Exp $ (or in FreeBSD's case, $FreeBSD$) lines, so you'll have to edit the file to resolve the conflict (remove the marker lines and - the second $Id: article.sgml,v 1.69 2001-06-02 05:45:59 dd Exp $ line, leaving the original - $Id: article.sgml,v 1.69 2001-06-02 05:45:59 dd Exp $ line intact). + the second $Id: article.sgml,v 1.70 2001-06-03 21:39:50 dd Exp $ line, leaving the original + $Id: article.sgml,v 1.70 2001-06-03 21:39:50 dd Exp $ line intact). View differences between the local version and the repository version with the diff command. &prompt.user; cvs diff shazam shows you every modification you've made to the shazam file or module. Useful <command>cvs diff</command> options Uses the unified diff format. Shows missing or added files.
You always want to use , since unified diffs are much easier to read than almost any other diff format (in some circumstances, context diffs may be better, but they're much bulkier). A unified diff consists of a series of hunks. Each hunk begins with a line that starts with two @ signs and specifies where in the file the differences are and how many lines they span. This is followed by a number of lines; some (preceded by a blank) are context; some (preceded by a - sign) are outtakes and some (preceded by a +) are additions. You can also diff against a different version than the one you checked out by specifying a version with or as in checkout or update, or even view the diffs between two arbitrary versions (with no regard for what you have locally) by specifying two versions with or . View log entries with the log command. &prompt.user; cvs log shazam See who did what with the annotate command. This command shows you each line of the specified file or files, along with which user most recently changed that line. &prompt.user; cvs annotate shazam Add new files with the add command. Create the file, cvs add it, then cvs commit it. Similarly, you can add new directories by creating them and then cvs adding them. Note that you don't need to commit directories. Remove obsolete files with the remove command. Remove the file, then cvs rm it, then cvs commit it. Commit with the commit or checkin command. Useful <command>cvs commit</command> options Force a commit of an unmodified file. Specify a commit message on the command line rather than invoking an editor.
Use the option if you realize that you left out important information from the commit message. Good commit messages are important. They tell others why you did the changes you did, not just right here and now, but months or years from now when someone wonders why some seemingly illogical or inefficient piece of code snuck into your source file. It's also an invaluable aid to deciding which changes to MFC and which not to MFC. Don't waste space in the commit messages explaining what you did. That's what cvs diff is for. Instead, tell us why you did it. Avoid committing several unrelated changes in one go. It makes merging difficult, and also makes it harder to determine which change is the culprit if a bug crops up. Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made. Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small groups of files) with tailored commit messages. Before committing, always: verify which branch you're committing to, using cvs status. review your diffs, using cvs diff Also, ALWAYS specify which files to commit explicitly on the command line, so you don't accidentally commit other files than the ones you intended - cvs commit with no arguments will commit every modification in your current working directory and every subdirectory. Additional tips and tricks: You can place commonly used options in your ~/.cvsrc, like this: cvs -z3 diff -Nu update -Pd checkout -P This example says: always use compression level 3 when talking to a remote server. This is a life-saver when working over a slow connection. always use the (show added or removed files) and (unified diff format) options to &man.diff.1;. always use the (prune empty directories) and (check out new directories) options when updating. always use the (prune empty directories) option when checking out. Use Eivind Eklund's cdiff script to view unidiffs. It's a wrapper for &man.less.1; that adds ANSI color codes to make hunk headers, outtakes and additions stand out; context and garbage are unmodified. It also expands tabs properly (tabs often look wrong in diffs because of the extra character in front of each line). http://people.FreeBSD.org/~eivind/cdiff Simply use it instead of &man.more.1; or &man.less.1;: &prompt.user; cvs diff -Nu shazam | cdiff Alternatively some editors like &man.vim.1; (ports/editors/vim5) have color support and when used as a pager with color syntax highlighting switched on will highlight many types of file, including diffs, patches, and cvs/rcs logs. &prompt.user; echo "syn on" >> ~/.vimrc &prompt.user; cvs diff -Nu shazam | vim - &prompt.user; cvs log shazam | vim - CVS is old, arcane, crufty and buggy, and sometimes exhibits non-deterministic behavior which some claim as proof that it's actually merely the Newtonian manifestation of a sentient transdimensional entity. It's not humanly possible to know its every quirk inside out, so don't be afraid to ask the resident AI (cvs@FreeBSD.org) for help when you screw up. Don't leave the cvs commit command in commit message editing mode for too long (more than 2-3 minutes). It locks the directory you are working with and will prevent other developers from committing into the same directory. If you have to type a long commit message, type it before executing cvs commit, and insert it into the commit message. Conventions and Traditions As a new committer there are a number of things you should do first. Add yourself to the Developers section of the Handbook and remove yourself from the Additional Contributors section. This is a relatively easy task, but remains a good first test of your CVS skills. Add an entry for yourself to www/en/news/newsflash.sgml. Look for the other entries that look like A new committer and follow the format. If you have a PGP or GnuPG key, you may want to add it to doc/en_US.ISO_8859-1/books/handbook/pgpkeys. Some people also add an entry for themselves to ports/astro/xearth/files/freebsd.committers.markers. Introduce yourself to the other committers, otherwise no one will have any idea who you are or what you are working on. You do not have to write a comprehensive biography, just write a paragraph or two about who you are and what you plan to be working on as a committer in FreeBSD. Email this to developers@FreeBSD.org and you will be on your way! Log into hub.FreeBSD.org and create a /var/forward/user (where user is your username) file containing the e-mail address where you want mail addressed to yourusername@FreeBSD.org to be forwarded. This includes all of the commit messages as well as any other mail addressed to cvs-committers@FreeBSD.org and developers@FreeBSD.org. Really large mailboxes which have taken up permanent residence on hub often get accidently truncated without warning, so forward it or read it and you will not lose it. All new committers also have a mentor assigned to them for the first few months. Your mentor is more or less responsible for explaining anything which is confusing to you and is also responsible for your actions during this initial period. If you make a bogus commit, it is only going to embarrass your mentor and you should probably make it a policy to pass at least your first few commits by your mentor before committing it to the repository. All commits should go to -CURRENT first before being merged to -STABLE. No major new features or high-risk modifications should be made to the -STABLE branch. Developer Relations If you are working directly on your own code or on code which is already well established as your responsibility, then there is probably little need to check with other committers before jumping in with a commit. If you see a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. If, however, you are about to modify something which is clearly being actively maintained by someone else (and it is only by watching the cvs-committers mailing list that you can really get a feel for just what is and is not) then consider sending the change to them instead, just as you would have before becoming a committer. For ports, you should contact the listed MAINTAINER in the Makefile. For other parts of the repository, if you are unsure who the active maintainer might be, it may help to scan the output of cvs log to see who has committed changes in the past. &a.fenner; has written a nice shell script that can help determine who the active maintainer might be. It lists each person who has committed to a given file along with the number of commits each person has made. It can be found on freefall at ~fenner/bin/whodid. If your queries go unanswered or the committer otherwise indicates a lack of proprietary interest in the area affected, go ahead and commit it. If you are unsure about a commit for any reason at all, have it reviewed by -hackers before committing. Better to have it flamed then and there rather than when it is part of the CVS repository. If you do happen to commit something which results in controversy erupting, you may also wish to consider backing the change out again until the matter is settled. Remember – with CVS we can always change it back. GNATS The FreeBSD Project utilizes GNATS for tracking bugs and change requests. Be sure that if you commit a fix or suggestion found in a GNATS PR, you use edit-pr pr-number on freefall to close it. It is also considered nice if you take time to close any PRs associated with your commits, if appropriate. You can also make use of &man.send-pr.1; yourself for proposing any change which you feel should probably be made, pending a more extensive peer-review first. You can find out more about GNATS at: http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html http://www.FreeBSD.org/support.html http://www.FreeBSD.org/send-pr.html &man.send-pr.1; You can run a local copy of GNATS, and then integrate the FreeBSD GNATS tree in to it using CVSup. Then you can run GNATS commands locally, or use other interfaces, such as tkgnats. This lets you query the PR database without needing to be connected to the Internet. Using a local GNATS tree If you are not already downloading the GNATS tree, add this line to your supfile, and re-sup. Note that since GNATS is not under CVS control it has no tag, so if you are adding it to your existing supfile it should appear before any tag= entry as these remain active once set. gnats release=current prefix=/usr This will place the FreeBSD GNATS tree in /usr/gnats. You can use a refuse file to control which categories to receive. For example, to only receive docs PRs, put this line in /usr/local/etc/cvsup/sup/refuse The precise path depends on the *default base setting in your supfile. . gnats/[a-ce-z]* The rest of these examples assume you have only supped the docs category. Adjust them as necessary, depending on the categories you are synching. Install the GNATS port from ports/databases/gnats. This will place the various GNATS directories under $PREFIX/share/gnats. Symlink the GNATS directories you are supping under the version of GNATS you have installed. &prompt.root; cd /usr/local/share/gnats/gnats-db &prompt.root; ln -s /usr/gnats/docs Repeat as necessary, depending on how many GNATS categories you are synching. Update the GNATS categories file with these categories. The file is $PREFIX/share/gnats/gnats-db/gnats-adm/categories. # This category is mandatory pending:Category for faulty PRs:gnats-admin: # # FreeBSD categories # docs:Documentation Bug:nik: Run $PREFIX/libexec/gnats/gen-index to recreate the GNATS index. The output has to be redirected to $PREFIX/share/gnats/gnats-db/gnats-adm/index. You can do this periodically from &man.cron.8;, or run &man.cvsup.1; from a shell script that does this as well. &prompt.root; /usr/local/libexec/gnats/gen-index \ > /usr/local/share/gnats/gnats-db/gnats-adm/index Test the configuration by querying the PR database. This command shows open docs PRs. &prompt.root; query-pr -c docs -s open Other interfaces, like ports/databases/tkgnats should also work nicely. Pick a PR and close it. This procedure only works to allow you to view and query the PRs locally. To edit or close them you will still have to log in to freefall and do it from there. Who's Who Besides Peter Wemm and John Polstra, the repository meisters, there are other FreeBSD project members whom you will probably get to know in your role as a committer. Briefly, and by no means all-inclusively, these are: &a.asami; Satoshi is the Ports Wraith, meaning that he has ultimate authority over any modifications to the ports collection or the ports skeleton makefiles. He is also the one responsible for administering ports freezes before the releases. &a.ru; - Ruslan is Mr mdoc(7). If you are writing a man page and need + Ruslan is Mister &man.mdoc.7;. If you are writing a + man page and need some advice on the structure, or the markup, ask Ruslan. &a.bde; Bruce is the Style Police-Meister. When you do a commit that could have been done better, Bruce will be there to tell you. Be thankful that someone is. Bruce is also very knowledgeable on the various standards applicable to FreeBSD. &a.gallatin; &a.mjacob; &a.dfr; &a.obrien; These are the primary developers and overseers of the DEC Alpha AXP platform. &a.dg; David is the overseer of the VM system. If you have a VM system change in mind, coordinate it with David. &a.jkh; Jordan is the release engineer. He is responsible for setting release deadlines and controlling the release process. During code freezes, he also has final authority on all changes to the system for whichever branch is pending release status. If there is something you want merged from -CURRENT to -STABLE (whatever values those may have at any given time), he is also the one to talk to about it. &a.bmah; Bruce is keeper of the release notes (src/release/texts/* or src/release/doc/*, as appropriate). If you commit a change that you think is worthy of mention in the release notes, please make sure Bruce knows about it. Better still, send him a patch with your suggested commentary for the release notes. &a.obrien; David is the unofficial src/contrib-Meister. If you have something significant you'd like to do there, you should probably coordinate it with David first. Please consult him before importing into src/contrib if you have never done this before in the FreeBSD CVS repository. Also if you need to commit to something you do not maintain in src/contrib and it is unclear who the maintainer / point of contact is. (It is also not a bad idea to consult David if you need to make a non-import commit to something you maintain in src/contrib and you are new to how FreeBSD does things.) &a.brian; Official maintainer of /usr/sbin/ppp. &a.wollman; If you need advice on obscure network internals or aren't sure of some potential change to the networking subsystem you have in mind, Garrett is someone to talk to. Garrett is also very knowledgeable on the various standards applicable to FreeBSD. &a.committers; cvs-committers is the entity that CVS uses to send you all your commit messages. You should never send email directly to this list. You should only send replies to this list when they are short and are directly related to a commit. &a.developers; developers is all committers. This list was created to be a forum for the committers "community" issues. Examples are Core voting, announcements, etc... developers@FreeBSD.org is not intended as a place for code reviews or a replacement for arch@FreeBSD.org or audit@FreeBSD.org. In fact using it as such hurts the FreeBSD Project as it gives a sense of a closed list where general decisions affecting all of the FreeBSD using community are made with out being "open". SSH Quick-Start Guide If you are using FreeBSD 4.0 or later, OpenSSH is included in the base system. If you are using an earlier release, update and install one of the SSH ports. In general, you will probably want to get OpenSSH from the port in /usr/ports/security/openssh. You may also wish to check out the original ssh1 in /usr/ports/security/ssh, but make certain you pay attention to its license. Note that both of these ports cannot be installed at the same time. If you do not wish to type your password in every time you use &man.ssh.1;, and you use RSA keys to authenticate, &man.ssh-agent.1; is there for your convenience. If you want to use &man.ssh-agent.1;, make sure that you run it before running other applications. X users, for example, usually do this from their .xsession or .xinitrc file. See &man.ssh-agent.1; for details. Generate a key pair using &man.ssh-keygen.1;. The key pair will wind up in the $HOME/.ssh directory. Send your public key ($HOME/.ssh/identity.pub) to the person setting you up as a committer so it can be put into your authorized_keys file in your home directory on freefall (i.e. $HOME/.ssh/authorized_keys). Now you should be able to use &man.ssh-add.1; for authentication once per session. This will prompt you for your private key's pass phrase, and then store it in your authentication agent (&man.ssh-agent.1;). If you no longer wish to have your key stored in the agent, issuing ssh-add -d will remove it. Test by doing something such as ssh freefall.FreeBSD.org ls /usr. For more information, see /usr/ports/security/openssh, &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and &man.scp.1;. The FreeBSD Committers' Big List of Rules Respect other committers. Respect other contributors. Discuss any significant change before committing. Respect existing maintainers (if listed in the MAINTAINER field in Makefile or in the MAINTAINER file in the top-level directory). Never touch the repository directly. Ask a Repomeister. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion. Changes go to -CURRENT before -STABLE unless specifically permitted by the release engineer or unless they're not applicable to -CURRENT. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in -CURRENT for at least 3 days before merging so that it can be given sufficient testing. The release engineer has the same authority over the -STABLE branch as outlined for the maintainer in rule #5. Don't fight in public with other committers; it looks bad. If you must strongly disagree about something, do so only in private. Respect all code freezes and read the committers mailing list in a timely manner so you know when a code freeze is in effect. When in doubt on any procedure, ask first! Test your changes before committing them. Don't commit to anything under the src/contrib, src/crypto, and src/sys/contrib trees without explicit approval from the respective maintainer(s). As noted, breaking some of these rules can be grounds for suspension or, upon repeated offense, permanent removal of commit privileges. Three or more members of core acting in unison, have the power to temporarily suspend commit privileges until -core as a whole has the chance to review the issue. In case of an emergency (a committer doing damage to the repository), a temporary suspension may also be done by the repository meisters or any other member of core who may happen to be awake at the time. Only core as a whole has the authority to suspend commit privileges for any significant length of time or to remove them permanently, the latter generally only being done after consultation with committers. This rule does not exist to set core up as a bunch of cruel dictators who can dispose of committers as casually as empty soda cans, but to give the project a kind of safety fuse. If someone is seriously out of control, it's important to be able to deal with this immediately rather than be paralyzed by debate. In all cases, a committer whose privileges are suspended or revoked is entitled to a hearing, the total duration of the suspension being determined at that time. A committer whose privileges are suspended may also request a review of the decision after 30 days and every 30 days thereafter (unless the total suspension period is less than 30 days). A committer whose privileges have been revoked entirely may request a review after a period of 6 months have elapsed. This review policy is strictly informal and, in all cases, core reserves the right to either act on or disregard requests for review if they feel their original decision to be the right one. In all other aspects of project operation, core is a subset of committers and is bound by the same rules. Just because someone is in core doesn't mean that they have special dispensation to step outside of any of the lines painted here; core's special powers only kick in when it acts as a group, not on an individual basis. As individuals, we are all committers first and core second. Details Respect other committers. This means that you need to treat other committers as the peer-group developers that they are. Despite our occasional attempts to prove the contrary, one doesn't get into committers by being stupid and nothing rankles more than being treated that way by one of your peers. Whether we always feel respect for one another or not (and everyone has off days), we still have to treat other committers with respect at all times or the whole team structure rapidly breaks down. Being able to work together long term is this project's greatest asset, one far more important than any set of changes to the code, and turning arguments about code into issues that affect our long-term ability to work harmoniously together is just not worth the trade-off by any conceivable stretch of the imagination. To comply with this rule, don't send email when you're angry or otherwise behave in a manner which is likely to strike others as needlessly confrontational. First calm down, then think about how to communicate in the most effective fashion for convincing the other person(s) that your side of the argument is correct, don't just blow off some steam so you can feel better in the short term at the cost of a long-term flame war. Not only is this very bad energy economics, but repeated displays of public aggression which impair our ability to work well together will be dealt with severely by the project leadership and may result in suspension or termination of your commit privileges. That's never an option which the project's leadership enjoys in the slightest, but unity comes first. No amount of code or good advice is worth trading that away. Respect other contributors. You weren't always a committer. At one time you were a contributor. Remember that at all times. Remember what it was like trying to get help and attention. Don't forget that your work as a contributor time was very important to you. Remember what it was like. Don't discourage, belittle, or demean contributors. Treat them with respect. They are our committers in waiting. They are every bit as important to the project as committers. Their contributions are as valid and as important as your own. After all, you made many contributions before you became a committer. Always remember that. Consider the points raised under 'Respect other committers' and apply them also to contributors. Discuss any significant change before committing. The CVS repository is not where changes should be initially submitted for correctness or argued over, that should happen first in the mailing lists and then committed only once something resembling consensus has been reached. This doesn't mean that you have to ask permission before correcting every obvious syntax error or man page misspelling, simply that you should try to develop a feel for when a proposed change isn't quite such a no-brainer and requires some feedback first. People really don't mind sweeping changes if the result is something clearly better than what they had before, they just don't like being surprised by those changes. The very best way of making sure that you're on the right track is to have your code reviewed by one or more other committers. When in doubt, ask for review! Respect existing maintainers if listed. Many parts of FreeBSD aren't owned in the sense that any specific individual will jump up and yell if you commit a change to their area, but it still pays to check first. One convention we use is to put a maintainer line in the Makefile for any package or subtree which is being actively maintained by one or more people; see http://www.FreeBSD.org/handbook/policies.html for documentation on this. Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer. In cases where the maintainer-ship of something isn't clear, you can also look at the CVS logs for the file(s) in question and see if someone has been working recently or predominantly in that area. Other areas of FreeBSD fall under the control of someone who manages an overall category of FreeBSD evolution, such as internationalization or networking. See http://www.FreeBSD.org/handbook/staff-who.html for more information on this. Never touch the repository directly. Ask a Repomeister. This is pretty clear - you're not allowed to make direct modifications to the CVS repository, period. In case of difficulty, ask one of the repository meisters by sending mail to cvs@FreeBSD.org and simply wait for them to fix the problem and get back to you. Do not attempt to fix the problem yourself! If you're thinking about putting down a tag or doing a new import of code on a vendor branch, you might also find it useful to ask for advice first. A lot of people get this wrong the first few times and the consequences are expensive in terms of files touched and angry CVSup/CTM folks who are suddenly getting a lot of changes sent over unnecessarily. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer Security related changes may override a maintainer's wishes at the Security Officer's discretion. This may be hard to swallow in times of conflict (when each side is convinced that they're in the right, of course) but CVS makes it unnecessary to have an ongoing dispute raging when it's far easier to simply reverse the disputed change, get everyone calmed down again and then try and figure out how best to proceed. If the change turns out to be the best thing after all, it can be easily brought back. If it turns out not to be, then the users didn't have to live with the bogus change in the tree while everyone was busily debating its merits. People very very rarely call for back-outs in the repository since discussion generally exposes bad or controversial changes before the commit even happens, but on such rare occasions the back-out should be done without argument so that we can get immediately on to the topic of figuring out whether it was bogus or not. Changes go to -CURRENT before -STABLE unless specifically permitted by the release engineer or unless they're not applicable to -CURRENT. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in -CURRENT for at least 3 days before merging so that it can be given sufficient testing. The release engineer has the same authority over the -STABLE branch as outlined in rule #5. This is another don't argue about it issue since it's the release engineer who is ultimately responsible (and gets beaten up) if a change turns out to be bad. Please respect this and give the release engineer your full cooperation when it comes to the -STABLE branch. The management of -STABLE may frequently seem to be overly conservative to the casual observer, but also bear in mind the fact that conservatism is supposed to be the hallmark of -STABLE and different rules apply there than in -CURRENT. There's also really no point in having -CURRENT be a testing ground if changes are merged over to -STABLE immediately. Changes need a chance to be tested by the -CURRENT developers, so allow some time to elapse before merging unless the -STABLE fix is critical, time sensitive or so obvious as to make further testing unnecessary (spelling fixes to manpages, obvious bug/typo fixes, etc.) In other words, apply common sense. Don't fight in public with other committers; it looks bad. If you must strongly disagree about something, do so only in private. This project has a public image to uphold and that image is very important to all of us, especially if we are to continue to attract new members. There will be occasions when, despite everyone's very best attempts at self-control, tempers are lost and angry words are exchanged, and the best we can do is try and minimize the effects of this until everyone has cooled back down. That means that you should not air your angry words in public and you should not forward private correspondence to public mailing lists or aliases. What people say one-to-one is often much less sugar-coated than what they would say in public, and such communications therefore have no place there - they only serve to inflame an already bad situation. If the person sending you a flame-o-gram at least had the grace to send it privately, then have the grace to keep it private yourself. If you feel you are being unfairly treated by another developer, and it is causing you anguish, bring the matter up with core rather than taking it public. We will do our best to play peace makers and get things back to sanity. In cases where the dispute involves a change to the codebase and the participants do not appear to be reaching an amicable agreement, core may appoint a mutually-agreeable 3rd party to resolve the dispute. All parties involved must then agree to be bound by the decision reached by this 3rd party. Respect all code freezes and read the committers mailing list on a timely basis so you know when they are. Committing changes during a code freeze is a really big mistake and committers are expected to keep up-to-date on what's going on before jumping in after a long absence and committing 10 megabytes worth of accumulated stuff. People who abuse this on a regular basis will have their commit privileges suspended until they get back from the FreeBSD Happy Reeducation Camp we run in Greenland. When in doubt on any procedure, ask first! Many mistakes are made because someone is in a hurry and just assumes they know the right way of doing something. If you have not done it before, chances are good that you do not actually know the way we do things and really need to ask first or you are going to completely embarrass yourself in public. There's no shame in asking how in the heck do I do this? We already know you are an intelligent person; otherwise, you would not be a committer. Test your changes before committing them. This may sound obvious, but if it really were so obvious then we probably wouldn't see so many cases of people clearly not doing this. If your changes are to the kernel, make sure you can still compile both GENERIC and LINT. If your changes are anywhere else, make sure you can still make world. If your changes are to a branch, make sure your testing occurs with a machine which is running that code. If you have a change which also may break another architecture, be sure and test on all supported architectures. Currently, this is only the x86 and the Alpha so it's pretty easy to do. If you need to test on the AXP, your account on beast.FreeBSD.org will let you compile and test Alpha binaries/kernels/etc. As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available. Don't commit to anything under the src/contrib, src/crypto, and src/sys/contrib trees without explicit approval from the respective maintainer(s). The trees mentioned above are for contributed software usually imported onto a vendor branch. Committing something there, even if it doesn't take the file off the vendor branch, may cause unnecessary headaches for those responsible for maintaining that particular piece of software. Thus, unless you have explicit approval from the maintainer (or you are the maintainer), do not commit there! Please note that this doesn't mean you shouldn't try to improve the software in question; you are still more than welcome to do so. Ideally, you should submit your patches to the vendor. If your changes are FreeBSD-specific, talk to the maintainer; they may be willing to apply them locally. But whatever you do, do not commit there by yourself! Contact the &a.core; if you wish to take up maintainership of an unmaintained part of the tree. Other Suggestions When committing documentation changes, use a spell checker before committing. :) For all SGML docs, you should also verify that your formatting directives are correct by running make lint. For all on-line manual pages, run manck (from ports) over the man page to verify all of the cross references and file references are correct and that the man page has all of the appropriate MLINKs installed. Do not mix style fixes with new functionality. A style fix is any change which does not modify the functionality of the code. Mixing the changes obfuscates the functionality change when using cvs diff, which can hide any new bugs. Do not include whitespace changes with content changes in commits to doc/ or www/. The extra clutter in the diffs makes the translators' job much more difficult. Instead, make any style or whitespace changes in separate commits that are clearly labeled as such in the commit message. Ports Specific FAQ Adding a New Port How do I add a new port? First, please read the section about repository copy. The easiest way to add a new port is to use the addport script on freefall. It will add a port from the directory you specify, determining the category automatically from the port Makefile. It will also add an entry to the CVSROOT/modules file and the port's category Makefile. It was written by &a.mharo; and &a.will;, but Will is the current maintainer so please send questions/patches about addport to him. Any other things I need to know when I add a new port? Check the port, preferably to make sure it compiles and packages correctly. This is the recommended sequence: &prompt.root; make install &prompt.root; make package &prompt.root; make deinstall &prompt.root; pkg_add package you built above &prompt.root; make deinstall &prompt.root; make reinstall &prompt.root; make package The Porters Handbook contains more detailed instructions. Use &man.portlint.1; to check the syntax of the port. You don't necessarily have to eliminate all warnings but make sure you have fixed the simple ones. If the port came from a submitter who has not contributed to the project before, add that person's name to the Handbook's Additional Contributors section. Close the PR if the port came in as a PR. To close a PR, just do edit-pr PR# on freefall and change the state from open to closed. You will be asked to enter a log message and then you are done. Repository Copies When do we need a repository copy? When you want to add a port that is related to any port that is already in the tree in a separate directory, please send mail to the ports manager asking about it. Here related means it is a different version or a slightly modified version. Examples are print/ghostscript* (different versions) and x11-wm/windowmaker* (English-only and internationalized version). Another example is when a port is moved from one subdirectory to another, or when you want to change the name of a directory because the author(s) renamed their software even though it is a descendant of a port already in a tree. When do we not need a repository copy? When there is no history to preserve. If a port is added into a wrong category and is moved immediately, it suffices to simply cvs remove the old one and addport the new one. What do I need to do? Send mail to the ports manager, who will do a copy from the old location/name to the new location/name. You will then get a notice, at which point you are expected to perform the following: cvs remove the old port (if necessary) Adjust the parent (category) Makefile Update CVSROOT/modules If other ports depend on the updated port, change their Makefiles' dependency lines If the port changed categories, modify the CATEGORIES line of the port's Makefile accordingly Ports Freeze What is a ports freeze? Before a release, it is necessary to restrict commits to the ports tree for a short period of time while the packages and the release itself are being built. This is to ensure consistency among the various parts of the release, and is called the ports freeze. How long is a ports freeze? Usually an hour or two. What does it mean to me? During the ports freeze, you are not allowed to commit anything to the tree without explicit approval from the ports manager. Explicit approval here means either of the following: You asked the ports manager and got a reply saying, Go ahead and commit it. The ports manager sent a mail to you or the mailing lists during the ports freeze pointing out that the port is broken and has to be fixed. Note that you do not have implicit permission to fix a port during the freeze just because it is broken. How do I know when the ports freeze starts? The ports manager will send out warning messages to the freebsd-ports@FreeBSD.org and cvs-committers@FreeBSD.org mailing lists announcing the start of the impending release, usually two or three weeks in advance. The exact starting time will not be determined until a few days before the actual release. This is because the ports freeze has to be synchronized with the release, and it is usually not known until then when exactly the release will be rolled. When the freeze starts, there will be another announcement to the cvs-committers@FreeBSD.org list, of course. How do I know when the ports freeze ends? A few hours after the release, the ports manager will send out a mail to the freebsd-ports@FreeBSD.org and cvs-committers@FreeBSD.org mailing lists announcing the end of the ports freeze. Note that the release being cut does not automatically end the freeze. We have to make sure there will not be any last minute snafus that result in an immediate re-rolling of the release. Miscellaneous Questions How do I know if my port is building correctly or not? First, go check http://bento.FreeBSD.org/~asami/errorlogs/. There you will find error logs from the latest package building runs on 3-stable, 4-stable and 5-current. However, just because the port doesn't show up there doesn't mean it's building correctly. (One of the dependencies may have failed, for instance.) Here are the relevant directories on bento, so feel free to dig around. /a/asami/portbuild/3/errors error logs from latest 3-stable run /logs all logs from latest 3-stable run /packages packages from latest 3-stable run /bak/errors error logs from last complete 3-stable run /bak/logs all logs from last complete 3-stable run /bak/packages packages from last complete 3-stable run /4/errors error logs from latest 4-stable run /logs all logs from latest 4-stable run /packages packages from latest 4-stable run /bak/errors error logs from last complete 4-stable run /bak/logs all logs from last complete 4-stable run /bak/packages packages from last complete 4-stable run /5/errors error logs from latest 5-current run /logs all logs from latest 5-current run /packages packages from latest 5-current run /bak/errors error logs from last complete 5-current run /bak/logs all logs from last complete 5-current run /bak/packages packages from last complete 5-current run Basically, if the port shows up in packages, or it is in logs but not in errors, it built fine. (The errors directories are what you get from the web page.) I added a new port. Do I need to add it to the INDEX? No. The ports manager will regenerate the INDEX and commit it every few days. Are there any other files I'm not allowed to touch? Any file directly under ports/, or any file under a subdirectory that starts with an uppercase letter (Mk/, Tools/, etc.). In particular, the ports manager is very protective of ports/Mk/bsd.port*.mk so don't commit changes to those files unless you want to face his wra(i)th. Miscellaneous Questions Why are trivial or cosmetic changes to files on a vendor branch a bad idea? From now on, every new vendor release of that file will need to have patches merged in by hand. From now on, every new vendor release of that file will need to have patches verified by hand. The option doesn't work very well. Ask &a.obrien; for horror stories. How do I add a new file to a CVS branch? To add a file onto a branch, simply checkout or update to the branch you want to add to and then add the file using cvs add as you normally would. For example, if you wanted to MFC the file src/sys/alpha/include/smp.h from HEAD to RELENG_4 and it does not exist in RELENG_4 yet, you would use the following steps: MFC'ing a New File &prompt.user; cd sys/alpha/include &prompt.user; cvs update -rRELENG_4 cvs update: Updating . U clockvar.h U console.h ... &prompt.user; cvs update -kk -Ap smp.h > smp.h =================================================================== Checking out smp.h RCS: /usr/cvs/src/sys/alpha/include/smp.h,v VERS: 1.1 *************** &prompt.user; cvs add smp.h cvs add: scheduling file `smp.h' for addition on branch `RELENG_4' cvs add: use 'cvs commit' to add this file permanently &prompt.user; cvs commit What meta information should I include in a commit message? As well as including an informative message with each commit you may need to include some additional information as well. This information consists of one or more lines containing the the key word or phrase, a colon, tabs for formatting, and then the additional information. The key words or phrases are: PR: The problem report (if any) which is affected (typically, by being closed) by this commit. Submitted by: The name and e-mail address of the person that submitted the fix. Reviewed by: The name and e-mail address of the person or people that reviewed the change. If a patch was submitted to a mailing list for review, and the review was favourable, then just include the list name. Approved by: The name and e-mail address of the person or people that approved the change. It is customary to get prior approval for a commit if it is to an area of the tree to which you do not usually commit. In addition, during the run up to a new release all commits must be approved by the release engineer. If these are your first commits then you should have passed them past your mentor first for approval, and you should list your mentor. Obtained from: The name of the project (if any) from which the code was obtained. Commit log for a commit based on a PR You want to commit a change based on a PR submitted by John Smith containing a patch. The end of the commit message should look something like this. ... PR: foo/12345 Submitted by: John Smith <John.Smith@example.com> Commit log for a commit needing review You want to change the virtual memory system. You have posted patches to the appropriate mailing list (in this case, freebsd-arch) and the changes have been approved. ... Reviewed by: -arch Commit log for a commit needing approval You want to commit a change to a section of the tree with a MAINTAINER assigned. You have collaborated with the listed MAINTAINER, who has told you to go ahead and commit. ... Approved by: abc Where abc is the account name of the person who approved. Commit log for a commit bringing in code from OpenBSD You want to commit some code based on work done in the OpenBSD project. ... Obtained from: OpenBSD In some cases you may need to combine some of these. Consider the situation where a user has submitted a PR containing code from the NetBSD project. You are looking at the PR, but it's not an area of the tree you normally work in, so you've decided to get the change reviewed by the arch mailing list. The extra information to include in the commit would look something like PR: foo/54321 Submitted by: John Smith <John.Smith@example.com> Reviewed by: -arch Obtained from: NetBSD
diff --git a/en_US.ISO_8859-1/books/handbook/security/chapter.sgml b/en_US.ISO_8859-1/books/handbook/security/chapter.sgml index 8f037fafe4..c6836a8c5c 100644 --- a/en_US.ISO_8859-1/books/handbook/security/chapter.sgml +++ b/en_US.ISO_8859-1/books/handbook/security/chapter.sgml @@ -1,2906 +1,2906 @@ Security Much of this chapter has been taken from the &man.security.7; man page, originally written by &a.dillon;. Synopsis The following chapter will provide a basic introduction to system security concepts, some general good rules of thumb, and some advanced topics such as S/Key, OpenSSL, Kerberos, and others. Introduction Security is a function that begins and ends with the system administrator. While all BSD UNIX multi-user systems have some inherent security, the job of building and maintaining additional security mechanisms to keep those users honest is probably one of the single largest undertakings of the sysadmin. Machines are only as secure as you make them, and security concerns are ever competing with the human necessity for convenience. UNIX systems, in general, are capable of running a huge number of simultaneous processes and many of these processes operate as servers – meaning that external entities can connect and talk to them. As yesterday's mini-computers and mainframes become today's desktops, and as computers become networked and internetworked, security becomes an ever bigger issue. Security is best implemented through a layered onion approach. In a nutshell, what you want to do is to create as many layers of security as are convenient and then carefully monitor the system for intrusions. You do not want to overbuild your security or you will interfere with the detection side, and detection is one of the single most important aspects of any security mechanism. For example, it makes little sense to set the schg flags (see &man.chflags.1;) on every system binary because while this may temporarily protect the binaries, it prevents an attacker who has broken in from making an easily detectable change that may result in your security mechanisms not detecting the attacker at all. System security also pertains to dealing with various forms of attack, including attacks that attempt to crash or otherwise make a system unusable but do not attempt to break root. Security concerns can be split up into several categories: Denial of service attacks. User account compromises. Root compromise through accessible servers. Root compromise via user accounts. Backdoor creation. A denial of service attack is an action that deprives the machine of needed resources. Typically, D.O.S. attacks are brute-force mechanisms that attempt to crash or otherwise make a machine unusable by overwhelming its servers or network stack. Some D.O.S. attacks try to take advantages of bugs in the networking stack to crash a machine with a single packet. The latter can only be fixed by applying a bug fix to the kernel. Attacks on servers can often be fixed by properly specifying options to limit the load the servers incur on the system under adverse conditions. Brute-force network attacks are harder to deal with. A spoofed-packet attack, for example, is nearly impossible to stop short of cutting your system off from the internet. It may not be able to take your machine down, but it can fill up internet pipe. A user account compromise is even more common then a D.O.S. attack. Many sysadmins still run standard telnetd, rlogind, rshd, and ftpd servers on their machines. These servers, by default, do not operate over encrypted connections. The result is that if you have any moderate-sized user base, one or more of your users logging into your system from a remote location (which is the most common and convenient way to login to a system) will have his or her password sniffed. The attentive system admin will analyze his remote access logs looking for suspicious source addresses even for successful logins. One must always assume that once an attacker has access to a user account, the attacker can break root. However, the reality is that in a well secured and maintained system, access to a user account does not necessarily give the attacker access to root. The distinction is important because without access to root the attacker cannot generally hide his tracks and may, at best, be able to do nothing more then mess with the user's files or crash the machine. User account compromises are very common because users tend not to take the precautions that sysadmins take. System administrators must keep in mind that there are potentially many ways to break root on a machine. The attacker may know the root password, the attacker may find a bug in a root-run server and be able to break root over a network connection to that server, or the attacker may know of a bug in an suid-root program that allows the attacker to break root once he has broken into a user's account. If an attacker has found a a way to break root on a machine, the attacker may not have a need to install a backdoor. Many of the root holes found and closed to date involve a considerable amount of work by the attacker to cleanup after himself, so most attackers install backdoors. Backdoors provide the attacker with a way to easily regain root access to the system, but it also gives the smart system administrator a convenient way to detect the intrusion. Making it impossible for an attacker to install a backdoor may actually be detrimental to your security because it will not close off the hole the attacker found to break in the first place. Security remedies should always be implemented with a multi-layered onion peel approach and can be categorized as follows: Securing root and staff accounts. Securing root – root-run servers and suid/sgid binaries. Securing user accounts. Securing the password file. Securing the kernel core, raw devices, and filesystems. Quick detection of inappropriate changes made to the system. Paranoia. The next section of this chapter will cover the above bullet items in greater depth. Securing FreeBSD The sections that follow will cover the methods of securing your FreeBSD system that were mentioned in the last section of this chapter. Securing the root account and staff accounts First off, do not bother securing staff accounts if you have not secured the root account. Most systems have a password assigned to the root account. The first thing you do is assume that the password is always compromised. This does not mean that you should remove the password. The password is almost always necessary for console access to the machine. What it does mean is that you should not make it possible to use the password outside of the console or possibly even with the &man.su.1; command. For example, make sure that your pty's are specified as being unsecure in the /etc/ttys file so that direct root logins via telnet or rlogin are disallowed. If using other login services such as sshd, make sure that direct root logins are disabled there as well. Consider every access method – services such as FTP often fall through the cracks. Direct root logins should only be allowed via the system console. Of course, as a sysadmin you have to be able to get to root, so we open up a few holes. But we make sure these holes require additional password verification to operate. One way to make root accessible is to add appropriate staff accounts to the wheel group (in /etc/group). The staff members placed in the wheel group are allowed to su to root. You should never give staff members native wheel access by putting them in the wheel group in their password entry. Staff accounts should be placed in a staff group, and then added to the wheel group via the /etc/group file. Only those staff members who actually need to have root access should be placed in the wheel group. It is also possible, when using an authentication method such as kerberos, to use kerberos' .k5login file in the root account to allow a &man.ksu.1; to root without having to place anyone at all in the wheel group. This may be the better solution since the wheel mechanism still allows an intruder to break root if the intruder has gotten hold of your password file and can break into a staff account. While having the wheel mechanism is better then having nothing at all, it is not necessarily the safest option. An indirect way to secure the root account is to secure your staff accounts by using an alternative login access method and *'ing out the crypted password for the staff accounts. This way an intruder may be able to steal the password file but will not be able to break into any staff accounts (or, indirectly, root, even if root has a crypted password associated with it). Staff members get into their staff accounts through a secure login mechanism such as &man.kerberos.1; or &man.ssh.1; using a private/public key pair. When you use something like kerberos, you generally must secure the machines which run the kerberos servers and your desktop workstation. When you use a public/private key pair with ssh, you must generally secure the machine you are logging in from (typically your workstation), but you can also add an additional layer of protection to the key pair by password protecting the keypair when you create it with &man.ssh-keygen.1;. Being able to * out the passwords for staff accounts also guarantees that staff members can only login through secure access methods that you have setup. You can thus force all staff members to use secure, encrypted connections for all of their sessions which closes an important hole used by many intruders: That of sniffing the network from an unrelated, less secure machine. The more indirect security mechanisms also assume that you are logging in from a more restrictive server to a less restrictive server. For example, if your main box is running all sorts of servers, your workstation should not be running any. In order for your workstation to be reasonably secure you should run as few servers as possible, up to and including no servers at all, and you should run a password-protected screen blanker. Of course, given physical access to a workstation an attacker can break any sort of security you put on it. This is definitely a problem that you should consider but you should also consider the fact that the vast majority of break-ins occur remotely, over a network, from people who do not have physical access to your workstation or servers. Using something like kerberos also gives you the ability to disable or change the password for a staff account in one place and have it immediately effect all the machine the staff member may have an account on. If a staff member's account gets compromised, the ability to instantly change his password on all machines should not be underrated. With discrete passwords, changing a password on N machines can be a mess. You can also impose re-passwording restrictions with kerberos: not only can a kerberos ticket be made to timeout after a while, but the kerberos system can require that the user choose a new password after a certain period of time (say, once a month). Securing Root-run Servers and SUID/SGID Binaries The prudent sysadmin only runs the servers he needs to, no more, no less. Be aware that third party servers are often the most bug-prone. For example, running an old version of imapd or popper is like giving a universal root ticket out to the entire world. Never run a server that you have not checked out carefully. Many servers do not need to be run as root. For example, the ntalk, comsat, and finger daemons can be run in special user sandboxes. A sandbox isn't perfect unless you go to a large amount of trouble, but the onion approach to security still stands: If someone is able to break in through a server running in a sandbox, they still have to break out of the sandbox. The more layers the attacker must break through, the lower the likelihood of his success. Root holes have historically been found in virtually every server ever run as root, including basic system servers. If you are running a machine through which people only login via sshd and never login via telnetd or rshd or rlogind, then turn off those services! FreeBSD now defaults to running ntalkd, comsat, and finger in a sandbox. Another program which may be a candidate for running in a sandbox is &man.named.8;. /etc/defaults/rc.conf includes the arguments necessary to run named in a sandbox in a commented-out form. Depending on whether you are installing a new system or upgrading an existing system, the special user accounts used by these sandboxes may not be installed. The prudent sysadmin would research and implement sandboxes for servers whenever possible. There are a number of other servers that typically do not run in sandboxes: sendmail, popper, imapd, ftpd, and others. There are alternatives to some of these, but installing them may require more work then you are willing to perform (the convenience factor strikes again). You may have to run these servers as root and rely on other mechanisms to detect break-ins that might occur through them. The other big potential root hole in a system are the suid-root and sgid binaries installed on the system. Most of these binaries, such as rlogin, reside in /bin, /sbin, /usr/bin, or /usr/sbin. While nothing is 100% safe, the system-default suid and sgid binaries can be considered reasonably safe. Still, root holes are occasionally found in these binaries. A root hole was found in Xlib in 1998 that made xterm (which is typically suid) vulnerable. It is better to be safe then sorry and the prudent sysadmin will restrict suid binaries that only staff should run to a special group that only staff can access, and get rid of (chmod 000) any suid binaries that nobody uses. A server with no display generally does not need an xterm binary. Sgid binaries can be almost as dangerous. If an intruder can break an sgid-kmem binary the intruder might be able to read /dev/kmem and thus read the crypted password file, potentially compromising any passworded account. Alternatively an intruder who breaks group kmem can monitor keystrokes sent through pty's, including pty's used by users who login through secure methods. An intruder that breaks the tty group can write to almost any user's tty. If a user is running a terminal program or emulator with a keyboard-simulation feature, the intruder can potentially generate a data stream that causes the user's terminal to echo a command, which is then run as that user. Securing User Accounts User accounts are usually the most difficult to secure. While you can impose Draconian access restrictions on your staff and * out their passwords, you may not be able to do so with any general user accounts you might have. If you do have sufficient control then you may win out and be able to secure the user accounts properly. If not, you simply have to be more vigilant in your monitoring of those accounts. Use of ssh and kerberos for user accounts is more problematic due to the extra administration and technical support required, but still a very good solution compared to a crypted password file. Securing the Password File The only sure fire way is to * out as many passwords as you can and use ssh or kerberos for access to those accounts. Even though the crypted password file (/etc/spwd.db) can only be read by root, it may be possible for an intruder to obtain read access to that file even if the attacker cannot obtain root-write access. Your security scripts should always check for and report changes to the password file (see Checking file integrity below). Securing the Kernel Core, Raw Devices, and Filesystems If an attacker breaks root he can do just about anything, but there are certain conveniences. For example, most modern kernels have a packet sniffing device driver built in. Under FreeBSD it is called the bpf device. An intruder will commonly attempt to run a packet sniffer on a compromised machine. You do not need to give the intruder the capability and most systems should not have the bpf device compiled in. But even if you turn off the bpf device, you still have /dev/mem and /dev/kmem to worry about. For that matter, the intruder can still write to raw disk devices. Also, there is another kernel feature called the module loader, &man.kldload.8;. An enterprising intruder can use a KLD module to install his own bpf device or other sniffing device on a running kernel. To avoid these problems you have to run the kernel at a higher secure level, at least securelevel 1. The securelevel can be set with a sysctl on the kern.securelevel variable. Once you have set the securelevel to 1, write access to raw devices will be denied and special chflags flags, such as schg, will be enforced. You must also ensure that the schg flag is set on critical startup binaries, directories, and script files – everything that gets run up to the point where the securelevel is set. This might be overdoing it, and upgrading the system is much more difficult when you operate at a higher secure level. You may compromise and run the system at a higher secure level but not set the schg flag for every system file and directory under the sun. Another possibility is to simply mount / and /usr read-only. It should be noted that being too draconian in what you attempt to protect may prevent the all-important detection of an intrusion. Checking File Integrity: Binaries, Configuration Files, Etc. When it comes right down to it, you can only protect your core system configuration and control files so much before the convenience factor rears its ugly head. For example, using chflags to set the schg bit on most of the files in / and /usr is probably counterproductive because while it may protect the files, it also closes a detection window. The last layer of your security onion is perhaps the most important – detection. The rest of your security is pretty much useless (or, worse, presents you with a false sense of safety) if you cannot detect potential incursions. Half the job of the onion is to slow down the attacker rather then stop him in order to give the detection side of the equation a chance to catch him in the act. The best way to detect an incursion is to look for modified, missing, or unexpected files. The best way to look for modified files is from another (often centralized) limited-access system. Writing your security scripts on the extra-secure limited-access system makes them mostly invisible to potential attackers, and this is important. In order to take maximum advantage you generally have to give the limited-access box significant access to the other machines in the business, usually either by doing a read-only NFS export of the other machines to the limited-access box, or by setting up ssh keypairs to allow the limit-access box to ssh to the other machines. Except for its network traffic, NFS is the least visible method – allowing you to monitor the filesystems on each client box virtually undetected. If your limited-access server is connected to the client boxes through a switch, the NFS method is often the better choice. If your limited-access server is connected to the client boxes through a hub or through several layers of routing, the NFS method may be too insecure (network-wise) and using ssh may be the better choice even with the audit-trail tracks that ssh lays. Once you give a limit-access box at least read access to the client systems it is supposed to monitor, you must write scripts to do the actual monitoring. Given an NFS mount, you can write scripts out of simple system utilities such as &man.find.1; and &man.md5.1;. It is best to physically md5 the client-box files boxes at least once a day, and to test control files such as those found in /etc and /usr/local/etc even more often. When mismatches are found relative to the base md5 information the limited-access machine knows is valid, it should scream at a sysadmin to go check it out. A good security script will also check for inappropriate suid binaries and for new or deleted files on system partitions such as / and /usr. When using ssh rather then NFS, writing the security script is much more difficult. You essentially have to scp the scripts to the client box in order to run them, making them visible, and for safety you also need to scp the binaries (such as find) that those scripts use. The ssh daemon on the client box may already be compromised. All in all, using ssh may be necessary when running over unsecure links, but it's also a lot harder to deal with. A good security script will also check for changes to user and staff members access configuration files: .rhosts, .shosts, .ssh/authorized_keys and so forth… files that might fall outside the purview of the MD5 check. If you have a huge amount of user disk space it may take too long to run through every file on those partitions. In this case, setting mount flags to disallow suid binaries and devices on those partitions is a good idea. The nodev and nosuid options (see &man.mount.8;) are what you want to look into. You should probably scan them anyway at least once a week, since the object of this layer is to detect a break-in whether or not the break-in is effective. Process accounting (see &man.accton.8;) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in occurs. Finally, security scripts should process the log files and the logs themselves should be generated in as secure a manner as possible – remote syslog can be very useful. An intruder tries to cover his tracks, and log files are critical to the sysadmin trying to track down the time and method of the initial break-in. One way to keep a permanent record of the log files is to run the system console to a serial port and collect the information on a continuing basis through a secure machine monitoring the consoles. Paranoia A little paranoia never hurts. As a rule, a sysadmin can add any number of security features as long as they do not effect convenience, and can add security features that do effect convenience with some added thought. Even more importantly, a security administrator should mix it up a bit – if you use recommendations such as those given by this document verbatim, you give away your methodologies to the prospective attacker who also has access to this document. Denial of Service Attacks This section covers Denial of Service attacks. A DOS attack is typically a packet attack. While there is not much you can do about modern spoofed packet attacks that saturate your network, you can generally limit the damage by ensuring that the attacks cannot take down your servers. Limiting server forks. Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.). Kernel Route Cache. A common DOS attack is against a forking server that attempts to cause the server to eat processes, file descriptors, and memory until the machine dies. Inetd (see &man.inetd.8;) has several options to limit this sort of attack. It should be noted that while it is possible to prevent a machine from going down it is not generally possible to prevent a service from being disrupted by the attack. Read the inetd manual page carefully and pay specific attention to the , , and options. Note that spoofed-IP attacks will circumvent the option to inetd, so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters. Sendmail has its option which tends to work much better than trying to use sendmail's load limiting options due to the load lag. You should specify a MaxDaemonChildren parameter when you start sendmail high enough to handle your expected load but no so high that the computer cannot handle that number of sendmails without falling on its face. It is also prudent to run sendmail in queued mode () and to run the daemon (sendmail -bd) separate from the queue-runs (sendmail -q15m). If you still want real-time delivery you can run the queue at a much lower interval, such as , but be sure to specify a reasonable MaxDaemonChildren option for that sendmail to prevent cascade failures. Syslogd can be attacked directly and it is strongly recommended that you use the option whenever possible, and the option otherwise. You should also be fairly careful with connect-back services such as tcpwrapper's reverse-identd, which can be attacked directly. You generally do not want to use the reverse-ident feature of tcpwrappers for this reason. It is a very good idea to protect internal services from external access by firewalling them off at your border routers. The idea here is to prevent saturation attacks from outside your LAN, not so much to protect internal services from network-based root compromise. Always configure an exclusive firewall, i.e., firewall everything except ports A, B, C, D, and M-Z. This way you can firewall off all of your low ports except for certain specific services such as named (if you are primary for a zone), ntalkd, sendmail, and other internet-accessible services. If you try to configure the firewall the other way – as an inclusive or permissive firewall, there is a good chance that you will forget to close a couple of services or that you will add a new internal service and forget to update the firewall. You can still open up the high-numbered port range on the firewall to allow permissive-like operation without compromising your low ports. Also take note that FreeBSD allows you to control the range of port numbers used for dynamic binding via the various net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange), which can also ease the complexity of your firewall's configuration. For example, you might use a normal first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then block everything under 4000 off in your firewall (except for certain specific internet-accessible ports, of course). Another common DOS attack is called a springboard attack – to attack a server in a manner that causes the server to generate responses which then overload the server, the local network, or some other machine. The most common attack of this nature is the ICMP ping broadcast attack. The attacker spoofs ping packets sent to your LAN's broadcast address with the source IP address set to the actual machine they wish to attack. If your border routers are not configured to stomp on ping's to broadcast addresses, your LAN winds up generating sufficient responses to the spoofed source address to saturate the victim, especially when the attacker uses the same trick on several dozen broadcast addresses over several dozen different networks at once. Broadcast attacks of over a hundred and twenty megabits have been measured. A second common springboard attack is against the ICMP error reporting system. By constructing packets that generate ICMP error responses, an attacker can saturate a server's incoming network and cause the server to saturate its outgoing network with ICMP responses. This type of attack can also crash the server by running it out of mbuf's, especially if the server cannot drain the ICMP responses it generates fast enough. The FreeBSD kernel has a new kernel compile option called ICMP_BANDLIM which limits the effectiveness of these sorts of attacks. The last major class of springboard attacks is related to certain internal inetd services such as the udp echo service. An attacker simply spoofs a UDP packet with the source address being server A's echo port, and the destination address being server B's echo port, where server A and B are both on your LAN. The two servers then bounce this one packet back and forth between each other. The attacker can overload both servers and their LANs simply by injecting a few packets in this manner. Similar problems exist with the internal chargen port. A competent sysadmin will turn off all of these inetd-internal test services. Spoofed packet attacks may also be used to overload the kernel route cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache sysctl parameters. A spoofed packet attack that uses a random source IP will cause the kernel to generate a temporary cached route in the route table, viewable with netstat -rna | fgrep W3. These routes typically timeout in 1600 seconds or so. If the kernel detects that the cached route table has gotten too big it will dynamically reduce the rtexpire but will never decrease it to less then rtminexpire. There are two problems: The kernel does not react quickly enough when a lightly loaded server is suddenly attacked. The rtminexpire is not low enough for the kernel to survive a sustained attack. If your servers are connected to the internet via a T3 or better it may be prudent to manually override both rtexpire and rtminexpire via &man.sysctl.8;. Never set either parameter to zero (unless you want to crash the machine :-). Setting both parameters to 2 seconds should be sufficient to protect the route table from attack. Access Issues with Kerberos and SSH There are a few issues with both kerberos and ssh that need to be addressed if you intend to use them. Kerberos V is an excellent authentication protocol but there are bugs in the kerberized telnet and rlogin applications that make them unsuitable for dealing with binary streams. Also, by default kerberos does not encrypt a session unless you use the option. ssh encrypts everything by default. ssh works quite well in every respect except that it forwards encryption keys by default. What this means is that if you have a secure workstation holding keys that give you access to the rest of the system, and you ssh to an unsecure machine, your keys becomes exposed. The actual keys themselves are not exposed, but ssh installs a forwarding port for the duration of your login and if a attacker has broken root on the unsecure machine he can utilize that port to use your keys to gain access to any other machine that your keys unlock. We recommend that you use ssh in combination with kerberos whenever possible for staff logins. ssh can be compiled with kerberos support. This reduces your reliance on potentially exposable ssh keys while at the same time protecting passwords via kerberos. ssh keys should only be used for automated tasks from secure machines (something that kerberos is unsuited to). We also recommend that you either turn off key-forwarding in the ssh configuration, or that you make use of the from=IP/DOMAIN option that ssh allows in its authorized_keys file to make the key only usable to entities logging in from specific machines. DES, MD5, and Crypt Parts rewritten and updated by &a.unfurl;, 21 March 2000. Every user on a UNIX system has a password associated with their account. It seems obvious that these passwords need to be known only to the user and the actual operating system. In order to keep these passwords secret, they are encrypted with what is known as a one-way hash, that is, they can only be easily encrypted but not decrypted. In other words, what we told you a moment ago was obvious is not even true: the operating system itself does not really know the password. It only knows the encrypted form of the password. The only way to get the plain-text password is by a brute force search of the space of possible passwords. Unfortunately the only secure way to encrypt passwords when UNIX came into being was based on DES, the Data Encryption Standard. This is not such a problem for users that live in the US, but since the source code for DES could not be exported outside the US, FreeBSD had to find a way to both comply with US law and retain compatibility with all the other UNIX variants that still use DES. The solution was to divide up the encryption libraries so that US users could install the DES libraries and use DES but international users still had an encryption method that could be exported abroad. This is how FreeBSD came to use MD5 as its default encryption method. MD5 is believed to be more secure than DES, so installing DES is offered primarily for compatibility reasons. Recognizing your crypt mechanism It is pretty easy to identify which encryption method FreeBSD is set up to use. Examining the encrypted passwords in the /etc/master.passwd file is one way. Passwords encrypted with the MD5 hash are longer than those with encrypted with the DES hash and also begin with the characters $1$. DES password strings do not have any particular identifying characteristics, but they are shorter than MD5 passwords, and are coded in a 64-character alphabet which does not include the $ character, so a relatively short string which does not begin with a dollar sign is very likely a DES password. The libraries can identify the passwords this way as well. As a result, the DES libraries are able to identify MD5 passwords, and use MD5 to check passwords that were encrypted that way, and DES for the rest. They are able to do this because the DES libraries also contain MD5. Unfortunately, the reverse is not true, so the MD5 libraries cannot authenticate passwords that were encrypted with DES. Identifying which library is being used by the programs on your system is easy as well. Any program that uses crypt is linked against libcrypt which for each type of library is a symbolic link to the appropriate implementation. For example, on a system using the DES versions: &prompt.user; ls -l /usr/lib/libcrypt* lrwxr-xr-x 1 root wheel 13 Mar 19 06:56 libcrypt.a -> libdescrypt.a lrwxr-xr-x 1 root wheel 18 Mar 19 06:56 libcrypt.so.2.0 -> libdescrypt.so.2.0 lrwxr-xr-x 1 root wheel 15 Mar 19 06:56 libcrypt_p.a -> libdescrypt_p.a On a system using the MD5-based libraries, the same links will be present, but the target will be libscrypt rather than libdescrypt. If you have installed the DES-capable crypt library libdescrypt (e.g. by installing the "crypto" distribution), then which password format will be used for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of either des or md5. See the - login.conf(5) manpage for more information about login + &man.login.conf.5; manpage for more information about login capabilities. S/Key S/Key is a one-time password scheme based on a one-way hash function. FreeBSD uses the MD4 hash for compatibility but other systems have used MD5 and DES-MAC. S/Key has been part of the FreeBSD base system since version 1.1.5 and is also used on a growing number of other operating systems. S/Key is a registered trademark of Bell Communications Research, Inc. There are three different sorts of passwords which we will talk about in the discussion below. The first is your usual UNIX-style or Kerberos password; we will call this a UNIX password. The second sort is the one-time password which is generated by the S/Key key program and accepted by the keyinit program and the login prompt; we will call this a one-time password. The final sort of password is the secret password which you give to the key program (and sometimes the keyinit program) which it uses to generate one-time passwords; we will call it a secret password or just unqualified password. The secret password does not have anything to do with your UNIX password; they can be the same but this is not recommended. S/Key secret passwords are not limited to 8 characters like UNIX passwords, they can be as long as you like. Passwords of six or seven word long phrases are fairly common. For the most part, the S/Key system operates completely independently of the UNIX password system. Besides the password, there are two other pieces of data that are important to S/Key. One is what is known as the seed or key and consists of two letters and five digits. The other is what is called the iteration count and is a number between 1 and 100. S/Key creates the one-time password by concatenating the seed and the secret password, then applying the MD4 hash as many times as specified by the iteration count and turning the result into six short English words. These six English words are your one-time password. The login and su programs keep track of the last one-time password used, and the user is authenticated if the hash of the user-provided password is equal to the previous password. Because a one-way hash is used it is impossible to generate future one-time passwords if a successfully used password is captured; the iteration count is decremented after each successful login to keep the user and the login program in sync. When the iteration count gets down to 1 S/Key must be reinitialized. There are four programs involved in the S/Key system which we will discuss below. The key program accepts an iteration count, a seed, and a secret password, and generates a one-time password. The keyinit program is used to initialized S/Key, and to change passwords, iteration counts, or seeds; it takes either a secret password, or an iteration count, seed, and one-time password. The keyinfo program examines the /etc/skeykeys file and prints out the invoking user's current iteration count and seed. Finally, the login and su programs contain the necessary logic to accept S/Key one-time passwords for authentication. The login program is also capable of disallowing the use of UNIX passwords on connections coming from specified addresses. There are four different sorts of operations we will cover. The first is using the keyinit program over a secure connection to set up S/Key for the first time, or to change your password or seed. The second operation is using the keyinit program over an insecure connection, in conjunction with the key program over a secure connection, to do the same. The third is using the key program to log in over an insecure connection. The fourth is using the key program to generate a number of keys which can be written down or printed out to carry with you when going to some location without secure connections to anywhere. Secure connection initialization To initialize S/Key for the first time, change your password, or change your seed while logged in over a secure connection (e.g., on the console of a machine or via ssh), use the keyinit command without any parameters while logged in as yourself: &prompt.user; keyinit Adding unfurl: Reminder - Only use this method if you are directly connected. If you are using telnet or rlogin exit with no password and use keyinit -s. Enter secret password: Again secret password: ID unfurl s/key is 99 to17757 DEFY CLUB PRO NASH LACE SOFT At the Enter secret password: prompt you should enter a password or phrase. Remember, this is not the password that you will use to login with, this is used to generate your one-time login keys. The ID line gives the parameters of your particular S/Key instance; your login name, the iteration count, and seed. When logging in with S/Key, the system will remember these parameters and present them back to you so you do not have to remember them. The last line gives the particular one-time password which corresponds to those parameters and your secret password; if you were to re-login immediately, this one-time password is the one you would use. Insecure connection initialization To initialize S/Key or change your secret password over an insecure connection, you will need to already have a secure connection to some place where you can run the key program; this might be in the form of a desk accessory on a Macintosh, or a shell prompt on a machine you trust. You will also need to make up an iteration count (100 is probably a good value), and you may make up your own seed or use a randomly-generated one. Over on the insecure connection (to the machine you are initializing), use the keyinit -s command: &prompt.user; keyinit -s Updating unfurl: Old key: to17758 Reminder you need the 6 English words from the key command. Enter sequence count from 1 to 9999: 100 Enter new key [default to17759]: s/key 100 to 17759 s/key access password: To accept the default seed (which the keyinit program confusingly calls a key), press return. Then before entering an access password, move over to your secure connection or S/Key desk accessory, and give it the same parameters: &prompt.user; key 100 to17759 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> CURE MIKE BANE HIM RACY GORE Now switch back over to the insecure connection, and copy the one-time password generated by key over to the keyinit program: s/key access password:CURE MIKE BANE HIM RACY GORE ID unfurl s/key is 100 to17759 CURE MIKE BANE HIM RACY GORE The rest of the description from the previous section applies here as well. Generating a single one-time password Once you've initialized S/Key, when you login you will be presented with a prompt like this: &prompt.user; telnet example.com Trying 10.0.0.1... Connected to example.com Escape character is '^]'. FreeBSD/i386 (example.com) (ttypa) login: <username> s/key 97 fw13894 Password: As a side note, the S/Key prompt has a useful feature (not shown here): if you press return at the password prompt, the login program will turn echo on, so you can see what you are typing. This can be extremely useful if you are attempting to type in an S/Key by hand, such as from a printout. Also, if this machine were configured to disallow UNIX passwords over a connection from the source machine, the prompt would have also included the annotation (s/key required), indicating that only S/Key one-time passwords will be accepted. At this point you need to generate your one-time password to answer this login prompt. This must be done on a trusted system that you can run the key command on. (There are versions of the key program from DOS, Windows and MacOS as well.) The key program needs both the iteration count and the seed as command line options. You can cut-and-paste these right from the login prompt on the machine that you are logging in to. On the trusted system: &prompt.user; key 97 fw13894 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: WELD LIP ACTS ENDS ME HAAG Now that you have your one-time password you can continue logging in: login: <username> s/key 97 fw13894 Password: <return to enable echo> s/key 97 fw13894 Password [echo on]: WELD LIP ACTS ENDS ME HAAG Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... This is the easiest mechanism if you have a trusted machine. There is a Java S/Key key applet, The Java OTP Calculator, that you can download and run locally on any Java supporting browser. Generating multiple one-time passwords Sometimes you have have to go places where you do not have access to a trusted machine or secure connection. In this case, it is possible to use the key command to generate a number of one-time passwords before hand to be printed out and taken with you. For example: &prompt.user; key -n 5 30 zz99999 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> 26: SODA RUDE LEA LIND BUDD SILT 27: JILT SPY DUTY GLOW COWL ROT 28: THEM OW COLA RUNT BONG SCOT 29: COT MASH BARR BRIM NAN FLAG 30: CAN KNEE CAST NAME FOLK BILK The requests five keys in sequence, the specifies what the last iteration number should be. Note that these are printed out in reverse order of eventual use. If you are really paranoid, you might want to write the results down by hand; otherwise you can cut-and-paste into lpr. Note that each line shows both the iteration count and the one-time password; you may still find it handy to scratch off passwords as you use them. Restricting use of UNIX passwords Restrictions can be placed on the use of UNIX passwords based on the host name, user name, terminal port, or IP address of a login session. These restrictions can be found in the configuration file /etc/skey.access. The &man.skey.access.5; manual page has more info on the complete format of the file and also details some security cautions to be aware of before depending on this file for security. If there is no /etc/skey.access file (this is the FreeBSD default), then all users will be allowed to use UNIX passwords. If the file exists, however, then all users will be required to use S/Key unless explicitly permitted to do otherwise by configuration statements in the skey.access file. In all cases, UNIX passwords are permitted on the console. Here is a sample configuration file which illustrates the three most common sorts of configuration statements: permit internet 192.168.0.0 255.255.0.0 permit user fnord permit port ttyd0 The first line (permit internet) allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use UNIX passwords. This should not be considered a security mechanism, but rather, a means to remind authorized users that they are using an insecure network and need to use S/Key for authentication. The second line (permit user) allows the specified username, in this case fnord, to use UNIX passwords at any time. Generally speaking, this should only be used for people who are either unable to use the key program, like those with dumb terminals, or those who are uneducable. The third line (permit port) allows all users logging in on the specified terminal line to use UNIX passwords; this would be used for dial-ups. Kerberos Contributed by &a.markm; (based on contribution by &a.md;). Kerberos is a network add-on system/protocol that allows users to authenticate themselves through the services of a secure server. Services such as remote login, remote copy, secure inter-system file copying and other high-risk tasks are made considerably safer and more controllable. The following instructions can be used as a guide on how to set up Kerberos as distributed for FreeBSD. However, you should refer to the relevant manual pages for a complete description. In FreeBSD, the Kerberos is not that from the original 4.4BSD-Lite, distribution, but eBones, which had been previously ported to FreeBSD 1.1.5.1, and was sourced from outside the USA/Canada, and was thus available to system owners outside those countries during the era of restrictive export controls on cryptographic code from the USA. Creating the initial database This is done on the Kerberos server only. First make sure that you do not have any old Kerberos databases around. You should change to the directory /etc/kerberosIV and check that only the following files are present: &prompt.root; cd /etc/kerberosIV &prompt.root; ls README krb.conf krb.realms If any additional files (such as principal.* or master_key) exist, then use the kdb_destroy command to destroy the old Kerberos database, of if Kerberos is not running, simply delete the extra files. You should now edit the krb.conf and krb.realms files to define your Kerberos realm. In this case the realm will be GRONDAR.ZA and the server is grunt.grondar.za. We edit or create the krb.conf file: &prompt.root; cat krb.conf GRONDAR.ZA GRONDAR.ZA grunt.grondar.za admin server CS.BERKELEY.EDU okeeffe.berkeley.edu ATHENA.MIT.EDU kerberos.mit.edu ATHENA.MIT.EDU kerberos-1.mit.edu ATHENA.MIT.EDU kerberos-2.mit.edu ATHENA.MIT.EDU kerberos-3.mit.edu LCS.MIT.EDU kerberos.lcs.mit.edu TELECOM.MIT.EDU bitsy.mit.edu ARC.NASA.GOV trident.arc.nasa.gov In this case, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to not include them for simplicity. The first line names the realm in which this system works. The other lines contain realm/host entries. The first item on a line is a realm, and the second is a host in that realm that is acting as a key distribution center. The words admin server following a hosts name means that host also provides an administrative database server. For further explanation of these terms, please consult the Kerberos man pages. Now we have to add grunt.grondar.za to the GRONDAR.ZA realm and also add an entry to put all hosts in the .grondar.za domain in the GRONDAR.ZA realm. The krb.realms file would be updated as follows: &prompt.root; cat krb.realms grunt.grondar.za GRONDAR.ZA .grondar.za GRONDAR.ZA .berkeley.edu CS.BERKELEY.EDU .MIT.EDU ATHENA.MIT.EDU .mit.edu ATHENA.MIT.EDU Again, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to remove them to simplify things. The first line puts the specific system into the named realm. The rest of the lines show how to default systems of a particular subdomain to a named realm. Now we are ready to create the database. This only needs to run on the Kerberos server (or Key Distribution Center). Issue the kdb_init command to do this: &prompt.root; kdb_init Realm name [default ATHENA.MIT.EDU ]: GRONDAR.ZA You will be prompted for the database Master Password. It is important that you NOT FORGET this password. Enter Kerberos master key: Now we have to save the key so that servers on the local machine can pick it up. Use the kstash command to do this. &prompt.root; kstash Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! This saves the encrypted master password in /etc/kerberosIV/master_key. Making it all run Two principals need to be added to the database for each system that will be secured with Kerberos. Their names are kpasswd and rcmd These two principals are made for each system, with the instance being the name of the individual system. These daemons, kpasswd and rcmd allow other systems to change Kerberos passwords and run commands like rcp, rlogin and rsh. Now let's add these entries: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: passwd Instance: grunt <Not found>, Create [y] ? y Principal: passwd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? y Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: rcmd Instance: grunt <Not found>, Create [y] ? Principal: rcmd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Creating the server file We now have to extract all the instances which define the services on each machine. For this we use the ext_srvtab command. This will create a file which must be copied or moved by secure means to each Kerberos client's /etc/kerberosIV directory. This file must be present on each server and client, and is crucial to the operation of Kerberos. &prompt.root; ext_srvtab grunt Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Generating 'grunt-new-srvtab'.... Now, this command only generates a temporary file which must be renamed to srvtab so that all the server can pick it up. Use the mv command to move it into place on the original system: &prompt.root; mv grunt-new-srvtab srvtab If the file is for a client system, and the network is not deemed safe, then copy the client-new-srvtab to removable media and transport it by secure physical means. Be sure to rename it to srvtab in the client's /etc/kerberosIV directory, and make sure it is mode 600: &prompt.root; mv grumble-new-srvtab srvtab &prompt.root; chmod 600 srvtab Populating the database We now have to add some user entries into the database. First let's create an entry for the user jane. Use the kdb_edit command to do this: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: <Not found>, Create [y] ? y Principal: jane, Instance: , kdc_key_ver: 1 New Password: <---- enter a secure password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Testing it all out First we have to start the Kerberos daemons. NOTE that if you have correctly edited your /etc/rc.conf then this will happen automatically when you reboot. This is only necessary on the Kerberos server. Kerberos clients will automagically get what they need from the /etc/kerberosIV directory. &prompt.root; kerberos & Kerberos server starting Sleep forever on error Log file is /var/log/kerberos.log Current Kerberos master key version is 1. Master key entered. BEWARE! Current Kerberos master key version is 1 Local realm: GRONDAR.ZA &prompt.root; kadmind -n & KADM Server KADM0.0A initializing Please do not use 'kill -9' to kill this job, use a regular kill instead Current Kerberos master key version is 1. Master key entered. BEWARE! Now we can try using the kinit command to get a ticket for the id jane that we created above: &prompt.user; kinit jane MIT Project Athena (grunt.grondar.za) Kerberos Initialization for "jane" Password: Try listing the tokens using klist to see if we really have them: &prompt.user; klist Ticket file: /tmp/tkt245 Principal: jane@GRONDAR.ZA Issued Expires Principal Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.GRONDAR.ZA@GRONDAR.ZA Now try changing the password using passwd to check if the kpasswd daemon can get authorization to the Kerberos database: &prompt.user; passwd realm GRONDAR.ZA Old password for jane: New Password for jane: Verifying password New Password for jane: Password changed. Adding <command>su</command> privileges Kerberos allows us to give each user who needs root privileges their own separate supassword. We could now add an id which is authorized to su to root. This is controlled by having an instance of root associated with a principal. Using kdb_edit we can create the entry jane.root in the Kerberos database: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: root <Not found>, Create [y] ? y Principal: jane, Instance: root, kdc_key_ver: 1 New Password: <---- enter a SECURE password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short! Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Now try getting tokens for it to make sure it works: &prompt.root; kinit jane.root MIT Project Athena (grunt.grondar.za) Kerberos Initialization for "jane.root" Password: Now we need to add the user to root's .klogin file: &prompt.root; cat /root/.klogin jane.root@GRONDAR.ZA Now try doing the su: &prompt.user; su Password: and take a look at what tokens we have: &prompt.root; klist Ticket file: /tmp/tkt_root_245 Principal: jane.root@GRONDAR.ZA Issued Expires Principal May 2 20:43:12 May 3 04:43:12 krbtgt.GRONDAR.ZA@GRONDAR.ZA Using other commands In an earlier example, we created a principal called jane with an instance root. This was based on a user with the same name as the principal, and this is a Kerberos default; that a <principal>.<instance> of the form <username>.root will allow that <username> to su to root if the necessary entries are in the .klogin file in root's home directory: &prompt.root; cat /root/.klogin jane.root@GRONDAR.ZA Likewise, if a user has in their own home directory lines of the form: &prompt.user; cat ~/.klogin jane@GRONDAR.ZA jack@GRONDAR.ZA This allows anyone in the GRONDAR.ZA realm who has authenticated themselves to jane or jack (via kinit, see above) access to rlogin to jane's account or files on this system (grunt) via rlogin, rsh or rcp. For example, Jane now logs into another system, using Kerberos: &prompt.user; kinit MIT Project Athena (grunt.grondar.za) Password: %prompt.user; rlogin grunt Last login: Mon May 1 21:14:47 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Or Jack logs into Jane's account on the same machine (Jane having set up the .klogin file as above, and the person in charge of Kerberos having set up principal jack with a null instance: &prompt.user; kinit &prompt.user; rlogin grunt -l jane MIT Project Athena (grunt.grondar.za) Password: Last login: Mon May 1 21:16:55 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Firewalls Contributed by &a.gpalmer; and Alex Nash. Firewalls are an area of increasing interest for people who are connected to the Internet, and are even finding applications on private networks to provide enhanced security. This section will hopefully explain what firewalls are, how to use them, and how to use the facilities provided in the FreeBSD kernel to implement them. People often think that having a firewall between your internal network and the Big Bad Internet will solve all your security problems. It may help, but a poorly setup firewall system is more of a security risk than not having one at all. A firewall can add another layer of security to your systems, but it cannot stop a really determined cracker from penetrating your internal network. If you let internal security lapse because you believe your firewall to be impenetrable, you have just made the crackers job that much easier. What is a firewall? There are currently two distinct types of firewalls in common use on the Internet today. The first type is more properly called a packet filtering router, where the kernel on a multi-homed machine chooses whether to forward or block packets based on a set of rules. The second type, known as a proxy server, relies on daemons to provide authentication and to forward packets, possibly on a multi-homed machine which has kernel packet forwarding disabled. Sometimes sites combine the two types of firewalls, so that only a certain machine (known as a bastion host) is allowed to send packets through a packet filtering router onto an internal network. Proxy services are run on the bastion host, which are generally more secure than normal authentication mechanisms. FreeBSD comes with a kernel packet filter (known as IPFW), which is what the rest of this section will concentrate on. Proxy servers can be built on FreeBSD from third party software, but there is such a variety of proxy servers available that it would be impossible to cover them in this document. Packet filtering routers A router is a machine which forwards packets between two or more networks. A packet filtering router has an extra piece of code in its kernel which compares each packet to a list of rules before deciding if it should be forwarded or not. Most modern IP routing software has packet filtering code within it that defaults to forwarding all packets. To enable the filters, you need to define a set of rules for the filtering code so it can decide if the packet should be allowed to pass or not. To decide whether a packet should be passed on, the code looks through its set of rules for a rule which matches the contents of this packets headers. Once a match is found, the rule action is obeyed. The rule action could be to drop the packet, to forward the packet, or even to send an ICMP message back to the originator. Only the first match counts, as the rules are searched in order. Hence, the list of rules can be referred to as a rule chain. The packet matching criteria varies depending on the software used, but typically you can specify rules which depend on the source IP address of the packet, the destination IP address, the source port number, the destination port number (for protocols which support ports), or even the packet type (UDP, TCP, ICMP, etc). Proxy servers Proxy servers are machines which have had the normal system daemons (telnetd, ftpd, etc) replaced with special servers. These servers are called proxy servers as they normally only allow onward connections to be made. This enables you to run (for example) a proxy telnet server on your firewall host, and people can telnet in to your firewall from the outside, go through some authentication mechanism, and then gain access to the internal network (alternatively, proxy servers can be used for signals coming from the internal network and heading out). Proxy servers are normally more secure than normal servers, and often have a wider variety of authentication mechanisms available, including one-shot password systems so that even if someone manages to discover what password you used, they will not be able to use it to gain access to your systems as the password instantly expires. As they do not actually give users access to the host machine, it becomes a lot more difficult for someone to install backdoors around your security system. Proxy servers often have ways of restricting access further, so that only certain hosts can gain access to the servers, and often they can be set up so that you can limit which users can talk to which destination machine. Again, what facilities are available depends largely on what proxy software you choose. What does IPFW allow me to do? IPFW, the software supplied with FreeBSD, is a packet filtering and accounting system which resides in the kernel, and has a user-land control utility, &man.ipfw.8;. Together, they allow you to define and query the rules currently used by the kernel in its routing decisions. There are two related parts to IPFW. The firewall section allows you to perform packet filtering. There is also an IP accounting section which allows you to track usage of your router, based on similar rules to the firewall section. This allows you to see (for example) how much traffic your router is getting from a certain machine, or how much WWW (World Wide Web) traffic it is forwarding. As a result of the way that IPFW is designed, you can use IPFW on non-router machines to perform packet filtering on incoming and outgoing connections. This is a special case of the more general use of IPFW, and the same commands and techniques should be used in this situation. Enabling IPFW on FreeBSD As the main part of the IPFW system lives in the kernel, you will need to add one or more options to your kernel configuration file, depending on what facilities you want, and recompile your kernel. See reconfiguring the kernel for more details on how to recompile your kernel. There are currently three kernel configuration options relevant to IPFW: options IPFIREWALL Compiles into the kernel the code for packet filtering. options IPFIREWALL_VERBOSE Enables code to allow logging of packets through &man.syslogd.8;. Without this option, even if you specify that packets should be logged in the filter rules, nothing will happen. options IPFIREWALL_VERBOSE_LIMIT=10 Limits the number of packets logged through &man.syslogd.8; on a per entry basis. You may wish to use this option in hostile environments in which you want to log firewall activity, but do not want to be open to a denial of service attack via syslog flooding. When a chain entry reaches the packet limit specified, logging is turned off for that particular entry. To resume logging, you will need to reset the associated counter using the &man.ipfw.8; utility: &prompt.root; ipfw zero 4500 Where 4500 is the chain entry you wish to continue logging. Previous versions of FreeBSD contained an IPFIREWALL_ACCT option. This is now obsolete as the firewall code automatically includes accounting facilities. Configuring IPFW The configuration of the IPFW software is done through the &man.ipfw.8; utility. The syntax for this command looks quite complicated, but it is relatively simple once you understand its structure. There are currently four different command categories used by the utility: addition/deletion, listing, flushing, and clearing. Addition/deletion is used to build the rules that control how packets are accepted, rejected, and logged. Listing is used to examine the contents of your rule set (otherwise known as the chain) and packet counters (accounting). Flushing is used to remove all entries from the chain. Clearing is used to zero out one or more accounting entries. Altering the IPFW rules The syntax for this form of the command is: ipfw -N command index action log protocol addresses options There is one valid flag when using this form of the command: -N Resolve addresses and service names in output. The command given can be shortened to the shortest unique form. The valid commands are: add Add an entry to the firewall/accounting rule list delete Delete an entry from the firewall/accounting rule list Previous versions of IPFW used separate firewall and accounting entries. The present version provides packet accounting with each firewall entry. If an index value is supplied, it used to place the entry at a specific point in the chain. Otherwise, the entry is placed at the end of the chain at an index 100 greater than the last chain entry (this does not include the default policy, rule 65535, deny). The log option causes matching rules to be output to the system console if the kernel was compiled with IPFIREWALL_VERBOSE. Valid actions are: reject Drop the packet, and send an ICMP host or port unreachable (as appropriate) packet to the source. allow Pass the packet on as normal. (aliases: pass and accept) deny Drop the packet. The source is not notified via an ICMP message (thus it appears that the packet never arrived at the destination). count Update packet counters but do not allow/deny the packet based on this rule. The search continues with the next chain entry. Each action will be recognized by the shortest unambiguous prefix. The protocols which can be specified are: all Matches any IP packet icmp Matches ICMP packets tcp Matches TCP packets udp Matches UDP packets The address specification is: from address/maskport to address/maskport via interface You can only specify port in conjunction with protocols which support ports (UDP and TCP). The is optional and may specify the IP address or domain name of a local IP interface, or an interface name (e.g. ed0) to match only packets coming through this interface. Interface unit numbers can be specified with an optional wildcard. For example, ppp* would match all kernel PPP interfaces. The syntax used to specify an address/mask is: address or address/mask-bits or address:mask-pattern A valid hostname may be specified in place of the IP address. is a decimal number representing how many bits in the address mask should be set. e.g. specifying 192.216.222.1/24 will create a mask which will allow any address in a class C subnet (in this case, 192.216.222) to be matched. is an IP address which will be logically AND'ed with the address given. The keyword any may be used to specify any IP address. The port numbers to be blocked are specified as: port,port,port… to specify either a single port or a list of ports, or port-port to specify a range of ports. You may also combine a single range with a list, but the range must always be specified first. The options available are: frag Matches if the packet is not the first fragment of the datagram. in Matches if the packet is on the way in. out Matches if the packet is on the way out. ipoptions spec Matches if the IP header contains the comma separated list of options specified in spec. The supported list of IP options are: ssrr (strict source route), lsrr (loose source route), rr (record packet route), and ts (time stamp). The absence of a particular option may be denoted with a leading !. established Matches if the packet is part of an already established TCP connection (i.e. it has the RST or ACK bits set). You can optimize the performance of the firewall by placing established rules early in the chain. setup Matches if the packet is an attempt to establish a TCP connection (the SYN bit set is set but the ACK bit is not). tcpflags flags Matches if the TCP header contains the comma separated list of flags. The supported flags are fin, syn, rst, psh, ack, and urg. The absence of a particular flag may be indicated by a leading !. icmptypes types Matches if the ICMP type is present in the list types. The list may be specified as any combination of ranges and/or individual types separated by commas. Commonly used ICMP types are: 0 echo reply (ping reply), 3 destination unreachable, 5 redirect, 8 echo request (ping request), and 11 time exceeded (used to indicate TTL expiration as with &man.traceroute.8;). Listing the IPFW rules The syntax for this form of the command is: ipfw -a -t -N l There are three valid flags when using this form of the command: -a While listing, show counter values. This option is the only way to see accounting counters. -t Display the last match times for each chain entry. The time listing is incompatible with the input syntax used by the &man.ipfw.8; utility. -N Attempt to resolve given addresses and service names. Flushing the IPFW rules The syntax for flushing the chain is: ipfw flush This causes all entries in the firewall chain to be removed except the fixed default policy enforced by the kernel (index 65535). Use caution when flushing rules, the default deny policy will leave your system cut off from the network until allow entries are added to the chain. Clearing the IPFW packet counters The syntax for clearing one or more packet counters is: ipfw zero index When used without an index argument, all packet counters are cleared. If an index is supplied, the clearing operation only affects a specific chain entry. Example commands for ipfw This command will deny all packets from the host evil.crackers.org to the telnet port of the host nice.people.org: &prompt.root ipfw add deny tcp from evil.crackers.org to nice.people.org 23 The next example denies and logs any TCP traffic from the entire crackers.org network (a class C) to the nice.people.org machine (any port). &prompt.root; ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org If you do not want people sending X sessions to your internal network (a subnet of a class C), the following command will do the necessary filtering: &prompt.root; ipfw add deny tcp from any to my.org/28 6000 setup To see the accounting records: &prompt.root; ipfw -a list or in the short form &prompt.root; ipfw -a l You can also see the last time a chain entry was matched with: &prompt.root; ipfw -at l Building a packet filtering firewall The following suggestions are just that: suggestions. The requirements of each firewall are different and we cannot tell you how to build a firewall to meet your particular requirements. When initially setting up your firewall, unless you have a test bench setup where you can configure your firewall host in a controlled environment, it is strongly recommend you use the logging version of the commands and enable logging in the kernel. This will allow you to quickly identify problem areas and cure them without too much disruption. Even after the initial setup phase is complete, I recommend using the logging for `deny' as it allows tracing of possible attacks and also modification of the firewall rules if your requirements alter. If you use the logging versions of the accept command, it can generate large amounts of log data as one log line will be generated for every packet that passes through the firewall, so large ftp/http transfers, etc, will really slow the system down. It also increases the latencies on those packets as it requires more work to be done by the kernel before the packet can be passed on. syslogd with also start using up a lot more processor time as it logs all the extra data to disk, and it could quite easily fill the partition /var/log is located on. You should enable your firewall from /etc/rc.conf.local or /etc/rc.conf. The associated man page explains which knobs to fiddle and lists some preset firewall configurations. If you do not use a preset configuration, ipfw list will output the current ruleset into a file that you can pass to rc.conf. If you do not use /etc/rc.conf.local or /etc/rc.conf to enable your firewall, it is important to make sure your firewall is enabled before any IP interfaces are configured. The next problem is what your firewall should actually do! This is largely dependent on what access to your network you want to allow from the outside, and how much access to the outside world you want to allow from the inside. Some general rules are: Block all incoming access to ports below 1024 for TCP. This is where most of the security sensitive services are, like finger, SMTP (mail) and telnet. Block all incoming UDP traffic. There are very few useful services that travel over UDP, and what useful traffic there is is normally a security threat (e.g. Suns RPC and NFS protocols). This has its disadvantages also, since UDP is a connectionless protocol, denying incoming UDP traffic also blocks the replies to outgoing UDP traffic. This can cause a problem for people (on the inside) using external archie (prospero) servers. If you want to allow access to archie, you'll have to allow packets coming from ports 191 and 1525 to any internal UDP port through the firewall. ntp is another service you may consider allowing through, which comes from port 123. Block traffic to port 6000 from the outside. Port 6000 is the port used for access to X11 servers, and can be a security threat (especially if people are in the habit of doing xhost + on their workstations). X11 can actually use a range of ports starting at 6000, the upper limit being how many X displays you can run on the machine. The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063. Check what ports any internal servers use (e.g. SQL servers, etc). It is probably a good idea to block those as well, as they normally fall outside the 1-1024 range specified above. Another checklist for firewall configuration is available from CERT at http://www.cert.org/tech_tips/packet_filtering.html As stated above, these are only guidelines. You will have to decide what filter rules you want to use on your firewall yourself. We cannot accept ANY responsibility if someone breaks into your network, even if you follow the advice given above. OpenSSL As of FreeBSD 4.0, the OpenSSL toolkit is a part of the base system. OpenSSL provides a general-purpose cryptography library, as well as the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols. However, one of the algorithms (specifically IDEA) included in OpenSSL is protected by patents in the USA and elsewhere, and is not available for unrestricted use. IDEA is included in the OpenSSL sources in FreeBSD, but it is not built by default. If you wish to use it, and you comply with the license terms, enable the MAKE_IDEA switch in /etc/make.conf and rebuild your sources using 'make world'. Today, the RSA algorithm is free for use in USA and other countries. In the past it was protected by a patent. Source Code Installations OpenSSL is part of the src-crypto and src-secure cvsup collections. See the Obtaining FreeBSD section for more information about obtaining and updating FreeBSD source code. IPsec Contributed by &a.shin;, 5 March 2000. The IPsec mechanism provides secure communication either for IP layer and socket layer communication. This section should explain how to use them. For implementation details, please refer to The Developers' Handbook. The current IPsec implementation supports both transport mode and tunnel mode. However, tunnel mode comes with some restrictions. http://www.kame.net/newsletter/ has more comprehensive examples. Please be aware that in order to use this functionality, you must have the following options compiled into your kernel: options IPSEC #IP security options IPSEC_ESP #IP security (crypto; define w/IPSEC) Transport mode example with IPv4 Let's setup security association to deploy a secure channel between HOST A (10.2.3.4) and HOST B (10.6.7.8). Here we show a little complicated example. From HOST A to HOST B, only old AH is used. From HOST B to HOST A, new AH and new ESP are combined. Now we should choose algorithm to be used corresponding to "AH"/"new AH"/"ESP"/"new ESP". Please refer to the &man.setkey.8; man page to know algorithm names. Our choice is MD5 for AH, new-HMAC-SHA1 for new AH, and new-DES-expIV with 8 byte IV for new ESP. Key length highly depends on each algorithm. For example, key length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1, and 8 for new-DES-expIV. Now we choose "MYSECRETMYSECRET", "KAMEKAMEKAMEKAMEKAME", "PASSWORD", respectively. OK, let's assign SPI (Security Parameter Index) for each protocol. Please note that we need 3 SPIs for this secure channel since three security headers are produced (one for from HOST A to HOST B, two for from HOST B to HOST A). Please also note that SPI MUST be greater than or equal to 256. We choose, 1000, 2000, and 3000, respectively. (1) HOST A ------> HOST B (1)PROTO=AH ALG=MD5(RFC1826) KEY=MYSECRETMYSECRET SPI=1000 (2.1) HOST A <------ HOST B <------ (2.2) (2.1) PROTO=AH ALG=new-HMAC-SHA1(new AH) KEY=KAMEKAMEKAMEKAMEKAME SPI=2000 (2.2) PROTO=ESP ALG=new-DES-expIV(new ESP) IV length = 8 KEY=PASSWORD SPI=3000 Now, let's setup security association. Execute &man.setkey.8; on both HOST A and B: &prompt.root; setkey -c add 10.2.3.4 10.6.7.8 ah-old 1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ; add 10.6.7.8 10.2.3.4 ah 2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ; add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ; ^D Actually, IPsec communication doesn't process until security policy entries will be defined. In this case, you must setup each host. At A: &prompt.root; setkey -c spdadd 10.2.3.4 10.6.7.8 any -P out ipsec ah/transport/10.2.3.4-10.6.7.8/require ; ^D At B: &prompt.root; setkey -c spdadd 10.6.7.8 10.2.3.4 any -P out ipsec esp/transport/10.6.7.8-10.2.3.4/require ; spdadd 10.6.7.8 10.2.3.4 any -P out ipsec ah/transport/10.6.7.8-10.2.3.4/require ; ^D HOST A --------------------------------------> HOST E 10.2.3.4 10.6.7.8 | | ========== old AH keyed-md5 ==========> <========= new AH hmac-sha1 =========== <========= new ESP des-cbc ============ Transport mode example with IPv6 Another example using IPv6. ESP transport mode is recommended for TCP port number 110 between Host-A and Host-B. ============ ESP ============ | | Host-A Host-B fec0::10 -------------------- fec0::11 Encryption algorithm is blowfish-cbc whose key is "kamekame", and authentication algorithm is hmac-sha1 whose key is "this is the test key". Configuration at Host-A: &prompt.root; setkey -c <<EOF spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec esp/transport/fec0::10-fec0::11/use ; spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec esp/transport/fec0::11-fec0::10/use ; add fec0::10 fec0::11 esp 0x10001 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; add fec0::11 fec0::10 esp 0x10002 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; EOF and at Host-B: &prompt.root; setkey -c <<EOF spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec esp/transport/fec0::11-fec0::10/use ; spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec esp/transport/fec0::10-fec0::11/use ; add fec0::10 fec0::11 esp 0x10001 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; add fec0::11 fec0::10 esp 0x10002 -m transport -E blowfish-cbc "kamekame" -A hmac-sha1 "this is the test key" ; EOF Note the direction of SP. Tunnel mode example with IPv4 Tunnel mode between two security gateways Security protocol is old AH tunnel mode, i.e. specified by RFC1826, with keyed-md5 whose key is "this is the test" as authentication algorithm. ======= AH ======= | | Network-A Gateway-A Gateway-B Network-B 10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24 Configuration at Gateway-A: &prompt.root; setkey -c <<EOF spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec ah/tunnel/172.16.0.1-172.16.0.2/require ; spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec ah/tunnel/172.16.0.2-172.16.0.1/require ; add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any -A keyed-md5 "this is the test" ; add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any -A keyed-md5 "this is the test" ; EOF If port number field is omitted such above then "[any]" is employed. `-m' specifies the mode of SA to be used. "-m any" means wild-card of mode of security protocol. You can use this SA for both tunnel and transport mode. and at Gateway-B: &prompt.root; setkey -c <<EOF spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec ah/tunnel/172.16.0.2-172.16.0.1/require ; spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec ah/tunnel/172.16.0.1-172.16.0.2/require ; add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any -A keyed-md5 "this is the test" ; add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any -A keyed-md5 "this is the test" ; EOF Making SA bundle between two security gateways AH transport mode and ESP tunnel mode is required between Gateway-A and Gateway-B. In this case, ESP tunnel mode is applied first, and AH transport mode is next. ========== AH ========= | ======= ESP ===== | | | | | Network-A Gateway-A Gateway-B Network-B fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64 Tunnel mode example with IPv6 Encryption algorithm is 3des-cbc, and authentication algorithm for ESP is hmac-sha1. Authentication algorithm for AH is hmac-md5. Configuration at Gateway-A: &prompt.root; setkey -c <<EOF spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ; spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ; add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel -E 3des-cbc "kamekame12341234kame1234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport -A hmac-md5 "this is the test" ; add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel -E 3des-cbc "kamekame12341234kame1234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport -A hmac-md5 "this is the test" ; EOF Making SAs with the different end ESP tunnel mode is required between Host-A and Gateway-A. Encryption algorithm is cast128-cbc, and authentication algorithm for ESP is hmac-sha1. ESP transport mode is recommended between Host-A and Host-B. Encryption algorithm is rc5-cbc, and authentication algorithm for ESP is hmac-md5. ================== ESP ================= | ======= ESP ======= | | | | | Host-A Gateway-A Host-B fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2 Configuration at Host-A: &prompt.root; setkey -c <<EOF spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ; spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ; add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001 -m transport -E cast128-cbc "12341234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002 -E rc5-cbc "kamekame" -A hmac-md5 "this is the test" ; add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003 -m transport -E cast128-cbc "12341234" -A hmac-sha1 "this is the test key" ; add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004 -E rc5-cbc "kamekame" -A hmac-md5 "this is the test" ; EOF OpenSSH Contributed by &a.chern;, April 21, 2001. Secure shell is a set of network connectivity tools used to access remote machines securely. It can be used as a direct replacement for rlogin, rsh, rcp, and telnet. Additionaly, any other TCP/IP connections can be tunnelled/forwarded securely through ssh. ssh encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks. OpenSSH is maintained by the OpenBSD project, and is based upon SSH v1.2.12 with all the recent bug fixes and updates. It is compatible with both SSH protocols 1 and 2. OpenSSH has been in the base system since FreeBSD 4.0. Advantages of using OpenSSH Normally, when using &man.telnet.1; or &man.rlogin.1;, data is sent over the network in an clear, un-encrypted form. Network sniffers anywhere in between the client and server can steal your user/password information or data transferred in your session. OpenSSH offers a variety of authentication and encryption methods to prevent this from happening. Enabling sshd Be sure to make the following additions to your rc.conf file: sshd_enable="YES" This will load the ssh daemon the next time your system inializes. Alternatively, you can simply run the sshd daemon. SSH client The &man.ssh.1; utility works similarly to &man.rlogin.1;. &prompt.root ssh user@foobardomain.com Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)? yes Host 'foobardomain.com' added to the list of known hosts. user@foobardomain.com's password: ******* The login will continue just as it would have if a session was created using rlogin or telnet. SSH utilizes a key fingerprint system for verifying the authenticity of the server when the client connects. The user is prompted to enter 'yes' only during the first time connecting. Future attempts to login are all verified against the saved fingerprint key. The SSH client will alert you if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in ~/.ssh/known_hosts Secure copy The scp command works similarly to rcp; it copies a file to or from a remote machine, except in a secure fashion. &prompt.root scp user@foobardomain.com:/COPYRIGHT COPYRIGHT user@foobardomain.com's password: COPYRIGHT 100% |*****************************| 4735 00:00 &prompt.root Since the fingerprint was already saved for this host in the previous example, it is verified when using scp here. Configuration The system-wide configuration files for both the OpenSSH daemon and client reside within the /etc/ssh directory. ssh_config configures the client settings, while sshd_config configures the daemon. ssh-keygen Instead of using passwords, &man.ssh-keygen.1; can be used to generate RSA keys to authenticate a user. &prompt.user ssh-keygen Initializing random number generator... Generating p: .++ (distance 66) Generating q: ..............................++ (distance 498) Computing the keys... Key generation complete. Enter file in which to save the key (/home/user/.ssh/identity): Enter passphrase: Enter the same passphrase again: Your identification has been saved in /home/user/.ssh/identity. ... &man.ssh-keygen.1; will create a public and private key pair for use in authentication. The private key is stored in ~/.ssh/identity, whereas the public key is stored in ~/.ssh/identity.pub. The public key must be placed in ~/.ssh/authorized_keys of the remote machine in order for the setup to work. This will allow connection to the remote machine based upon RSA authentication instead of passwords. If a passphrase is used in &man.ssh-keygen.1;, the user will be prompted for a password each time in order to use the private key. &man.ssh-agent.1; and &man.ssh-add.1; are utilities used in managing multiple passworded private keys. SSH Tunneling OpenSSH has the ability to create a tunnel to encapsulate another protocol in an encrypted session. The following command tells &man.ssh.1; to create a tunnel for telnet. &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.bar.com &prompt.user; -2 this forces &man.ssh.1 to use version 2 of the protocol. (Do not use if you are working with older ssh servers) -N indicates no command, or tunnel only. If ommitted, &man.ssh.1; would initiate a normal session. -f forces &man.ssh.1; to run in the background. -L indicates a local tunnel in localport:localhost:remoteport fashion. foo.bar.com is the remote/target SSH server. An SSH tunnel works by creating a listen socket on the specified local host and port. It then forwards any connection to the local host/port via the SSH connection to the remote machine on the specified remote port. In the example, port 5023 on localhost is being forwarded to port 23 on the remote machine. Since 23 is telnet, this would create a secure telnet session through an SSH tunnel. This can be used to wrap any number of insecure TCP protocols such as smtp, pop3, ftp, etc. A typical SSH Tunnel &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.foobar.com user@mailserver.foobar.com's password: ***** &prompt.user; telnet localhost 5025 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 220 mailserver.foobar.com ESMTP This can be used in conjunction with an &man.ssh-keygen.1; and additional user accounts to create a more seamless/hassle-free SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a seperate user. Further Reading OpenSSH &man.ssh.1; &man.scp.1; &man.ssh-keygen.1; &man.ssh-agent.1; &man.ssh-add.1; &man.sshd.8; &man.sftp-server.8; diff --git a/en_US.ISO_8859-1/books/porters-handbook/book.sgml b/en_US.ISO_8859-1/books/porters-handbook/book.sgml index f425e7553e..e694c885cc 100644 --- a/en_US.ISO_8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO_8859-1/books/porters-handbook/book.sgml @@ -1,4480 +1,4482 @@ %man; %bookinfo; %authors; %mailing-lists; ]> FreeBSD Porter's Handbook The FreeBSD Documentation Project April 2000 2000 The FreeBSD Documentation Project &bookinfo.legalnotice; Making a port yourself So, now 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 bsd.port.mk. This file uses a non-standard tab setting. Emacs and Vim should recognize the setting on loading the file. Both vi and ex 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 enough, but we will see. 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 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 three description files that are required for any port, whether they actually package or not. They are pkg-comment, pkg-descr, and pkg-plist, and their pkg- prefix distinguishes them from other files. <filename>pkg-comment</filename> This is the 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: A cat chasing a mouse all over the screen <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; man 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. 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. The latter one helps the committers a lot, who use scripts for the ports-work. One more time, do not include the original source distfile, the work directory, or the package you built with make package. In the past, we asked you to upload new port submissions in our ftp site (ftp.FreeBSD.org). This is no longer recommended as read access is turned off on the incoming/ directory of that site due to the large amount of pirated software showing up there. We will look at your port, get back to you if necessary, and put it in the tree. Your name will also appear in the list of “Additional FreeBSD contributors” in the FreeBSD Handbook and other files. Isn't that great?!? :-) 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: <short description of the port>” for new ports and “Update port: <category>/<port> <short description of the update>” for port updates. If you stick to this scheme, the chance that one takes a look at your PR soon is much bigger. 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 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/, 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 touch extract! 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. 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). Make sure you set MASTER_SITES to reflect your choice. If you cannot find somewhere convenient and reliable to put the distfile we can “house” it ourselves on ftp.FreeBSD.org. 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 for no good reason, consider putting the distfile in your home page and listing it as the first MASTER_SITES. This 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 diff for later feeding to patch. 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). 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, then 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). 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 CD-ROMs 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. <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. PORTREVISION is increased each time a change is made to the FreeBSD port which significantly affects the content or stucture 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 FreeBSD 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 behaviour 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 effect 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 no package was 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 someone, somewhere, would benefit from having (either because of an enhancement, fix, or by virtue that the new package will actually work for them). If yes, the PORTREVISION should be bumped so that automated tools (e.g. pkg_version) will highlight the fact that a new package is available. <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 is never 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 (2000801), but the ,1 suffix is treated specially by automated tools and found to be greater than the implied suffix ",0" on the earlier package) 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. <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, use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. <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 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 when 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>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 CD-ROM. Please take a look at the existing 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 the categories section 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. <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, and we are even planning to add support for automatically determining the closest master site and fetching from there! 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 archives 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>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. Note that 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. <makevar>MAINTAINER</makevar> Set your mail-address here. Please. :-) For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section. Dependencies Many ports depend on other ports. There are five 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 behaviour 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 pkg_add 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= ${PREFIX}/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 in to the package so that pkg_add 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>DEPENDS</makevar> If there is a dependency that does not fall into either of the above four 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. Common dependency variables 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=yes if your port requires GNU autoconf to be run. Define USE_QT=yes 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. 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 the to get to 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 behaviour 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. Optional dependencies Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to decide which configuration should be built. Supporting these properly will make uses happy, and effectively provide 2 or more ports for the price of one. The easiest of these to use is WITHOUT_X11. If the port can be built both with and without X support, then it should normally be built with X support. If WITHOUT_X11 is defined, then the version that does not have X support should be built. Various parts of GNOME have such knobs, though they are slightly more difficult to use. The variables to use in the Makefile are WANT_* and HAVE_*. If the application can be built both with or without one of the dependencies listed below, then the Makefile should set WANT_PKG, and should build the version that uses PKG if HAVE_PKG is defined. The WANT_* variables currently supported this way are WANT_GLIB, WANT_GTK, WANT_ESOUND, WANT_IMLIB, and WANT_GNOME. 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=yes. This implies GNU_CONFIGURE, and will cause autoconf to be run before configure. 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 deinstallation will not cause the system to still believe the library is there. If you need, you can override default location where the new library is installed by defining 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. <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 Makefiles, 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>REQUIRES_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 to use 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 is new to XFree86 release 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 The new version of texinfo (included in 2.2.2-RELEASE and onwards) contains a utility called install-info to add and delete entries to the dir file. If your port installs any info documents, please follow these instructions so your port/package will correctly update the user's PREFIX/info/dir file. (Sorry for the length of this section, but is it imperative to weave all the info files together. If done correctly, it will produce a beautiful listing, so please bear with me! First, this is what you (as a porter) need to know &prompt.user; install-info --help install-info [OPTION]... [INFO-FILE [DIR-FILE]] Install INFO-FILE in the Info directory file DIR-FILE. Options: --delete Delete existing entries in INFO-FILE; don't insert any new entries. : --entry=TEXT Insert TEXT as an Info directory entry. : --section=SEC Put this file's entries in section SEC of the directory. : This program will not actually install info files; it merely inserts or deletes entries in the dir file. Here's a seven-step procedure to convert ports to use install-info. editors/emacs will be used as an example. Look at the texinfo sources and make a patch to insert @dircategory and @direntry statements to files that do not have them. This is part of my patch: --- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 +++ ./man/vip.texi Tue May 20 01:28:33 1997 @@ -2,6 +2,10 @@ @setfilename ../info/vip @settitle VIP +@dircategory The Emacs editor and associated tools +@direntry +* VIP: (vip). A VI-emulation for Emacs. +@end direntry @iftex @finalout : The format should be self-explanatory. Many authors leave a dir file in the source tree that contains all the entries you need, so look around before you try to write your own. Also, make sure you look into related ports and make the section names and entry indentations consistent (we recommend that all entry text start at the 4th tab stop). Note that you can put only one info entry per file because of a bug in install-info --delete that deletes only the first entry if you specify multiple entries in the @direntry section. You can give the dir entries to install-info as arguments ( and ) instead of patching the texinfo sources. This probably is not a good idea for ports because you need to duplicate the same information in three places (Makefile and @exec/@unexec of pkg-plist; see below). However, if you have Japanese (or other multibyte encoding) info files, you will have to use the extra arguments to install-info because makeinfo cannot handle those texinfo sources. (See Makefile and pkg-plist of japanese/skk for examples on how to do this). Go back to the port directory and do a make clean; make and verify that the info files are regenerated from the texinfo sources. Since the texinfo sources are newer than the info files, they should be rebuilt when you type make; but many Makefiles do not include correct dependencies for info files. In emacs' case, it was necessary to patch the main Makefile.in so it would descend into the man subdirectory to rebuild the info pages. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Tue Apr 15 00:15:28 1997 @@ -184,7 +184,7 @@ # Subdirectories to make recursively. `lisp' is not included # because the compiled lisp files are part of the distribution # and you cannot remake them without installing Emacs first. -SUBDIR = lib-src src +SUBDIR = lib-src src man # The makefiles of the directories in $SUBDIR. SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile --- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 +++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 @@ -66,6 +66,7 @@ ${srcdir}/gnu1.texi \ ${srcdir}/glossary.texi +all: info info: $(INFO_TARGETS) dvi: $(DVI_TARGETS) The second hunk was necessary because the default target in the man subdir is called info, while the main Makefile wants to call all. The installation of the info info file was also removed because we already have one with the same name in /usr/share/info (that patch is not shown here). If there is a place in the Makefile that is installing the dir file, delete it. Your port may not be doing it. Also, remove any commands that are otherwise mucking around with the dir file. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Mon Apr 14 23:38:07 1997 @@ -368,14 +368,8 @@ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ then \ (cd ${infodir}; \ - if [ -f dir ]; then \ - if [ ! -f dir.old ]; then mv -f dir dir.old; \ - else mv -f dir dir.bak; fi; \ - fi; \ cd ${srcdir}/info ; \ - (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \ - (cd $${thisdir}; chmod a+r ${infodir}/dir); \ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ (cd $${thisdir}; \ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ chmod a+r ${infodir}/$$f); \ (This step is only necessary if you are modifying an existing port.) Take a look at pkg-plist and delete anything that is trying to patch up info/dir. They may be in pkg-install or some other file, so search extensively. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/04/15 06:32:12 @@ -15,9 +15,6 @@ man/man1/emacs.1.gz man/man1/etags.1.gz man/man1/ctags.1.gz -@unexec cp %D/info/dir %D/info/dir.bak -info/dir -@unexec cp %D/info/dir.bak %D/info/dir info/cl info/cl-1 info/cl-2 Add a post-install target to the Makefile to call install-info with the installed info files. (It is no longer necessary to create the dir file yourself; install-info automatically creates this file if it does not exist.) Index: Makefile =================================================================== RCS file: /usr/cvs/ports/editors/emacs/Makefile,v retrieving revision 1.26 diff -u -r1.26 Makefile --- Makefile 1996/11/19 13:14:40 1.26 +++ Makefile 1997/05/20 10:25:09 1.28 @@ -20,5 +20,8 @@ post-install: .for file in emacs-19.34 emacsclient etags ctags b2m strip ${PREFIX}/bin/${file} .endfor +.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode + install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir +.endfor .include <bsd.port.mk> Edit pkg-plist and add equivalent @exec statements and also @unexec for pkg_delete. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/05/20 10:25:12 1.17 @@ -16,7 +14,14 @@ man/man1/etags.1.gz man/man1/ctags.1.gz +@unexec install-info --delete %D/info/emacs %D/info/dir : +@unexec install-info --delete %D/info/ccmode %D/info/dir info/cl info/cl-1 @@ -87,6 +94,18 @@ info/viper-3 info/viper-4 +@exec install-info %D/info/emacs %D/info/dir : +@exec install-info %D/info/ccmode %D/info/dir libexec/emacs/19.34/i386--freebsd/cvtmail libexec/emacs/19.34/i386--freebsd/digest-doc The @unexec install-info --delete commands have to be listed before the info files themselves so they can read the files. Also, the @exec install-info commands have to be after the info files and the @exec command that creates the the dir file. Test and admire your work. :-). Check the dir file before and after each step. 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 pkg_add 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 pkg_add you can do this via the pkg-install script. This script will automatically be added to the package, and will be run twice by pkg_add. 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-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/deinstallation time to determine whether or not installation/deinstallation should proceed. 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., 2.2.7). %%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). 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 man pages) will be done between the do-install and post-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 do-install. Also, if your port needs to edit the resulting file, do so in post-install to a file named TMPPLIST. 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 in to the pkg-* subdirectory). Here is a list of variable names and their default values. (PKGDIR defaults to ${MASTERDIR}.) Variable Default value COMMENT ${PKGDIR}/pkg-comment 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. Licensing Problems Some software packages have restrictive licenses or can be in violation of the law in some countries (such as violating a patent). What we can do with them varies a lot, depending on the exact wordings of the respective licenses. 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 or CD-ROM. If in doubt, please contact the &a.ports;. There are two variables you can set in the Makefile to handle the situations that arise frequently: If the port has a “do not sell for profit” type of license, set the variable NO_CDROM to a string describing the reason why. We will make sure such ports will not go into the CD-ROM come release time. The distfile and package will still be available via ftp. If the resulting package needs to be built uniquely for each site, or the resulting binary package cannot be distributed due to licensing; set the variable NO_PACKAGE to a string describing the reason why. We will make sure such packages will not go on the ftp site, nor into the CD-ROM come release time. The distfile will still be included on both however. If the port has legal restrictions on who can use it (e.g., patented stuff) or has a “no commercial use” license, set the variable RESTRICTED to be the string describing the reason why. For such ports, the distfiles/packages will not be available even from our ftp sites. The GNU General Public License (GPL), both version 1 and 2, should not be a problem for ports. If you are a committer, make sure you update the ports/LEGAL file too. Upgrading When you notice that a port is out of date compared to the latest version from the original authors, first make sure you have the latest port. You can find them in the ports/ports-current directory of the ftp mirror sites. You may also use CVSup to keep your whole ports collection up-to-date, as described in the Handbook. The next step is to send a mail to the maintainer, if one is listed in the port's Makefile. 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). If the maintainer asks you to do the upgrade or there is not any such person to begin with, please make the upgrade and send the recursive diff (either unified or context diff is fine, but port committers appear to prefer unified diff more) of the new and old ports directories to us (e.g., if your modified port directory is called superedit and the original as in our tree is superedit.bak, then send us the result of diff -ruN superedit.bak superedit). Please examine the output to make sure all the changes make sense. The best way to send us the diff is by including it via &man.send-pr.1; (category ports). Please mention any added or deleted files in the message, as they have to be explicitly specified to CVS 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. Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! <anchor id="porting-dads">Dos and Don'ts 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. Strip Binaries Do strip binaries. If the original source already strips the binaries, fine; otherwise you should add a post-install rule to to it yourself. Here is an example: post-install: strip ${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. 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 compiling ports from 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 FreeBSD 1.x 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 Berkeleyisms, not FreeBSD changes. In FreeBSD 2.x, __FreeBSD__ is defined to be 2. In earlier versions, it is 1. Later versions will 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 3.x 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 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 semctl(2) change + 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 mount(2) change + 3.0-CURRENT before &man.mount.2; change 300000 - 3.0-CURRENT after mount(2) change + 3.0-CURRENT after &man.mount.2; change 300001 - 3.0-CURRENT after semctl(2) change + 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 mkstemps() to libc + 3.3-STABLE after adding &man.mkstemp.3; + to libc 330002 3.4-RELEASE 340000 3.4-STABLE 340001 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 dladdr(3) + 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 suser(9) API change + 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 jail(2) + 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 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 setproctitle() moved from + 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 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 setproctitle() moved from + 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 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. 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. 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 pre.mk/post.mk pair or bsd.port.mk only; do not mix these two. 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, same as __FreeBSD_version. PORTOBJFORMAT The object format of the system (aout or elf) 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 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 to the variable NOPORTDOCS so that users can disable it in /etc/make.conf, like this: post-install: .if !defined(NOPORTDOCS) ${MKDIR} ${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif Do not forget to add them to pkg-plist too. (Do not worry about NOPORTDOCS here; there is currently no way for the packages to read variables from /etc/make.conf.) You can also use the pkg-message file to display messages upon installation. See the using pkg-message section for details. pkg-message does not need to be added to pkg-plist. <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. Package information Do include package information, i.e. pkg-comment, pkg-descr, and pkg-plist. Note that these files are not used only for packaging anymore, and are mandatory now, even if NO_PACKAGE is set. RCS strings 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. Recursive diff Using the recurse () option to diff 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=yes and take the diffs of configure.in. 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. <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).) Not hard-coding /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 isn't 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, making the package creation process will complain that it can't 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 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. 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 bode 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 &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 deinstalled. 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 pkg_delete 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 99 and register it below. Look at japanese/Wnn 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 99. majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh 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:/nonexistent wnn:*:69:7:Wnn:/nonexistent:/nonexistent ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent qmaill:*:83:81:QMail user:/var/qmail:/nonexistent qmaild:*:82:81:QMail user:/var/qmail:/nonexistent qmailq:*:85:82:QMail user:/var/qmail:/nonexistent qmails:*:87:82:QMail user:/var/qmail:/nonexistent qmailp:*:84:81:QMail user:/var/qmail:/nonexistent qmailr:*:86:82:QMail user:/var/qmail:/nonexistent msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent 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}. Respect <makevar>CFLAGS</makevar> The port should respect the CFLAGS variable. 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 pkg_delete 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. Portlint Do check your work with portlint before you submit or commit it. 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. Miscellanea The files pkg-comment, 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 [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. Create an empty pkg-plist. &prompt.root; touch pkg-plist Next, create a new set of directories which your port can be installed, and install any dependencies. &prompt.root; mtree -U -f /etc/mtree/BSD.local.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 * -type d) > OLD-DIRS 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 * \! -type d) > pkg-plist You must also add any newly created directories to the packing list. &prompt.root; (cd /var/tmp/port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm #' >> pkg-plist Finally, you need to tidy up the packing list by hand; it isn't 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. Package Names 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 lots and lots 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. Categories As you already know, ports are classified in several categories. But for this to work, it is important that porters and users understand what each category is for and how we decide what to put in each category. Current list of categories First, this 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. For non-virtual categories, you will find a one-line description in the pkg/COMMENT file in that subdirectory (e.g., archivers/pkg/COMMENT). Category Description afterstep* Ports to support the AfterStep window manager. 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. 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. 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 GNU Object Model Environment (GNOME) Project. graphics Graphics utilities. hebrew Hebrew language support. irc Internet Relay Chat utilities. ipv6* IPv6 related software. japanese Japanese language support. java Java language support. kde* Ports from the K Desktop Environment (KDE) Project. korean Korean language support. lang Programming languages. linux* Linux applications and support utilities. 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. This is the only category that 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! net Miscellaneous networking software. news USENET news software. offix* Ports from the OffiX suite. palm Software support for the 3Com Palm(tm) series. perl5* Ports that require perl version 5 to run. picobsd Ports to support PicoBSD. plan9* Various programs from Plan9. print Printing software. Desktop publishing tools (previewers, etc.) belong here too. python* Software written in python. ruby* Software written in ruby. russian Russian language support. science Scientific ports that don't 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. 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. 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. If your port is an X application, define USE_XLIB (implied by USE_IMAKE) and put it in the appropriate categories. Also, many of them go into other x11-* categories (see below). 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. 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 win over less-specific ones. For instance, an HTML editor should be listed as www editors, not the other way around. Also, you do not need to list net when the port belongs to any of irc, mail, mbone, news, security, or www. 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. 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 send-pr 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. Changes to this document and the ports system If you maintain a lot of ports, you should consider following the &a.ports;. Important changes to the way ports work will be announced there. You can always find more detailed information on the latest changes by looking at the bsd.port.mk CVS log. That is It, Folks! Boy, this sure was a long tutorial, wasn't it? Thanks for following us to here, really. Now that you know how to do a port, have at it and convert everything in the world into ports! That is the easiest way to start contributing to the FreeBSD Project! :-)