diff --git a/en_US.ISO8859-1/articles/contributing/article.xml b/en_US.ISO8859-1/articles/contributing/article.xml index ac6d5f2450..b0a45facaa 100644 --- a/en_US.ISO8859-1/articles/contributing/article.xml +++ b/en_US.ISO8859-1/articles/contributing/article.xml @@ -1,551 +1,549 @@
Contributing to FreeBSD This article describes the different ways in which an individual or organization may contribute to the FreeBSD Project. Jordan Hubbard Contributed by &tm-attrib.freebsd; &tm-attrib.ieee; &tm-attrib.general; $FreeBSD$ $FreeBSD$ contributing So you want to contribute to FreeBSD? That is great! FreeBSD relies on the contributions of its user base to survive. Your contributions are not only appreciated, they are vital to FreeBSD's continued growth. Contrary to what some people might have you believe, you do not need to be a hot-shot programmer or a close personal friend of the FreeBSD core team to have your contributions accepted. A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD. There is always more work to be done than there are people available to do it, and more help is always appreciated. The FreeBSD project is responsible for an entire operating system environment, rather than just a kernel or a few scattered utilities. As such, our TODO lists span a very wide range of tasks: from documentation, beta testing and presentation, to the system installer and highly specialized types of kernel development. People of any skill level, in almost any area, can almost certainly help the project. Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us. Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish. Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it. The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look. What Is Needed The following list of tasks and sub-projects represents something of an amalgam of various TODO lists and user requests. Ongoing Non-Programmer Tasks Many people who are involved in FreeBSD are not programmers. The Project includes documentation writers, Web designers, and support people. All that these people need to contribute is an investment of time and a willingness to learn. Read through the FAQ and Handbook periodically. If anything is badly explained, out of date or even just completely wrong, let us know. Even better, send us a fix (Docbook is not difficult to learn, but there is no objection to ASCII submissions). Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date. First take a look at the Translations FAQ in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this — as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. Read the &a.questions; and &ng.misc; occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to work on. Ongoing Programmer Tasks Most of the tasks listed here require either a considerable investment of time, or an in-depth knowledge of the FreeBSD kernel, or both. However, there are also many useful tasks which are suitable for weekend hackers. If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine current.FreeBSD.org which builds a full release once a day—every now and again, try to install the latest release from it and report any failures in the process. Read the &a.bugs;. There might be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. If you know of any bug fixes which have been successfully applied to -CURRENT but have not been merged into -STABLE after a decent interval (normally a couple of weeks), send the committer a polite reminder. Move contributed software to src/contrib in the source tree. Make sure code in src/contrib is up to date. Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings. Fix warnings for ports which do deprecated things like using gets() or including malloc.h. If you have contributed any ports and you had to make &os;-specific changes, send your patches back to the original authors (this will make your life easier when they bring out the next version). Get copies of formal standards like &posix;. You can get some links about these standards at the FreeBSD C99 & POSIX Standards Conformance Project web site. Compare FreeBSD's behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. If you are able, figure out how to fix it and include a patch in the PR. If you think the standard is wrong, ask the standards body to consider the question. Suggest further tasks for this list! Work through the PR Database problem reports database The FreeBSD PR list shows all the current active problem reports and requests for enhancement that have been submitted by FreeBSD users. The PR database includes both programmer and non-programmer tasks. Look through the open PRs, and see if anything there takes your interest. Some of these might be very simple tasks that just need an extra pair of eyes to look over them and confirm that the fix in the PR is a good one. Others might be much more complex, or might not even have a fix included at all. Start with the PRs that have not been assigned to anyone else. If a PR is assigned to someone else, but it looks like something you can handle, email the person it is assigned to and ask if you can work on it—they might already have a patch ready to be tested, or further ideas that you can discuss with them. Pick one of the items from the <quote>Ideas</quote> page The &os; list of projects and ideas for volunteers is also available for people willing to contribute to the &os; project. The list is being regularly updated and contains items for both programmers and non-programmers with information about each project. How to Contribute Contributions to the system generally fall into one or more of the following 5 categories: Bug Reports and General Commentary An idea or suggestion of general technical interest should be mailed to the &a.hackers;. Likewise, people with an interest in such things (and a tolerance for a high volume of mail!) may subscribe to the &a.hackers;. See The FreeBSD Handbook for more information about this and other mailing lists. If you find a bug or are submitting a specific change, please report it using the &man.send-pr.1; program or its WEB-based equivalent. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put [PATCH] in the synopsis of the report. When including patches, do not use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. When patches are a lot larger than 20KB, consider compressing them (eg. with &man.gzip.1; or &man.bzip2.1;) and using &man.uuencode.1; to include their compressed form in your problem report. After filing a report, you should receive confirmation along with a tracking number. Keep this tracking number so that you can update us with details about the problem by sending mail to &a.bugfollowup;. Use the number as the message subject, e.g. "Re: kern/3377". Additional information for any bug report should be submitted this way. If you do not receive confirmation in a timely fashion (3 days to a week, depending on your email connection) or are, for some reason, unable to use the &man.send-pr.1; command, then you may ask someone to file it for you by sending mail to the &a.bugs;. See also this article on how to write good problem reports. Changes to the Documentation documentation submissions Changes to the documentation are overseen by the &a.doc;. Please look at the FreeBSD Documentation Project Primer for complete instructions. Send submissions and changes (even small ones are welcome!) using &man.send-pr.1; as described in Bug Reports and General Commentary. Changes to Existing Source Code FreeBSD-CURRENT An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as FreeBSD-CURRENT which is made available in a variety of ways for the convenience of developers working actively on the system. See The FreeBSD Handbook for more information about getting and using FreeBSD-CURRENT. Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the &a.announce; and the &a.current; lists, where discussions on the current state of the system take place. Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the &man.diff.1; command. The preferred &man.diff.1; format for submitting patches is the unified output format generated by diff -u. diff &prompt.user; diff -u oldfile newfile or &prompt.user; diff -u -r -N olddir newdir would generate a set of unified diffs for the given source file or directory hierarchy. See &man.diff.1; for more information. Once you have a set of diffs (which you may test with the &man.patch.1; command), you should submit them for inclusion with FreeBSD. Use the &man.send-pr.1; program as described in Bug Reports and General Commentary. Do not just send the diffs to the &a.hackers; or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including [PATCH] in the synopsis of the report. uuencode If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a tar file and run the &man.uuencode.1; program on it. Archives created with &man.shar.1; are also welcome. If your change is of a potentially sensitive nature, such as if you are unsure of copyright issues governing its further distribution then you should send it to &a.core; directly rather than submitting it with &man.send-pr.1;. The &a.core; reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also very busy and so you should only send mail to them where it is truly necessary. Please refer to &man.intro.9; and &man.style.9; for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. New Code or Major Value-Added Packages In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as uuencoded tar files or upload them to a web or FTP site for other people to access. If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are: - BSD copyright - - The BSD copyright. This copyright is most preferred + The BSD copyrightBSD copyright. This copyright is most preferred due to its no strings attached nature and general attractiveness to commercial enterprises. Far from discouraging such commercial use, the FreeBSD Project actively encourages such participation by commercial interests who might eventually be inclined to invest something of their own into FreeBSD. + GPL GNU General Public License GNU General Public License - - The GNU General Public License, or GPL. + The GNU General Public License, or GPL. This license is not quite as popular with us due to the amount of extra effort demanded of anyone using the code for commercial purposes, but given the sheer quantity of GPL'd code we currently require (compiler, assembler, text formatter, etc) it would be silly to refuse additional contributions under this license. Code under the GPL also goes into a different part of the tree, that being /sys/gnu or /usr/src/gnu, and is therefore easily identifiable to anyone for whom the GPL presents a problem. Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will be considered. Contributions for which particularly restrictive commercial copyrights apply are generally rejected, though the authors are always encouraged to make such changes available through their own channels. To place a BSD-style copyright on your work, include the following text at the very beginning of every source code file you wish to protect, replacing the text between the %% with the appropriate information: Copyright (c) %%proper_years_here%% %%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $&os;$ For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright. Money, Hardware or Internet Access We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves. <anchor id="donations"/>Donating Funds The FreeBSD Foundation is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax. Donations to a tax-exempt entity are often deductible from taxable federal income. Donations may be sent in check form to:
The FreeBSD Foundation P.O. Box 20247, Boulder, CO 80308 USA
The FreeBSD Foundation is now able to accept donations through the web with PayPal. To place a donation, please visit the Foundation web site. More information about the FreeBSD Foundation can be found in The FreeBSD Foundation -- an Introduction. To contact the Foundation by email, write to bod@FreeBSDFoundation.org. Donating Hardware donations The FreeBSD Project happily accepts donations of hardware that it can find good use for. If you are interested in donating hardware, please contact the Donations Liaison Office.
diff --git a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml index af76ac8d6d..5d92602d5d 100644 --- a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml @@ -1,2013 +1,2006 @@ Sergey Babkin Written by Murray Stokely Modifications for Handbook made by Common Access Method SCSI Controllers Synopsis SCSI This document assumes that the reader has a general understanding of device drivers in FreeBSD and of the SCSI protocol. Much of the information in this document was extracted from the drivers: ncr (/sys/pci/ncr.c) by Wolfgang Stanglmeier and Stefan Esser sym (/sys/dev/sym/sym_hipd.c) by Gerard Roudier aic7xxx (/sys/dev/aic7xxx/aic7xxx.c) by Justin T. Gibbs and from the CAM code itself (by Justin T. Gibbs, see /sys/cam/*). When some solution looked the most logical and was essentially verbatim extracted from the code by Justin T. Gibbs, I marked it as recommended. The document is illustrated with examples in pseudo-code. Although sometimes the examples have many details and look like real code, it is still pseudo-code. It was written to demonstrate the concepts in an understandable way. For a real driver other approaches may be more modular and efficient. It also abstracts from the hardware details, as well as issues that would cloud the demonstrated concepts or that are supposed to be described in the other chapters of the developers handbook. Such details are commonly shown as calls to functions with descriptive names, comments or pseudo-statements. Fortunately real life full-size examples with all the details can be found in the real drivers. General Architecture Common Access Method (CAM) CAM stands for Common Access Method. It is a generic way to address the I/O buses in a SCSI-like way. This allows a separation of the generic device drivers from the drivers controlling the I/O bus: for example the disk driver becomes able to control disks on both SCSI, IDE, and/or any other bus so the disk driver portion does not have to be rewritten (or copied and modified) for every new I/O bus. Thus the two most important active entities are: CD-ROM tape IDE Peripheral Modules - a driver for peripheral devices (disk, tape, CD-ROM, etc.) SCSI Interface Modules (SIM) - a Host Bus Adapter drivers for connecting to an I/O bus such as SCSI or IDE. A peripheral driver receives requests from the OS, converts them to a sequence of SCSI commands and passes these SCSI commands to a SCSI Interface Module. The SCSI Interface Module is responsible for passing these commands to the actual hardware (or if the actual hardware is not SCSI but, for example, IDE then also converting the SCSI commands to the native commands of the hardware). Because we are interested in writing a SCSI adapter driver here, from this point on we will consider everything from the SIM standpoint. A typical SIM driver needs to include the following CAM-related header files: #include <cam/cam.h> #include <cam/cam_ccb.h> #include <cam/cam_sim.h> #include <cam/cam_xpt_sim.h> #include <cam/cam_debug.h> #include <cam/scsi/scsi_all.h> The first thing each SIM driver must do is register itself with the CAM subsystem. This is done during the driver's xxx_attach() function (here and further xxx_ is used to denote the unique driver name prefix). The xxx_attach() function itself is called by the system bus auto-configuration code which we do not describe here. This is achieved in multiple steps: first it is necessary to allocate the queue of requests associated with this SIM: struct cam_devq *devq; if(( devq = cam_simq_alloc(SIZE) )==NULL) { error; /* some code to handle the error */ } Here SIZE is the size of the queue to be allocated, maximal number of requests it could contain. It is the number of requests that the SIM driver can handle in parallel on one SCSI card. Commonly it can be calculated as: SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET Next we create a descriptor of our SIM: struct cam_sim *sim; if(( sim = cam_sim_alloc(action_func, poll_func, driver_name, softc, unit, max_dev_transactions, max_tagged_dev_transactions, devq) )==NULL) { cam_simq_free(devq); error; /* some code to handle the error */ } Note that if we are not able to create a SIM descriptor we free the devq also because we can do nothing else with it and we want to conserve memory. - SCSIbus - If a SCSI card has multiple SCSI buses on it then each bus + If a SCSI card has multiple SCSI busesSCSIbus on it then each bus requires its own cam_sim structure. An interesting question is what to do if a SCSI card has more than one SCSI bus, do we need one devq structure per card or per SCSI bus? The answer given in the comments to the CAM code is: either way, as the driver's author prefers. The arguments are: action_func - pointer to the driver's xxx_action function. static void xxx_action struct cam_sim *sim, union ccb *ccb poll_func - pointer to the driver's xxx_poll() static void xxx_poll struct cam_sim *sim driver_name - the name of the actual driver, such as ncr or wds. softc - pointer to the driver's internal descriptor for this SCSI card. This pointer will be used by the driver in future to get private data. unit - the controller unit number, for example for controller wds0 this number will be 0 max_dev_transactions - maximal number of simultaneous transactions per SCSI target in the non-tagged mode. This value will be almost universally equal to 1, with possible exceptions only for the non-SCSI cards. Also the drivers that hope to take advantage by preparing one transaction while another one is executed may set it to 2 but this does not seem to be worth the complexity. max_tagged_dev_transactions - the same thing, but in the tagged mode. Tags are the SCSI way to initiate multiple transactions on a device: each transaction is assigned a unique tag and the transaction is sent to the device. When the device completes some transaction it sends back the result together with the tag so that the SCSI adapter (and the driver) can tell which transaction was completed. This argument is also known as the maximal tag depth. It depends on the abilities of the SCSI adapter. - SCSIadapter Finally we register the SCSI buses associated with our SCSI - adapter: + adapterSCSIadapter: if(xpt_bus_register(sim, bus_number) != CAM_SUCCESS) { cam_sim_free(sim, /*free_devq*/ TRUE); error; /* some code to handle the error */ } If there is one devq structure per SCSI bus (i.e., we consider a card with multiple buses as multiple cards with one bus each) then the bus number will always be 0, otherwise each bus on the SCSI card should be get a distinct number. Each bus needs its own separate structure cam_sim. After that our controller is completely hooked to the CAM system. The value of devq can be discarded now: sim will be passed as an argument in all further calls from CAM and devq can be derived from it. CAM provides the framework for such asynchronous events. Some events originate from the lower levels (the SIM drivers), some events originate from the peripheral drivers, some events originate from the CAM subsystem itself. Any driver can register callbacks for some types of the asynchronous events, so that it would be notified if these events occur. A typical example of such an event is a device reset. Each transaction and event identifies the devices to which it applies by the means of path. The target-specific events normally occur during a transaction with this device. So the path from that transaction may be re-used to report this event (this is safe because the event path is copied in the event reporting routine but not deallocated nor passed anywhere further). Also it is safe to allocate paths dynamically at any time including the interrupt routines, although that incurs certain overhead, and a possible problem with this approach is that there may be no free memory at that time. For a bus reset event we need to define a wildcard path including all devices on the bus. So we can create the path for the future bus reset events in advance and avoid problems with the future memory shortage: struct cam_path *path; if(xpt_create_path(&path, /*periph*/NULL, cam_sim_path(sim), CAM_TARGET_WILDCARD, CAM_LUN_WILDCARD) != CAM_REQ_CMP) { xpt_bus_deregister(cam_sim_path(sim)); cam_sim_free(sim, /*free_devq*/TRUE); error; /* some code to handle the error */ } softc->wpath = path; softc->sim = sim; As you can see the path includes: ID of the peripheral driver (NULL here because we have none) ID of the SIM driver (cam_sim_path(sim)) SCSI target number of the device (CAM_TARGET_WILDCARD means all devices) SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means all LUNs) If the driver can not allocate this path it will not be able to work normally, so in that case we dismantle that SCSI bus. And we save the path pointer in the softc structure for future use. After that we save the value of sim (or we can also discard it on the exit from xxx_probe() if we wish). That is all for a minimalistic initialization. To do things right there is one more issue left. For a SIM driver there is one particularly interesting event: when a target device is considered lost. In this case resetting the SCSI negotiations with this device may be a good idea. So we register a callback for this event with CAM. The request is passed to CAM by requesting CAM action on a CAM control block for this type of request: struct ccb_setasync csa; xpt_setup_ccb(&csa.ccb_h, path, /*priority*/5); csa.ccb_h.func_code = XPT_SASYNC_CB; csa.event_enable = AC_LOST_DEVICE; csa.callback = xxx_async; csa.callback_arg = sim; xpt_action((union ccb *)&csa); Now we take a look at the xxx_action() and xxx_poll() driver entry points. static void xxx_action struct cam_sim *sim, union ccb *ccb Do some action on request of the CAM subsystem. Sim describes the SIM for the request, CCB is the request itself. CCB stands for CAM Control Block. It is a union of many specific instances, each describing arguments for some type of transactions. All of these instances share the CCB header where the common part of arguments is stored. CAM supports the SCSI controllers working in both initiator (normal) mode and target (simulating a SCSI device) mode. Here we only consider the part relevant to the initiator mode. There are a few function and macros (in other words, methods) defined to access the public data in the struct sim: cam_sim_path(sim) - the path ID (see above) cam_sim_name(sim) - the name of the sim cam_sim_softc(sim) - the pointer to the softc (driver private data) structure cam_sim_unit(sim) - the unit number cam_sim_bus(sim) - the bus ID To identify the device, xxx_action() can get the unit number and pointer to its structure softc using these functions. The type of request is stored in ccb->ccb_h.func_code. So generally xxx_action() consists of a big switch: struct xxx_softc *softc = (struct xxx_softc *) cam_sim_softc(sim); struct ccb_hdr *ccb_h = &ccb->ccb_h; int unit = cam_sim_unit(sim); int bus = cam_sim_bus(sim); switch(ccb_h->func_code) { case ...: ... default: ccb_h->status = CAM_REQ_INVALID; xpt_done(ccb); break; } As can be seen from the default case (if an unknown command was received) the return code of the command is set into ccb->ccb_h.status and the completed CCB is returned back to CAM by calling xpt_done(ccb). xpt_done() does not have to be called from xxx_action(): For example an I/O request may be enqueued inside the SIM driver and/or its SCSI controller. Then when the device would post an interrupt signaling that the processing of this request is complete xpt_done() may be called from the interrupt handling routine. Actually, the CCB status is not only assigned as a return code but a CCB has some status all the time. Before CCB is passed to the xxx_action() routine it gets the status CCB_REQ_INPROG meaning that it is in progress. There are a surprising number of status values defined in /sys/cam/cam.h which should be able to represent the status of a request in great detail. More interesting yet, the status is in fact a bitwise or of an enumerated status value (the lower 6 bits) and possible additional flag-like bits (the upper bits). The enumerated values will be discussed later in more detail. The summary of them can be found in the Errors Summary section. The possible status flags are: CAM_DEV_QFRZN - if the SIM driver gets a serious error (for example, the device does not respond to the selection or breaks the SCSI protocol) when processing a CCB it should freeze the request queue by calling xpt_freeze_simq(), return the other enqueued but not processed yet CCBs for this device back to the CAM queue, then set this flag for the troublesome CCB and call xpt_done(). This flag causes the CAM subsystem to unfreeze the queue after it handles the error. CAM_AUTOSNS_VALID - if the device returned an error condition and the flag CAM_DIS_AUTOSENSE is not set in CCB the SIM driver must execute the REQUEST SENSE command automatically to extract the sense (extended error information) data from the device. If this attempt was successful the sense data should be saved in the CCB and this flag set. CAM_RELEASE_SIMQ - like CAM_DEV_QFRZN but used in case there is some problem (or resource shortage) with the SCSI controller itself. Then all the future requests to the controller should be stopped by xpt_freeze_simq(). The controller queue will be restarted after the SIM driver overcomes the shortage and informs CAM by returning some CCB with this flag set. CAM_SIM_QUEUED - when SIM puts a CCB into its request queue this flag should be set (and removed when this CCB gets dequeued before being returned back to CAM). This flag is not used anywhere in the CAM code now, so its purpose is purely diagnostic. The function xxx_action() is not allowed to sleep, so all the synchronization for resource access must be done using SIM or device queue freezing. Besides the aforementioned flags the CAM subsystem provides functions xpt_release_simq() and xpt_release_devq() to unfreeze the queues directly, without passing a CCB to CAM. The CCB header contains the following fields: path - path ID for the request target_id - target device ID for the request target_lun - LUN ID of the target device timeout - timeout interval for this command, in milliseconds timeout_ch - a convenience place for the SIM driver to store the timeout handle (the CAM subsystem itself does not make any assumptions about it) flags - various bits of information about the request spriv_ptr0, spriv_ptr1 - fields reserved for private use by the SIM driver (such as linking to the SIM queues or SIM private control blocks); actually, they exist as unions: spriv_ptr0 and spriv_ptr1 have the type (void *), spriv_field0 and spriv_field1 have the type unsigned long, sim_priv.entries[0].bytes and sim_priv.entries[1].bytes are byte arrays of the size consistent with the other incarnations of the union and sim_priv.bytes is one array, twice bigger. The recommended way of using the SIM private fields of CCB is to define some meaningful names for them and use these meaningful names in the driver, like: #define ccb_some_meaningful_name sim_priv.entries[0].bytes #define ccb_hcb spriv_ptr1 /* for hardware control block */ The most common initiator mode requests are: XPT_SCSI_IO - execute an I/O transaction The instance struct ccb_scsiio csio of the union ccb is used to transfer the arguments. They are: cdb_io - pointer to the SCSI command buffer or the buffer itself cdb_len - SCSI command length data_ptr - pointer to the data buffer (gets a bit complicated if scatter/gather is used) dxfer_len - length of the data to transfer sglist_cnt - counter of the scatter/gather segments scsi_status - place to return the SCSI status sense_data - buffer for the SCSI sense information if the command returns an error (the SIM driver is supposed to run the REQUEST SENSE command automatically in this case if the CCB flag CAM_DIS_AUTOSENSE is not set) sense_len - the length of that buffer (if it happens to be higher than size of sense_data the SIM driver must silently assume the smaller value) resid, sense_resid - if the transfer of data or SCSI sense returned an error these are the returned counters of the residual (not transferred) data. They do not seem to be especially meaningful, so in a case when they are difficult to compute (say, counting bytes in the SCSI controller's FIFO buffer) an approximate value will do as well. For a successfully completed transfer they must be set to zero. tag_action - the kind of tag to use: CAM_TAG_ACTION_NONE - do not use tags for this transaction MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG, MSG_ORDERED_Q_TAG - value equal to the appropriate tag message (see /sys/cam/scsi/scsi_message.h); this gives only the tag type, the SIM driver must assign the tag value itself The general logic of handling this request is the following: The first thing to do is to check for possible races, to make sure that the command did not get aborted when it was sitting in the queue: struct ccb_scsiio *csio = &ccb->csio; if ((ccb_h->status & CAM_STATUS_MASK) != CAM_REQ_INPROG) { xpt_done(ccb); return; } Also we check that the device is supported at all by our controller: if(ccb_h->target_id > OUR_MAX_SUPPORTED_TARGET_ID || cch_h->target_id == OUR_SCSI_CONTROLLERS_OWN_ID) { ccb_h->status = CAM_TID_INVALID; xpt_done(ccb); return; } if(ccb_h->target_lun > OUR_MAX_SUPPORTED_LUN) { ccb_h->status = CAM_LUN_INVALID; xpt_done(ccb); return; } - hardware control block - Then allocate whatever data structures (such as - card-dependent hardware control block) we need to process this + card-dependent hardware control blockhardware control block) we need to process this request. If we can not then freeze the SIM queue and remember that we have a pending operation, return the CCB back and ask CAM to re-queue it. Later when the resources become available the SIM queue must be unfrozen by returning a ccb with the CAM_SIMQ_RELEASE bit set in its status. Otherwise, if all went well, link the CCB with the hardware control block (HCB) and mark it as queued. struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus); if(hcb == NULL) { softc->flags |= RESOURCE_SHORTAGE; xpt_freeze_simq(sim, /*count*/1); ccb_h->status = CAM_REQUEUE_REQ; xpt_done(ccb); return; } hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb; ccb_h->status |= CAM_SIM_QUEUED; Extract the target data from CCB into the hardware control block. Check if we are asked to assign a tag and if yes then generate an unique tag and build the SCSI tag messages. The SIM driver is also responsible for negotiations with the devices to set the maximal mutually supported bus width, synchronous rate and offset. hcb->target = ccb_h->target_id; hcb->lun = ccb_h->target_lun; generate_identify_message(hcb); if( ccb_h->tag_action != CAM_TAG_ACTION_NONE ) generate_unique_tag_message(hcb, ccb_h->tag_action); if( !target_negotiated(hcb) ) generate_negotiation_messages(hcb); Then set up the SCSI command. The command storage may be specified in the CCB in many interesting ways, specified by the CCB flags. The command buffer can be contained in CCB or pointed to, in the latter case the pointer may be physical or virtual. Since the hardware commonly needs physical address we always convert the address to the physical one. A NOT-QUITE RELATED NOTE: Normally this is done by a call to vtophys(), but for the PCI device (which account for most of the SCSI controllers now) drivers' portability to the Alpha architecture the conversion must be done by vtobus() instead due to special Alpha quirks. [IMHO it would be much better to have two separate functions, vtop() and ptobus() then vtobus() would be a simple superposition of them.] In case if a physical address is requested it is OK to return the CCB with the status CAM_REQ_INVALID, the current drivers do that. But it is also possible to compile the Alpha-specific piece of code, as in this example (there should be a more direct way to do that, without conditional compilation in the drivers). If necessary a physical address can be also converted or mapped back to a virtual address but with big pain, so we do not do that. if(ccb_h->flags & CAM_CDB_POINTER) { /* CDB is a pointer */ if(!(ccb_h->flags & CAM_CDB_PHYS)) { /* CDB pointer is virtual */ hcb->cmd = vtobus(csio->cdb_io.cdb_ptr); } else { /* CDB pointer is physical */ #if defined(__alpha__) hcb->cmd = csio->cdb_io.cdb_ptr | alpha_XXX_dmamap_or ; #else hcb->cmd = csio->cdb_io.cdb_ptr ; #endif } } else { /* CDB is in the ccb (buffer) */ hcb->cmd = vtobus(csio->cdb_io.cdb_bytes); } hcb->cmdlen = csio->cdb_len; Now it is time to set up the data. Again, the data storage may be specified in the CCB in many interesting ways, specified by the CCB flags. First we get the direction of the data transfer. The simplest case is if there is no data to transfer: int dir = (ccb_h->flags & CAM_DIR_MASK); if (dir == CAM_DIR_NONE) goto end_data; Then we check if the data is in one chunk or in a scatter-gather list, and the addresses are physical or virtual. The SCSI controller may be able to handle only a limited number of chunks of limited length. If the request hits this limitation we return an error. We use a special function to return the CCB to handle in one place the HCB resource shortages. The functions to add chunks are driver-dependent, and here we leave them without detailed implementation. See description of the SCSI command (CDB) handling for the details on the address-translation issues. If some variation is too difficult or impossible to implement with a particular card it is OK to return the status CAM_REQ_INVALID. Actually, it seems like the scatter-gather ability is not used anywhere in the CAM code now. But at least the case for a single non-scattered virtual buffer must be implemented, it is actively used by CAM. int rv; initialize_hcb_for_data(hcb); if((!(ccb_h->flags & CAM_SCATTER_VALID)) { /* single buffer */ if(!(ccb_h->flags & CAM_DATA_PHYS)) { rv = add_virtual_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir); } } else { rv = add_physical_chunk(hcb, csio->data_ptr, csio->dxfer_len, dir); } } else { int i; struct bus_dma_segment *segs; segs = (struct bus_dma_segment *)csio->data_ptr; if ((ccb_h->flags & CAM_SG_LIST_PHYS) != 0) { /* The SG list pointer is physical */ rv = setup_hcb_for_physical_sg_list(hcb, segs, csio->sglist_cnt); } else if (!(ccb_h->flags & CAM_DATA_PHYS)) { /* SG buffer pointers are virtual */ for (i = 0; i < csio->sglist_cnt; i++) { rv = add_virtual_chunk(hcb, segs[i].ds_addr, segs[i].ds_len, dir); if (rv != CAM_REQ_CMP) break; } } else { /* SG buffer pointers are physical */ for (i = 0; i < csio->sglist_cnt; i++) { rv = add_physical_chunk(hcb, segs[i].ds_addr, segs[i].ds_len, dir); if (rv != CAM_REQ_CMP) break; } } } if(rv != CAM_REQ_CMP) { /* we expect that add_*_chunk() functions return CAM_REQ_CMP * if they added a chunk successfully, CAM_REQ_TOO_BIG if * the request is too big (too many bytes or too many chunks), * CAM_REQ_INVALID in case of other troubles */ free_hcb_and_ccb_done(hcb, ccb, rv); return; } end_data: If disconnection is disabled for this CCB we pass this information to the hcb: if(ccb_h->flags & CAM_DIS_DISCONNECT) hcb_disable_disconnect(hcb); If the controller is able to run REQUEST SENSE command all by itself then the value of the flag CAM_DIS_AUTOSENSE should also be passed to it, to prevent automatic REQUEST SENSE if the CAM subsystem does not want it. The only thing left is to set up the timeout, pass our hcb to the hardware and return, the rest will be done by the interrupt handler (or timeout handler). ccb_h->timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, (ccb_h->timeout * hz) / 1000); /* convert milliseconds to ticks */ put_hcb_into_hardware_queue(hcb); return; And here is a possible implementation of the function returning CCB: static void free_hcb_and_ccb_done(struct xxx_hcb *hcb, union ccb *ccb, u_int32_t status) { struct xxx_softc *softc = hcb->softc; ccb->ccb_h.ccb_hcb = 0; if(hcb != NULL) { untimeout(xxx_timeout, (caddr_t) hcb, ccb->ccb_h.timeout_ch); /* we're about to free a hcb, so the shortage has ended */ if(softc->flags & RESOURCE_SHORTAGE) { softc->flags &= ~RESOURCE_SHORTAGE; status |= CAM_RELEASE_SIMQ; } free_hcb(hcb); /* also removes hcb from any internal lists */ } ccb->ccb_h.status = status | (ccb->ccb_h.status & ~(CAM_STATUS_MASK|CAM_SIM_QUEUED)); xpt_done(ccb); } XPT_RESET_DEV - send the SCSI BUS DEVICE RESET message to a device There is no data transferred in CCB except the header and the most interesting argument of it is target_id. Depending on the controller hardware a hardware control block just like for the XPT_SCSI_IO request may be constructed (see XPT_SCSI_IO request description) and sent to the controller or the SCSI controller may be immediately programmed to send this RESET message to the device or this request may be just not supported (and return the status CAM_REQ_INVALID). Also on completion of the request all the disconnected transactions for this target must be aborted (probably in the interrupt routine). Also all the current negotiations for the target are lost on reset, so they might be cleaned too. Or they clearing may be deferred, because anyway the target would request re-negotiation on the next transaction. XPT_RESET_BUS - send the RESET signal to the SCSI bus No arguments are passed in the CCB, the only interesting argument is the SCSI bus indicated by the struct sim pointer. A minimalistic implementation would forget the SCSI negotiations for all the devices on the bus and return the status CAM_REQ_CMP. The proper implementation would in addition actually reset the SCSI bus (possible also reset the SCSI controller) and mark all the CCBs being processed, both those in the hardware queue and those being disconnected, as done with the status CAM_SCSI_BUS_RESET. Like: int targ, lun; struct xxx_hcb *h, *hh; struct ccb_trans_settings neg; struct cam_path *path; /* The SCSI bus reset may take a long time, in this case its completion * should be checked by interrupt or timeout. But for simplicity * we assume here that it is really fast. */ reset_scsi_bus(softc); /* drop all enqueued CCBs */ for(h = softc->first_queued_hcb; h != NULL; h = hh) { hh = h->next; free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); } /* the clean values of negotiations to report */ neg.bus_width = 8; neg.sync_period = neg.sync_offset = 0; neg.valid = (CCB_TRANS_BUS_WIDTH_VALID | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID); /* drop all disconnected CCBs and clean negotiations */ for(targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) { clean_negotiations(softc, targ); /* report the event if possible */ if(xpt_create_path(&path, /*periph*/NULL, cam_sim_path(sim), targ, CAM_LUN_WILDCARD) == CAM_REQ_CMP) { xpt_async(AC_TRANSFER_NEG, path, &neg); xpt_free_path(path); } for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) for(h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) { hh=h->next; free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); } } ccb->ccb_h.status = CAM_REQ_CMP; xpt_done(ccb); /* report the event */ xpt_async(AC_BUS_RESET, softc->wpath, NULL); return; Implementing the SCSI bus reset as a function may be a good idea because it would be re-used by the timeout function as a last resort if the things go wrong. XPT_ABORT - abort the specified CCB The arguments are transferred in the instance struct ccb_abort cab of the union ccb. The only argument field in it is: abort_ccb - pointer to the CCB to be aborted If the abort is not supported just return the status CAM_UA_ABORT. This is also the easy way to minimally implement this call, return CAM_UA_ABORT in any case. The hard way is to implement this request honestly. First check that abort applies to a SCSI transaction: struct ccb *abort_ccb; abort_ccb = ccb->cab.abort_ccb; if(abort_ccb->ccb_h.func_code != XPT_SCSI_IO) { ccb->ccb_h.status = CAM_UA_ABORT; xpt_done(ccb); return; } Then it is necessary to find this CCB in our queue. This can be done by walking the list of all our hardware control blocks in search for one associated with this CCB: struct xxx_hcb *hcb, *h; hcb = NULL; /* We assume that softc->first_hcb is the head of the list of all * HCBs associated with this bus, including those enqueued for * processing, being processed by hardware and disconnected ones. */ for(h = softc->first_hcb; h != NULL; h = h->next) { if(h->ccb == abort_ccb) { hcb = h; break; } } if(hcb == NULL) { /* no such CCB in our queue */ ccb->ccb_h.status = CAM_PATH_INVALID; xpt_done(ccb); return; } hcb=found_hcb; Now we look at the current processing status of the HCB. It may be either sitting in the queue waiting to be sent to the SCSI bus, being transferred right now, or disconnected and waiting for the result of the command, or actually completed by hardware but not yet marked as done by software. To make sure that we do not get in any races with hardware we mark the HCB as being aborted, so that if this HCB is about to be sent to the SCSI bus the SCSI controller will see this flag and skip it. int hstatus; /* shown as a function, in case special action is needed to make * this flag visible to hardware */ set_hcb_flags(hcb, HCB_BEING_ABORTED); abort_again: hstatus = get_hcb_status(hcb); switch(hstatus) { case HCB_SITTING_IN_QUEUE: remove_hcb_from_hardware_queue(hcb); /* FALLTHROUGH */ case HCB_COMPLETED: /* this is an easy case */ free_hcb_and_ccb_done(hcb, abort_ccb, CAM_REQ_ABORTED); break; If the CCB is being transferred right now we would like to signal to the SCSI controller in some hardware-dependent way that we want to abort the current transfer. The SCSI controller would set the SCSI ATTENTION signal and when the target responds to it send an ABORT message. We also reset the timeout to make sure that the target is not sleeping forever. If the command would not get aborted in some reasonable time like 10 seconds the timeout routine would go ahead and reset the whole SCSI bus. Because the command will be aborted in some reasonable time we can just return the abort request now as successfully completed, and mark the aborted CCB as aborted (but not mark it as done yet). case HCB_BEING_TRANSFERRED: untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch); abort_ccb->ccb_h.timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, 10 * hz); abort_ccb->ccb_h.status = CAM_REQ_ABORTED; /* ask the controller to abort that HCB, then generate * an interrupt and stop */ if(signal_hardware_to_abort_hcb_and_stop(hcb) < 0) { /* oops, we missed the race with hardware, this transaction * got off the bus before we aborted it, try again */ goto abort_again; } break; If the CCB is in the list of disconnected then set it up as an abort request and re-queue it at the front of hardware queue. Reset the timeout and report the abort request to be completed. case HCB_DISCONNECTED: untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch); abort_ccb->ccb_h.timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, 10 * hz); put_abort_message_into_hcb(hcb); put_hcb_at_the_front_of_hardware_queue(hcb); break; } ccb->ccb_h.status = CAM_REQ_CMP; xpt_done(ccb); return; That is all for the ABORT request, although there is one more issue. Because the ABORT message cleans all the ongoing transactions on a LUN we have to mark all the other active transactions on this LUN as aborted. That should be done in the interrupt routine, after the transaction gets aborted. Implementing the CCB abort as a function may be quite a good idea, this function can be re-used if an I/O transaction times out. The only difference would be that the timed out transaction would return the status CAM_CMD_TIMEOUT for the timed out request. Then the case XPT_ABORT would be small, like that: case XPT_ABORT: struct ccb *abort_ccb; abort_ccb = ccb->cab.abort_ccb; if(abort_ccb->ccb_h.func_code != XPT_SCSI_IO) { ccb->ccb_h.status = CAM_UA_ABORT; xpt_done(ccb); return; } if(xxx_abort_ccb(abort_ccb, CAM_REQ_ABORTED) < 0) /* no such CCB in our queue */ ccb->ccb_h.status = CAM_PATH_INVALID; else ccb->ccb_h.status = CAM_REQ_CMP; xpt_done(ccb); return; XPT_SET_TRAN_SETTINGS - explicitly set values of SCSI transfer settings The arguments are transferred in the instance struct ccb_trans_setting cts of the union ccb: valid - a bitmask showing which settings should be updated: CCB_TRANS_SYNC_RATE_VALID - synchronous transfer rate CCB_TRANS_SYNC_OFFSET_VALID - synchronous offset CCB_TRANS_BUS_WIDTH_VALID - bus width CCB_TRANS_DISC_VALID - set enable/disable disconnection CCB_TRANS_TQ_VALID - set enable/disable tagged queuing flags - consists of two parts, binary arguments and identification of sub-operations. The binary arguments are: CCB_TRANS_DISC_ENB - enable disconnection CCB_TRANS_TAG_ENB - enable tagged queuing the sub-operations are: CCB_TRANS_CURRENT_SETTINGS - change the current negotiations CCB_TRANS_USER_SETTINGS - remember the desired user values sync_period, sync_offset - self-explanatory, if sync_offset==0 then the asynchronous mode is requested bus_width - bus width, in bits (not bytes) Two sets of negotiated parameters are supported, the user settings and the current settings. The user settings are not really used much in the SIM drivers, this is mostly just a piece of memory where the upper levels can store (and later recall) its ideas about the parameters. Setting the user parameters does not cause re-negotiation of the transfer rates. But when the SCSI controller does a negotiation it must never set the values higher than the user parameters, so it is essentially the top boundary. The current settings are, as the name says, current. Changing them means that the parameters must be re-negotiated on the next transfer. Again, these new current settings are not supposed to be forced on the device, just they are used as the initial step of negotiations. Also they must be limited by actual capabilities of the SCSI controller: for example, if the SCSI controller has 8-bit bus and the request asks to set 16-bit wide transfers this parameter must be silently truncated to 8-bit transfers before sending it to the device. One caveat is that the bus width and synchronous parameters are per target while the disconnection and tag enabling parameters are per lun. The recommended implementation is to keep 3 sets of negotiated (bus width and synchronous transfer) parameters: user - the user set, as above current - those actually in effect goal - those requested by setting of the current parameters The code looks like: struct ccb_trans_settings *cts; int targ, lun; int flags; cts = &ccb->cts; targ = ccb_h->target_id; lun = ccb_h->target_lun; flags = cts->flags; if(flags & CCB_TRANS_USER_SETTINGS) { if(flags & CCB_TRANS_SYNC_RATE_VALID) softc->user_sync_period[targ] = cts->sync_period; if(flags & CCB_TRANS_SYNC_OFFSET_VALID) softc->user_sync_offset[targ] = cts->sync_offset; if(flags & CCB_TRANS_BUS_WIDTH_VALID) softc->user_bus_width[targ] = cts->bus_width; if(flags & CCB_TRANS_DISC_VALID) { softc->user_tflags[targ][lun] &= ~CCB_TRANS_DISC_ENB; softc->user_tflags[targ][lun] |= flags & CCB_TRANS_DISC_ENB; } if(flags & CCB_TRANS_TQ_VALID) { softc->user_tflags[targ][lun] &= ~CCB_TRANS_TQ_ENB; softc->user_tflags[targ][lun] |= flags & CCB_TRANS_TQ_ENB; } } if(flags & CCB_TRANS_CURRENT_SETTINGS) { if(flags & CCB_TRANS_SYNC_RATE_VALID) softc->goal_sync_period[targ] = max(cts->sync_period, OUR_MIN_SUPPORTED_PERIOD); if(flags & CCB_TRANS_SYNC_OFFSET_VALID) softc->goal_sync_offset[targ] = min(cts->sync_offset, OUR_MAX_SUPPORTED_OFFSET); if(flags & CCB_TRANS_BUS_WIDTH_VALID) softc->goal_bus_width[targ] = min(cts->bus_width, OUR_BUS_WIDTH); if(flags & CCB_TRANS_DISC_VALID) { softc->current_tflags[targ][lun] &= ~CCB_TRANS_DISC_ENB; softc->current_tflags[targ][lun] |= flags & CCB_TRANS_DISC_ENB; } if(flags & CCB_TRANS_TQ_VALID) { softc->current_tflags[targ][lun] &= ~CCB_TRANS_TQ_ENB; softc->current_tflags[targ][lun] |= flags & CCB_TRANS_TQ_ENB; } } ccb->ccb_h.status = CAM_REQ_CMP; xpt_done(ccb); return; Then when the next I/O request will be processed it will check if it has to re-negotiate, for example by calling the function target_negotiated(hcb). It can be implemented like this: int target_negotiated(struct xxx_hcb *hcb) { struct softc *softc = hcb->softc; int targ = hcb->targ; if( softc->current_sync_period[targ] != softc->goal_sync_period[targ] || softc->current_sync_offset[targ] != softc->goal_sync_offset[targ] || softc->current_bus_width[targ] != softc->goal_bus_width[targ] ) return 0; /* FALSE */ else return 1; /* TRUE */ } After the values are re-negotiated the resulting values must be assigned to both current and goal parameters, so for future I/O transactions the current and goal parameters would be the same and target_negotiated() would return TRUE. When the card is initialized (in xxx_attach()) the current negotiation values must be initialized to narrow asynchronous mode, the goal and current values must be initialized to the maximal values supported by controller. XPT_GET_TRAN_SETTINGS - get values of SCSI transfer settings This operations is the reverse of XPT_SET_TRAN_SETTINGS. Fill up the CCB instance struct ccb_trans_setting cts with data as requested by the flags CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both are set then the existing drivers return the current settings). Set all the bits in the valid field. - BIOS - XPT_CALC_GEOMETRY - calculate logical - (BIOS) geometry of the disk + (BIOS)BIOS geometry of the disk The arguments are transferred in the instance struct ccb_calc_geometry ccg of the union ccb: block_size - input, block (A.K.A sector) size in bytes volume_size - input, volume size in bytes cylinders - output, logical cylinders heads - output, logical heads secs_per_track - output, logical sectors per track - SCSIBIOS If the returned geometry differs much enough from what the - SCSI controller BIOS thinks and a disk on this SCSI controller + SCSI controller BIOSSCSIBIOS thinks and a disk on this SCSI controller is used as bootable the system may not be able to boot. The typical calculation example taken from the aic7xxx driver is: struct ccb_calc_geometry *ccg; u_int32_t size_mb; u_int32_t secs_per_cylinder; int extended; ccg = &ccb->ccg; size_mb = ccg->volume_size / ((1024L * 1024L) / ccg->block_size); extended = check_cards_EEPROM_for_extended_geometry(softc); if (size_mb > 1024 && extended) { ccg->heads = 255; ccg->secs_per_track = 63; } else { ccg->heads = 64; ccg->secs_per_track = 32; } secs_per_cylinder = ccg->heads * ccg->secs_per_track; ccg->cylinders = ccg->volume_size / secs_per_cylinder; ccb->ccb_h.status = CAM_REQ_CMP; xpt_done(ccb); return; This gives the general idea, the exact calculation depends on the quirks of the particular BIOS. If BIOS provides no way set the extended translation flag in EEPROM this flag should normally be assumed equal to 1. Other popular geometries are: 128 heads, 63 sectors - Symbios controllers 16 heads, 63 sectors - old controllers Some system BIOSes and SCSI BIOSes fight with each other with variable success, for example a combination of Symbios 875/895 SCSI and Phoenix BIOS can give geometry 128/63 after power up and 255/63 after a hard reset or soft reboot. XPT_PATH_INQ - path inquiry, in other words get the SIM driver and SCSI controller (also known as HBA - Host Bus Adapter) properties The properties are returned in the instance struct ccb_pathinq cpi of the union ccb: version_num - the SIM driver version number, now all drivers use 1 hba_inquiry - bitmask of features supported by the controller: PI_MDP_ABLE - supports MDP message (something from SCSI3?) PI_WIDE_32 - supports 32 bit wide SCSI PI_WIDE_16 - supports 16 bit wide SCSI PI_SDTR_ABLE - can negotiate synchronous transfer rate PI_LINKED_CDB - supports linked commands PI_TAG_ABLE - supports tagged commands PI_SOFT_RST - supports soft reset alternative (hard reset and soft reset are mutually exclusive within a SCSI bus) target_sprt - flags for target mode support, 0 if unsupported hba_misc - miscellaneous controller features: PIM_SCANHILO - bus scans from high ID to low ID PIM_NOREMOVE - removable devices not included in scan PIM_NOINITIATOR - initiator role not supported PIM_NOBUSRESET - user has disabled initial BUS RESET hba_eng_cnt - mysterious HBA engine count, something related to compression, now is always set to 0 vuhba_flags - vendor-unique flags, unused now max_target - maximal supported target ID (7 for 8-bit bus, 15 for 16-bit bus, 127 for Fibre Channel) max_lun - maximal supported LUN ID (7 for older SCSI controllers, 63 for newer ones) async_flags - bitmask of installed Async handler, unused now hpath_id - highest Path ID in the subsystem, unused now unit_number - the controller unit number, cam_sim_unit(sim) bus_id - the bus number, cam_sim_bus(sim) initiator_id - the SCSI ID of the controller itself base_transfer_speed - nominal transfer speed in KB/s for asynchronous narrow transfers, equals to 3300 for SCSI sim_vid - SIM driver's vendor id, a zero-terminated string of maximal length SIM_IDLEN including the terminating zero hba_vid - SCSI controller's vendor id, a zero-terminated string of maximal length HBA_IDLEN including the terminating zero dev_name - device driver name, a zero-terminated string of maximal length DEV_IDLEN including the terminating zero, equal to cam_sim_name(sim) The recommended way of setting the string fields is using strncpy, like: strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN); After setting the values set the status to CAM_REQ_CMP and mark the CCB as done. Polling static void xxx_poll struct cam_sim *sim The poll function is used to simulate the interrupts when the interrupt subsystem is not functioning (for example, when the system has crashed and is creating the system dump). The CAM subsystem sets the proper interrupt level before calling the poll routine. So all it needs to do is to call the interrupt routine (or the other way around, the poll routine may be doing the real action and the interrupt routine would just call the poll routine). Why bother about a separate function then? Because of different calling conventions. The xxx_poll routine gets the struct cam_sim pointer as its argument when the PCI interrupt routine by common convention gets pointer to the struct xxx_softc and the ISA interrupt routine gets just the device unit number. So the poll routine would normally look as: static void xxx_poll(struct cam_sim *sim) { xxx_intr((struct xxx_softc *)cam_sim_softc(sim)); /* for PCI device */ } or static void xxx_poll(struct cam_sim *sim) { xxx_intr(cam_sim_unit(sim)); /* for ISA device */ } Asynchronous Events If an asynchronous event callback has been set up then the callback function should be defined. static void ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg) callback_arg - the value supplied when registering the callback code - identifies the type of event path - identifies the devices to which the event applies arg - event-specific argument Implementation for a single type of event, AC_LOST_DEVICE, looks like: struct xxx_softc *softc; struct cam_sim *sim; int targ; struct ccb_trans_settings neg; sim = (struct cam_sim *)callback_arg; softc = (struct xxx_softc *)cam_sim_softc(sim); switch (code) { case AC_LOST_DEVICE: targ = xpt_path_target_id(path); if(targ <= OUR_MAX_SUPPORTED_TARGET) { clean_negotiations(softc, targ); /* send indication to CAM */ neg.bus_width = 8; neg.sync_period = neg.sync_offset = 0; neg.valid = (CCB_TRANS_BUS_WIDTH_VALID | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID); xpt_async(AC_TRANSFER_NEG, path, &neg); } break; default: break; } Interrupts SCSIinterrupts The exact type of the interrupt routine depends on the type of the peripheral bus (PCI, ISA and so on) to which the SCSI controller is connected. The interrupt routines of the SIM drivers run at the interrupt level splcam. So splcam() should be used in the driver to synchronize activity between the interrupt routine and the rest of the driver (for a multiprocessor-aware driver things get yet more interesting but we ignore this case here). The pseudo-code in this document happily ignores the problems of synchronization. The real code must not ignore them. A simple-minded approach is to set splcam() on the entry to the other routines and reset it on return thus protecting them by one big critical section. To make sure that the interrupt level will be always restored a wrapper function can be defined, like: static void xxx_action(struct cam_sim *sim, union ccb *ccb) { int s; s = splcam(); xxx_action1(sim, ccb); splx(s); } static void xxx_action1(struct cam_sim *sim, union ccb *ccb) { ... process the request ... } This approach is simple and robust but the problem with it is that interrupts may get blocked for a relatively long time and this would negatively affect the system's performance. On the other hand the functions of the spl() family have rather high overhead, so vast amount of tiny critical sections may not be good either. The conditions handled by the interrupt routine and the details depend very much on the hardware. We consider the set of typical conditions. First, we check if a SCSI reset was encountered on the bus (probably caused by another SCSI controller on the same SCSI bus). If so we drop all the enqueued and disconnected requests, report the events and re-initialize our SCSI controller. It is important that during this initialization the controller will not issue another reset or else two controllers on the same SCSI bus could ping-pong resets forever. The case of fatal controller error/hang could be handled in the same place, but it will probably need also sending RESET signal to the SCSI bus to reset the status of the connections with the SCSI devices. int fatal=0; struct ccb_trans_settings neg; struct cam_path *path; if( detected_scsi_reset(softc) || (fatal = detected_fatal_controller_error(softc)) ) { int targ, lun; struct xxx_hcb *h, *hh; /* drop all enqueued CCBs */ for(h = softc->first_queued_hcb; h != NULL; h = hh) { hh = h->next; free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); } /* the clean values of negotiations to report */ neg.bus_width = 8; neg.sync_period = neg.sync_offset = 0; neg.valid = (CCB_TRANS_BUS_WIDTH_VALID | CCB_TRANS_SYNC_RATE_VALID | CCB_TRANS_SYNC_OFFSET_VALID); /* drop all disconnected CCBs and clean negotiations */ for(targ=0; targ <= OUR_MAX_SUPPORTED_TARGET; targ++) { clean_negotiations(softc, targ); /* report the event if possible */ if(xpt_create_path(&path, /*periph*/NULL, cam_sim_path(sim), targ, CAM_LUN_WILDCARD) == CAM_REQ_CMP) { xpt_async(AC_TRANSFER_NEG, path, &neg); xpt_free_path(path); } for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) for(h = softc->first_discon_hcb[targ][lun]; h != NULL; h = hh) { hh=h->next; if(fatal) free_hcb_and_ccb_done(h, h->ccb, CAM_UNREC_HBA_ERROR); else free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); } } /* report the event */ xpt_async(AC_BUS_RESET, softc->wpath, NULL); /* re-initialization may take a lot of time, in such case * its completion should be signaled by another interrupt or * checked on timeout - but for simplicity we assume here that * it is really fast */ if(!fatal) { reinitialize_controller_without_scsi_reset(softc); } else { reinitialize_controller_with_scsi_reset(softc); } schedule_next_hcb(softc); return; } If interrupt is not caused by a controller-wide condition then probably something has happened to the current hardware control block. Depending on the hardware there may be other non-HCB-related events, we just do not consider them here. Then we analyze what happened to this HCB: struct xxx_hcb *hcb, *h, *hh; int hcb_status, scsi_status; int ccb_status; int targ; int lun_to_freeze; hcb = get_current_hcb(softc); if(hcb == NULL) { /* either stray interrupt or something went very wrong * or this is something hardware-dependent */ handle as necessary; return; } targ = hcb->target; hcb_status = get_status_of_current_hcb(softc); First we check if the HCB has completed and if so we check the returned SCSI status. if(hcb_status == COMPLETED) { scsi_status = get_completion_status(hcb); Then look if this status is related to the REQUEST SENSE command and if so handle it in a simple way. if(hcb->flags & DOING_AUTOSENSE) { if(scsi_status == GOOD) { /* autosense was successful */ hcb->ccb->ccb_h.status |= CAM_AUTOSNS_VALID; free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR); } else { autosense_failed: free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_AUTOSENSE_FAIL); } schedule_next_hcb(softc); return; } Else the command itself has completed, pay more attention to details. If auto-sense is not disabled for this CCB and the command has failed with sense data then run REQUEST SENSE command to receive that data. hcb->ccb->csio.scsi_status = scsi_status; calculate_residue(hcb); if( (hcb->ccb->ccb_h.flags & CAM_DIS_AUTOSENSE)==0 && ( scsi_status == CHECK_CONDITION || scsi_status == COMMAND_TERMINATED) ) { /* start auto-SENSE */ hcb->flags |= DOING_AUTOSENSE; setup_autosense_command_in_hcb(hcb); restart_current_hcb(softc); return; } if(scsi_status == GOOD) free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_REQ_CMP); else free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR); schedule_next_hcb(softc); return; } One typical thing would be negotiation events: negotiation messages received from a SCSI target (in answer to our negotiation attempt or by target's initiative) or the target is unable to negotiate (rejects our negotiation messages or does not answer them). switch(hcb_status) { case TARGET_REJECTED_WIDE_NEG: /* revert to 8-bit bus */ softc->current_bus_width[targ] = softc->goal_bus_width[targ] = 8; /* report the event */ neg.bus_width = 8; neg.valid = CCB_TRANS_BUS_WIDTH_VALID; xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); continue_current_hcb(softc); return; case TARGET_ANSWERED_WIDE_NEG: { int wd; wd = get_target_bus_width_request(softc); if(wd <= softc->goal_bus_width[targ]) { /* answer is acceptable */ softc->current_bus_width[targ] = softc->goal_bus_width[targ] = neg.bus_width = wd; /* report the event */ neg.valid = CCB_TRANS_BUS_WIDTH_VALID; xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); } else { prepare_reject_message(hcb); } } continue_current_hcb(softc); return; case TARGET_REQUESTED_WIDE_NEG: { int wd; wd = get_target_bus_width_request(softc); wd = min (wd, OUR_BUS_WIDTH); wd = min (wd, softc->user_bus_width[targ]); if(wd != softc->current_bus_width[targ]) { /* the bus width has changed */ softc->current_bus_width[targ] = softc->goal_bus_width[targ] = neg.bus_width = wd; /* report the event */ neg.valid = CCB_TRANS_BUS_WIDTH_VALID; xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); } prepare_width_nego_rsponse(hcb, wd); } continue_current_hcb(softc); return; } Then we handle any errors that could have happened during auto-sense in the same simple-minded way as before. Otherwise we look closer at the details again. if(hcb->flags & DOING_AUTOSENSE) goto autosense_failed; switch(hcb_status) { The next event we consider is unexpected disconnect. Which is considered normal after an ABORT or BUS DEVICE RESET message and abnormal in other cases. case UNEXPECTED_DISCONNECT: if(requested_abort(hcb)) { /* abort affects all commands on that target+LUN, so * mark all disconnected HCBs on that target+LUN as aborted too */ for(h = softc->first_discon_hcb[hcb->target][hcb->lun]; h != NULL; h = hh) { hh=h->next; free_hcb_and_ccb_done(h, h->ccb, CAM_REQ_ABORTED); } ccb_status = CAM_REQ_ABORTED; } else if(requested_bus_device_reset(hcb)) { int lun; /* reset affects all commands on that target, so * mark all disconnected HCBs on that target+LUN as reset */ for(lun=0; lun <= OUR_MAX_SUPPORTED_LUN; lun++) for(h = softc->first_discon_hcb[hcb->target][lun]; h != NULL; h = hh) { hh=h->next; free_hcb_and_ccb_done(h, h->ccb, CAM_SCSI_BUS_RESET); } /* send event */ xpt_async(AC_SENT_BDR, hcb->ccb->ccb_h.path_id, NULL); /* this was the CAM_RESET_DEV request itself, it is completed */ ccb_status = CAM_REQ_CMP; } else { calculate_residue(hcb); ccb_status = CAM_UNEXP_BUSFREE; /* request the further code to freeze the queue */ hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; lun_to_freeze = hcb->lun; } break; If the target refuses to accept tags we notify CAM about that and return back all commands for this LUN: case TAGS_REJECTED: /* report the event */ neg.flags = 0 & ~CCB_TRANS_TAG_ENB; neg.valid = CCB_TRANS_TQ_VALID; xpt_async(AC_TRANSFER_NEG, hcb->ccb.ccb_h.path_id, &neg); ccb_status = CAM_MSG_REJECT_REC; /* request the further code to freeze the queue */ hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; lun_to_freeze = hcb->lun; break; Then we check a number of other conditions, with processing basically limited to setting the CCB status: case SELECTION_TIMEOUT: ccb_status = CAM_SEL_TIMEOUT; /* request the further code to freeze the queue */ hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; lun_to_freeze = CAM_LUN_WILDCARD; break; case PARITY_ERROR: ccb_status = CAM_UNCOR_PARITY; break; case DATA_OVERRUN: case ODD_WIDE_TRANSFER: ccb_status = CAM_DATA_RUN_ERR; break; default: /* all other errors are handled in a generic way */ ccb_status = CAM_REQ_CMP_ERR; /* request the further code to freeze the queue */ hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; lun_to_freeze = CAM_LUN_WILDCARD; break; } Then we check if the error was serious enough to freeze the input queue until it gets proceeded and do so if it is: if(hcb->ccb->ccb_h.status & CAM_DEV_QFRZN) { /* freeze the queue */ xpt_freeze_devq(ccb->ccb_h.path, /*count*/1); /* re-queue all commands for this target/LUN back to CAM */ for(h = softc->first_queued_hcb; h != NULL; h = hh) { hh = h->next; if(targ == h->targ && (lun_to_freeze == CAM_LUN_WILDCARD || lun_to_freeze == h->lun) ) free_hcb_and_ccb_done(h, h->ccb, CAM_REQUEUE_REQ); } } free_hcb_and_ccb_done(hcb, hcb->ccb, ccb_status); schedule_next_hcb(softc); return; This concludes the generic interrupt handling although specific controllers may require some additions. Errors Summary SCSIerrors When executing an I/O request many things may go wrong. The reason of error can be reported in the CCB status with great detail. Examples of use are spread throughout this document. For completeness here is the summary of recommended responses for the typical error conditions: CAM_RESRC_UNAVAIL - some resource is temporarily unavailable and the SIM driver cannot generate an event when it will become available. An example of this resource would be some intra-controller hardware resource for which the controller does not generate an interrupt when it becomes available. CAM_UNCOR_PARITY - unrecovered parity error occurred CAM_DATA_RUN_ERR - data overrun or unexpected data phase (going in other direction than specified in CAM_DIR_MASK) or odd transfer length for wide transfer CAM_SEL_TIMEOUT - selection timeout occurred (target does not respond) CAM_CMD_TIMEOUT - command timeout occurred (the timeout function ran) CAM_SCSI_STATUS_ERROR - the device returned error CAM_AUTOSENSE_FAIL - the device returned error and the REQUEST SENSE COMMAND failed CAM_MSG_REJECT_REC - MESSAGE REJECT message was received CAM_SCSI_BUS_RESET - received SCSI bus reset CAM_REQ_CMP_ERR - impossible SCSI phase occurred or something else as weird or just a generic error if further detail is not available CAM_UNEXP_BUSFREE - unexpected disconnect occurred CAM_BDR_SENT - BUS DEVICE RESET message was sent to the target CAM_UNREC_HBA_ERROR - unrecoverable Host Bus Adapter Error CAM_REQ_TOO_BIG - the request was too large for this controller CAM_REQUEUE_REQ - this request should be re-queued to preserve transaction ordering. This typically occurs when the SIM recognizes an error that should freeze the queue and must place other queued requests for the target at the sim level back into the XPT queue. Typical cases of such errors are selection timeouts, command timeouts and other like conditions. In such cases the troublesome command returns the status indicating the error, the and the other commands which have not be sent to the bus yet get re-queued. CAM_LUN_INVALID - the LUN ID in the request is not supported by the SCSI controller CAM_TID_INVALID - the target ID in the request is not supported by the SCSI controller Timeout Handling When the timeout for an HCB expires that request should be aborted, just like with an XPT_ABORT request. The only difference is that the returned status of aborted request should be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that is why implementation of the abort better be done as a function). But there is one more possible problem: what if the abort request itself will get stuck? In this case the SCSI bus should be reset, just like with an XPT_RESET_BUS request (and the idea about implementing it as a function called from both places applies here too). Also we should reset the whole SCSI bus if a device reset request got stuck. So after all the timeout function would look like: static void xxx_timeout(void *arg) { struct xxx_hcb *hcb = (struct xxx_hcb *)arg; struct xxx_softc *softc; struct ccb_hdr *ccb_h; softc = hcb->softc; ccb_h = &hcb->ccb->ccb_h; if(hcb->flags & HCB_BEING_ABORTED || ccb_h->func_code == XPT_RESET_DEV) { xxx_reset_bus(softc); } else { xxx_abort_ccb(hcb->ccb, CAM_CMD_TIMEOUT); } } When we abort a request all the other disconnected requests to the same target/LUN get aborted too. So there appears a question, should we return them with status CAM_REQ_ABORTED or CAM_CMD_TIMEOUT? The current drivers use CAM_CMD_TIMEOUT. This seems logical because if one request got timed out then probably something really bad is happening to the device, so if they would not be disturbed they would time out by themselves. diff --git a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml index 65c06106e4..fc90285e3e 100644 --- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml @@ -1,687 +1,686 @@ Jean-Francois Dockes Contributed by Sound Subsystem Introduction sound subsystem The FreeBSD sound subsystem cleanly separates generic sound handling issues from device-specific ones. This makes it easier to add support for new hardware. The &man.pcm.4; framework is the central piece of the sound subsystem. It mainly implements the following elements: system call interface A system call interface (read, write, ioctls) to digitized sound and mixer functions. The ioctl command set is compatible with the legacy OSS or Voxware interface, allowing common multimedia applications to be ported without modification. Common code for processing sound data (format conversions, virtual channels). A uniform software interface to hardware-specific audio interface modules. Additional support for some common hardware interfaces (ac97), or shared hardware-specific code (ex: ISA DMA routines). The support for specific sound cards is implemented by hardware-specific drivers, which provide channel and mixer interfaces to plug into the generic pcm code. In this chapter, the term pcm will refer to the central, common part of the sound driver, as opposed to the hardware-specific modules. The prospective driver writer will of course want to start from an existing module and use the code as the ultimate reference. But, while the sound code is nice and clean, it is also mostly devoid of comments. This document tries to give an overview of the framework interface and answer some questions that may arise while adapting the existing code. As an alternative, or in addition to starting from a working example, you can find a commented driver template at http://people.FreeBSD.org/~cg/template.c Files All the relevant code lives in /usr/src/sys/dev/sound/, except for the public ioctl interface definitions, found in /usr/src/sys/sys/soundcard.h Under /usr/src/sys/dev/sound/, the pcm/ directory holds the central code, while the pci/, isa/ and usb/ directories have the drivers for PCI and ISA boards, and for USB audio devices. Probing, Attaching, etc. Sound drivers probe and attach in almost the same way as any hardware driver module. You might want to look at the ISA or PCI specific sections of the handbook for more information. However, sound drivers differ in some ways: They declare themselves as pcm class devices, with a struct snddev_info device private structure: static driver_t xxx_driver = { "pcm", xxx_methods, sizeof(struct snddev_info) }; DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0); MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER); - device driverssound - Most sound drivers need to store additional private + Most sound driversdevice driverssound need to store additional private information about their device. A private data structure is usually allocated in the attach routine. Its address is passed to pcm by the calls to pcm_register() and mixer_init(). pcm later passes back this address as a parameter in calls to the sound driver interfaces. The sound driver attach routine should declare its MIXER or AC97 interface to pcm by calling mixer_init(). For a MIXER interface, this causes in turn a call to xxxmixer_init(). The sound driver attach routine declares its general CHANNEL configuration to pcm by calling pcm_register(dev, sc, nplay, nrec), where sc is the address for the device data structure, used in further calls from pcm, and nplay and nrec are the number of play and record channels. The sound driver attach routine declares each of its channel objects by calls to pcm_addchan(). This sets up the channel glue in pcm and causes in turn a call to xxxchannel_init(). The sound driver detach routine should call pcm_unregister() before releasing its resources. There are two possible methods to handle non-PnP devices: Use a device_identify() method (example: sound/isa/es1888.c). The device_identify() method probes for the hardware at known addresses and, if it finds a supported device, creates a new pcm device which is then passed to probe/attach. Use a custom kernel configuration with appropriate hints for pcm devices (example: sound/isa/mss.c). pcm drivers should implement device_suspend, device_resume and device_shutdown routines, so that power management and module unloading function correctly. Interfaces The interface between the pcm core and the sound drivers is defined in terms of kernel objects. There are two main interfaces that a sound driver will usually provide: CHANNEL and either MIXER or AC97. The AC97 interface is a very small hardware access (register read/write) interface, implemented by drivers for hardware with an AC97 codec. In this case, the actual MIXER interface is provided by the shared AC97 code in pcm. The CHANNEL Interface Common Notes for Function Parameters Sound drivers usually have a private data structure to describe their device, and one structure for each play and record data channel that it supports. For all CHANNEL interface functions, the first parameter is an opaque pointer. The second parameter is a pointer to the private channel data structure, except for channel_init() which has a pointer to the private device structure (and returns the channel pointer for further use by pcm). Overview of Data Transfer Operations For sound data transfers, the pcm core and the sound drivers communicate through a shared memory area, described by a struct snd_dbuf. struct snd_dbuf is private to pcm, and sound drivers obtain values of interest by calls to accessor functions (sndbuf_getxxx()). The shared memory area has a size of sndbuf_getsize() and is divided into fixed size blocks of sndbuf_getblksz() bytes. When playing, the general transfer mechanism is as follows (reverse the idea for recording): pcm initially fills up the buffer, then calls the sound driver's xxxchannel_trigger() function with a parameter of PCMTRIG_START. The sound driver then arranges to repeatedly transfer the whole memory area (sndbuf_getbuf(), sndbuf_getsize()) to the device, in blocks of sndbuf_getblksz() bytes. It calls back the chn_intr() pcm function for each transferred block (this will typically happen at interrupt time). chn_intr() arranges to copy new data to the area that was transferred to the device (now free), and make appropriate updates to the snd_dbuf structure. channel_init xxxchannel_init() is called to initialize each of the play or record channels. The calls are initiated from the sound driver attach routine. (See the probe and attach section). static void * xxxchannel_init(kobj_t obj, void *data, struct snd_dbuf *b, struct pcm_channel *c, int dir) { struct xxx_info *sc = data; struct xxx_chinfo *ch; ... return ch; } b is the address for the channel struct snd_dbuf. It should be initialized in the function by calling sndbuf_alloc(). The buffer size to use is normally a small multiple of the 'typical' unit transfer size for your device. c is the pcm channel control structure pointer. This is an opaque object. The function should store it in the local channel structure, to be used in later calls to pcm (ie: chn_intr(c)). dir indicates the channel direction (PCMDIR_PLAY or PCMDIR_REC). The function should return a pointer to the private area used to control this channel. This will be passed as a parameter to other channel interface calls. channel_setformat xxxchannel_setformat() should set up the hardware for the specified channel for the specified sound format. static int xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format) { struct xxx_chinfo *ch = data; ... return 0; } format is specified as an AFMT_XXX value (soundcard.h). channel_setspeed xxxchannel_setspeed() sets up the channel hardware for the specified sampling speed, and returns the possibly adjusted speed. static int xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed) { struct xxx_chinfo *ch = data; ... return speed; } channel_setblocksize xxxchannel_setblocksize() sets the block size, which is the size of unit transactions between pcm and the sound driver, and between the sound driver and the device. Typically, this would be the number of bytes transferred before an interrupt occurs. During a transfer, the sound driver should call pcm's chn_intr() every time this size has been transferred. Most sound drivers only take note of the block size here, to be used when an actual transfer will be started. static int xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) { struct xxx_chinfo *ch = data; ... return blocksize; } The function returns the possibly adjusted block size. In case the block size is indeed changed, sndbuf_resize() should be called to adjust the buffer. channel_trigger xxxchannel_trigger() is called by pcm to control data transfer operations in the driver. static int xxxchannel_trigger(kobj_t obj, void *data, int go) { struct xxx_chinfo *ch = data; ... return 0; } go defines the action for the current call. The possible values are: PCMTRIG_START: the driver should start a data transfer from or to the channel buffer. If needed, the buffer base and size can be retrieved through sndbuf_getbuf() and sndbuf_getsize(). PCMTRIG_EMLDMAWR / PCMTRIG_EMLDMARD: this tells the driver that the input or output buffer may have been updated. Most drivers just ignore these calls. PCMTRIG_STOP / PCMTRIG_ABORT: the driver should stop the current transfer. If the driver uses ISA DMA, sndbuf_isadma() should be called before performing actions on the device, and will take care of the DMA chip side of things. channel_getptr xxxchannel_getptr() returns the current offset in the transfer buffer. This will typically be called by chn_intr(), and this is how pcm knows where it can transfer new data. channel_free xxxchannel_free() is called to free up channel resources, for example when the driver is unloaded, and should be implemented if the channel data structures are dynamically allocated or if sndbuf_alloc() was not used for buffer allocation. channel_getcaps struct pcmchan_caps * xxxchannel_getcaps(kobj_t obj, void *data) { return &xxx_caps; } The routine returns a pointer to a (usually statically-defined) pcmchan_caps structure (defined in sound/pcm/channel.h. The structure holds the minimum and maximum sampling frequencies, and the accepted sound formats. Look at any sound driver for an example. More Functions channel_reset(), channel_resetdone(), and channel_notify() are for special purposes and should not be implemented in a driver without discussing it on the &a.multimedia;. channel_setdir() is deprecated. The MIXER Interface mixer_init xxxmixer_init() initializes the hardware and tells pcm what mixer devices are available for playing and recording static int xxxmixer_init(struct snd_mixer *m) { struct xxx_info *sc = mix_getdevinfo(m); u_int32_t v; [Initialize hardware] [Set appropriate bits in v for play mixers] mix_setdevs(m, v); [Set appropriate bits in v for record mixers] mix_setrecdevs(m, v) return 0; } Set bits in an integer value and call mix_setdevs() and mix_setrecdevs() to tell pcm what devices exist. Mixer bits definitions can be found in soundcard.h (SOUND_MASK_XXX values and SOUND_MIXER_XXX bit shifts). mixer_set xxxmixer_set() sets the volume level for one mixer device. static int xxxmixer_set(struct snd_mixer *m, unsigned dev, unsigned left, unsigned right) { struct sc_info *sc = mix_getdevinfo(m); [set volume level] return left | (right << 8); } The device is specified as a SOUND_MIXER_XXX value The volume values are specified in range [0-100]. A value of zero should mute the device. As the hardware levels probably will not match the input scale, and some rounding will occur, the routine returns the actual level values (in range 0-100) as shown. mixer_setrecsrc xxxmixer_setrecsrc() sets the recording source device. static int xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src) { struct xxx_info *sc = mix_getdevinfo(m); [look for non zero bit(s) in src, set up hardware] [update src to reflect actual action] return src; } The desired recording devices are specified as a bit field The actual devices set for recording are returned. Some drivers can only set one device for recording. The function should return -1 if an error occurs. mixer_uninit, mixer_reinit xxxmixer_uninit() should ensure that all sound is muted and if possible mixer hardware should be powered down xxxmixer_reinit() should ensure that the mixer hardware is powered up and any settings not controlled by mixer_set() or mixer_setrecsrc() are restored. The AC97 Interface AC97 The AC97 interface is implemented by drivers with an AC97 codec. It only has three methods: xxxac97_init() returns the number of ac97 codecs found. ac97_read() and ac97_write() read or write a specified register. The AC97 interface is used by the AC97 code in pcm to perform higher level operations. Look at sound/pci/maestro3.c or many others under sound/pci/ for an example. diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml index 6d7432628c..75a575f28a 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml @@ -1,560 +1,558 @@ Poul-Henning Kamp Contributed by Giorgos Keramidas Source Tree Guidelines and Policies This chapter documents various guidelines and policies in force for the FreeBSD source tree. Style Guidelines style Consistent coding style is extremely important, particularly with large projects like &os;. Code should follow the &os; coding styles described in &man.style.9; and &man.style.Makefile.5;. <makevar>MAINTAINER</makevar> on Makefiles ports maintainer If a particular portion of the &os; src/ distribution is being maintained by a person or group of persons, this is communicated through an entry in the src/MAINTAINERS file. Maintainers of ports within the Ports Collection express their maintainership to the world by adding a MAINTAINER line to the Makefile of the port in question: MAINTAINER= email-addresses For other parts of the repository, or for sections not listed as having a maintainer, or when you are unsure who the active maintainer is, try looking at the recent commit history of the relevant parts of the source tree. It is quite often the case that a maintainer is not explicitly named, but the people who are actively working in a part of the source tree for, say, the last couple of years are interested in reviewing changes. Even if this is not specifically mentioned in the documentation or the source itself, asking for a review as a form of courtesy is a very reasonable thing to do. The role of the maintainer is as follows: The maintainer owns and is responsible for that code. This means that he or she is responsible for fixing bugs and answering problem reports pertaining to that piece of the code, and in the case of contributed software, for tracking new versions, as appropriate. Changes to directories which have a maintainer defined shall be sent to the maintainer for review before being committed. Only if the maintainer does not respond for an unacceptable period of time, to several emails, will it be acceptable to commit changes without review by the maintainer. However, it is suggested that you try to have the changes reviewed by someone else if at all possible. It is of course not acceptable to add a person or group as maintainer unless they agree to assume this duty. On the other hand it does not have to be a committer and it can easily be a group of people. Poul-Henning Kamp Contributed by David O'Brien Gavin Atkinson Contributed Software contributed software Some parts of the FreeBSD distribution consist of software that is actively being maintained outside the FreeBSD project. For historical reasons, we call this contributed software. Some examples are sendmail, gcc and patch. Over the last couple of years, various methods have been used in dealing with this type of software and all have some number of advantages and drawbacks. No clear winner has emerged. Since this is the case, after some debate one of these methods has been selected as the official method and will be required for future imports of software of this kind. Furthermore, it is strongly suggested that existing contributed software converge on this model over time, as it has significant advantages over the old method, including the ability to easily obtain diffs relative to the official versions of the source by everyone (even without direct repository access). This will make it significantly easier to return changes to the primary developers of the contributed software. Ultimately, however, it comes down to the people actually doing the work. If using this model is particularly unsuited to the package being dealt with, exceptions to these rules may be granted only with the approval of the core team and with the general consensus of the other developers. The ability to maintain the package in the future will be a key issue in the decisions. Because it makes it harder to import future versions minor, trivial and/or cosmetic changes are strongly discouraged on files that are still tracking the vendor branch. Dag-Erling Smørgrav Contributed by Vendor Imports with SVN This section describes the vendor import procedure with Subversion in details. Preparing the Tree If this is your first import after the switch to SVN, you will have to flatten and clean up the vendor tree, and bootstrap merge history in the main tree. If not, you can safely omit this step. During the conversion from CVS to SVN, vendor branches were imported with the same layout as the main tree. For example, the foo vendor sources ended up in vendor/foo/dist/contrib/foo, but it is pointless and rather inconvenient. What we really want is to have the vendor source directly in vendor/foo/dist, like this: &prompt.user; cd vendor/foo/dist/contrib/foo &prompt.user; svn move $(svn list) ../.. &prompt.user; cd ../.. &prompt.user; svn remove contrib &prompt.user; svn propdel svn:mergeinfo &prompt.user; svn commit Note that, the propdel bit is necessary because starting with 1.5, Subversion will automatically add svn:mergeinfo to any directory you copy or move. In this case, you will not need this information, since you are not going to merge anything from the tree you deleted. You may want to flatten the tags as well. The procedure is exactly the same. If you do this, put off the commit until the end. Check the dist tree and perform any cleanup that is deemed to be necessary. You may want to disable keyword expansion, as it makes no sense on unmodified vendor code. In some cases, it can be even be harmful. &prompt.user; svn propdel svn:keywords . &prompt.user; svn commit Bootstrapping of svn:mergeinfo on the target directory (in the main tree) to the revision that corresponds to the last change was made to the vendor tree prior to importing new sources is also needed: &prompt.user; cd head/contrib/foo &prompt.user; svn merge svn_base/vendor/foo/dist@12345678 . &prompt.user; svn commit where svn_base is the base directory of your SVN repository, e.g. svn+ssh://svn.FreeBSD.org/base. Importing New Sources Prepare a full, clean tree of the vendor sources. With SVN, we can keep a full distribution in the vendor tree without bloating the main tree. Import everything but merge only what is needed. Note that you will need to add any files that were added since the last vendor import, and remove any that were removed. To facilitate this, you should prepare sorted lists of the contents of the vendor tree and of the sources you are about to import: &prompt.user; cd vendor/foo/dist &prompt.user; svn list | grep '/$' | sort > ../old &prompt.user; cd ../foo-9.9 &prompt.user; find . f | cut 3- | sort > ../new With these two files, the following command will list list removed files (files only in old): &prompt.user; comm ../old ../new While the command below will list added files (files only in new): &prompt.user; comm ../old ../new Let's put this together: &prompt.user; cd vendor/foo/foo-9.9 &prompt.user; tar cf - . | tar xf - ../dist &prompt.user; cd ../dist &prompt.user; comm ../old ../new | xargs svn remove &prompt.user; comm ../old ../new | xargs svn add If there are new directories in the new distribution, the last command will fail. You will have to add the directories, and run it again. Conversely, if any directories were removed, you will have to remove them manually. Check properties on any new files: All text files should have svn:eol-style set to native. All binary files should have svn:mime-type set to application/octet-stream, unless there is a more appropriate media type. Executable files should have svn:executable set to *. There should be no other properties on any file in the tree. You are ready to commit, but you should first check the output of svn stat and svn diff to make sure everything is in order. Once you have committed the new vendor release, you should tag it for future reference. The best and quickest way is to do it directly in the repository: &prompt.user; svn copy svn_base/vendor/foo/dist svn_base/vendor/foo/9.9 To get the new tag, you can update your working copy of vendor/foo. If you choose to do the copy in the checkout instead, do not forget to remove the generated svn:mergeinfo as described above. Merging to <emphasis>-HEAD</emphasis> After you have prepared your import, it is time to merge. Option tells SVN not to handle merge conflicts yet, because they will be taken care of manually: &prompt.user; cd head/contrib/foo &prompt.user; svn update &prompt.user; svn merge svn_base/vendor/foo/dist Resolve any conflicts, and make sure that any files that were added or removed in the vendor tree have been properly added or removed in the main tree. It is always a good idea to check differences against the vendor branch: &prompt.user; svn diff svn_base/vendor/foo/dist . The option tells SVN not to check files that are in the vendor tree but not in the main tree. With SVN, there is no concept of on or off the vendor branch. If a file that previously had local modifications no longer does, just remove any left-over cruft, such as &os; version tags, so it no longer shows up in diffs against the vendor tree. If any changes are required for the world to build with the new sources, make them now — and test until you are satisfied that everything build and runs correctly. Commit Now, you are ready to commit. Make sure you get everything in one go. Ideally, you would have done all steps in a clean tree, in which case you can just commit from the top of that tree. That is the best way to avoid surprises. If you do it properly, the tree will move atomically from a consistent state with the old code to a consistent state with the new code. Encumbered Files It might occasionally be necessary to include an encumbered file in the FreeBSD source tree. For example, if a device requires a small piece of binary code to be loaded to it before the device will operate, and we do not have the source to that code, then the binary file is said to be encumbered. The following policies apply to including encumbered files in the FreeBSD source tree. Any file which is interpreted or executed by the system CPU(s) and not in source format is encumbered. Any file with a license more restrictive than BSD or GNU is encumbered. A file which contains downloadable binary data for use by the hardware is not encumbered, unless (1) or (2) apply to it. It must be stored in an architecture neutral ASCII format (file2c or uuencoding is recommended). Any encumbered file requires specific approval from the Core Team before it is added to the repository. Encumbered files go in src/contrib or src/sys/contrib. The entire module should be kept together. There is no point in splitting it, unless there is code-sharing with non-encumbered code. Object files are named arch/filename.o.uu>. Kernel files: Should always be referenced in conf/files.* (for build simplicity). Should always be in LINT, but the Core Team decides per case if it should be commented out or not. The Core Team can, of course, change their minds later on. The Release Engineer decides whether or not it goes into the release. User-land files: - core team - The Core team decides if + The Core teamcore team decides if the code should be part of make world. - release engineering - The Release Engineering + The Release Engineeringrelease engineering decides if it goes into the release. Satoshi Asami Contributed by Peter Wemm David O'Brien Shared Libraries If you are adding shared library support to a port or other piece of software that does not have one, the version numbers should follow these rules. Generally, the resulting numbers will have nothing to do with the release version of the software. The three principles of shared library building are: Start from 1.0 If there is a change that is backwards compatible, bump minor number (note that ELF systems ignore the minor number) If there is an incompatible change, bump major number For instance, added functions and bugfixes result in the minor version number being bumped, while deleted functions, changed function call syntax, etc. will force the major version number to change. Stick to version numbers of the form major.minor (x.y). Our a.out dynamic linker does not handle version numbers of the form x.y.z well. Any version number after the y (i.e. the third digit) is totally ignored when comparing shared lib version numbers to decide which library to link with. Given two shared libraries that differ only in the micro revision, ld.so will link with the higher one. That is, if you link with libfoo.so.3.3.3, the linker only records 3.3 in the headers, and will link with anything starting with libfoo.so.3.(anything >= 3).(highest available). ld.so will always use the highest minor revision. For instance, it will use libc.so.2.2 in preference to libc.so.2.0, even if the program was initially linked with libc.so.2.0. In addition, our ELF dynamic linker does not handle minor version numbers at all. However, one should still specify a major and minor version number as our Makefiles do the right thing based on the type of system. For non-port libraries, it is also our policy to change the shared library version number only once between releases. In addition, it is our policy to change the major shared library version number only once between major OS releases (i.e. from 6.0 to 7.0). When you make a change to a system library that requires the version number to be bumped, check the Makefile's commit logs. It is the responsibility of the committer to ensure that the first such change since the release will result in the shared library version number in the Makefile to be updated, and any subsequent changes will not. diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.xml b/en_US.ISO8859-1/books/handbook/boot/chapter.xml index c13bec3bbb..55da99f249 100644 --- a/en_US.ISO8859-1/books/handbook/boot/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/boot/chapter.xml @@ -1,1022 +1,1016 @@ The &os; Booting Process Synopsis booting bootstrap The process of starting a computer and loading the operating system is referred to as the bootstrap process, or simply booting. &os;'s boot process provides a great deal of flexibility in customizing what happens when the system starts, including the ability to select from different operating systems installed on the same computer, different versions of the same operating system, or a different installed kernel. This chapter details the configuration options that can be set. It demonstrates how to customize the &os; boot process, including everything that happens until the &os; kernel has started, probed for devices, and started &man.init.8;. This occurs when the text color of the boot messages changes from bright white to grey. After reading this chapter, you will recognize: The components of the &os; bootstrap system and how they interact. The options that can be passed to the components in the &os; bootstrap in order to control the boot process. The basics of &man.device.hints.5;. This chapter only describes the boot process for &os; running on Intel x86 systems. The Booting Problem Turning on a computer and starting the operating system poses an interesting dilemma. By definition, the computer does not know how to do anything until the operating system is started. This includes running programs from the disk. If the computer can not run a program from the disk without the operating system, and the operating system programs are on the disk, how is the operating system started? This problem parallels one in the book The Adventures of Baron Munchausen. A character had fallen part way down a manhole, and pulled himself out by grabbing his bootstraps, and lifting. In the early days of computing the term bootstrap was applied to the mechanism used to load the operating system, which has become shortened to booting. BIOS Basic Input/Output System BIOS On x86 hardware the Basic Input/Output System (BIOS) is responsible for loading the operating system. To do this, the BIOS looks on the hard disk for the Master Boot Record (MBR), which must be located in a specific place on the disk. The BIOS has enough knowledge to load and run the MBR, and assumes that the MBR can then carry out the rest of the tasks involved in loading the operating system, possibly with the help of the BIOS. Master Boot Record MBR) Boot Manager Boot Loader The code within the MBR is usually referred to as a boot manager, especially when it interacts with the user. In this case, the boot manager usually has more code in the first track of the disk or within the file system of some operating systems. A boot manager is sometimes also called a boot loader, but &os; uses that term for a later stage of booting. Popular boot managers include boot0, also called Boot Easy, the standard &os; boot manager, Grub, GAG, and LILO. Only boot0 fits within the MBR. If only one operating system is installed, a standard PC MBR will suffice. This MBR searches for the first bootable (active) slice on the disk, and then runs the code on that slice to load the remainder of the operating system. By default, the MBR installed by &man.fdisk.8; is such an MBR and is based on /boot/mbr. If multiple operating systems are present, a different boot manager can be installed which displays the list of operating systems so that the user can choose which one to boot from. Two boot managers are discussed in the next subsection. The remainder of the &os; bootstrap system is divided into three stages. The first stage is run by the MBR, which knows just enough to get the computer into a specific state and run the second stage. The second stage can do a little bit more, before running the third stage. The third stage finishes the task of loading the operating system. The work is split into three stages because PC standards put limits on the size of the programs that can be run at stages one and two. Chaining the tasks together allows &os; to provide a more flexible loader. kernel &man.init.8; The kernel is then started and it begins to probe for devices and initialize them for use. Once the kernel boot process is finished, the kernel passes control to the user process &man.init.8;, which then makes sure the disks are in a usable state. &man.init.8; then starts the user-level resource configuration which mounts file systems, sets up network cards to communicate on the network, and starts the processes which have been configured to run on a &os; system at startup. The Boot Manager and Boot Stages Boot Manager The Boot Manager Master Boot Record (MBR) The code in the MBR or boot manager is sometimes referred to as stage zero of the boot process. This section discusses two boot managers: boot0 and LILO. The <application>boot0</application> Boot Manager: The MBR installed by &os;'s installer or &man.boot0cfg.8; is based on /boot/boot0. The size and capability of boot0 is restricted to 446 bytes due to the slice table and 0x55AA identifier at the end of the MBR. If boot0 and multiple operating systems are installed, a message similar to this example will be displayed at boot time: <filename>boot0</filename> Screenshot F1 Win F2 FreeBSD Default: F2 Other operating systems, in particular &windows;, will overwrite an existing MBR if they are installed after &os;. If this happens, or to replace the existing MBR with the &os; MBR, use the following command: &prompt.root; fdisk -B -b /boot/boot0 device where device is the boot disk, such as ad0 for the first IDE disk, ad2 for the first IDE disk on a second IDE controller, or da0 for the first SCSI disk. To create a custom configuration of the MBR, refer to &man.boot0cfg.8;. The LILO Boot Manager: To install this boot manager so it will also boot &os;, boot into Linux and add the following to the existing /etc/lilo.conf configuration: other=/dev/hdXY table=/dev/hdX loader=/boot/chain.b label=FreeBSD Specify &os;'s primary partition and drive using Linux specifiers, replacing X with the Linux drive letter and Y with the Linux primary partition number. For a SCSI drive, change /dev/hd to /dev/sd. The line can be omitted if both operating systems are installed on the same drive. Next, run /sbin/lilo -v to commit the new changes. Verify these are correct by checking the screen messages. Stage One, <filename>/boot/boot1</filename>, and Stage Two, <filename>/boot/boot2</filename> Conceptually, the first and second stages are part of the same program, on the same area of the disk. Because of space constraints, they have been split into two, but are always installed together. They are copied from the combined /boot/boot by the installer or &man.bsdlabel.8;. They are located outside file systems, in the first track of the boot slice, starting with the first sector. This is where boot0 (), or any other boot manager, expects to find a program to run which will continue the boot process. The number of sectors used is easily determined from the size of /boot/boot. boot1 is very simple, since it can only be 512 bytes in size, and knows just enough about the &os; bsdlabel, which stores information about the slice, to find and execute boot2. boot2 is slightly more sophisticated, and understands the &os; file system enough to find files, and can provide a simple interface to choose the kernel or loader to run. However, &man.loader.8; is much more sophisticated and provides a boot configuration which is run by boot2. <filename>boot2</filename> Screenshot >> FreeBSD/i386 BOOT Default: 0:ad(0,a)/boot/loader boot: &man.bsdlabel.8; can be used to replace the installed boot1 and boot2: &prompt.root; bsdlabel -B diskslice where diskslice is the disk and slice to boot from, such as ad0s1 for the first slice on the first IDE disk. Dangerously Dedicated Mode If just the disk name is used, such as ad0, &man.bsdlabel.8; will create a dangerously dedicated disk, without slices. This is probably not the desired action, so double check the diskslice passed to &man.bsdlabel.8; before pressing Return. Stage Three, <filename>/boot/loader</filename> boot-loader The loader is the final stage of the three-stage bootstrap, and is located on the file system, usually as /boot/loader. The loader is intended as an interactive method for configuration, using a built-in command set, backed up by a more powerful interpreter which has a more complex command set. Loader Program Flow During initialization, the loader will probe for a console and for disks, and figure out which disk it is booting from. It will set variables accordingly, and an interpreter is started where user commands can be passed from a script or interactively. loader loader configuration The loader will then read /boot/loader.rc, which by default reads in /boot/defaults/loader.conf which sets reasonable defaults for variables and reads /boot/loader.conf for local changes to those variables. loader.rc then acts on these variables, loading whichever modules and kernel are selected. Finally, by default, the loader issues a 10 second wait for key presses, and boots the kernel if it is not interrupted. If interrupted, the user is presented with a prompt which understands the command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot. Loader Built-In Commands These are the most commonly used loader commands. For a complete discussion of all available commands, refer to &man.loader.8;. autoboot seconds Proceeds to boot the kernel if not interrupted within the time span given, in seconds. It displays a countdown, and the default time span is 10 seconds. boot -options kernelname Immediately proceeds to boot the kernel, with any specified options or kernel name. Providing a kernel name on the command-line is only applicable after an unload command has been issued; otherwise the previously-loaded kernel will be used. boot-conf Goes through the same automatic configuration of modules based on specified variables, most commonly kernel. This only makes sense if unload is used first, before changing some variables. help topic Shows help messages read from /boot/loader.help. If the topic given is index, the list of available topics is displayed. include filename … Processes the file with the given filename. The file is read in and interpreted line by line. An error immediately stops the include command. load type filename Loads the kernel, kernel module, or file of the type given, with the specified filename. Any arguments after filename are passed to the file. ls path Displays a listing of files in the given path, or the root directory, if the path is not specified. If is specified, file sizes will also be shown. lsdev Lists all of the devices from which it may be possible to load modules. If is specified, more details are printed. lsmod Displays loaded modules. If is specified, more details are shown. more filename Displays the files specified, with a pause at each LINES displayed. reboot Immediately reboots the system. set variable set variable=value Sets the loader's environment variables. unload Removes all loaded modules. Loader Examples Here are some practical examples of loader usage: - single-user mode - - To boot the usual kernel in single-user mode: + To boot the usual kernel in single-user modesingle-user mode: boot -s To unload the usual kernel and modules, and then load the previous or another kernel: - - kernel.old - - unload load kernel.old Use kernel.GENERIC to refer to the default kernel that comes with an installation, or - kernel.old to refer to the + kernel.oldkernel.old to refer to the previously installed kernel before a system upgrade or before configuring a custom kernel. Use the following to load the usual modules with another kernel: unload set kernel="kernel.old" boot-conf To load an automated kernel configuration script: load -t userconfig_script /boot/kernel.conf Joseph J. Barbish Contributed by Boot Time Splash Screens The splash screen creates an alternate boot screen. The splash screen hides all the boot probe messages and service startup messages before displaying either a command line or graphical login prompt. There are two basic environments available in &os;. The first is the default legacy virtual console command line environment. After the system finishes booting, a console login prompt is presented. The second environment is the graphical environment as described in . Refer to that chapter for more information on how to install and configure a graphical display manager and a graphical login manager. Splash Screen Function The splash screen function supports 256-colors in the bitmap (.bmp), ZSoft PCX (.pcx), or TheDraw (.bin) formats. The splash image files must have a resolution of 320 by 200 pixels or less in order to work on standard VGA adapters. To use larger images, up to the maximum resolution of 1024 by 768 pixels, load the VESA module during system boot. For a custom kernel, as described in , include the VESA kernel configuration option. Loading VESA support provides the ability to display a splash screen image that fills the whole display screen. While the splash screen is being displayed during the booting process, it can be turned off any time by hitting any key on the keyboard. The splash screen also defaults to being a screen saver outside. After a time period of non-use, the splash screen will be displayed and will cycle through steps of changing intensity of the image, from bright to very dark and over again. The configuration of the splash screen saver can be overridden by adding a saver= line to /etc/rc.conf. Several built-in screen savers are available and described in &man.splash.4;. The saver= option only applies to virtual consoles and has no effect on graphical display managers. A few boot loader messages, including the boot options menu and a timed wait count down prompt, are displayed at boot time, even when the splash screen is enabled. Sample splash screen files can be downloaded from the gallery at http://artwork.freebsdgr.org. By installing the sysutils/bsd-splash-changer port, splash images can be chosen from a collection randomly at each boot. Enabling the Splash Screen Function The splash screen .bmp, .pcx, or .bin image has to be placed on the root partition, for example in /boot. For the default boot display resolution of 256-colors and 320 by 200 pixels or less, edit /boot/loader.conf so it contains the following: splash_bmp_load="YES" bitmap_load="YES" bitmap_name="/boot/splash.bmp" For larger video resolutions up to the maximum of 1024 by 768 pixels, edit /boot/loader.conf, so it contains the following: vesa_load="YES" splash_bmp_load="YES" bitmap_load="YES" bitmap_name="/boot/splash.bmp" This example assumes that /boot/splash.bmp is used for the splash screen. To use a PCX file, use the following statements, plus the vesa_load="YES" line, depending on the resolution: splash_pcx_load="YES" bitmap_load="YES" bitmap_name="/boot/splash.pcx" Beginning with &os; 8.3, another option is to use ASCII art in TheDraw format. splash_txt="YES" bitmap_load="YES" bitmap_name="/boot/splash.bin" The file name is not restricted to splash as shown in the above example. It can be anything as long as it is one of the supported types such as, splash_640x400.bmp or bluewave.pcx. Other interesting loader.conf options include: beastie_disable="YES" This will stop the boot options menu from being displayed, but the timed wait count down prompt will still be present. Even with the display of the boot options menu disabled, entering an option selection at the timed wait count down prompt will enact the corresponding boot option. loader_logo="beastie" This will replace the default words &os;, which are displayed to the right of the boot options menu with the colored beastie logo. For more information, refer to &man.splash.4;, &man.loader.conf.5;, and &man.vga.4;. Kernel Interaction During Boot kernel boot interaction Once the kernel is loaded by either the default loader () or by boot2 (), which bypasses the loader, it examines any boot flags and adjusts its behavior as necessary. Kernel Boot Flags kernel bootflags Here are the more common boot flags: During kernel initialization, ask for the device to mount as the root file system. Boot from CDROM. Run UserConfig, the boot-time kernel configurator. Boot into single-user mode. Be more verbose during kernel startup. Refer to &man.boot.8; for more information on the other boot flags. Tom Rhodes Contributed by Device Hints device.hints During initial system startup, the boot &man.loader.8; reads &man.device.hints.5;. This file stores kernel boot information known as variables, sometimes referred to as device hints. These device hints are used by device drivers for device configuration. Device hints may also be specified at the Stage 3 boot loader prompt, as demonstrated in . Variables can be added using set, removed with unset, and viewed show. Variables set in /boot/device.hints can also be overridden. Device hints entered at the boot loader are not permanent and will not be applied on the next reboot. Once the system is booted, &man.kenv.1; can be used to dump all of the variables. The syntax for /boot/device.hints is one variable per line, using the hash # as comment markers. Lines are constructed as follows: hint.driver.unit.keyword="value" The syntax for the Stage 3 boot loader is: set hint.driver.unit.keyword=value where driver is the device driver name, unit is the device driver unit number, and keyword is the hint keyword. The keyword may consist of the following options: at: specifies the bus which the device is attached to. port: specifies the start address of the I/O to be used. irq: specifies the interrupt request number to be used. drq: specifies the DMA channel number. maddr: specifies the physical memory address occupied by the device. flags: sets various flag bits for the device. disabled: if set to 1 the device is disabled. Since device drivers may accept or require more hints not listed here, viewing a driver's manual page is recommended. For more information, refer to &man.device.hints.5;, &man.kenv.1;, &man.loader.conf.5;, and &man.loader.8;. Init: Process Control Initialization &man.init.8; Once the kernel has finished booting, it passes control to the user process &man.init.8;, which is located at /sbin/init, or the program path specified in the init_path variable in loader. Automatic Reboot Sequence The automatic reboot sequence makes sure that the file systems available on the system are consistent. If they are not, and &man.fsck.8; cannot fix the inconsistencies of a UFS file system, &man.init.8; drops the system into single-user mode () so that the system administrator can resolve the problem directly. Single-User Mode single-user mode console This mode can be reached through the automatic reboot sequence (), the user booting with , or by setting the boot_ single variable in &man.loader.8;. It can also be reached by calling &man.shutdown.8; from multi-user mode () without including or . If the system console is set to insecure in /etc/ttys, the system will prompt for the root password before initiating single-user mode. An Insecure Console in <filename>/etc/ttys</filename> # name getty type status comments # # If console is marked "insecure", then init will ask for the root password # when going to single-user mode. console none unknown off insecure An insecure console means that physical security to the console is considered to be insecure, so only someone who knows the root password may use single-user mode. Thus, to add this measure of security, choose insecure, instead of the default of secure. Multi-User Mode multi-user mode If &man.init.8; finds the file systems to be in order, or once the user has finished their commands in single-user mode (), the system enters multi-user mode, in which it starts the resource configuration of the system. Resource Configuration rc files The resource configuration system reads in configuration defaults from /etc/defaults/rc.conf, and system-specific details from /etc/rc.conf, and then proceeds to mount the system file systems listed in /etc/fstab. It starts up networking services, miscellaneous system daemons, then the startup scripts of locally installed packages. To learn more about the resource configuration system, refer to &man.rc.8; and examine the scripts themselves. Shutdown Sequence &man.shutdown.8; Upon controlled shutdown using &man.shutdown.8;, &man.init.8; will attempt to run the script /etc/rc.shutdown, and then proceed to send all processes the TERM signal, and subsequently the KILL signal to any that do not terminate in a timely manner. To power down a &os; machine on architectures and systems that support power management, use shutdown -p now to turn the power off immediately. To reboot a &os; system, use shutdown -r now. One must be root or a member of operator in order to run &man.shutdown.8;. One can also use &man.halt.8; and &man.reboot.8;. Refer to their manual pages and to &man.shutdown.8; for more information. Power management requires &man.acpi.4; to be loaded as a module or staticly compiled into a custom kernel. diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml index 4be1c5afae..d240376426 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml @@ -1,3153 +1,3103 @@ Jim Mock Restructured, reorganized, and parts updated by Jordan Hubbard Original work by Poul-Henning Kamp John Polstra Nik Clayton Updating and Upgrading &os; Synopsis &os; is under constant development between releases. Some people prefer to use the officially released versions, while others prefer to keep in sync with the latest developments. However, even official releases are often updated with security and other critical fixes. Regardless of the version used, &os; provides all the necessary tools to keep the system updated, and allows for easy upgrades between versions. This chapter describes how to track the development system and the basic tools for keeping a &os; system up-to-date. After reading this chapter, you will know: Which utilities are available to update the system and the Ports Collection. How to keep a &os; system up-to-date with freebsd-update, Subversion, or CTM. How to compare the state of an installed system against a known pristine copy. How to keep the installed documentation up-to-date with Subversion or documentation ports. The difference between the two development branches: &os.stable; and &os.current;. How to rebuild and reinstall the entire base system. Before reading this chapter, you should: Properly set up the network connection (). Know how to install additional third-party software (). Throughout this chapter, svn is used to obtain and update &os; sources. To use it, first install the devel/subversion port or package. Tom Rhodes Written by Colin Percival Based on notes provided by &os; Update Updating and Upgrading freebsd-update updating-upgrading Applying security patches is an important part of maintaining computer software, especially the operating system. For the longest time on &os;, this process was not an easy one. Patches had to be applied to the source code, the code rebuilt into binaries, and then the binaries had to be re-installed. This is no longer the case as &os; now includes a utility called freebsd-update. This utility provides two separate functions. First, it allows for binary security and errata updates to be applied to the &os; base system without the build and install requirements. Second, the utility supports minor and major release upgrades. Binary updates are available for all architectures and releases currently supported by the security team. Before updating to a new release, its release announcement should be reviewed as it contains important information pertinent to the release. Release announcements are available from . If a crontab utilizing the features of &man.freebsd-update.8; exists, it must be disabled before the following operation is started. The Configuration File Some users may wish to tweak the default configuration in /etc/freebsd-update.conf, allowing better control of the process. The options are well documented, but the following may require a bit more explanation: # Components of the base system which should be kept updated. Components src world kernel This parameter controls which parts of &os; will be kept up-to-date. The default is to update the source code, the entire base system, and the kernel. Components are the same as those available during installation. For instance, adding world/games would allow game patches to be applied. Using src/bin would allow the source code in src/bin to be updated. The best option is to leave this at the default as changing it to include specific items requires the user to list every item to be updated. This could have disastrous consequences as source code and binaries may become out of sync. # Paths which start with anything matching an entry in an IgnorePaths # statement will be ignored. IgnorePaths To leave specified directories, such as /bin or /sbin, untouched during the update process, add their paths to this statement. This option may be used to prevent freebsd-update from overwriting local modifications. # Paths which start with anything matching an entry in an UpdateIfUnmodified # statement will only be updated if the contents of the file have not been # modified by the user (unless changes are merged; see below). UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile This option will only update unmodified configuration files in the specified directories. Any changes made by the user will invalidate the automatic updating of these files. There is another option, KeepModifiedMetadata, which will instruct freebsd-update to save the changes during the merge. # When upgrading to a new &os; release, files which match MergeChanges # will have any local changes merged into the version from the new release. MergeChanges /etc/ /var/named/etc/ List of directories with configuration files that freebsd-update should attempt to merge. The file merge process is a series of &man.diff.1; patches similar to &man.mergemaster.8;, but with fewer options. Merges are either accepted, open an editor, or freebsd-update will abort. When in doubt, backup /etc and just accept the merges. See for more information about mergemaster. # Directory in which to store downloaded updates and temporary # files used by &os; Update. # WorkDir /var/db/freebsd-update This directory is where all patches and temporary files are placed. In cases where the user is doing a version upgrade, this location should have a least a gigabyte of disk space available. # When upgrading between releases, should the list of Components be # read strictly (StrictComponents yes) or merely as a list of components # which *might* be installed of which &os; Update should figure out # which actually are installed and upgrade those (StrictComponents no)? # StrictComponents no When this option is set to yes, freebsd-update will assume that the Components list is complete and will not attempt to make changes outside of the list. Effectively, freebsd-update will attempt to update every file which belongs to the Components list. Security Patches &os; security patches may be downloaded and installed using the following command: &prompt.root; freebsd-update fetch &prompt.root; freebsd-update install If the update applied any kernel patches, the system will need a reboot in order to boot into the patched kernel. Otherwise, the system should be patched and freebsd-update may be run as a nightly &man.cron.8; job by adding this entry to /etc/crontab: @daily root freebsd-update cron This entry states that freebsd-update will run once every day. When run with , freebsd-update will only check if updates exist. If patches exist, they will automatically be downloaded to the local disk but will not be applied. The root user will be sent an email so that they may be reviewed and manually installed. If anything goes wrong, freebsd-update has the ability to roll back the last set of changes with the following command: &prompt.root; freebsd-update rollback Once complete, the system should be restarted if the kernel or any kernel modules were modified. This will allow &os; to load the new binaries into memory. Only the GENERIC kernel can be automatically updated by freebsd-update. If a custom kernel is installed, it will have to be rebuilt and reinstalled after freebsd-update finishes installing the rest of the updates. However, freebsd-update will detect and update the GENERIC kernel if /boot/GENERIC exists, even if it is not the current running kernel of the system. It is a good idea to always keep a copy of the GENERIC kernel in /boot/GENERIC. It will be helpful in diagnosing a variety of problems, and in performing version upgrades using freebsd-update as described in . Unless the default configuration in /etc/freebsd-update.conf has been changed, freebsd-update will install the updated kernel sources along with the rest of the updates. Rebuilding and reinstalling a new custom kernel can then be performed in the usual way. The updates distributed by freebsd-update do not always involve the kernel. It is not necessary to rebuild a custom kernel if the kernel sources have not been modified by the execution of freebsd-update install. However, freebsd-update will always update /usr/src/sys/conf/newvers.sh. The current patch level, as indicated by the -p number reported by uname -r, is obtained from this file. Rebuilding a custom kernel, even if nothing else changed, allows &man.uname.1; to accurately report the current patch level of the system. This is particularly helpful when maintaining multiple systems, as it allows for a quick assessment of the updates installed in each one. Major and Minor Version Upgrades Upgrades from one minor version of &os; to another, like from &os; 9.0 to &os; 9.1, are called minor version upgrades. Generally, installed applications will continue to work without problems after minor version upgrades. Major version upgrades occur when &os; is upgraded from one major version to another, like from &os; 8.X to &os; 9.X. Major version upgrades remove old object files and libraries which will break most third party applications. It is recommended that all installed ports either be removed and re-installed or upgraded after a major version upgrade using a utility such as ports-mgmt/portmaster. A brute-force rebuild of all installed applications can be accomplished with this command: &prompt.root; portmaster -af This will ensure everything will be re-installed correctly. Note that setting the BATCH environment variable to yes will answer yes to any prompts during this process, removing the need for manual intervention during the build process. Dealing with Custom Kernels If a custom kernel is in use, the upgrade process is slightly more involved, and the procedure varies depending on the version of &os;. Custom Kernels with &os; 8.X A copy of the GENERIC kernel is needed, and should be placed in /boot/GENERIC. If the GENERIC kernel is not present in the system, it may be obtained using one of the following methods: If a custom kernel has only been built once, the kernel in /boot/kernel.old is actually GENERIC. Rename this directory to /boot/GENERIC. Assuming physical access to the machine is possible, a copy of the GENERIC kernel can be installed from the installation media using the following commands: &prompt.root; mount /cdrom &prompt.root; cd /cdrom/X.Y-RELEASE/kernels &prompt.root; ./install.sh GENERIC Replace X.Y-RELEASE with the actual version of the release being used. The GENERIC kernel will be installed in /boot/GENERIC by default. Failing all the above, the GENERIC kernel may be rebuilt and installed from source: &prompt.root; cd /usr/src &prompt.root; env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null &prompt.root; mv /boot/GENERIC/boot/kernel/* /boot/GENERIC &prompt.root; rm -rf /boot/GENERIC/boot For this kernel to be picked up as GENERIC by freebsd-update, the GENERIC configuration file must not have been modified in any way. It is also suggested that it is built without any other special options. Rebooting to the GENERIC kernel is not required at this stage. Custom Kernels with &os; 9.X and Later If a custom kernel has only been built once, the kernel in /boot/kernel.old is actually the GENERIC kernel. Rename this directory to /boot/kernel. If physical access to the machine is available, a copy of the GENERIC kernel can be installed from the installation media using these commands: &prompt.root; mount /cdrom &prompt.root; cd /cdrom/usr/freebsd-dist &prompt.root; tar -C/ -xvf kernel.txz boot/kernel/kernel If the options above cannot be used, the GENERIC kernel may be rebuilt and installed from source: &prompt.root; cd /usr/src &prompt.root; make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null For this kernel to be identified as the GENERIC kernel by freebsd-update, the GENERIC configuration file must not have been modified in any way. It is also suggested that the kernel is built without any other special options. Rebooting to the GENERIC kernel is not required at this stage. Performing the Upgrade Major and minor version upgrades may be performed by providing freebsd-update with a release version target. The following command will update to &os; 9.1: &prompt.root; freebsd-update -r 9.1-RELEASE upgrade After the command has been received, freebsd-update will evaluate the configuration file and current system in an attempt to gather the information necessary to perform the upgrade. A screen listing will display which components have and have not been detected. For example: Looking up update.FreeBSD.org mirrors... 1 mirrors found. Fetching metadata signature for 9.0-RELEASE from update1.FreeBSD.org... done. Fetching metadata index... done. Inspecting system... done. The following components of FreeBSD seem to be installed: kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin world/base world/info world/lib32 world/manpages The following components of FreeBSD do not seem to be installed: kernel/generic world/catpages world/dict world/doc world/games world/proflibs Does this look reasonable (y/n)? y At this point, freebsd-update will attempt to download all files required for the upgrade. In some cases, the user may be prompted with questions regarding what to install or how to proceed. When using a custom kernel, the above step will produce a warning similar to the following: WARNING: This system is running a "MYKERNEL" kernel, which is not a kernel configuration distributed as part of FreeBSD 9.0-RELEASE. This kernel will not be updated: you MUST update the kernel manually before running "/usr/sbin/freebsd-update install" This warning may be safely ignored at this point. The updated GENERIC kernel will be used as an intermediate step in the upgrade process. Once all the patches have been downloaded to the local system, they will be applied. This process may take a while, depending on the speed and workload of the machine. Configuration files will then be merged. The merging process requires some user intervention as a file may be merged or an editor may appear on screen for a manual merge. The results of every successful merge will be shown to the user as the process continues. A failed or ignored merge will cause the process to abort. Users may wish to make a backup of /etc and manually merge important files, such as master.passwd or group at a later time. The system is not being altered yet as all patching and merging is happening in another directory. Once all patches have been applied successfully, all configuration files have been merged and it seems the process will go smoothly, the changes can be committed to disk by the user using the following command: &prompt.root; freebsd-update install The kernel and kernel modules will be patched first. At this point, the machine must be rebooted. If the system is running with a custom kernel, use &man.nextboot.8; to set the kernel for the next boot to the updated /boot/GENERIC: &prompt.root; nextboot -k GENERIC Before rebooting with the GENERIC kernel, make sure it contains all the drivers required for the system to boot properly and connect to the network, if the machine being updated is accessed remotely. In particular, if the running custom kernel contains built-in functionality usually provided by kernel modules, make sure to temporarily load these modules into the GENERIC kernel using the /boot/loader.conf facility. It is recommended to disable non-essential services as well as any disk and network mounts until the upgrade process is complete. The machine should now be restarted with the updated kernel: &prompt.root; shutdown -r now Once the system has come back online, restart freebsd-update using the following command. The state of the process has been saved and thus, freebsd-update will not start from the beginning, but will remove all old shared libraries and object files. &prompt.root; freebsd-update install Depending upon whether any library version numbers were bumped, there may only be two install phases instead of three. Rebuilding Ports After a Major Version Upgrade After a major version upgrade, all third party software needs to be rebuilt and re-installed. This is required as installed software may depend on libraries which have been removed during the upgrade process. This process can be automated using ports-mgmt/portmaster: &prompt.root; portmaster -f Once this has completed, finish the upgrade process with a final call to freebsd-update in order to tie up all the loose ends in the upgrade process: &prompt.root; freebsd-update install If the GENERIC kernel was temporarily used, this is the time to build and install a new custom kernel in the usual way. Reboot the machine into the new &os; version. The process is complete. System State Comparison freebsd-update can be used to test the state of the installed &os; version against a known good copy. This option evaluates the current version of system utilities, libraries, and configuration files. To begin the comparison, issue the following command: &prompt.root; freebsd-update IDS >> outfile.ids While the command name is IDS it is not a replacement for a real intrusion detection system such as security/snort. As freebsd-update stores data on disk, the possibility of tampering is evident. While this possibility may be reduced using kern.securelevel and by storing the freebsd-update data on a read only file system when not in use, a better solution would be to compare the system against a secure disk, such as a DVD or securely stored external USB disk device. The system will now be inspected, and a lengthy listing of files, along with the &man.sha256.1; hash values for both the known value in the release and the current installation, will be sent to the specified outfile.ids file. The entries in the listing are extremely long, but the output format may be easily parsed. For instance, to obtain a list of all files which differ from those in the release, issue the following command: &prompt.root; cat outfile.ids | awk '{ print $1 }' | more /etc/master.passwd /etc/motd /etc/passwd /etc/pf.conf This sample output has been truncated as many more files exist. Some files have natural modifications. For example, /etc/passwd has been modified because users have been added to the system. Other files, such as kernel modules, may differ as freebsd-update may have updated them. To exclude specific files or directories, add them to the IDSIgnorePaths option in /etc/freebsd-update.conf. This system may be used as part of an elaborate upgrade method, aside from the previously discussed version. Tom Rhodes Written by Colin Percival Based on notes provided by Portsnap: a Ports Collection Update Tool Updating and Upgrading Portsnap Updating and Upgrading The base system of &os; includes &man.portsnap.8; for updating the Ports Collection. This utility connects to a &os; site, verifies the secure key, and downloads a new copy of the Ports Collection. The key is used to verify the integrity of all downloaded files. To download the latest Ports Collection files, issue the following command: &prompt.root; portsnap fetch Looking up portsnap.FreeBSD.org mirrors... 9 mirrors found. Fetching snapshot tag from geodns-1.portsnap.freebsd.org... done. Fetching snapshot metadata... done. Updating from Tue May 22 02:12:15 CEST 2012 to Wed May 23 16:28:31 CEST 2012. Fetching 3 metadata patches.. done. Applying metadata patches... done. Fetching 3 metadata files... done. Fetching 90 patches.....10....20....30....40....50....60....70....80....90. done. Applying patches... done. Fetching 133 new ports or files... done. What this example shows is that &man.portsnap.8; has found and verified several patches to the current ports data. This also indicates that the utility was run previously; if it was a first time run, the collection would have simply been downloaded. When &man.portsnap.8; successfully completes a fetch operation, the Ports Collection and subsequent patches which exist on the local system have passed verification. The first time portsnap is executed, use extract to install the downloaded files: &prompt.root; portsnap extract /usr/ports/.cvsignore /usr/ports/CHANGES /usr/ports/COPYRIGHT /usr/ports/GIDs /usr/ports/KNOBS /usr/ports/LEGAL /usr/ports/MOVED /usr/ports/Makefile /usr/ports/Mk/bsd.apache.mk /usr/ports/Mk/bsd.autotools.mk /usr/ports/Mk/bsd.cmake.mk ... To update an already installed Ports Collection, use portsnap update: &prompt.root; portsnap update The process is now complete, and applications may be installed or upgraded using the updated Ports Collection. When using fetch, the extract or the update operation may be run consecutively: &prompt.root; portsnap fetch update This command downloads the latest version of the Ports Collection and updates the local version under /usr/ports. Updating the Documentation Set Updating and Upgrading Documentation Updating and Upgrading Documentation is an integral part of the &os; operating system. While an up-to-date version of the &os; Documentation Set is always available on the &os; web site, some users might have slow or no permanent network connectivity. There are several ways to update the local copy of documentation with the latest &os; Documentation Set. Using <application>Subversion</application> to Update the Documentation The &os; documentation sources can be obtained with svn. This section describes how to: Install the documentation toolchain, the tools that are required to rebuild the &os; documentation from its source. Download a copy of the documentation source at /usr/doc, using svn. Rebuild the &os; documentation from its source, and install it under /usr/share/doc. Recognize some of the build options that are supported by the build system of the documentation, such as the options that build only some of the different language translations of the documentation or the options that select a specific output format. Installing <application>svn</application> and the Documentation Toolchain Rebuilding the &os; documentation from source requires a collection of tools which are not part of the &os; base system due to the amount of disk space these tools use. They are also not useful to all &os; users, only those users that are actively writing new documentation for &os; or are frequently updating their documentation from source. The required tools, including svn, are available in the textproc/docproj meta-port developed by the &os; Documentation Project. When no &postscript; or PDF documentation required, one might consider installing the textproc/docproj-nojadetex port instead. This version of the documentation toolchain includes everything except the teTeX typesetting engine. teTeX is a very large collection of tools, so it may be quite sensible to omit its installation if PDF output is not really necessary. Updating the Documentation Sources In this example, svn is used to fetch a clean copy of the documentation sources from the western US mirror using the HTTPS protocol: &prompt.root; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc Select the closest mirror from the available Subversion mirror sites. The initial download of the documentation sources may take a while. Let it run until it completes. Future updates of the documentation sources may be fetched by running: &prompt.root; svn update /usr/doc After checking out the sources, an alternative way of updating the documentation is supported by the /usr/doc/Makefile by running the following commands: &prompt.root; cd /usr/doc &prompt.root; make update Tunable Options of the Documentation Sources The updating and build system of the &os; documentation set supports a few options that ease the process of updating only parts of the documentation, or the build of specific translations. These options can be set either as system-wide options in /etc/make.conf, or as command-line options passed to &man.make.1;. The options include: DOC_LANG The list of languages and encodings to build and install, such as en_US.ISO8859-1 for English documentation. FORMATS A single format or a list of output formats to be built. Currently, html, html-split, txt, ps, pdf, and rtf are supported. DOCDIR Where to install the documentation. It defaults to /usr/share/doc. For more make variables supported as system-wide options in &os;, refer to &man.make.conf.5;. For more make variables supported by the build system of the &os; documentation, refer to the &os; Documentation Project Primer for New Contributors. Installing the &os; Documentation from Source Once an up-to-date snapshot of the documentation sources has been fetched to /usr/doc, everything is ready for an update of the installed documentation. A full update of all the languages defined in DOC_LANG may be performed by typing: &prompt.root; cd /usr/doc &prompt.root; make install clean If an update of only a specific language is desired, &man.make.1; can be invoked in a language specific subdirectory of /usr/doc: &prompt.root; cd /usr/doc/en_US.ISO8859-1 &prompt.root; make update install clean The output formats that will be installed may be specified by setting FORMATS: &prompt.root; cd /usr/doc &prompt.root; make FORMATS='html html-split' install clean For information on editing and submitting corrections to the documentation, refer to the &os; Documentation Project Primer for New Contributors. Marc Fonvieille Based on the work of Using Documentation Ports Updating and Upgrading documentation package Updating and Upgrading The previous section presented a method for updating the &os; documentation from sources. Source based updates may not be feasible or practical for all &os; systems as building the documentation sources requires the documentation toolchain, a certain level of familiarity with svn and source checkouts from a repository, and a few manual steps to build the checked out sources. This section describes an alternative method which uses the Ports Collection and makes it possible to: Download and install pre-built snapshots of the documentation, without having to locally build anything or install the documentation toolchain. Download the documentation sources and build them through the ports framework, making the checkout and build steps a bit easier. These two methods of updating the &os; documentation are supported by a set of documentation ports, updated by the &a.doceng; on a monthly basis. These are listed in the &os; Ports Collection, under the docs category. Building and Installing Documentation Ports The documentation ports use the ports building framework to make documentation builds easier. They automate the process of checking out the documentation source, running &man.make.1; with the appropriate environment settings and command-line options, and they make the installation or deinstallation of documentation as easy as the installation of any other &os; port or package. As an extra feature, when the documentation ports are built locally, they record a dependency to the documentation toolchain ports, so that they are also automatically installed. Organization of the documentation ports is as follows: The master port, misc/freebsd-doc-en, which installs all of the English documentation ports. The all in one port, misc/freebsd-doc-all, builds and installs all documentation in all available languages. There is a slave port for each translation, such as misc/freebsd-doc-hu for the Hungarian-language documents. For example, to build and install the English documentation in split HTML format, similar to the format used on , to /usr/local/share/doc/freebsd, install the following port &prompt.root; cd /usr/ports/misc/freebsd-doc-en &prompt.root; make install clean Common Knobs and Options There are many options for modifying the default behavior of the documentation ports, including: WITH_HTML Builds the HTML format with a single HTML file per document. The formatted documentation is saved to a file called article.html, or book.html, as appropriate, plus images. WITH_PDF Builds the &adobe; Portable Document Format (PDF). The formatted documentation is saved to a file called article.pdf or book.pdf, as appropriate. DOCBASE Specifies where to install the documentation. It defaults to /usr/local/share/doc/freebsd. The default target directory differs from the directory used svn. This is because ports are usually installed within /usr/local. This can be overridden by using PREFIX. This example uses variables to install the Hungarian documentation as a PDF: &prompt.root; cd /usr/ports/misc/freebsd-doc-hu &prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean Using Documentation Packages Building the documentation ports from source, as described in the previous section, requires a local installation of the documentation toolchain and a bit of disk space for the build of the ports. When resources are not available to install the documentation toolchain, or because the build from sources would take too much disk space, it is still possible to install pre-built snapshots of the documentation ports. The &a.doceng; prepares monthly snapshots of the &os; documentation packages. These binary packages can be used with any of the bundled package tools, like &man.pkg.add.1;, &man.pkg.delete.1;, and so on. When binary packages are used, the &os; documentation will be installed in all available formats for the given language. For example, the following command will install the latest pre-built package of the Hungarian documentation: &prompt.root; pkg_add -r hu-freebsd-doc Packages use a format that differs from the corresponding port's name: lang-freebsd-doc, where lang is the short format of the language code, such as hu for Hungarian, or zh_cn for Simplified Chinese. Updating Documentation Ports Documentation ports can be updated like any other port. For example, the following command updates the installed Hungarian documentation using ports-mgmt/portmaster by using packages only: &prompt.root; portmaster -PP hu-freebsd-doc Tracking a Development Branch -CURRENT -STABLE There are two development branches to &os;: &os.current; and &os.stable;. This section provides an explanation of each and describes how to keep a system up-to-date with each respective tree. &os.current; will be discussed first, then &os.stable;. Staying Current with &os; &os.current; is the bleeding edge of &os; development. &os.current; users are expected to have a high degree of technical skill and should be capable of solving difficult system problems on their own. If you are new to &os;, track &os.stable; instead. What Is &os.current;? snapshot &os.current; is the very latest source code for &os;. This includes work in progress, experimental changes, and transitional mechanisms that might or might not be present in the next official release of the software. While many &os; developers compile the &os.current; source code daily, there are periods of time when the sources are not buildable. These problems are resolved as quickly as possible, but whether or not &os.current; brings disaster or greatly desired functionality can be a matter of when the source code was synced. Who Needs &os.current;? &os.current; is made available for three primary interest groups: Members of the &os; community who are actively working on some part of the source tree and for whom keeping current is an absolute requirement. Members of the &os; community who are active testers, willing to spend time solving problems in order to ensure that &os.current; remains as sane as possible. These testers wish to make topical suggestions on changes and the general direction of &os;, and submit patches to implement them. Those who merely wish to keep an eye on things, or to use the current sources for reference purposes. These people also make the occasional comment or contribute code. What Is &os.current; <emphasis>Not</emphasis>? A fast-track to getting new features before the next release. Pre-release features are not yet fully tested and most likely contain bugs. A quick way of getting bug fixes. Any given commit is just as likely to introduce new bugs as to fix existing ones. In any way officially supported. Using &os.current; -CURRENT using Join the &a.current.name; and the &a.svn-src-head.name; lists. This is essential in order to see the comments that people are making about the current state of the system and to receive important bulletins which may be critical to the system's continued health. The &a.svn-src-head.name; list records the commit log entry for each change as it is made, along with any pertinent information on possible side-effects. To join these lists, go to &a.mailman.lists.link;, click on the list to subscribe to, and follow the instructions. In order to track changes to the whole source tree, subscribe to the &a.svn-src-all.name; list. Grab the sources from a &os; mirror site using one of the following methods: - - Subversion - - - cron - - - -CURRENT - Syncing with - Subversion - - - - -CURRENT - Syncing with - CTM - - - - Use svn to check out + Use svnSubversion-CURRENTSyncing with Subversion to check out the desired development or release branch. This is the recommended method, providing access to &os; development as it occurs. Checkout the -CURRENT code from the head branch of one of the Subversion mirror sites. Due to the size of the repository, it is recommended that only desired subtrees be checked out. - - -CURRENT - Syncing with CTM - - Use the CTM facility. + linkend="ctm">CTM-CURRENTSyncing with CTM facility. If you have bad connectivity such as high price connections or only email access, CTM is an option, but it is not as reliable as Subversion. For this reason, Subversion is the recommended method for any system with Internet connectivity. If you plan to run, and not just look at the sources, download all of &os.current;, not just selected portions. Various parts of the source depend on updates elsewhere, and trying to compile just a subset is almost guaranteed to cause problems. - - -CURRENT - compiling - - Before compiling &os.current;, read + Before compiling &os.current;-CURRENTcompiling, read /usr/src/Makefile very carefully. Install a new kernel and rebuild the world the first time through as part of the upgrading process. Read the &a.current; and /usr/src/UPDATING to stay up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. Be active! &os.current; users are encouraged to submit their suggestions for enhancements or bug fixes. Suggestions with accompanying code are received most enthusiastically! Staying Stable with &os; What Is &os.stable;? -STABLE &os.stable; is the development branch from which major releases are made. Changes go into this branch at a different pace, and with the general assumption that they have first gone into &os.current; for testing. This is still a development branch, however, and this means that at any given time, the sources for &os.stable; may or may not be suitable for any particular purpose. It is simply another engineering development track, not a resource for end-users. Who Needs &os.stable;? Those interested in tracking or contributing to the FreeBSD development process, especially as it relates to the next point release of FreeBSD, should consider following &os.stable;. While security fixes go into the &os.stable; branch, one does not need to track &os.stable; to receive security fixes. Every security advisory for &os; explains how to fix the problem for the releases it affects which are not yet EOL. For a complete description of the current security policy for old releases of FreeBSD, refer to http://www.FreeBSD.org/security/.. While the &os.stable; branch should compile and run at all times, this cannot be guaranteed. While code is developed in &os.current; before including it in &os.stable;, more people run &os.stable; than &os.current;, so it is inevitable that bugs and corner cases will sometimes be found in &os.stable; that were not apparent in &os.current;. For these reasons, one should not blindly track &os.stable;. It is particularly important not to update any production servers to &os.stable; without first thoroughly testing the code in a development/testing environment. Except for those users who have the resources to perform testing, it is recommended that users instead run the most recent release of FreeBSD, and use the binary update mechanism to move from release to release. Using &os.stable; -STABLE using Join the &a.stable.name; list in order to stay informed of build-dependencies that may appear in &os.stable; or any other issues requiring special attention. Developers will also make announcements in this mailing list when they are contemplating some controversial fix or update, giving the users a chance to respond if they have any issues to raise concerning the proposed change. Join the relevant svn list for the branch being tracked. For example, users tracking the 9-STABLE branch should join the &a.svn-src-stable-9.name; list. This list records the commit log entry for each change as it is made, along with any pertinent information on possible side-effects. To join these lists, go to &a.mailman.lists.link;, click on the list to subscribe to, and follow the instructions. In order to track changes for the whole source tree, subscribe to &a.svn-src-all.name;. To install a new system running monthly snapshots built from &os.stable;, refer to Snapshots for more information. Alternatively, it is possible to install the most recent &os.stable; release from the mirror sites and follow the instructions below to upgrade the system to the most up-to-date &os.stable; source code. Several methods are available to upgrade from a &os; mirror site on a system already running a previous release of &os;: - - Subversion - - - cron - - - -STABLE - syncing with - Subversion - - - Use svn to check out + Use svnSubversion to check out the desired development or release branch. This is the recommended method, providing access to &os; development as it occurs. Branch names include head for the current development head, and branches identified in the release engineering - page, such as stable/9 + page, such as stable/9-STABLEsyncing with Subversion or releng/9.0. URL prefixes for Subversion checkout of the base system are shown in Subversion mirror sites. Because of the size of the repository, it is recommended that only desired subtrees be checked out. - - -STABLE - syncing with CTM - - Consider using CTM if you do + linkend="ctm">CTM-STABLEsyncing with CTM if you do not have a fast connection to the Internet. - - -STABLE - compiling - - - Before compiling &os.stable;, read + Before compiling &os.stable;-STABLEcompiling, read /usr/src/Makefile carefully. Install a new kernel and rebuild the world the first time through as part of the upgrading process. Read &a.stable; and /usr/src/UPDATING to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. Synchronizing Source There are various ways of using an Internet or email connection to stay up-to-date with any given area, or all areas, of the &os; project sources. The primary services are Subversion and CTM. While it is possible to update only parts of the source tree, the only supported update procedure is to update the entire tree and recompile all the programs that run in user space, such as those in /bin and /sbin, and kernel sources. Updating only part of the source tree, only the kernel, or only the userland programs will often result in problems ranging from compile errors to kernel panics or data corruption. Subversion Subversion uses the pull model of updating sources. The user, or a cron script, invokes the svn program, and it brings files up-to-date. Subversion is the preferred means of updating local source trees. The updates are up-to-the-minute and the user controls when they are downloaded. It is easy to restrict updates to specific files or directories and the requested updates are generated on the fly by the server. CTM CTM does not interactively compare the local sources with those on the master archive or otherwise pull them across. Instead, a script which identifies changes in files since its previous run is executed several times a day on the master CTM machine. Any detected changes are compressed, stamped with a sequence-number, and encoded for transmission over email in printable ASCII only. Once received, these CTM deltas can then be handed to the &man.ctm.rmail.1; utility which will automatically decode, verify, and apply the changes to the user's copy of the sources. This process is more efficient than Subversion and places less strain on server resources since it is a push rather than a pull model. There are other trade-offs. If a user inadvertently wipes out portions of the local archive, Subversion will detect and rebuild the damaged portions. CTM will not do this, and if a user deletes some portion of the source tree and does not have a backup, they will have to start from scratch from the most recent CTM base delta and rebuild it all with CTM. Rebuilding <quote>world</quote> Rebuilding world Once the local source tree is synchronized against a particular version of &os; such as &os.stable; or &os.current;, the source tree can be used to rebuild the system. Make a Backup It cannot be stressed enough how important it is to make a backup of the system before rebuilding the system. While rebuilding the world is an easy task, there will inevitably be times when mistakes in the source tree render the system unbootable. Create and verify a backup and have a bootable installation media at hand. You will probably never have to use it, but it is better to be safe than sorry! Subscribe to the Right Mailing List mailing list The &os.stable; and &os.current; branches are, by their nature, in development. People that contribute to &os; are human, and mistakes occasionally happen. Sometimes these mistakes can be quite harmless, just causing the system to print a new diagnostic warning. Or the change may be catastrophic, and render the system unbootable or destroy file systems. When problems occur, a heads up is posted to the appropriate mailing list, explaining the nature of the problem and which systems it affects. An all clear announcement is posted when the problem has been solved. Users who track &os.stable; or &os.current; and do not read &a.stable; or &a.current; respectively, are asking for trouble. Do Not Use <command>make world</command> Some older documentation recommends using make world. However, that command skips some important steps and should only be used by experts. For almost all circumstances make world is the wrong thing to do, and the procedure described here should be used instead. The Canonical Way to Update Your System Before updating the system, read /usr/src/UPDATING for any pre-buildworld steps necessary for that version of the sources. Then, use the procedure outlined here. These upgrade steps assume an upgrade from an older &os; version, consisting of an old compiler, old kernel, old world, and old configuration files. World includes the core system binaries, libraries, and programming files. The compiler is part of world, but has a few special concerns. These steps also assume that the sources to a newer version have already been obtained. If the sources are not up-to-date, refer to for detailed help about synchronizing to a newer version. Updating the system from source is a more subtle process than it might initially seem to be, and the &os; developers have found it necessary over the years to change the recommended approach fairly dramatically as new kinds of unavoidable dependencies come to light. The rest of this section describes the rationale behind the currently recommended upgrade sequence. Any successful update sequence must deal with the following issues: The old compiler might have a bug and not be able to compile the new kernel. So, the new kernel should be built with the new compiler, meaning that the new compiler must be built before the new kernel is built. This does not necessarily mean that the new compiler must be installed before building the new kernel. The new world might rely on new kernel features. So, the new kernel must be installed before the new world is installed. These first two issues are the basis for the core buildworld, buildkernel, installkernel, installworld sequence described in the following paragraphs. Other reasons for using these steps are listed below: The old world might not run correctly on the new kernel, so the new world must be installed immediately upon installing the new kernel. Some configuration changes must be made before the new world is installed, but others might break the old world. Hence, two different configuration upgrade steps are generally needed. For the most part, the update process only replaces or adds files and existing old files are not deleted. In a few cases, this can cause problems. As a result, the update procedure will sometimes specify certain files that should be manually deleted at certain steps. This may or may not be automated in the future. These concerns have led to the following recommended sequence. Note that the detailed sequence for particular updates may require additional steps, but this core process should remain unchanged for some time: make buildworld This first compiles the new compiler and a few related tools, then uses the new compiler to compile the rest of the new world. The result ends up in /usr/obj. make buildkernel This uses the new compiler residing in /usr/obj in order to protect against compiler-kernel mismatches. make installkernel Place the new kernel and kernel modules onto the disk, making it possible to boot with the newly updated kernel. Reboot into single user mode. Single user mode minimizes problems from updating software that is already running. It also minimizes any problems from running the old world on a new kernel. mergemaster This does some initial configuration file updates in preparation for the new world. For instance, it may add new user groups to the system, or new user names to the password database. This is often necessary when new groups or special system-user accounts have been added since the last update, so that the installworld step will be able to use the newly installed system user or system group names without problems. make installworld Copies the world from /usr/obj. The new kernel and new world are now installed on disk. mergemaster Repeated to update the remaining configuration files, now that the new world is on disk. make delete-old This target deletes old (obsolete) files. This is important because sometimes they cause problems if left on the disk, for example the presence of the old utmp.h causes problems in some ports when the new utmpx.h is installed. Reboot. A full machine reboot is needed now to load the new kernel and new world with new configuration files. make delete-old-libs Remove any obsolete libraries to avoid conflicts with newer ones. Make sure that all ports have been rebuilt before old libraries are removed. Upgrades from one release of the same &os; branch to a more recent release of the same branch, such as from 9.0 to 9.1, may not need this procedure since it is less likely to run into serious mismatches between compiler, kernel, userland, and configuration files. The approach of make world followed by building and installing a new kernel might work well enough for minor updates. When upgrading across major releases, people who do not follow this procedure should expect some problems. It is also worth noting that many upgrades may require specific additional steps such as renaming or deleting specific files prior to installworld. Read /usr/src/UPDATING carefully, especially at the end, where the currently recommended upgrade sequence is explicitly spelled out. This procedure has evolved over time as the developers have found it impossible to completely prevent certain kinds of mismatch problems. Hopefully, the current procedure will remain stable for a long time. To summarize, the currently recommended way of upgrading &os; from sources is: &prompt.root; cd /usr/src &prompt.root; make buildworld &prompt.root; make buildkernel &prompt.root; make installkernel &prompt.root; shutdown -r now There are a few rare cases when an extra run of mergemaster -p is needed before the buildworld step. These are described in UPDATING. In general, though, this step can safely be omitted when not updating across one or more major &os; versions. After installkernel finishes successfully, boot into single user mode using boot -s from the loader prompt. Then run: &prompt.root; mount -u / &prompt.root; mount -a -t ufs &prompt.root; adjkerntz -i &prompt.root; mergemaster -p &prompt.root; cd /usr/src &prompt.root; make installworld &prompt.root; mergemaster &prompt.root; make delete-old &prompt.root; reboot &prompt.root; make delete-old-libs Read Further Explanations The following sections clearly describe each step, especially when using a custom kernel configuration. Read <filename>/usr/src/UPDATING</filename> Before updating, read /usr/src/UPDATING. This file contains important information about potential problems and may specify the order to run certain commands. If UPDATING contradicts the procedure in this section, UPDATING takes precedence. Reading UPDATING is not an acceptable substitute for subscribing to the correct mailing list. The two requirements are complementary, not exclusive. Check <filename>/etc/make.conf</filename> make.conf Available &man.make.1; options are shown in &man.make.conf.5; and /usr/share/examples/etc/make.conf. These settings can be added to /etc/make.conf to control the way &man.make.1; runs and how it builds programs. Changes to some settings can have far-reaching and potentially surprising effects. Read the comments in both locations and keep in mind that the defaults have been chosen for a combination of performance and safety. Options set in /etc/make.conf take effect every time &man.make.1; is used, including compiling applications from the Ports Collection or user-written C programs, or building the &os; operating system. Check <filename>/etc/src.conf</filename> src.conf /etc/src.conf controls the building of the operating system from source code. Unlike /etc/make.conf, the contents of /etc/src.conf only take effect when the &os; operating system itself is being built. Descriptions of the many options available for this file are shown in &man.src.conf.5;. Be cautious about disabling seemingly unneeded kernel modules and build options. Sometimes there are unexpected or subtle interactions. Update the Files in <filename>/etc</filename> /etc contains a large part of the system's configuration information, as well as scripts that are run at system startup. Some of these scripts change between &os; versions. Some of the configuration files are used in the day to day running of the system, such as /etc/group. There have been occasions when the installation part of make installworld expected certain usernames or groups to exist. When performing an upgrade, it is likely that these users or groups do not yet exist. In some cases make buildworld will check to see if these users or groups exist. The solution is to run &man.mergemaster.8; in pre-buildworld mode with . This compares only those files that are essential for the success of buildworld or installworld. To check which files are owned by the group being renamed or deleted: &prompt.root; find / -group GID -print This command will show all files owned by group GID, which can be either a group name or a numeric group ID. Drop to Single User Mode single-user mode Consider compiling the system in single user mode. Reinstalling the system touches a lot of important system files, all the standard system binaries, libraries, and include files. Changing these on a running system, particularly one with active users, is asking for trouble. multi-user mode Another method is to compile the system in multi-user mode, and then drop into single user mode for the installation. With this method, hold off on the following steps until the build has completed. Drop to single user mode in order to run installkernel or installworld. To enter single user mode from a running system: &prompt.root; shutdown now Alternatively, reboot the system, and at the boot prompt, select the single user option. Once at the single user mode shell prompt, run: &prompt.root; fsck -p &prompt.root; mount -u / &prompt.root; mount -a -t ufs &prompt.root; swapon -a This checks the file systems, remounts / read/write, mounts all the other UFS file systems referenced in /etc/fstab, and turns swapping on. If the CMOS clock is set to local time and not to GMT (this is true if the output of &man.date.1; does not show the correct time and zone), run the following command: &prompt.root; adjkerntz -i This ensures that the local time-zone settings get set up correctly. Remove <filename>/usr/obj</filename> As parts of the system are rebuilt, they are, by default, placed in subdirectories of /usr/obj. The directories shadow those under /usr/src. To speed up the make buildworld process, and possibly save some dependency headaches, remove this directory if it already exists. Some files below /usr/obj may have the immutable flag set which must be removed first using &man.chflags.1;. &prompt.root; cd /usr/obj &prompt.root; chflags -R noschg * &prompt.root; rm -rf * Recompile the Base System Saving the Output It is a good idea to save the output from running &man.make.1; to a file. If something goes wrong, a copy of the error message can be posted to one of the &os; mailing lists. The easiest way to do this is to use &man.script.1; with a parameter that specifies the name of the file to save all output to. Run this command immediately before rebuilding the world, and then type exit when the process has finished: &prompt.root; script /var/tmp/mw.out Script started, output file is /var/tmp/mw.out &prompt.root; make TARGET … compile, compile, compile … &prompt.root; exit Script done, … Do not save the output in /tmp as this directory may be cleared at next reboot. A better place to save the file is /var/tmp or in root's home directory. Compile the Base System While in /usr/src type: &prompt.root; cd /usr/src make To rebuild the world, use &man.make.1;. This command reads instructions from the Makefile, which describes how the programs that comprise &os; should be built and the order in which they should be built. The general format of the command is as follows: &prompt.root; make -x -DVARIABLE target In this example, is an option passed to &man.make.1;. Refer to &man.make.1; for an examples of available options. passes a variable to the Makefile. The behavior of the Makefile is controlled by these variables. These are the same variables as are set in /etc/make.conf, and this provides another way of setting them. For example: &prompt.root; make -DNO_PROFILE target is another way of specifying that profiled libraries should not be built, and corresponds with the NO_PROFILE= true # Avoid compiling profiled libraries line in /etc/make.conf. target tells &man.make.1; what to do. Each Makefile defines a number of different targets, and the choice of target determines what happens. Some targets listed in the Makefile are used by the build process to break out the steps necessary to rebuild the system into a number of sub-steps. Most of the time, no parameters need to be passed to &man.make.1; and the command looks like this: &prompt.root; make target Where target is one of many build options. The first target should always be buildworld. As the names imply, buildworld builds a complete new tree under /usr/obj and installworld installs this tree on the current machine. Having separate options is useful for two reasons. First, it allows for a self hosted build that does not affect any components of a running system. Because of this, buildworld can be run on a machine running in multi-user mode with no fear of ill-effects. It is still recommended that installworld be run in part in single user mode, though. Secondly, it allows NFS mounts to be used to upgrade multiple machines on a network. If order to upgrade three machines, A, B and C, run make buildworld and make installworld on A. B and C should then NFS mount /usr/src and /usr/obj from A, and run make installworld to install the results of the build on B and C. Although the world target still exists, users are strongly encouraged not to use it. Instead, run: &prompt.root; make buildworld It is possible to specify which will cause make to spawn several simultaneous processes. This is most useful on multi-CPU machines. However, since much of the compiling process is I/O bound rather than CPU bound, it is also useful on single CPU machines. On a typical single-CPU machine, run: &prompt.root; make -j4 buildworld &man.make.1; will then have up to 4 processes running at any one time. Empirical evidence posted to the mailing lists shows this generally gives the best performance benefit. On a multi-CPU machine using an SMP configured kernel, try values between 6 and 10 and see how they speed things up. Timings rebuilding world timings Many factors influence the build time, but fairly recent machines may only take a one or two hours to build the &os.stable; tree, with no tricks or shortcuts used during the process. A &os.current; tree will take somewhat longer. Compile and Install a New Kernel kernel compiling To take full advantage of the new system, recompile the kernel. This is practically a necessity, as certain memory structures may have changed, and programs like &man.ps.1; and &man.top.1; will fail to work until the kernel and source code versions are the same. The simplest, safest way to do this is to build and install a kernel based on GENERIC. While GENERIC may not have all the necessary devices for the system, it should contain everything necessary to boot the system back to single user mode. This is a good test that the new system works properly. After booting from GENERIC and verifying that the system works, a new kernel can be built based on a custom kernel configuration file. On &os; it is important to build world before building a new kernel. To build a custom kernel with an existing customized configuration file, use KERNCONF=MYKERNEL: &prompt.root; cd /usr/src &prompt.root; make buildkernel KERNCONF=MYKERNEL &prompt.root; make installkernel KERNCONF=MYKERNEL If kern.securelevel has been raised above 1 and noschg or similar flags have been set on the kernel binary, drop into single user mode to use installkernel. Otherwise, both these commands can be run from multi user mode without problems. See &man.init.8; for details about kern.securelevel and &man.chflags.1; for details about the various file flags. Reboot into Single User Mode single-user mode Reboot into single user mode to test that the new kernel works using the instructions in . Install the New System Binaries Next, use installworld to install the new system binaries: &prompt.root; cd /usr/src &prompt.root; make installworld If variables were specified to make buildworld, specify the same variables to make installworld. However, must never be used with installworld. For example, if you ran: &prompt.root; make -DNO_PROFILE buildworld install the results with: &prompt.root; make -DNO_PROFILE installworld otherwise, the command will try to install profiled libraries that were not built during the make buildworld phase. Update Files Not Updated by <command>make installworld</command> Remaking the world will not update certain directories, such as /etc, /var and /usr, with new or changed configuration files. The simplest way to update the files in these directories is to use &man.mergemaster.8;. Be sure to first make a backup of /etc in case anything goes wrong. Tom Rhodes Contributed by <command>mergemaster</command> mergemaster &man.mergemaster.8; is a Bourne script to aid in determining the differences between the configuration files in /etc, and the configuration files in the source tree /usr/src/etc. This is the recommended solution for keeping the system configuration files up to date with those located in the source tree. To begin, type mergemaster and it will build a temporary root environment, from / down, and populate it with various system configuration files. Those files are then compared to the ones currently installed in the system. Files that differ will be shown in &man.diff.1; format, with the sign representing added or modified lines, and representing lines that will be either removed completely, or replaced with a new file. Refer to &man.diff.1; for more information about the &man.diff.1; syntax and how file differences are shown. &man.mergemaster.8; will then display each file that differs, and present the options of either deleting the new file, referred to as the temporary file, installing the temporary file in its unmodified state, merging the temporary file with the currently installed file, or viewing the &man.diff.1; results again. Choosing to delete the temporary file will tell &man.mergemaster.8; to keep the current file unchanged and to delete the new version. This option is not recommended, unless there is no reason to change the current file. To get help at any time, type ? at the &man.mergemaster.8; prompt. If the user chooses to skip a file, it will be presented again after all other files have been dealt with. Choosing to install the unmodified temporary file will replace the current file with the new one. For most unmodified files, this is the best option. Choosing to merge the file will present a text editor, and the contents of both files. The files can be merged by reviewing both files side by side on the screen, and choosing parts from both to create a finished product. When the files are compared side by side, l selects the left contents and r selects contents from the right. The final output will be a file consisting of both parts, which can then be installed. This option is customarily used for files where settings have been modified by the user. Choosing to view the &man.diff.1; results again will display the file differences just like &man.mergemaster.8; did before prompting an option. After &man.mergemaster.8; is done with the system files, it will prompt for other options. &man.mergemaster.8; may prompt to rebuild the password file and will finish up with an option to remove left-over temporary files. Manual Update To perform the update manually instead, do not just copy over the files from /usr/src/etc to /etc and expect it to work. Some files must be installed first as /usr/src/etc is not a copy of what /etc should look like. In addition, some files that should be in /etc are not in /usr/src/etc. If you are using &man.mergemaster.8; (as recommended), you can skip forward to the next section. The simplest way to merge files by hand is to install the files into a new directory, and then work through them looking for differences. Backup Your Existing <filename>/etc</filename> It is recommended to first copy the existing /etc somewhere safe, like so: &prompt.root; cp -Rp /etc /etc.old where does a recursive copy and preserves times and the ownerships on files. Build a temporary set of directories into which the new /etc and other files can be installed: &prompt.root; mkdir /var/tmp/root &prompt.root; cd /usr/src/etc &prompt.root; make DESTDIR=/var/tmp/root distrib-dirs distribution This will build the necessary directory structure and install the files. A lot of the subdirectories that have been created under /var/tmp/root are empty and should be deleted. The simplest way to do this is to: &prompt.root; cd /var/tmp/root &prompt.root; find -d . -type d | xargs rmdir 2>/dev/null This will remove all empty directories while redirecting standard error to /dev/null to prevent the warnings about the directories that are not empty. /var/tmp/root now contains all the files that should be placed in appropriate locations below /. Go through each of these files, determining how they differ from the system's existing files. Some of the files installed into /var/tmp/root have a leading .. Make sure to use ls -a in order to catch them. The simplest way to compare files is to use &man.diff.1;: &prompt.root; diff /etc/shells /var/tmp/root/etc/shells This command will show the differences between the existing /etc/shells and the new /var/tmp/root/etc/shells. Review the differences to decide whether to merge in custom changes or to replace the existing file with the new one. Name the New Root Directory (<filename class="directory">/var/tmp/root</filename>) with a Time Stamp, so You Can Easily Compare Differences Between Versions Frequently rebuilding world entails frequently updating /etc as well, which can be a bit of a chore. To speed up this process, use the following procedure to keep a copy of the last set of changed files that were merged into /etc. Make the world as normal. When updating /etc and the other directories, give the target directory a name based on the current date: &prompt.root; mkdir /var/tmp/root-20130214 &prompt.root; cd /usr/src/etc &prompt.root; make DESTDIR=/var/tmp/root-20130214 \ distrib-dirs distribution Merge in the changes from this directory as outlined above. Do not remove the /var/tmp/root-20130214 directory when you have finished. After downloading the latest version of the source and remaking it, follow step 1. Create a new directory, which reflects the new date. This example uses /var/tmp/root-20130221. Use &man.diff.1; to see the differences that have been made in the intervening week by creating a recursive diff between the two directories: &prompt.root; cd /var/tmp &prompt.root; diff -r root-20130214 root-20130221 Typically, this will be a much smaller set of differences than those between /var/tmp/root-20130221/etc and /etc. Because the set of differences is smaller, it is easier to migrate those changes across into /etc. When finished, remove the older of the two /var/tmp/root-* directories: &prompt.root; rm -rf /var/tmp/root-20130214 Repeat this process whenever merging in changes to /etc. Use &man.date.1; to automate the generation of the directory names: &prompt.root; mkdir /var/tmp/root-`date "+%Y%m%d"` Anton Shterenlikht Based on notes provided by Deleting Obsolete Files and Directories Deleting obsolete files and directories As a part of the &os; development lifecycle, files and their contents occasionally become obsolete. This may be because functionality is implemented elsewhere, the version number of the library has changed, or it was removed from the system entirely. This includes old files, libraries, and directories, which should be removed when updating the system. The benefit is that the system is not cluttered with old files which take up unnecessary space on the storage and backup media. Additionally, if the old library has a security or stability issue, the system should be updated to the newer library to keep it safe and to prevent crashes caused by the old library. Files, directories, and libraries which are considered obsolete are listed in /usr/src/ObsoleteFiles.inc. The following instructions should be used to remove obsolete files during the system upgrade process. After the make installworld and the subsequent mergemaster have finished successfully, check for obsolete files and libraries as follows: &prompt.root; cd /usr/src &prompt.root; make check-old If any obsolete files are found, they can be deleted using the following command: &prompt.root; make delete-old Refer to /usr/src/Makefile for more targets of interest. A prompt is displayed before deleting each obsolete file. To skip the prompt and let the system remove these files automatically, use BATCH_DELETE_OLD_FILES: &prompt.root; make -DBATCH_DELETE_OLD_FILES delete-old The same goal can be achieved by piping these commands through yes: &prompt.root; yes|make delete-old Rebooting Verify that everything appears to be in the right place, then reboot the system using &man.shutdown.8;: &prompt.root; shutdown -r now Deleting obsolete libraries Warning Deleting obsolete files will break applications that still depend on those obsolete files. This is especially true for old libraries. In most cases, the programs, ports, or libraries that used the old library need to be recompiled before make delete-old-libs is executed. Utilities for checking shared library dependencies are available from the Ports Collection in sysutils/libchk or sysutils/bsdadminscripts. Obsolete shared libraries can conflict with newer libraries, causing messages like these: /usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5 /usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5 To solve these problems, determine which port installed the library: &prompt.root; pkg_info -W /usr/local/lib/libtiff.so /usr/local/lib/libtiff.so was installed by package tiff-3.9.4 &prompt.root; pkg_info -W /usr/local/lib/libXext.so /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1 Then deinstall, rebuild and reinstall the port. ports-mgmt/portmaster can be used to automate this process. After all ports are rebuilt and no longer use the old libraries, delete the old libraries using the following command: &prompt.root; make delete-old-libs You should now have successfully upgraded the &os; system. Congratulations. If things went slightly wrong, it is easy to rebuild a particular piece of the system. For example, if /etc/magic was accidentally deleted as part of the upgrade or merge of /etc, &man.file.1; will stop working. To fix this, run: &prompt.root; cd /usr/src/usr.bin/file &prompt.root; make all install Questions Do I need to re-make the world for every change? There is no easy answer, as it depends on the nature of the change. For example, if running svn only shows the following files as being updated: src/games/cribbage/instr.c src/games/sail/pl_main.c src/release/sysinstall/config.c src/release/sysinstall/media.c src/share/mk/bsd.port.mk it probably is not worth rebuilding the entire world. Instead, go into the appropriate sub-directories and run make all install. But if something major changed, such as src/lib/libc/stdlib, either re-make world, or at least those parts of it that are statically linked. At the end of the day, it is your call. Some users re-make the world every fortnight and let changes accumulate over that fortnight. Others only re-make those things that have changed and are careful to spot all the dependencies. It all depends on how often a user wants to upgrade and whether they are tracking &os.stable; or &os.current;. My compile failed with lots of signal 11signal 11 (or other signal number) errors. What happened? This normally indicates hardware problems. (Re)making world is an effective way to stress test hardware, and will frequently throw up memory problems which normally manifest themselves as the compiler mysteriously aborts. A sure indicator of this occurs when make is restarted and it dies at a different point in the process. To resolve this error, start swapping around the components in the machine to determine which one is failing. Can /usr/obj be removed when finished? The short answer is yes. /usr/obj contains all the object files that were produced during the compilation phase. Normally, one of the first steps in the make buildworld process is to remove this directory and start afresh. Keeping /usr/obj around when finished makes little sense, and its removal frees up a approximately 2 GB of disk space. Advances users can instruct make buildworld to skip this step. This speeds up subsequent builds, since most of the sources will not need to be recompiled. The flip side is that subtle dependency problems can creep in, causing the build to fail in odd ways. This frequently generates noise on the &os; mailing lists, when one person complains that their build has failed, not realizing that it is because they have tried to cut corners. Can interrupted builds be resumed? This depends on how far into the process the problem occurs. In general, make buildworld builds new copies of essential tools, such as &man.gcc.1; and &man.make.1;, and the system libraries. These tools and libraries are then installed, used to rebuild themselves, and are installed again. The entire system, including regular user programs such as &man.ls.1; or &man.grep.1;, is then rebuilt with the new system files. During the last stage, it is fairly safe to: … fix the problem … &prompt.root; cd /usr/src &prompt.root; make -DNO_CLEAN all This will not undo the work of the previous make buildworld. If you see the message: -------------------------------------------------------------- Building everything.. -------------------------------------------------------------- in the make buildworld output, it is probably fairly safe to do so. If that message is not displayed, or you are not sure, it is always better to be safe than sorry, and restart the build from scratch. How can I speed up making the world? Run it in single user mode. Put /usr/src and /usr/obj on separate file systems held on separate disks. If possible, put these disks on separate disk controllers. Alternately, put these file systems across multiple disks using &man.ccd.4;. Turn off profiling by setting NO_PROFILE=true in /etc/make.conf. Pass to &man.make.1; to run multiple processes in parallel. This usually helps on both single and multi processor machines. The file system holding /usr/src can be mounted or remounted with . This prevents the file system from recording the file access time which is probably not needed. &prompt.root; mount -u -o noatime /usr/src This example assumes /usr/src is on its own file system. If it is part of /usr, then use that file system mount point instead. The file system holding /usr/obj can be mounted or remounted with so that disk writes happen asynchronously. The write completes immediately, and the data is written to the disk a few seconds later. This allows writes to be clustered together, and can provide a dramatic performance boost. Keep in mind that this option makes the file system more fragile. With this option, there is an increased chance that, should power fail, the file system will be in an unrecoverable state when the machine restarts. If /usr/obj is the only directory on this file system, this is not a problem. If you have other, valuable data on the same file system, ensure that there are verified backups before enabling this option. &prompt.root; mount -u -o async /usr/obj If /usr/obj is not on its own file system, replace it in the example with the name of the appropriate mount point. What do I do if something goes wrong? Make absolutely sure that the environment has no extraneous cruft from earlier builds: &prompt.root; chflags -R noschg /usr/obj/usr &prompt.root; rm -rf /usr/obj/usr &prompt.root; cd /usr/src &prompt.root; make cleandir &prompt.root; make cleandir Yes, make cleandir really should be run twice. Then, restart the whole process, starting with make buildworld. If problems persist, send the error and the output of uname -a to &a.questions;. Be prepared to answer other questions about the setup! Mike Meyer Contributed by Tracking for Multiple Machines NFS installing multiple machines When multiple machines need to track the same source tree, it is a waste of disk space, network bandwidth, and CPU cycles to have each system download the sources and rebuild everything. The solution is to have one machine do most of the work, while the rest of the machines mount that work via NFS. This section outlines a method of doing so. Preliminaries First, identify a set of machines which will run the same set of binaries, known as a build set. Each machine can have a custom kernel, but will run the same userland binaries. From that set, choose a machine to be the build machine that the world and kernel are built on. Ideally, this is a fast machine that has sufficient spare CPU to run make buildworld and make buildkernel. Select a machine to be the test machine, which will test software updates before they are put into production. This must be a machine that can afford to be down for an extended period of time. It can be the build machine, but need not be. All the machines in this build set need to mount /usr/obj and /usr/src from the same machine, and at the same point. Ideally, those directories are on two different drives on the build machine, but they can be NFS mounted on that machine as well. For multiple build sets, /usr/src should be on one build machine, and NFS mounted on the rest. Finally, ensure that /etc/make.conf and /etc/src.conf on all the machines in the build set agree with the build machine. That means that the build machine must build all the parts of the base system that any machine in the build set is going to install. Also, each build machine should have its kernel name set with KERNCONF in /etc/make.conf, and the build machine should list them all in KERNCONF, listing its own kernel first. The build machine must have the kernel configuration files for each machine in /usr/src/sys/arch/conf if it is going to build their kernels. The Base System On the build machine, build the kernel and world as described in , but do not install anything. After the build has finished, go to the test machine, and install the built kernel. If this machine mounts /usr/src and /usr/obj via NFS, enable the network and mount these directories after rebooting to single user mode. The easiest way to do this is to boot to multi-user, then run shutdown now to go to single user mode. Once there, install the new kernel and world and run mergemaster as usual. When done, reboot to return to normal multi-user operations for this machine. After verifying that everything on the test machine is working properly, use the same procedure to install the new software on each of the other machines in the build set. Ports The same ideas can be used for the ports tree. The first critical step is to mount /usr/ports from the same machine to all the machines in the build set. Then, configure /etc/make.conf properly to share distfiles. Set DISTDIR to a common shared directory that is writable by whichever user root is mapped to by the NFS mounts. Each machine should set WRKDIRPREFIX to a local build directory. Finally, if the system is to build and distribute packages, set PACKAGES to a directory similar to DISTDIR. diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.xml b/en_US.ISO8859-1/books/handbook/install/chapter.xml index 333118b3a0..60a7ac871f 100644 --- a/en_US.ISO8859-1/books/handbook/install/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/install/chapter.xml @@ -1,4889 +1,4879 @@ Jim Mock Restructured, reorganized, and parts rewritten by Randy Pratt The sysinstall walkthrough, screenshots, and general copy by Installing &os; 8.<replaceable>X</replaceable> Synopsis installation &os; provides a text-based, easy to use installation program. &os; 9.0-RELEASE and later use the installation program known as &man.bsdinstall.8; while &os; 8.X uses &man.sysinstall.8;. This chapter describes how to use &man.sysinstall.8;. The use of &man.bsdinstall.8; is covered in . After reading this chapter, you will know: How to create the &os; installation media. How &os; refers to and subdivides hard disks. How to start &man.sysinstall.8;. The questions &man.sysinstall.8; asks, what they mean, and how to answer them. Before reading this chapter, you should: Read the supported hardware list that shipped with the version of &os; to install, and verify that the system's hardware is supported. In general, these installation instructions are written for the &i386; and &os;/&arch.amd64; architectures. Where applicable, instructions specific to other platforms will be listed. There may be minor differences between the installer and what is shown here. This chapter should be used as a general guide rather than a literal installation manual. Hardware Requirements Minimal Configuration The minimal configuration to install &os; varies with the &os; version and the hardware architecture. A summary of this information is given in the following sections. Depending on the method chosen to install &os;, a floppy drive, CDROM drive, or network adapter may be needed. Instructions on how to prepare the installation media can be found in . &os;/&arch.i386; and &os;/&arch.pc98; Both &os;/&arch.i386; and &os;/&arch.pc98; require a 486 or better processor, at least 24 MB of RAM, and at least 150 MB of free hard drive space for the most minimal installation. In the case of older hardware, installing more RAM and more hard drive space is often more important than a faster processor. &os;/&arch.amd64; There are two classes of processors capable of running &os;/&arch.amd64;. The first are AMD64 processors, including the &amd.athlon;64, &amd.athlon;64-FX, and &amd.opteron; or better processors. The second class of processors includes those using the &intel; EM64T architecture. Examples of these processors include the &intel; &core; 2 Duo, Quad, Extreme processor families, and the &intel; &xeon; 3000, 5000, and 7000 sequences of processors. If the machine is based on an nVidia nForce3 Pro-150, the BIOS setup must be used to disable the IO APIC. If this option does not exist, disable ACPI instead as there are bugs in the Pro-150 chipset. &os;/&arch.sparc64; To install &os;/&arch.sparc64;, use a supported platform (see ). A dedicated disk is needed for &os;/&arch.sparc64; as it is not possible to share a disk with another operating system at this time. Supported Hardware A list of supported hardware is provided with each &os; release in the &os; Hardware Notes. This document can usually be found in a file named HARDWARE.TXT, in the top-level directory of a CDROM or FTP distribution, or in &man.sysinstall.8;'s documentation menu. It lists, for a given architecture, which hardware devices are known to be supported by each release of &os;. Copies of the supported hardware list for various releases and architectures can also be found on the Release Information page of the &os; website. Pre-installation Tasks Inventory the Computer Before installing &os; it is recommended to inventory the components in the computer. The &os; installation routines will show components such as hard disks, network cards, and CDROM drives with their model number and manufacturer. &os; will also attempt to determine the correct configuration for these devices, including information about IRQ and I/O port usage. Due to the vagaries of computer hardware, this process is not always completely successful, and &os; may need some manual configuration. If another operating system is already installed, use the facilities provided by that operating systems to view the hardware configuration. If the settings of an expansion card are not obvious, check if they are printed on the card itself. Popular IRQ numbers are 3, 5, and 7, and I/O port addresses are normally written as hexadecimal numbers, such as 0x330. It is recommended to print or write down this information before installing &os;. It may help to use a table, as seen in this example: Sample Device Inventory Device Name IRQ I/O port(s) Notes First hard disk N/A N/A 40 GB, made by Seagate, first IDE master CDROM N/A N/A First IDE slave Second hard disk N/A N/A 20 GB, made by IBM, second IDE master First IDE controller 14 0x1f0 Network card N/A N/A &intel; 10/100 Modem N/A N/A &tm.3com; 56K faxmodem, on COM1 …
Once the inventory of the components in the computer is complete, check if it matches the hardware requirements of the &os; release to install. Make a Backup If the computer contains valuable data, ensure it is backed up, and that the backup has been tested before installing &os;. The &os; installer will prompt before writing any data to disk, but once that process has started, it cannot be undone. Decide Where to Install &os; If &os; is to be installed on the entire hard disk, skip this section. However, if &os; will co-exist with other operating systems, a rough understanding of how data is laid out on the disk is useful. Disk Layouts for &os;/&arch.i386; A PC disk can be divided into discrete chunks known as partitions. Since &os; also has partitions, naming can quickly become confusing. Therefore, these disk chunks are referred to as slices in &os;. For example, the &os; version of &man.fdisk.8; refers to slices instead of partitions. By design, the PC only supports four partitions per disk. These partitions are called primary partitions. To work around this limitation and allow more than four partitions, a new partition type was created, the extended partition. A disk may contain only one extended partition. Special partitions, called logical partitions, can be created inside this extended partition. Each partition has a partition ID, which is a number used to identify the type of data on the partition. &os; partitions have the partition ID of 165. In general, each operating system will identify partitions in a particular way. For example, &windows;, assigns each primary and logical partition a drive letter, starting with C:. &os; must be installed into a primary partition. If there are multiple disks, a &os; partition can be created on all, or some, of them. When &os; is installed, at least one partition must be available. This might be a blank partition or it might be an existing partition whose data can be overwritten. If all the partitions on all the disks are in use, free one of them for &os; using the tools provided by an existing operating system, such as &windows; fdisk. If there is a spare partition, use that. If it is too small, shrink one or more existing partitions to create more available space. A minimal installation of &os; takes as little as 100 MB of disk space. However, that is a very minimal install, leaving almost no space for files. A more realistic minimum is 250 MB without a graphical environment, and 350 MB or more for a graphical user interface. If other third-party software will be installed, even more space is needed. You can use a tool such as GParted to resize your partitions and make space for &os;. GParted is known to work on NTFS and is available on a number of Live CD Linux distributions, such as SystemRescueCD. Incorrect use of a shrinking tool can delete the data on the disk. Always have a recent, working backup before using this type of tool. Using an Existing Partition Unchanged Consider a computer with a single 4 GB disk that already has a version of &windows; installed, where the disk has been split into two drive letters, C: and D:, each of which is 2 GB in size. There is 1 GB of data on C:, and 0.5 GB of data on D:. This disk has two partitions, one per drive letter. Copy all existing data from D: to C:, which will free up the second partition, ready for &os;. Shrinking an Existing Partition Consider a computer with a single 4 GB disk that already has a version of &windows; installed. When &windows; was installed, it created one large partition, a C: drive that is 4 GB in size. Currently, 1.5 GB of space is used, and &os; should have 2 GB of space. In order to install &os;, either: Backup the &windows; data and then reinstall &windows;, asking for a 2 GB partition at install time. Use one of the tools described above to shrink your &windows; partition. Collect the Network Configuration Details Before installing from an FTP site or an NFS server, make note of the network configuration. The installer will prompt for this information so that it can connect to the network to complete the installation. Connecting to an Ethernet Network or Cable/DSL Modem If using an Ethernet network or an Internet connection using an Ethernet adapter via cable or DSL, the following information is needed: IP address IP address of the default gateway Hostname DNS server IP addresses Subnet Mask If this information is unknown, ask the system administrator or service provider. Make note if this information is assigned automatically using DHCP. Connecting Using a Modem If using a dialup modem, &os; can still be installed over the Internet, it will just take a very long time. You will need to know: The phone number to dial the Internet Service Provider (ISP) The COM: port the modem is connected to The username and password for the ISP account Check for &os; Errata Although the &os; Project strives to ensure that each release of &os; is as stable as possible, bugs do occasionally creep into the process. On rare occasions those bugs affect the installation process. As these problems are discovered and fixed, they are noted in the &os; Errata, which is found on the &os; website. Check the errata before installing to make sure that there are no late-breaking problems to be aware of. Information about all releases, including the errata for each release, can be found on the release information section of the &os; website. Obtain the &os; Installation Files The &os; installer can install &os; from files located in any of the following places: Local Media A CDROM or DVD A USB Memory Stick A &ms-dos; partition on the same computer Floppy disks (&os;/&arch.pc98; only) Network An FTP site through a firewall or using an HTTP proxy An NFS server A dedicated parallel or serial connection If installing from a purchased &os; CD/DVD, skip ahead to . To obtain the &os; installation files, skip ahead to which explains how to prepare the installation media. After reading that section, come back here and read on to . Prepare the Boot Media The &os; installation process is started by booting the computer into the &os; installer. It is not a program that can be run within another operating system. The computer normally boots using the operating system installed on the hard disk, but it can also be configured to boot from a CDROM or from a USB disk. If installing from a CD/DVD to a computer whose BIOS supports booting from the CD/DVD, skip this section. The &os; CD/DVD images are bootable and can be used to install &os; without any other special preparation. To create a bootable memory stick, follow these steps: Acquire the Memory Stick Image Memory stick images for &os; 8.X can be downloaded from the ISO-IMAGES/ directory at ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/arch/ISO-IMAGES/version/&os;-version-RELEASE-arch-memstick.img. Replace arch and version with the architecture and the version number to install. For example, the memory stick images for &os;/&arch.i386; &rel2.current;-RELEASE are available from . A different directory path is used for &os; 9.0-RELEASE and later versions. How to download and install &os; 9.X is covered in . The memory stick image has a .img extension. The ISO-IMAGES/ directory contains a number of different images and the one to use depends on the version of &os; and the type of media supported by the hardware being installed to. Before proceeding, back up the data on the USB stick, as this procedure will erase it. Write the Image File to the Memory Stick Using &os; to Write the Image The example below lists /dev/da0 as the target device where the image will be written. Be very careful that you have the correct device as the output target, or you may destroy your existing data. Writing the Image with &man.dd.1; The .img file is not a regular file that can just be copied to the memory stick. It is an image of the complete contents of the disk. This means that &man.dd.1; must be used to write the image directly to the disk: &prompt.root; dd if=&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img of=/dev/da0 bs=64k If an Operation not permitted error is displayed, make certain that the target device is not in use, mounted, or being automounted by another program. Then try again. Using &windows; to Write the Image Make sure to use the correct drive letter as the output target, as this command will overwrite and destroy any existing data on the specified device. Obtaining <application>Image Writer for Windows</application> Image Writer for Windows is a free application that can correctly write an image file to a memory stick. Download it from and extract it into a folder. Writing the Image with Image Writer Double-click the Win32DiskImager icon to start the program. Verify that the drive letter shown under Device is the drive with the memory stick. Click the folder icon and select the image to be written to the memory stick. Click Save to accept the image file name. Verify that everything is correct, and that no folders on the memory stick are open in other windows. Finally, click Write to write the image file to the drive. To create the boot floppy images for a &os;/&arch.pc98; installation, follow these steps: Acquire the Boot Floppy Images The &os;/&arch.pc98; boot disks can be downloaded from the floppies directory, ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/pc98/version-RELEASE/floppies/. Replace version with the version number to install. The floppy images have a .flp extension. floppies/ contains a number of different images. Download boot.flp as well as the number of files associated with the type of installation, such as kern.small* or kern*. The FTP program must use binary mode to download these disk images. Some web browsers use text or ASCII mode, which will be apparent if the disks are not bootable. Prepare the Floppy Disks Prepare one floppy disk per downloaded image file. It is imperative that these disks are free from defects. The easiest way to test this is to reformat the disks. Do not trust pre-formatted floppies. The format utility in &windows; will not tell about the presence of bad blocks, it simply marks them as bad and ignores them. It is advised to use brand new floppies. If the installer crashes, freezes, or otherwise misbehaves, one of the first things to suspect is the floppies. Write the floppy image files to new disks and try again. Write the Image Files to the Floppy Disks The .flp files are not regular files that can be copied to the disk. They are images of the complete contents of the disk. Specific tools must be used to write the images directly to the disk. DOS &os; provides a tool called rawrite for creating the floppies on a computer running &windows;. This tool can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/pc98/ version-RELEASE/tools/ on the &os; FTP site. Download this tool, insert a floppy, then specify the filename to write to the floppy drive: C:\> rawrite boot.flp A: Repeat this command for each .flp file, replacing the floppy disk each time, being sure to label the disks with the name of the file. Adjust the command line as necessary, depending on where the .flp files are located. When writing the floppies on a &unix;-like system, such as another &os; system, use &man.dd.1; to write the image files directly to disk. On &os;, run: &prompt.root; dd if=boot.flp of=/dev/fd0 On &os;, /dev/fd0 refers to the first floppy disk. Other &unix; variants might have different names for the floppy disk device, so check the documentation for the system as necessary. You are now ready to start installing &os;. Starting the Installation By default, the installer will not make any changes to the disk(s) until after the following message: Last Chance: Are you SURE you want continue the installation? If you're running this on a disk with data you wish to save then WE STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! We can take no responsibility for lost disk contents! The install can be exited at any time prior to this final warning without changing the contents of the hard drive. If there is a concern that something is configured incorrectly, turn the computer off before this point, and no damage will be done. Booting Booting for the &i386; Turn on the computer. As it starts it should display an option to enter the system set up menu, or BIOS, commonly reached by keys like F2, F10, Del, or Alt S . Use whichever keystroke is indicated on screen. In some cases the computer may display a graphic while it starts. Typically, pressing Esc will dismiss the graphic and display the boot messages. Find the setting that controls which devices the system boots from. This is usually labeled as the Boot Order and commonly shown as a list of devices, such as Floppy, CDROM, First Hard Disk, and so on. If booting from the CD/DVD, make sure that the CDROM drive is selected. If booting from a USB disk, make sure that it is selected instead. When in doubt, consult the manual that came with the computer or its motherboard. Make the change, then save and exit. The computer should now restart. If using a prepared a bootable USB stick, as described in , plug in the USB stick before turning on the computer. If booting from CD/DVD, turn on the computer, and insert the CD/DVD at the first opportunity. For &os;/&arch.pc98;, installation boot floppies are available and can be prepared as described in . The first floppy disc will contain boot.flp. Put this floppy in the floppy drive to boot into the installer. If the computer starts up as normal and loads the existing operating system, then either: The disks were not inserted early enough in the boot process. Leave them in, and try restarting the computer. The BIOS changes did not work correctly. Redo that step until the right option is selected. That particular BIOS does not support booting from the desired media. &os; will start to boot. If booting from CD/DVD, messages will be displayed, similar to these: Booting from CD-Rom... 645MB medium detected CD Loader 1.2 Building the boot loader arguments Looking up /BOOT/LOADER... Found Relocating the loader and the BTX Starting the BTX loader BTX loader 1.00 BTX version is 1.02 Consoles: internal video/keyboard BIOS CD is cd0 BIOS drive C: is disk0 BIOS drive D: is disk1 BIOS 636kB/261056kB available memory FreeBSD/i386 bootstrap loader, Revision 1.1 Loading /boot/defaults/loader.conf /boot/kernel/kernel text=0x64daa0 data=0xa4e80+0xa9e40 syms=[0x4+0x6cac0+0x4+0x88e9d] \ If booting from floppy disc, a display similar to this will be shown: Booting from Floppy... Uncompressing ... done BTX loader 1.00 BTX version is 1.01 Console: internal video/keyboard BIOS drive A: is disk0 BIOS drive C: is disk1 BIOS 639kB/261120kB available memory FreeBSD/i386 bootstrap loader, Revision 1.1 Loading /boot/defaults/loader.conf /kernel text=0x277391 data=0x3268c+0x332a8 | Insert disk labelled "Kernel floppy 1" and press any key... Remove the boot.flp floppy, insert the next floppy, and press Enter. When prompted, insert the other disks as required. The boot process will then display the &os; boot loader menu:
&os; Boot Loader Menu
Either wait ten seconds, or press Enter. Booting for &sparc64; Most &sparc64; systems are set to boot automatically from disk. To install &os;, boot over the network or from a CD/DVD and wait until the boot message appears. The message depends on the model, but should look similar to: Sun Blade 100 (UltraSPARC-IIe), Keyboard Present Copyright 1998-2001 Sun Microsystems, Inc. All rights reserved. OpenBoot 4.2, 128 MB memory installed, Serial #51090132. Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4. If the system proceeds to boot from disk, press L1A or StopA on the keyboard, or send a BREAK over the serial console using ~# in &man.tip.1; or &man.cu.1; to get to the PROM prompt. It looks like this: ok ok {0} This is the prompt used on systems with just one CPU. This is the prompt used on SMP systems and the digit indicates the number of the active CPU. At this point, place the CD/DVD into the drive and from the PROM prompt, type boot cdrom. Reviewing the Device Probe Results The last few hundred lines that have been displayed on screen are stored and can be reviewed. To review this buffer, press Scroll Lock to turn on scrolling in the display. Use the arrow keys or PageUp and PageDown to view the results. Press Scroll Lock again to stop scrolling. Do this now, to review the text that scrolled off the screen when the kernel was carrying out the device probes. Text similar to will be displayed, although it will differ depending on the devices in the computer.
Typical Device Probe Results avail memory = 253050880 (247120K bytes) Preloaded elf kernel "kernel" at 0xc0817000. Preloaded mfs_root "/mfsroot" at 0xc0817084. md0: Preloaded image </mfsroot> 4423680 bytes at 0xc03ddcd4 md1: Malloc disk Using $PIR table, 4 entries at 0xc00fde60 npx0: <math processor> on motherboard npx0: INT 16 interface pcib0: <Host to PCI bridge> on motherboard pci0: <PCI bus> on pcib0 pcib1:<VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0 pci1: <PCI bus> on pcib1 pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11 isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0 isa0: <iSA bus> on isab0 atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0 ata0: at 0x1f0 irq 14 on atapci0 ata1: at 0x170 irq 15 on atapci0 uhci0 <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci 0 usb0: <VIA 83572 USB controller> on uhci0 usb0: USB revision 1.0 uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1 uhub0: 2 ports with 2 removable, self powered pci0: <unknown card> (vendor=0x1106, dev=0x3040) at 7.3 dc0: <ADMtek AN985 10/100BaseTX> port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir q 11 at device 8.0 on pci0 dc0: Ethernet address: 00:04:5a:74:6b:b5 miibus0: <MII bus> on dc0 ukphy0: <Generic IEEE 802.3u media interface> on miibus0 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xec00-0xec1f irq 9 at device 10. 0 on pci0 ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit) isa0: too many dependant configs (8) isa0: unexpected small tag 14 orm0: <Option ROM> at iomem 0xc0000-0xc7fff on isa0 fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq2 on isa0 fdc0: FIFO enabled, 8 bytes threshold fd0: <1440-KB 3.5” drive> on fdc0 drive 0 atkbdc0: <Keyboard controller (i8042)> at port 0x60,0x64 on isa0 atkbd0: <AT Keyboard> flags 0x1 irq1 on atkbdc0 kbd0 at atkbd0 psm0: <PS/2 Mouse> irq 12 on atkbdc0 psm0: model Generic PS/@ mouse, device ID 0 vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 sc0: <System console> at flags 0x100 on isa0 sc0: VGA <16 virtual consoles, flags=0x300> sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 sio0: type 16550A sio1 at port 0x2f8-0x2ff irq 3 on isa0 sio1: type 16550A ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 pppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode ppc0: FIFO with 16/16/15 bytes threshold plip0: <PLIP network interface> on ppbus0 ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master UDMA33 acd0: CD-RW <LITE-ON LTR-1210B> at ata1-slave PIO4 Mounting root from ufs:/dev/md0c /stand/sysinstall running as init on vty0
Check the probe results carefully to make sure that &os; found all the devices. If a device was not found, it will not be listed. A custom kernel can be used to add in support for devices which are not in the GENERIC kernel. After the device probe, the menu shown in will be displayed. Use the arrow key to choose a country, region, or group. Then press Enter to set the country.
Selecting Country Menu
If United States is selected as the country, the standard American keyboard map will be used. If a different country is chosen, the following menu will be displayed. Use the arrow keys to choose the correct keyboard map and press Enter.
Selecting Keyboard Menu
After the country selection, the &man.sysinstall.8; main menu will display. Introducing &man.sysinstall.8; The &os; 8.X installer, &man.sysinstall.8;, is console based and is divided into a number of menus and screens that can be used to configure and control the installation process. This menu system is controlled by the arrow keys, Enter, Tab, Space, and other keys. To view a detailed description of these keys and what they do, ensure that the Usage entry is highlighted and that the [Select] button is selected, as shown in , then press Enter. The instructions for using the menu system will be displayed. After reviewing them, press Enter to return to the Main Menu.
Selecting Usage from Sysinstall Main Menu
Selecting the Documentation Menu From the Main Menu, select Doc with the arrow keys and press Enter.
Selecting Documentation Menu
This will display the Documentation Menu.
Sysinstall Documentation Menu
It is important to read the documents provided. To view a document, select it with the arrow keys and press Enter. When finished reading a document, press Enter to return to the Documentation Menu. To return to the Main Installation Menu, select Exit with the arrow keys and press Enter. Selecting the Keymap Menu To change the keyboard mapping, use the arrow keys to select Keymap from the menu and press Enter. This is only required when using a non-standard or non-US keyboard.
Sysinstall Main Menu
A different keyboard mapping may be chosen by selecting the menu item using the up and down arrow keys and pressing Space. Pressing Space again will unselect the item. When finished, choose the &gui.ok; using the arrow keys and press Enter. Only a partial list is shown in this screen representation. Selecting &gui.cancel; by pressing Tab will use the default keymap and return to the Main Install Menu.
Sysinstall Keymap Menu
Installation Options Screen Select Options and press Enter.
Sysinstall Main Menu
Sysinstall Options
The default values are usually fine for most users and do not need to be changed. The release name will vary according to the version being installed. The description of the selected item will appear at the bottom of the screen highlighted in blue. Notice that one of the options is Use Defaults to reset all values to startup defaults. Press F1 to read the help screen about the various options. Press Q to return to the Main Install menu. Begin a Standard Installation The Standard installation is the option recommended for those new to &unix; or &os;. Use the arrow keys to select Standard and then press Enter to start the installation.
Begin Standard Installation
Allocating Disk Space The first task is to allocate disk space for &os;, and label that space so that &man.sysinstall.8; can prepare it. In order to do this you need to know how &os; expects to find information on the disk. BIOS Drive Numbering Before installing and configuring &os; it is important to be aware how &os; deals with BIOS drive mappings. MS-DOS Microsoft Windows In a PC running a BIOS-dependent operating system such as µsoft.windows;, the BIOS is able to abstract the normal disk drive order and the operating system goes along with the change. This allows the user to boot from a disk drive other than the "primary master". This is especially convenient for users buy an identical second hard drive, and perform routine copies of the first drive to the second drive. If the first drive fails, is attacked by a virus, or is scribbled upon by an operating system defect, they can easily recover by instructing the BIOS to logically swap the drives. It is like switching the cables on the drives, without having to open the case. SCSI BIOS Systems with SCSI controllers often include BIOS extensions which allow the SCSI drives to be re-ordered in a similar fashion for up to seven drives. A user who is accustomed to taking advantage of these features may become surprised when the results with &os; are not as expected. &os; does not use the BIOS, and does not know the logical BIOS drive mapping. This can lead to perplexing situations, especially when drives are physically identical in geometry and have been made as data clones of one another. When using &os;, always restore the BIOS to natural drive numbering before installing &os;, and then leave it that way. If drives need to be switched around, take the time to open the case and move the jumpers and cables. An Illustration from the Files of Bill and Fred's Exceptional Adventures: Bill breaks-down an older Wintel box to make another &os; box for Fred. Bill installs a single SCSI drive as SCSI unit zero and installs &os; on it. Fred begins using the system, but after several days notices that the older SCSI drive is reporting numerous errors. To address the situation, Bill grabs an identical SCSI drive and installs this drive as SCSI unit four and makes an image copy from drive zero to drive four. Now that the new drive is installed and functioning, Bill decides to start using it, so he uses features in the SCSI BIOS to re-order the disk drives so that the system boots from SCSI unit four. &os; boots and runs just fine. Fred continues his work and soon decides that it is time to upgrade to a newer version of &os;. Bill removes SCSI unit zero because it was a bit flaky and replaces it with another identical disk drive. Bill then installs the new version of &os; onto the new SCSI unit zero and the installation goes well. Fred uses the new version of &os; for a few days, and certifies that it is good enough for use in the engineering department. It is time to copy all of his work from the old version, so Fred mounts SCSI unit four which should contain the latest copy of the older &os; version. Fred is dismayed to find that none of his work is present on SCSI unit four. It turns out that when Bill made an image copy of the original SCSI unit zero onto SCSI unit four, unit four became the new clone. When Bill re-ordered the SCSI BIOS so that he could boot from SCSI unit four, &os; was still running on SCSI unit zero. Making this kind of BIOS change causes some or all of the boot and loader code to be fetched from the selected BIOS drive. But when the &os; kernel drivers take over, the BIOS drive numbering is ignored, and &os; transitions back to normal drive numbering. In this example, the system continued to operate on the original SCSI unit zero, and all of Fred's data was there, not on SCSI unit four. The fact that the system appeared to be running on SCSI unit four was simply an artifact of human expectations. Fortunately, the older SCSI unit zero was retrieved and all of Fred's work was restored. Although SCSI drives were used in this illustration, the concepts apply equally to IDE drives. Creating Slices Using FDisk After choosing to begin a standard installation in &man.sysinstall.8;, this message will appear: Message In the next menu, you will need to set up a DOS-style ("fdisk") partitioning scheme for your hard disk. If you simply wish to devote all disk space to FreeBSD (overwriting anything else that might be on the disk(s) selected) then use the (A)ll command to select the default partitioning scheme followed by a (Q)uit. If you wish to allocate only free space to FreeBSD, move to a partition marked "unused" and use the (C)reate command. [ OK ] [ Press enter or space ] Press Enter and a list of all the hard drives that the kernel found when it carried out the device probes will be displayed. shows an example from a system with two IDE disks called ad0 and ad2.
Select Drive for FDisk
Note that ad1 is not listed here. Consider two IDE hard disks where one is the master on the first IDE controller and one is the master on the second IDE controller. If &os; numbered these as ad0 and ad1, everything would work. But if a third disk is later added as the slave device on the first IDE controller, it would now be ad1, and the previous ad1 would become ad2. Because device names are used to find filesystems, some filesystems may no longer appear correctly, requiring a change to the &os; configuration. To work around this, the kernel can be configured to name IDE disks based on where they are and not the order in which they were found. With this scheme, the master disk on the second IDE controller will always be ad2, even if there are no ad0 or ad1 devices. This configuration is the default for the &os; kernel, which is why the display in this example shows ad0 and ad2. The machine on which this screenshot was taken had IDE disks on both master channels of the IDE controllers and no disks on the slave channels. Select the disk on which to install &os;, and then press &gui.ok;. FDisk will start, with a display similar to that shown in . The FDisk display is broken into three sections. The first section, covering the first two lines of the display, shows details about the currently selected disk, including its &os; name, the disk geometry, and the total size of the disk. The second section shows the slices that are currently on the disk, where they start and end, how large they are, the name &os; gives them, and their description and sub-type. This example shows two small unused slices which are artifacts of disk layout schemes on the PC. It also shows one large FAT slice, which appears as C: in &windows;, and an extended slice, which may contain other drive letters in &windows;. The third section shows the commands that are available in FDisk.
Typical Default <application>FDisk</application> Partitions
This step varies, depending on how the disk is to be sliced. To install &os; to the entire disk, which will delete all the other data on this disk, press A, which corresponds to the Use Entire Disk option. The existing slices will be removed and replaced with a small area flagged as unused and one large slice for &os;. Then, select the newly created &os; slice using the arrow keys and press S to mark the slice as being bootable. The screen will then look similar to . Note the A in the Flags column, which indicates that this slice is active, and will be booted from. If an existing slice needs to be deleted to make space for &os;, select the slice using the arrow keys and press D. Then, press C to be prompted for the size of the slice to create. Enter the appropriate value and press Enter. The default value in this box represents the largest possible slice to make, which could be the largest contiguous block of unallocated space or the size of the entire hard disk. If you have already made space for &os; then you can press C to create a new slice. Again, you will be prompted for the size of slice you would like to create.
Fdisk Partition Using Entire Disk
When finished, press Q. Any changes will be saved in &man.sysinstall.8;, but will not yet be written to disk. Install a Boot Manager The next menu provides the option to install a boot manager. In general, install the &os; boot manager if: There is more than one drive and &os; will be installed onto a drive other than the first one. &os; will be installed alongside another operating system on the same disk, and you want to choose whether to start &os; or the other operating system when the computer starts. If &os; is going to be the only operating system on this machine, installed on the first hard disk, then the Standard boot manager will suffice. Choose None if using a third-party boot manager capable of booting &os;. Make a selection and press Enter.
Sysinstall Boot Manager Menu
The help screen, reached by pressing F1, discusses the problems that can be encountered when trying to share the hard disk between operating systems. Creating Slices on Another Drive If there is more than one drive, it will return to the Select Drives screen after the boot manager selection. To install &os; on to more than one disk, select another disk and repeat the slice process using FDisk. If installing &os; on a drive other than the first drive, the &os; boot manager needs to be installed on both drives.
Exit Select Drive
Use Tab to toggle between the last drive selected, &gui.ok;, and &gui.cancel;. Press Tab once to toggle to &gui.ok;, then press Enter to continue with the installation. Creating Partitions Using <application>Disklabel</application> Next, create some partitions inside each slice. Remember that each partition is lettered, from a through to h, and that partitions b, c, and d have conventional meanings that should be adhered to. Certain applications can benefit from particular partition schemes, especially when laying out partitions across more than one disk. However, for a first &os; installation, do not give too much thought to how to partition the disk. It is more important to install &os; and start learning how to use it. You can always re-install &os; to change the partition scheme after becoming more familiar with the operating system. The following scheme features four partitions: one for swap space and three for filesystems. Partition Layout for First Disk Partition Filesystem Size Description a / 1 GB This is the root filesystem. Every other filesystem will be mounted somewhere under this one. 1 GB is a reasonable size for this filesystem as user files should not be stored here and a regular &os; install will put about 128 MB of data here. b N/A 2-3 x RAM The system's swap space is kept on the b partition. Choosing the right amount of swap space can be a bit of an art. A good rule of thumb is that swap space should be two or three times as much as the available physical memory (RAM). There should be at least 64 MB of swap, so if there is less than 32 MB of RAM in the computer, set the swap amount to 64 MB. If there is more than one disk, swap space can be put on each disk. &os; will then use each disk for swap, which effectively speeds up the act of swapping. In this case, calculate the total amount of swap needed and divide this by the number of disks to give the amount of swap to put on each disk. e /var 512 MB to 4096 MB /var contains files that are constantly varying, such as log files and other administrative files. Many of these files are read from or written to extensively during &os;'s day-to-day running. Putting these files on another filesystem allows &os; to optimize the access of these files without affecting other files in other directories that do not have the same access pattern. f /usr Rest of disk (at least 8 GB) All other files will typically be stored in /usr and its subdirectories.
The values above are given as example and should be used by experienced users only. Users are encouraged to use the automatic partition layout called Auto Defaults by the &os; partition editor. If installing &os; on to more than one disk, create partitions in the other configured slices. The easiest way to do this is to create two partitions on each disk, one for the swap space, and one for a filesystem. Partition Layout for Subsequent Disks Partition Filesystem Size Description b N/A See description Swap space can be split across each disk. Even though the a partition is free, convention dictates that swap space stays on the b partition. e /diskn Rest of disk The rest of the disk is taken up with one big partition. This could easily be put on the a partition, instead of the e partition. However, convention says that the a partition on a slice is reserved for the filesystem that will be the root (/) filesystem. Following this convention is not necessary, but &man.sysinstall.8; uses it, so following it makes the installation slightly cleaner. This filesystem can be mounted anywhere; this example mounts it as /diskn, where n is a number that changes for each disk.
Having chosen the partition layout, create it using &man.sysinstall.8;. Message Now, you need to create BSD partitions inside of the fdisk partition(s) just created. If you have a reasonable amount of disk space (1GB or more) and don't have any special requirements, simply use the (A)uto command to allocate space automatically. If you have more specific needs or just don't care for the layout chosen by (A)uto, press F1 for more information on manual layout. [ OK ] [ Press enter or space ] Press Enter to start the &os; partition editor, called Disklabel. shows the display when Disklabel starts. The display is divided into three sections. The first few lines show the name of the disk being worked on and the slice that contains the partitions to create. At this point, Disklabel calls this the Partition name rather than slice name. This display also shows the amount of free space within the slice; that is, space that was set aside in the slice, but that has not yet been assigned to a partition. The middle of the display shows the partitions that have been created, the name of the filesystem that each partition contains, their size, and some options pertaining to the creation of the filesystem. The bottom third of the screen shows the keystrokes that are valid in Disklabel.
Sysinstall Disklabel Editor
Disklabel can automatically create partitions and assign them default sizes. The default sizes are calculated with the help of an internal partition sizing algorithm based on the disk size. Press A to see a display similar to that shown in . Depending on the size of the disk, the defaults may or may not be appropriate. The default partitioning assigns /tmp its own partition instead of being part of the / partition. This helps avoid filling the / partition with temporary files.
Sysinstall Disklabel Editor with Auto Defaults
To replace the default partitions, use the arrow keys to select the first partition and press D to delete it. Repeat this to delete all the suggested partitions. To create the first partition, a, mounted as /, make sure the proper disk slice at the top of the screen is selected and press C. A dialog box will appear, prompting for the size of the new partition, as shown in . The size can be entered as the number of disk blocks to use or as a number followed by either M for megabytes, G for gigabytes, or C for cylinders.
Free Space for Root Partition
The default size shown will create a partition that takes up the rest of the slice. If using the partition sizes described in the earlier example, delete the existing figure using Backspace, and then type in 512M, as shown in . Then press &gui.ok;.
Edit Root Partition Size
After choosing the partition's size, the installer will ask whether this partition will contain a filesystem or swap space. The dialog box is shown in . This first partition will contain a filesystem, so check that FS is selected and press Enter.
Choose the Root Partition Type
Finally, tell Disklabel where the filesystem will be mounted. The dialog box is shown in . Type /, and then press Enter.
Choose the Root Mount Point
The display will then update to show the newly created partition. Repeat this procedure for the other partitions. When creating the swap partition, it will not prompt for the filesystem mount point. When creating the final partition, /usr, leave the suggested size as is to use the rest of the slice. The final &os; DiskLabel Editor screen will appear similar to , although the values chosen may be different. Press Q to finish.
Sysinstall Disklabel Editor
Choosing What to Install Select the Distribution Set Deciding which distribution set to install will depend largely on the intended use of the system and the amount of disk space available. The predefined options range from installing the smallest possible configuration to everything. Those who are new to &unix; or &os; should select one of these canned options. Customizing a distribution set is typically for the more experienced user. Press F1 for more information on the distribution set options and what they contain. When finished reviewing the help, press Enter to return to the Select Distributions Menu. If a graphical user interface is desired, the configuration of &xorg; and selection of a default desktop must be done after the installation of &os;. More information regarding the installation and configuration of a &xorg; can be found in . If compiling a custom kernel is anticipated, select an option which includes the source code. For more information on why a custom kernel should be built or how to build a custom kernel, see . The most versatile system is one that includes everything. If there is adequate disk space, select All, as shown in , by using the arrow keys and pressing Enter. If there is a concern about disk space, consider using an option that is more suitable for the situation. Do not fret over the perfect choice, as other distributions can be added after installation.
Choose Distributions
Installing the Ports Collection After selecting the desired distribution, an opportunity to install the &os; Ports Collection is presented. The Ports Collection is an easy and convenient way to install software as it provides a collection of files that automate the downloading, compiling, and installation of third-party software packages. discusses how to use the Ports Collection. The installation program does not check to see if you have adequate space. Select this option only if you have adequate hard disk space. As of &os; &rel.current;, the &os; Ports Collection takes up about &ports.size; of disk space. You can safely assume a larger value for more recent versions of &os;. User Confirmation Requested Would you like to install the FreeBSD ports collection? This will give you ready access to over &os.numports; ported software packages, at a cost of around &ports.size; of disk space when "clean" and possibly much more than that if a lot of the distribution tarballs are loaded (unless you have the extra CDs from a FreeBSD CD/DVD distribution available and can mount it on /cdrom, in which case this is far less of a problem). The Ports Collection is a very valuable resource and well worth having on your /usr partition, so it is advisable to say Yes to this option. For more information on the Ports Collection & the latest ports, visit: http://www.FreeBSD.org/ports [ Yes ] No Select &gui.yes; with the arrow keys to install the Ports Collection or &gui.no; to skip this option. Press Enter to continue. The Choose Distributions menu will redisplay.
Confirm Distributions
Once satisfied with the options, select Exit with the arrow keys, ensure that &gui.ok; is highlighted, and press Enter to continue. Choosing the Installation Media If installing from a CD/DVD, use the arrow keys to highlight Install from a &os; CD/DVD. Ensure that &gui.ok; is highlighted, then press Enter to proceed with the installation. For other methods of installation, select the appropriate option and follow the instructions. Press F1 to display the Online Help for installation media. Press Enter to return to the media selection menu.
Choose Installation Media
FTP Installation Modes installation network FTP There are three FTP installation modes to choose from: active FTP, passive FTP, or via a HTTP proxy. FTP Active: Install from an FTP server This option makes all FTP transfers use Active mode. This will not work through firewalls, but will often work with older FTP servers that do not support passive mode. If the connection hangs with passive mode (the default), try using active mode. FTP Passive: Install from an FTP server through a firewall - - FTP - passive mode - - This option instructs &man.sysinstall.8; - to use passive mode for all FTP + to use passive modeFTPpassive mode for all FTP operations. This allows the user to pass through firewalls that do not allow incoming connections on random TCP ports. FTP via a HTTP proxy: Install from an FTP server through a http proxy - - FTP - via a HTTP proxy - - This option instructs &man.sysinstall.8; to use the HTTP protocol to connect to a proxy for all FTP operations. The proxy will translate the requests and send them to the FTP server. This allows the user to pass through firewalls that do not allow FTP, but offer a HTTP - proxy. + proxyFTPvia a HTTP proxy. In this case, specify the proxy in addition to the FTP server. For a proxy FTP server, give the name of the server as part of the username, after an @ sign. The proxy server then fakes the real server. For example, to install from ftp.FreeBSD.org, using the proxy FTP server foo.example.com, listening on port 1234, go to the options menu, set the FTP username to ftp@ftp.FreeBSD.org and the password to an email address. As the installation media, specify FTP (or passive FTP, if the proxy supports it), and the URL ftp://foo.example.com:1234/pub/FreeBSD. Since /pub/FreeBSD from ftp.FreeBSD.org is proxied under foo.example.com, the proxy will fetch the files from ftp.FreeBSD.org as the installer requests them. Committing to the Installation The installation can now proceed if desired. This is also the last chance for aborting the installation to prevent changes to the hard drive. User Confirmation Requested Last Chance! Are you SURE you want to continue the installation? If you're running this on a disk with data you wish to save then WE STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! We can take no responsibility for lost disk contents! [ Yes ] No Select &gui.yes; and press Enter to proceed. The installation time will vary according to the distribution chosen, installation media, and the speed of the computer. There will be a series of messages displayed, indicating the status. The installation is complete when the following message is displayed: Message Congratulations! You now have FreeBSD installed on your system. We will now move on to the final configuration questions. For any option you do not wish to configure, simply select No. If you wish to re-enter this utility after the system is up, you may do so by typing: /usr/sbin/sysinstall. [ OK ] [ Press enter or space ] Press Enter to proceed with post-installation configurations. Selecting &gui.no; and pressing Enter will abort the installation so no changes will be made to the system. The following message will appear: Message Installation complete with some errors. You may wish to scroll through the debugging messages on VTY1 with the scroll-lock feature. You can also choose "No" at the next prompt and go back into the installation menus to retry whichever operations have failed. [ OK ] This message is generated because nothing was installed. Pressing Enter will return to the Main Installation Menu to exit the installation. Post-installation Configuration of various options can be performed after a successful installation. An option can be configured by re-entering the configuration menus before booting the new &os; system or after boot using &man.sysinstall.8; and then selecting the Configure menu. Network Device Configuration If PPP was previously configured for an FTP install, this screen will not display and can be configured after boot as described above. For detailed information on Local Area Networks and configuring &os; as a gateway/router refer to the Advanced Networking chapter. User Confirmation Requested Would you like to configure any Ethernet or PPP network devices? [ Yes ] No To configure a network device, select &gui.yes; and press Enter. Otherwise, select &gui.no; to continue.
Selecting an Ethernet Device
Select the interface to be configured with the arrow keys and press Enter. User Confirmation Requested Do you want to try IPv6 configuration of the interface? Yes [ No ] In this private local area network, the current Internet type protocol (IPv4) was sufficient and &gui.no; was selected with the arrow keys and Enter pressed. If connected to an existing IPv6 network with an RA server, choose &gui.yes; and press Enter. It will take several seconds to scan for RA servers. User Confirmation Requested Do you want to try DHCP configuration of the interface? Yes [ No ] If Dynamic Host Configuration Protocol DHCP) is not required, select &gui.no; with the arrow keys and press Enter. Selecting &gui.yes; will execute &man.dhclient.8; and, if successful, will fill in the network configuration information automatically. Refer to for more information. The following Network Configuration screen shows the configuration of the Ethernet device for a system that will act as the gateway for a Local Area Network.
Set Network Configuration for <replaceable>ed0</replaceable>
Use Tab to select the information fields and fill in appropriate information: Host The fully-qualified hostname, such as k6-2.example.com in this case. Domain The name of the domain that the machine is in, such as example.com for this case. IPv4 Gateway IP address of host forwarding packets to non-local destinations. This must be filled in if the machine is a node on the network. Leave this field blank if the machine is the gateway to the Internet for the network. The IPv4 Gateway is also known as the default gateway or default route. Name server IP address of the local DNS server. There is no local DNS server on this private local area network so the IP address of the provider's DNS server (208.163.10.2) was used. IPv4 address The IP address to be used for this interface was 192.168.0.1 Netmask The address block being used for this local area network is 192.168.0.0 - 192.168.0.255 with a netmask of 255.255.255.0. Extra options to &man.ifconfig.8; Any additional interface-specific options to &man.ifconfig.8;. There were none in this case. Use Tab to select &gui.ok; when finished and press Enter. User Confirmation Requested Would you like to bring the ed0 interface up right now? [ Yes ] No Choosing &gui.yes; and pressing Enter will bring the machine up on the network so it is ready for use. However, this does not accomplish much during installation, since the machine still needs to be rebooted. Configure Gateway User Confirmation Requested Do you want this machine to function as a network gateway? [ Yes ] No If the machine will be acting as the gateway for a local area network and forwarding packets between other machines, select &gui.yes; and press Enter. If the machine is a node on a network, select &gui.no; and press Enter to continue. Configure Internet Services User Confirmation Requested Do you want to configure inetd and the network services that it provides? Yes [ No ] If &gui.no; is selected, various services will not be enabled. These services can be enabled after installation by editing /etc/inetd.conf with a text editor. See for more information. Otherwise, select &gui.yes; to configure these services during install. An additional confirmation will display: User Confirmation Requested The Internet Super Server (inetd) allows a number of simple Internet services to be enabled, including finger, ftp and telnetd. Enabling these services may increase risk of security problems by increasing the exposure of your system. With this in mind, do you wish to enable inetd? [ Yes ] No Select &gui.yes; to continue. User Confirmation Requested inetd(8) relies on its configuration file, /etc/inetd.conf, to determine which of its Internet services will be available. The default FreeBSD inetd.conf(5) leaves all services disabled by default, so they must be specifically enabled in the configuration file before they will function, even once inetd(8) is enabled. Note that services for IPv6 must be separately enabled from IPv4 services. Select [Yes] now to invoke an editor on /etc/inetd.conf, or [No] to use the current settings. [ Yes ] No Selecting &gui.yes; allows services to be enabled by deleting the # at the beginning of the lines representing those services.
Editing <filename>inetd.conf</filename>
Once the edits are complete, press Esc to display a menu which will exit the editor and save the changes. Enabling SSH Login SSH sshd User Confirmation Requested Would you like to enable SSH login? Yes [ No ] Selecting &gui.yes; will enable &man.sshd.8;, the daemon for OpenSSH. This allows secure remote access to the machine. For more information about OpenSSH, see . Anonymous FTP FTP anonymous User Confirmation Requested Do you want to have anonymous FTP access to this machine? Yes [ No ] Deny Anonymous FTP Selecting the default &gui.no; and pressing Enter will still allow users who have accounts with passwords to use FTP to access the machine. Allow Anonymous FTP Anyone can access the machine if anonymous FTP connections are allowed. The security implications should be considered before enabling this option. For more information about security, see . To allow anonymous FTP, use the arrow keys to select &gui.yes; and press Enter. An additional confirmation will display: User Confirmation Requested Anonymous FTP permits un-authenticated users to connect to the system FTP server, if FTP service is enabled. Anonymous users are restricted to a specific subset of the file system, and the default configuration provides a drop-box incoming directory to which uploads are permitted. You must separately enable both inetd(8), and enable ftpd(8) in inetd.conf(5) for FTP services to be available. If you did not do so earlier, you will have the opportunity to enable inetd(8) again later. If you want the server to be read-only you should leave the upload directory option empty and add the -r command-line option to ftpd(8) in inetd.conf(5) Do you wish to continue configuring anonymous FTP? [ Yes ] No This message indicates that the FTP service will also have to be enabled in /etc/inetd.conf to allow anonymous FTP connections. Select &gui.yes; and press Enter to continue. The following screen will display:
Default Anonymous FTP Configuration
Use Tab to select the information fields and fill in appropriate information: UID The user ID to assign to the anonymous FTP user. All files uploaded will be owned by this ID. Group Which group to place the anonymous FTP user into. Comment String describing this user in /etc/passwd. FTP Root Directory Where files available for anonymous FTP will be kept. Upload Subdirectory Where files uploaded by anonymous FTP users will go. The FTP root directory will be put in /var by default. If there is not enough room there for the anticipated FTP needs, use /usr instead by setting the FTP root directory to /usr/ftp. Once satisfied with the values, press Enter to continue. User Confirmation Requested Create a welcome message file for anonymous FTP users? [ Yes ] No If &gui.yes; is selected, press Enter and the &man.cu.1; editor will automatically start.
Edit the FTP Welcome Message
Use the instructions to change the message. Note the file name location at the bottom of the editor screen. Press Esc and a pop-up menu will default to a) leave editor. Press Enter to exit and continue. Press Enter again to save any changes. Configure the Network File System The Network File System (NFS) allows sharing of files across a network. A machine can be configured as a server, a client, or both. Refer to for more information. NFS Server User Confirmation Requested Do you want to configure this machine as an NFS server? Yes [ No ] If there is no need for a NFS server, select &gui.no; and press Enter. If &gui.yes; is chosen, a message will pop-up indicating that /etc/exports must be created. Message Operating as an NFS server means that you must first configure an /etc/exports file to indicate which hosts are allowed certain kinds of access to your local filesystems. Press [Enter] now to invoke an editor on /etc/exports [ OK ] Press Enter to continue. A text editor will start, allowing /etc/exports to be edited.
Editing <filename>exports</filename>
Use the instructions to add the exported filesystems. Note the file name location at the bottom of the editor screen. Press Esc and a pop-up menu will default to a) leave editor. Press Enter to exit and continue. <acronym>NFS</acronym> Client The NFS client allows the machine to access NFS servers. User Confirmation Requested Do you want to configure this machine as an NFS client? Yes [ No ] With the arrow keys, select &gui.yes; or &gui.no; as appropriate and press Enter. System Console Settings There are several options available to customize the system console. User Confirmation Requested Would you like to customize your system console settings? [ Yes ] No To view and configure the options, select &gui.yes; and press Enter.
System Console Configuration Options
A commonly used option is the screen saver. Use the arrow keys to select Saver and then press Enter.
Screen Saver Options
Select the desired screen saver using the arrow keys and then press Enter. The System Console Configuration menu will redisplay. The default time interval is 300 seconds. To change the time interval, select Saver again. At the Screen Saver Options menu, select Timeout using the arrow keys and press Enter. A pop-up menu will appear:
Screen Saver Timeout
The value can be changed, then select &gui.ok; and press Enter to return to the System Console Configuration menu.
System Console Configuration Exit
Select Exit and press Enter to continue with the post-installation configuration. Setting the Time Zone Setting the time zone allows the system to automatically correct for any regional time changes and perform other time zone related functions properly. The example shown is for a machine located in the Eastern time zone of the United States. The selections will vary according to the geographic location. User Confirmation Requested Would you like to set this machine's time zone now? [ Yes ] No Select &gui.yes; and press Enter to set the time zone. User Confirmation Requested Is this machine's CMOS clock set to UTC? If it is set to local time or you don't know, please choose NO here! Yes [ No ] Select &gui.yes; or &gui.no; according to how the machine's clock is configured, then press Enter.
Select the Region
The appropriate region is selected using the arrow keys and then pressing Enter.
Select the Country
Select the appropriate country using the arrow keys and press Enter.
Select the Time Zone
The appropriate time zone is selected using the arrow keys and pressing Enter. Confirmation Does the abbreviation 'EDT' look reasonable? [ Yes ] No Confirm that the abbreviation for the time zone is correct. If it looks okay, press Enter to continue with the post-installation configuration. Mouse Settings This option allows cut and paste in the console and user programs using a 3-button mouse. If using a 2-button mouse, refer to &man.moused.8; for details on emulating the 3-button style. This example depicts a non-USB mouse configuration: User Confirmation Requested Does this system have a PS/2, serial, or bus mouse? [ Yes ] No Select &gui.yes; for a PS/2, serial, or bus mouse, or &gui.no; for a USB mouse, then press Enter.
Select Mouse Protocol Type
Use the arrow keys to select Type and press Enter.
Set Mouse Protocol
The mouse used in this example is a PS/2 type, so the default Auto is appropriate. To change the mouse protocol, use the arrow keys to select another option. Ensure that &gui.ok; is highlighted and press Enter to exit this menu.
Configure Mouse Port
Use the arrow keys to select Port and press Enter.
Setting the Mouse Port
This system had a PS/2 mouse, so the default PS/2 is appropriate. To change the port, use the arrow keys and then press Enter.
Enable the Mouse Daemon
Last, use the arrow keys to select Enable, and press Enter to enable and test the mouse daemon.
Test the Mouse Daemon
Move the mouse around the screen to verify that the cursor responds properly. If it does, select &gui.yes; and press Enter. If not, the mouse has not been configured correctly. Select &gui.no; and try using different configuration options. Select Exit with the arrow keys and press Enter to continue with the post-installation configuration. Install Packages Packages are pre-compiled binaries and are a convenient way to install software. Installation of one package is shown for purposes of illustration. Additional packages can also be added at this time if desired. After installation, &man.sysinstall.8; can be used to add additional packages. User Confirmation Requested The FreeBSD package collection is a collection of hundreds of ready-to-run applications, from text editors to games to WEB servers and more. Would you like to browse the collection now? [ Yes ] No Select &gui.yes; and press Enter to be presented with the Package Selection screens:
Select Package Category
Only packages on the current installation media are available for installation at any given time. All packages available will be displayed if All is selected. Otherwise, select a particular category. Highlight the selection with the arrow keys and press Enter. A menu will display showing all the packages available for the selection made:
Select Packages
The bash shell is shown as selected. Select as many packages as desired by highlighting the package and pressing Space. A short description of each package will appear in the lower left corner of the screen. Press Tab to toggle between the last selected package, &gui.ok;, and &gui.cancel;. Once finished marking the packages for installation, press Tab once to toggle to &gui.ok; and press Enter to return to the Package Selection menu. The left and right arrow keys will also toggle between &gui.ok; and &gui.cancel;. This method can also be used to select &gui.ok; and press Enter to return to the Package Selection menu.
Install Packages
Use the Tab and arrow keys to select [ Install ] and press Enter to see the installation confirmation message:
Confirm Package Installation
Select &gui.ok; and press Enter to start the package installation. Installation messages will appear until all of the installations have completed. Make note if there are any error messages. The final configuration continues after packages are installed. If no packages are selected, select Install to return to the final configuration. Add Users/Groups Add at least one user during the installation so that the system can be used without logging in as root. The root partition is generally small and running applications as root can quickly fill it. A bigger danger is noted below: User Confirmation Requested Would you like to add any initial user accounts to the system? Adding at least one account for yourself at this stage is suggested since working as the "root" user is dangerous (it is easy to do things which adversely affect the entire system). [ Yes ] No Select &gui.yes; and press Enter to continue with adding a user.
Select User
Select User with the arrow keys and press Enter.
Add User Information
The following descriptions will appear in the lower part of the screen as the items are selected with Tab to assist with entering the required information: Login ID The login name of the new user (mandatory). UID The numerical ID for this user (leave blank for automatic choice). Group The login group name for this user (leave blank for automatic choice). Password The password for this user (enter this field with care!). Full name The user's full name (comment). Member groups The groups this user belongs to. Home directory The user's home directory (leave blank for default). Login shell The user's login shell (leave blank for default of /bin/sh). In this example, the login shell was changed from /bin/sh to /usr/local/bin/bash to use the bash shell that was previously installed as a package. Do not use a shell that does not exist or the user will not be able to login. The most common shell used in &os; is the C shell, /bin/tcsh. The user was also added to the wheel group to be able to become a superuser with root privileges. Once satisfied, press &gui.ok; and the User and Group Management menu will redisplay:
Exit User and Group Management
Groups can also be added at this time. Otherwise, this menu may be accessed using &man.sysinstall.8; at a later time. When finished adding users, select Exit with the arrow keys and press Enter to continue the installation. Set the <username>root</username> Password Message Now you must set the system manager's password. This is the password you'll use to log in as "root". [ OK ] [ Press enter or space ] Press Enter to set the root password. The password will need to be typed in twice correctly. Do not forget this password. Notice that the typed password is not echoed, nor are asterisks displayed. New password: Retype new password : The installation will continue after the password is successfully entered. Exiting Install A message will ask if configuration is complete: User Confirmation Requested Visit the general configuration menu for a chance to set any last options? Yes [ No ] Select &gui.no; with the arrow keys and press Enter to return to the Main Installation Menu.
Exit Install
Select [X Exit Install] with the arrow keys and press Enter. The installer will prompt to confirm exiting the installation: User Confirmation Requested Are you sure you wish to exit? The system will reboot. [ Yes ] No Select &gui.yes;. If booting from the CDROM drive, the following message will remind you to remove the disk: Message Be sure to remove the media from the drive. [ OK ] [ Press enter or space ] The CDROM drive is locked until the machine starts to reboot, then the disk can quickly be removed from the drive. Press &gui.ok; to reboot. The system will reboot so watch for any error messages that may appear, see for more details. Tom Rhodes Contributed by Configure Additional Network Services Configuring network services can be a daunting task for users that lack previous knowledge in this area. Since networking and the Internet are critical to all modern operating systems, it is useful to have some understanding of &os;'s extensive networking capabilities. Network services are programs that accept input from anywhere on the network. Since there have been cases where bugs in network services have been exploited by attackers, it is important to only enable needed network services. If in doubt, do not enable a network service until it is needed. Services can be enabled with &man.sysinstall.8; or by editing /etc/rc.conf. Selecting the Networking option will display a menu similar to the one below:
Network Configuration Upper-level
The first option, Interfaces, is covered in . Selecting the AMD option adds support for &man.amd.8;. This is usually used in conjunction with NFS for automatically mounting remote filesystems. Next is the AMD Flags option. When selected, a menu will pop up where specific AMD flags can be entered. The menu already contains a set of default options: -a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map sets the default mount location which is specified here as /.amd_mnt. specifies the default log; however, when &man.syslogd.8; is used, all log activity will be sent to the system log daemon. /host is used to mount an exported file system from a remote host, while /net is used to mount an exported filesystem from an IP address. The default options for AMD exports are defined in /etc/amd.map. FTP anonymous The Anon FTP option permits anonymous FTP connections. Select this option to make this machine an anonymous FTP server. Be aware of the security risks involved with this option. Another menu will be displayed to explain the security risks and configuration in depth. The Gateway menu will configure the machine to be a gateway. This menu can also be used to unset the Gateway option if it was accidentally selected during installation. The Inetd option can be used to configure or completely disable &man.inetd.8;. The Mail option is used to configure the system's default Mail Transfer Agent (MTA). Selecting this option will bring up the following menu:
Select a Default MTA
This menu offers a choice as to which MTA to install and set as the default. An MTA is a mail server which delivers email to users on the system or the Internet. Select Sendmail to install Sendmail as the default MTA. Select Sendmail local to set Sendmail as the default MTA, but disable its ability to receive incoming email from the Internet. The other options, Postfix and Exim, provide alternatives to Sendmail. The next menu after the MTA menu is NFS client. This menu is used to configure the system to communicate with a NFS server which in turn is used to make filesystems available to other machines on the network over the NFS protocol. See for more information about client and server configuration. Below that option is the NFS server option, for setting the system up as an NFS server. This adds the required information to start up the Remote Procedure Call RPC services. RPC is used to coordinate connections between hosts and programs. Next in line is the Ntpdate option, which deals with time synchronization. When selected, a menu like the one below shows up:
Ntpdate Configuration
From this menu, select the server which is geographically closest. This will make the time synchronization more accurate as a farther server may have more connection latency. The next option is the PCNFSD selection. This option will install the net/pcnfsd package from the Ports Collection. This is a useful utility which provides NFS authentication services for systems which are unable to provide their own, such as Microsoft's &ms-dos; operating system. Now, scroll down a bit to see the other options:
Network Configuration Lower-level
RPC. communication between NFS servers and clients is managed by &man.rpcbind.8; which is required for NFS servers to operate correctly. Status monitoring is provided by &man.rpc.statd.8; and the reported status is usually held in /var/db/statd.status. The next option is for &man.rpc.lockd.8; which provides file locking services. This is usually used with &man.rpc.statd.8; to monitor which hosts are requesting locks and how frequently they request them. While these last two options are useful for debugging, they are not required for NFS servers and clients to operate correctly. The next menu, Routed, configures the routing daemon. &man.routed.8;, manages network routing tables, discovers multicast routers, and supplies a copy of the routing tables to any physically connected host on the network upon request. This is mainly used for machines which act as a gateway for the local network. If selected, a menu will request the default location of the utility. To accept the default location, press Enter. Yet another menu will ask for the flags to pass to &man.routed.8;. The default of should appear on the screen. The next menu, Rwhod, starts &man.rwhod.8; during system initialization. This utility broadcasts system messages across the network periodically, or collects them when in consumer mode. More information can be found in &man.ruptime.1; and &man.rwho.1;. The next to last option in the list is for &man.sshd.8;, the secure shell server for OpenSSH. It is highly recommended over the standard &man.telnetd.8; and &man.ftpd.8; servers as it is used to create a secure, encrypted connection from one host to another. The final option is TCP Extensions which are defined in RFC 1323 and RFC 1644. While on many hosts this can speed up connections, it can also cause some connections to be dropped. It is not recommended for servers, but may be beneficial for stand alone machines. Once the network services are configured, scroll up to the very top item which is X Exit and continue on to the next configuration item or simply exit &man.sysinstall.8; by selecting X Exit twice then [X Exit Install]. &os; Bootup &os;/&arch.i386; Bootup If everything went well, messages will scroll along the screen and a login prompt will appear. To view these messages, press Scroll-Lock then use PgUp and PgDn. Press Scroll-Lock again to return to the prompt. All of the messages may not display due to buffer limitations, but they can be read after logging using &man.dmesg.8;. Login using the username and password which were set during installation. Avoid logging in as root except when necessary. Typical boot messages (version information omitted): Copyright (c) 1992-2002 The FreeBSD Project. Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 The Regents of the University of California. All rights reserved. Timecounter "i8254" frequency 1193182 Hz CPU: AMD-K6(tm) 3D processor (300.68-MHz 586-class CPU) Origin = "AuthenticAMD" Id = 0x580 Stepping = 0 Features=0x8001bf<FPU,VME,DE,PSE,TSC,MSR,MCE,CX8,MMX> AMD Features=0x80000800<SYSCALL,3DNow!> real memory = 268435456 (262144K bytes) config> di sn0 config> di lnc0 config> di le0 config> di ie0 config> di fe0 config> di cs0 config> di bt0 config> di aic0 config> di aha0 config> di adv0 config> q avail memory = 256311296 (250304K bytes) Preloaded elf kernel "kernel" at 0xc0491000. Preloaded userconfig_script "/boot/kernel.conf" at 0xc049109c. md0: Malloc disk Using $PIR table, 4 entries at 0xc00fde60 npx0: <math processor> on motherboard npx0: INT 16 interface pcib0: <Host to PCI bridge> on motherboard pci0: <PCI bus> on pcib0 pcib1: <VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0 pci1: <PCI bus> on pcib1 pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11 isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0 isa0: <ISA bus> on isab0 atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0 ata0: at 0x1f0 irq 14 on atapci0 ata1: at 0x170 irq 15 on atapci0 uhci0: <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci0 usb0: <VIA 83C572 USB controller> on uhci0 usb0: USB revision 1.0 uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr 1 uhub0: 2 ports with 2 removable, self powered chip1: <VIA 82C586B ACPI interface> at device 7.3 on pci0 ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xe800-0xe81f irq 9 at device 10.0 on pci0 ed0: address 52:54:05:de:73:1b, type NE2000 (16 bit) isa0: too many dependant configs (8) isa0: unexpected small tag 14 fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq 2 on isa0 fdc0: FIFO enabled, 8 bytes threshold fd0: <1440-KB 3.5" drive> on fdc0 drive 0 atkbdc0: <keyboard controller (i8042)> at port 0x60-0x64 on isa0 atkbd0: <AT Keyboard> flags 0x1 irq 1 on atkbdc0 kbd0 at atkbd0 psm0: <PS/2 Mouse> irq 12 on atkbdc0 psm0: model Generic PS/2 mouse, device ID 0 vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 sc0: <System console> at flags 0x1 on isa0 sc0: VGA <16 virtual consoles, flags=0x300> sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 sio0: type 16550A sio1 at port 0x2f8-0x2ff irq 3 on isa0 sio1: type 16550A ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode ppc0: FIFO with 16/16/15 bytes threshold ppbus0: IEEE1284 device found /NIBBLE Probing for PnP devices on ppbus0: plip0: <PLIP network interface> on ppbus0 lpt0: <Printer> on ppbus0 lpt0: Interrupt-driven port ppi0: <Parallel I/O> on ppbus0 ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master using UDMA33 ad2: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata1-master using UDMA33 acd0: CDROM <DELTA OTC-H101/ST3 F/W by OIPD> at ata0-slave using PIO4 Mounting root from ufs:/dev/ad0s1a swapon: adding /dev/ad0s1b as swap device Automatic boot in progress... /dev/ad0s1a: FILESYSTEM CLEAN; SKIPPING CHECKS /dev/ad0s1a: clean, 48752 free (552 frags, 6025 blocks, 0.9% fragmentation) /dev/ad0s1f: FILESYSTEM CLEAN; SKIPPING CHECKS /dev/ad0s1f: clean, 128997 free (21 frags, 16122 blocks, 0.0% fragmentation) /dev/ad0s1g: FILESYSTEM CLEAN; SKIPPING CHECKS /dev/ad0s1g: clean, 3036299 free (43175 frags, 374073 blocks, 1.3% fragmentation) /dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS /dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation) Doing initial network setup: hostname. ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1 ether 52:54:05:de:73:1b lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 inet6 fe80::1%lo0 prefixlen 64 scopeid 0x8 inet6 ::1 prefixlen 128 inet 127.0.0.1 netmask 0xff000000 Additional routing options: IP gateway=YES TCP keepalive=YES routing daemons:. additional daemons: syslogd. Doing additional network setup:. Starting final network daemons: creating ssh RSA host key Generating public/private rsa1 key pair. Your identification has been saved in /etc/ssh/ssh_host_key. Your public key has been saved in /etc/ssh/ssh_host_key.pub. The key fingerprint is: cd:76:89:16:69:0e:d0:6e:f8:66:d0:07:26:3c:7e:2d root@k6-2.example.com creating ssh DSA host key Generating public/private dsa key pair. Your identification has been saved in /etc/ssh/ssh_host_dsa_key. Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. The key fingerprint is: f9:a1:a9:47:c4:ad:f9:8d:52:b8:b8:ff:8c:ad:2d:e6 root@k6-2.example.com. setting ELF ldconfig path: /usr/lib /usr/lib/compat /usr/X11R6/lib /usr/local/lib a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout starting standard daemons: inetd cron sshd usbd sendmail. Initial rc.i386 initialization:. rc.i386 configuring syscons: blank_time screensaver moused. Additional ABI support: linux. Local package initialization:. Additional TCP options:. FreeBSD/i386 (k6-2.example.com) (ttyv0) login: rpratt Password: Generating the RSA and DSA keys may take some time on slower machines. This happens only on the initial boot-up of a new installation. Subsequent boots will be faster. If &xorg; has been configured and a default desktop chosen, it can be started by typing startx at the command line. &os; Shutdown It is important to properly shutdown the operating system. Do not just turn off the power. First, become the superuser using &man.su.1; and entering the root password. This will work only if the user is a member of wheel. Otherwise, login as root. To shutdown the system, type shutdown -h now. The operating system has halted. Please press any key to reboot. It is safe to turn off the power after the shutdown command has been issued and the message Please press any key to reboot appears. If any key is pressed instead of turning off the power switch, the system will reboot. The Ctrl Alt Del key combination can also be used to reboot the system; however, this is not recommended. Troubleshooting installation troubleshooting This section covers basic installation troubleshooting of common problems. There are also a few questions and answers for people wishing to dual-boot &os; with &windows;. If Something Goes Wrong Due to various limitations of the PC architecture, it is impossible for device probing to be 100% reliable. However, there are a few things to try if it fails. Check the Hardware Notes document for the version of &os; to make sure the hardware is supported. If the hardware is supported but still experiences lock-ups or other problems, build a custom kernel to add in support for devices which are not present in the GENERIC kernel. The default kernel assumes that most hardware devices are in their factory default configuration in terms of IRQs, I/O addresses, and DMA channels. If the hardware has been reconfigured, create a custom kernel configuration file and recompile to tell &os; where to find things. It is also possible that a probe for a device not present will cause a later probe for another device that is present to fail. In that case, the probes for the conflicting driver(s) should be disabled. Some installation problems can be avoided or alleviated by updating the firmware on various hardware components, most notably the motherboard BIOS. Most motherboard and computer manufacturers have a website where upgrade information may be located. Most manufacturers strongly advise against upgrading the motherboard BIOS unless there is a good reason for doing so, such as a critical update. The upgrade process can go wrong, causing permanent damage to the BIOS chip. Using &windows; Filesystems At this time, &os; does not support file systems compressed with the Double Space™ application. Therefore the file system will need to be uncompressed before &os; can access the data. This can be done by running the Compression Agent located in the Start> Programs > System Tools menu. &os; can support &ms-dos; file systems (sometimes called FAT file systems). The &man.mount.msdosfs.8; command grafts such file systems onto the existing directory hierarchy, allowing the file system's contents to be accessed. The &man.mount.msdosfs.8; program is not usually invoked directly; instead, it is called by the system through a line in /etc/fstab or by using &man.mount.8; with the appropriate parameters. A typical line in /etc/fstab is: /dev/ad0sN /dos msdosfs rw 0 0 /dos must already exist for this to work. For details about the format of /etc/fstab, see &man.fstab.5;. A typical call to &man.mount.8; for a FAT filesystem looks like: &prompt.root; mount -t msdosfs /dev/ad0s1 /mnt In this example, the FAT filesystem is located on the first partition of the primary hard disk. The output from &man.dmesg.8; and &man.mount.8; should produce enough information to give an idea of the partition layout. &os; may number FAT partitions differently than other operating systems. In particular, extended partitions are usually given higher slice numbers than primary partitions. Use &man.fdisk.8; to help determine which slices belong to &os; and which belong to other operating systems. NTFS partitions can also be mounted in a similar manner using &man.mount.ntfs.8;. Troubleshooting Questions and Answers My system hangs while probing hardware during boot or it behaves strangely during install. &os; makes extensive use of the system ACPI service on the i386, amd64, and ia64 platforms to aid in system configuration if it is detected during boot. Unfortunately, some bugs still exist in the ACPI driver and various system motherboards. The use of ACPI can be disabled by setting hint.acpi.0.disabled in the third stage boot loader: set hint.acpi.0.disabled="1" This is reset each time the system is booted, so it is necessary to add hint.acpi.0.disabled="1" to /boot/loader.conf to make this change permanent. More information about the boot loader can be found in . When booting from the hard disk for the first time after installing &os;, the kernel loads and probes hardware, but stops with messages like: changing root device to ad1s1a panic: cannot mount root What is wrong? This can occur when the boot disk is not the first disk in the system. The BIOS uses a different numbering scheme to &os;, and working out which numbers correspond to which is difficult to get right. If this occurs, tell &os; where the root filesystem is by specifying the BIOS disk number, the disk type, and the &os; disk number for that type. Consider two IDE disks, each configured as the master on their respective IDE bus, where &os; should be booted from the second disk. The BIOS sees these as disk 0 and disk 1, while &os; sees them as ad0 and ad2. If &os; is on BIOS disk 1, of type ad and the &os; disk number is 2, this is the correct value: 1:ad(2,a)kernel Note that if there is a slave on the primary bus, the above is not necessary and is effectively wrong. The second situation involves booting from a SCSI disk when there are one or more IDE disks in the system. In this case, the &os; disk number is lower than the BIOS disk number. For two IDE disks and a SCSI disk, where the SCSI disk is BIOS disk 2, type da, and &os; disk number 0, the correct value is: 2:da(0,a)kernel This tells &os; to boot from BIOS disk 2, which is the first SCSI disk in the system. If there is only IDE disk, use 1: instead. Once the correct value to use is determined, put the command in /boot.config using a text editor. Unless instructed otherwise, &os; will use the contents of this file as the default response to the boot: prompt. When booting from the hard disk for the first time after installing &os;, the Boot Manager prompt just prints F? at the boot menu and the boot will not go any further. The hard disk geometry was set incorrectly in the partition editor when &os; was installed. Go back into the partition editor and specify the actual geometry of the hard disk. &os; must be reinstalled again from the beginning with the correct geometry. For a dedicated &os; system that does not need future compatibility with another operating system, use the entire disk by selecting A in the installer's partition editor. The system finds the &man.ed.4; network card but continuously displays device timeout errors. The card is probably on a different IRQ from what is specified in /boot/device.hints. The &man.ed.4; driver does not use software configuration by default, but it will if -1 is specified in the hints for the interface. Either move the jumper on the card to the configuration setting or specify the IRQ as -1 by setting the hint hint.ed.0.irq="-1". This tells the kernel to use the software configuration. Another possibility is that the card is at IRQ 9, which is shared by IRQ 2 and frequently a cause of problems, especially if a VGA card is using IRQ 2. Do not use IRQ 2 or 9 if at all possible. When &man.sysinstall.8; is used in an &xorg; terminal, the yellow font is difficult to read against the light gray background. Is there a way to provide higher contrastcolor contrast for this application? If the default colors chosen by &man.sysinstall.8; make text illegible while using x11/xterm or x11/rxvt, add the following to ~/.Xdefaults to get a darker background gray: XTerm*color7: #c0c0c0 Valentino Vaschetto Contributed by Marc Fonvieille Updated by Advanced Installation Guide This section describes how to install &os; in exceptional cases. Installing &os; on a System Without a Monitor or Keyboard installation headless (serial console) serial console This type of installation is called a headless install because the machine to be installed does not have either an attached monitor or a VGA output. This type of installation is possible using a serial console, another machine which acts as the main display and keyboard. To do this, follow the steps to create an installation USB stick, explained in , or download the correct installation ISO image as described in . To modify the installation media to boot into a serial console, follow these steps. If using a CD/DVD media, skip the first step): Enabling the Installation USB Stick to Boot into a Serial Console &man.mount.8; By default, booting into the USB stick boots into the installer. To instead boot into a serial console, mount the USB disk onto a &os; system using &man.mount.8;: &prompt.root; mount /dev/da0a /mnt Adapt the device node and the mount point to the situation. Once the USB stick is mounted, set it to boot into a serial console. Add this line to /boot/loader.conf on the USB stick: &prompt.root; echo 'console="comconsole"' >> /mnt/boot/loader.conf Now that the USB is stick configured correctly, unmount the disk using &man.umount.8;: &prompt.root; umount /mnt Now, unplug the USB stick and jump directly to the third step of this procedure. Enabling the Installation CD/DVD to Boot into a Serial Console &man.mount.8; By default, when booting into the installation CD/DVD, &os; boots into its normal install mode. To instead boot into a serial console, extract, modify, and regenerate the ISO image before burning it to the CD/DVD media. From the &os; system with the saved installation ISO image, use &man.tar.1; to extract all the files: &prompt.root; mkdir /path/to/headless-iso &prompt.root; tar -C /path/to/headless-iso -pxvf &os;-&rel.current;-RELEASE-i386-disc1.iso Next, set the installation media to boot into a serial console. Add this line to the /boot/loader.conf of the extracted ISO image: &prompt.root; echo 'console="comconsole"' >> /path/to/headless-iso/boot/loader.conf Then, create a new ISO image from the modified tree. This example uses &man.mkisofs.8; from the sysutils/cdrtools package or port: &prompt.root; mkisofs -v -b boot/cdboot -no-emul-boot -r -J -V "Headless_install" \ -o Headless-&os;-&rel2.current;-RELEASE-i386-disc1.iso/path/to/headless-iso Now that the ISO image is configured correctly, burn it to a CD/DVD media using a burning application. Connecting the Null-modem Cable null-modem cable Connect a null-modem cable to the serial ports of the two machines. A normal serial cable will not work. A null-modem cable is required. Booting Up for the Install It is now time to go ahead and start the install. Plug in the USB stick or insert the CD/DVD media in the headless install machine and power it on. Connecting to the Headless Machine &man.cu.1; Next, connect to that machine with &man.cu.1;: &prompt.root; cu -l /dev/cuau0 The headless machine can now be controlled using &man.cu.1;. It will load the kernel and then dispaly a selection of which type of terminal to use. Select the &os; color console and proceed with the installation. Preparing Custom Installation Media Some situations may require a customized &os; installation media and/or source. This might be physical media or a source that &man.sysinstall.8; can use to retrieve the installation files. Some example situations include: A local network with many machines has a private FTP server hosting the &os; installation files which the machines should use for installation. &os; does not recognize the CD/DVD drive but &windows; does. In this case, copy the &os; installation files to a &windows; partition on the same computer, and then install &os; using those files. The computer to install does not have a CD/DVD drive or a network card, but can be connected using a null-printer cable to a computer that does. A tape will be be used to install &os;. Creating an Installation ISO As part of each release, the &os; Project provides ISO images for each supported architecture. These images can be written (burned) to CD or DVD media using a burning application, and then used to install &os;. If a CD/DVD writer is available, this is the easiest way to install &os;. Download the Correct ISO Images The ISO images for each release can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-arch/version or the closest mirror. or the closest mirror. Substitute arch and version as appropriate. An image directory normally contains the following images: &os; ISO Image Names and Meanings Filename Contents &os;-version-RELEASE-arch-bootonly.iso This CD image starts the installation process by booting from a CD-ROM drive but it does not contain the support for installing &os; from the CD itself. Perform a network based install, such as from an FTP server, after booting from this CD. &os;-version-RELEASE-arch-dvd1.iso.gz This DVD image contains everything necessary to install the base &os; operating system, a collection of pre-built packages, and the documentation. It also supports booting into a livefs based rescue mode. &os;-version-RELEASE-arch-memstick.img This image can be written to an USB memory stick in order to install machines capable of booting from USB drives. It also supports booting into a livefs based rescue mode. The only included package is the documentation package. &os;-version-RELEASE-arch-disc1.iso This CD image contains the base &os; operating system and the documentation package but no other packages. &os;-version-RELEASE-arch-disc2.iso A CD image with as many third-party packages as would fit on the disc. This image is not available for &os; 9.X. &os;-version-RELEASE-arch-disc3.iso Another CD image with as many third-party packages as would fit on the disc. This image is not available for &os; 9.X. &os;-version-RELEASE-arch-livefs.iso This CD image contains support for booting into a livefs based rescue mode but does not support doing an install from the CD itself.
When performing a CD installation, download either the bootonly ISO image or disc1. Do not download both, since disc1 contains everything that the bootonly ISO image contains. Use the bootonly ISO to perform a network install over the Internet. Additional software can be installed as needed using the Ports Collection as described in . Use dvd1 to install &os; and a selection of third-party packages from the disc. Burn the Media Next, write the downloaded image(s) to disc. If using another &os; system, refer to and for instructions. If using another platform, use any burning utility that exists for that platform. The images are in the standard ISO format which most CD writing applications support. To build a customized release of &os;, refer to the Release Engineering Article. Creating a Local FTP Site with a &os; Disc installation network FTP &os; discs are laid out in the same way as the FTP site. This makes it easy to create a local FTP site that can be used by other machines on a network to install &os;. On the &os; computer that will host the FTP site, ensure that the CD/DVD is in the drive and mounted: &prompt.root; mount /cdrom Create an account for anonymous FTP. Use &man.vipw.8; to insert this line: ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent Ensure that the FTP service is enabled in /etc/inetd.conf. Anyone with network connectivity to the machine can now chose a media type of FTP and type in ftp://your machine after picking Other in the FTP sites menu during the install. If the boot media for the FTP clients is not precisely the same version as that provided by the local FTP site, &man.sysinstall.8; will not complete the installation. To override this, go into the Options menu and change the distribution name to any. This approach is acceptable for a machine on the local network which is protected by a firewall. Offering anonymous FTP services to other machines over the Internet exposes the computer to increased security risks. It is strongly recommended to follow good security practices when providing services over the Internet. Installing from an &windows; Partition installation from &windows; To prepare for an installation from a &windows; partition, copy the files from the distribution into a directory in the root directory of the partition, such as c:\freebsd. Since the directory structure must be reproduced, it is recommended to use robocopy when copying from a CD/DVD. For example, to prepare for a minimal installation of &os;: C:\> md c:\freebsd C:\> robocopy e:\bin c:\freebsd\bin\ /s C:\> robocopy e:\manpages c:\freebsd\manpages\ /s This example assumes that C: has enough free space and E: is where the CD/DVD is mounted. Alternatively, download the distribution from ftp.FreeBSD.org. Each distribution is in its own directory; for example, the base distribution can be found in the &rel2.current;/base/ directory. Copy the distributions to install from a &windows; partition to c:\freebsd. Both the base and kernel distributions are needed for the most minimal installation. Before Installing over a Network installation network serial (PPP) installation network parallel (PLIP) installation network Ethernet There are three types of network installations available: Ethernet, PPP, and PLIP. For the fastest possible network installation, use an Ethernet adapter. &os; supports most common Ethernet cards. A list of supported cards is provided in the Hardware Notes for each release of &os;. If using a supported PCMCIA Ethernet card, be sure that it is plugged in before the system is powered on as &os; does not support hot insertion of PCMCIA cards during installation. Make note of the system's IP address, subnet mask, hostname, default gateway address, and DNS server addresses if these values are statically assigned. If installing by FTP through a HTTP proxy, make note of the proxy's address. If you do not know these values, ask the system administrator or ISP before trying this type of installation. If using a dialup modem, have the service provider's PPP information handy as it is needed early in the installation process. If PAP or CHAP are used to connect to the ISP without using a script, type dial at the &os; ppp prompt. Otherwise, know how to dial the ISP using the AT commands specific to the modem, as the PPP dialer provides only a simple terminal emulator. Refer to and for further information. Logging can be directed to the screen using set log local .... If a hard-wired connection to another &os; machine is available, the installation can occur over a null-modem parallel port cable. The data rate over the parallel port is higher than what is typically possible over a serial line. Before Installing via <acronym>NFS</acronym> installation network NFS To perform an NFS installation, copy the needed &os; distribution files to an NFS server and then point the installer's NFS media selection to it. If the server supports only a privileged port, set the option NFS Secure in the Options menu so that the installation can proceed. If using a poor quality Ethernet card which suffers from slow transfer rates, toggle the NFS Slow flag to on. In order for an NFS installation to work, the server must support subdir mounts. For example, if the &os; &rel.current; distribution lives on: ziggy:/usr/archive/stuff/FreeBSD, ziggy will have to allow the direct mounting of /usr/archive/stuff/FreeBSD, not just /usr or /usr/archive/stuff. In &os;, this is controlled by using in /etc/exports. Other NFS servers may have different conventions. If the server is displaying permission denied messages, it is likely that this is not enabled properly. diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml index a413c4bb62..eac6e1decb 100644 --- a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml @@ -1,956 +1,884 @@ Jim Mock Restructured, reorganized, and parts rewritten by Introduction Synopsis Thank you for your interest in &os;! The following chapter covers various aspects of the &os; Project, such as its history, goals, development model, and so on. After reading this chapter, you will know: How &os; relates to other computer operating systems. The history of the &os; Project. The goals of the &os; Project. The basics of the &os; open-source development model. And of course: where the name &os; comes from. Welcome to &os;! 4.4BSD-Lite &os; is a 4.4BSD-Lite based operating system for Intel (x86 and &itanium;), AMD64, Sun &ultrasparc; computers. Ports to other architectures are also underway. You can also read about the history of &os;, or the current release. If you are interested in contributing something to the Project (code, hardware, funding), see the Contributing to &os; article. What Can &os; Do? &os; has many noteworthy features. Some of these are: - preemptive - multitasking - - Preemptive multitasking with + Preemptive multitaskingpreemptive multitasking with dynamic priority adjustment to ensure smooth and fair sharing of the computer between applications and users, even under the heaviest of loads. - multi-user - facilities - - Multi-user facilities which allow + Multi-user facilitiesmulti-user facilities which allow many people to use a &os; system simultaneously for a variety of things. This means, for example, that system peripherals such as printers and tape drives are properly shared between all users on the system or the network and that individual resource limits can be placed on users or groups of users, protecting critical system resources from over-use. - TCP/IP networking - - Strong TCP/IP networking with + Strong TCP/IP networkingTCP/IP networking with support for industry standards such as SCTP, DHCP, NFS, NIS, PPP, SLIP, IPsec, and IPv6. This means that your &os; machine can interoperate easily with other systems as well as act as an enterprise server, providing vital functions such as NFS (remote file access) and email services or putting your organization on the Internet with WWW, FTP, routing and firewall (security) services. - memory protection - - Memory protection ensures that + Memory protectionmemory protection ensures that applications (or users) cannot interfere with each other. One application crashing will not affect others in any way. - - X Window System - - The industry standard X Window - System (X11R7) provides a graphical user + SystemX Window System (X11R7) provides a graphical user interface (GUI) for the cost of a common VGA card and monitor and comes with full sources. + binary compatibility Linux binary compatibility SCO binary compatibility SVR4 binary compatibility BSD/OS binary compatibility NetBSD - - Binary compatibility with many + Binary compatibility with many programs built for Linux, SCO, SVR4, BSDI and NetBSD. Thousands of ready-to-run applications are available from the &os; ports and packages collection. Why search the net when you can find it all right here? Thousands of additional and easy-to-port applications are available on the Internet. &os; is source code compatible with most popular commercial &unix; systems and thus most applications require few, if any, changes to compile. - virtual memory - - Demand paged virtual memory and + Demand paged virtual memoryvirtual memory and merged VM/buffer cache design efficiently satisfies applications with large appetites for memory while still maintaining interactive response to other users. - - Symmetric Multi-Processing (SMP) - - - SMP support for machines with + SMPSymmetric Multi-Processing (SMP) support for machines with multiple CPUs. + compilers C compilers C++ - - A full complement of C + A full complement of C and C++ development tools. Many additional languages for advanced research and development are also available in the ports and packages collection. - source code - - Source code for the entire system + Source codesource code for the entire system means you have the greatest degree of control over your environment. Why be locked into a proprietary solution at the mercy of your vendor when you can have a truly open system? Extensive online documentation. And many more! - 4.4BSD-Lite - - Computer Systems Research Group (CSRG) - - U.C. Berkeley - &os; is based on the 4.4BSD-Lite release from Computer - Systems Research Group (CSRG) at the University of California + &os; is based on the 4.4BSD-Lite4.4BSD-Lite release from Computer + Systems Research Group (CSRG)Computer Systems Research Group (CSRG) at the University of California at Berkeley, and carries on the distinguished tradition of BSD systems development. In addition to the fine work provided by CSRG, the &os; Project has put in many thousands of hours in fine tuning the system for maximum performance and reliability in real-life load situations. As many of the commercial giants struggle to field PC operating systems with such features, performance and reliability, &os; can offer them now! The applications to which &os; can be put are truly limited only by your own imagination. From software development to factory automation, inventory control to azimuth correction of remote satellite antennae; if it can be done with a commercial &unix; product then it is more than likely that you can do it with &os; too! &os; also benefits significantly from literally thousands of high quality applications developed by research centers and universities around the world, often available at little to no cost. Commercial applications are also available and appearing in greater numbers every day. Because the source code for &os; itself is generally available, the system can also be customized to an almost unheard of degree for special applications or projects, and in ways not generally possible with operating systems from most major commercial vendors. Here is just a sampling of some of the applications in which people are currently using &os;: Internet Services: The robust TCP/IP networking built into &os; makes it an ideal platform for a variety of Internet services such as: - FTP servers - - FTP servers + FTP serversFTP servers - web servers - - World Wide Web servers (standard or secure + World Wide Web serversweb servers (standard or secure [SSL]) IPv4 and IPv6 routing - firewall - - NAT - - Firewalls and NAT (IP masquerading) + Firewallsfirewall and NATNAT (IP masquerading) gateways + electronic mail email email - - Electronic Mail servers + Electronic Mail servers - USENET - - USENET News or Bulletin Board Systems + USENETUSENET News or Bulletin Board Systems And more... With &os;, you can easily start out small with an inexpensive 386 class PC and upgrade all the way up to a quad-processor Xeon with RAID storage as your enterprise grows. Education: Are you a student of computer science or a related engineering field? There is no better way of learning about operating systems, computer architecture and networking than the hands on, under the hood experience that &os; can provide. A number of freely available CAD, mathematical and graphic design packages also make it highly useful to those whose primary interest in a computer is to get other work done! Research: With source code for the entire system available, &os; is an excellent platform for research in operating systems as well as other branches of computer science. &os;'s freely available nature also makes it possible for remote groups to collaborate on ideas or shared development without having to worry about special licensing agreements or limitations on what may be discussed in open forums. - router - - DNS Server - - Networking: Need a new router? - A name server (DNS)? A firewall to keep people out of your + Networking: Need a new router?router + A name server (DNS)?DNS Server A firewall to keep people out of your internal network? &os; can easily turn that unused 386 or 486 PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities. + X Window System X Window System Accelerated-X - - X Window workstation: &os; is a + X Window workstation: &os; is a fine choice for an inexpensive X terminal solution, using the freely available X11 server. Unlike an X terminal, &os; allows many applications to be run locally if desired, thus relieving the burden on a central server. &os; can even boot diskless, making individual workstations even cheaper and easier to administer. - GNU Compiler - Collection - Software Development: The basic &os; system comes with a full complement of development - tools including the renowned GNU C/C++ compiler and + tools including the renowned GNU C/C++GNU Compiler Collection compiler and debugger. &os; is available in both source and binary form on CD-ROM, DVD, and via anonymous FTP. Please see for more information about obtaining &os;. Who Uses &os;? users large sites running &os; &os; is used as a platform for devices and products from many of the world's largest IT companies, including: - Apple Apple + url="http://www.apple.com/">AppleApple - Cisco Cisco + url="http://www.cisco.com/">CiscoCisco Juniper - NetApp NetApp + url="http://www.netapp.com/">NetAppNetApp &os; is also used to power some of the biggest sites on the Internet, including: - Yahoo! Yahoo! + url="http://www.yahoo.com/">Yahoo!Yahoo! - Yandex Yandex + url="http://www.yandex.ru/">YandexYandex - Apache Apache + url="http://www.apache.org/">ApacheApache - Rambler Rambler + url="http://www.rambler.ru/">RamblerRambler - Sina - Sina + SinaSina - Pair Networks - Pair Networks + url="http://www.pair.com/">Pair NetworksPair Networks - Sony Japan - Sony Japan + url="http://www.sony.co.jp/">Sony JapanSony Japan - Netcraft - Netcraft + url="http://www.netcraft.com/">NetcraftNetcraft - NetEase - NetEase + url="http://www.163.com/">NetEaseNetEase - Weathernews - Weathernews + url="http://www.weathernews.com/">WeathernewsWeathernews - TELEHOUSE America - TELEHOUSE - America + AmericaTELEHOUSE America - Experts Exchange - Experts - Exchange + ExchangeExperts Exchange and many more. About the &os; Project The following section provides some background information on the project, including a brief history, project goals, and the development model of the project. A Brief History of &os; 386BSD Patchkit Hubbard, Jordan Williams, Nate Grimes, Rod FreeBSD Project history The &os; Project had its genesis in the early part of 1993, partially as an outgrowth of the Unofficial 386BSDPatchkit by the patchkit's last 3 coordinators: Nate Williams, Rod Grimes and Jordan Hubbard. 386BSD The original goal was to produce an intermediate snapshot of 386BSD in order to fix a number of problems with it that the patchkit mechanism just was not capable of solving. The early working title for the project was 386BSD 0.5 or 386BSD Interim in reference of that fact. Jolitz, Bill 386BSD was Bill Jolitz's operating system, which had been up to that point suffering rather severely from almost a year's worth of neglect. As the patchkit swelled ever more uncomfortably with each passing day, they decided to assist Bill by providing this interim cleanup snapshot. Those plans came to a rude halt when Bill Jolitz suddenly decided to withdraw his sanction from the project without any clear indication of what would be done instead. Greenman, David Walnut Creek CDROM The trio thought that the goal remained worthwhile, even without Bill's support, and so they adopted the name "&os;" coined by David Greenman. The initial objectives were set after consulting with the system's current users and, once it became clear that the project was on the road to perhaps even becoming a reality, Jordan contacted Walnut Creek CDROM with an eye toward improving &os;'s distribution channels for those many unfortunates without easy access to the Internet. Walnut Creek CDROM not only supported the idea of distributing &os; on CD but also went so far as to provide the project with a machine to work on and a fast Internet connection. Without Walnut Creek CDROM's almost unprecedented degree of faith in what was, at the time, a completely unknown project, it is quite unlikely that &os; would have gotten as far, as fast, as it has today. 4.3BSD-Lite Net/2 U.C. Berkeley 386BSD Free Software Foundation The first CD-ROM (and general net-wide) distribution was &os; 1.0, released in December of 1993. This was based on the 4.3BSD-Lite (Net/2) tape from U.C. Berkeley, with many components also provided by 386BSD and the Free Software Foundation. It was a fairly reasonable success for a first offering, and they followed it with the highly successful &os; 1.1 release in May of 1994. Novell U.C. Berkeley Net/2 AT&T Around this time, some rather unexpected storm clouds formed on the horizon as Novell and U.C. Berkeley settled their long-running lawsuit over the legal status of the Berkeley Net/2 tape. A condition of that settlement was U.C. Berkeley's concession that large parts of Net/2 were encumbered code and the property of Novell, who had in turn acquired it from AT&T some time previously. What Berkeley got in return was Novell's blessing that the 4.4BSD-Lite release, when it was finally released, would be declared unencumbered and all existing Net/2 users would be strongly encouraged to switch. This included &os;, and the project was given until the end of July 1994 to stop shipping its own Net/2 based product. Under the terms of that agreement, the project was allowed one last release before the deadline, that release being &os; 1.1.5.1. &os; then set about the arduous task of literally re-inventing itself from a completely new and rather incomplete set of 4.4BSD-Lite bits. The Lite releases were light in part because Berkeley's CSRG had removed large chunks of code required for actually constructing a bootable running system (due to various legal requirements) and the fact that the Intel port of 4.4 was highly incomplete. It took the project until November of 1994 to make this transition, at which point it released &os; 2.0 to the net and on CD-ROM (in late December). Despite being still more than a little rough around the edges, the release was a significant success and was followed by the more robust and easier to install &os; 2.0.5 release in June of 1995. Since that time, &os; has made a series of releases each time improving the stability, speed, and feature set of the previous version. For now, long-term development projects continue to take place in the 10.X-CURRENT (trunk) branch, and snapshot releases of 10.X are continually made available from the snapshot server as work progresses. Jordan Hubbard Contributed by &os; Project Goals FreeBSD Project goals The goals of the &os; Project are to provide software that may be used for any purpose and without strings attached. Many of us have a significant investment in the code (and project) and would certainly not mind a little financial compensation now and then, but we are definitely not prepared to insist on it. We believe that our first and foremost mission is to provide code to any and all comers, and for whatever purpose, so that the code gets the widest possible use and provides the widest possible benefit. This is, I believe, one of the most fundamental goals of Free Software and one that we enthusiastically support. GNU General Public License (GPL) GNU Lesser General Public License (LGPL) BSD Copyright That code in our source tree which falls under the GNU General Public License (GPL) or Library General Public License (LGPL) comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software we do, however, prefer software submitted under the more relaxed BSD copyright when it is a reasonable option to do so. Satoshi Asami Contributed by The &os; Development Model FreeBSD Project development model The development of &os; is a very open and flexible process, being literally built from the contributions of hundreds of people around the world, as can be seen from our list of contributors. &os;'s development infrastructure allow these hundreds of developers to collaborate over the Internet. We are constantly on the lookout for new developers and ideas, and those interested in becoming more closely involved with the project need simply contact us at the &a.hackers;. The &a.announce; is also available to those wishing to make other &os; users aware of major areas of work. Useful things to know about the &os; Project and its development process, whether working independently or in close cooperation: The SVN repositories + CVS CVS Repository Concurrent Versions System CVS Subversion Subversion Repository SVN Subversion - - For several years, the central source tree for &os; + For several years, the central source tree for &os; was maintained by CVS (Concurrent Versions System), a freely available source code control tool that comes bundled with &os;. In June 2008, the Project switched to using SVN (Subversion). The switch was deemed necessary, as the technical limitations imposed by CVS were becoming obvious due to the rapid expansion of the source tree and the amount of history already stored. The Documentation Project and Ports Collection repositories also moved from CVS to SVN in May 2012 and July 2012, respectively. Please refer to the Synchronizing your source tree section for more information on obtaining the &os; src/ repository and Using the Ports Collection for details on obtaining the &os; Ports Collection. The committers list - committers - - The committers + The committerscommitters are the people who have write access to the Subversion tree, and are authorized to make modifications to the &os; source (the term committer comes from the source control commit command, which is used to bring new changes into the repository). The best way of making submissions for review by the committers list is to use the &man.send-pr.1; command. If something appears to be jammed in the system, then you may also reach them by sending mail to the &a.committers;. The FreeBSD core team - core team - - The &os; core team + The &os; core teamcore team would be equivalent to the board of directors if the &os; Project were a company. The primary task of the core team is to make sure the project, as a whole, is in good shape and is heading in the right directions. Inviting dedicated and responsible developers to join our group of committers is one of the functions of the core team, as is the recruitment of new core team members as others move on. The current core team was elected from a pool of committer candidates in July 2012. Elections are held every 2 years. Some core team members also have specific areas of responsibility, meaning that they are committed to ensuring that some large portion of the system works as advertised. For a complete list of &os; developers and their areas of responsibility, please see the Contributors List Most members of the core team are volunteers when it comes to &os; development and do not benefit from the project financially, so commitment should also not be misconstrued as meaning guaranteed support. The board of directors analogy above is not very accurate, and it may be more suitable to say that these are the people who gave up their lives in favor of &os; against their better judgement! Outside contributors - contributors - Last, but definitely not least, the largest group of developers are the users themselves who provide feedback and bug fixes to us on an almost constant basis. The primary way of keeping in touch with &os;'s more non-centralized development is to subscribe to the &a.hackers; where such things are discussed. See for more information about the various &os; mailing lists. The - &os; Contributors List is a long + &os; Contributors Listcontributors is a long and growing one, so why not join it by contributing something back to &os; today? Providing code is not the only way of contributing to the project; for a more complete list of things that need doing, please refer to the &os; Project web site. In summary, our development model is organized as a loose set of concentric circles. The centralized model is designed for the convenience of the users of &os;, who are provided with an easy way of tracking one central code base, not to keep potential contributors out! Our desire is to present a stable operating system with a large set of coherent application programs that the users can easily install and use — this model works very well in accomplishing that. All we ask of those who would join us as &os; developers is some of the same dedication its current people have to its continued success! Third Party Programs In addition to the base distributions, &os; offers a ported software collection with thousands of commonly sought-after programs. At the time of this writing, there were over &os.numports; ports! The list of ports ranges from http servers, to games, languages, editors, and almost everything in between. The entire Ports Collection requires approximately &ports.size;. To compile a port, you simply change to the directory of the program you wish to install, type make install, and let the system do the rest. The full original distribution for each port you build is retrieved dynamically so you need only enough disk space to build the ports you want. Almost every port is also provided as a pre-compiled package, which can be installed with a simple command (pkg_add) by those who do not wish to compile their own ports from source. More information on packages and ports can be found in . Additional Documentation All recent &os; versions provide an option in the installer (either &man.sysinstall.8; or &man.bsdinstall.8;) to install additional documentation under /usr/local/share/doc/freebsd during the initial system setup. Documentation may also be installed at any later time using packages as described in . You may view the locally installed manuals with any HTML capable browser using the following URLs: The FreeBSD Handbook /usr/local/share/doc/freebsd/handbook/index.html The FreeBSD FAQ /usr/local/share/doc/freebsd/faq/index.html You can also view the master (and most frequently updated) copies at . diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.xml b/en_US.ISO8859-1/books/handbook/l10n/chapter.xml index 1fbe10fc99..1b4b618de7 100644 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.xml @@ -1,975 +1,974 @@ Andrey Chernov Contributed by Michael C. Wu Rewritten by Localization - <acronym>i18n</acronym>/<acronym>L10n</acronym> Usage and Setup Synopsis &os; is a distributed project with users and contributors located all over the world. This chapter discusses the internationalization and localization features of &os; that allow non-English speaking users to get real work done. Since there are many aspects of the i18n implementation in both the system and application levels, more specific sources of documentation are referred to, where applicable. After reading this chapter, you will know: How different languages and locales are encoded on modern operating systems. How to set the locale for a login shell. How to configure the console for non-English languages. How to use Xorgeffectively with different languages. Where to find more information about writing i18n-compliant applications. Before reading this chapter, you should: Know how to install additional third-party applications. The Basics What Is <acronym>i18n</acronym>/<acronym>L10n</acronym>? internationalization localization localization The term internationalization has been shortened to i18n, which represents the number of letters between the first and the last letters of internationalization. L10n uses the same naming scheme, coming from localization. Combined together, i18n/L10n methods, protocols, and applications allow users to use languages of their choice. i18n applications are programmed using i18n kits under libraries. These allow developers to write a simple file and translate displayed menus and texts to each language. Why Use <acronym>i18n</acronym>/<acronym>L10n</acronym>? Using i18n/L10n allows a user to view, input, or process data in non-English languages. Which Languages Are Supported? i18n and L10n are not &os; specific. Currently, one can choose from most of the major languages, including but not limited to: Chinese, German, Japanese, Korean, French, Russian, and Vietnamese. Using Localization locale Localization settings are based on three main terms: Language Code, Country Code, and Encoding. Locale names are constructed from these parts as follows: LanguageCode_CountryCode.Encoding Language and Country Codes language codes country codes In order to localize a &os; system to a specific language, the user needs to determine the codes for the specific country and language as the country code tells applications which variation of the given language to use. The following are examples of language/country codes: Language/Country Code Description en_US English - United States ru_RU Russian for Russia zh_TW Traditional Chinese for Taiwan A complete listing of available locales can be found by typing: &prompt.user; locale -a Encodings encodings ASCII Some languages use non-ASCII encodings that are 8-bit, wide, or multibyte characters. For more information on these encodings, refer to &man.multibyte.3;. Older applications do not recognize these encodings and mistake them for control characters. Newer applications usually recognize 8-bit characters. Depending on the implementation, users may be required to compile an application with wide or multibyte character support, or configure it correctly. To provide application support for wide or multibyte characters, the &os; Ports Collection contains programs for several languages. Refer to the i18n documentation in the respective &os; port. Specifically, the user needs to look at the application documentation to decide how to configure it correctly or to determine which compile options to use when building the port. Some things to keep in mind are: Language specific single C chars character sets such as ISO8859-1, ISO8859-15, KOI8-R, and CP437. These are described in &man.multibyte.3;. Wide or multibyte encodings such as EUC and Big5. The active list of character sets can be found at the IANA Registry. &os; uses Xorg-compatible locale encodings instead. In the &os; Ports Collection, i18n applications include i18n in their names for easy identification. However, they do not always support the language needed. Setting Locale Usually it is sufficient to export the value of the locale name as LANG in the login shell. This could be done in the user's ~/.login_conf or in the startup file of the user's shell: (~/.profile, ~/.bashrc, or ~/.cshrc). There is no need to set the locale subsets such as LC_CTYPE or LC_CTIME. Refer to language-specific &os; documentation for more information. Each user should set the following two environment variables in their configuration files: - POSIX - LANG for &posix; &man.setlocale.3; + LANG for &posix;POSIX &man.setlocale.3; family functions MIME MM_CHARSET for applications' MIME character set These should be set in the user's shell configuration, the specific application configuration, and the Xorg configuration. Setting Locale Methods locale login class This section describes the two methods for setting locale. The first is recommended and assigns the environment variables in the login class. The second method adds the environment variable assignments to the system's shell startup file. Login Classes Method This method allows environment variables needed for locale name and MIME character sets to be assigned once for every possible shell instead of adding specific shell assignments to each shell's startup file. User Level Setup can be performed by each user while Administrator Level Setup requires superuser privileges. User Level Setup This provides a minimal example of a .login_conf located in a user's home directory which has both variables set for the Latin-1 encoding: me:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1: Traditional Chinese BIG-5 encoding Here is an example of a user's .login_conf that sets the variables for Traditional Chinese in BIG-5 encoding. More variables are set because some applications do not correctly respect locale variables for Chinese, Japanese, and Korean. #Users who do not wish to use monetary units or time formats #of Taiwan can manually change each variable me:\ :lang=zh_TW.Big5:\ :setenv=LC_ALL=zh_TW.Big5:\ :setenv=LC_COLLATE=zh_TW.Big5:\ :setenv=LC_CTYPE=zh_TW.Big5:\ :setenv=LC_MESSAGES=zh_TW.Big5:\ :setenv=LC_MONETARY=zh_TW.Big5:\ :setenv=LC_NUMERIC=zh_TW.Big5:\ :setenv=LC_TIME=zh_TW.Big5:\ :charset=big5:\ :xmodifiers="@im=gcin": #Set gcin as the XIM Input Server See Administrator Level Setup and &man.login.conf.5; for more details. Administrator Level Setup Verify that the user's login class in /etc/login.conf sets the correct language: language_name|Account Type Description:\ :charset=MIME_charset:\ :lang=locale_name:\ :tc=default: The previous Latin-1 example would look like this: german|German Users Accounts:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1:\ :tc=default: Whenever this file is edited, execute the following command to update the capability database: &prompt.root; cap_mkdb /etc/login.conf Changing Login Classes with &man.vipw.8; vipw When using vipw to add new users, use language to set the language: user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh Changing Login Classes with &man.adduser.8; adduser login class When using adduser to add new users, configure the language as follows: If all new users use the same language, set defaultclass = language in /etc/adduser.conf. Alternatively, input the specified language at this prompt: Enter login class: default []: when creating a new user using &man.adduser.8;. Another alternative is to use the following when creating a user that uses a different language than the one set in /etc/adduser.conf: &prompt.root; adduser -class language Changing Login Classes with &man.pw.8; pw If &man.pw.8; is used to add new users, call it in this form: &prompt.root; pw useradd user_name -L language Shell Startup File Method This method is not recommended because it requires a different setup for each shell. Use the Login Class Method instead. MIME locale To add the locale name and MIME character set, set the two environment variables shown below in the /etc/profile or /etc/csh.login shell startup files. This example sets the German language: In /etc/profile: LANG=de_DE.ISO8859-1; export LANG MM_CHARSET=ISO-8859-1; export MM_CHARSET Or in /etc/csh.login: setenv LANG de_DE.ISO8859-1 setenv MM_CHARSET ISO-8859-1 Alternatively, add the above settings to /usr/share/skel/dot.profile or /usr/share/skel/dot.login. To configure Xorg, add one of the following to ~/.xinitrc, depending upon the shell: LANG=de_DE.ISO8859-1; export LANG setenv LANG de_DE.ISO8859-1 Console Setup For all single C chars character sets, set the correct console fonts in /etc/rc.conf for the language in question with: font8x16=font_name font8x14=font_name font8x8=font_name The font_name is taken from /usr/share/syscons/fonts, without the .fnt suffix. sysinstall keymap screenmap The keymap and screenmap for the single C chars character set can be set using sysinstall. Once inside sysinstall, choose Configure, then Console. Alternatively, add the following to /etc/rc.conf: scrnmap=screenmap_name keymap=keymap_name keychange="fkey_number sequence" The screenmap_name is taken from /usr/share/syscons/scrnmaps, without the .scm suffix. A screenmap with a corresponding mapped font is usually needed as a workaround for expanding bit 8 to bit 9 on a VGA adapter's font character matrix. This will move letters out of the pseudographics area if the screen font uses a bit 8 column. If moused is enabled in /etc/rc.conf, review the mouse cursor information in the next paragraph. moused By default, the mouse cursor of the &man.syscons.4; driver occupies the 0xd0-0xd3 range in the character set. If the language uses this range, move the cursor's range. To enable this workaround for &os;, add the following line to /etc/rc.conf: mousechar_start=3 The keymap_name in the above example is taken from /usr/share/syscons/keymaps, without the .kbd suffix. When uncertain as to which keymap to use, &man.kbdmap.1; can be used to test keymaps without rebooting. The keychange is usually needed to program function keys to match the selected terminal type because function key sequences cannot be defined in the key map. Be sure to set the correct console terminal type in /etc/ttys for all virtual terminal entries. Current pre-defined correspondences are: Character Set Terminal Type ISO8859-1 or ISO8859-15 cons25l1 ISO8859-2 cons25l2 ISO8859-7 cons25l7 KOI8-R cons25r KOI8-U cons25u CP437 (VGA default) cons25 US-ASCII cons25w For languages with wide or multibyte characters, use the correct &os; port in /usr/ports/language. Some applications appear as serial terminals to the system. Reserve enough terminals in /etc/ttys for both Xorg and the pseudo-serial console. Here is a partial list of applications for using other languages in the console: Language Location Traditional Chinese (BIG-5) chinese/big5con Japanese japanese/kon2-16dot or japanese/mule-freewnn Korean korean/han Xorg Setup Although Xorg is not installed with &os;, it can be installed from the Ports Collection. Refer to for more information on how to do this. This section discusses how to localize Xorg once it is installed. Application specific i18n settings such as fonts and menus can be tuned in ~/.Xresources. Displaying Fonts Xorg True Type font server After installing x11-servers/xorg-server, install the language's &truetype; fonts. Setting the correct locale should allow users to view their selected language in graphical application menus. Inputting Non-English Characters X Input Method (XIM) The X Input Method (XIM) protocol is an input standard for Xorg clients. All Xorg applications should be written as XIM clients that take input from XIM input servers. There are several XIM servers available for different languages. Printer Setup Some single C chars character sets are hardware coded into printers. Wide or multibyte character sets require special setup using a utility such as apsfilter. Documents can be converted to &postscript; or PDF formats using language specific converters. Kernel and File Systems The &os; fast filesystem (FFS) is 8-bit clean, so it can be used with any single C chars character set. However, character set names are not stored in the filesystem as it is raw 8-bit and does not understand encoding order. Officially, FFS does not support any form of wide or multibyte character sets. However, some wide or multibyte character sets have independent patches for enabling support on FFS. Refer to the respective languages' web sites for more information and the patch files. DOS Unicode &os;'s support for the &ms-dos; filesystem has the configurable ability to convert between &ms-dos;, Unicode character sets, and chosen &os; filesystem character sets. Refer to &man.mount.msdosfs.8; for details. Compiling <acronym>i18n</acronym> Programs Many applications in the &os; Ports Collection have been ported with i18n support. Some of these include -i18n in the port name. These and many other programs have built in support for i18n and need no special consideration. MySQL However, some applications such as MySQL need to have their Makefile configured with the specific charset. This is usually done in the port's Makefile or by passing a value to configure in the source. Localizing &os; to Specific Languages Andrey Chernov Originally contributed by Russian Language (KOI8-R Encoding) localization Russian For more information about KOI8-R encoding, refer to KOI8-R References (Russian Net Character Set). Locale Setup To set this locale, put the following lines into each user's ~/.login_conf: me:My Account:\ :charset=KOI8-R:\ :lang=ru_RU.KOI8-R: Console Setup Add the following lines to /etc/rc.conf: keymap="ru.koi8-r" scrnmap="koi8-r2cp866" font8x16="cp866b-8x16" font8x14="cp866-8x14" font8x8="cp866-8x8" mousechar_start=3 For each ttyv entry in /etc/ttys, use cons25r as the terminal type. Printer Setup printers Since most printers with Russian characters come with hardware code page CP866, a special output filter is needed to convert from KOI8-R to CP866. &os; installs a default filter as /usr/libexec/lpr/ru/koi2alt. A Russian printer /etc/printcap entry should look like: lp|Russian local line printer:\ :sh:of=/usr/libexec/lpr/ru/koi2alt:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: Refer to &man.printcap.5; for a more detailed description. &ms-dos; and Russian Filenames The following example &man.fstab.5; entry enables support for Russian filenames in mounted &ms-dos; filesystems: /dev/ad0s2 /dos/c msdos rw,-Lru_RU.KOI8-R 0 0 selects the locale name. Refer to &man.mount.msdosfs.8; for more details. <application>Xorg</application> Setup First, configure the non-X locale setup. When using &xorg;, install the x11-fonts/xorg-fonts-cyrillic package. Check the "Files" section in /etc/X11/xorg.conf. The following line must be added before any other FontPath entries: FontPath "/usr/local/lib/X11/fonts/cyrillic" Search the Ports Collection for more Cyrillic fonts. To activate a Russian keyboard, add the following to the "Keyboard" section of /etc/xorg.conf: Option "XkbLayout" "us,ru" Option "XkbOptions" "grp:toggle" Make sure that XkbDisable is commented out in that file. For grp:toggle use Right Alt, for grp:ctrl_shift_toggle use CtrlShift. For grp:caps_toggle use CapsLock. The old CapsLock function is still available in LAT mode only using ShiftCapsLock. grp:caps_toggle does not work in &xorg; for some unknown reason. If the keyboard has &windows; keys, and some non-alphabetical keys are mapped incorrectly, add the following line to /etc/xorg.conf: Option "XkbVariant" ",winkeys" The Russian XKB keyboard may not work with non-localized applications. Minimally localized applications should call a XtSetLanguageProc (NULL, NULL, NULL); function early in the program. See KOI8-R for X Window for more instructions on localizing Xorg applications. Traditional Chinese Localization for Taiwan localization Traditional Chinese The &os;-Taiwan Project has a Chinese HOWTO for &os; at using many Chinese ports. The current editor for the &os; Chinese HOWTO is Shen Chuan-Hsing statue@freebsd.sinica.edu.tw. German Language Localization for All ISO 8859-1 Languages localization German Slaven Rezic eserte@cs.tu-berlin.de wrote a tutorial on using umlauts on &os;. The tutorial is written in German and is available at . Greek Language Localization localization Greek Nikos Kokkalis nickkokkalis@gmail.com has written a complete article on Greek support in &os;. It is available here, in Greek only, as part of the official &os; Greek documentation. Japanese and Korean Language Localization localization Japanese localization Korean For Japanese, refer to , and for Korean, refer to . Non-English &os; Documentation Some &os; contributors have translated parts of the &os; documentation to other languages. They are available through links on the main site or in /usr/share/doc. diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.xml b/en_US.ISO8859-1/books/handbook/mail/chapter.xml index 12ff246e7b..6a5a690e83 100644 --- a/en_US.ISO8859-1/books/handbook/mail/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/mail/chapter.xml @@ -1,2100 +1,2099 @@ Bill Lloyd Original work by Jim Mock Rewritten by Electronic Mail Synopsis email Electronic Mail, better known as email, is one of the most widely used forms of communication today. This chapter provides a basic introduction to running a mail server on &os;, as well as an introduction to sending and receiving email using &os;. For more complete coverage of this subject, refer to the books listed in . After reading this chapter, you will know: Which software components are involved in sending and receiving electronic mail. Where basic sendmail configuration files are located in &os;. The difference between remote and local mailboxes. How to block spammers from illegally using a mail server as a relay. How to install and configure an alternate Mail Transfer Agent, replacing sendmail. How to troubleshoot common mail server problems. How to set up the system to send mail only. How to use mail with a dialup connection. How to configure SMTP authentication for added security. How to install and use a Mail User Agent, such as mutt, to send and receive email. How to download mail from a remote POP or IMAP server. How to automatically apply filters and rules to incoming email. Before reading this chapter, you should: Properly set up a network connection (). Properly set up the DNS information for a mail host (). Know how to install additional third-party software (). Using Electronic Mail POP IMAP DNS There are five major parts involved in an email exchange: the Mail User Agent MUA>, the Mail Transfer AgentMTA, DNS, a remote or local mailbox, and the mail host. The Mail User Agent This includes command line programs such as mutt, alpine, elm, and mail, GUI programs such as balsa or xfmail, and web mail programs which can be accessed from a web browser. User programs pass the email transactions to the local mail host, either by a MTA, or by delivering it over TCP. The Mail Transfer Agent mail server daemons Sendmail mail server daemons Postfix mail server daemons qmail mail server daemons Exim &os; ships with Sendmail as the default MTA, but it also supports numerous other mail server daemons, including: Exim; Postfix; qmail. The MTA usually has two functions. It is responsible for receiving incoming mail as well as delivering outgoing mail. It is not responsible for the collection of mail using protocols such as POP or IMAP, nor does it allow connecting to local mbox or Maildir mailboxes. An additional daemon may be required for these functions. Older versions of Sendmail contain serious security issues which may result in an attacker gaining local or remote access to the system. Run a current version to &os; to avoid these problems. Optionally, install an alternative MTA from the &os; Ports Collection. Email and DNS The Domain Name System (DNS) and its daemon named play a large role in the delivery of email. In order to deliver mail from one site to another, the MTA will look up the remote site in DNS to determine which host will receive mail for the destination. This process also occurs when mail is sent from a remote host to the MTA. MX record DNS is responsible for mapping hostnames to IP addresses, as well as for storing information specific to mail delivery, known as Mail eXchanger MX records. The MX record specifies which host, or hosts, will receive mail for a particular domain. If there is no MX record for the hostname or domain, the mail will be delivered directly to the host, provided there is an A record pointing the hostname to the IP address. To view the MX records for a domain, specify the type of record using &man.host.1;, as seen in the example below: &prompt.user; host -t mx FreeBSD.org FreeBSD.org mail is handled by 10 mx1.FreeBSD.org Receiving Mail email receiving Receiving mail for a domain is done by the mail host. It will collect all mail sent to the domain and store it either in the default mbox or the alternative Maildir format, depending on the configuration. Once mail has been stored, it may either be read locally using a MUA, or remotely accessed and collected using protocols such as POP or IMAP. In order to read mail locally, a POP or IMAP server does not need to be installed. Accessing Remote Mailboxes Using <acronym>POP</acronym> and <acronym>IMAP</acronym> POP IMAP To access mailboxes remotely, access to a POP or IMAP server is required. These protocols allow users to connect to their mailboxes from remote locations. Though both POP and IMAP allow users to remotely access mailboxes, IMAP offers many advantages, including: IMAP can store messages on a remote server as well as fetch them. IMAP supports concurrent updates. IMAP can be useful over low-speed links as it allows users to fetch the structure of messages without downloading them. It can also perform tasks such as searching on the server in order to minimize data transfer between clients and servers. In order to install a POP or IMAP server, the following steps should be performed: Use the Ports Collection to install an IMAP or POP server. The following POP and IMAP servers are well known: mail/qpopper mail/teapop mail/imap-uw mail/courier-imap mail/dovecot2 Where required, use the startup script that came with the application to load the POP or IMAP server. Those programs will also provide a variable which can be added to /etc/rc.conf to automate the startup of the application's daemon whenever the system boots. It should be noted that both POP and IMAP transmit information, including username and password credentials, in clear-text. To secure the transmission of information across these protocols, consider tunneling sessions over &man.ssh.1; () or using SSL (). Accessing Local Mailboxes Mailboxes may be accessed locally by directly using an MUA on the server on which the mailbox resides. This can be done using a built-in application such as &man.mail.1; or by installing a MUA from the Ports Collection.. The Mail Host mail host The mail host is a server that is responsible for delivering and receiving mail for a host, or a network. Christopher Shumway Contributed by <application>Sendmail</application> Configuration Sendmail &man.sendmail.8; is the default MTA which is installed with &os;. Sendmail accepts mail from MUAs and delivers it to the appropriate mailer as defined by its configuration file. Sendmail can also accept network connections and deliver mail to local mailboxes or to another program. Sendmail uses the following configuration files. This section describes these files in more detail. /etc/mail/access /etc/mail/aliases /etc/mail/local-host-names /etc/mail/mailer.conf /etc/mail/mailertable /etc/mail/sendmail.cf /etc/mail/virtusertable Filename Function /etc/mail/access Sendmail access database file. /etc/mail/aliases Mailbox aliases /etc/mail/local-host-names Lists of hosts Sendmail accepts mail for. /etc/mail/mailer.conf Mailer program configuration. /etc/mail/mailertable Mailer delivery table. /etc/mail/sendmail.cf Sendmail master configuration file. /etc/mail/virtusertable Virtual users and domain tables. <filename>/etc/mail/access</filename> This database defines which host(s) or IP addresses have access to the local mail server and what kind of access they have. Hosts can be listed as , , or , or can be passed to Sendmail's error handling routine with a given mailer error. Hosts that are listed as , which is the default option, are allowed to send mail to this host as long as the mail's final destination is the local machine. Hosts that are listed as are rejected for all mail connections. Hosts that are listed as are allowed to send mail for any destination using this mail server. Configuring the <application>Sendmail</application> Access Database cyberspammer.com 550 We do not accept mail from spammers FREE.STEALTH.MAILER@ 550 We do not accept mail from spammers another.source.of.spam REJECT okay.cyberspammer.com OK 128.32 RELAY This example shows five entries. Mail senders that match the left side of the table are affected by the action on the right side of the table. The first two examples give an error code to Sendmail's error handling routine. The message is sent to the remote host when a mail matches the left side of the table. The third entry rejects mail from a specific host on the Internet, another.source.of.spam. The fourth entry accepts mail connections from okay.cyberspammer.com, which is more specific than the cyberspammer.com line above. More specific matches override less exact matches. The last entry allows relaying of email from hosts with an IP address that begins with 128.32. These hosts can send mail through this mail server that is destined for other mail servers. Whenever this file is updated, run make in /etc/mail/ to update the database. <filename>/etc/mail/aliases</filename> This database contains a list of virtual mailboxes that are expanded to other user(s), files, programs, or other aliases. Here are a few examples to illustrate the file format: Mail Aliases root: localuser ftp-bugs: joe,eric,paul bit.bucket: /dev/null procmail: "|/usr/local/bin/procmail" The mailbox name on the left side of the colon is expanded to the target(s) on the right. The first entry expands the mailbox root to the mailbox localuser, which is then looked up again in the aliases database. If no match is found, the message is delivered to localuser. The second entry shows a mail list. Mail to the mailbox ftp-bugs is expanded to the three local mailboxes joe, eric, and paul. A remote mailbox could be specified as user@example.com. The third entry shows how to write mail to a file, in this case /dev/null. The last entry demonstrates how to send mail to a program, /usr/local/bin/procmail, through a &unix; pipe. Whenever this file is updated, run make in /etc/mail/ to update the database. <filename>/etc/mail/local-host-names</filename> This is a list of hostnames &man.sendmail.8; is to accept as the local host name. Place any domains or hosts that Sendmail will receive mail for. For example, to configure a mail server to accept mail for the domain example.com and the host mail.example.com, add these entries to local-host-names: example.com mail.example.com Whenever this file is updated, &man.sendmail.8; needs to be restarted so that it will read the changes. <filename>/etc/mail/sendmail.cf</filename> This is the master configuration file for Sendmail. It controls the overall behavior of Sendmail, including everything from rewriting email addresses to printing rejection messages to remote mail servers. Accordingly, this configuration file is quite complex. Fortunately, this file rarely needs to be changed for standard mail servers. The master Sendmail configuration file can be built from &man.m4.1; macros that define the features and behavior of Sendmail. Refer to /usr/src/contrib/sendmail/cf/README for some of the details. Whenever changes to this file are made, Sendmail needs to be restarted for the changes to take effect. <filename>/etc/mail/virtusertable</filename> The virtusertable maps mail addresses for virtual domains and mailboxes to real mailboxes. These mailboxes can be local, remote, aliases defined in /etc/mail/aliases, or files. Example Virtual Domain Mail Map root@example.com root postmaster@example.com postmaster@noc.example.net @example.com joe The above example contains a mapping for the domain example.com. This file is processed in a first match order. The first item maps root@example.com to the local mailbox root. The second entry maps postmaster@example.com to the mailbox postmaster on the host noc.example.net. Finally, if nothing from example.com has matched so far, it will match the last mapping, which matches every other mail message addressed to someone at example.com to the local mailbox joe. Andrew Boothman Written by Gregory Neil Shapiro Information taken from emails written by Changing the Mail Transfer Agent email change mta &os; comes with Sendmail already installed as the MTA which is in charge of outgoing and incoming mail. However, the system administrator can change the system's MTA. The reasons for doing so range from wanting to try out another MTA to needing a specific feature or package which relies on another MTA. Whatever the reason, &os; makes it easy to make the change. Install a New <acronym>MTA</acronym> A wide choice of MTAs is available from the mail category of the &os; Ports Collection. Once a new MTA is installed, configure the new software and decide if it really fulfills your needs before replacing Sendmail. Refer to the new chosen MTA's documentation for information on how to configure the software. Disable <application>Sendmail</application> If Sendmail's outgoing mail service is disabled, it is important that it is replaced with an alternative mail delivery system. Otherwise, system functions such as &man.periodic.8; will be unable to deliver their results by email. Many parts of the system expect a functional MTA. If applications continue to use Sendmail's binaries to try to send email they are disabled, mail could go into an inactive Sendmail queue, and never be delivered. In order to completely disable Sendmail, including the outgoing mail service, add or edit the following lines in /etc/rc.conf: sendmail_enable="NO" sendmail_submit_enable="NO" sendmail_outbound_enable="NO" sendmail_msp_queue_enable="NO" To only disable Sendmail's incoming mail service, set sendmail_enable="NO" in /etc/rc.conf. More information on Sendmail's startup options is available in &man.rc.sendmail.8;. Running the New <acronym>MTA</acronym> on Boot The new MTA can be started during boot by adding a configuration line to /etc/rc.conf. This example enables the Postfix MTA: &prompt.root; echo 'postfix_enable=YES' >> /etc/rc.conf The specified MTA will now be automatically started during boot. Replacing <application>Sendmail</application> as the System's Default Mailer Sendmail is so ubiquitous as standard software on &unix; systems that some software assumes it is already installed and configured. For this reason, many alternative MTAs provide their own compatible implementations of the Sendmail command-line interface in order to facilitate using them as drop-in replacements for Sendmail. When using an alternative MTA, make sure that software trying to execute standard Sendmail binaries, such as /usr/bin/sendmail, actually execute the chosen mailer instead. Fortunately, &os; provides a system called &man.mailwrapper.8; for this purpose. When Sendmail is operating as installed, /etc/mail/mailer.conf will look like this: sendmail /usr/libexec/sendmail/sendmail send-mail /usr/libexec/sendmail/sendmail mailq /usr/libexec/sendmail/sendmail newaliases /usr/libexec/sendmail/sendmail hoststat /usr/libexec/sendmail/sendmail purgestat /usr/libexec/sendmail/sendmail When any of the commands listed on the left are run, the system actually executes the associated command shown on the right instead. This system makes it easy to change what binaries are executed when these default Sendmail functions are invoked. As an example, to run /usr/local/supermailer/bin/sendmail-compat instead of Sendmail, specify the paths to the installed applications in /etc/mail/mailer.conf: sendmail /usr/local/supermailer/bin/sendmail-compat send-mail /usr/local/supermailer/bin/sendmail-compat mailq /usr/local/supermailer/bin/mailq-compat newaliases /usr/local/supermailer/bin/newaliases-compat hoststat /usr/local/supermailer/bin/hoststat-compat purgestat /usr/local/supermailer/bin/purgestat-compat Finishing Once everything is configured, either kill the unneeded sendmail processes and start the processes belonging to the new software, or reboot. Rebooting provides the opportunity to ensure that the system is correctly configured to start the new MTA automatically on boot. Troubleshooting email troubleshooting Why do I have to use the FQDN for hosts on my site? The host may actually be in a different domain. For example, in order for a host in foo.bar.edu to reach a host called mumble in the bar.edu domain, refer to it by the Fully-Qualified Domain Name FQDN, mumble.bar.edu, instead of just mumble. This is because the version of BIND BIND which ships with &os; no longer provides default abbreviations for non-FQDNs other than the local domain. An unqualified host such as mumble must either be found as mumble.foo.bar.edu, or it will be searched for in the root domain. In older versions of BIND, the search continued across mumble.bar.edu, and mumble.edu. RFC 1535 details why this is considered bad practice or even a security hole. As a good workaround, place the line: search foo.bar.edu bar.edu instead of the previous: domain foo.bar.edu into /etc/resolv.conf. However, make sure that the search order does not go beyond the boundary between local and public administration, as RFC 1535 calls it. Sendmail says mail loops back to myself. This is answered in the Sendmail FAQ as follows. This FAQ is recommended reading when tweaking the mail setup. I'm getting these error messages: 553 MX list for domain.net points back to relay.domain.net 554 <user@domain.net>... Local configuration error How can I solve this problem? You have asked mail to the domain (e.g., domain.net) to be forwarded to a specific host (in this case, relay.domain.net) by using an MX record, but the relay machine does not recognize itself as domain.net. Add domain.net to /etc/mail/local-host-names [known as /etc/sendmail.cw prior to version 8.10] (if you are using FEATURE(use_cw_file)) or add Cw domain.net to /etc/mail/sendmail.cf. How can I run a mail server on a dial-up PPP host? Connect to a &os; mail gateway on the LAN. The PPP connection is non-dedicated. One way to do this is to get a full-time Internet server to provide secondary MX MX record services for the domain. In this example, the domain is example.com and the ISP has configured example.net to provide secondary MX services to the domain: example.com. MX 10 example.com. MX 20 example.net. Only one host should be specified as the final recipient. For Sendmail, add Cw example.com in /etc/mail/sendmail.cf on example.com. When the sending MTA attempts to deliver mail, it will try to connect to the system, example.com, over the PPP link. This will time out if the destination is offline. The MTA will automatically deliver it to the secondary MX site at the Internet Service Provider (ISP), example.net. The secondary MX site will periodically try to connect to the primary MX host, example.com. Use something like this as a login script: #!/bin/sh # Put me in /usr/local/bin/pppmyisp ( sleep 60 ; /usr/sbin/sendmail -q ) & /usr/sbin/ppp -direct pppmyisp When creating a separate login script for users, instead use sendmail -qRexample.com in the script above. This will force all mail in the queue for example.com to be processed immediately. A further refinement of the situation can be seen from this example from the &a.isp;: > we provide the secondary MX for a customer. The customer connects to > our services several times a day automatically to get the mails to > his primary MX (We do not call his site when a mail for his domains > arrived). Our sendmail sends the mailqueue every 30 minutes. At the > moment he has to stay 30 minutes online to be sure that all mail is > gone to the primary MX. > > Is there a command that would initiate sendmail to send all the mails > now? The user has not root-privileges on our machine of course. In the privacy flags section of sendmail.cf, there is a definition Opgoaway,restrictqrun Remove restrictqrun to allow non-root users to start the queue processing. You might also like to rearrange the MXs. We are the 1st MX for our customers like this, and we have defined: # If we are the best MX for a host, try directly instead of generating # local config error. OwTrue That way a remote site will deliver straight to you, without trying the customer connection. You then send to your customer. Only works for hosts, so you need to get your customer to name their mail machine customer.com as well as hostname.customer.com in the DNS. Just put an A record in the DNS for customer.com. Why do I keep getting Relaying Denied errors when sending mail from other hosts? In a default &os; installation, Sendmail is configured to only send mail from the host it is running on. For example, if a POP server is available, users will be able to check mail from remote locations but they will not be able to send outgoing emails from outside locations. Typically, a few moments after the attempt, an email will be sent from MAILER-DAEMON with a 5.7 Relaying Denied. The most straightforward solution is to add the ISP's FQDN to /etc/mail/relay-domains, as seen in this example: &prompt.root; echo "your.isp.example.com" > /etc/mail/relay-domains After creating or editing this file, restart Sendmail. This works great if the server administrator does not wish to send mail locally, would like to use a MUA on a remote machine, or would like to use another ISP for remote connections. It is also useful when there is only one or two email accounts. If there are a large number of addresses, add them one per line: your.isp.example.com other.isp.example.net users-isp.example.org www.example.org Now any mail sent through the system by any host in this list, provided the user has an account on the system, will succeed. This allows users to send mail from the system remotely without opening the system up to relaying SPAM from the Internet. Advanced Topics This section covers more involved topics such as mail configuration and setting up mail for an entire domain. Basic Configuration email configuration Out of the box, one can send email to external hosts as long as /etc/resolv.conf is configured or the network has access to a configured DNS server. If order to have mail delivered to the MTA on the &os; host, do one of the following: Run a DNS server for the domain. Get mail delivered directly to to the FQDN for the machine. SMTP In order to have mail delivered directly to a host, it must have a permanent static IP address, not a dynamic IP address. If the system is behind a firewall, it must be configured to allow SMTP traffic. To receive mail directly at a host, one of these two must be configured: - MX record Make sure that the lowest-numbered - MX record in + MXMX record record in DNS points to the host's static IP address. Make sure there is no MX entry in the DNS for the host. Either of the above will allow mail to be received directly at the host. Try this: &prompt.root; hostname example.FreeBSD.org &prompt.root; host example.FreeBSD.org example.FreeBSD.org has address 204.216.27.XX In this example, mail sent directly to yourlogin@example.FreeBSD.org should work without problems, assuming Sendmail is running correctly on example.FreeBSD.org. For this example: &prompt.root; host example.FreeBSD.org example.FreeBSD.org has address 204.216.27.XX example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org All mail sent to example.FreeBSD.org will be collected on hub under the same username instead of being sent directly to your host. The above information is handled by the DNS server. The DNS record that carries mail routing information is the MX entry. If no MX record exists, mail will be delivered directly to the host by way of its IP address. The MX entry for freefall.FreeBSD.org at one time looked like this: freefall MX 30 mail.crl.net freefall MX 40 agora.rdrop.com freefall MX 10 freefall.FreeBSD.org freefall MX 20 who.cdrom.com freefall had many MX entries. The lowest MX number is the host that receives mail directly, if available. If it is not accessible for some reason, the next lower-numbered host will accept messages temporarily, and pass it along when a lower-numbered host becomes available. Alternate MX sites should have separate Internet connections in order to be most useful. Your ISP can provide this service. Mail for a Domain When configuring a MTA for a network, any mail sent to hosts in its domain should be diverted to the MTA so that users can receive their mail on the master mail server. DNS To make life easiest, a user account with the same username should exist on both the MTA and the system with the MUA. Use &man.adduser.8; to create the user accounts. The MTA must be the designated mail exchanger for each workstation on the network. This is done in theDNS configuration with an MX record: example.FreeBSD.org A 204.216.27.XX ; Workstation MX 10 hub.FreeBSD.org ; Mailhost This will redirect mail for the workstation to the MTA no matter where the A record points. The mail is sent to the MX host. This must be configured on a DNS server. If the network does not run its own DNS server, talk to the ISP or DNS provider. The following is an example of virtual email hosting. Consider a customer with the domain customer1.org, where all the mail for customer1.org should be sent to mail.myhost.com. The DNS entry should look like this: customer1.org MX 10 mail.myhost.com An A> record is not needed for customer1.org in order to only handle email for that domain. However, running ping against customer1.org will not work unless an A record exists for it. Tell the MTA which domains and/or hostnames it should accept mail for. Either of the following will work for Sendmail: Add the hosts to /etc/mail/local-host-names when using the FEATURE(use_cw_file). For versions of Sendmail earlier than 8.10, edit /etc/sendmail.cw instead. Add a Cwyour.host.com line to /etc/sendmail.cf. For Sendmail 8.10 or higher, add that line to /etc/mail/sendmail.cf. Bill Moran Contributed by Setting Up to Send Only There are many instances where one may only want to send mail through a relay. Some examples are: The computer is a desktop machine that needs to use programs such as &man.send-pr.1;, using the ISP's mail relay. The computer is a server that does not handle mail locally, but needs to pass off all mail to a relay for processing. While any MTA is capable of filling this particular niche, it can be difficult to properly configure a full-featured MTA just to handle offloading mail. Programs such as Sendmail and Postfix are overkill for this use. Additionally, a typical Internet access service agreement may forbid one from running a mail server. The easiest way to fulfill those needs is to install the mail/ssmtp port: &prompt.root; cd /usr/ports/mail/ssmtp &prompt.root; make install replace clean Once installed, mail/ssmtp can be configured with /usr/local/etc/ssmtp/ssmtp.conf: root=yourrealemail@example.com mailhub=mail.example.com rewriteDomain=example.com hostname=_HOSTNAME_ Use the real email address for root. Enter the ISP's outgoing mail relay in place of mail.example.com. Some ISPs call this the outgoing mail server or SMTP server). Make sure to disable Sendmail, including the outgoing mail service. See for details. mail/ssmtp has some other options available. Refer to the examples in /usr/local/etc/ssmtp or the manual page of ssmtp for more information. Setting up ssmtp in this manner allows any software on the computer that needs to send mail to function properly, while not violating the ISP's usage policy or allowing the computer to be hijacked for spamming. Using Mail with a Dialup Connection When using a static IP address, one should not need to adjust the default configuration. Set the hostname to the assigned Internet name and Sendmail will do the rest. When using a dynamically assigned IP address and a dialup PPP connection to the Internet, one usually has a mailbox on the ISP's mail server. In this example, the ISP's domain is example.net, the user name is user, the hostname is bsd.home, and the ISP has allowed relay.example.net as a mail relay. In order to retrieve mail from the ISP's mailbox, install a retrieval agent from the Ports Collection. mail/fetchmail is a good choice as it supports many different protocols. Usually, the ISP will provide POP. When using user PPP, email can be automatically fetched when an Internet connection is established with the following entry in /etc/ppp/ppp.linkup: MYADDR: !bg su user -c fetchmail When using Sendmail to deliver mail to non-local accounts, configure Sendmail to process the mail queue as soon as the Internet connection is established. To do this, add this line after the above fetchmail entry in /etc/ppp/ppp.linkup: !bg su user -c "sendmail -q" In this example, there is an account for user on bsd.home. In the home directory of user on bsd.home, create a .fetchmailrc which contains this line: poll example.net protocol pop3 fetchall pass MySecret This file should not be readable by anyone except user as it contains the password MySecret. In order to send mail with the correct from: header, configure Sendmail to use user@example.net rather than user@bsd.home and to send all mail via relay.example.net, allowing quicker mail transmission. The following .mc file should suffice: VERSIONID(`bsd.home.mc version 1.0') OSTYPE(bsd4.4)dnl FEATURE(nouucp)dnl MAILER(local)dnl MAILER(smtp)dnl Cwlocalhost Cwbsd.home MASQUERADE_AS(`example.net')dnl FEATURE(allmasquerade)dnl FEATURE(masquerade_envelope)dnl FEATURE(nocanonify)dnl FEATURE(nodns)dnl define(`SMART_HOST', `relay.example.net') Dmbsd.home define(`confDOMAIN_NAME',`bsd.home')dnl define(`confDELIVERY_MODE',`deferred')dnl Refer to the previous section for details of how to convert this file into the sendmail.cf format. Do not forget to restart Sendmail after updating sendmail.cf. James Gorham Written by SMTP Authentication Configuring SMTP authentication on the MTA provides a number of benefits. SMTP authentication adds a layer of security to Sendmail, and provides mobile users who switch hosts the ability to use the same MTA without the need to reconfigure their mail client's settings each time. Install security/cyrus-sasl2 from the Ports Collection. This port supports a number of compile-time options. For the SMTP authentication method demonstrated in this example, make sure that is not disabled. After installing security/cyrus-sasl2, edit /usr/local/lib/sasl2/Sendmail.conf, or create it if it does not exist, and add the following line: pwcheck_method: saslauthd Next, install security/cyrus-sasl2-saslauthd and add the following line to /etc/rc.conf: saslauthd_enable="YES" Finally, start the saslauthd daemon: &prompt.root; service saslauthd start This daemon serves as a broker for sendmail to authenticate against the &os; &man.passwd.5; database. This saves the trouble of creating a new set of usernames and passwords for each user that needs to use SMTP authentication, and keeps the login and mail password the same. Next, edit /etc/make.conf and add the following lines: SENDMAIL_CFLAGS=-I/usr/local/include/sasl -DSASL SENDMAIL_LDFLAGS=-L/usr/local/lib SENDMAIL_LDADD=-lsasl2 These lines provide Sendmail the proper configuration options for linking to cyrus-sasl2 at compile time. Make sure that cyrus-sasl2 has been installed before recompiling Sendmail. Recompile Sendmail by executing the following commands: &prompt.root; cd /usr/src/lib/libsmutil &prompt.root; make cleandir && make obj && make &prompt.root; cd /usr/src/lib/libsm &prompt.root; make cleandir && make obj && make &prompt.root; cd /usr/src/usr.sbin/sendmail &prompt.root; make cleandir && make obj && make && make install This compile should not have any problems if /usr/src has not changed extensively and the shared libraries it needs are available. After Sendmail has been compiled and reinstalled, edit /etc/mail/freebsd.mc or the local .mc file. Many administrators choose to use the output from &man.hostname.1; as the name of the .mc file for uniqueness. Add these lines: dnl set SASL options TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl These options configure the different methods available to Sendmail for authenticating users. To use a method other than pwcheck, refer to the Sendmail documentation. Finally, run &man.make.1; while in /etc/mail. That will run the new .mc and create a .cf named either freebsd.cf or the name used for the local .mc. Then, run make install restart, which will copy the file to sendmail.cf, and properly restart Sendmail. For more information about this process, refer to /etc/mail/Makefile. To test the configuration, use a MUA to send a test message. For further investigation, set the of Sendmail to 13 and watch /var/log/maillog for any errors. For more information, refer to SMTP authentication. Marc Silver Contributed by Mail User Agents Mail User Agents A MUA is an application that is used to send and receive email. As email evolves and becomes more complex, MUAs are becoming increasingly powerful and provide users increased functionality and flexibility. The mail category of the &os; Ports Collection contains numerous MUAs. These include graphical email clients such as Evolution or Balsa and console based clients such as mutt or alpine. <command>mail</command> &man.mail.1; is the default MUA installed with &os;. It is a console based MUA that offers the basic functionality required to send and receive text-based email. It provides limited attachment support and can only access local mailboxes. Although mail does not natively support interaction with POP or IMAP servers, these mailboxes may be downloaded to a local mbox using an application such as fetchmail. In order to send and receive email, run mail: &prompt.user; mail The contents of the user's mailbox in /var/mail are automatically read by mail. Should the mailbox be empty, the utility exits with a message indicating that no mail could be found. If mail exists, the application interface starts, and a list of messages will be displayed. Messages are automatically numbered, as can be seen in the following example: Mail version 8.1 6/6/93. Type ? for help. "/var/mail/marcs": 3 messages 3 new >N 1 root@localhost Mon Mar 8 14:05 14/510 "test" N 2 root@localhost Mon Mar 8 14:05 14/509 "user account" N 3 root@localhost Mon Mar 8 14:05 14/509 "sample" Messages can now be read by typing t followed by the message number. This example reads the first email: & t 1 Message 1: From root@localhost Mon Mar 8 14:05:52 2004 X-Original-To: marcs@localhost Delivered-To: marcs@localhost To: marcs@localhost Subject: test Date: Mon, 8 Mar 2004 14:05:52 +0200 (SAST) From: root@localhost (Charlie Root) This is a test message, please reply if you receive it. As seen in this example, the message will be displayed with full headers. To display the list of messages again, press h. If the email requires a reply, press either R or r mail keys. R instructs mail to reply only to the sender of the email, while r replies to all other recipients of the message. These commands can be suffixed with the mail number of the message to reply to. After typing the response, the end of the message should be marked by a single . on its own line. An example can be seen below: & R 1 To: root@localhost Subject: Re: test Thank you, I did get your email. . EOT In order to send a new email, press m, followed by the recipient email address. Multiple recipients may be specified by separating each address with the , delimiter. The subject of the message may then be entered, followed by the message contents. The end of the message should be specified by putting a single . on its own line. & mail root@localhost Subject: I mastered mail Now I can send and receive email using mail ... :) . EOT While using mail, press ? to display help at any time. Refer to &man.mail.1; for more help on how to use mail. &man.mail.1; was not designed to handle attachments and thus deals with them poorly. Newer MUAs handle attachments in a more intelligent way. Users who prefer to use mail may find the converters/mpack port to be of considerable use. <application>mutt</application> mutt is a powerful MUA, with many features, including: The ability to thread messages. PGP support for digital signing and encryption of email. MIME support. Maildir support. Highly customizable. Refer to for more information on mutt. mutt may be installed using the mail/mutt port. After the port has been installed, mutt can be started by issuing the following command: &prompt.user; mutt mutt will automatically read and display the contents of the user mailbox in /var/mail. If no mails are found, mutt will wait for commands from the user. The example below shows mutt displaying a list of messages: To read an email, select it using the cursor keys and press Enter. An example of mutt displaying email can be seen below: Similar to &man.mail.1;, mutt can be used to reply only to the sender of the message as well as to all recipients. To reply only to the sender of the email, press r. To send a group reply to the original sender as well as all the message recipients, press g. By default, mutt uses the &man.vi.1; editor for creating and replying to emails. Each user can customize this by creating or editing the .muttrc in their home directory and setting the editor variable or by setting the EDITOR environment variable. Refer to for more information about configuring mutt. To compose a new mail message, press m. After a valid subject has been given, mutt will start &man.vi.1; so the email can be written. Once the contents of the email are complete, save and quit from vi. mutt will resume, displaying a summary screen of the mail that is to be delivered. In order to send the mail, press y. An example of the summary screen can be seen below: mutt contains extensive help which can be accessed from most of the menus by pressing ?. The top line also displays the keyboard shortcuts where appropriate. <application>alpine</application> alpine is aimed at a beginner user, but also includes some advanced features. alpine has had several remote vulnerabilities discovered in the past, which allowed remote attackers to execute arbitrary code as users on the local system, by the action of sending a specially-prepared email. While known problems have been fixed, alpine code is written in an insecure style and the &os; Security Officer believes there are likely to be other undiscovered vulnerabilities. Users install alpine at their own risk. The current version of alpine may be installed using the mail/alpine port. Once the port has installed, alpine can be started by issuing the following command: &prompt.user; alpine The first time alpine runs, it displays a greeting page with a brief introduction, as well as a request from the alpine development team to send an anonymous email message allowing them to judge how many users are using their client. To send this anonymous message, press Enter. Alternatively, press E to exit the greeting without sending an anonymous message. An example of the greeting page is shown below: The main menu is then presented, which can be navigated using the cursor keys. This main menu provides shortcuts for the composing new mails, browsing mail directories, and administering address book entries. Below the main menu, relevant keyboard shortcuts to perform functions specific to the task at hand are shown. The default directory opened by alpine is inbox. To view the message index, press I, or select the MESSAGE INDEX option shown below: The message index shows messages in the current directory and can be navigated by using the cursor keys. Highlighted messages can be read by pressing Enter. In the screenshot below, a sample message is displayed by alpine. Contextual keyboard shortcuts are displayed at the bottom of the screen. An example of one of a shortcut is r, which tells the MUA to reply to the current message being displayed. Replying to an email in alpine is done using the pico editor, which is installed by default with alpine. pico makes it easy to navigate the message and is easier for novice users to use than &man.vi.1; or &man.mail.1;. Once the reply is complete, the message can be sent by pressing CtrlX . alpine will ask for confirmation before sending the message. alpine can be customized using the SETUP option from the main menu. Consult for more information. Marc Silver Contributed by Using <application>fetchmail</application> fetchmail fetchmail is a full-featured IMAP and POP client. It allows users to automatically download mail from remote IMAP and POP servers and save it into local mailboxes where it can be accessed more easily. fetchmail can be installed using the mail/fetchmail port, and offers various features, including: Support for the POP3, APOP, KPOP, IMAP, ETRN and ODMR protocols. Ability to forward mail using SMTP, which allows filtering, forwarding, and aliasing to function normally. May be run in daemon mode to check periodically for new messages. Can retrieve multiple mailboxes and forward them, based on configuration, to different local users. This section explains some of the basic features of fetchmail. This utility requires a .fetchmailrc configuration in the user's home directory in order to run correctly. This file includes server information as well as login credentials. Due to the sensitive nature of the contents of this file, it is advisable to make it readable only by the user, with the following command: &prompt.user; chmod 600 .fetchmailrc The following .fetchmailrc serves as an example for downloading a single user mailbox using POP. It tells fetchmail to connect to example.com using a username of joesoap and a password of XXX. This example assumes that the user joesoap exists on the local system. poll example.com protocol pop3 username "joesoap" password "XXX" The next example connects to multiple POP and IMAP servers and redirects to different local usernames where applicable: poll example.com proto pop3: user "joesoap", with password "XXX", is "jsoap" here; user "andrea", with password "XXXX"; poll example2.net proto imap: user "john", with password "XXXXX", is "myth" here; fetchmail can be run in daemon mode by running it with , followed by the interval (in seconds) that fetchmail should poll servers listed in .fetchmailrc. The following example configures fetchmail to poll every 600 seconds: &prompt.user; fetchmail -d 600 More information on fetchmail can be found at . Marc Silver Contributed by Using <application>procmail</application> procmail procmail is a powerful application used to filter incoming mail. It allows users to define rules which can be matched to incoming mails to perform specific functions or to reroute mail to alternative mailboxes or email addresses. procmail can be installed using the mail/procmail port. Once installed, it can be directly integrated into most MTAs. Consult the MTA documentation for more information. Alternatively, procmail can be integrated by adding the following line to a .forward in the home directory of the user: "|exec /usr/local/bin/procmail || exit 75" The following section displays some basic procmail rules, as well as brief descriptions of what they do. Rules must be inserted into a .procmailrc, which must reside in the user's home directory. The majority of these rules can be found in &man.procmailex.5;. To forward all mail from user@example.com to an external address of goodmail@example2.com: :0 * ^From.*user@example.com ! goodmail@example2.com To forward all mails shorter than 1000 bytes to an external address of goodmail@example2.com: :0 * < 1000 ! goodmail@example2.com To send all mail sent to alternate@example.com to a mailbox called alternate: :0 * ^TOalternate@example.com alternate To send all mail with a subject of Spam to /dev/null: :0 ^Subject:.*Spam /dev/null A useful recipe that parses incoming &os;.org mailing lists and places each list in its own mailbox: :0 * ^Sender:.owner-freebsd-\/[^@]+@FreeBSD.ORG { LISTNAME=${MATCH} :0 * LISTNAME??^\/[^@]+ FreeBSD-${MATCH} } diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml index 98d96ed097..ac804104c2 100644 --- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml @@ -1,6333 +1,6319 @@ Murray Stokely Reorganized by Network Servers Synopsis This chapter will cover some of the more frequently used network services on &unix; systems. We will cover how to install, configure, test, and maintain many different types of network services. Example configuration files are included throughout this chapter for you to benefit from. After reading this chapter, you will know: How to manage the inetd daemon. How to set up a network file system. How to set up a network information server for sharing user accounts. How to set &os; up to act as an LDAP server or client How to set &os; up to act as an LDAP server or client How to set up automatic network settings using DHCP. How to set up a domain name server. How to set up the Apache HTTP Server. How to set up a File Transfer Protocol (FTP) Server. How to set up a file and print server for &windows; clients using Samba. How to synchronize the time and date, and set up a time server, with the NTP protocol. How to configure the standard logging daemon, syslogd, to accept logs from remote hosts. Before reading this chapter, you should: Understand the basics of the /etc/rc scripts. Be familiar with basic network terminology. Know how to install additional third-party software (). Chern Lee Contributed by Updated by The &os; Documentation Project The <application>inetd</application> <quote>Super-Server</quote> Overview The &man.inetd.8; daemon is sometimes referred to as the Internet Super-Server because it manages connections for many services. When a connection is received by inetd, it determines which program the connection is destined for, spawns the particular process and delegates the socket to it (the program is invoked with the service socket as its standard input, output and error descriptors). Running inetd for servers that are not heavily used can reduce the overall system load, when compared to running each daemon individually in stand-alone mode. Primarily, inetd is used to spawn other daemons, but several trivial protocols are handled directly, such as chargen, auth, and daytime. This section will cover the basics in configuring inetd through its command-line options and its configuration file, /etc/inetd.conf. Settings inetd is initialized through the &man.rc.8; system. The inetd_enable option is set to NO by default, but may be turned on by sysinstall during installation, depending on the configuration chosen by the user. Placing: inetd_enable="YES" or inetd_enable="NO" into /etc/rc.conf will enable or disable inetd starting at boot time. The command: &prompt.root; service inetd rcvar can be run to display the current effective setting. Additionally, different command-line options can be passed to inetd via the inetd_flags option. Command-Line Options Like most server daemons, inetd has a number of options that it can be passed in order to modify its behaviour. See the &man.inetd.8; manual page for the full list of options. Options can be passed to inetd using the inetd_flags option in /etc/rc.conf. By default, inetd_flags is set to -wW -C 60, which turns on TCP wrapping for inetd's services, and prevents any single IP address from requesting any service more than 60 times in any given minute. Although we mention rate-limiting options below, novice users may be pleased to note that these parameters usually do not need to be modified. These options may be useful if an excessive amount of connections are being established. A full list of options can be found in the &man.inetd.8; manual. -c maximum Specify the default maximum number of simultaneous invocations of each service; the default is unlimited. May be overridden on a per-service basis with the parameter. -C rate Specify the default maximum number of times a service can be invoked from a single IP address in one minute; the default is unlimited. May be overridden on a per-service basis with the parameter. -R rate Specify the maximum number of times a service can be invoked in one minute; the default is 256. A rate of 0 allows an unlimited number of invocations. -s maximum Specify the maximum number of times a service can be invoked from a single IP address at any one time; the default is unlimited. May be overridden on a per-service basis with the parameter. <filename>inetd.conf</filename> Configuration of inetd is done via the file /etc/inetd.conf. When a modification is made to /etc/inetd.conf, inetd can be forced to re-read its configuration file by running the command: Reloading the <application>inetd</application> Configuration File &prompt.root; service inetd reload Each line of the configuration file specifies an individual daemon. Comments in the file are preceded by a #. The format of each entry in /etc/inetd.conf is as follows: service-name socket-type protocol {wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]] user[:group][/login-class] server-program server-program-arguments An example entry for the &man.ftpd.8; daemon using IPv4 might read: ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l service-name This is the service name of the particular daemon. It must correspond to a service listed in /etc/services. This determines which port inetd must listen to. If a new service is being created, it must be placed in /etc/services first. socket-type Either stream, dgram, raw, or seqpacket. stream must be used for connection-based, TCP daemons, while dgram is used for daemons utilizing the UDP transport protocol. protocol One of the following: Protocol Explanation tcp, tcp4 TCP IPv4 udp, udp4 UDP IPv4 tcp6 TCP IPv6 udp6 UDP IPv6 tcp46 Both TCP IPv4 and v6 udp46 Both UDP IPv4 and v6 {wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]] indicates whether the daemon invoked from inetd is able to handle its own socket or not. socket types must use the option, while stream socket daemons, which are usually multi-threaded, should use . usually hands off multiple sockets to a single daemon, while spawns a child daemon for each new socket. The maximum number of child daemons inetd may spawn can be set using the option. If a limit of ten instances of a particular daemon is needed, a /10 would be placed after . Specifying /0 allows an unlimited number of children In addition to , two other options which limit the maximum connections from a single place to a particular daemon can be enabled. limits the number of connections from any particular IP address per minutes, e.g., a value of ten would limit any particular IP address connecting to a particular service to ten attempts per minute. limits the number of children that can be started on behalf on any single IP address at any moment. These options are useful to prevent intentional or unintentional excessive resource consumption and Denial of Service (DoS) attacks to a machine. In this field, either of or is mandatory. , and are optional. A stream-type multi-threaded daemon without any , or limits would simply be: nowait. The same daemon with a maximum limit of ten daemons would read: nowait/10. The same setup with a limit of twenty connections per IP address per minute and a maximum total limit of ten child daemons would read: nowait/10/20. These options are utilized by the default settings of the &man.fingerd.8; daemon, as seen here: finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -s Finally, an example of this field with a maximum of 100 children in total, with a maximum of 5 for any one IP address would read: nowait/100/0/5. user This is the username that the particular daemon should run as. Most commonly, daemons run as the root user. For security purposes, it is common to find some servers running as the daemon user, or the least privileged nobody user. server-program The full path of the daemon to be executed when a connection is received. If the daemon is a service provided by inetd internally, then should be used. server-program-arguments This works in conjunction with by specifying the arguments, starting with argv[0], passed to the daemon on invocation. If mydaemon -d is the command line, mydaemon -d would be the value of . Again, if the daemon is an internal service, use here. Security Depending on the choices made at install time, many of inetd's services may be enabled by default. If there is no apparent need for a particular daemon, consider disabling it. Place a # in front of the daemon in question in /etc/inetd.conf, and then reload the inetd configuration. Some daemons, such as fingerd, may not be desired at all because they provide information that may be useful to an attacker. Some daemons are not security-conscious and have long, or non-existent, timeouts for connection attempts. This allows an attacker to slowly send connections to a particular daemon, thus saturating available resources. It may be a good idea to place , or limitations on certain daemons if there are too many connections. By default, TCP wrapping is turned on. Consult the &man.hosts.access.5; manual page for more information on placing TCP restrictions on various inetd invoked daemons. Miscellaneous daytime, time, echo, discard, chargen, and auth are all internally provided services of inetd. The auth service provides identity network services, and is configurable to a certain degree, whilst the others are simply on or off. Consult the &man.inetd.8; manual page for more in-depth information. Tom Rhodes Reorganized and enhanced by Bill Swingle Written by Network File System (NFS) NFS Among the many different file systems that FreeBSD supports is the Network File System, also known as NFS. NFS allows a system to share directories and files with others over a network. By using NFS, users and programs can access files on remote systems almost as if they were local files. Some of the most notable benefits that NFS can provide are: Local workstations use less disk space because commonly used data can be stored on a single machine and still remain accessible to others over the network. There is no need for users to have separate home directories on every network machine. Home directories could be set up on the NFS server and made available throughout the network. Storage devices such as floppy disks, CDROM drives, and &iomegazip; drives can be used by other machines on the network. This may reduce the number of removable media drives throughout the network. How <acronym>NFS</acronym> Works NFS consists of at least two main parts: a server and one or more clients. The client remotely accesses the data that is stored on the server machine. In order for this to function properly a few processes have to be configured and running. The server has to be running the following daemons: NFS server file server UNIX clients rpcbind mountd nfsd Daemon Description nfsd The NFS daemon which services requests from the NFS clients. mountd The NFS mount daemon which carries out the requests that &man.nfsd.8; passes on to it. rpcbind This daemon allows NFS clients to discover which port the NFS server is using. The client can also run a daemon, known as nfsiod. The nfsiod daemon services the requests from the NFS server. This is optional, and improves performance, but is not required for normal and correct operation. See the &man.nfsiod.8; manual page for more information. Configuring <acronym>NFS</acronym> NFS configuration NFS configuration is a relatively straightforward process. The processes that need to be running can all start at boot time with a few modifications to /etc/rc.conf. On the NFS server, make sure that the following options are configured in the /etc/rc.conf file: rpcbind_enable="YES" nfs_server_enable="YES" mountd_flags="-r" mountd runs automatically whenever the NFS server is enabled. On the client, make sure this option is present in /etc/rc.conf: nfs_client_enable="YES" The /etc/exports file specifies which file systems NFS should export (sometimes referred to as share). Each line in /etc/exports specifies a file system to be exported and which machines have access to that file system. Along with what machines have access to that file system, access options may also be specified. There are many such options that can be used in this file but only a few will be mentioned here. Other options are discussed in the &man.exports.5; manual page. Here are a few example /etc/exports entries: NFS export examples The following examples give an idea of how to export file systems, although the settings may be different depending on the environment and network configuration. For instance, to export the /cdrom directory to three example machines that have the same domain name as the server (hence the lack of a domain name for each) or have entries in the /etc/hosts file. The flag makes the exported file system read-only. With this flag, the remote system will not be able to write any changes to the exported file system. /cdrom -ro host1 host2 host3 The following line exports /home to three hosts by IP address. This is a useful setup on a private network without a DNS server configured. Optionally the /etc/hosts file could be configured for internal hostnames; please review &man.hosts.5; for more information. The flag allows the subdirectories to be mount points. In other words, it will not mount the subdirectories but permit the client to mount only the directories that are required or needed. /home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4 The following line exports /a so that two clients from different domains may access the file system. The flag allows the root user on the remote system to write data on the exported file system as root. If the -maproot=root flag is not specified, then even if a user has root access on the remote system, he will not be able to modify files on the exported file system. /a -maproot=root host.example.com box.example.org In order for a client to access an exported file system, the client must have permission to do so. Make sure the client is listed in /etc/exports. In /etc/exports, each line represents the export information for one file system to one host. A remote host can only be specified once per file system, and may only have one default entry. For example, assume that /usr is a single file system. The following /etc/exports would be invalid: # Invalid when /usr is one file system /usr/src client /usr/ports client One file system, /usr, has two lines specifying exports to the same host, client. The correct format for this situation is: /usr/src /usr/ports client The properties of one file system exported to a given host must all occur on one line. Lines without a client specified are treated as a single host. This limits how file systems may be exported; however, for most environments, this is not an issue. The following is an example of a valid export list, where /usr and /exports are local file systems: # Export src and ports to client01 and client02, but only # client01 has root privileges on it /usr/src /usr/ports -maproot=root client01 /usr/src /usr/ports client02 # The client machines have root and can mount anywhere # on /exports. Anyone in the world can mount /exports/obj read-only /exports -alldirs -maproot=root client01 client02 /exports/obj -ro The mountd daemon must be forced to recheck the /etc/exports file whenever it has been modified, so the changes can take effect. This can be accomplished either by sending a HUP signal to the running daemon: &prompt.root; kill -HUP `cat /var/run/mountd.pid` or by invoking the mountd &man.rc.8; script with the appropriate parameter: &prompt.root; service mountd onereload Please refer to for more information about using rc scripts. Alternatively, a reboot will make FreeBSD set everything up properly. A reboot is not necessary though. Executing the following commands as root should start everything up. On the NFS server: &prompt.root; rpcbind &prompt.root; nfsd -u -t -n 4 &prompt.root; mountd -r On the NFS client: &prompt.root; nfsiod -n 4 Now everything should be ready to actually mount a remote file system. In these examples the server's name will be server and the client's name will be client. For testing or to temporarily mount a remote file system execute a command like this as root on the client: NFS mounting &prompt.root; mount server:/home /mnt This will mount the /home directory on the server at /mnt on the client. If everything is set up correctly, the server's files should be visible and available in the /mnt directory. To permanently mount a remote file system each time the computer boots, add the file system to the /etc/fstab file. Here is an example: server:/home /mnt nfs rw 0 0 The &man.fstab.5; manual page lists all the available options. Locking Some applications (e.g., mutt) require file locking to operate correctly. In the case of NFS, rpc.lockd can be used for file locking. To enable it, add the following to the /etc/rc.conf file on both client and server (it is assumed that the NFS client and server are configured already): rpc_lockd_enable="YES" rpc_statd_enable="YES" Start the application by using: &prompt.root; service lockd start &prompt.root; service statd start If real locking between the NFS clients and NFS server is not required, it is possible to let the NFS client do locking locally by passing to &man.mount.nfs.8;. Refer to the &man.mount.nfs.8; manual page for further details. Practical Uses NFS has many practical uses. Some of the more common ones are listed below: NFS uses Set several machines to share a CDROM or other media among them. This is cheaper and often a more convenient method to install software on multiple machines. On large networks, it might be more convenient to configure a central NFS server in which to store all the user home directories. These home directories can then be exported to the network so that users would always have the same home directory, regardless of which workstation they log in to. Several machines could have a common /usr/ports/distfiles directory. This allows for quick access to the source files without downloading them on each machine. Wylie Stilwell Contributed by Chern Lee Rewritten by Automatic Mounts with <application>amd</application> amd automatic mounter daemon &man.amd.8; (the automatic mounter daemon) automatically mounts a remote file system whenever a file or directory within that file system is accessed. Filesystems that are inactive for a period of time will also be automatically unmounted by amd. Using amd provides a simple alternative to permanent mounts, as permanent mounts are usually listed in /etc/fstab. amd operates by attaching itself as an NFS server to the /host and /net directories. When a file is accessed within one of these directories, amd looks up the corresponding remote mount and automatically mounts it. /net is used to mount an exported file system from an IP address, while /host is used to mount an export from a remote hostname. An access to a file within /host/foobar/usr would tell amd to attempt to mount the /usr export on the host foobar. Mounting an Export with <application>amd</application> The showmount command shows the available mounts on a remote host. For example, to view the mounts of a host named foobar: &prompt.user; showmount -e foobar Exports list on foobar: /usr 10.10.10.0 /a 10.10.10.0 &prompt.user; cd /host/foobar/usr As seen in the example, the showmount shows /usr as an export. When changing directories to /host/foobar/usr, amd attempts to resolve the hostname foobar and automatically mount the desired export. amd can be started by the startup scripts by placing the following lines in /etc/rc.conf: amd_enable="YES" Additionally, custom flags can be passed to amd from the amd_flags option. By default, amd_flags is set to: amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map" The /etc/amd.map file defines the default options that exports are mounted with. The /etc/amd.conf file defines some of the more advanced features of amd. Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more information. John Lind Contributed by Problems Integrating with Other Systems Certain Ethernet adapters for ISA PC systems have limitations which can lead to serious network problems, particularly with NFS. This difficulty is not specific to FreeBSD, but FreeBSD systems are affected by it. The problem nearly always occurs when (FreeBSD) PC systems are networked with high-performance workstations, such as those made by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS mount will work fine, and some operations may succeed, but suddenly the server will seem to become unresponsive to the client, even though requests to and from other systems continue to be processed. This happens to the client system, whether the client is the FreeBSD system or the workstation. On many systems, there is no way to shut down the client gracefully once this problem has manifested itself. The only solution is often to reset the client, because the NFS situation cannot be resolved. Though the correct solution is to get a higher performance and capacity Ethernet adapter for the FreeBSD system, there is a simple workaround that will allow satisfactory operation. If the FreeBSD system is the server, include the option on the mount from the client. If the FreeBSD system is the client, then mount the NFS file system with the option . These options may be specified using the fourth field of the fstab entry on the client for automatic mounts, or by using the parameter of the &man.mount.8; command for manual mounts. It should be noted that there is a different problem, sometimes mistaken for this one, when the NFS servers and clients are on different networks. If that is the case, make certain that the routers are routing the necessary UDP information. In the following examples, fastws is the host (interface) name of a high-performance workstation, and freebox is the host (interface) name of a FreeBSD system with a lower-performance Ethernet adapter. Also, /sharedfs will be the exported NFS file system (see &man.exports.5;), and /project will be the mount point on the client for the exported file system. In all cases, note that additional options, such as or and may be desirable in the application. Examples for the FreeBSD system (freebox) as the client in /etc/fstab on freebox: fastws:/sharedfs /project nfs rw,-r=1024 0 0 As a manual mount command on freebox: &prompt.root; mount -t nfs -o -r=1024 fastws:/sharedfs /project Examples for the FreeBSD system as the server in /etc/fstab on fastws: freebox:/sharedfs /project nfs rw,-w=1024 0 0 As a manual mount command on fastws: &prompt.root; mount -t nfs -o -w=1024 freebox:/sharedfs /project Nearly any 16-bit Ethernet adapter will allow operation without the above restrictions on the read or write size. For anyone who cares, here is what happens when the failure occurs, which also explains why it is unrecoverable. NFS typically works with a block size of 8 K (though it may do fragments of smaller sizes). Since the maximum Ethernet packet is around 1500 bytes, the NFS block gets split into multiple Ethernet packets, even though it is still a single unit to the upper-level code, and must be received, assembled, and acknowledged as a unit. The high-performance workstations can pump out the packets which comprise the NFS unit one right after the other, just as close together as the standard allows. On the smaller, lower capacity cards, the later packets overrun the earlier packets of the same unit before they can be transferred to the host and the unit as a whole cannot be reconstructed or acknowledged. As a result, the workstation will time out and try again, but it will try again with the entire 8 K unit, and the process will be repeated, ad infinitum. By keeping the unit size below the Ethernet packet size limitation, we ensure that any complete Ethernet packet received can be acknowledged individually, avoiding the deadlock situation. Overruns may still occur when a high-performance workstations is slamming data out to a PC system, but with the better cards, such overruns are not guaranteed on NFS units. When an overrun occurs, the units affected will be retransmitted, and there will be a fair chance that they will be received, assembled, and acknowledged. Bill Swingle Written by Eric Ogren Enhanced by Udo Erdelhoff Network Information System (NIS/YP) What Is It? NIS Solaris HP-UX AIX Linux NetBSD OpenBSD NIS, which stands for Network Information Services, was developed by Sun Microsystems to centralize administration of &unix; (originally &sunos;) systems. It has now essentially become an industry standard; all major &unix; like systems (&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD, etc) support NIS. yellow pages NIS NIS was formerly known as Yellow Pages, but because of trademark issues, Sun changed the name. The old term (and yp) is still often seen and used. NIS domains It is a RPC-based client/server system that allows a group of machines within an NIS domain to share a common set of configuration files. This permits a system administrator to set up NIS client systems with only minimal configuration data and add, remove or modify configuration data from a single location. Windows NT It is similar to the &windowsnt; domain system; although the internal implementation of the two are not at all similar, the basic functionality can be compared. <acronym>NIS</acronym>Terms and Processes There are several terms and important user processes that will be explained while attempting to implement NIS on FreeBSD, regardless if the system is a NIS server or a NIS client: rpcbind portmap Term Description NIS domainname An NIS master server and all of its clients (including its slave servers) have a NIS domainname. Similar to an &windowsnt; domain name, the NIS domainname does not have anything to do with DNS. rpcbind Must be running in order to enable RPC (Remote Procedure Call, a network protocol used by NIS). If rpcbind is not running, it will be impossible to run an NIS server, or to act as an NIS client. ypbind Binds an NIS client to its NIS server. It will take the NIS domainname from the system, and using RPC, connect to the server. ypbind is the core of client-server communication in an NIS environment; if ypbind dies on a client machine, it will not be able to access the NIS server. ypserv Should only be running on NIS servers; this is the NIS server process itself. If &man.ypserv.8; dies, then the server will no longer be able to respond to NIS requests (hopefully, there is a slave server to take over for it). There are some implementations of NIS (but not the FreeBSD one), that do not try to reconnect to another server if the server it used before dies. Often, the only thing that helps in this case is to restart the server process (or even the whole server) or the ypbind process on the client. rpc.yppasswdd Another process that should only be running on NIS master servers; this is a daemon that will allow NIS clients to change their NIS passwords. If this daemon is not running, users will have to login to the NIS master server and change their passwords there. How Does It Work? There are three types of hosts in an NIS environment: master servers, slave servers, and clients. Servers act as a central repository for host configuration information. Master servers hold the authoritative copy of this information, while slave servers mirror this information for redundancy. Clients rely on the servers to provide this information to them. Information in many files can be shared in this manner. The master.passwd, group, and hosts files are commonly shared via NIS. Whenever a process on a client needs information that would normally be found in these files locally, it makes a query to the NIS server that it is bound to instead. Machine Types - - NIS - master server - - A NIS master server. This + A NIS master serverNISmaster server. This server, analogous to a &windowsnt; primary domain controller, maintains the files used by all of the NIS clients. The passwd, group, and other various files used by the NIS clients live on the master server. It is possible for one machine to be an NIS master server for more than one NIS domain. However, this will not be covered in this introduction, which assumes a relatively small-scale NIS environment. - - NIS - slave server - - - NIS slave servers. Similar to + NIS slave serversNISslave server. Similar to the &windowsnt; backup domain controllers, NIS slave servers maintain copies of the NIS master's data files. NIS slave servers provide the redundancy, which is needed in important environments. They also help to balance the load of the master server: NIS Clients always attach to the NIS server whose response they get first, and this includes slave-server-replies. - - NIS - client - - - NIS clients. NIS clients, like + NIS clientsNISclient. NIS clients, like most &windowsnt; workstations, authenticate against the NIS server (or the &windowsnt; domain controller in the &windowsnt; workstations case) to log on. Using NIS/YP This section will deal with setting up a sample NIS environment. Planning Let us assume that an administrator of a small university lab, which consists of 15 FreeBSD machines, currently has no centralized point of administration. Each machine has its own /etc/passwd and /etc/master.passwd. These files are kept in sync with each other only through manual intervention; currently, a user is added to the lab, the process must be ran on all 15 machines. The lab would clearly benefit from the addition of two NIS servers. Therefore, the configuration of the lab now looks something like: Machine name IP address Machine role ellington 10.0.0.2 NIS master coltrane 10.0.0.3 NIS slave basie 10.0.0.4 Faculty workstation bird 10.0.0.5 Client machine cli[1-11] 10.0.0.[6-17] Other client machines If this is the first time a NIS scheme is being developed, it should be thoroughly planned ahead of time. Regardless of network size, several decisions need to be made as part of the planning process. Choosing a NIS Domain Name NIS domainname This might not be the normal domainname for the network. It is more accurately called the NIS domainname. When a client broadcasts its requests for info, it includes the name of the NIS domain that it is part of. This is how multiple servers on one network can tell which server should answer which request. Think of the NIS domainname as the name for a group of hosts that are related in some way. Some organizations choose to use their Internet domainname for their NIS domainname. This is not recommended as it can cause confusion when trying to debug network problems. The NIS domainname should be unique within the network and it is helpful if it describes the group of machines it represents. For example, the Art department at Acme Inc. might be in the acme-art NIS domain. For this example, assume the chosen name will be test-domain. SunOS However, some operating systems (notably &sunos;) use their NIS domain name as their Internet domain name. If one or more machines on the network have this restriction, it must be used as the Internet domain name for the NIS domain name. Physical Server Requirements There are several things to keep in mind when choosing a machine to use as a NIS server. One of the unfortunate things about NIS is the level of dependency the clients have on the server. If a client cannot contact the server for its NIS domain, very often the machine becomes unusable. The lack of user and group information causes most systems to temporarily freeze up. With this in mind be sure to choose a machine that will not be prone to being rebooted frequently, or one that might be used for development. The NIS server should ideally be a stand alone machine whose sole purpose in life is to be an NIS server. If the network is not very heavily used, it is acceptable to put the NIS server on a machine running other services, however; if the NIS server becomes unavailable, it will adversely affect all NIS clients. NIS Servers The canonical copies of all NIS information are stored on a single machine called the NIS master server. The databases used to store the information are called NIS maps. In FreeBSD, these maps are stored in /var/yp/[domainname] where [domainname] is the name of the NIS domain being served. A single NIS server can support several domains at once, therefore it is possible to have several such directories, one for each supported domain. Each domain will have its own independent set of maps. NIS master and slave servers handle all NIS requests with the ypserv daemon. ypserv is responsible for receiving incoming requests from NIS clients, translating the requested domain and map name to a path to the corresponding database file and transmitting data from the database back to the client. Setting Up a NIS Master Server NIS server configuration Setting up a master NIS server can be relatively straight forward, depending on environmental needs. &os; comes with support for NIS out-of-the-box. It only needs to be enabled by adding the following lines to /etc/rc.conf: nisdomainname="test-domain" This line will set the NIS domainname to test-domain upon network setup (e.g., after reboot). nis_server_enable="YES" This will tell FreeBSD to start up the NIS server processes when the networking is next brought up. nis_yppasswdd_enable="YES" This will enable the rpc.yppasswdd daemon which, as mentioned above, will allow users to change their NIS password from a client machine. Depending on the NIS setup, additional entries may be required. See the section about NIS servers that are also NIS clients, below, for details. After setting up the above entries, run the command /etc/netstart as superuser. It will set up everything, using the values defined in /etc/rc.conf. As a last step, before initializing the NIS maps, start the ypserv daemon manually: &prompt.root; service ypserv start Initializing the NIS Maps NIS maps The NIS maps are database files, that are kept in the /var/yp directory. They are generated from configuration files in the /etc directory of the NIS master, with one exception: /etc/master.passwd. This is for a good reason, never propagate passwords for root and other administrative accounts to all the servers in the NIS domain. Therefore, before the the NIS maps are initialized, configure the primary password files: &prompt.root; cp /etc/master.passwd /var/yp/master.passwd &prompt.root; cd /var/yp &prompt.root; vi master.passwd It is advisable to remove all entries regarding system accounts (bin, tty, kmem, games, etc), as well as any accounts that do not need to be propagated to the NIS clients (for example root and any other UID 0 (superuser) accounts). Ensure the /var/yp/master.passwd is neither group or world readable (mode 600)! Use the chmod command, as appropriate. Tru64 UNIX When this task has been completed, it is time to initialize the NIS maps. FreeBSD includes a script named ypinit to do this (see its manual page for more information). Note that this script is available on most &unix; Operating Systems, but not on all. On Digital UNIX/Compaq Tru64 UNIX it is called ypsetup. Because we are generating maps for an NIS master, we are going to pass the option to ypinit. To generate the NIS maps run: ellington&prompt.root; ypinit -m test-domain Server Type: MASTER Domain: test-domain Creating an YP server will require that you answer a few questions. Questions will all be asked at the beginning of the procedure. Do you want this procedure to quit on non-fatal errors? [y/n: n] n Ok, please remember to go back and redo manually whatever fails. If you don't, something might not work. At this point, we have to construct a list of this domains YP servers. rod.darktech.org is already known as master server. Please continue to add any slave servers, one per line. When you are done with the list, type a <control D>. master server : ellington next host to add: coltrane next host to add: ^D The current list of NIS servers looks like this: ellington coltrane Is this correct? [y/n: y] y [..output from map generation..] NIS Map update completed. ellington has been setup as an YP master server without any errors. At this point, ypinit should have created /var/yp/Makefile from /var/yp/Makefile.dist. When created, this file assumes that the operating environment is a single server NIS system with only &os; machines. Since test-domain has a slave server as well, edit /var/yp/Makefile as well: ellington&prompt.root; vi /var/yp/Makefile You should comment out the line that says NOPUSH = "True" (if it is not commented out already). Setting up a NIS Slave Server NIS slave server Setting up an NIS slave server is even more simple than setting up the master. Log on to the slave server and edit the file /etc/rc.conf as you did before. The only difference is that we now must use the option when running ypinit. The option requires the name of the NIS master be passed to it as well, so our command line looks like: coltrane&prompt.root; ypinit -s ellington test-domain Server Type: SLAVE Domain: test-domain Master: ellington Creating an YP server will require that you answer a few questions. Questions will all be asked at the beginning of the procedure. Do you want this procedure to quit on non-fatal errors? [y/n: n] n Ok, please remember to go back and redo manually whatever fails. If you don't, something might not work. There will be no further questions. The remainder of the procedure should take a few minutes, to copy the databases from ellington. Transferring netgroup... ypxfr: Exiting: Map successfully transferred Transferring netgroup.byuser... ypxfr: Exiting: Map successfully transferred Transferring netgroup.byhost... ypxfr: Exiting: Map successfully transferred Transferring master.passwd.byuid... ypxfr: Exiting: Map successfully transferred Transferring passwd.byuid... ypxfr: Exiting: Map successfully transferred Transferring passwd.byname... ypxfr: Exiting: Map successfully transferred Transferring group.bygid... ypxfr: Exiting: Map successfully transferred Transferring group.byname... ypxfr: Exiting: Map successfully transferred Transferring services.byname... ypxfr: Exiting: Map successfully transferred Transferring rpc.bynumber... ypxfr: Exiting: Map successfully transferred Transferring rpc.byname... ypxfr: Exiting: Map successfully transferred Transferring protocols.byname... ypxfr: Exiting: Map successfully transferred Transferring master.passwd.byname... ypxfr: Exiting: Map successfully transferred Transferring networks.byname... ypxfr: Exiting: Map successfully transferred Transferring networks.byaddr... ypxfr: Exiting: Map successfully transferred Transferring netid.byname... ypxfr: Exiting: Map successfully transferred Transferring hosts.byaddr... ypxfr: Exiting: Map successfully transferred Transferring protocols.bynumber... ypxfr: Exiting: Map successfully transferred Transferring ypservers... ypxfr: Exiting: Map successfully transferred Transferring hosts.byname... ypxfr: Exiting: Map successfully transferred coltrane has been setup as an YP slave server without any errors. Don't forget to update map ypservers on ellington. There should be a directory called /var/yp/test-domain. Copies of the NIS master server's maps should be in this directory. These files must always be up to date. The following /etc/crontab entries on the slave servers should do the job: 20 * * * * root /usr/libexec/ypxfr passwd.byname 21 * * * * root /usr/libexec/ypxfr passwd.byuid These two lines force the slave to sync its maps with the maps on the master server. These entries are not mandatory because the master server automatically attempts to push any map changes to its slaves; however, due to the importance of correct password information on other clients depending on the slave server, it is recommended to specifically force the password map updates frequently. This is especially important on busy networks where map updates might not always complete. Now, run the command /etc/netstart on the slave server as well, which again starts the NIS server. NIS Clients An NIS client establishes what is called a binding to a particular NIS server using the ypbind daemon. The ypbind command checks the system's default domain (as set by the domainname command), and begins broadcasting RPC requests on the local network. These requests specify the name of the domain for which ypbind is attempting to establish a binding. If a server that has been configured to serve the requested domain receives one of the broadcasts, it will respond to ypbind, which will record the server's address. If there are several servers available (a master and several slaves, for example), ypbind will use the address of the first one to respond. From that point on, the client system will direct all of its NIS requests to that server. ypbind will occasionally ping the server to make sure it is still up and running. If it fails to receive a reply to one of its pings within a reasonable amount of time, ypbind will mark the domain as unbound and begin broadcasting again in the hopes of locating another server. Setting Up a NIS Client NIS client configuration Setting up a FreeBSD machine to be a NIS client is fairly straightforward. Edit /etc/rc.conf and add the following lines in order to set the NIS domainname and start ypbind during network startup: nisdomainname="test-domain" nis_client_enable="YES" To import all possible password entries from the NIS server, remove all user accounts from the /etc/master.passwd file and use vipw to add the following line to the end of the file: +::::::::: This line will afford anyone with a valid account in the NIS server's password maps an account. There are many ways to configure the NIS client by changing this line. See the netgroups section below for more information. For more detailed reading see O'Reilly's book on Managing NFS and NIS. Keep in mind that at least one local account (i.e. not imported via NIS) must exist in /etc/master.passwd and this account should also be a member of the group wheel. If there is something wrong with NIS, this account can be used to log in remotely, become root, and fix things. To import all possible group entries from the NIS server, add this line to /etc/group: +:*:: To start the NIS client immediately, execute the following commands as the superuser: &prompt.root; /etc/netstart &prompt.root; service ypbind start After completing these steps, the command, ypcat passwd, should show the server's passwd map. NIS Security In general, any remote user may issue an RPC to &man.ypserv.8; and retrieve the contents of the NIS maps, provided the remote user knows the domainname. To prevent such unauthorized transactions, &man.ypserv.8; supports a feature called securenets which can be used to restrict access to a given set of hosts. At startup, &man.ypserv.8; will attempt to load the securenets information from a file called /var/yp/securenets. This path varies depending on the path specified with the option. This file contains entries that consist of a network specification and a network mask separated by white space. Lines starting with # are considered to be comments. A sample securenets file might look like this: # allow connections from local host -- mandatory 127.0.0.1 255.255.255.255 # allow connections from any host # on the 192.168.128.0 network 192.168.128.0 255.255.255.0 # allow connections from any host # between 10.0.0.0 to 10.0.15.255 # this includes the machines in the testlab 10.0.0.0 255.255.240.0 If &man.ypserv.8; receives a request from an address that matches one of these rules, it will process the request normally. If the address fails to match a rule, the request will be ignored and a warning message will be logged. If the /var/yp/securenets file does not exist, ypserv will allow connections from any host. The ypserv program also has support for Wietse Venema's TCP Wrapper package. This allows the administrator to use the TCP Wrapper configuration files for access control instead of /var/yp/securenets. While both of these access control mechanisms provide some security, they, like the privileged port test, are vulnerable to IP spoofing attacks. All NIS-related traffic should be blocked at the firewall. Servers using /var/yp/securenets may fail to serve legitimate NIS clients with archaic TCP/IP implementations. Some of these implementations set all host bits to zero when doing broadcasts and/or fail to observe the subnet mask when calculating the broadcast address. While some of these problems can be fixed by changing the client configuration, other problems may force the retirement of the client systems in question or the abandonment of /var/yp/securenets. Using /var/yp/securenets on a server with such an archaic implementation of TCP/IP is a really bad idea and will lead to loss of NIS functionality for large parts of the network. TCP Wrappers The use of TCP Wrapper increases the latency of the NIS server. The additional delay may be long enough to cause timeouts in client programs, especially in busy networks or with slow NIS servers. If one or more of the client systems suffers from these symptoms, convert the client systems in question into NIS slave servers and force them to bind to themselves. Barring Some Users from Logging On In our lab, there is a machine basie that is supposed to be a faculty only workstation. We do not want to take this machine out of the NIS domain, yet the passwd file on the master NIS server contains accounts for both faculty and students. What can we do? There is a way to bar specific users from logging on to a machine, even if they are present in the NIS database. To do this, add -username with the correct number of colons like other entries to the end of the /etc/master.passwd file on the client machine, where username is the username of the user to bar from logging in. The line with the blocked user must be before the + line for allowing NIS users. This should preferably be done using vipw, since vipw will sanity check the changes to /etc/master.passwd, as well as automatically rebuild the password database after editing. For example, to bar user bill from logging on to basie: basie&prompt.root; vipw [add -bill::::::::: to the end, exit] vipw: rebuilding the database... vipw: done basie&prompt.root; cat /etc/master.passwd root:[password]:0:0::0:0:The super-user:/root:/bin/csh toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin operator:*:2:5::0:0:System &:/:/sbin/nologin bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin news:*:8:8::0:0:News Subsystem:/:/sbin/nologin man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin -bill::::::::: +::::::::: basie&prompt.root; Udo Erdelhoff Contributed by Using Netgroups netgroups The method shown in the previous section works reasonably well for special rules in an environment with small numbers of users and/or machines. On larger networks, administrators will likely forget to bar some users from logging onto sensitive machines, or may even have to modify each machine separately, thus losing the main benefit of NIS: centralized administration. The NIS developers' solution for this problem is called netgroups. Their purpose and semantics can be compared to the normal groups used by &unix; file systems. The main differences are the lack of a numeric ID and the ability to define a netgroup by including both user accounts and other netgroups. Netgroups were developed to handle large, complex networks with hundreds of users and machines. On one hand, this is a Good Thing in such a situation. On the other hand, this complexity makes it almost impossible to explain netgroups with really simple examples. The example used in the remainder of this section demonstrates this problem. Let us assume that the successful introduction of NIS in the laboratory caught a superiors' interest. The next task is to extend the NIS domain to cover some of the other machines on campus. The two tables contain the names of the new users and new machines as well as brief descriptions of them. User Name(s) Description alpha, beta Normal employees of the IT department charlie, delta The new apprentices of the IT department echo, foxtrott, golf, ... Ordinary employees able, baker, ... The current interns Machine Name(s) Description war, death, famine, pollution The most important servers deployed. Only the IT employees are allowed to log onto these machines. pride, greed, envy, wrath, lust, sloth Less important servers. All members of the IT department are allowed to login onto these machines. one, two, three, four, ... Ordinary workstations. Only the real employees are allowed to use these machines. trashcan A very old machine without any critical data. Even the intern is allowed to use this box. An attempt to implement these restrictions by separately blocking each user, would require the addition of the -user line to each system's passwd. One line for each user who is not allowed to login onto that system. Forgetting just one entry could cause significant trouble. It may be feasible to do this correctly during the initial setup; however, eventually someone will forget to add these lines for new users. Handling this situation with netgroups offers several advantages. Each user need not be handled separately; they would be assigned to one or more netgroups and logins would be allowed or forbidden for all members of the netgroup. While adding a new machine, login restrictions must be defined for all netgroups. If a new user is added, they must be added to one or more netgroups. Those changes are independent of each other: no more for each combination of user and machine do... If the NIS setup is planned carefully, only one central configuration file needs modification to grant or deny access to machines. The first step is the initialization of the NIS map netgroup. &os;'s &man.ypinit.8; does not create this map by default, but its NIS implementation will support it after creation. To create an empty map, simply type ellington&prompt.root; vi /var/yp/netgroup and begin adding content. For our example, we need at least four netgroups: IT employees, IT apprentices, normal employees and interns. IT_EMP (,alpha,test-domain) (,beta,test-domain) IT_APP (,charlie,test-domain) (,delta,test-domain) USERS (,echo,test-domain) (,foxtrott,test-domain) \ (,golf,test-domain) INTERNS (,able,test-domain) (,baker,test-domain) IT_EMP, IT_APP etc. are the names of the netgroups. Each bracketed group adds one or more user accounts to it. The three fields inside a group are: The name of the host(s) where the following items are valid. If a hostname is not specified, the entry is valid on all hosts. If a hostname is specified, it will need to be micro-managed within this configuration. The name of the account that belongs to this netgroup. The NIS domain for the account. Accounts may be imported from other NIS domains into a netgroup. Each of these fields may contain wildcards. See &man.netgroup.5; for details. netgroups Netgroup names longer than 8 characters should not be used, especially with machines running other operating systems within the NIS domain. The names are case sensitive; using capital letters for netgroup names is an easy way to distinguish between user, machine and netgroup names. Some NIS clients (other than &os;) cannot handle netgroups with a large number of entries. For example, some older versions of &sunos; start to cause trouble if a netgroup contains more than 15 entries. This limit may be circumvented by creating several sub-netgroups with 15 users or fewer and a real netgroup consisting of the sub-netgroups: BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...] BIGGRP2 (,joe16,domain) (,joe17,domain) [...] BIGGRP3 (,joe31,domain) (,joe32,domain) BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3 Repeat this process if more than 225 users will exist within a single netgroup. Activating and distributing the new NIS map is easy: ellington&prompt.root; cd /var/yp ellington&prompt.root; make This will generate the three NIS maps netgroup, netgroup.byhost and netgroup.byuser. Use &man.ypcat.1; to check if the new NIS maps are available: ellington&prompt.user; ypcat -k netgroup ellington&prompt.user; ypcat -k netgroup.byhost ellington&prompt.user; ypcat -k netgroup.byuser The output of the first command should resemble the contents of /var/yp/netgroup. The second command will not produce output without specified host-specific netgroups. The third command may be used to get the list of netgroups for a user. The client setup is quite simple. To configure the server war, use &man.vipw.8; to replace the line +::::::::: with +@IT_EMP::::::::: Now, only the data for the users defined in the netgroup IT_EMP is imported into war's password database and only these users are allowed to login. Unfortunately, this limitation also applies to the ~ function of the shell and all routines converting between user names and numerical user IDs. In other words, cd ~user will not work, ls -l will show the numerical ID instead of the username and find . -user joe -print will fail with No such user. To fix this, import all user entries without allowing them to login into the servers. This can be achieved by adding another line to /etc/master.passwd. This line should contain: +:::::::::/sbin/nologin, meaning Import all entries but replace the shell with /sbin/nologin in the imported entries. It is possible to replace any field in the passwd entry by placing a default value in /etc/master.passwd. Make sure that the line +:::::::::/sbin/nologin is placed after +@IT_EMP:::::::::. Otherwise, all user accounts imported from NIS will have /sbin/nologin as their login shell. After this change, the NIS map will only need modification when a new employee joins the IT department. A similar approach for the less important servers may be used by replacing the old +::::::::: in their local version of /etc/master.passwd with something like this: +@IT_EMP::::::::: +@IT_APP::::::::: +:::::::::/sbin/nologin The corresponding lines for the normal workstations could be: +@IT_EMP::::::::: +@USERS::::::::: +:::::::::/sbin/nologin And everything would be fine until there is a policy change a few weeks later: The IT department starts hiring interns. The IT interns are allowed to use the normal workstations and the less important servers; and the IT apprentices are allowed to login onto the main servers. Add a new netgroup IT_INTERN, then add the new IT interns to this netgroup and start to change the configuration on each and every machine. As the old saying goes: Errors in centralized planning lead to global mess. NIS' ability to create netgroups from other netgroups can be used to prevent situations like these. One possibility is the creation of role-based netgroups. For example, one might create a netgroup called BIGSRV to define the login restrictions for the important servers, another netgroup called SMALLSRV for the less important servers and a third netgroup called USERBOX for the normal workstations. Each of these netgroups contains the netgroups that are allowed to login onto these machines. The new entries for the NIS map netgroup should look like this: BIGSRV IT_EMP IT_APP SMALLSRV IT_EMP IT_APP ITINTERN USERBOX IT_EMP ITINTERN USERS This method of defining login restrictions works reasonably well when it is possible to define groups of machines with identical restrictions. Unfortunately, this is the exception and not the rule. Most of the time, the ability to define login restrictions on a per-machine basis is required. Machine-specific netgroup definitions are the other possibility to deal with the policy change outlined above. In this scenario, the /etc/master.passwd of each box contains two lines starting with +. The first of them adds a netgroup with the accounts allowed to login onto this machine, the second one adds all other accounts with /sbin/nologin as shell. It is a good idea to use the ALL-CAPS version of the machine name as the name of the netgroup. In other words, the lines should look like this: +@BOXNAME::::::::: +:::::::::/sbin/nologin Once this task is completed on all the machines, there is no longer a need to modify the local versions of /etc/master.passwd ever again. All further changes can be handled by modifying the NIS map. Here is an example of a possible netgroup map for this scenario with some additional goodies: # Define groups of users first IT_EMP (,alpha,test-domain) (,beta,test-domain) IT_APP (,charlie,test-domain) (,delta,test-domain) DEPT1 (,echo,test-domain) (,foxtrott,test-domain) DEPT2 (,golf,test-domain) (,hotel,test-domain) DEPT3 (,india,test-domain) (,juliet,test-domain) ITINTERN (,kilo,test-domain) (,lima,test-domain) D_INTERNS (,able,test-domain) (,baker,test-domain) # # Now, define some groups based on roles USERS DEPT1 DEPT2 DEPT3 BIGSRV IT_EMP IT_APP SMALLSRV IT_EMP IT_APP ITINTERN USERBOX IT_EMP ITINTERN USERS # # And a groups for a special tasks # Allow echo and golf to access our anti-virus-machine SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain) # # machine-based netgroups # Our main servers WAR BIGSRV FAMINE BIGSRV # User india needs access to this server POLLUTION BIGSRV (,india,test-domain) # # This one is really important and needs more access restrictions DEATH IT_EMP # # The anti-virus-machine mentioned above ONE SECURITY # # Restrict a machine to a single user TWO (,hotel,test-domain) # [...more groups to follow] If some kind of database is used to manage the user accounts, it may be possible to create the first part of the map using the database's reporting tools. This way, new users will automatically have access to the boxes. One last word of caution: It may not always be advisable to use machine-based netgroups. When deploying a couple of dozen or even hundreds of identical machines for student labs, role-based netgroups instead of machine-based netgroups may be used to keep the size of the NIS map within reasonable limits. Important Things to Remember There are still a couple of things administrators need to do differently now that machines are in an NIS environment. Every time a new user is added to the lab, they must be added to the master NIS server and the NIS maps will need rebuilt. If this step is omitted, the new user will not be able to login anywhere except on the NIS master. For example, if we needed to add a new user jsmith to the lab, we would: &prompt.root; pw useradd jsmith &prompt.root; cd /var/yp &prompt.root; make test-domain The user may also be added using adduser jsmith instead of pw useradd jsmith. Keep the administration accounts out of the NIS maps. This is undesirable as it will create a security risk. These users and passwords should not be propagated to all machines. Especially if these machines will have users whom should not have access to those accounts. Keep the NIS master and slave secure, and minimize their downtime. If somebody either hacks or simply turns off these machines, they have effectively rendered many people without the ability to login to the lab. This is the chief weakness of any centralized administration system. If the NIS servers are not protected, there will be a lot of angry users and unhappy management! NIS v1 Compatibility &os;'s ypserv has some support for serving NIS v1 clients. &os;'s NIS implementation only uses the NIS v2 protocol; however, other implementations include support for the v1 protocol for backwards compatibility with older systems. The ypbind daemons supplied with these systems will attempt to establish a binding to an NIS v1 server even though they may never actually need it (and they may persist in broadcasting in search of one even after they receive a response from a v2 server). Note that while support for normal client calls is provided, this version of ypserv does not handle v1 map transfer requests. Additionally, it cannot be used as a master or slave in conjunction with older NIS servers that only support the v1 protocol. Fortunately, there probably are not any such servers still in use today. NIS Servers That Are Also NIS Clients Care must be taken when running ypserv in a multi-server domain where the server machines are also NIS clients. It is generally a good idea to force the servers to bind to themselves rather than allowing them to broadcast bind requests and possibly become bound to each other. Strange failure modes can result if one server goes down and others are dependent upon it. Eventually all the clients will time out and attempt to bind to other servers, but the delay involved can be considerable and the failure mode is still present since the servers might bind to each other all over again. A host may be forced to bind to a particular server by running ypbind with the flag. Add the following lines to /etc/rc.conf to enable this feature during every system boot: nis_client_enable="YES" # run client stuff as well nis_client_flags="-S NIS domain,server" See &man.ypbind.8; for further information. Password Formats NIS password formats One of the most common issues that people run into when trying to implement NIS is password format compatibility. If the NIS server is using DES encrypted passwords, it will only support clients that are also using DES. For example, if any &solaris; NIS clients exist on the network, there is a highly likelihood DES must be used for encrypted passwords. To check which format the servers and clients are using, look at /etc/login.conf. If the host is configured to use DES encrypted passwords, then the default class will contain an entry like this: default:\ :passwd_format=des:\ :copyright=/etc/COPYRIGHT:\ [Further entries elided] Other possible values for the passwd_format capability include blf and md5 (for Blowfish and MD5 encrypted passwords, respectively). If any changes were made to /etc/login.conf, the login capability database must be rebuilt by running the following command as root: &prompt.root; cap_mkdb /etc/login.conf The format of passwords already in /etc/master.passwd will not be updated until a user changes his password for the first time after the login capability database is rebuilt. Next, in order to ensure that passwords are encrypted with the chosen format, check that the crypt_default in /etc/auth.conf gives precedence to the chosen password format. To do this, place the chosen format first in the list. For example, when using DES encrypted passwords, the entry would be: crypt_default = des blf md5 Having followed the above steps on each of the &os; based NIS servers and clients, verify that they all agree on which password format is used within the network. If users have trouble authenticating on an NIS client, this is a pretty good place to start looking for possible problems. Remember: to deploy an NIS server for a heterogeneous network, they will probably have to use DES on all systems because it is the lowest common standard. Tom Rhodes Written by &os; and <acronym>LDAP</acronym> LDAP LDAP, the Lightweight Directory Access Protocol, is an application layer protocol used to access, modify, and authenticate (bind) using a distributed directory information service. Think of it as a phone or record book which stores several levels of hierarchical, homogeneous information. It is often used in networks where users often need access to several levels of internal information utilizing a single account. For example, email authentication, pulling employee contact information, and internal website authentication might all make use of a single user in the LDAP server's record base. This section will not provide a history or the implementation details of the protocol. These sections were authored to get an LDAP server and/or client configured both quickly and securely; however, any information base requires planning and this is no exception. Planning should include what type of information will be stored, what that information will be used for, whom should have access to said information, and how to secure this information from prying eyes. <acronym>LDAP</acronym> Terminology and Structure Before continuing, several parts of LDAP must be explained to prevent confusion. And confusion with this configuration is relatively simple. To begin, all directory entries consist of a group of attributes. Each of these attribute sets contain a name, a unique identifier known as a DN or distinguished name normally built from several other attributes such as the RDN. The RDN or relative distinguished name, is a more common name for the attribute. Like directories have absolute and relative paths, consider a DN as an absolute path and the RDN as the relative path. As an example, an entry might look like the following: &prompt.user; ldapsearch -xb "uid=trhodes,ou=users,o=example.com" # extended LDIF # # LDAPv3 # base <uid=trhodes,ou=users,o=example.com> with scope subtree # filter: (objectclass=*) # requesting: ALL # # trhodes, users, example.com dn: uid=trhodes,ou=users,o=example.com mail: trhodes@example.com cn: Tom Rhodes uid: trhodes telephoneNumber: (xxx) xxx-xxxx # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 In this example, it is very obvious what the various attributes are; however, the cn attribute should be noticed. This is the RDN discussed previously. In addition, there is a unique user id provided here. It is common practice to have specific uid or uuids for entries to ease in any future migration. Configuring an <acronym>LDAP</acronym> Server LDAP Server To configure &os; to act as an LDAP server, the OpenLDAP port needs installed. This may be accomplished using the pkg_add command or by installing the net/openldap24-server port. Building the port is recommended as the administrator may select a great deal of options at this time and disable some options. In most cases, the defaults will be fine; however, this is the time to enable SQL support if needed. A few directories will be required from this point on, at minimal, a data directory and a directory to store the certificates in. Create them both with the following commands: &prompt.root; mkdir /var/db/openldap-data &prompt.root; mkdir /usr/local/etc/openldap/private Copy over the database configuration file: &prompt.root; cp /usr/local/etc/openldap/DB_CONFIG.example /var/db/openldap-data/DB_CONFIG The next phase is to configure the SSL certificates. While creating certificates is discussed in the OpenSSL section in this book, a certificate authority is needed so a different method will be used. It is recommended that this section be reviewed prior to configuring to ensure correct information is entered during the certificate creation process below. The following commands must be executed in the /usr/local/etc/openldap/private directory. This is important as the file permissions will need to be restrictive and users should not have access to these files directly. To create the certificates, issues the following commands. &prompt.root; openssl req -days 365 -nodes -new -x509 -keyout ca.key -out ../ca.crt The entries for these may be completely generic except for the Common Name entry. This entry must have something different than the system hostname. If the entry is the hostname, it would be like the hostname is attempting to verify hostname. In cases with a self signed certificate like this example, just prefix the hostname with CA for certificate authority. The next task is to create a certificate signing request and a private key. To do this, issue the following commands: &prompt.root; openssl req -days 365 -nodes -new -keyout server.key -out server.csr During the certificate generation process, be sure to correctly set the common name attribute. After this has been completed, the key will need signed: &prompt.root; openssl x509 -req -days 365 -in server.csr -out ../server.crt -CA ../ca.crt -CAkey ca.key -CAcreateserial The final part of the certificate generation process is to generate and sign the client certificates: &prompt.root; openssl req -days 365 -nodes -new -keyout client.key -out client.csr &prompt.root; openssl x509 -req -days 3650 -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key Remember, again, to respect the common name attribute. This is a common cause for confusion during the first attempt to configure LDAP. In addition, ensure that a total of eight (8) new files have been generated through the proceeding commands. If so, the next step is to edit /usr/local/etc/openldap/slapd.conf and add the following options: TLSCipherSuite HIGH:MEDIUM:+SSLv3 TLSCertificateFile /usr/local/etc/openldap/server.crt TLSCertificateKeyFile /usr/local/etc/openldap/private/server.key TLSCACertificateFile /usr/local/etc/openldap/ca.crt In addition, edit /usr/local/etc/openldap/ldap.conf and add the following lines: TLS_CACERT /usr/local/etc/openldap/ca.crt TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3 While editing these this file, set the to the desired values, and uncomment all three of the , and options. In addition, set the to contain and . The resulting file should look similar to the following shown here: BASE dc=example,dc=com URI ldap:// ldaps:// SIZELIMIT 12 TIMELIMIT 15 #DEREF never TLS_CACERT /usr/local/etc/openldap/ca.crt TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3 A password for the server will need to be created as the default is extremely poor as is normal in this industry. To do this, issue the following command, sending the output to slapd.conf: &prompt.root; slappasswd -h "{SHA}" >> /usr/local/etc/openldap/slapd.conf There will be a prompt for entering the password and, if the process does not fail, a password hash will be added to the end of slapd.conf. The slappasswd understands several hashing formats, refer to the manual page for more information. Edit /usr/local/etc/openldap/slapd.conf and add the following lines: password-hash {sha} allow bind_v2 In addition, the in this file must be updated to match the from the previous configuration. The option should also be set. A good recommendation is something like . Before saving this file, place the option in front of the password output from the slappasswd and delete the old option above. The end result should look similar to this: TLSCipherSuite HIGH:MEDIUM:+SSLv3 TLSCertificateFile /usr/local/etc/openldap/server.crt TLSCertificateKeyFile /usr/local/etc/openldap/private/server.key TLSCACertificateFile /usr/local/etc/openldap/ca.crt rootpw {SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g= Finally, enable the OpenLDAP service in rc.conf. At this time, setting up a URI and providing the group and user to run as may be useful. Edit /etc/rc.conf and add the following lines: slapd_enable="YES" slapd_flags="-4 -h ldaps:///" At this point the server should be ready to be brought up and tested. To perform this task, issue the following command: &prompt.root; service slapd start If everything was configured correctly, a search of the directory should show a successful connection with a single response as in this example: &prompt.root; ldapsearch -Z # extended LDIF # # LDAPv3 # base <dc=example,dc=com> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # search result search: 3 result: 32 No such object # numResponses: 1 Considering the service should now be responding, as it is above, the directory may be populated using the ldapadd command. In this example, there is a file containing a list of users to be added to this particular directory. First, create a file to be imported with the following dataset: dn: dc=example,dc=com objectclass: dcObject objectclass: organization o: Example dc: Example dn: cn=Manager,dc=example,dc=com objectclass: organizationalRole cn: Manager To debug any of the following, stop the slapd service using the service command and start it using with debugging options. To accomplish this, issue the following command: &prompt.root; /usr/local/libexec/slapd -d -1 To import this datafile, issue the following command, assuming the file is import.ldif: &prompt.root; ldapadd -Z -D "cn=Manager,dc=example,dc=com" -W -f import.ldif There will be a request for the password specified earlier, and the output should look like this: Enter LDAP Password: adding new entry "dc=example,dc=com" adding new entry "cn=Manager,dc=example,dc=com" Verify the data was added by issuing a search on the server using ldapsearch. In this case the output should look like this: &prompt.user; ldapsearch -Z # extended LDIF # # LDAPv3 # base <dc=example,dc=com> (default) with scope subtree # filter: (objectclass=*) # requesting: ALL # # example.com dn: dc=example,dc=com objectClass: dcObject objectClass: organization o: Example dc: Example # Manager, example.com dn: cn=Manager,dc=example,dc=com objectClass: organizationalRole cn: Manager # search result search: 3 result: 0 Success # numResponses: 3 # numEntries: 2 It is of course advisable to read about the structure of LDAP directories and the various manual pages mentioned in this section. At this point, the server should be configured and functioning properly. Greg Sutter Written by Automatic Network Configuration (DHCP) What Is DHCP? Dynamic Host Configuration Protocol DHCP Internet Systems Consortium (ISC) DHCP, the Dynamic Host Configuration Protocol, describes the means by which a system can connect to a network and obtain the necessary information for communication upon that network. FreeBSD uses the OpenBSD dhclient taken from OpenBSD 3.7. All information here regarding dhclient is for use with either of the ISC or OpenBSD DHCP clients. The DHCP server is the one included in the ISC distribution. What This Section Covers This section describes both the client-side components of the ISC and OpenBSD DHCP client and server-side components of the ISC DHCP system. The client-side program, dhclient, comes integrated within FreeBSD, and the server-side portion is available from the net/isc-dhcp42-server port. The &man.dhclient.8;, &man.dhcp-options.5;, and &man.dhclient.conf.5; manual pages, in addition to the references below, are useful resources. How It Works UDP When dhclient, the DHCP client, is executed on the client machine, it begins broadcasting requests for configuration information. By default, these requests are on UDP port 68. The server replies on UDP 67, giving the client an IP address and other relevant network information such as netmask, router, and DNS servers. All of this information comes in the form of a DHCP lease and is only valid for a certain time (configured by the DHCP server maintainer). In this manner, stale IP addresses for clients no longer connected to the network can be automatically reclaimed. DHCP clients can obtain a great deal of information from the server. An exhaustive list may be found in &man.dhcp-options.5;. FreeBSD Integration &os; fully integrates the OpenBSD DHCP client, dhclient. DHCP client support is provided within both the installer and the base system, obviating the need for detailed knowledge of network configurations on any network that runs a DHCP server. sysinstall DHCP is supported by sysinstall. When configuring a network interface within sysinstall, the second question asked is: Do you want to try DHCP configuration of the interface?. Answering affirmatively will execute dhclient, and if successful, will fill in the network configuration information automatically. There are two things required to have the system use DHCP upon startup: DHCP requirements Make sure that the bpf device is compiled into the kernel. To do this, add device bpf to the kernel configuration file, and rebuild the kernel. For more information about building kernels, see . The bpf device is already part of the GENERIC kernel that is supplied with &os;, thus there is no need to build a custom kernel for DHCP. In the case of a custom kernel configuration file, this device must be present for DHCP to function properly. For those who are particularly security conscious, take note that bpf is also the device that allows packet sniffers to work correctly (although they still have to be run as root). bpf is required to use DHCP; however, the security sensitive types should probably not add bpf to the kernel in the expectation that at some point in the future the system will be using DHCP. By default, DHCP configuration on &os; runs in the background, or asynchronously. Other startup scripts continue to run while DHCP completes, speeding up system startup. Background DHCP works well when the DHCP server responds quickly to requests and the DHCP configuration process goes quickly. However, DHCP may take a long time to complete on some systems. If network services attempt to run before DHCP has completed, they will fail. Using DHCP in synchronous mode prevents the problem, pausing startup until DHCP configuration has completed. To connect to a DHCP server in the background while other startup continues (asynchronous mode), use the DHCP value in /etc/rc.conf: ifconfig_fxp0="DHCP" To pause startup while DHCP completes, use synchronous mode with the SYNCDHCP value: ifconfig_fxp0="SYNCDHCP" Replace the fxp0 shown in these examples with the name of the interface to be dynamically configured, as described in . When using a different file system location for dhclient, or if additional flags must be passed to dhclient, include (editing as necessary): dhclient_program="/sbin/dhclient" dhclient_flags="" DHCP server The DHCP server, dhcpd, is included as part of the net/isc-dhcp42-server port in the ports collection. This port contains the ISC DHCP server and documentation. Files DHCP configuration files /etc/dhclient.conf dhclient requires a configuration file, /etc/dhclient.conf. Typically the file contains only comments, the defaults being reasonably sane. This configuration file is described by the &man.dhclient.conf.5; manual page. /sbin/dhclient dhclient is statically linked and resides in /sbin. The &man.dhclient.8; manual page gives more information about dhclient. /sbin/dhclient-script dhclient-script is the FreeBSD-specific DHCP client configuration script. It is described in &man.dhclient-script.8;, but should not need any user modification to function properly. /var/db/dhclient.leases.interface The DHCP client keeps a database of valid leases in this file, which is written as a log. &man.dhclient.leases.5; gives a slightly longer description. Further Reading The DHCP protocol is fully described in RFC 2131. An informational resource has also been set up at . Installing and Configuring a DHCP Server What This Section Covers This section provides information on how to configure a FreeBSD system to act as a DHCP server using the ISC (Internet Systems Consortium) implementation of the DHCP server. The server is not provided as part of &os;, and so the net/isc-dhcp42-server port must be installed to provide this service. See for more information on using the Ports Collection. DHCP Server Installation DHCP installation In order to configure the &os; system as a DHCP server, first ensure that the &man.bpf.4; device is compiled into the kernel. To do this, add device bpf to the kernel configuration file, and rebuild the kernel. For more information about building kernels, see . The bpf device is already part of the GENERIC kernel that is supplied with &os;, so there is no need to create a custom kernel in order to get DHCP working. Those who are particularly security conscious should note that bpf is also the device that allows packet sniffers to function correctly (although such programs still need privileged access). The bpf device is required to use DHCP, but if the sensitivity of the system's security is high, this device should not be included in the kernel purely because the use of DHCP may, at some point in the future, be desired. The next thing that is needed is to edit the sample dhcpd.conf which was installed by the net/isc-dhcp42-server port. By default, this will be /usr/local/etc/dhcpd.conf.sample, and you should copy this to /usr/local/etc/dhcpd.conf before proceeding to make changes. Configuring the DHCP Server DHCP dhcpd.conf dhcpd.conf is comprised of declarations regarding subnets and hosts, and is perhaps most easily explained using an example : option domain-name "example.com"; option domain-name-servers 192.168.4.100; option subnet-mask 255.255.255.0; default-lease-time 3600; max-lease-time 86400; ddns-update-style none; subnet 192.168.4.0 netmask 255.255.255.0 { range 192.168.4.129 192.168.4.254; option routers 192.168.4.1; } host mailhost { hardware ethernet 02:03:04:05:06:07; fixed-address mailhost.example.com; } This option specifies the domain that will be provided to clients as the default search domain. See &man.resolv.conf.5; for more information on what this means. This option specifies a comma separated list of DNS servers that the client should use. The netmask that will be provided to clients. A client may request a specific length of time that a lease will be valid. Otherwise the server will assign a lease with this expiry value (in seconds). This is the maximum length of time that the server will lease for. Should a client request a longer lease, a lease will be issued, although it will only be valid for max-lease-time seconds. This option specifies whether the DHCP server should attempt to update DNS when a lease is accepted or released. In the ISC implementation, this option is required. This denotes which IP addresses should be used in the pool reserved for allocating to clients. IP addresses between, and including, the ones stated are handed out to clients. Declares the default gateway that will be provided to clients. The hardware MAC address of a host (so that the DHCP server can recognize a host when it makes a request). Specifies that the host should always be given the same IP address. Note that using a hostname is correct here, since the DHCP server will resolve the hostname itself before returning the lease information. Once the configuration of dhcpd.conf has been completed, enable the DHCP server in /etc/rc.conf, i.e., by adding: dhcpd_enable="YES" dhcpd_ifaces="dc0" Replace the dc0 interface name with the interface (or interfaces, separated by whitespace) that the DHCP server should listen on for DHCP client requests. Proceed to start the server by issuing the following command: &prompt.root; service isc-dhcpd start Any future changes to the configuration of the server will require the sending of a SIGTERM signal to dhcpd rather than a SIGHUP. It is definitely more simple to use &man.service.8; to completely restart the service. Files DHCP configuration files /usr/local/sbin/dhcpd dhcpd is statically linked and resides in /usr/local/sbin. The &man.dhcpd.8; manual page installed with the port gives more information about dhcpd. /usr/local/etc/dhcpd.conf dhcpd requires a configuration file, /usr/local/etc/dhcpd.conf before it will start providing service to clients. This file needs to contain all the information that should be provided to clients that are being serviced, along with information regarding the operation of the server. This configuration file is described by the &man.dhcpd.conf.5; manual page installed by the port. /var/db/dhcpd.leases The DHCP server keeps a database of leases it has issued in this file, which is written as a log. The manual page &man.dhcpd.leases.5;, installed by the port gives a slightly longer description. /usr/local/sbin/dhcrelay dhcrelay is used in advanced environments where one DHCP server forwards a request from a client to another DHCP server on a separate network. If this functionality is required, then install the net/isc-dhcp42-relay port. The &man.dhcrelay.8; manual page provided with the port contains more detail. Chern Lee Contributed by Tom Rhodes Daniel Gerzo Domain Name System (<acronym>DNS</acronym>) Overview BIND &os; utilizes, by default, a version of BIND (Berkeley Internet Name Domain), which is the most common implementation of the DNS protocol. DNS is the protocol through which names are mapped to IP addresses, and vice versa. For example, a query for www.FreeBSD.org will receive a reply with the IP address of The &os; Project's web server, whereas, a query for ftp.FreeBSD.org will return the IP address of the corresponding FTP machine. Likewise, the opposite can happen. A query for an IP address can resolve its hostname. It is not necessary to run a name server to perform DNS lookups on a system. &os; currently comes with BIND9 DNS server software by default. Our installation provides enhanced security features, a new file system layout and automated &man.chroot.8; configuration. DNS DNS is coordinated across the Internet through a somewhat complex system of authoritative root, Top Level Domain (TLD), and other smaller-scale name servers which host and cache individual domain information. Currently, BIND is maintained by the Internet Systems Consortium . Terminology To understand this document, some terms related to DNS must be understood. resolver reverse DNS root zone Term Definition Forward DNS Mapping of hostnames to IP addresses. Origin Refers to the domain covered in a particular zone file. named, BIND Common names for the BIND name server package within &os;. Resolver A system process through which a machine queries a name server for zone information. Reverse DNS Mapping of IP addresses to hostnames. Root zone The beginning of the Internet zone hierarchy. All zones fall under the root zone, similar to how all files in a file system fall under the root directory. Zone An individual domain, subdomain, or portion of the DNS administered by the same authority. zones examples Examples of zones: . is how the root zone is usually referred to in documentation. org. is a Top Level Domain (TLD) under the root zone. example.org. is a zone under the org. TLD. 1.168.192.in-addr.arpa is a zone referencing all IP addresses which fall under the 192.168.1.* IP address space. As one can see, the more specific part of a hostname appears to its left. For example, example.org. is more specific than org., as org. is more specific than the root zone. The layout of each part of a hostname is much like a file system: the /dev directory falls within the root, and so on. Reasons to Run a Name Server Name servers generally come in two forms: authoritative name servers, and caching (also known as resolving) name servers. An authoritative name server is needed when: One wants to serve DNS information to the world, replying authoritatively to queries. A domain, such as example.org, is registered and IP addresses need to be assigned to hostnames under it. An IP address block requires reverse DNS entries (IP to hostname). A backup or second name server, called a slave, will reply to queries. A caching name server is needed when: A local DNS server may cache and respond more quickly than querying an outside name server. When one queries for www.FreeBSD.org, the resolver usually queries the uplink ISP's name server, and retrieves the reply. With a local, caching DNS server, the query only has to be made once to the outside world by the caching DNS server. Additional queries will not have to go outside the local network, since the information is cached locally. How It Works In &os;, the BIND daemon is called named. File Description &man.named.8; The BIND daemon. &man.rndc.8; Name server control utility. /etc/namedb Directory where BIND zone information resides. /etc/namedb/named.conf Configuration file of the daemon. Depending on how a given zone is configured on the server, the files related to that zone can be found in the master, slave, or dynamic subdirectories of the /etc/namedb directory. These files contain the DNS information that will be given out by the name server in response to queries. Starting BIND BIND starting Since BIND is installed by default, configuring it is relatively simple. The default named configuration is that of a basic resolving name server, running in a &man.chroot.8; environment, and restricted to listening on the local IPv4 loopback address (127.0.0.1). To start the server one time with this configuration, use the following command: &prompt.root; service named onestart To ensure the named daemon is started at boot each time, put the following line into the /etc/rc.conf: named_enable="YES" There are obviously many configuration options for /etc/namedb/named.conf that are beyond the scope of this document. There are other startup options for named on &os;, take a look at the named_* flags in /etc/defaults/rc.conf and consult the &man.rc.conf.5; manual page. The section is also a good read. Configuration Files BIND configuration files Configuration files for named currently reside in /etc/namedb directory and will need modification before use unless all that is needed is a simple resolver. This is where most of the configuration will be performed. <filename>/etc/namedb/named.conf</filename> // $FreeBSD$ // // Refer to the named.conf(5) and named(8) man pages, and the documentation // in /usr/share/doc/bind9 for more details. // // If you are going to set up an authoritative server, make sure you // understand the hairy details of how DNS works. Even with // simple mistakes, you can break connectivity for affected parties, // or cause huge amounts of useless Internet traffic. options { // All file and path names are relative to the chroot directory, // if any, and should be fully qualified. directory "/etc/namedb/working"; pid-file "/var/run/named/pid"; dump-file "/var/dump/named_dump.db"; statistics-file "/var/stats/named.stats"; // If named is being used only as a local resolver, this is a safe default. // For named to be accessible to the network, comment this option, specify // the proper IP address, or delete this option. listen-on { 127.0.0.1; }; // If you have IPv6 enabled on this system, uncomment this option for // use as a local resolver. To give access to the network, specify // an IPv6 address, or the keyword "any". // listen-on-v6 { ::1; }; // These zones are already covered by the empty zones listed below. // If you remove the related empty zones below, comment these lines out. disable-empty-zone "255.255.255.255.IN-ADDR.ARPA"; disable-empty-zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA"; disable-empty-zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA"; // If you've got a DNS server around at your upstream provider, enter // its IP address here, and enable the line below. This will make you // benefit from its cache, thus reduce overall DNS traffic in the Internet. /* forwarders { 127.0.0.1; }; */ // If the 'forwarders' clause is not empty the default is to 'forward first' // which will fall back to sending a query from your local server if the name // servers in 'forwarders' do not have the answer. Alternatively you can // force your name server to never initiate queries of its own by enabling the // following line: // forward only; // If you wish to have forwarding configured automatically based on // the entries in /etc/resolv.conf, uncomment the following line and // set named_auto_forward=yes in /etc/rc.conf. You can also enable // named_auto_forward_only (the effect of which is described above). // include "/etc/namedb/auto_forward.conf"; Just as the comment says, to benefit from an uplink's cache, forwarders can be enabled here. Under normal circumstances, a name server will recursively query the Internet looking at certain name servers until it finds the answer it is looking for. Having this enabled will have it query the uplink's name server (or name server provided) first, taking advantage of its cache. If the uplink name server in question is a heavily trafficked, fast name server, enabling this may be worthwhile. 127.0.0.1 will not work here. Change this IP address to a name server at the uplink. /* Modern versions of BIND use a random UDP port for each outgoing query by default in order to dramatically reduce the possibility of cache poisoning. All users are strongly encouraged to utilize this feature, and to configure their firewalls to accommodate it. AS A LAST RESORT in order to get around a restrictive firewall policy you can try enabling the option below. Use of this option will significantly reduce your ability to withstand cache poisoning attacks, and should be avoided if at all possible. Replace NNNNN in the example with a number between 49160 and 65530. */ // query-source address * port NNNNN; }; // If you enable a local name server, don't forget to enter 127.0.0.1 // first in your /etc/resolv.conf so this server will be queried. // Also, make sure to enable it in /etc/rc.conf. // The traditional root hints mechanism. Use this, OR the slave zones below. zone "." { type hint; file "/etc/namedb/named.root"; }; /* Slaving the following zones from the root name servers has some significant advantages: 1. Faster local resolution for your users 2. No spurious traffic will be sent from your network to the roots 3. Greater resilience to any potential root server failure/DDoS On the other hand, this method requires more monitoring than the hints file to be sure that an unexpected failure mode has not incapacitated your server. Name servers that are serving a lot of clients will benefit more from this approach than individual hosts. Use with caution. To use this mechanism, uncomment the entries below, and comment the hint zone above. As documented at http://dns.icann.org/services/axfr/ these zones: "." (the root), ARPA, IN-ADDR.ARPA, IP6.ARPA, and ROOT-SERVERS.NET are available for AXFR from these servers on IPv4 and IPv6: xfr.lax.dns.icann.org, xfr.cjr.dns.icann.org */ /* zone "." { type slave; file "/etc/namedb/slave/root.slave"; masters { 192.5.5.241; // F.ROOT-SERVERS.NET. }; notify no; }; zone "arpa" { type slave; file "/etc/namedb/slave/arpa.slave"; masters { 192.5.5.241; // F.ROOT-SERVERS.NET. }; notify no; }; */ /* Serving the following zones locally will prevent any queries for these zones leaving your network and going to the root name servers. This has two significant advantages: 1. Faster local resolution for your users 2. No spurious traffic will be sent from your network to the roots */ // RFCs 1912 and 5735 (and BCP 32 for localhost) zone "localhost" { type master; file "/etc/namedb/master/localhost-forward.db"; }; zone "127.in-addr.arpa" { type master; file "/etc/namedb/master/localhost-reverse.db"; }; zone "255.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // RFC 1912-style zone for IPv6 localhost address zone "0.ip6.arpa" { type master; file "/etc/namedb/master/localhost-reverse.db"; }; // "This" Network (RFCs 1912 and 5735) zone "0.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // Private Use Networks (RFCs 1918 and 5735) zone "10.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "16.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "17.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "18.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "19.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "20.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "21.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "22.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "23.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "24.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "25.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "26.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "27.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "28.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "29.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "30.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "31.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "168.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // Link-local/APIPA (RFCs 3927 and 5735) zone "254.169.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IETF protocol assignments (RFCs 5735 and 5736) zone "0.0.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // TEST-NET-[1-3] for Documentation (RFCs 5735 and 5737) zone "2.0.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "100.51.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "113.0.203.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IPv6 Range for Documentation (RFC 3849) zone "8.b.d.0.1.0.0.2.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // Domain Names for Documentation and Testing (BCP 32) zone "test" { type master; file "/etc/namedb/master/empty.db"; }; zone "example" { type master; file "/etc/namedb/master/empty.db"; }; zone "invalid" { type master; file "/etc/namedb/master/empty.db"; }; zone "example.com" { type master; file "/etc/namedb/master/empty.db"; }; zone "example.net" { type master; file "/etc/namedb/master/empty.db"; }; zone "example.org" { type master; file "/etc/namedb/master/empty.db"; }; // Router Benchmark Testing (RFCs 2544 and 5735) zone "18.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "19.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IANA Reserved - Old Class E Space (RFC 5735) zone "240.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "241.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "242.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "243.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "244.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "245.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "246.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "247.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "248.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "249.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "250.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "251.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "252.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "253.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "254.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IPv6 Unassigned Addresses (RFC 4291) zone "1.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "3.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "4.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "5.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "6.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "7.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "8.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "9.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "a.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "b.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "c.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "d.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "e.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "0.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "1.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "2.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "3.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "4.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "5.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "6.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "7.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "8.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "9.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "a.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "b.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "0.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "1.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "2.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "3.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "4.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "5.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "6.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "7.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IPv6 ULA (RFC 4193) zone "c.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "d.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IPv6 Link Local (RFC 4291) zone "8.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "9.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "a.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "b.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IPv6 Deprecated Site-Local Addresses (RFC 3879) zone "c.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "d.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "e.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; zone "f.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; // IP6.INT is Deprecated (RFC 4159) zone "ip6.int" { type master; file "/etc/namedb/master/empty.db"; }; // NB: Do not use the IP addresses below, they are faked, and only // serve demonstration/documentation purposes! // // Example slave zone config entries. It can be convenient to become // a slave at least for the zone your own domain is in. Ask // your network administrator for the IP address of the responsible // master name server. // // Do not forget to include the reverse lookup zone! // This is named after the first bytes of the IP address, in reverse // order, with ".IN-ADDR.ARPA" appended, or ".IP6.ARPA" for IPv6. // // Before starting to set up a master zone, make sure you fully // understand how DNS and BIND work. There are sometimes // non-obvious pitfalls. Setting up a slave zone is usually simpler. // // NB: Don't blindly enable the examples below. :-) Use actual names // and addresses instead. /* An example dynamic zone key "exampleorgkey" { algorithm hmac-md5; secret "sf87HJqjkqh8ac87a02lla=="; }; zone "example.org" { type master; allow-update { key "exampleorgkey"; }; file "/etc/namedb/dynamic/example.org"; }; */ /* Example of a slave reverse zone zone "1.168.192.in-addr.arpa" { type slave; file "/etc/namedb/slave/1.168.192.in-addr.arpa"; masters { 192.168.1.1; }; }; */ In named.conf, these are examples of slave entries for a forward and reverse zone. For each new zone served, a new zone entry must be added to named.conf. For example, the simplest zone entry for example.org can look like: zone "example.org" { type master; file "master/example.org"; }; The zone is a master, as indicated by the statement, holding its zone information in /etc/namedb/master/example.org indicated by the statement. zone "example.org" { type slave; file "slave/example.org"; }; In the slave case, the zone information is transferred from the master name server for the particular zone, and saved in the file specified. If and when the master server dies or is unreachable, the slave name server will have the transferred zone information and will be able to serve it. Zone Files BIND zone files An example master zone file for example.org (existing within /etc/namedb/master/example.org) is as follows: $TTL 3600 ; 1 hour default TTL example.org. IN SOA ns1.example.org. admin.example.org. ( 2006051501 ; Serial 10800 ; Refresh 3600 ; Retry 604800 ; Expire 300 ; Negative Response TTL ) ; DNS Servers IN NS ns1.example.org. IN NS ns2.example.org. ; MX Records IN MX 10 mx.example.org. IN MX 20 mail.example.org. IN A 192.168.1.1 ; Machine Names localhost IN A 127.0.0.1 ns1 IN A 192.168.1.2 ns2 IN A 192.168.1.3 mx IN A 192.168.1.4 mail IN A 192.168.1.5 ; Aliases www IN CNAME example.org. Note that every hostname ending in a . is an exact hostname, whereas everything without a trailing . is relative to the origin. For example, ns1 is translated into ns1.example.org. The format of a zone file follows: recordname IN recordtype value DNS records The most commonly used DNS records: SOA start of zone authority NS an authoritative name server A a host address CNAME the canonical name for an alias MX mail exchanger PTR a domain name pointer (used in reverse DNS) example.org. IN SOA ns1.example.org. admin.example.org. ( 2006051501 ; Serial 10800 ; Refresh after 3 hours 3600 ; Retry after 1 hour 604800 ; Expire after 1 week 300 ) ; Negative Response TTL example.org. the domain name, also the origin for this zone file. ns1.example.org. the primary/authoritative name server for this zone. admin.example.org. the responsible person for this zone, email address with @ replaced. (admin@example.org becomes admin.example.org) 2006051501 the serial number of the file. This must be incremented each time the zone file is modified. Nowadays, many admins prefer a yyyymmddrr format for the serial number. 2006051501 would mean last modified 05/15/2006, the latter 01 being the first time the zone file has been modified this day. The serial number is important as it alerts slave name servers for a zone when it is updated. IN NS ns1.example.org. This is an NS entry. Every name server that is going to reply authoritatively for the zone must have one of these entries. localhost IN A 127.0.0.1 ns1 IN A 192.168.1.2 ns2 IN A 192.168.1.3 mx IN A 192.168.1.4 mail IN A 192.168.1.5 The A record indicates machine names. As seen above, ns1.example.org would resolve to 192.168.1.2. IN A 192.168.1.1 This line assigns IP address 192.168.1.1 to the current origin, in this case example.org. www IN CNAME @ The canonical name record is usually used for giving aliases to a machine. In the example, www is aliased to the master machine whose name happens to be the same as the domain name example.org (192.168.1.1). CNAMEs can never be used together with another kind of record for the same hostname. MX record IN MX 10 mail.example.org. The MX record indicates which mail servers are responsible for handling incoming mail for the zone. mail.example.org is the hostname of a mail server, and 10 is the priority of that mail server. One can have several mail servers, with priorities of 10, 20 and so on. A mail server attempting to deliver to example.org would first try the highest priority MX (the record with the lowest priority number), then the second highest, etc, until the mail can be properly delivered. For in-addr.arpa zone files (reverse DNS), the same format is used, except with PTR entries instead of A or CNAME. $TTL 3600 1.168.192.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. ( 2006051501 ; Serial 10800 ; Refresh 3600 ; Retry 604800 ; Expire 300 ) ; Negative Response TTL IN NS ns1.example.org. IN NS ns2.example.org. 1 IN PTR example.org. 2 IN PTR ns1.example.org. 3 IN PTR ns2.example.org. 4 IN PTR mx.example.org. 5 IN PTR mail.example.org. This file gives the proper IP address to hostname mappings for the above fictitious domain. It is worth noting that all names on the right side of a PTR record need to be fully qualified (i.e., end in a .). Caching Name Server BIND caching name server A caching name server is a name server whose primary role is to resolve recursive queries. It simply asks queries of its own, and remembers the answers for later use. <acronym role="Domain Name Security Extensions">DNSSEC</acronym> BIND DNS security extensions Domain Name System Security Extensions, or DNSSEC for short, is a suite of specifications to protect resolving name servers from forged DNS data, such as spoofed DNS records. By using digital signatures, a resolver can verify the integrity of the record. Note that DNSSEC only provides integrity via digitally signing the Resource Records (RRs). It provides neither confidentiality nor protection against false end-user assumptions. This means that it cannot protect against people going to example.net instead of example.com. The only thing DNSSEC does is authenticate that the data has not been compromised in transit. The security of DNS is an important step in securing the Internet in general. For more in-depth details of how DNSSEC works, the relevant RFCs are a good place to start. See the list in . The following sections will demonstrate how to enable DNSSEC for an authoritative DNS server and a recursive (or caching) DNS server running BIND 9. While all versions of BIND 9 support DNSSEC, it is necessary to have at least version 9.6.2 in order to be able to use the signed root zone when validating DNS queries. This is because earlier versions lack the required algorithms to enable validation using the root zone key. It is strongly recommended to use the latest version of BIND 9.7 or later to take advantage of automatic key updating for the root key, as well as other features to automatically keep zones signed and signatures up to date. Where configurations differ between 9.6.2 and 9.7 and later, differences will be pointed out. Recursive <acronym>DNS</acronym> Server Configuration Enabling DNSSEC validation of queries performed by a recursive DNS server requires a few changes to named.conf. Before making these changes the root zone key, or trust anchor, must be acquired. Currently the root zone key is not available in a file format BIND understands, so it has to be manually converted into the proper format. The key itself can be obtained by querying the root zone for it using dig. By running &prompt.user; dig +multi +noall +answer DNSKEY . > root.dnskey the key will end up in root.dnskey. The contents should look something like this: . 93910 IN DNSKEY 257 3 8 ( AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQ bSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh /RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWA JQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXp oY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3 LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGO Yl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGc LmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0= ) ; key id = 19036 . 93910 IN DNSKEY 256 3 8 ( AwEAAcaGQEA+OJmOzfzVfoYN249JId7gx+OZMbxy69Hf UyuGBbRN0+HuTOpBxxBCkNOL+EJB9qJxt+0FEY6ZUVjE g58sRr4ZQ6Iu6b1xTBKgc193zUARk4mmQ/PPGxn7Cn5V EGJ/1h6dNaiXuRHwR+7oWh7DnzkIJChcTqlFrXDW3tjt ) ; key id = 34525 Do not be alarmed if the obtained keys differ from this example. They might have changed since these instructions were last updated. This output actually contains two keys. The first key in the listing, with the value 257 after the DNSKEY record type, is the one needed. This value indicates that this is a Secure Entry Point (SEP), commonly known as a Key Signing Key (KSK). The second key, with value 256, is a subordinate key, commonly called a Zone Signing Key (ZSK). More on the different key types later in . Now the key must be verified and formatted so that BIND can use it. To verify the key, generate a DS RR set. Create a file containing these RRs with &prompt.user; dnssec-dsfromkey -f root-dnskey . > root.ds These records use SHA-1 and SHA-256 respectively, and should look similar to the following example, where the longer is using SHA-256. . IN DS 19036 8 1 B256BD09DC8DD59F0E0F0D8541B8328DD986DF6E . IN DS 19036 8 2 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE1CDDE32F24E8FB5 The SHA-256 RR can now be compared to the digest in https://data.iana.org/root-anchors/root-anchors.xml. To be absolutely sure that the key has not been tampered with the data in the XML file can be verified using the PGP signature in https://data.iana.org/root-anchors/root-anchors.asc. Next, the key must be formatted properly. This differs a little between BIND versions 9.6.2 and 9.7 and later. In version 9.7 support was added to automatically track changes to the key and update it as necessary. This is done using managed-keys as seen in the example below. When using the older version, the key is added using a trusted-keys statement and updates must be done manually. For BIND 9.6.2 the format should look like: trusted-keys { "." 257 3 8 "AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjF FVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoX bfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaD X6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpz W5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relS Qageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulq QxA+Uk1ihz0="; }; For 9.7 the format will instead be: managed-keys { "." initial-key 257 3 8 "AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjF FVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoX bfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaD X6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpz W5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relS Qageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulq QxA+Uk1ihz0="; }; The root key can now be added to named.conf either directly or by including a file containing the key. After these steps, configure BIND to do DNSSEC validation on queries by editing named.conf and adding the following to the options directive: dnssec-enable yes; dnssec-validation yes; To verify that it is actually working use dig to make a query for a signed zone using the resolver just configured. A successful reply will contain the AD flag to indicate the data was authenticated. Running a query such as &prompt.user; dig @resolver +dnssec se ds should return the DS RR for the .se zone. In the flags: section the AD flag should be set, as seen in: ... ;; flags: qr rd ra ad; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1 ... The resolver is now capable of authenticating DNS queries. Authoritative <acronym>DNS</acronym> Server Configuration In order to get an authoritative name server to serve a DNSSEC signed zone a little more work is required. A zone is signed using cryptographic keys which must be generated. It is possible to use only one key for this. The preferred method however is to have a strong well-protected Key Signing Key (KSK) that is not rotated very often and a Zone Signing Key (ZSK) that is rotated more frequently. Information on recommended operational practices can be found in RFC 4641: DNSSEC Operational Practices. Practices regarding the root zone can be found in DNSSEC Practice Statement for the Root Zone KSK operator and DNSSEC Practice Statement for the Root Zone ZSK operator. The KSK is used to build a chain of authority to the data in need of validation and as such is also called a Secure Entry Point (SEP) key. A message digest of this key, called a Delegation Signer (DS) record, must be published in the parent zone to establish the trust chain. How this is accomplished depends on the parent zone owner. The ZSK is used to sign the zone, and only needs to be published there. To enable DNSSEC for the example.com zone depicted in previous examples, the first step is to use dnssec-keygen to generate the KSK and ZSK key pair. This key pair can utilize different cryptographic algorithms. It is recommended to use RSA/SHA256 for the keys and 2048 bits key length should be enough. To generate the KSK for example.com, run &prompt.user; dnssec-keygen -f KSK -a RSASHA256 -b 2048 -n ZONE example.com and to generate the ZSK, run &prompt.user; dnssec-keygen -a RSASHA256 -b 2048 -n ZONE example.com dnssec-keygen outputs two files, the public and the private keys in files named similar to Kexample.com.+005+nnnnn.key (public) and Kexample.com.+005+nnnnn.private (private). The nnnnn part of the file name is a five digit key ID. Keep track of which key ID belongs to which key. This is especially important when having more than one key in a zone. It is also possible to rename the keys. For each KSK file do: &prompt.user; mv Kexample.com.+005+nnnnn.key Kexample.com.+005+nnnnn.KSK.key &prompt.user; mv Kexample.com.+005+nnnnn.private Kexample.com.+005+nnnnn.KSK.private For the ZSK files, substitute KSK for ZSK as necessary. The files can now be included in the zone file, using the $include statement. It should look something like this: $include Kexample.com.+005+nnnnn.KSK.key ; KSK $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK Finally, sign the zone and tell BIND to use the signed zone file. To sign a zone dnssec-signzone is used. The command to sign the zone example.com, located in example.com.db would look similar to &prompt.user; dnssec-signzone -o example.com -k Kexample.com.+005+nnnnn.KSK example.com.db Kexample.com.+005+nnnnn.ZSK.key The key supplied to the argument is the KSK and the other key file is the ZSK that should be used in the signing. It is possible to supply more than one KSK and ZSK, which will result in the zone being signed with all supplied keys. This can be needed to supply zone data signed using more than one algorithm. The output of dnssec-signzone is a zone file with all RRs signed. This output will end up in a file with the extension .signed, such as example.com.db.signed. The DS records will also be written to a separate file dsset-example.com. To use this signed zone just modify the zone directive in named.conf to use example.com.db.signed. By default, the signatures are only valid 30 days, meaning that the zone needs to be resigned in about 15 days to be sure that resolvers are not caching records with stale signatures. It is possible to make a script and a cron job to do this. See relevant manuals for details. Be sure to keep private keys confidential, as with all cryptographic keys. When changing a key it is best to include the new key into the zone, while still signing with the old one, and then move over to using the new key to sign. After these steps are done the old key can be removed from the zone. Failure to do this might render the DNS data unavailable for a time, until the new key has propagated through the DNS hierarchy. For more information on key rollovers and other DNSSEC operational issues, see RFC 4641: DNSSEC Operational practices. Automation Using <acronym>BIND</acronym> 9.7 or Later Beginning with BIND version 9.7 a new feature called Smart Signing was introduced. This feature aims to make the key management and signing process simpler by automating parts of the task. By putting the keys into a directory called a key repository, and using the new option auto-dnssec, it is possible to create a dynamic zone which will be resigned as needed. To update this zone use nsupdate with the new option . rndc has also grown the ability to sign zones with keys in the key repository, using the option . To tell BIND to use this automatic signing and zone updating for example.com, add the following to named.conf: zone example.com { type master; key-directory "/etc/named/keys"; update-policy local; auto-dnssec maintain; file "/etc/named/dynamic/example.com.zone"; }; After making these changes, generate keys for the zone as explained in , put those keys in the key repository given as the argument to the key-directory in the zone configuration and the zone will be signed automatically. Updates to a zone configured this way must be done using nsupdate, which will take care of re-signing the zone with the new data added. For further details, see and the BIND documentation. Security Although BIND is the most common implementation of DNS, there is always the issue of security. Possible and exploitable security holes are sometimes found. While &os; automatically drops named into a &man.chroot.8; environment; there are several other security mechanisms in place which could help to lure off possible DNS service attacks. It is always good idea to read CERT's security advisories and to subscribe to the &a.security-notifications; to stay up to date with the current Internet and &os; security issues. If a problem arises, keeping sources up to date and having a fresh build of named may help. Further Reading BIND/named manual pages: &man.rndc.8; &man.named.8; &man.named.conf.5; &man.nsupdate.1; &man.dnssec-signzone.8; &man.dnssec-keygen.8; Official ISC BIND Page Official ISC BIND Forum O'Reilly DNS and BIND 5th Edition Root DNSSEC DNSSEC Trust Anchor Publication for the Root Zone RFC1034 - Domain Names - Concepts and Facilities RFC1035 - Domain Names - Implementation and Specification RFC4033 - DNS Security Introduction and Requirements RFC4034 - Resource Records for the DNS Security Extensions RFC4035 - Protocol Modifications for the DNS Security Extensions RFC4641 - DNSSEC Operational Practices RFC 5011 - Automated Updates of DNS Security (DNSSEC Trust Anchors Murray Stokely Contributed by Apache HTTP Server web servers setting up Apache Overview &os; is used to run some of the busiest web sites in the world. The majority of web servers on the Internet are using the Apache HTTP Server. Apache software packages should be included on the &os; installation media. If Apache was not installed while installing &os;, then it can be installed from the www/apache22 port. Once Apache has been installed successfully, it must be configured. This section covers version 2.2.X of the Apache HTTP Server as that is the most widely used version for &os;. For more detailed information beyond the scope of this document about Apache 2.X, please see . Configuration Apache configuration file The main Apache HTTP Server configuration file is installed as /usr/local/etc/apache22/httpd.conf on &os;. This file is a typical &unix; text configuration file with comment lines beginning with the # character. A comprehensive description of all possible configuration options is outside the scope of this book, so only the most frequently modified directives will be described here. ServerRoot "/usr/local" This specifies the default directory hierarchy for the Apache installation. Binaries are stored in the bin and sbin subdirectories of the server root, and configuration files are stored in etc/apache. ServerAdmin you@your.address The address to which problems with the server should be emailed. This address also appears on some server-generated pages, such as error documents. ServerName www.example.com ServerName allows an administrator to set a host name which is sent back to clients for the server. This is useful if the host is different than the one that it is configured with (i.e., use www instead of the host's real name). DocumentRoot "/usr/local/www/apache22/data" DocumentRoot: The directory where documents will be served from. By default, all requests are taken from this directory, but symbolic links and aliases may be used to point to other locations. It is always a good idea to make backup copies of the Apache configuration file before making changes. When the configuration of Apache, is complete, save the file and verify the configuration using &man.apachectl.8;. To do this, issue apachectl configtest which should return Syntax OK. Running <application>Apache</application> Apache starting or stopping The www/apache22 port installs an &man.rc.8; script to aid in starting, stopping, and restarting Apache, which can be found in /usr/local/etc/rc.d/. To launch Apache at system startup, add the following line to /etc/rc.conf: apache22_enable="YES" If Apache should be started with non-default options, the following line may be added to /etc/rc.conf: apache22_flags="" The Apache configuration can be tested for errors after making subsequent configuration changes while httpd is running. This can be done by the &man.rc.8; script directly, or by the &man.service.8; utility by issuing one of the following commands: &prompt.root; service apache22 configtest It is important to note that the configtest is not an &man.rc.8; standard, and should not be expected to work for all &man.rc.8; startup scripts. If Apache does not report configuration errors, the Apache httpd can be started with &man.service.8;: &prompt.root; service apache22 start The httpd service can be tested by entering http://localhost in a web browser, replacing localhost with the fully-qualified domain name of the machine running httpd, if it is not the local machine. The default web page that is displayed is /usr/local/www/apache22/data/index.html. Virtual Hosting Apache supports two different types of Virtual Hosting. The first method is Name-based Virtual Hosting. Name-based virtual hosting uses the clients HTTP/1.1 headers to figure out the hostname. This allows many different domains to share the same IP address. To setup Apache to use Name-based Virtual Hosting add an entry like the following to httpd.conf: NameVirtualHost * If the webserver was named www.domain.tld and a virtual domain for www.someotherdomain.tld then add the following entries to httpd.conf: <VirtualHost *> ServerName www.domain.tld DocumentRoot /www/domain.tld </VirtualHost> <VirtualHost *> ServerName www.someotherdomain.tld DocumentRoot /www/someotherdomain.tld </VirtualHost> Replace the addresses with the addresses needed and the path to the documents with what are being used. For more information about setting up virtual hosts, please consult the official Apache documentation at: . Apache Modules Apache modules There are many different Apache modules available to add functionality to the basic server. The FreeBSD Ports Collection provides an easy way to install Apache together with some of the more popular add-on modules. <application>mod_ssl</application> web servers secure SSL cryptography The mod_ssl module uses the OpenSSL library to provide strong cryptography via the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1) protocols. This module provides everything necessary to request a signed certificate from a trusted certificate signing authority to run a secure web server on &os;. The mod_ssl module is built by default, but can be enabled by specifying -DWITH_SSL at compile time. Language Bindings There are Apache modules for most major scripting languages. These modules typically make it possible to write Apache modules entirely in a scripting language. They are also often used as a persistent interpreter embedded into the server that avoids the overhead of starting an external interpreter and the startup-time penalty for dynamic websites, as described in the next section. Dynamic Websites web servers dynamic In the last decade, more businesses have turned to the Internet in order to enhance their revenue and increase exposure. This has also increased the need for interactive web content. While some companies, such as µsoft;, have introduced solutions into their proprietary products, the open source community answered the call. Modern options for dynamic web content include Django, Ruby on Rails, mod_perl2, and mod_php. Django Python Django Django is a BSD licensed framework designed to allow developers to write high performance, elegant web applications quickly. It provides an object-relational mapper so that data types are developed as Python objects, and a rich dynamic database-access API is provided for those objects without the developer ever having to write SQL. It also provides an extensible template system so that the logic of the application is separated from the HTML presentation. Django depends on mod_python, Apache, and an SQL database engine. The &os; Port will install all of these pre-requisites with the appropriate flags. Installing Django with <application>Apache2</application>, <application>mod_python3</application>, and <application>PostgreSQL</application> &prompt.root; cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL Once Django and these pre-requisites are installed, the application will need a Django project directory along with the Apache configuration to use the embedded Python interpreter. This will be the interpreter to call the application for specific URLs on the site. Apache Configuration for Django/mod_python A line must be added to the apache httpd.conf file to configure Apache to pass requests for certain URLs to the web application: <Location "/"> SetHandler python-program PythonPath "['/dir/to/the/django/packages/'] + sys.path" PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE mysite.settings PythonAutoReload On PythonDebug On </Location> Ruby on Rails Ruby on Rails Ruby on Rails is another open source web framework that provides a full development stack and is optimized to make web developers more productive and capable of writing powerful applications quickly. It can be installed easily from the ports system. &prompt.root; cd /usr/ports/www/rubygem-rails; make all install clean <application>mod_perl2</application> mod_perl2 Perl The Apache/Perl integration project brings together the full power of the Perl programming language and the Apache HTTP Server. With the mod_perl2 module it is possible to write Apache modules entirely in Perl. In addition, the persistent interpreter embedded in the server avoids the overhead of starting an external interpreter and the penalty of Perl start-up time. mod_perl2 is available in the www/mod_perl2 port. Tom Rhodes Written by <application>mod_php</application> mod_php PHP PHP, also known as PHP: Hypertext Preprocessor is a general-purpose scripting language that is especially suited for Web development. Capable of being embedded into HTML its syntax draws upon C, &java;, and Perl with the intention of allowing web developers to write dynamically generated webpages quickly. To gain support for PHP5 for the Apache web server, begin by installing the lang/php5 port. If the lang/php5 port is being installed for the first time, available OPTIONS will be displayed automatically. If a menu is not displayed, i.e., because the lang/php5 port has been installed some time in the past, it is always possible to bring the options dialog up again by running: &prompt.root; make config in the port directory. In the options dialog, check the APACHE option to build mod_php5 as a loadable module for the Apache web server. A lot of sites are still using PHP4 for various reasons (i.e., compatibility issues or already deployed web applications). If the mod_php4 is needed instead of mod_php5, then please use the lang/php4 port. The lang/php4 port supports many of the configuration and build-time options of the lang/php5 port. This will install and configure the modules required to support dynamic PHP applications. Check to ensure the following sections have been added to /usr/local/etc/apache22/httpd.conf: LoadModule php5_module libexec/apache/libphp5.so AddModule mod_php5.c <IfModule mod_php5.c> DirectoryIndex index.php index.html </IfModule> <IfModule mod_php5.c> AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps </IfModule> Once completed, a simple call to the apachectl command for a graceful restart is needed to load the PHP module: &prompt.root; apachectl graceful For future upgrades of PHP, the make config command will not be required; the selected OPTIONS are saved automatically by the &os; Ports framework. The PHP support in &os; is extremely modular so the base install is very limited. It is very easy to add support using the lang/php5-extensions port. This port provides a menu driven interface to PHP extension installation. Alternatively, individual extensions can be installed using the appropriate port. For instance, to add support for the MySQL database server to PHP5, simply install the port databases/php5-mysql. After installing an extension, the Apache server must be reloaded to pick up the new configuration changes: &prompt.root; apachectl graceful Murray Stokely Contributed by File Transfer Protocol (FTP) FTP servers Overview The File Transfer Protocol (FTP) provides users with a simple way to transfer files to and from an FTP server. &os; includes FTP server software, ftpd, in the base system. This makes setting up and administering an FTP server on FreeBSD very straightforward. Configuration The most important configuration step is deciding which accounts will be allowed access to the FTP server. A normal &os; system has a number of system accounts used for various daemons, but unknown users should not be allowed to log in with these accounts. The /etc/ftpusers file is a list of users disallowed any FTP access. By default, it includes the aforementioned system accounts, but it is possible to add specific users here that should not be allowed access to FTP. In some cases it may be desirable to restrict the access of some users without preventing them completely from using FTP. This can be accomplished with the /etc/ftpchroot file. This file lists users and groups subject to FTP access restrictions. The &man.ftpchroot.5; manual page has all of the details so it will not be described in detail here. FTP anonymous To enable anonymous FTP access to the server, create a user named ftp on the &os; system. Users will then be able to log on to the FTP server with a username of ftp or anonymous and with any password (by convention an email address for the user should be used as the password). The FTP server will call &man.chroot.2; when an anonymous user logs in, to restrict access to only the home directory of the ftp user. There are two text files that specify welcome messages to be displayed to FTP clients. The contents of the file /etc/ftpwelcome will be displayed to users before they reach the login prompt. After a successful login, the contents of the file /etc/ftpmotd will be displayed. Note that the path to this file is relative to the login environment, so the file ~ftp/etc/ftpmotd would be displayed for anonymous users. Once the FTP server has been configured properly, it must be enabled in /etc/inetd.conf. All that is required here is to remove the comment symbol # from in front of the existing ftpd line : ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l As explained in , the inetd configuration must be reloaded after this configuration file is changed. Please refer to for details on enabling inetd on the system. Alternatively, ftpd can also be started as a stand-alone server. In this case, it is sufficient to set the appropriate variable in /etc/rc.conf: ftpd_enable="YES" After setting the above variable, the stand-alone server will be started at the next reboot, or it can be started manually by executing the following command as root: &prompt.root; service ftpd start You can now log on to the FTP server by typing: &prompt.user; ftp localhost Maintaining syslog log files FTP The ftpd daemon uses &man.syslog.3; to log messages. By default, the system log daemon will put messages related to FTP in the /var/log/xferlog file. The location of the FTP log can be modified by changing the following line in /etc/syslog.conf: ftp.info /var/log/xferlog FTP anonymous Be aware of the potential problems involved with running an anonymous FTP server. In particular, think twice about allowing anonymous users to upload files. It may turn out that the FTP site becomes a forum for the trade of unlicensed commercial software or worse. If anonymous FTP uploads are required, then verify the permissions so that these files can not be read by other anonymous users until they have been reviewed by an administrator. Murray Stokely Contributed by File and Print Services for µsoft.windows; Clients (Samba) Samba server Microsoft Windows file server Windows clients print server Windows clients Overview Samba is a popular open source software package that provides file and print services for µsoft.windows; clients. Such clients can connect to and use &os; filespace as if it was a local disk drive, or &os; printers as if they were local printers. Samba software packages should be included on the &os; installation media. If they were not installed when first installing &os;, then they may be installed from the net/samba34 port or package. Configuration A default Samba configuration file is installed as /usr/local/share/examples/samba34/smb.conf.default. This file must be copied to /usr/local/etc/smb.conf and customized before Samba can be used. The smb.conf file contains runtime configuration information for Samba, such as definitions of the printers and file system shares that will be shared with &windows; clients. The Samba package includes a web based tool called swat which provides a simple way of configuring the smb.conf file. Using the Samba Web Administration Tool (SWAT) The Samba Web Administration Tool (SWAT) runs as a daemon from inetd. Therefore, inetd must be enabled as shown in , and the following line in /etc/inetd.conf should be uncommented before swat can be used to configure Samba: swat stream tcp nowait/400 root /usr/local/sbin/swat swat As explained in , the inetd configuration must be reloaded after this configuration file is changed. Once swat has been enabled in inetd.conf, a web browser may be used to connect to . At first login, the system root account must be used. Once successfully logging on to the main Samba configuration page, the system documentation will be available, or configuration may begin by clicking on the Globals tab. The Globals section corresponds to the variables that are set in the [global] section of /usr/local/etc/smb.conf. Global Settings Whether swat is being used or /usr/local/etc/smb.conf is being edited directly, the first directives encountered when configuring Samba are: workgroup NT Domain-Name or Workgroup-Name for the computers that will be accessing this server. netbios name This sets the NetBIOS name by which a Samba server is known. By default it is the same as the first component of the host's DNS name. server string This sets the string that will be displayed with the net view command and some other networking tools that seek to display descriptive text about the server. Security Settings Two of the most important settings in /usr/local/etc/smb.conf are the security model chosen, and the backend password format for client users. The following directives control these options: security The two most common options here are security = share and security = user. If the clients use usernames that are the same as their usernames on the &os; machine then user level security should be used. This is the default security policy and it requires clients to first log on before they can access shared resources. In share level security, clients do not need to log onto the server with a valid username and password before attempting to connect to a shared resource. This was the default security model for older versions of Samba. passdb backend NIS+ LDAP SQL database Samba has several different backend authentication models. Clients may be authenticated with LDAP, NIS+, an SQL database, or a modified password file. The default authentication method is smbpasswd, and that is all that will be covered here. Assuming that the default smbpasswd backend is used, the /usr/local/etc/samba/smbpasswd file must be created to allow Samba to authenticate clients. To provide the &unix; user accounts access from &windows; clients, use the following command: &prompt.root; smbpasswd -a username The recommended backend is now tdbsam, and the following command should be used to add user accounts: &prompt.root; pdbedit username Please see the Official Samba HOWTO for additional information about configuration options. With the basics outlined here, the minimal required start running Samba will be explained. Other documentation should be consulted in addition to the information here. Starting <application>Samba</application> The net/samba34 port adds a new startup script, which can be used to control Samba. To enable this script, so that it can be used for example to start, stop or restart Samba, add the following line to the /etc/rc.conf file: samba_enable="YES" Or, for fine grain control: nmbd_enable="YES" smbd_enable="YES" This will also configure Samba to automatically start at system boot time. It is possible then to start Samba at any time by typing: &prompt.root; service samba start Starting SAMBA: removing stale tdbs : Starting nmbd. Starting smbd. Please refer to for more information about using rc scripts. Samba actually consists of three separate daemons. Notice that both the nmbd and smbd daemons are started by the samba script. If winbind, name resolution services were enabled in smb.conf, the winbindd daemon will be started as well. Samba may be stopped at any time by typing: &prompt.root; service samba stop Samba is a complex software suite with functionality that allows broad integration with µsoft.windows; networks. For more information about functionality beyond the basic installation described here, please see . Tom Hukins Contributed by Clock Synchronization with NTP NTP Overview Over time, a computer's clock is prone to drift. The Network Time Protocol (NTP) is one way to ensure the clock stays accurate. Many Internet services rely on, or greatly benefit from, computers' clocks being accurate. For example, a web server may receive requests to send a file if it has been modified since a certain time. In a local area network environment, it is essential that computers sharing files from the same file server have synchronized clocks so that file timestamps stay consistent. Services such as &man.cron.8; also rely on an accurate system clock to run commands at the specified times. NTP ntpd &os; ships with the &man.ntpd.8; NTP server which can be used to query other NTP servers to set the clock on the machine or provide time services to others. Choosing Appropriate NTP Servers NTP choosing servers In order to synchronize the clock, one or more NTP servers must be defined. The network administrator or ISP may have set up an NTP server for this purpose—check their documentation to see if this is the case. There is an online list of publicly accessible NTP servers which may be referenced to find an NTP server nearest to the system. Take care to review the policy for any chosen servers, and ask for permission if required. Choosing several unconnected NTP servers is a good idea in case one of the servers being used becomes unreachable or its clock is unreliable. &man.ntpd.8; uses the responses it receives from other servers intelligently—it will favor unreliable servers less than reliable ones. Configuring The Machine NTP configuration Basic Configuration ntpdate To synchronize the clock only when the machine boots up, use &man.ntpdate.8;. This may be appropriate for some desktop machines which are frequently rebooted and only require infrequent synchronization, but most machines should run &man.ntpd.8;. Using &man.ntpdate.8; at boot time is also a good idea for machines that run &man.ntpd.8;. The &man.ntpd.8; program changes the clock gradually, whereas &man.ntpdate.8; sets the clock, no matter how great the difference between a machine's current clock setting and the correct time. To enable &man.ntpdate.8; at boot time, add ntpdate_enable="YES" to /etc/rc.conf. Also specify all synchronization servers and any flags to be passed to &man.ntpdate.8; in ntpdate_flags. General Configuration NTP ntp.conf NTP is configured by the /etc/ntp.conf file in the format described in &man.ntp.conf.5;. Here is a simple example: server ntplocal.example.com prefer server timeserver.example.org server ntp2a.example.net driftfile /var/db/ntp.drift The server option specifies which servers are to be used, with one server listed on each line. If a server is specified with the prefer argument, as with ntplocal.example.com, that server is preferred over other servers. A response from a preferred server will be discarded if it differs significantly from other servers' responses, otherwise it will be used without any consideration to other responses. The prefer argument is normally used for NTP servers that are known to be highly accurate, such as those with special time monitoring hardware. The driftfile option specifies which file is used to store the system clock's frequency offset. The &man.ntpd.8; program uses this to automatically compensate for the clock's natural drift, allowing it to maintain a reasonably correct setting even if it is cut off from all external time sources for a period of time. The driftfile option specifies which file is used to store information about previous responses from the NTP servers being used. This file contains internal information for NTP. It should not be modified by any other process. Controlling Access to Your Server By default, the NTP server will be accessible to all hosts on the Internet. The restrict option in /etc/ntp.conf controls which machines can access the server. To deny all machines from accessing the NTP server, add the following line to /etc/ntp.conf: restrict default ignore This will also prevent access from the server to any servers listed in the local configuration. If there is a need to synchronise the NTP server with an external NTP server, allow only that specific server. See the &man.ntp.conf.5; manual for more information. To allow machines within the network to synchronize their clocks with the server, but ensure they are not allowed to configure the server or used as peers to synchronize against, add restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap instead, where 192.168.1.0 is an IP address on the network and 255.255.255.0 is the network's netmask. The /etc/ntp.conf file can contain multiple restrict options. For more details, see the Access Control Support subsection of &man.ntp.conf.5;. Running the NTP Server To ensure the NTP server is started at boot time, add the line ntpd_enable="YES" to /etc/rc.conf. To pass additional flags to &man.ntpd.8;, edit the ntpd_flags parameter in /etc/rc.conf. To start the server without rebooting the machine, run ntpd being sure to specify any additional parameters from ntpd_flags in /etc/rc.conf. For example: &prompt.root; ntpd -p /var/run/ntpd.pid Using <application>ntpd</application> with a Temporary Internet Connection The &man.ntpd.8; program does not need a permanent connection to the Internet to function properly. However, if there is a temporary connection that is configured to dial out on demand, it is a good idea to prevent NTP traffic from triggering a dial out or keeping the connection alive. PPP users can use the filter directives in /etc/ppp/ppp.conf. For example: set filter dial 0 deny udp src eq 123 # Prevent NTP traffic from initiating dial out set filter dial 1 permit 0 0 set filter alive 0 deny udp src eq 123 # Prevent incoming NTP traffic from keeping the connection open set filter alive 1 deny udp dst eq 123 # Prevent outgoing NTP traffic from keeping the connection open set filter alive 2 permit 0/0 0/0 For more details see the PACKET FILTERING section in &man.ppp.8; and the examples in /usr/share/examples/ppp/. Some Internet access providers block low-numbered ports, preventing NTP from functioning since replies never reach the machine. Further Information Documentation for the NTP server can be found in /usr/share/doc/ntp/ in HTML format. Tom Rhodes Contributed by Remote Host Logging with <command>syslogd</command> Interacting with system logs is a crucial aspect of both security and system administration. Monitoring the log files of multiple hosts can get very unwieldy when these hosts are distributed across medium or large networks, or when they are parts of various different types of networks. In these cases, configuring remote logging may make the whole process a lot more comfortable. Centralized logging to a specific logging host can reduce some of the administrative burden of log file administration. Log file aggregation, merging and rotation may be configured in one location, using the native tools of &os;, such as &man.syslogd.8; and &man.newsyslog.8;. In the following example configuration, host A, named logserv.example.com, will collect logging information for the local network. Host B, named logclient.example.com will pass logging information to the server system. In live configurations, both hosts require proper forward and reverse DNS or entries in /etc/hosts. Otherwise, data will be rejected by the server. Log Server Configuration Log servers are machines configured to accept logging information from remote hosts. In most cases this is to ease configuration, in other cases it may just be a better administration move. Regardless of reason, there are a few requirements before continuing. A properly configured logging server has met the following minimal requirements: The firewall ruleset allows for UDP to be passed on port 514 on both the client and server; syslogd has been configured to accept remote messages from client machines; The syslogd server and all client machines must have valid entries for both forward and reverse DNS, or be properly configured in /etc/hosts. To configure the log server, the client must be listed in /etc/syslog.conf, and the logging facility must be specified: +logclient.example.com *.* /var/log/logclient.log More information on various supported and available facilities may be found in the &man.syslog.conf.5; manual page. Once added, all facility messages will be logged to the file specified previously, /var/log/logclient.log. The server machine must also have the following listing placed inside /etc/rc.conf: syslogd_enable="YES" syslogd_flags="-a logclient.example.com -v -v" The first option will enable the syslogd daemon on boot up, and the second option allows data from the specified client to be accepted on this server. The latter part, using , will increase the verbosity of logged messages. This is extremely useful for tweaking facilities as administrators are able to see what type of messages are being logged under which facility. Multiple options may be specified to allow logging from multiple clients. IP addresses and whole netblocks may also be specified, see the &man.syslog.3; manual page for a full list of possible options. Finally, the log file should be created. The method used does not matter, but &man.touch.1; works great for situations such as this: &prompt.root; touch /var/log/logclient.log At this point, the syslogd daemon should be restarted and verified: &prompt.root; service syslogd restart &prompt.root; pgrep syslog If a PID is returned, the server has been restarted successfully, and client configuration may begin. If the server has not restarted, consult the /var/log/messages log for any output. Log Client Configuration A logging client is a machine which sends log information to a logging server in addition to keeping local copies. Similar to log servers, clients must also meet a few minimum requirements: &man.syslogd.8; must be configured to send messages of specific types to a log server, which must accept them; The firewall must allow UDP packets through on port 514; Both forward and reverse DNS must be configured or have proper entries in the /etc/hosts. Client configuration is a bit more relaxed when compared to that of the servers. The client machine must have the following listing placed inside /etc/rc.conf: syslogd_enable="YES" syslogd_flags="-s -v -v" As before, these entries will enable the syslogd daemon on boot up, and increases the verbosity of logged messages. The option prevents logs from being accepted by this client from other hosts. Facilities describe the system part for which a message is generated. For an example, ftp and ipfw are both facilities. When log messages are generated for those two services, they will normally include those two utilities in any log messages. Facilities are accompanied with a priority or level, which is used to mark how important a log message is. The most common will be the warning and info. Please refer to the &man.syslog.3; manual page for a full list of available facilities and priorities. The logging server must be defined in the client's /etc/syslog.conf. In this instance, the @ symbol is used to send logging data to a remote server and would look similar to the following entry: *.* @logserv.example.com Once added, syslogd must be restarted for the changes to take effect: &prompt.root; service syslogd restart To test that log messages are being sent across the network, use &man.logger.1; on the client to send a message to syslogd: &prompt.root; logger "Test message from logclient" This message should now exist both in /var/log/messages on the client, and /var/log/logclient.log on the log server. Debugging Log Servers In certain cases, debugging may be required if messages are not being received on the log server. There are several reasons this may occur; however, the most common two are network connection issues and DNS issues. To test these cases, ensure both hosts are able to reach one another using the hostname specified in /etc/rc.conf. If this appears to be working properly, an alternation to the syslogd_flags option in /etc/rc.conf will be required. In the following example, /var/log/logclient.log is empty, and the /var/log/messages files indicate no reason for the failure. To increase debugging output, change the syslogd_flags option to look like the following example, and issue a restart: syslogd_flags="-d -a logclien.example.com -v -v" &prompt.root; service syslogd restart Debugging data similar to the following will flash on the screen immediately after the restart: logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart syslogd: restarted logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel Logging to FILE /var/log/messages syslogd: kernel boot file is /boot/kernel/kernel cvthname(192.168.1.10) validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com; rejected in rule 0 due to name mismatch. It appears obvious the messages are being rejected due to a name mismatch. After reviewing the configuration bit by bit, it appears a typo in the following /etc/rc.conf line has an issue: syslogd_flags="-d -a logclien.example.com -v -v" The line should contain logclient, not logclien. After the proper alterations are made, a restart is issued with expected results: &prompt.root; service syslogd restart logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart syslogd: restarted logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel syslogd: kernel boot file is /boot/kernel/kernel logmsg: pri 166, flags 17, from logserv.example.com, msg Dec 10 20:55:02 <syslog.err> logserv.example.com syslogd: exiting on signal 2 cvthname(192.168.1.10) validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com; accepted in rule 0. logmsg: pri 15, flags 0, from logclient.example.com, msg Dec 11 02:01:28 trhodes: Test message 2 Logging to FILE /var/log/logclient.log Logging to FILE /var/log/messages At this point, the messages are being properly received and placed in the correct file. Security Considerations As with any network service, security requirements should be considered before implementing this configuration. At times, log files may contain sensitive data about services enabled on the local host, user accounts, and configuration data. Network data sent from the client to the server will not be encrypted nor password protected. If a need for encryption exists, it might be possible to use security/stunnel, which will transmit data over an encrypted tunnel. Local security is also an issue. Log files are not encrypted during use or after log rotation. Local users may access these files to gain additional insight on system configuration. In those cases, setting proper permissions on these files will be critical. The &man.newsyslog.8; utility supports setting permissions on newly created and rotated log files. Setting log files to mode 600 should prevent any unwanted snooping by local users. diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml index 86d0c65702..7fcceb544a 100644 --- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml @@ -1,3318 +1,3280 @@ Jim Mock Restructured, reorganized, and updated by PPP and SLIP Synopsis PPP SLIP FreeBSD has a number of ways to link one computer to another. To establish a network or Internet connection through a dial-up modem, or to allow others to do so through you, requires the use of PPP or SLIP. This chapter describes setting up these modem-based communication services in detail. After reading this chapter, you will know: How to set up user PPP. How to set up kernel PPP (&os; 7.X only). How to set up PPPoE (PPP over Ethernet). How to set up PPPoA (PPP over ATM). How to configure and set up a SLIP client and server (&os; 7.X only). PPP user PPP PPP kernel PPP PPP over Ethernet Before reading this chapter, you should: Be familiar with basic network terminology. Understand the basics and purpose of a dialup connection and PPP and/or SLIP. You may be wondering what the main difference is between user PPP and kernel PPP. The answer is simple: user PPP processes the inbound and outbound data in userland rather than in the kernel. This is expensive in terms of copying the data between the kernel and userland, but allows a far more feature-rich PPP implementation. User PPP uses the tun device to communicate with the outside world whereas kernel PPP uses the ppp device. Throughout in this chapter, user PPP will simply be referred to as ppp unless a distinction needs to be made between it and any other PPP software such as pppd (&os; 7.X only). Unless otherwise stated, all of the commands explained in this chapter should be executed as root. Tom Rhodes Updated and enhanced by Brian Somers Originally contributed by Nik Clayton With input from Dirk Frömberg Peter Childs Using User PPP User PPP Assumptions This document assumes you have the following: - - ISP - - - PPP - - An account with an Internet Service Provider (ISP) - which you connect to using PPP. + An account with an Internet Service Provider (ISP)ISP + which you connect to using PPPPPP. A modem or other device connected to your system and properly configured to allow you to connect to your ISP. The dial-up number(s) of your ISP. - - PAP - - - CHAP - - - UNIX - - - login name - - - password - - Your login name and password. (Either a - regular &unix; style login and password pair, or a PAP - or CHAP login and password pair). + Your login namelogin name and passwordpassword. (Either a + regular &unix;UNIX style login and password pair, or a PAPPAP + or CHAPCHAP login and password pair). - - nameserver - - - The IP address of one or more name servers. + The IP address of one or more name serversnameserver. Normally, you will be given two IP addresses by your ISP to use for this. If they have not given you at least one, then you can use the enable dns command in ppp.conf and ppp will set the name servers for you. This feature depends on your ISPs PPP implementation supporting DNS negotiation. The following information may be supplied by your ISP, but is not completely necessary: The IP address of your ISP's gateway. The gateway is the machine to which you will connect and will be set up as your default route. If you do not have this information, we can make one up and your ISP's PPP server will tell us the correct value when we connect. This IP number is referred to as HISADDR by ppp. The netmask you should use. If your ISP has not provided you with one, you can safely use 255.255.255.255. static IP address If your ISP provides you with a static IP address and hostname, you can enter it. Otherwise, we simply let the peer assign whatever IP address it sees fit. If you do not have any of the required information, contact your ISP. Throughout this section, many of the examples showing the contents of configuration files are numbered by line. These numbers serve to aid in the presentation and discussion only and are not meant to be placed in the actual file. Proper indentation with tab and space characters is also important. Automatic <application>PPP</application> Configuration PPP configuration Both ppp and pppd (the kernel level implementation of PPP, &os; 7.X only) use the configuration files located in the /etc/ppp directory. Examples for user ppp can be found in /usr/share/examples/ppp/. Configuring ppp requires that you edit a number of files, depending on your requirements. What you put in them depends to some extent on whether your ISP allocates IP addresses statically (i.e., you get given one IP address, and always use that one) or dynamically (i.e., your IP address changes each time you connect to your ISP). PPP and Static IP Addresses PPP with static IP addresses You will need to edit the /etc/ppp/ppp.conf configuration file. It should look similar to the example below. Lines that end in a : start in the first column (beginning of the line)— all other lines should be indented as shown using spaces or tabs. 1 default: 2 set log Phase Chat LCP IPCP CCP tun command 3 ident user-ppp VERSION (built COMPILATIONDATE) 4 set device /dev/cuau0 5 set speed 115200 6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \ 7 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT" 8 set timeout 180 9 enable dns 10 11 provider: 12 set phone "(123) 456 7890" 13 set authname foo 14 set authkey bar 15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp" 16 set timeout 300 17 set ifaddr x.x.x.x y.y.y.y 255.255.255.255 0.0.0.0 18 add default HISADDR Line 1: Identifies the default entry. Commands in this entry are executed automatically when ppp is run. Line 2: Enables logging parameters. When the configuration is working satisfactorily, this line should be reduced to saying: set log phase tun in order to avoid excessive log file sizes. Line 3: Tells PPP how to identify itself to the peer. PPP identifies itself to the peer if it has any trouble negotiating and setting up the link, providing information that the peers administrator may find useful when investigating such problems. Line 4: Identifies the device to which the modem is connected. COM1 is /dev/cuau0 and COM2 is /dev/cuau1. Line 5: Sets the speed you want to connect at. If 115200 does not work (it should with any reasonably new modem), try 38400 instead. Line 6 & 7: - - PPP - user PPP - - - The dial string. User PPP uses an expect-send + The dial string. User PPPPPPuser PPP uses an expect-send syntax similar to the &man.chat.8; program. Refer to the manual page for information on the features of this language. Note that this command continues onto the next line for readability. Any command in ppp.conf may do this if the last character on the line is a \ character. Line 8: Sets the idle timeout for the link. 180 seconds is the default, so this line is purely cosmetic. Line 9: Tells PPP to ask the peer to confirm the local resolver settings. If you run a local name server, this line should be commented out or removed. Line 10: A blank line for readability. Blank lines are ignored by PPP. Line 11: Identifies an entry for a provider called provider. This could be changed to the name of your ISP so that later you can use the to start the connection. Line 12: Sets the phone number for this provider. Multiple phone numbers may be specified using the colon (:) or pipe character (|) as a separator. The difference between the two separators is described in &man.ppp.8;. To summarize, if you want to rotate through the numbers, use a colon. If you want to always attempt to dial the first number first and only use the other numbers if the first number fails, use the pipe character. Always quote the entire set of phone numbers as shown. You must enclose the phone number in quotation marks (") if there is any intention on using spaces in the phone number. This can cause a simple, yet subtle error. Line 13 & 14: Identifies the user name and password. When connecting using a &unix; style login prompt, these values are referred to by the set login command using the \U and \P variables. When connecting using PAP or CHAP, these values are used at authentication time. Line 15: - PAP - CHAP - If you are using PAP or CHAP, there will be no + If you are using PAPPAP or CHAPCHAP, there will be no login at this point, and this line should be commented out or removed. See PAP and CHAP authentication for further details. The login string is of the same chat-like syntax as the dial string. In this example, the string works for a service whose login session looks like this: J. Random Provider login: foo password: bar protocol: ppp You will need to alter this script to suit your own needs. When you write this script for the first time, you should ensure that you have enabled chat logging so you can determine if the conversation is going as expected. Line 16: - timeout - - Sets the default idle timeout (in seconds) for + Sets the default idle timeouttimeout (in seconds) for the connection. Here, the connection will be closed automatically after 300 seconds of inactivity. If you never want to timeout, set this value to zero or use the command line switch. Line 17: - ISP - Sets the interface addresses. The string x.x.x.x should be - replaced by the IP address that your provider has + replaced by the IP address that your providerISP has allocated to you. The string y.y.y.y should be replaced by the IP address that your ISP indicated for their gateway (the machine to which you connect). If your ISP has not given you a gateway address, use 10.0.0.2/0. If you need to use a guessed address, make sure that you create an entry in /etc/ppp/ppp.linkup as per the instructions for PPP and Dynamic IP addresses. If this line is omitted, ppp cannot run in mode. Line 18: Adds a default route to your ISP's gateway. The special word HISADDR is replaced with the gateway address specified on line 17. It is important that this line appears after line 17, otherwise HISADDR will not yet be initialized. If you do not wish to run ppp in , this line should be moved to the ppp.linkup file. It is not necessary to add an entry to ppp.linkup when you have a static IP address and are running ppp in mode as your routing table entries are already correct before you connect. You may however wish to create an entry to invoke programs after connection. This is explained later with the sendmail example. Example configuration files can be found in the /usr/share/examples/ppp/ directory. PPP and Dynamic IP Addresses PPP with dynamic IP addresses IPCP If your service provider does not assign static IP addresses, ppp can be configured to negotiate the local and remote addresses. This is done by guessing an IP address and allowing ppp to set it up correctly using the IP Configuration Protocol (IPCP) after connecting. The ppp.conf configuration is the same as PPP and Static IP Addresses, with the following change: 17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255 0.0.0.0 Again, do not include the line number, it is just for reference. Indentation of at least one space is required. Line 17: The number after the / character is the number of bits of the address that ppp will insist on. You may wish to use IP numbers more appropriate to your circumstances, but the above example will always work. The last argument (0.0.0.0) tells PPP to start negotiations using address 0.0.0.0 rather than 10.0.0.1 and is necessary for some ISPs. Do not use 0.0.0.0 as the first argument to set ifaddr as it prevents PPP from setting up an initial route in mode. If you are not running in mode, you will need to create an entry in /etc/ppp/ppp.linkup. ppp.linkup is used after a connection has been established. At this point, ppp will have assigned the interface addresses and it will now be possible to add the routing table entries: 1 provider: 2 add default HISADDR Line 1: On establishing a connection, ppp will look for an entry in ppp.linkup according to the following rules: First, try to match the same label as we used in ppp.conf. If that fails, look for an entry for the IP address of our gateway. This entry is a four-octet IP style label. If we still have not found an entry, look for the MYADDR entry. Line 2: This line tells ppp to add a default route that points to HISADDR. HISADDR will be replaced with the IP number of the gateway as negotiated by the IPCP. See the pmdemand entry in the files /usr/share/examples/ppp/ppp.conf.sample and /usr/share/examples/ppp/ppp.linkup.sample for a detailed example. Receiving Incoming Calls PPP receiving incoming calls When you configure ppp to receive incoming calls on a machine connected to a LAN, you must decide if you wish to forward packets to the LAN. If you do, you should allocate the peer an IP number from your LAN's subnet, and use the command enable proxy in your /etc/ppp/ppp.conf file. You should also confirm that the /etc/rc.conf file contains the following: gateway_enable="YES" Which getty? Configuring FreeBSD for Dial-up Services provides a good description on enabling dial-up services using &man.getty.8;. An alternative to getty is mgetty (from comms/mgetty+sendfax port), a smarter version of getty designed with dial-up lines in mind. The advantages of using mgetty is that it actively talks to modems, meaning if port is turned off in /etc/ttys then your modem will not answer the phone. Later versions of mgetty (from 0.99beta onwards) also support the automatic detection of PPP streams, allowing your clients script-less access to your server. Refer to Mgetty and AutoPPP for more information on mgetty. <application>PPP</application> Permissions The ppp command must normally be run as the root user. If however, you wish to allow ppp to run in server mode as a normal user by executing ppp as described below, that user must be given permission to run ppp by adding them to the network group in /etc/group. You will also need to give them access to one or more sections of the configuration file using the allow command: allow users fred mary If this command is used in the default section, it gives the specified users access to everything. PPP Shells for Dynamic-IP Users PPP shells Create a file called /etc/ppp/ppp-shell containing the following: #!/bin/sh IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'` CALLEDAS="$IDENT" TTY=`tty` if [ x$IDENT = xdialup ]; then IDENT=`basename $TTY` fi echo "PPP for $CALLEDAS on $TTY" echo "Starting PPP for $IDENT" exec /usr/sbin/ppp -direct $IDENT This script should be executable. Now make a symbolic link called ppp-dialup to this script using the following commands: &prompt.root; ln -s ppp-shell /etc/ppp/ppp-dialup You should use this script as the shell for all of your dialup users. This is an example from /etc/passwd for a dialup PPP user with username pchilds (remember do not directly edit the password file, use &man.vipw.8;). pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup Create a /home/ppp directory that is world readable containing the following 0 byte files: -r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin -r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts which prevents /etc/motd from being displayed. PPP Shells for Static-IP Users PPP shells Create the ppp-shell file as above, and for each account with statically assigned IPs create a symbolic link to ppp-shell. For example, if you have three dialup customers, fred, sam, and mary, that you route /24 CIDR networks for, you would type the following: &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam &prompt.root; ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary Each of these users dialup accounts should have their shell set to the symbolic link created above (for example, mary's shell should be /etc/ppp/ppp-mary). Setting Up <filename>ppp.conf</filename> for Dynamic-IP Users The /etc/ppp/ppp.conf file should contain something along the lines of: default: set debug phase lcp chat set timeout 0 ttyu0: set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255 enable proxy ttyu1: set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255 enable proxy The indenting is important. The default: section is loaded for each session. For each dialup line enabled in /etc/ttys create an entry similar to the one for ttyu0: above. Each line should get a unique IP address from your pool of IP addresses for dynamic users. Setting Up <filename>ppp.conf</filename> for Static-IP Users Along with the contents of the sample /usr/share/examples/ppp/ppp.conf above you should add a section for each of the statically assigned dialup users. We will continue with our fred, sam, and mary example. fred: set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255 sam: set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255 mary: set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255 The file /etc/ppp/ppp.linkup should also contain routing information for each static IP user if required. The line below would add a route for the 203.14.101.0/24 network via the client's ppp link. fred: add 203.14.101.0 netmask 255.255.255.0 HISADDR sam: add 203.14.102.0 netmask 255.255.255.0 HISADDR mary: add 203.14.103.0 netmask 255.255.255.0 HISADDR <command>mgetty</command> and AutoPPP mgetty AutoPPP LCP By default the comms/mgetty+sendfax port comes with the AUTO_PPP option enabled allowing mgetty to detect the LCP phase of PPP connections and automatically spawn off a ppp shell. However, since the default login/password sequence does not occur it is necessary to authenticate users using either PAP or CHAP. This section assumes the user has successfully compiled, and installed the comms/mgetty+sendfax port on his system. Make sure your /usr/local/etc/mgetty+sendfax/login.config file has the following in it: /AutoPPP/ - - /etc/ppp/ppp-pap-dialup This will tell mgetty to run the ppp-pap-dialup script for detected PPP connections. Create a file called /etc/ppp/ppp-pap-dialup containing the following (the file should be executable): #!/bin/sh exec /usr/sbin/ppp -direct pap$IDENT For each dialup line enabled in /etc/ttys, create a corresponding entry in /etc/ppp/ppp.conf. This will happily co-exist with the definitions we created above. pap: enable pap set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40 enable proxy Each user logging in with this method will need to have a username/password in /etc/ppp/ppp.secret file, or alternatively add the following option to authenticate users via PAP from the /etc/passwd file. enable passwdauth If you wish to assign some users a static IP number, you can specify the number as the third argument in /etc/ppp/ppp.secret. See /usr/share/examples/ppp/ppp.secret.sample for examples. MS Extensions DNS NetBIOS PPP Microsoft extensions It is possible to configure PPP to supply DNS and NetBIOS nameserver addresses on demand. To enable these extensions with PPP version 1.x, the following lines might be added to the relevant section of /etc/ppp/ppp.conf. enable msext set ns 203.14.100.1 203.14.100.2 set nbns 203.14.100.5 And for PPP version 2 and above: accept dns set dns 203.14.100.1 203.14.100.2 set nbns 203.14.100.5 This will tell the clients the primary and secondary name server addresses, and a NetBIOS nameserver host. In version 2 and above, if the set dns line is omitted, PPP will use the values found in /etc/resolv.conf. PAP and CHAP Authentication PAP CHAP Some ISPs set their system up so that the authentication part of your connection is done using either of the PAP or CHAP authentication mechanisms. If this is the case, your ISP will not give a login: prompt when you connect, but will start talking PPP immediately. PAP is less secure than CHAP, but security is not normally an issue here as passwords, although being sent as plain text with PAP, are being transmitted down a serial line only. There is not much room for crackers to eavesdrop. Referring back to the PPP and Static IP addresses or PPP and Dynamic IP addresses sections, the following alterations must be made: 13 set authname MyUserName 14 set authkey MyPassword 15 set login Line 13: This line specifies your PAP/CHAP user name. You will need to insert the correct value for MyUserName. Line 14: - password - - This line specifies your PAP/CHAP password. + This line specifies your PAP/CHAP passwordpassword. You will need to insert the correct value for MyPassword. You may want to add an additional line, such as: 16 accept PAP or 16 accept CHAP to make it obvious that this is the intention, but PAP and CHAP are both accepted by default. Line 15: Your ISP will not normally require that you log into the server if you are using PAP or CHAP. You must therefore disable your set login string. Changing Your <command>ppp</command> Configuration on the Fly It is possible to talk to the ppp program while it is running in the background, but only if a suitable diagnostic port has been set up. To do this, add the following line to your configuration: set server /var/run/ppp-tun%d DiagnosticPassword 0177 This will tell PPP to listen to the specified &unix; domain socket, asking clients for the specified password before allowing access. The %d in the name is replaced with the tun device number that is in use. Once a socket has been set up, the &man.pppctl.8; program may be used in scripts that wish to manipulate the running program. Using PPP Network Address Translation Capability PPPNAT PPP has ability to use internal NAT without kernel diverting capabilities. This functionality may be enabled by the following line in /etc/ppp/ppp.conf: nat enable yes Alternatively, PPP NAT may be enabled by command-line option -nat. There is also /etc/rc.conf knob named ppp_nat, which is enabled by default. If you use this feature, you may also find useful the following /etc/ppp/ppp.conf options to enable incoming connections forwarding: nat port tcp 10.0.0.2:ftp ftp nat port tcp 10.0.0.2:http http or do not trust the outside at all nat deny_incoming yes Final System Configuration PPPconfiguration You now have ppp configured, but there are a few more things to do before it is ready to work. They all involve editing the /etc/rc.conf file. Working from the top down in this file, make sure the hostname= line is set, e.g.: hostname="foo.example.com" If your ISP has supplied you with a static IP address and name, it is probably best that you use this name as your host name. Look for the network_interfaces variable. If you want to configure your system to dial your ISP on demand, make sure the tun0 device is added to the list, otherwise remove it. network_interfaces="lo0 tun0" ifconfig_tun0= The ifconfig_tun0 variable should be empty, and a file called /etc/start_if.tun0 should be created. This file should contain the line: ppp -auto mysystem This script is executed at network configuration time, starting your ppp daemon in automatic mode. If you have a LAN for which this machine is a gateway, you may also wish to use the switch. Refer to the manual page for further details. Make sure that the router program is set to NO with the following line in your /etc/rc.conf: router_enable="NO" routed It is important that the routed daemon is not started, as routed tends to delete the default routing table entries created by ppp. It is probably a good idea to ensure that the sendmail_flags line does not include the option, otherwise sendmail will attempt to do a network lookup every now and then, possibly causing your machine to dial out. You may try: sendmail_flags="-bd" sendmail The downside of this is that you must force sendmail to re-examine the mail queue whenever the ppp link is up by typing: &prompt.root; /usr/sbin/sendmail -q You may wish to use the !bg command in ppp.linkup to do this automatically: 1 provider: 2 delete ALL 3 add 0 0 HISADDR 4 !bg sendmail -bd -q30m SMTP If you do not like this, it is possible to set up a dfilter to block SMTP traffic. Refer to the sample files for further details. All that is left is to reboot the machine. After rebooting, you can now either type: &prompt.root; ppp and then dial provider to start the PPP session, or, if you want ppp to establish sessions automatically when there is outbound traffic (and you have not created the start_if.tun0 script), type: &prompt.root; ppp -auto provider Summary To recap, the following steps are necessary when setting up ppp for the first time: Client side: Ensure that the tun device is built into your kernel. Ensure that the tunN device file is available in the /dev directory. Create an entry in /etc/ppp/ppp.conf. The pmdemand example should suffice for most ISPs. If you have a dynamic IP address, create an entry in /etc/ppp/ppp.linkup. Update your /etc/rc.conf file. Create a start_if.tun0 script if you require demand dialing. Server side: Ensure that the tun device is built into your kernel. Ensure that the tunN device file is available in the /dev directory. Create an entry in /etc/passwd (using the &man.vipw.8; program). Create a profile in this users home directory that runs ppp -direct direct-server or similar. Create an entry in /etc/ppp/ppp.conf. The direct-server example should suffice. Create an entry in /etc/ppp/ppp.linkup. Update your /etc/rc.conf file. Gennady B. Sorokopud Parts originally contributed by Robert Huff Using Kernel PPP This section applies and is valid only for &os; 7.X. Setting Up Kernel PPP PPP kernel PPP Before you start setting up PPP on your machine, make sure that pppd is located in /usr/sbin and the directory /etc/ppp exists. pppd can work in two modes: As a client — you want to connect your machine to the outside world via a PPP serial connection or modem line. PPP server As a server — your machine is located on the network, and is used to connect other computers using PPP. In both cases you will need to set up an options file (/etc/ppp/options or ~/.ppprc if you have more than one user on your machine that uses PPP). You will also need some modem/serial software (preferably comms/kermit), so you can dial and establish a connection with the remote host. Trev Roydhouse Based on information provided by Using <command>pppd</command> as a Client PPP client Cisco The following /etc/ppp/options might be used to connect to a Cisco terminal server PPP line. crtscts # enable hardware flow control modem # modem control line noipdefault # remote PPP server must supply your IP address # if the remote host does not send your IP during IPCP # negotiation, remove this option passive # wait for LCP packets domain ppp.foo.com # put your domain name here :remote_ip # put the IP of remote PPP host here # it will be used to route packets via PPP link # if you didn't specified the noipdefault option # change this line to local_ip:remote_ip defaultroute # put this if you want that PPP server will be your # default router To connect: Kermit modem Dial to the remote host using Kermit (or some other modem program), and enter your user name and password (or whatever is needed to enable PPP on the remote host). Exit Kermit (without hanging up the line). Enter the following: &prompt.root; /usr/sbin/pppd /dev/tty01 19200 Be sure to use the appropriate speed and device name. Now your computer is connected with PPP. If the connection fails, you can add the option to the /etc/ppp/options file, and check console messages to track the problem. Following /etc/ppp/pppup script will make all 3 stages automatic: #!/bin/sh pgrep -l pppd pid=`pgrep pppd` if [ "X${pid}" != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill ${pid} fi pgrep -l kermit pid=`pgrep kermit` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi ifconfig ppp0 down ifconfig ppp0 delete kermit -y /etc/ppp/kermit.dial pppd /dev/tty01 19200 Kermit /etc/ppp/kermit.dial is a Kermit script that dials and makes all necessary authorization on the remote host (an example of such a script is attached to the end of this document). Use the following /etc/ppp/pppdown script to disconnect the PPP line: #!/bin/sh pid=`pgrep pppd` if [ X${pid} != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill -TERM ${pid} fi pgrep -l kermit pid=`pgrep kermit` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi /sbin/ifconfig ppp0 down /sbin/ifconfig ppp0 delete kermit -y /etc/ppp/kermit.hup /etc/ppp/ppptest Check to see if pppd is still running by executing /usr/etc/ppp/ppptest, which should look like this: #!/bin/sh pid=`pgrep pppd` if [ X${pid} != "X" ] ; then echo 'pppd running: PID=' ${pid-NONE} else echo 'No pppd running.' fi set -x netstat -n -I ppp0 ifconfig ppp0 To hang up the modem, execute /etc/ppp/kermit.hup, which should contain: set line /dev/tty01 ; put your modem device here set speed 19200 set file type binary set file names literal set win 8 set rec pack 1024 set send pack 1024 set block 3 set term bytesize 8 set command bytesize 8 set flow none pau 1 out +++ inp 5 OK out ATH0\13 echo \13 exit Here is an alternate method using chat instead of kermit: The following two files are sufficient to accomplish a pppd connection. /etc/ppp/options: /dev/cuad1 115200 crtscts # enable hardware flow control modem # modem control line connect "/usr/bin/chat -f /etc/ppp/login.chat.script" noipdefault # remote PPP serve must supply your IP address # if the remote host doesn't send your IP during # IPCP negotiation, remove this option passive # wait for LCP packets domain your.domain # put your domain name here : # put the IP of remote PPP host here # it will be used to route packets via PPP link # if you didn't specified the noipdefault option # change this line to local_ip:remote_ip defaultroute # put this if you want that PPP server will be # your default router /etc/ppp/login.chat.script: The following should go on a single line. ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDTphone.number CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: login-id TIMEOUT 5 sword: password Once these are installed and modified correctly, all you need to do is run pppd, like so: &prompt.root; pppd Using <command>pppd</command> as a Server /etc/ppp/options should contain something similar to the following: crtscts # Hardware flow control netmask 255.255.255.0 # netmask (not required) 192.114.208.20:192.114.208.165 # IP's of local and remote hosts # local ip must be different from one # you assigned to the Ethernet (or other) # interface on your machine. # remote IP is IP address that will be # assigned to the remote machine domain ppp.foo.com # your domain passive # wait for LCP modem # modem line The following /etc/ppp/pppserv script will tell pppd to behave as a server: #!/bin/sh pgrep -l pppd pid=`pgrep pppd` if [ "X${pid}" != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill ${pid} fi pgrep -l kermit pid=`pgrep kermit` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi # reset ppp interface ifconfig ppp0 down ifconfig ppp0 delete # enable autoanswer mode kermit -y /etc/ppp/kermit.ans # run ppp pppd /dev/tty01 19200 Use this /etc/ppp/pppservdown script to stop the server: #!/bin/sh pgrep -l pppd pid=`pgrep pppd` if [ "X${pid}" != "X" ] ; then echo 'killing pppd, PID=' ${pid} kill ${pid} fi pgrep -l kermit pid=`pgrep kermit` if [ "X${pid}" != "X" ] ; then echo 'killing kermit, PID=' ${pid} kill -9 ${pid} fi ifconfig ppp0 down ifconfig ppp0 delete kermit -y /etc/ppp/kermit.noans The following Kermit script (/etc/ppp/kermit.ans) will enable/disable autoanswer mode on your modem. It should look like this: set line /dev/tty01 set speed 19200 set file type binary set file names literal set win 8 set rec pack 1024 set send pack 1024 set block 3 set term bytesize 8 set command bytesize 8 set flow none pau 1 out +++ inp 5 OK out ATH0\13 inp 5 OK echo \13 out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable ; autoanswer mode inp 5 OK echo \13 exit A script named /etc/ppp/kermit.dial is used for dialing and authenticating on the remote host. You will need to customize it for your needs. Put your login and password in this script; you will also need to change the input statement depending on responses from your modem and remote host. ; ; put the com line attached to the modem here: ; set line /dev/tty01 ; ; put the modem speed here: ; set speed 19200 set file type binary ; full 8 bit file xfer set file names literal set win 8 set rec pack 1024 set send pack 1024 set block 3 set term bytesize 8 set command bytesize 8 set flow none set modem hayes set dial hangup off set carrier auto ; Then SET CARRIER if necessary, set dial display on ; Then SET DIAL if necessary, set input echo on set input timeout proceed set input case ignore def \%x 0 ; login prompt counter goto slhup :slcmd ; put the modem in command mode echo Put the modem in command mode. clear ; Clear unread characters from input buffer pause 1 output +++ ; hayes escape sequence input 1 OK\13\10 ; wait for OK if success goto slhup output \13 pause 1 output at\13 input 1 OK\13\10 if fail goto slcmd ; if modem doesn't answer OK, try again :slhup ; hang up the phone clear ; Clear unread characters from input buffer pause 1 echo Hanging up the phone. output ath0\13 ; hayes command for on hook input 2 OK\13\10 if fail goto slcmd ; if no OK answer, put modem in command mode :sldial ; dial the number pause 1 echo Dialing. output atdt9,550311\13\10 ; put phone number here assign \%x 0 ; zero the time counter :look clear ; Clear unread characters from input buffer increment \%x ; Count the seconds input 1 {CONNECT } if success goto sllogin reinput 1 {NO CARRIER\13\10} if success goto sldial reinput 1 {NO DIALTONE\13\10} if success goto slnodial reinput 1 {\255} if success goto slhup reinput 1 {\127} if success goto slhup if < \%x 60 goto look else goto slhup :sllogin ; login assign \%x 0 ; zero the time counter pause 1 echo Looking for login prompt. :slloop increment \%x ; Count the seconds clear ; Clear unread characters from input buffer output \13 ; ; put your expected login prompt here: ; input 1 {Username: } if success goto sluid reinput 1 {\255} if success goto slhup reinput 1 {\127} if success goto slhup if < \%x 10 goto slloop ; try 10 times to get a login prompt else goto slhup ; hang up and start again if 10 failures :sluid ; ; put your userid here: ; output ppp-login\13 input 1 {Password: } ; ; put your password here: ; output ppp-password\13 input 1 {Entering SLIP mode.} echo quit :slnodial echo \7No dialtone. Check the telephone line!\7 exit 1 ; local variables: ; mode: csh ; comment-start: "; " ; comment-start-skip: "; " ; end: Tom Rhodes Contributed by Troubleshooting <acronym>PPP</acronym> Connections PPP troubleshooting This section covers a few issues which may arise when using PPP over a modem connection. For instance, perhaps you need to know exactly what prompts the system you are dialing into will present. Some ISPs present the ssword prompt, and others will present password; if the ppp script is not written accordingly, the login attempt will fail. The most common way to debug ppp connections is by connecting manually. The following information will walk you through a manual connection step by step. Check the Device Nodes When using a custom kernel, make sure to include the following line in your kernel configuration file: device uart The uart device is already included in the GENERIC kernel, so no additional steps are necessary in this case. Just check the dmesg output for the modem device with: &prompt.root; dmesg | grep uart You should get some pertinent output about the uart devices. These are the COM ports we need. If your modem acts like a standard serial port then you should see it listed on uart1, or COM2. If so, you are not required to rebuild the kernel. When matching up sio modem is on uart1 or COM2 if you are in DOS, then your modem device would be /dev/cuau1. Connecting Manually Connecting to the Internet by manually controlling ppp is quick, easy, and a great way to debug a connection or just get information on how your ISP treats ppp client connections. Lets start PPP from the command line. Note that in all of our examples we will use example as the hostname of the machine running PPP. You start ppp by just typing ppp: &prompt.root; ppp We have now started ppp. ppp ON example> set device /dev/cuau1 We set our modem device, in this case it is cuau1. ppp ON example> set speed 115200 Set the connection speed, in this case we are using 115,200 kbps. ppp ON example> enable dns Tell ppp to configure our resolver and add the nameserver lines to /etc/resolv.conf. If ppp cannot determine our hostname, we can set one manually later. ppp ON example> term Switch to terminal mode so that we can manually control the modem. deflink: Entering terminal mode on /dev/cuau1 type '~h' for help at OK atdt123456789 Use at to initialize the modem, then use atdt and the number for your ISP to begin the dial in process. CONNECT Confirmation of the connection, if we are going to have any connection problems, unrelated to hardware, here is where we will attempt to resolve them. ISP Login:myusername Here you are prompted for a username, return the prompt with the username that was provided by the ISP. ISP Pass:mypassword This time we are prompted for a password, just reply with the password that was provided by the ISP. Just like logging into &os;, the password will not echo. Shell or PPP:ppp Depending on your ISP this prompt may never appear. Here we are being asked if we wish to use a shell on the provider, or to start ppp. In this example, we have chosen to use ppp as we want an Internet connection. Ppp ON example> Notice that in this example the first has been capitalized. This shows that we have successfully connected to the ISP. PPp ON example> We have successfully authenticated with our ISP and are waiting for the assigned IP address. PPP ON example> We have made an agreement on an IP address and successfully completed our connection. PPP ON example>add default HISADDR Here we add our default route, we need to do this before we can talk to the outside world as currently the only established connection is with the peer. If this fails due to existing routes you can put a bang character ! in front of the . Alternatively, you can set this before making the actual connection and it will negotiate a new route accordingly. If everything went good we should now have an active connection to the Internet, which could be thrown into the background using CTRL z If you notice the PPP return to ppp then we have lost our connection. This is good to know because it shows our connection status. Capital P's show that we have a connection to the ISP and lowercase p's show that the connection has been lost for whatever reason. ppp only has these 2 states. Debugging If you have a direct line and cannot seem to make a connection, then turn hardware flow CTS/RTS to off with the . This is mainly the case if you are connected to some PPP capable terminal servers, where PPP hangs when it tries to write data to your communication link, so it would be waiting for a CTS, or Clear To Send signal which may never come. If you use this option however, you should also use the option, which may be required to defeat hardware dependent on passing certain characters from end to end, most of the time XON/XOFF. See the &man.ppp.8; manual page for more information on this option, and how it is used. If you have an older modem, you may need to use the . Parity is set at none be default, but is used for error checking (with a large increase in traffic) on older modems and some ISPs. You may need this option for the Compuserve ISP. PPP may not return to the command mode, which is usually a negotiation error where the ISP is waiting for your side to start negotiating. At this point, using the ~p command will force ppp to start sending the configuration information. If you never obtain a login prompt, then most likely you need to use PAP or CHAP authentication instead of the &unix; style in the example above. To use PAP or CHAP just add the following options to PPP before going into terminal mode: ppp ON example> set authname myusername Where myusername should be replaced with the username that was assigned by the ISP. ppp ON example> set authkey mypassword Where mypassword should be replaced with the password that was assigned by the ISP. If you connect fine, but cannot seem to find any domain name, try to use &man.ping.8; with an IP address and see if you can get any return information. If you experience 100 percent (100%) packet loss, then it is most likely that you were not assigned a default route. Double check that the option was set during the connection. If you can connect to a remote IP address then it is possible that a resolver address has not been added to the /etc/resolv.conf. This file should look like: domain example.com nameserver x.x.x.x nameserver y.y.y.y Where x.x.x.x and y.y.y.y should be replaced with the IP address of your ISP's DNS servers. This information may or may not have been provided when you signed up, but a quick call to your ISP should remedy that. You could also have &man.syslog.3; provide a logging function for your PPP connection. Just add: !ppp *.* /var/log/ppp.log to /etc/syslog.conf. In most cases, this functionality already exists. Jim Mock Contributed (from http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by Using PPP over Ethernet (PPPoE) PPP over Ethernet PPPoE PPP, over Ethernet This section describes how to set up PPP over Ethernet (PPPoE). Configuring the Kernel No kernel configuration is necessary for PPPoE any longer. If the necessary netgraph support is not built into the kernel, it will be dynamically loaded by ppp. Setting Up <filename>ppp.conf</filename> Here is an example of a working ppp.conf: default: set log Phase tun command # you can add more detailed logging if you wish set ifaddr 10.0.0.1/0 10.0.0.2/0 name_of_service_provider: set device PPPoE:xl1 # replace xl1 with your Ethernet device set authname YOURLOGINNAME set authkey YOURPASSWORD set dial set login add default HISADDR Running <application>ppp</application> As root, you can run: &prompt.root; ppp -ddial name_of_service_provider Starting <application>ppp</application> at Boot Add the following to your /etc/rc.conf file: ppp_enable="YES" ppp_mode="ddial" ppp_nat="YES" # if you want to enable nat for your local network, otherwise NO ppp_profile="name_of_service_provider" Using a PPPoE Service Tag Sometimes it will be necessary to use a service tag to establish your connection. Service tags are used to distinguish between different PPPoE servers attached to a given network. You should have been given any required service tag information in the documentation provided by your ISP. If you cannot locate it there, ask your ISP's tech support personnel. As a last resort, you could try the method suggested by the Roaring Penguin PPPoE program which can be found in the Ports Collection. Bear in mind however, this may de-program your modem and render it useless, so think twice before doing it. Simply install the program shipped with the modem by your provider. Then, access the System menu from the program. The name of your profile should be listed there. It is usually ISP. The profile name (service tag) will be used in the PPPoE configuration entry in ppp.conf as the provider part of the set device command (see the &man.ppp.8; manual page for full details). It should look like this: set device PPPoE:xl1:ISP Do not forget to change xl1 to the proper device for your Ethernet card. Do not forget to change ISP to the profile you have just found above. For additional information, see: Cheaper Broadband with FreeBSD on DSL by Renaud Waldura. PPPoE with a &tm.3com; <trademark class="registered">HomeConnect</trademark> ADSL Modem Dual Link This modem does not follow RFC 2516 (A Method for transmitting PPP over Ethernet (PPPoE), written by L. Mamakos, K. Lidl, J. Evarts, D. Carrel, D. Simone, and R. Wheeler). Instead, different packet type codes have been used for the Ethernet frames. Please complain to 3Com if you think it should comply with the PPPoE specification. In order to make FreeBSD capable of communicating with this device, a sysctl must be set. This can be done automatically at boot time by updating /etc/sysctl.conf: net.graph.nonstandard_pppoe=1 or can be done immediately with the command: &prompt.root; sysctl net.graph.nonstandard_pppoe=1 Unfortunately, because this is a system-wide setting, it is not possible to talk to a normal PPPoE client or server and a &tm.3com; HomeConnect ADSL Modem at the same time. Using <application>PPP</application> over ATM (PPPoA) PPP over ATM PPPoA PPP, over ATM The following describes how to set up PPP over ATM (PPPoA). PPPoA is a popular choice among European DSL providers. Using PPPoA with the Alcatel &speedtouch; USB PPPoA support for this device is supplied as a port in FreeBSD because the firmware is distributed under Alcatel's license agreement and can not be redistributed freely with the base system of FreeBSD. To install the software, simply use the Ports Collection. Install the net/pppoa port and follow the instructions provided with it. Like many USB devices, the Alcatel &speedtouch; USB needs to download firmware from the host computer to operate properly. It is possible to automate this process in &os; so that this transfer takes place whenever the device is plugged into a USB port. The following information can be added to the /etc/usbd.conf file to enable this automatic firmware transfer. This file must be edited as the root user. device "Alcatel SpeedTouch USB" devname "ugen[0-9]+" vendor 0x06b9 product 0x4061 attach "/usr/local/sbin/modem_run -f /usr/local/libdata/mgmt.o" To enable the USB daemon, usbd, put the following the line into /etc/rc.conf: usbd_enable="YES" It is also possible to set up ppp to dial up at startup. To do this add the following lines to /etc/rc.conf. Again, for this procedure you will need to be logged in as the root user. ppp_enable="YES" ppp_mode="ddial" ppp_profile="adsl" For this to work correctly you will need to have used the sample ppp.conf which is supplied with the net/pppoa port. Using mpd You can use mpd to connect to a variety of services, in particular PPTP services. You can find mpd in the Ports Collection, net/mpd. Many ADSL modems require that a PPTP tunnel is created between the modem and computer, one such modem is the Alcatel &speedtouch; Home. First you must install the port, and then you can configure mpd to suit your requirements and provider settings. The port places a set of sample configuration files which are well documented in PREFIX/etc/mpd/. Note here that PREFIX means the directory into which your ports are installed, this defaults to /usr/local/. A complete guide to configure mpd is available in HTML format once the port has been installed. It is placed in PREFIX/share/doc/mpd/. Here is a sample configuration for connecting to an ADSL service with mpd. The configuration is spread over two files, first the mpd.conf: This example of the mpd.conf file only works with mpd 4.x. default: load adsl adsl: new -i ng0 adsl adsl set bundle authname username set bundle password password set bundle disable multilink set link no pap acfcomp protocomp set link disable chap set link accept chap set link keep-alive 30 10 set ipcp no vjcomp set ipcp ranges 0.0.0.0/0 0.0.0.0/0 set iface route default set iface disable on-demand set iface enable proxy-arp set iface idle 0 open The username used to authenticate with your ISP. The password used to authenticate with your ISP. The mpd.links file contains information about the link, or links, you wish to establish. An example mpd.links to accompany the above example is given beneath: adsl: set link type pptp set pptp mode active set pptp enable originate outcall set pptp self 10.0.0.1 set pptp peer 10.0.0.138 The IP address of your &os; computer which you will be using mpd from. The IP address of your ADSL modem. For the Alcatel &speedtouch; Home this address defaults to 10.0.0.138. It is possible to initialize the connection easily by issuing the following command as root: &prompt.root; mpd -b adsl You can see the status of the connection with the following command: &prompt.user; ifconfig ng0 ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff Using mpd is the recommended way to connect to an ADSL service with &os;. Using pptpclient It is also possible to use FreeBSD to connect to other PPPoA services using net/pptpclient. To use net/pptpclient to connect to a DSL service, install the port or package and edit your /etc/ppp/ppp.conf. You will need to be root to perform both of these operations. An example section of ppp.conf is given below. For further information on ppp.conf options consult the ppp manual page, &man.ppp.8;. adsl: set log phase chat lcp ipcp ccp tun command set timeout 0 enable dns set authname username set authkey password set ifaddr 0 0 add default HISADDR The username of your account with the DSL provider. The password for your account. Because you must put your account's password in the ppp.conf file in plain text form you should make sure than nobody can read the contents of this file. The following series of commands will make sure the file is only readable by the root account. Refer to the manual pages for &man.chmod.1; and &man.chown.8; for further information. &prompt.root; chown root:wheel /etc/ppp/ppp.conf &prompt.root; chmod 600 /etc/ppp/ppp.conf This will open a tunnel for a PPP session to your DSL router. Ethernet DSL modems have a preconfigured LAN IP address which you connect to. In the case of the Alcatel &speedtouch; Home this address is 10.0.0.138. Your router documentation should tell you which address your device uses. To open the tunnel and start a PPP session execute the following command: &prompt.root; pptp address adsl You may wish to add an ampersand (&) to the end of the previous command because pptp will not return your prompt to you otherwise. A tun virtual tunnel device will be created for interaction between the pptp and ppp processes. Once you have been returned to your prompt, or the pptp process has confirmed a connection you can examine the tunnel like so: &prompt.user; ifconfig tun0 tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00 Opened by PID 918 If you are unable to connect, check the configuration of your router, which is usually accessible via telnet or with a web browser. If you still cannot connect you should examine the output of the pptp command and the contents of the ppp log file, /var/log/ppp.log for clues. Satoshi Asami Originally contributed by Guy Helmer With input from Piero Serini Using SLIP SLIP This section applies and is valid only for &os; 7.X. Setting Up a SLIP Client SLIP client The following is one way to set up a FreeBSD machine for SLIP on a static host network. For dynamic hostname assignments (your address changes each time you dial up), you probably need to have a more complex setup. First, determine which serial port your modem is connected to. Many people set up a symbolic link, such as /dev/modem, to point to the real device name, /dev/cuadN. This allows you to abstract the actual device name should you ever need to move the modem to a different port. It can become quite cumbersome when you need to fix a bunch of files in /etc and .kermrc files all over the system! /dev/cuad0 is COM1, /dev/cuad1 is COM2, etc. Make sure you have the following in your kernel configuration file: device sl It is included in the GENERIC kernel, so this should not be a problem unless you have deleted it. Things You Have to Do Only Once Add your home machine, the gateway and nameservers to your /etc/hosts file. Ours looks like this: 127.0.0.1 localhost loghost 136.152.64.181 water.CS.Example.EDU water.CS water 136.152.64.1 inr-3.CS.Example.EDU inr-3 slip-gateway 128.32.136.9 ns1.Example.EDU ns1 128.32.136.12 ns2.Example.EDU ns2 Make sure you have files before dns in the hosts: section of your /etc/nsswitch.conf file. Without these parameters funny things may happen. Edit the /etc/rc.conf file. Set your hostname by editing the line that says: hostname="myname.my.domain" Your machine's full Internet hostname should be placed here. default route Designate the default router by changing the line: defaultrouter="NO" to: defaultrouter="slip-gateway" Make a file /etc/resolv.conf which contains: domain CS.Example.EDU nameserver 128.32.136.9 nameserver 128.32.136.12 nameserver domain name As you can see, these set up the nameserver hosts. Of course, the actual domain names and addresses depend on your environment. Set the password for root and toor (and any other accounts that do not have a password). Reboot your machine and make sure it comes up with the correct hostname. Making a SLIP Connection SLIP connecting with Dial up, type slip at the prompt, enter your machine name and password. What is required to be entered depends on your environment. If you use Kermit, you can try a script like this: # kermit setup set modem hayes set line /dev/modem set speed 115200 set parity none set flow rts/cts set terminal bytesize 8 set file type binary # The next macro will dial up and login define slip dial 643-9600, input 10 =>, if failure stop, - output slip\x0d, input 10 Username:, if failure stop, - output silvia\x0d, input 10 Password:, if failure stop, - output ***\x0d, echo \x0aCONNECTED\x0a Of course, you have to change the username and password to fit yours. After doing so, you can just type slip from the Kermit prompt to connect. Leaving your password in plain text anywhere in the filesystem is generally a bad idea. Do it at your own risk. Leave the Kermit there (you can suspend it by Ctrl z ) and as root, type: &prompt.root; slattach -h -c -s 115200 /dev/modem If you are able to ping hosts on the other side of the router, you are connected! If it does not work, you might want to try instead of as an argument to slattach. How to Shutdown the Connection Do the following: &prompt.root; kill -INT `cat /var/run/slattach.modem.pid` to kill slattach. Keep in mind you must be root to do the above. Then go back to kermit (by running fg if you suspended it) and exit from it (q). The &man.slattach.8; manual page says you have to use ifconfig sl0 down to mark the interface down, but this does not seem to make any difference. (ifconfig sl0 reports the same thing.) Some times, your modem might refuse to drop the carrier. In that case, simply start kermit and quit it again. It usually goes out on the second try. Troubleshooting If it does not work, feel free to ask on &a.net.name; mailing list. The things that people tripped over so far: Not using or in slattach (This should not be fatal, but some users have reported that this solves their problems.) Using instead of (might be hard to see the difference on some fonts). Try ifconfig sl0 to see your interface status. For example, you might get: &prompt.root; ifconfig sl0 sl0: flags=10<POINTOPOINT> inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00 If you get no route to host messages from &man.ping.8;, there may be a problem with your routing table. You can use the netstat -r command to display the current routes : &prompt.root; netstat -r Routing tables Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks: (root node) (root node) Route Tree for Protocol Family inet: (root node) => default inr-3.Example.EDU UG 8 224515 sl0 - - localhost.Exampl localhost.Example. UH 5 42127 lo0 - 0.438 inr-3.Example.ED water.CS.Example.E UH 1 0 sl0 - - water.CS.Example localhost.Example. UGH 34 47641234 lo0 - 0.438 (root node) The preceding examples are from a relatively busy system. The numbers on your system will vary depending on network activity. Setting Up a SLIP Server SLIP server This document provides suggestions for setting up SLIP Server services on a FreeBSD system, which typically means configuring your system to automatically start up connections upon login for remote SLIP clients. Prerequisites TCP/IP networking This section is very technical in nature, so background knowledge is required. It is assumed that you are familiar with the TCP/IP network protocol, and in particular, network and node addressing, network address masks, subnetting, routing, and routing protocols, such as RIP. Configuring SLIP services on a dial-up server requires a knowledge of these concepts, and if you are not familiar with them, please read a copy of either Craig Hunt's TCP/IP Network Administration published by O'Reilly & Associates, Inc. (ISBN Number 0-937175-82-X), or Douglas Comer's books on the TCP/IP protocol. modem It is further assumed that you have already set up your modem(s) and configured the appropriate system files to allow logins through your modems. If you have not prepared your system for this yet, please see for details on dialup services configuration. You may also want to check the manual pages or &man.sio.4; for information on the serial port device driver and &man.ttys.5;, &man.gettytab.5;, &man.getty.8;, & &man.init.8; for information relevant to configuring the system to accept logins on modems, and perhaps &man.stty.1; for information on setting serial port parameters (such as clocal for directly-connected serial interfaces). Quick Overview In its typical configuration, using FreeBSD as a SLIP server works as follows: a SLIP user dials up your FreeBSD SLIP Server system and logs in with a special SLIP login ID that uses /usr/sbin/sliplogin as the special user's shell. The sliplogin program browses the file /etc/sliphome/slip.hosts to find a matching line for the special user, and if it finds a match, connects the serial line to an available SLIP interface and then runs the shell script /etc/sliphome/slip.login to configure the SLIP interface. An Example of a SLIP Server Login For example, if a SLIP user ID were Shelmerg, Shelmerg's entry in /etc/master.passwd would look something like this: Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin When Shelmerg logs in, sliplogin will search /etc/sliphome/slip.hosts for a line that had a matching user ID; for example, there may be a line in /etc/sliphome/slip.hosts that reads: Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp sliplogin will find that matching line, hook the serial line into the next available SLIP interface, and then execute /etc/sliphome/slip.login like this: /etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp If all goes well, /etc/sliphome/slip.login will issue an ifconfig for the SLIP interface to which sliplogin attached itself (SLIP interface 0, in the above example, which was the first parameter in the list given to slip.login) to set the local IP address (dc-slip), remote IP address (sl-helmer), network mask for the SLIP interface (0xfffffc00), and any additional flags (autocomp). If something goes wrong, sliplogin usually logs good informational messages via the syslogd daemon facility, which usually logs to /var/log/messages (see the manual pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps check /etc/syslog.conf to see to what syslogd is logging and where it is logging to). Kernel Configuration kernel configuration SLIP &os;'s default kernel (GENERIC) comes with SLIP (&man.sl.4;) support; in case of a custom kernel, you have to add the following line to your kernel configuration file: device sl By default, your &os; machine will not forward packets. If you want your FreeBSD SLIP Server to act as a router, you will have to edit the /etc/rc.conf file and change the setting of the gateway_enable variable to . This will make sure that setting the routing option will be persistent after a reboot. To apply the settings immediately you can execute the following command as root: &prompt.root; service routing start Please refer to on Configuring the FreeBSD Kernel for help in reconfiguring your kernel. Sliplogin Configuration As mentioned earlier, there are three files in the /etc/sliphome directory that are part of the configuration for /usr/sbin/sliplogin (see &man.sliplogin.8; for the actual manual page for sliplogin): slip.hosts, which defines the SLIP users and their associated IP addresses; slip.login, which usually just configures the SLIP interface; and (optionally) slip.logout, which undoes slip.login's effects when the serial connection is terminated. <filename>slip.hosts</filename> Configuration /etc/sliphome/slip.hosts contains lines which have at least four items separated by whitespace: SLIP user's login ID Local address (local to the SLIP server) of the SLIP link Remote address of the SLIP link Network mask The local and remote addresses may be host names (resolved to IP addresses by /etc/hosts or by the domain name service, depending on your specifications in the file /etc/nsswitch.conf), and the network mask may be a name that can be resolved by a lookup into /etc/networks. On a sample system, /etc/sliphome/slip.hosts looks like this: # # login local-addr remote-addr mask opt1 opt2 # (normal,compress,noicmp) # Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp At the end of the line is one or more of the options: — no header compression — compress headers — compress headers if the remote end allows it — disable ICMP packets (so any ping packets will be dropped instead of using up your bandwidth) SLIP TCP/IP networking Your choice of local and remote addresses for your SLIP links depends on whether you are going to dedicate a TCP/IP subnet or if you are going to use proxy ARP on your SLIP server (it is not true proxy ARP, but that is the terminology used in this section to describe it). If you are not sure which method to select or how to assign IP addresses, please refer to the TCP/IP books referenced in the SLIP Prerequisites () and/or consult your IP network manager. If you are going to use a separate subnet for your SLIP clients, you will need to allocate the subnet number out of your assigned IP network number and assign each of your SLIP client's IP numbers out of that subnet. Then, you will probably need to configure a static route to the SLIP subnet via your SLIP server on your nearest IP router. Ethernet Otherwise, if you will use the proxy ARP method, you will need to assign your SLIP client's IP addresses out of your SLIP server's Ethernet subnet, and you will also need to adjust your /etc/sliphome/slip.login and /etc/sliphome/slip.logout scripts to use &man.arp.8; to manage the proxy ARP entries in the SLIP server's ARP table. <filename>slip.login</filename> Configuration The typical /etc/sliphome/slip.login file looks like this: #!/bin/sh - # # @(#)slip.login 5.1 (Berkeley) 7/1/90 # # generic login file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 inet $4 $5 netmask $6 This slip.login file merely runs ifconfig for the appropriate SLIP interface with the local and remote addresses and network mask of the SLIP interface. If you have decided to use the proxy ARP method (instead of using a separate subnet for your SLIP clients), your /etc/sliphome/slip.login file will need to look something like this: #!/bin/sh - # # @(#)slip.login 5.1 (Berkeley) 7/1/90 # # generic login file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 inet $4 $5 netmask $6 # Answer ARP requests for the SLIP client with our Ethernet addr /usr/sbin/arp -s $5 00:11:22:33:44:55 pub The additional line in this slip.login, arp -s $5 00:11:22:33:44:55 pub, creates an ARP entry in the SLIP server's ARP table. This ARP entry causes the SLIP server to respond with the SLIP server's Ethernet MAC address whenever another IP node on the Ethernet asks to speak to the SLIP client's IP address. Ethernet MAC address When using the example above, be sure to replace the Ethernet MAC address (00:11:22:33:44:55) with the MAC address of your system's Ethernet card, or your proxy ARP will definitely not work! You can discover your SLIP server's Ethernet MAC address by looking at the results of running netstat -i; the second line of the output should look something like: ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116 This indicates that this particular system's Ethernet MAC address is 00:02:c1:28:5f:4a — the periods in the Ethernet MAC address given by netstat -i must be changed to colons and leading zeros should be added to each single-digit hexadecimal number to convert the address into the form that &man.arp.8; desires; see the manual page on &man.arp.8; for complete information on usage. When you create /etc/sliphome/slip.login and /etc/sliphome/slip.logout, the execute bit (i.e., chmod 755 /etc/sliphome/slip.login /etc/sliphome/slip.logout) must be set, or sliplogin will be unable to execute it. <filename>slip.logout</filename> Configuration /etc/sliphome/slip.logout is not strictly needed (unless you are implementing proxy ARP), but if you decide to create it, this is an example of a basic slip.logout script: #!/bin/sh - # # slip.logout # # logout file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 down If you are using proxy ARP, you will want to have /etc/sliphome/slip.logout remove the ARP entry for the SLIP client: #!/bin/sh - # # @(#)slip.logout # # logout file for a slip line. sliplogin invokes this with # the parameters: # 1 2 3 4 5 6 7-n # slipunit ttyspeed loginname local-addr remote-addr mask opt-args # /sbin/ifconfig sl$1 down # Quit answering ARP requests for the SLIP client /usr/sbin/arp -d $5 The arp -d $5 removes the ARP entry that the proxy ARP slip.login added when the SLIP client logged in. It bears repeating: make sure /etc/sliphome/slip.logout has the execute bit set after you create it (i.e., chmod 755 /etc/sliphome/slip.logout). Routing Considerations SLIP routing If you are not using the proxy ARP method for routing packets between your SLIP clients and the rest of your network (and perhaps the Internet), you will probably have to add static routes to your closest default router(s) to route your SLIP clients subnet via your SLIP server. Static Routes static routes Adding static routes to your nearest default routers can be troublesome (or impossible if you do not have authority to do so...). If you have a multiple-router network in your organization, some routers, such as those made by Cisco and Proteon, may not only need to be configured with the static route to the SLIP subnet, but also need to be told which static routes to tell other routers about, so some expertise and troubleshooting/tweaking may be necessary to get static-route-based routing to work. diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.xml b/en_US.ISO8859-1/books/handbook/printing/chapter.xml index a368f5ad9a..caf27d4416 100644 --- a/en_US.ISO8859-1/books/handbook/printing/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/printing/chapter.xml @@ -1,5171 +1,5125 @@ Sean Kelly Contributed by Jim Mock Restructured and updated by Printing Synopsis LPD spooling system printing &os; can be used to print with a wide variety of printers, from the oldest impact printer to the latest laser printers, and everything in between, allowing you to produce high-quality printed output from the applications you run. &os; can also be configured to act as a print server on a network; in this capacity &os; can receive print jobs from a variety of other computers, including other &os; computers, &windows; and &macos; hosts. &os; will ensure that one job at a time is printed, and can keep statistics on which users and machines are doing the most printing, produce banner pages showing whose printout is whose, and more. After reading this chapter, you will know: How to configure the &os; print spooler. How to install print filters, to handle special print jobs differently, including converting incoming documents to print formats that your printers understand. How to enable header, or banner pages on your printout. How to print with printers connected to other computers. How to print with printers connected directly to the network. How to control printer restrictions, including limiting the size of print jobs, and preventing certain users from printing. How to keep printer statistics, and account for printer usage. How to troubleshoot printing problems. Before reading this chapter, you should: Know how to configure and install a new kernel (). Introduction In order to use printers with &os; you may set them up to work with the Berkeley line printer spooling system, also known as the LPD spooling system, or just LPD. It is the standard printer control system in &os;. This chapter introduces LPD and will guide you through its configuration. If you are already familiar with LPD or another printer spooling system, you may wish to skip to section Basic Setup. LPD controls everything about a host's printers. It is responsible for a number of things: It controls access to attached printers and printers attached to other hosts on the network. - print jobs - It enables users to submit files to be printed; these - submissions are known as jobs. + submissions are known as jobsprint jobs. It prevents multiple users from accessing a printer at the same time by maintaining a queue for each printer. It can print header pages (also known as banner or burst pages) so users can easily find jobs they have printed in a stack of printouts. It takes care of communications parameters for printers connected on serial ports. It can send jobs over the network to a LPD spooler on another host. It can run special filters to format jobs to be printed for various printer languages or printer capabilities. It can account for printer usage. Through a configuration file (/etc/printcap), and by providing the special filter programs, you can enable the LPD system to do all or some subset of the above for a great variety of printer hardware. Why You Should Use the Spooler The spooler still provides benefit on a single-user system and should be used because: LPD prints jobs in the background; you do not have to wait for data to be copied to the printer. - &tex; - LPD can conveniently run a job to be printed through filters to add date/time - headers or convert a special file format (such as a &tex; + headers or convert a special file format (such as a &tex;&tex; DVI file) into a format the printer will understand. You will not have to do these steps manually. Many free and commercial programs that provide a print feature usually expect to talk to the spooler on your system. By setting up the spooling system, you will more easily support other software you may later add or already have. Basic Setup To use printers with the LPD spooling system, you will need to set up both your printer hardware and the LPD software. This document describes two levels of setup: See section Simple Printer Setup to learn how to connect a printer, tell LPD how to communicate with it, and print plain text files to the printer. See section Advanced Printer Setup to learn how to print a variety of special file formats, to print header pages, to print across a network, to control access to printers, and to do printer accounting. Simple Printer Setup This section tells how to configure printer hardware and the LPD software to use the printer. It teaches the basics: Section Hardware Setup gives some hints on connecting the printer to a port on your computer. Section Software Setup shows how to set up the LPD spooler configuration file (/etc/printcap). If you are setting up a printer that uses a network protocol to accept data to print instead of a computer's local interfaces, see Printers With Networked Data Stream Interfaces. Although this section is called Simple Printer Setup, it is actually fairly complex. Getting the printer to work with your computer and the LPD spooler is the hardest part. The advanced options like header pages and accounting are fairly easy once you get the printer working. Hardware Setup This section tells about the various ways you can connect a printer to your PC. It talks about the kinds of ports and cables, and also the kernel configuration you may need to enable &os; to speak to the printer. If you have already connected your printer and have successfully printed with it under another operating system, you can probably skip to section Software Setup. Ports and Cables Printers sold for use on PC's today generally come with one or more of the following three interfaces: - - printers - serial - - - Serial interfaces, also known + Serialprintersserial interfaces, also known as RS-232 or COM ports, use a serial port on your computer to send data to the printer. Serial interfaces are common in the computer industry and cables are readily available and also easy to construct. Serial interfaces sometimes need special cables and might require you to configure somewhat complex communications options. Most PC serial ports have a maximum transmission rate of 115200 bps, which makes printing large graphic print jobs with them impractical. - - printers - parallel - - - Parallel interfaces use a + Parallelprintersparallel interfaces use a parallel port on your computer to send data to the printer. Parallel interfaces are common in the PC market and are faster than RS-232 serial. Cables are readily available but more difficult to construct by hand. There are usually no communications options with parallel interfaces, making their configuration exceedingly simple. - - centronics - parallel printers - Parallel interfaces are sometimes known as - Centronics interfaces, named after the + Centronicscentronicsparallel printers interfaces, named after the connector type on the printer. - - printers - USB - - - USB interfaces, named for the Universal Serial + USBprintersUSB interfaces, named for the Universal Serial Bus, can run at even faster speeds than parallel or RS-232 serial interfaces. Cables are simple and cheap. USB is superior to RS-232 Serial and to Parallel for printing, but it is not as well supported under &unix; systems. A way to avoid this problem is to purchase a printer that has both a USB interface and a Parallel interface, as many printers do. In general, Parallel interfaces usually offer just one-way communication (computer to printer) while serial and USB gives you two-way. Newer parallel ports (EPP and ECP) and printers can communicate in both directions under &os; when a IEEE-1284-compliant cable is used. PostScript Two-way communication to the printer over a parallel port is generally done in one of two ways. The first method uses a custom-built printer driver for &os; that speaks the proprietary language used by the printer. This is common with inkjet printers and can be used for reporting ink levels and other status information. The second method is used when the printer supports &postscript;. &postscript; jobs are actually programs sent to the printer; they need not produce paper at all and may return results directly to the computer. &postscript; also uses two-way communication to tell the computer about problems, such as errors in the &postscript; program or paper jams. Your users may be appreciative of such information. Furthermore, the best way to do effective accounting with a &postscript; printer requires two-way communication: you ask the printer for its page count (how many pages it has printed in its lifetime), then send the user's job, then ask again for its page count. Subtract the two values and you know how much paper to charge to the user. Parallel Ports To hook up a printer using a parallel interface, connect the Centronics cable between the printer and the computer. The instructions that came with the printer, the computer, or both should give you complete guidance. Remember which parallel port you used on the computer. The first parallel port is ppc0 to &os;; the second is ppc1, and so on. The printer device name uses the same scheme: /dev/lpt0 for the printer on the first parallel ports etc. Serial Ports To hook up a printer using a serial interface, connect the proper serial cable between the printer and the computer. The instructions that came with the printer, the computer, or both should give you complete guidance. If you are unsure what the proper serial cable is, you may wish to try one of the following alternatives: A modem cable connects each pin of the connector on one end of the cable straight through to its corresponding pin of the connector on the other end. This type of cable is also known as a DTE-to-DCE cable. - null-modem - cable - - A null-modem cable connects + A null-modem cablenull-modem cable connects some pins straight through, swaps others (send data to receive data, for example), and shorts some internally in each connector hood. This type of cable is also known as a DTE-to-DTE cable. A serial printer cable, required for some unusual printers, is like the null-modem cable, but sends some signals to their counterparts instead of being internally shorted. baud rate parity flow control protocol You should also set up the communications parameters for the printer, usually through front-panel controls or DIP switches on the printer. Choose the highest bps (bits per second, sometimes baud rate) that both your computer and the printer can support. Choose 7 or 8 data bits; none, even, or odd parity; and 1 or 2 stop bits. Also choose a flow control protocol: either none, or XON/XOFF (also known as in-band or software) flow control. Remember these settings for the software configuration that follows. Software Setup This section describes the software setup necessary to print with the LPD spooling system in &os;. Here is an outline of the steps involved: Configure your kernel, if necessary, for the port you are using for the printer; section Kernel Configuration tells you what you need to do. Set the communications mode for the parallel port, if you are using a parallel port; section Setting the Communication Mode for the Parallel Port gives details. Test if the operating system can send data to the printer. Section Checking Printer Communications gives some suggestions on how to do this. Set up LPD for the printer by modifying the file /etc/printcap. You will find out how to do this later in this chapter. Kernel Configuration The operating system kernel is compiled to work with a specific set of devices. The serial or parallel interface for your printer is a part of that set. Therefore, it might be necessary to add support for an additional serial or parallel port if your kernel is not already configured for one. To find out if the kernel you are currently using supports a serial interface, type: &prompt.root; grep sioN /var/run/dmesg.boot Where N is the number of the serial port, starting from zero. If you see output similar to the following: sio2 at port 0x3e8-0x3ef irq 5 on isa sio2: type 16550A then the kernel supports the port. To find out if the kernel supports a parallel interface, type: &prompt.root; grep ppcN /var/run/dmesg.boot Where N is the number of the parallel port, starting from zero. If you see output similar to the following: ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode ppc0: FIFO with 16/16/8 bytes threshold then the kernel supports the port. You might have to reconfigure your kernel in order for the operating system to recognize and use the parallel or serial port you are using for the printer. To add support for a serial port, see the section on kernel configuration. To add support for a parallel port, see that section and the section that follows. Setting the Communication Mode for the Parallel Port When you are using the parallel interface, you can choose whether &os; should use interrupt-driven or polled communication with the printer. The generic printer device driver (&man.lpt.4;) on &os; uses the &man.ppbus.4; system, which controls the port chipset with the &man.ppc.4; driver. The interrupt-driven method is the default with the GENERIC kernel. With this method, the operating system uses an IRQ line to determine when the printer is ready for data. The polled method directs the operating system to repeatedly ask the printer if it is ready for more data. When it responds ready, the kernel sends more data. The interrupt-driven method is usually somewhat faster but uses up a precious IRQ line. Some newer HP printers are claimed not to work correctly in interrupt mode, apparently due to some (not yet exactly understood) timing problem. These printers need polled mode. You should use whichever one works. Some printers will work in both modes, but are painfully slow in interrupt mode. You can set the communications mode in two ways: by configuring the kernel or by using the &man.lptcontrol.8; program. To set the communications mode by configuring the kernel: Edit your kernel configuration file. Look for an ppc0 entry. If you are setting up the second parallel port, use ppc1 instead. Use ppc2 for the third port, and so on. If you want interrupt-driven mode, edit the following line: hint.ppc.0.irq="N" in the /boot/device.hints file and replace N with the right IRQ number. The kernel configuration file must also contain the &man.ppc.4; driver: device ppc If you want polled mode, remove in your /boot/device.hints file, the following line: hint.ppc.0.irq="N" In some cases, this is not enough to put the port in polled mode under &os;. Most of time it comes from &man.acpi.4; driver, this latter is able to probe and attach devices, and therefore, control the access mode to the printer port. You should check your &man.acpi.4; configuration to correct this problem. Save the file. Then configure, build, and install the kernel, then reboot. See kernel configuration for more details. To set the communications mode with &man.lptcontrol.8;: Type: &prompt.root; lptcontrol /dev/lptN to set interrupt-driven mode for lptN. Type: &prompt.root; lptcontrol /dev/lptN to set polled-mode for lptN. You could put these commands in your /etc/rc.local file to set the mode each time your system boots. See &man.lptcontrol.8; for more information. Checking Printer Communications Before proceeding to configure the spooling system, you should make sure the operating system can successfully send data to your printer. It is a lot easier to debug printer communication and the spooling system separately. To test the printer, we will send some text to it. For printers that can immediately print characters sent to them, the program &man.lptest.1; is perfect: it generates all 96 printable ASCII characters in 96 lines. PostScript For a &postscript; (or other language-based) printer, we will need a more sophisticated test. A small &postscript; program, such as the following, will suffice: %!PS 100 100 moveto 300 300 lineto stroke 310 310 moveto /Helvetica findfont 12 scalefont setfont (Is this thing working?) show showpage The above &postscript; code can be placed into a file and used as shown in the examples appearing in the following sections. PCL When this document refers to a printer language, it is assuming a language like &postscript;, and not Hewlett Packard's PCL. Although PCL has great functionality, you can intermingle plain text with its escape sequences. &postscript; cannot directly print plain text, and that is the kind of printer language for which we must make special accommodations. Checking a Parallel Printer - - printers - parallel - This section tells you how to check if &os; can - communicate with a printer connected to a parallel + communicate with a printer connected to a parallelprintersparallel port. To test a printer on a parallel port: Become root with &man.su.1;. Send data to the printer. If the printer can print plain text, then use &man.lptest.1;. Type: &prompt.root; lptest > /dev/lptN Where N is the number of the parallel port, starting from zero. If the printer understands &postscript; or other printer language, then send a small program to the printer. Type: &prompt.root; cat > /dev/lptN Then, line by line, type the program carefully as you cannot edit a line once you have pressed RETURN or ENTER. When you have finished entering the program, press CONTROL+D, or whatever your end of file key is. Alternatively, you can put the program in a file and type: &prompt.root; cat file > /dev/lptN Where file is the name of the file containing the program you want to send to the printer. You should see something print. Do not worry if the text does not look right; we will fix such things later. Checking a Serial Printer printers serial This section tells you how to check if &os; can communicate with a printer on a serial port. To test a printer on a serial port: Become root with &man.su.1;. Edit the file /etc/remote. Add the following entry: printer:dv=/dev/port:br#bps-rate:pa=parity bits-per-second serial port parity Where port is the device entry for the serial port (ttyu0, ttyu1, etc.), bps-rate is the bits-per-second rate at which the printer communicates, and parity is the parity required by the printer (either even, odd, none, or zero). Here is a sample entry for a printer connected via a serial line to the third serial port at 19200 bps with no parity: printer:dv=/dev/ttyu2:br#19200:pa=none Connect to the printer with &man.tip.1;. Type: &prompt.root; tip printer If this step does not work, edit the file /etc/remote again and try using /dev/cuaaN instead of /dev/ttyuN. Send data to the printer. If the printer can print plain text, then use &man.lptest.1;. Type: &prompt.user; $lptest If the printer understands &postscript; or other printer language, then send a small program to the printer. Type the program, line by line, very carefully as backspacing or other editing keys may be significant to the printer. You may also need to type a special end-of-file key for the printer so it knows it received the whole program. For &postscript; printers, press CONTROL+D. Alternatively, you can put the program in a file and type: &prompt.user; >file Where file is the name of the file containing the program. After &man.tip.1; sends the file, press any required end-of-file key. You should see something print. Do not worry if the text does not look right; we will fix that later. Enabling the Spooler: the <filename>/etc/printcap</filename> File At this point, your printer should be hooked up, your kernel configured to communicate with it (if necessary), and you have been able to send some simple data to the printer. Now, we are ready to configure LPD to control access to your printer. You configure LPD by editing the file /etc/printcap. The LPD spooling system reads this file each time the spooler is used, so updates to the file take immediate effect. printers capabilities The format of the &man.printcap.5; file is straightforward. Use your favorite text editor to make changes to /etc/printcap. The format is identical to other capability files like /usr/share/misc/termcap and /etc/remote. For complete information about the format, see the &man.cgetent.3;. The simple spooler configuration consists of the following steps: Pick a name (and a few convenient aliases) for the printer, and put them in the /etc/printcap file; see the Naming the Printer section for more information on naming. - header pages - - Turn off header pages (which are on by default) by + Turn off header pagesheader pages (which are on by default) by inserting the sh capability; see the Suppressing Header Pages section for more information. Make a spooling directory, and specify its location with the sd capability; see the Making the Spooling Directory section for more information. Set the /dev entry to use for the printer, and note it in /etc/printcap with the lp capability; see the Identifying the Printer Device for more information. Also, if the printer is on a serial port, set up the communication parameters with the ms# capability which is discussed in the Configuring Spooler Communications Parameters section. Install a plain text input filter; see the Installing the Text Filter section for details. Test the setup by printing something with the &man.lpr.1; command. More details are available in the Trying It Out and Troubleshooting sections. Language-based printers, such as &postscript; printers, cannot directly print plain text. The simple setup outlined above and described in the following sections assumes that if you are installing such a printer you will print only files that the printer can understand. Users often expect that they can print plain text to any of the printers installed on your system. Programs that interface to LPD to do their printing usually make the same assumption. If you are installing such a printer and want to be able to print jobs in the printer language and print plain text jobs, you are strongly urged to add an additional step to the simple setup outlined above: install an automatic plain-text-to-&postscript; (or other printer language) conversion program. The section entitled Accommodating Plain Text Jobs on &postscript; Printers tells how to do this. Naming the Printer The first (easy) step is to pick a name for your printer. It really does not matter whether you choose functional or whimsical names since you can also provide a number of aliases for the printer. At least one of the printers specified in the /etc/printcap should have the alias lp. This is the default printer's name. If users do not have the PRINTER environment variable nor specify a printer name on the command line of any of the LPD commands, then lp will be the default printer they get to use. Also, it is common practice to make the last alias for a printer be a full description of the printer, including make and model. Once you have picked a name and some common aliases, put them in the /etc/printcap file. The name of the printer should start in the leftmost column. Separate each alias with a vertical bar and put a colon after the last alias. In the following example, we start with a skeletal /etc/printcap that defines two printers (a Diablo 630 line printer and a Panasonic KX-P4455 &postscript; laser printer): # # /etc/printcap for host rose # rattan|line|diablo|lp|Diablo 630 Line Printer: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4: In this example, the first printer is named rattan and has as aliases line, diablo, lp, and Diablo 630 Line Printer. Since it has the alias lp, it is also the default printer. The second is named bamboo, and has as aliases ps, PS, S, panasonic, and Panasonic KX-P4455 PostScript v51.4. Suppressing Header Pages printing header pages The LPD spooling system will by default print a header page for each job. The header page contains the user name who requested the job, the host from which the job came, and the name of the job, in nice large letters. Unfortunately, all this extra text gets in the way of debugging the simple printer setup, so we will suppress header pages. To suppress header pages, add the sh capability to the entry for the printer in /etc/printcap. Here is an example /etc/printcap with sh added: # # /etc/printcap for host rose - no header pages anywhere # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh: Note how we used the correct format: the first line starts in the leftmost column, and subsequent lines are indented. Every line in an entry except the last ends in a backslash character. Making the Spooling Directory printer spool print jobs The next step in the simple spooler setup is to make a spooling directory, a directory where print jobs reside until they are printed, and where a number of other spooler support files live. Because of the variable nature of spooling directories, it is customary to put these directories under /var/spool. It is not necessary to backup the contents of spooling directories, either. Recreating them is as simple as running &man.mkdir.1;. It is also customary to make the directory with a name that is identical to the name of the printer, as shown below: &prompt.root; mkdir /var/spool/printer-name However, if you have a lot of printers on your network, you might want to put the spooling directories under a single directory that you reserve just for printing with LPD. We will do this for our two example printers rattan and bamboo: &prompt.root; mkdir /var/spool/lpd &prompt.root; mkdir /var/spool/lpd/rattan &prompt.root; mkdir /var/spool/lpd/bamboo If you are concerned about the privacy of jobs that users print, you might want to protect the spooling directory so it is not publicly accessible. Spooling directories should be owned and be readable, writable, and searchable by user daemon and group daemon, and no one else. We will do this for our example printers: &prompt.root; chown daemon:daemon /var/spool/lpd/rattan &prompt.root; chown daemon:daemon /var/spool/lpd/bamboo &prompt.root; chmod 770 /var/spool/lpd/rattan &prompt.root; chmod 770 /var/spool/lpd/bamboo Finally, you need to tell LPD about these directories using the /etc/printcap file. You specify the pathname of the spooling directory with the sd capability: # # /etc/printcap for host rose - added spooling directories # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:sd=/var/spool/lpd/rattan: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo: Note that the name of the printer starts in the first column but all other entries describing the printer should be indented and each line end escaped with a backslash. If you do not specify a spooling directory with sd, the spooling system will use /var/spool/lpd as a default. Identifying the Printer Device In the Hardware Setup section, we identified the port and the relevant /dev directory entry that &os; will use to communicate with the printer. Now, we tell LPD that information. When the spooling system has a job to print, it will open the specified device on behalf of the filter program (which is responsible for passing data to the printer). List the /dev entry pathname in the /etc/printcap file using the lp capability. In our running example, let us assume that rattan is on the first parallel port, and bamboo is on a sixth serial port; here are the additions to /etc/printcap: # # /etc/printcap for host rose - identified what devices to use # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:\ :lp=/dev/ttyu5: If you do not specify the lp capability for a printer in your /etc/printcap file, LPD uses /dev/lp as a default. /dev/lp currently does not exist in &os;. If the printer you are installing is connected to a parallel port, skip to the section entitled, Installing the Text Filter. Otherwise, be sure to follow the instructions in the next section. Configuring Spooler Communication Parameters printers serial For printers on serial ports, LPD can set up the bps rate, parity, and other serial communication parameters on behalf of the filter program that sends data to the printer. This is advantageous since: It lets you try different communication parameters by simply editing the /etc/printcap file; you do not have to recompile the filter program. It enables the spooling system to use the same filter program for multiple printers which may have different serial communication settings. The following /etc/printcap capabilities control serial communication parameters of the device listed in the lp capability: br#bps-rate Sets the communications speed of the device to bps-rate, where bps-rate can be 50, 75, 110, 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, or 115200 bits-per-second. ms#stty-mode Sets the options for the terminal device after opening the device. &man.stty.1; explains the available options. When LPD opens the device specified by the lp capability, it sets the characteristics of the device to those specified with the ms# capability. Of particular interest will be the parenb, parodd, cs5, cs6, cs7, cs8, cstopb, crtscts, and ixon modes, which are explained in the &man.stty.1; manual page. Let us add to our example printer on the sixth serial port. We will set the bps rate to 38400. For the mode, we will set no parity with -parenb, 8-bit characters with cs8, no modem control with clocal and hardware flow control with crtscts: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:\ :lp=/dev/ttyu5:ms#-parenb cs8 clocal crtscts: Installing the Text Filter printing filters We are now ready to tell LPD what text filter to use to send jobs to the printer. A text filter, also known as an input filter, is a program that LPD runs when it has a job to print. When LPD runs the text filter for a printer, it sets the filter's standard input to the job to print, and its standard output to the printer device specified with the lp capability. The filter is expected to read the job from standard input, perform any necessary translation for the printer, and write the results to standard output, which will get printed. For more information on the text filter, see the Filters section. For our simple printer setup, the text filter can be a small shell script that just executes /bin/cat to send the job to the printer. &os; comes with another filter called lpf that handles backspacing and underlining for printers that might not deal with such character streams well. And, of course, you can use any other filter program you want. The filter lpf is described in detail in section entitled lpf: a Text Filter. First, let us make the shell script /usr/local/libexec/if-simple be a simple text filter. Put the following text into that file with your favorite text editor: #!/bin/sh # # if-simple - Simple text input filter for lpd # Installed in /usr/local/libexec/if-simple # # Simply copies stdin to stdout. Ignores all filter arguments. /bin/cat && exit 0 exit 2 Make the file executable: &prompt.root; chmod 555 /usr/local/libexec/if-simple And then tell LPD to use it by specifying it with the if capability in /etc/printcap. We will add it to the two printers we have so far in the example /etc/printcap: # # /etc/printcap for host rose - added text filter # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ :if=/usr/local/libexec/if-simple: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:\ :lp=/dev/ttyu5:ms#-parenb cs8 clocal crtscts:\ :if=/usr/local/libexec/if-simple: A copy of the if-simple script can be found in the /usr/share/examples/printing directory. Turn on <application>LPD</application> &man.lpd.8; is run from /etc/rc, controlled by the lpd_enable variable. This variable defaults to NO. If you have not done so already, add the line: lpd_enable="YES" to /etc/rc.conf, and then either restart your machine, or just run &man.lpd.8;. &prompt.root; lpd Trying It Out You have reached the end of the simple LPD setup. Unfortunately, congratulations are not quite yet in order, since we still have to test the setup and correct any problems. To test the setup, try printing something. To print with the LPD system, you use the command &man.lpr.1;, which submits a job for printing. You can combine &man.lpr.1; with the &man.lptest.1; program, introduced in section Checking Printer Communications to generate some test text. To test the simple LPD setup: Type: &prompt.root; lptest 20 5 | lpr printer-name Where printer-name is a the name of a printer (or an alias) specified in /etc/printcap. To test the default printer, type &man.lpr.1; without any argument. Again, if you are testing a printer that expects &postscript;, send a &postscript; program in that language instead of using &man.lptest.1;. You can do so by putting the program in a file and typing lpr file. For a &postscript; printer, you should get the results of the program. If you are using &man.lptest.1;, then your results should look like the following: !"#$%&'()*+,-./01234 "#$%&'()*+,-./012345 #$%&'()*+,-./0123456 $%&'()*+,-./01234567 %&'()*+,-./012345678 To further test the printer, try downloading larger programs (for language-based printers) or running &man.lptest.1; with different arguments. For example, lptest 80 60 will produce 60 lines of 80 characters each. If the printer did not work, see the Troubleshooting section. Advanced Printer Setup This section describes filters for printing specially formatted files, header pages, printing across networks, and restricting and accounting for printer usage. Filters printing filters Although LPD handles network protocols, queuing, access control, and other aspects of printing, most of the real work happens in the filters. Filters are programs that communicate with the printer and handle its device dependencies and special requirements. In the simple printer setup, we installed a plain text filter—an extremely simple one that should work with most printers (section Installing the Text Filter). However, in order to take advantage of format conversion, printer accounting, specific printer quirks, and so on, you should understand how filters work. It will ultimately be the filter's responsibility to handle these aspects. And the bad news is that most of the time you have to provide filters yourself. The good news is that many are generally available; when they are not, they are usually easy to write. Also, &os; comes with one, /usr/libexec/lpr/lpf, that works with many printers that can print plain text. (It handles backspacing and tabs in the file, and does accounting, but that is about all it does.) There are also several filters and filter components in the &os; Ports Collection. Here is what you will find in this section: Section How Filters Work, tries to give an overview of a filter's role in the printing process. You should read this section to get an understanding of what is happening under the hood when LPD uses filters. This knowledge could help you anticipate and debug problems you might encounter as you install more and more filters for each of your printers. LPD expects every printer to be able to print plain text by default. This presents a problem for &postscript; printers (or other language-based printers) which cannot directly print plain text. Section Accommodating Plain Text Jobs on &postscript; Printers tells you what you should do to overcome this problem. You should read this section if you have a &postscript; printer. &postscript; is a popular output format for many programs. Some people even write &postscript; code directly. Unfortunately, &postscript; printers are expensive. Section Simulating &postscript; on Non &postscript; Printers tells how you can further modify a printer's text filter to accept and print &postscript; data on a non &postscript; printer. You should read this section if you do not have a &postscript; printer. Section Conversion Filters tells about a way you can automate the conversion of specific file formats, such as graphic or typesetting data, into formats your printer can understand. After reading this section, you should be able to set up your printers such that users can type lpr to print troff data, or lpr to print &tex; DVI data, or lpr to print raster image data, and so forth. The reading of this section is recommended. Section Output Filters tells all about a not often used feature of LPD: output filters. Unless you are printing header pages (see Header Pages), you can probably skip that section altogether. Section lpf: a Text Filter describes lpf, a fairly complete if simple text filter for line printers (and laser printers that act like line printers) that comes with &os;. If you need a quick way to get printer accounting working for plain text, or if you have a printer which emits smoke when it sees backspace characters, you should definitely consider lpf. A copy of the various scripts described below can be found in the /usr/share/examples/printing directory. How Filters Work As mentioned before, a filter is an executable program started by LPD to handle the device-dependent part of communicating with the printer. When LPD wants to print a file in a job, it starts a filter program. It sets the filter's standard input to the file to print, its standard output to the printer, and its standard error to the error logging file (specified in the lf capability in /etc/printcap, or /dev/console by default). troff Which filter LPD starts and the filter's arguments depend on what is listed in the /etc/printcap file and what arguments the user specified for the job on the &man.lpr.1; command line. For example, if the user typed lpr , LPD would start the troff filter, listed in the tf capability for the destination printer. If the user wanted to print plain text, it would start the if filter (this is mostly true: see Output Filters for details). There are three kinds of filters you can specify in /etc/printcap: The text filter, confusingly called the input filter in LPD documentation, handles regular text printing. Think of it as the default filter. LPD expects every printer to be able to print plain text by default, and it is the text filter's job to make sure backspaces, tabs, or other special characters do not confuse the printer. If you are in an environment where you have to account for printer usage, the text filter must also account for pages printed, usually by counting the number of lines printed and comparing that to the number of lines per page the printer supports. The text filter is started with the following argument list: filter-name -c -w width -l length -i indent -n login -h host acct-file where appears if the job is submitted with lpr width is the value from the pw (page width) capability specified in /etc/printcap, default 132 length is the value from the pl (page length) capability, default 66 indent is the amount of the indentation from lpr , default 0 login is the account name of the user printing the file host is the host name from which the job was submitted acct-file is the name of the accounting file from the af capability. - - printing - filters - - - A conversion filter converts + A conversion filterprintingfilters converts a specific file format into one the printer can render onto paper. For example, ditroff typesetting data cannot be directly printed, but you can install a conversion filter for ditroff files to convert the ditroff data into a form the printer can digest and print. Section Conversion Filters tells all about them. Conversion filters also need to do accounting, if you need printer accounting. Conversion filters are started with the following arguments: filter-name -x pixel-width -y pixel-height -n login -h host acct-file where pixel-width is the value from the px capability (default 0) and pixel-height is the value from the py capability (default 0). The output filter is used only if there is no text filter, or if header pages are enabled. In our experience, output filters are rarely used. Section Output Filters describes them. There are only two arguments to an output filter: filter-name -w width -l length which are identical to the text filters and arguments. Filters should also exit with the following exit status: exit 0 If the filter printed the file successfully. exit 1 If the filter failed to print the file but wants LPD to try to print the file again. LPD will restart a filter if it exits with this status. exit 2 If the filter failed to print the file and does not want LPD to try again. LPD will throw out the file. The text filter that comes with the &os; release, /usr/libexec/lpr/lpf, takes advantage of the page width and length arguments to determine when to send a form feed and how to account for printer usage. It uses the login, host, and accounting file arguments to make the accounting entries. If you are shopping for filters, see if they are LPD-compatible. If they are, they must support the argument lists described above. If you plan on writing filters for general use, then have them support the same argument lists and exit codes. Accommodating Plain Text Jobs on &postscript; Printers print jobs If you are the only user of your computer and &postscript; (or other language-based) printer, and you promise to never send plain text to your printer and to never use features of various programs that will want to send plain text to your printer, then you do not need to worry about this section at all. But, if you would like to send both &postscript; and plain text jobs to the printer, then you are urged to augment your printer setup. To do so, we have the text filter detect if the arriving job is plain text or &postscript;. All &postscript; jobs must start with %! (for other printer languages, see your printer documentation). If those are the first two characters in the job, we have &postscript;, and can pass the rest of the job directly. If those are not the first two characters in the file, then the filter will convert the text into &postscript; and print the result. How do we do this? printers serial If you have got a serial printer, a great way to do it is to install lprps. lprps is a &postscript; printer filter which performs two-way communication with the printer. It updates the printer's status file with verbose information from the printer, so users and administrators can see exactly what the state of the printer is (such as toner low or paper jam). But more importantly, it includes a program called psif which detects whether the incoming job is plain text and calls textps (another program that comes with lprps) to convert it to &postscript;. It then uses lprps to send the job to the printer. lprps is part of the &os; Ports Collection (see The Ports Collection). You can install one of the both print/lprps-a4 and print/lprps-letter ports according to the paper size used. After installing lprps, just specify the pathname to the psif program that is part of lprps. If you installed lprps from the Ports Collection, use the following in the serial &postscript; printer's entry in /etc/printcap: :if=/usr/local/libexec/psif: The rw capability should be also included in order to let LPD to open the printer in the read-write mode. If you have a parallel &postscript; printer (and therefore cannot use two-way communication with the printer, which lprps needs), you can use the following shell script as the text filter: #!/bin/sh # # psif - Print PostScript or plain text on a PostScript printer # Script version; NOT the version that comes with lprps # Installed in /usr/local/libexec/psif # IFS="" read -r first_line first_two_chars=`expr "$first_line" : '\(..\)'` if [ "$first_two_chars" = "%!" ]; then # # PostScript job, print it. # echo "$first_line" && cat && printf "\004" && exit 0 exit 2 else # # Plain text, convert it, then print it. # ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0 exit 2 fi In the above script, textps is a program we installed separately to convert plain text to &postscript;. You can use any text-to-&postscript; program you wish. The &os; Ports Collection (see The Ports Collection) includes a full featured text-to-&postscript; program called a2ps that you might want to investigate. Simulating &postscript; on Non &postscript; Printers PostScript emulating Ghostscript &postscript; is the de facto standard for high quality typesetting and printing. &postscript; is, however, an expensive standard. Thankfully, Aladdin Enterprises has a free &postscript; work-alike called Ghostscript that runs with &os;. Ghostscript can read most &postscript; files and can render their pages onto a variety of devices, including many brands of non-&postscript; printers. By installing Ghostscript and using a special text filter for your printer, you can make your non &postscript; printer act like a real &postscript; printer. Ghostscript is in the &os; Ports Collection, many versions are available, the most commonly used version is print/ghostscript-gpl. To simulate &postscript;, we have the text filter detect if it is printing a &postscript; file. If it is not, then the filter will pass the file directly to the printer; otherwise, it will use Ghostscript to first convert the file into a format the printer will understand. Here is an example: the following script is a text filter for Hewlett Packard DeskJet 500 printers. For other printers, substitute the argument to the gs (Ghostscript) command. (Type gs to get a list of devices the current installation of Ghostscript supports.) #!/bin/sh # # ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500 # Installed in /usr/local/libexec/ifhp # # Treat LF as CR+LF (to avoid the "staircase effect" on HP/PCL # printers): # printf "\033&k2G" || exit 2 # # Read first two characters of the file # IFS="" read -r first_line first_two_chars=`expr "$first_line" : '\(..\)'` if [ "$first_two_chars" = "%!" ]; then # # It is PostScript; use Ghostscript to scan-convert and print it. # /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \ -sOutputFile=- - && exit 0 else # # Plain text or HP/PCL, so just print it directly; print a form feed # at the end to eject the last page. # echo "$first_line" && cat && printf "\033&l0H" && exit 0 fi exit 2 Finally, you need to notify LPD of the filter via the if capability: :if=/usr/local/libexec/ifhp: That is it. You can type lpr plain.text and lpr whatever.ps and both should print successfully. Conversion Filters After completing the simple setup described in Simple Printer Setup, the first thing you will probably want to do is install conversion filters for your favorite file formats (besides plain ASCII text). Why Install Conversion Filters? &tex; printing DVI files Conversion filters make printing various kinds of files easy. As an example, suppose we do a lot of work with the &tex; typesetting system, and we have a &postscript; printer. Every time we generate a DVI file from &tex;, we cannot print it directly until we convert the DVI file into &postscript;. The command sequence goes like this: &prompt.user; dvips seaweed-analysis.dvi &prompt.user; lpr seaweed-analysis.ps By installing a conversion filter for DVI files, we can skip the hand conversion step each time by having LPD do it for us. Now, each time we get a DVI file, we are just one step away from printing it: &prompt.user; lpr seaweed-analysis.dvi We got LPD to do the DVI file conversion for us by specifying the option. Section Formatting and Conversion Options lists the conversion options. For each of the conversion options you want a printer to support, install a conversion filter and specify its pathname in /etc/printcap. A conversion filter is like the text filter for the simple printer setup (see section Installing the Text Filter) except that instead of printing plain text, the filter converts the file into a format the printer can understand. Which Conversion Filters Should I Install? You should install the conversion filters you expect to use. If you print a lot of DVI data, then a DVI conversion filter is in order. If you have got plenty of troff to print out, then you probably want a troff filter. The following table summarizes the filters that LPD works with, their capability entries for the /etc/printcap file, and how to invoke them with the lpr command: File type /etc/printcap capability lpr option cifplot cf DVI df plot gf ditroff nf FORTRAN text rf troff tf raster vf plain text if none, , or In our example, using lpr means the printer needs a df capability in its entry in /etc/printcap. FORTRAN Despite what others might contend, formats like FORTRAN text and plot are probably obsolete. At your site, you can give new meanings to these or any of the formatting options just by installing custom filters. For example, suppose you would like to directly print Printerleaf files (files from the Interleaf desktop publishing program), but will never print plot files. You could install a Printerleaf conversion filter under the gf capability and then educate your users that lpr mean print Printerleaf files. Installing Conversion Filters Since conversion filters are programs you install outside of the base &os; installation, they should probably go under /usr/local. The directory /usr/local/libexec is a popular location, since they are specialized programs that only LPD will run; regular users should not ever need to run them. To enable a conversion filter, specify its pathname under the appropriate capability for the destination printer in /etc/printcap. In our example, we will add the DVI conversion filter to the entry for the printer named bamboo. Here is the example /etc/printcap file again, with the new df capability for the printer bamboo: # # /etc/printcap for host rose - added df filter for bamboo # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ :if=/usr/local/libexec/if-simple: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:\ :lp=/dev/ttyu5:ms#-parenb cs8 clocal crtscts:rw:\ :if=/usr/local/libexec/psif:\ :df=/usr/local/libexec/psdf: The DVI filter is a shell script named /usr/local/libexec/psdf. Here is that script: #!/bin/sh # # psdf - DVI to PostScript printer filter # Installed in /usr/local/libexec/psdf # # Invoked by lpd when user runs lpr -d # exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@" This script runs dvips in filter mode (the argument) on standard input, which is the job to print. It then starts the &postscript; printer filter lprps (see section Accommodating Plain Text Jobs on &postscript; Printers) with the arguments LPD passed to this script. The lprps utility will use those arguments to account for the pages printed. More Conversion Filter Examples There is no fixed set of steps to install conversion filters, some working examples are described in this section. Use these as guidance to making your own filters. Use them directly, if appropriate. This example script is a raster (well, GIF file, actually) conversion filter for a Hewlett Packard LaserJet III-Si printer: #!/bin/sh # # hpvf - Convert GIF files into HP/PCL, then print # Installed in /usr/local/libexec/hpvf PATH=/usr/X11R6/bin:$PATH; export PATH giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \ && exit 0 \ || exit 2 It works by converting the GIF file into a portable anymap, converting that into a portable graymap, converting that into a portable bitmap, and converting that into LaserJet/PCL-compatible data. Here is the /etc/printcap file with an entry for a printer using the above filter: # # /etc/printcap for host orchid # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ :if=/usr/local/libexec/hpif:\ :vf=/usr/local/libexec/hpvf: The following script is a conversion filter for troff data from the groff typesetting system for the &postscript; printer named bamboo: #!/bin/sh # # pstf - Convert groff's troff data into PS, then print. # Installed in /usr/local/libexec/pstf # exec grops | /usr/local/libexec/lprps "$@" The above script makes use of lprps again to handle the communication with the printer. If the printer were on a parallel port, we would use this script instead: #!/bin/sh # # pstf - Convert groff's troff data into PS, then print. # Installed in /usr/local/libexec/pstf # exec grops That is it. Here is the entry we need to add to /etc/printcap to enable the filter: :tf=/usr/local/libexec/pstf: Here is an example that might make old hands at FORTRAN blush. It is a FORTRAN-text filter for any printer that can directly print plain text. We will install it for the printer teak: #!/bin/sh # # hprf - FORTRAN text filter for LaserJet 3si: # Installed in /usr/local/libexec/hprf # printf "\033&k2G" && fpr && printf "\033&l0H" && exit 0 exit 2 And we will add this line to the /etc/printcap for the printer teak to enable this filter: :rf=/usr/local/libexec/hprf: Here is one final, somewhat complex example. We will add a DVI filter to the LaserJet printer teak introduced earlier. First, the easy part: updating /etc/printcap with the location of the DVI filter: :df=/usr/local/libexec/hpdf: Now, for the hard part: making the filter. For that, we need a DVI-to-LaserJet/PCL conversion program. The &os; Ports Collection (see The Ports Collection) has one: print/dvi2xx. Installing this port gives us the program we need, dvilj2p, which converts DVI into LaserJet IIp, LaserJet III, and LaserJet 2000 compatible codes. The dvilj2p utility makes the filter hpdf quite complex since dvilj2p cannot read from standard input. It wants to work with a filename. What is worse, the filename has to end in .dvi so using /dev/fd/0 for standard input is problematic. We can get around that problem by linking (symbolically) a temporary file name (one that ends in .dvi) to /dev/fd/0, thereby forcing dvilj2p to read from standard input. The only other fly in the ointment is the fact that we cannot use /tmp for the temporary link. Symbolic links are owned by user and group bin. The filter runs as user daemon. And the /tmp directory has the sticky bit set. The filter can create the link, but it will not be able clean up when done and remove it since the link will belong to a different user. Instead, the filter will make the symbolic link in the current working directory, which is the spooling directory (specified by the sd capability in /etc/printcap). This is a perfect place for filters to do their work, especially since there is (sometimes) more free disk space in the spooling directory than under /tmp. Here, finally, is the filter: #!/bin/sh # # hpdf - Print DVI data on HP/PCL printer # Installed in /usr/local/libexec/hpdf PATH=/usr/local/bin:$PATH; export PATH # # Define a function to clean up our temporary files. These exist # in the current directory, which will be the spooling directory # for the printer. # cleanup() { rm -f hpdf$$.dvi } # # Define a function to handle fatal errors: print the given message # and exit 2. Exiting with 2 tells LPD to do not try to reprint the # job. # fatal() { echo "$@" 1>&2 cleanup exit 2 } # # If user removes the job, LPD will send SIGINT, so trap SIGINT # (and a few other signals) to clean up after ourselves. # trap cleanup 1 2 15 # # Make sure we are not colliding with any existing files. # cleanup # # Link the DVI input file to standard input (the file to print). # ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0" # # Make LF = CR+LF # printf "\033&k2G" || fatal "Cannot initialize printer" # # Convert and print. Return value from dvilj2p does not seem to be # reliable, so we ignore it. # dvilj2p -M1 -q -e- dfhp$$.dvi # # Clean up and exit # cleanup exit 0 Automated Conversion: an Alternative to Conversion Filters All these conversion filters accomplish a lot for your printing environment, but at the cost forcing the user to specify (on the &man.lpr.1; command line) which one to use. If your users are not particularly computer literate, having to specify a filter option will become annoying. What is worse, though, is that an incorrectly specified filter option may run a filter on the wrong type of file and cause your printer to spew out hundreds of sheets of paper. Rather than install conversion filters at all, you might want to try having the text filter (since it is the default filter) detect the type of file it has been asked to print and then automatically run the right conversion filter. Tools such as file can be of help here. Of course, it will be hard to determine the differences between some file types—and, of course, you can still provide conversion filters just for them. apsfilter printing filters apsfilter The &os; Ports Collection has a text filter that performs automatic conversion called apsfilter (print/apsfilter). It can detect plain text, &postscript;, DVI and almost any kind of files, run the proper conversions, and print. Output Filters The LPD spooling system supports one other type of filter that we have not yet explored: an output filter. An output filter is intended for printing plain text only, like the text filter, but with many simplifications. If you are using an output filter but no text filter, then: LPD starts an output filter once for the entire job instead of once for each file in the job. LPD does not make any provision to identify the start or the end of files within the job for the output filter. LPD does not pass the user's login or host to the filter, so it is not intended to do accounting. In fact, it gets only two arguments: filter-name -wwidth -llength Where width is from the pw capability and length is from the pl capability for the printer in question. Do not be seduced by an output filter's simplicity. If you would like each file in a job to start on a different page an output filter will not work. Use a text filter (also known as an input filter); see section Installing the Text Filter. Furthermore, an output filter is actually more complex in that it has to examine the byte stream being sent to it for special flag characters and must send signals to itself on behalf of LPD. However, an output filter is necessary if you want header pages and need to send escape sequences or other initialization strings to be able to print the header page. (But it is also futile if you want to charge header pages to the requesting user's account, since LPD does not give any user or host information to the output filter.) On a single printer, LPD allows both an output filter and text or other filters. In such cases, LPD will start the output filter to print the header page (see section Header Pages) only. LPD then expects the output filter to stop itself by sending two bytes to the filter: ASCII 031 followed by ASCII 001. When an output filter sees these two bytes (031, 001), it should stop by sending SIGSTOP to itself. When LPD's done running other filters, it will restart the output filter by sending SIGCONT to it. If there is an output filter but no text filter and LPD is working on a plain text job, LPD uses the output filter to do the job. As stated before, the output filter will print each file of the job in sequence with no intervening form feeds or other paper advancement, and this is probably not what you want. In almost all cases, you need a text filter. The program lpf, which we introduced earlier as a text filter, can also run as an output filter. If you need a quick-and-dirty output filter but do not want to write the byte detection and signal sending code, try lpf. You can also wrap lpf in a shell script to handle any initialization codes the printer might require. <command>lpf</command>: a Text Filter The program /usr/libexec/lpr/lpf that comes with &os; binary distribution is a text filter (input filter) that can indent output (job submitted with lpr ), allow literal characters to pass (job submitted with lpr ), adjust the printing position for backspaces and tabs in the job, and account for pages printed. It can also act like an output filter. The lpf filter is suitable for many printing environments. And although it has no capability to send initialization sequences to a printer, it is easy to write a shell script to do the needed initialization and then execute lpf. page accounting accounting printer In order for lpf to do page accounting correctly, it needs correct values filled in for the pw and pl capabilities in the /etc/printcap file. It uses these values to determine how much text can fit on a page and how many pages were in a user's job. For more information on printer accounting, see Accounting for Printer Usage. Header Pages If you have lots of users, all of them using various printers, then you probably want to consider header pages as a necessary evil. banner pages header pages header pages Header pages, also known as banner or burst pages identify to whom jobs belong after they are printed. They are usually printed in large, bold letters, perhaps with decorative borders, so that in a stack of printouts they stand out from the real documents that comprise users' jobs. They enable users to locate their jobs quickly. The obvious drawback to a header page is that it is yet one more sheet that has to be printed for every job, their ephemeral usefulness lasting not more than a few minutes, ultimately finding themselves in a recycling bin or rubbish heap. (Note that header pages go with each job, not each file in a job, so the paper waste might not be that bad.) The LPD system can provide header pages automatically for your printouts if your printer can directly print plain text. If you have a &postscript; printer, you will need an external program to generate the header page; see Header Pages on &postscript; Printers. Enabling Header Pages In the Simple Printer Setup section, we turned off header pages by specifying sh (meaning suppress header) in the /etc/printcap file. To enable header pages for a printer, just remove the sh capability. Sounds too easy, right? You are right. You might have to provide an output filter to send initialization strings to the printer. Here is an example output filter for Hewlett Packard PCL-compatible printers: #!/bin/sh # # hpof - Output filter for Hewlett Packard PCL-compatible printers # Installed in /usr/local/libexec/hpof printf "\033&k2G" || exit 2 exec /usr/libexec/lpr/lpf Specify the path to the output filter in the of capability. See the Output Filters section for more information. Here is an example /etc/printcap file for the printer teak that we introduced earlier; we enabled header pages and added the above output filter: # # /etc/printcap for host orchid # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ :if=/usr/local/libexec/hpif:\ :vf=/usr/local/libexec/hpvf:\ :of=/usr/local/libexec/hpof: Now, when users print jobs to teak, they get a header page with each job. If users want to spend time searching for their printouts, they can suppress header pages by submitting the job with lpr ; see the Header Page Options section for more &man.lpr.1; options. LPD prints a form feed character after the header page. If your printer uses a different character or sequence of characters to eject a page, specify them with the ff capability in /etc/printcap. Controlling Header Pages By enabling header pages, LPD will produce a long header, a full page of large letters identifying the user, host, and job. Here is an example (kelly printed the job named outline from host rose): k ll ll k l l k l l k k eeee l l y y k k e e l l y y k k eeeeee l l y y kk k e l l y y k k e e l l y yy k k eeee lll lll yyy y y y y yyyy ll t l i t l oooo u u ttttt l ii n nnn eeee o o u u t l i nn n e e o o u u t l i n n eeeeee o o u u t l i n n e o o u uu t t l i n n e e oooo uuu u tt lll iii n n eeee r rrr oooo ssss eeee rr r o o s s e e r o o ss eeeeee r o o ss e r o o s s e e r oooo ssss eeee Job: outline Date: Sun Sep 17 11:04:58 1995 LPD appends a form feed after this text so the job starts on a new page (unless you have sf (suppress form feeds) in the destination printer's entry in /etc/printcap). If you prefer, LPD can make a short header; specify sb (short banner) in the /etc/printcap file. The header page will look like this: rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995 Also by default, LPD prints the header page first, then the job. To reverse that, specify hl (header last) in /etc/printcap. Accounting for Header Pages Using LPD's built-in header pages enforces a particular paradigm when it comes to printer accounting: header pages must be free of charge. Why? Because the output filter is the only external program that will have control when the header page is printed that could do accounting, and it is not provided with any user or host information or an accounting file, so it has no idea whom to charge for printer use. It is also not enough to just increase the page count by one by modifying the text filter or any of the conversion filters (which do have user and host information) since users can suppress header pages with lpr . They could still be charged for header pages they did not print. Basically, lpr will be the preferred option of environmentally-minded users, but you cannot offer any incentive to use it. It is still not enough to have each of the filters generate their own header pages (thereby being able to charge for them). If users wanted the option of suppressing the header pages with lpr , they will still get them and be charged for them since LPD does not pass any knowledge of the option to any of the filters. So, what are your options? You can: Accept LPD's paradigm and make header pages free. Install an alternative to LPD, such as LPRng. Section Alternatives to the Standard Spooler tells more about other spooling software you can substitute for LPD. Write a smart output filter. Normally, an output filter is not meant to do anything more than initialize a printer or do some simple character conversion. It is suited for header pages and plain text jobs (when there is no text (input) filter). But, if there is a text filter for the plain text jobs, then LPD will start the output filter only for the header pages. And the output filter can parse the header page text that LPD generates to determine what user and host to charge for the header page. The only other problem with this method is that the output filter still does not know what accounting file to use (it is not passed the name of the file from the af capability), but if you have a well-known accounting file, you can hard-code that into the output filter. To facilitate the parsing step, use the sh (short header) capability in /etc/printcap. Then again, all that might be too much trouble, and users will certainly appreciate the more generous system administrator who makes header pages free. Header Pages on &postscript; Printers As described above, LPD can generate a plain text header page suitable for many printers. Of course, &postscript; cannot directly print plain text, so the header page feature of LPD is useless—or mostly so. One obvious way to get header pages is to have every conversion filter and the text filter generate the header page. The filters should use the user and host arguments to generate a suitable header page. The drawback of this method is that users will always get a header page, even if they submit jobs with lpr . Let us explore this method. The following script takes three arguments (user login name, host name, and job name) and makes a simple &postscript; header page: #!/bin/sh # # make-ps-header - make a PostScript header page on stdout # Installed in /usr/local/libexec/make-ps-header # # # These are PostScript units (72 to the inch). Modify for A4 or # whatever size paper you are using: # page_width=612 page_height=792 border=72 # # Check arguments # if [ $# -ne 3 ]; then echo "Usage: `basename $0` <user> <host> <job>" 1>&2 exit 1 fi # # Save these, mostly for readability in the PostScript, below. # user=$1 host=$2 job=$3 date=`date` # # Send the PostScript code to stdout. # exec cat <<EOF %!PS % % Make sure we do not interfere with user's job that will follow % save % % Make a thick, unpleasant border around the edge of the paper. % $border $border moveto $page_width $border 2 mul sub 0 rlineto 0 $page_height $border 2 mul sub rlineto currentscreen 3 -1 roll pop 100 3 1 roll setscreen $border 2 mul $page_width sub 0 rlineto closepath 0.8 setgray 10 setlinewidth stroke 0 setgray % % Display user's login name, nice and large and prominent % /Helvetica-Bold findfont 64 scalefont setfont $page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto ($user) show % % Now show the boring particulars % /Helvetica findfont 14 scalefont setfont /y 200 def [ (Job:) (Host:) (Date:) ] { 200 y moveto show /y y 18 sub def } forall /Helvetica-Bold findfont 14 scalefont setfont /y 200 def [ ($job) ($host) ($date) ] { 270 y moveto show /y y 18 sub def } forall % % That is it % restore showpage EOF Now, each of the conversion filters and the text filter can call this script to first generate the header page, and then print the user's job. Here is the DVI conversion filter from earlier in this document, modified to make a header page: #!/bin/sh # # psdf - DVI to PostScript printer filter # Installed in /usr/local/libexec/psdf # # Invoked by lpd when user runs lpr -d # orig_args="$@" fail() { echo "$@" 1>&2 exit 2 } while getopts "x:y:n:h:" option; do case $option in x|y) ;; # Ignore n) login=$OPTARG ;; h) host=$OPTARG ;; *) echo "LPD started `basename $0` wrong." 1>&2 exit 2 ;; esac done [ "$login" ] || fail "No login name" [ "$host" ] || fail "No host name" ( /usr/local/libexec/make-ps-header $login $host "DVI File" /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args Notice how the filter has to parse the argument list in order to determine the user and host name. The parsing for the other conversion filters is identical. The text filter takes a slightly different set of arguments, though (see section How Filters Work). As we have mentioned before, the above scheme, though fairly simple, disables the suppress header page option (the option) to lpr. If users wanted to save a tree (or a few pennies, if you charge for header pages), they would not be able to do so, since every filter's going to print a header page with every job. To allow users to shut off header pages on a per-job basis, you will need to use the trick introduced in section Accounting for Header Pages: write an output filter that parses the LPD-generated header page and produces a &postscript; version. If the user submits the job with lpr , then LPD will not generate a header page, and neither will your output filter. Otherwise, your output filter will read the text from LPD and send the appropriate header page &postscript; code to the printer. If you have a &postscript; printer on a serial line, you can make use of lprps, which comes with an output filter, psof, which does the above. Note that psof does not charge for header pages. Networked Printing printers network network printing &os; supports networked printing: sending jobs to remote printers. Networked printing generally refers to two different things: Accessing a printer attached to a remote host. You install a printer that has a conventional serial or parallel interface on one host. Then, you set up LPD to enable access to the printer from other hosts on the network. Section Printers Installed on Remote Hosts tells how to do this. Accessing a printer attached directly to a network. The printer has a network interface in addition to (or in place of) a more conventional serial or parallel interface. Such a printer might work as follows: It might understand the LPD protocol and can even queue jobs from remote hosts. In this case, it acts just like a regular host running LPD. Follow the same procedure in section Printers Installed on Remote Hosts to set up such a printer. It might support a data stream network connection. In this case, you attach the printer to one host on the network by making that host responsible for spooling jobs and sending them to the printer. Section Printers with Networked Data Stream Interfaces gives some suggestions on installing such printers. Printers Installed on Remote Hosts The LPD spooling system has built-in support for sending jobs to other hosts also running LPD (or are compatible with LPD). This feature enables you to install a printer on one host and make it accessible from other hosts. It also works with printers that have network interfaces that understand the LPD protocol. To enable this kind of remote printing, first install a printer on one host, the printer host, using the simple printer setup described in the Simple Printer Setup section. Do any advanced setup in Advanced Printer Setup that you need. Make sure to test the printer and see if it works with the features of LPD you have enabled. Also ensure that the local host has authorization to use the LPD service in the remote host (see Restricting Jobs from Remote Hosts). printers network network printing If you are using a printer with a network interface that is compatible with LPD, then the printer host in the discussion below is the printer itself, and the printer name is the name you configured for the printer. See the documentation that accompanied your printer and/or printer-network interface. If you are using a Hewlett Packard Laserjet then the printer name text will automatically perform the LF to CRLF conversion for you, so you will not require the hpif script. Then, on the other hosts you want to have access to the printer, make an entry in their /etc/printcap files with the following: Name the entry anything you want. For simplicity, though, you probably want to use the same name and aliases as on the printer host. Leave the lp capability blank, explicitly (:lp=:). Make a spooling directory and specify its location in the sd capability. LPD will store jobs here before they get sent to the printer host. Place the name of the printer host in the rm capability. Place the printer name on the printer host in the rp capability. That is it. You do not need to list conversion filters, page dimensions, or anything else in the /etc/printcap file. Here is an example. The host rose has two printers, bamboo and rattan. We will enable users on the host orchid to print to those printers. Here is the /etc/printcap file for orchid (back from section Enabling Header Pages). It already had the entry for the printer teak; we have added entries for the two printers on the host rose: # # /etc/printcap for host orchid - added (remote) printers on rose # # # teak is local; it is connected directly to orchid: # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:\ :if=/usr/local/libexec/ifhp:\ :vf=/usr/local/libexec/vfhp:\ :of=/usr/local/libexec/ofhp: # # rattan is connected to rose; send jobs for rattan to rose: # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: # # bamboo is connected to rose as well: # bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo: Then, we just need to make spooling directories on orchid: &prompt.root; mkdir /var/spool/lpd/rattan /var/spool/lpd/bamboo &prompt.root; chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo &prompt.root; chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo Now, users on orchid can print to rattan and bamboo. If, for example, a user on orchid typed: &prompt.user; lpr bamboo sushi-review.dvi the LPD system on orchid would copy the job to the spooling directory /var/spool/lpd/bamboo and note that it was a DVI job. As soon as the host rose has room in its bamboo spooling directory, the two LPDs would transfer the file to rose. The file would wait in rose's queue until it was finally printed. It would be converted from DVI to &postscript; (since bamboo is a &postscript; printer) on rose. Printers with Networked Data Stream Interfaces Often, when you buy a network interface card for a printer, you can get two versions: one which emulates a spooler (the more expensive version), or one which just lets you send data to it as if you were using a serial or parallel port (the cheaper version). This section tells how to use the cheaper version. For the more expensive one, see the previous section Printers Installed on Remote Hosts. The format of the /etc/printcap file lets you specify what serial or parallel interface to use, and (if you are using a serial interface), what baud rate, whether to use flow control, delays for tabs, conversion of newlines, and more. But there is no way to specify a connection to a printer that is listening on a TCP/IP or other network port. To send data to a networked printer, you need to develop a communications program that can be called by the text and conversion filters. Here is one such example: the script netprint takes all data on standard input and sends it to a network-attached printer. We specify the hostname of the printer as the first argument and the port number to which to connect as the second argument to netprint. Note that this supports one-way communication only (&os; to printer); many network printers support two-way communication, and you might want to take advantage of that (to get printer status, perform accounting, etc.). #!/usr/bin/perl # # netprint - Text filter for printer attached to network # Installed in /usr/local/libexec/netprint # $#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>"; $printer_host = $ARGV[0]; $printer_port = $ARGV[1]; require 'sys/socket.ph'; ($ignore, $ignore, $protocol) = getprotobyname('tcp'); ($ignore, $ignore, $ignore, $ignore, $address) = gethostbyname($printer_host); $sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address); socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol) || die "Can't create TCP/IP stream socket: $!"; connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!"; while (<STDIN>) { print PRINTER; } exit 0; We can then use this script in various filters. Suppose we had a Diablo 750-N line printer connected to the network. The printer accepts data to print on port number 5100. The host name of the printer is scrivener. Here is the text filter for the printer: #!/bin/sh # # diablo-if-net - Text filter for Diablo printer `scrivener' listening # on port 5100. Installed in /usr/local/libexec/diablo-if-net # exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100 Restricting Printer Usage printers restricting access to This section gives information on restricting printer usage. The LPD system lets you control who can access a printer, both locally or remotely, whether they can print multiple copies, how large their jobs can be, and how large the printer queues can get. Restricting Multiple Copies The LPD system makes it easy for users to print multiple copies of a file. Users can print jobs with lpr (for example) and get five copies of each file in the job. Whether this is a good thing is up to you. If you feel multiple copies cause unnecessary wear and tear on your printers, you can disable the option to &man.lpr.1; by adding the sc capability to the /etc/printcap file. When users submit jobs with the option, they will see: lpr: multiple copies are not allowed Note that if you have set up access to a printer remotely (see section Printers Installed on Remote Hosts), you need the sc capability on the remote /etc/printcap files as well, or else users will still be able to submit multiple-copy jobs by using another host. Here is an example. This is the /etc/printcap file for the host rose. The printer rattan is quite hearty, so we will allow multiple copies, but the laser printer bamboo is a bit more delicate, so we will disable multiple copies by adding the sc capability: # # /etc/printcap for host rose - restrict multiple copies on bamboo # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ :if=/usr/local/libexec/if-simple: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:sc:\ :lp=/dev/ttyu5:ms#-parenb cs8 clocal crtscts:rw:\ :if=/usr/local/libexec/psif:\ :df=/usr/local/libexec/psdf: Now, we also need to add the sc capability on the host orchid's /etc/printcap (and while we are at it, let us disable multiple copies for the printer teak): # # /etc/printcap for host orchid - no multiple copies for local # printer teak or remote printer bamboo teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ :lp=/dev/lpt0:sd=/var/spool/lpd/teak:mx#0:sc:\ :if=/usr/local/libexec/ifhp:\ :vf=/usr/local/libexec/vfhp:\ :of=/usr/local/libexec/ofhp: rattan|line|diablo|lp|Diablo 630 Line Printer:\ :lp=:rm=rose:rp=rattan:sd=/var/spool/lpd/rattan: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :lp=:rm=rose:rp=bamboo:sd=/var/spool/lpd/bamboo:sc: By using the sc capability, we prevent the use of lpr , but that still does not prevent users from running &man.lpr.1; multiple times, or from submitting the same file multiple times in one job like this: &prompt.user; lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign There are many ways to prevent this abuse (including ignoring it) which you are free to explore. Restricting Access to Printers You can control who can print to what printers by using the &unix; group mechanism and the rg capability in /etc/printcap. Just place the users you want to have access to a printer in a certain group, and then name that group in the rg capability. If users outside the group (including root) try to print to the controlled printer then they will be greeted with the following message: lpr: Not a member of the restricted group As with the sc (suppress multiple copies) capability, you need to specify rg on remote hosts that also have access to your printers, if you feel it is appropriate (see section Printers Installed on Remote Hosts). For example, we will let anyone access the printer rattan, but only those in group artists can use bamboo. Here is the familiar /etc/printcap for host rose: # # /etc/printcap for host rose - restricted group for bamboo # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ :if=/usr/local/libexec/if-simple: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:\ :lp=/dev/ttyu5:ms#-parenb cs8 clocal crtscts:rw:\ :if=/usr/local/libexec/psif:\ :df=/usr/local/libexec/psdf: Let us leave the other example /etc/printcap file (for the host orchid) alone. Of course, anyone on orchid can print to bamboo. It might be the case that we only allow certain logins on orchid anyway, and want them to have access to the printer. Or not. There can be only one restricted group per printer. Controlling Sizes of Jobs Submitted print jobs If you have many users accessing the printers, you probably need to put an upper limit on the sizes of the files users can submit to print. After all, there is only so much free space on the filesystem that houses the spooling directories, and you also need to make sure there is room for the jobs of other users. print jobs controlling LPD enables you to limit the maximum byte size a file in a job can be with the mx capability. The units are in BUFSIZ blocks, which are 1024 bytes. If you put a zero for this capability, there will be no limit on file size; however, if no mx capability is specified, then a default limit of 1000 blocks will be used. The limit applies to files in a job, and not the total job size. LPD will not refuse a file that is larger than the limit you place on a printer. Instead, it will queue as much of the file up to the limit, which will then get printed. The rest will be discarded. Whether this is correct behavior is up for debate. Let us add limits to our example printers rattan and bamboo. Since those artists' &postscript; files tend to be large, we will limit them to five megabytes. We will put no limit on the plain text line printer: # # /etc/printcap for host rose # # # No limit on job size: # rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:mx#0:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ :if=/usr/local/libexec/if-simple: # # Limit of five megabytes: # bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ :lp=/dev/ttyu5:ms#-parenb cs8 clocal crtscts:rw:\ :if=/usr/local/libexec/psif:\ :df=/usr/local/libexec/psdf: Again, the limits apply to the local users only. If you have set up access to your printers remotely, remote users will not get those limits. You will need to specify the mx capability in the remote /etc/printcap files as well. See section Printers Installed on Remote Hosts for more information on remote printing. There is another specialized way to limit job sizes from remote printers; see section Restricting Jobs from Remote Hosts. Restricting Jobs from Remote Hosts The LPD spooling system provides several ways to restrict print jobs submitted from remote hosts: Host restrictions You can control from which remote hosts a local LPD accepts requests with the files /etc/hosts.equiv and /etc/hosts.lpd. LPD checks to see if an incoming request is from a host listed in either one of these files. If not, LPD refuses the request. The format of these files is simple: one host name per line. Note that the file /etc/hosts.equiv is also used by the &man.ruserok.3; protocol, and affects programs like &man.rsh.1; and &man.rcp.1;, so be careful. For example, here is the /etc/hosts.lpd file on the host rose: orchid violet madrigal.fishbaum.de This means rose will accept requests from the hosts orchid, violet, and madrigal.fishbaum.de. If any other host tries to access rose's LPD, the job will be refused. Size restrictions You can control how much free space there needs to remain on the filesystem where a spooling directory resides. Make a file called minfree in the spooling directory for the local printer. Insert in that file a number representing how many disk blocks (512 bytes) of free space there has to be for a remote job to be accepted. This lets you insure that remote users will not fill your filesystem. You can also use it to give a certain priority to local users: they will be able to queue jobs long after the free disk space has fallen below the amount specified in the minfree file. For example, let us add a minfree file for the printer bamboo. We examine /etc/printcap to find the spooling directory for this printer; here is bamboo's entry: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ :sh:sd=/var/spool/lpd/bamboo:sc:rg=artists:mx#5000:\ :lp=/dev/ttyu5:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\ :if=/usr/local/libexec/psif:\ :df=/usr/local/libexec/psdf: The spooling directory is given in the sd capability. We will make three megabytes (which is 6144 disk blocks) the amount of free disk space that must exist on the filesystem for LPD to accept remote jobs: &prompt.root; echo 6144 > /var/spool/lpd/bamboo/minfree User restrictions You can control which remote users can print to local printers by specifying the rs capability in /etc/printcap. When rs appears in the entry for a locally-attached printer, LPD will accept jobs from remote hosts if the user submitting the job also has an account of the same login name on the local host. Otherwise, LPD refuses the job. This capability is particularly useful in an environment where there are (for example) different departments sharing a network, and some users transcend departmental boundaries. By giving them accounts on your systems, they can use your printers from their own departmental systems. If you would rather allow them to use only your printers and not your computer resources, you can give them token accounts, with no home directory and a useless shell like /usr/bin/false. Accounting for Printer Usage accounting printer So, you need to charge for printouts. And why not? Paper and ink cost money. And then there are maintenance costs—printers are loaded with moving parts and tend to break down. You have examined your printers, usage patterns, and maintenance fees and have come up with a per-page (or per-foot, per-meter, or per-whatever) cost. Now, how do you actually start accounting for printouts? Well, the bad news is the LPD spooling system does not provide much help in this department. Accounting is highly dependent on the kind of printer in use, the formats being printed, and your equirements in charging for printer usage. To implement accounting, you have to modify a printer's text filter (to charge for plain text jobs) and the conversion filters (to charge for other file formats), to count pages or query the printer for pages printed. You cannot get away with using the simple output filter, since it cannot do accounting. See section Filters. Generally, there are two ways to do accounting: Periodic accounting is the more common way, possibly because it is easier. Whenever someone prints a job, the filter logs the user, host, and number of pages to an accounting file. Every month, semester, year, or whatever time period you prefer, you collect the accounting files for the various printers, tally up the pages printed by users, and charge for usage. Then you truncate all the logging files, starting with a clean slate for the next period. Timely accounting is less common, probably because it is more difficult. This method has the filters charge users for printouts as soon as they use the printers. Like disk quotas, the accounting is immediate. You can prevent users from printing when their account goes in the red, and might provide a way for users to check and adjust their print quotas. But this method requires some database code to track users and their quotas. The LPD spooling system supports both methods easily: since you have to provide the filters (well, most of the time), you also have to provide the accounting code. But there is a bright side: you have enormous flexibility in your accounting methods. For example, you choose whether to use periodic or timely accounting. You choose what information to log: user names, host names, job types, pages printed, square footage of paper used, how long the job took to print, and so forth. And you do so by modifying the filters to save this information. Quick and Dirty Printer Accounting &os; comes with two programs that can get you set up with simple periodic accounting right away. They are the text filter lpf, described in section lpf: a Text Filter, and &man.pac.8;, a program to gather and total entries from printer accounting files. As mentioned in the section on filters (Filters), LPD starts the text and the conversion filters with the name of the accounting file to use on the filter command line. The filters can use this argument to know where to write an accounting file entry. The name of this file comes from the af capability in /etc/printcap, and if not specified as an absolute path, is relative to the spooling directory. LPD starts lpf with page width and length arguments (from the pw and pl capabilities). The lpf filter uses these arguments to determine how much paper will be used. After sending the file to the printer, it then writes an accounting entry in the accounting file. The entries look like this: 2.00 rose:andy 3.00 rose:kelly 3.00 orchid:mary 5.00 orchid:mary 2.00 orchid:zhang You should use a separate accounting file for each printer, as lpf has no file locking logic built into it, and two lpfs might corrupt each other's entries if they were to write to the same file at the same time. An easy way to insure a separate accounting file for each printer is to use af=acct in /etc/printcap. Then, each accounting file will be in the spooling directory for a printer, in a file named acct. When you are ready to charge users for printouts, run the &man.pac.8; program. Just change to the spooling directory for the printer you want to collect on and type pac. You will get a dollar-centric summary like the following: Login pages/feet runs price orchid:kelly 5.00 1 $ 0.10 orchid:mary 31.00 3 $ 0.62 orchid:zhang 9.00 1 $ 0.18 rose:andy 2.00 1 $ 0.04 rose:kelly 177.00 104 $ 3.54 rose:mary 87.00 32 $ 1.74 rose:root 26.00 12 $ 0.52 total 337.00 154 $ 6.74 These are the arguments &man.pac.8; expects: Which printer to summarize. This option works only if there is an absolute path in the af capability in /etc/printcap. Sort the output by cost instead of alphabetically by user name. Ignore host name in the accounting files. With this option, user smith on host alpha is the same user smith on host gamma. Without, they are different users. Compute charges with price dollars per page or per foot instead of the price from the pc capability in /etc/printcap, or two cents (the default). You can specify price as a floating point number. Reverse the sort order. Make an accounting summary file and truncate the accounting file. name … Print accounting information for the given user names only. In the default summary that &man.pac.8; produces, you see the number of pages printed by each user from various hosts. If, at your site, host does not matter (because users can use any host), run pac , to produce the following summary: Login pages/feet runs price andy 2.00 1 $ 0.04 kelly 182.00 105 $ 3.64 mary 118.00 35 $ 2.36 root 26.00 12 $ 0.52 zhang 9.00 1 $ 0.18 total 337.00 154 $ 6.74 To compute the dollar amount due, &man.pac.8; uses the pc capability in the /etc/printcap file (default of 200, or 2 cents per page). Specify, in hundredths of cents, the price per page or per foot you want to charge for printouts in this capability. You can override this value when you run &man.pac.8; with the option. The units for the option are in dollars, though, not hundredths of cents. For example, &prompt.root; pac makes each page cost one dollar and fifty cents. You can really rake in the profits by using this option. Finally, running pac will save the summary information in a summary accounting file, which is named the same as the printer's accounting file, but with _sum appended to the name. It then truncates the accounting file. When you run &man.pac.8; again, it rereads the summary file to get starting totals, then adds information from the regular accounting file. How Can You Count Pages Printed? In order to perform even remotely accurate accounting, you need to be able to determine how much paper a job uses. This is the essential problem of printer accounting. For plain text jobs, the problem is not that hard to solve: you count how many lines are in a job and compare it to how many lines per page your printer supports. Do not forget to take into account backspaces in the file which overprint lines, or long logical lines that wrap onto one or more additional physical lines. The text filter lpf (introduced in lpf: a Text Filter) takes into account these things when it does accounting. If you are writing a text filter which needs to do accounting, you might want to examine lpf's source code. How do you handle other file formats, though? Well, for DVI-to-LaserJet or DVI-to-&postscript; conversion, you can have your filter parse the diagnostic output of dvilj or dvips and look to see how many pages were converted. You might be able to do similar things with other file formats and conversion programs. But these methods suffer from the fact that the printer may not actually print all those pages. For example, it could jam, run out of toner, or explode—and the user would still get charged. So, what can you do? There is only one sure way to do accurate accounting. Get a printer that can tell you how much paper it uses, and attach it via a serial line or a network connection. Nearly all &postscript; printers support this notion. Other makes and models do as well (networked Imagen laser printers, for example). Modify the filters for these printers to get the page usage after they print each job and have them log accounting information based on that value only. There is no line counting nor error-prone file examination required. Of course, you can always be generous and make all printouts free. Using Printers printers usage This section tells you how to use printers you have set up with &os;. Here is an overview of the user-level commands: &man.lpr.1; Print jobs &man.lpq.1; Check printer queues &man.lprm.1; Remove jobs from a printer's queue There is also an administrative command, &man.lpc.8;, described in the section Administering Printers, used to control printers and their queues. All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1; accept an option to specify on which printer/queue to operate, as listed in the /etc/printcap file. This enables you to submit, remove, and check on jobs for various printers. If you do not use the option, then these commands use the printer specified in the PRINTER environment variable. Finally, if you do not have a PRINTER environment variable, these commands default to the printer named lp. Hereafter, the terminology default printer means the printer named in the PRINTER environment variable, or the printer named lp when there is no PRINTER environment variable. Printing Jobs To print files, type: &prompt.user; lpr filename ... printing This prints each of the listed files to the default printer. If you list no files, &man.lpr.1; reads data to print from standard input. For example, this command prints some important system files: &prompt.user; lpr /etc/host.conf /etc/hosts.equiv To select a specific printer, type: &prompt.user; lpr printer-name filename ... This example prints a long listing of the current directory to the printer named rattan: &prompt.user; ls | lpr rattan Because no files were listed for the &man.lpr.1; command, lpr read the data to print from standard input, which was the output of the ls command. The &man.lpr.1; command can also accept a wide variety of options to control formatting, apply file conversions, generate multiple copies, and so forth. For more information, see the section Printing Options. Checking Jobs print jobs When you print with &man.lpr.1;, the data you wish to print is put together in a package called a print job, which is sent to the LPD spooling system. Each printer has a queue of jobs, and your job waits in that queue along with other jobs from yourself and from other users. The printer prints those jobs in a first-come, first-served order. To display the queue for the default printer, type &man.lpq.1;. For a specific printer, use the option. For example, the command &prompt.user; lpq bamboo shows the queue for the printer named bamboo. Here is an example of the output of the lpq command: bamboo is ready and printing Rank Owner Job Files Total Size active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes 2nd kelly 10 (standard input) 1635 bytes 3rd mary 11 ... 78519 bytes This shows three jobs in the queue for bamboo. The first job, submitted by user kelly, got assigned job number 9. Every job for a printer gets a unique job number. Most of the time you can ignore the job number, but you will need it if you want to cancel the job; see section Removing Jobs for details. Job number nine consists of two files; multiple files given on the &man.lpr.1; command line are treated as part of a single job. It is the currently active job (note the word active under the Rank column), which means the printer should be currently printing that job. The second job consists of data passed as the standard input to the &man.lpr.1; command. The third job came from user mary; it is a much larger job. The pathname of the file she is trying to print is too long to fit, so the &man.lpq.1; command just shows three dots. The very first line of the output from &man.lpq.1; is also useful: it tells what the printer is currently doing (or at least what LPD thinks the printer is doing). The &man.lpq.1; command also support a option to generate a detailed long listing. Here is an example of lpq : waiting for bamboo to become ready (offline ?) kelly: 1st [job 009rose] /etc/host.conf 73 bytes /etc/hosts.equiv 15 bytes kelly: 2nd [job 010rose] (standard input) 1635 bytes mary: 3rd [job 011rose] /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes Removing Jobs If you change your mind about printing a job, you can remove the job from the queue with the &man.lprm.1; command. Often, you can even use &man.lprm.1; to remove an active job, but some or all of the job might still get printed. To remove a job from the default printer, first use &man.lpq.1; to find the job number. Then type: &prompt.user; lprm job-number To remove the job from a specific printer, add the option. The following command removes job number 10 from the queue for the printer bamboo: &prompt.user; lprm bamboo 10 The &man.lprm.1; command has a few shortcuts: lprm - Removes all jobs (for the default printer) belonging to you. lprm user Removes all jobs (for the default printer) belonging to user. The superuser can remove other users' jobs; you can remove only your own jobs. lprm With no job number, user name, or appearing on the command line, &man.lprm.1; removes the currently active job on the default printer, if it belongs to you. The superuser can remove any active job. Just use the option with the above shortcuts to operate on a specific printer instead of the default. For example, the following command removes all jobs for the current user in the queue for the printer named rattan: &prompt.user; lprm rattan - If you are working in a networked environment, &man.lprm.1; will let you remove jobs only from the host from which the jobs were submitted, even if the same printer is available from other hosts. The following command sequence demonstrates this: &prompt.user; lpr rattan myfile &prompt.user; rlogin orchid &prompt.user; lpq rattan Rank Owner Job Files Total Size active seeyan 12 ... 49123 bytes 2nd kelly 13 myfile 12 bytes &prompt.user; lprm rattan 13 rose: Permission denied &prompt.user; logout &prompt.user; lprm rattan 13 dfA013rose dequeued cfA013rose dequeued Beyond Plain Text: Printing Options The &man.lpr.1; command supports a number of options that control formatting text, converting graphic and other file formats, producing multiple copies, handling of the job, and more. This section describes the options. Formatting and Conversion Options The following &man.lpr.1; options control formatting of the files in the job. Use these options if the job does not contain plain text or if you want plain text formatted through the &man.pr.1; utility. &tex; For example, the following command prints a DVI file (from the &tex; typesetting system) named fish-report.dvi to the printer named bamboo: &prompt.user; lpr bamboo -d fish-report.dvi These options apply to every file in the job, so you cannot mix (say) DVI and ditroff files together in a job. Instead, submit the files as separate jobs, using a different conversion option for each job. All of these options except and require conversion filters installed for the destination printer. For example, the option requires the DVI conversion filter. Section Conversion Filters gives details. Print cifplot files. Print DVI files. Print FORTRAN text files. Print plot data. Indent the output by number columns; if you omit number, indent by 8 columns. This option works only with certain conversion filters. Do not put any space between the and the number. Print literal text data, including control characters. Print ditroff (device independent troff) data. -p Format plain text with &man.pr.1; before printing. See &man.pr.1; for more information. Use title on the &man.pr.1; header instead of the file name. This option has effect only when used with the option. Print troff data. Print raster data. Here is an example: this command prints a nicely formatted version of the &man.ls.1; manual page on the default printer: &prompt.user; zcat /usr/share/man/man1/ls.1.gz | troff -man | lpr The &man.zcat.1; command uncompresses the source of the &man.ls.1; manual page and passes it to the &man.troff.1; command, which formats that source and makes GNU troff output and passes it to &man.lpr.1;, which submits the job to the LPD spooler. Because we used the option to &man.lpr.1;, the spooler will convert the GNU troff output into a format the default printer can understand when it prints the job. Job Handling Options The following options to &man.lpr.1; tell LPD to handle the job specially: -# copies Produce a number of copies of each file in the job instead of just one copy. An administrator may disable this option to reduce printer wear-and-tear and encourage photocopier usage. See section Restricting Multiple Copies. This example prints three copies of parser.c followed by three copies of parser.h to the default printer: &prompt.user; lpr parser.c parser.h -m Send mail after completing the print job. With this option, the LPD system will send mail to your account when it finishes handling your job. In its message, it will tell you if the job completed successfully or if there was an error, and (often) what the error was. -s Do not copy the files to the spooling directory, but make symbolic links to them instead. If you are printing a large job, you probably want to use this option. It saves space in the spooling directory (your job might overflow the free space on the filesystem where the spooling directory resides). It saves time as well since LPD will not have to copy each and every byte of your job to the spooling directory. There is a drawback, though: since LPD will refer to the original files directly, you cannot modify or remove them until they have been printed. If you are printing to a remote printer, LPD will eventually have to copy files from the local host to the remote host, so the option will save space only on the local spooling directory, not the remote. It is still useful, though. -r Remove the files in the job after copying them to the spooling directory, or after printing them with the option. Be careful with this option! Header Page Options These options to &man.lpr.1; adjust the text that normally appears on a job's header page. If header pages are suppressed for the destination printer, these options have no effect. See section Header Pages for information about setting up header pages. -C text Replace the hostname on the header page with text. The hostname is normally the name of the host from which the job was submitted. -J text Replace the job name on the header page with text. The job name is normally the name of the first file of the job, or stdin if you are printing standard input. -h Do not print any header page. At some sites, this option may have no effect due to the way header pages are generated. See Header Pages for details. Administering Printers As an administrator for your printers, you have had to install, set up, and test them. Using the &man.lpc.8; command, you can interact with your printers in yet more ways. With &man.lpc.8;, you can Start and stop the printers Enable and disable their queues Rearrange the order of the jobs in each queue. First, a note about terminology: if a printer is stopped, it will not print anything in its queue. Users can still submit jobs, which will wait in the queue until the printer is started or the queue is cleared. If a queue is disabled, no user (except root) can submit jobs for the printer. An enabled queue allows jobs to be submitted. A printer can be started for a disabled queue, in which case it will continue to print jobs in the queue until the queue is empty. In general, you have to have root privileges to use the &man.lpc.8; command. Ordinary users can use the &man.lpc.8; command to get printer status and to restart a hung printer only. Here is a summary of the &man.lpc.8; commands. Most of the commands take a printer-name argument to tell on which printer to operate. You can use all for the printer-name to mean all printers listed in /etc/printcap. abort printer-name Cancel the current job and stop the printer. Users can still submit jobs if the queue is enabled. clean printer-name Remove old files from the printer's spooling directory. Occasionally, the files that make up a job are not properly removed by LPD, particularly if there have been errors during printing or a lot of administrative activity. This command finds files that do not belong in the spooling directory and removes them. disable printer-name Disable queuing of new jobs. If the printer is running, it will continue to print any jobs remaining in the queue. The superuser (root) can always submit jobs, even to a disabled queue. This command is useful while you are testing a new printer or filter installation: disable the queue and submit jobs as root. Other users will not be able to submit jobs until you complete your testing and re-enable the queue with the enable command. down printer-name message Take a printer down. Equivalent to disable followed by stop. The message appears as the printer's status whenever a user checks the printer's queue with &man.lpq.1; or status with lpc status. enable printer-name Enable the queue for a printer. Users can submit jobs but the printer will not print anything until it is started. help command-name Print help on the command command-name. With no command-name, print a summary of the commands available. restart printer-name Start the printer. Ordinary users can use this command if some extraordinary circumstance hangs LPD, but they cannot start a printer stopped with either the stop or down commands. The restart command is equivalent to abort followed by start. start printer-name Start the printer. The printer will print jobs in its queue. stop printer-name Stop the printer. The printer will finish the current job and will not print anything else in its queue. Even though the printer is stopped, users can still submit jobs to an enabled queue. topq printer-name job-or-username Rearrange the queue for printer-name by placing the jobs with the listed job numbers or the jobs belonging to username at the top of the queue. For this command, you cannot use all as the printer-name. up printer-name Bring a printer up; the opposite of the down command. Equivalent to start followed by enable. &man.lpc.8; accepts the above commands on the command line. If you do not enter any commands, &man.lpc.8; enters an interactive mode, where you can enter commands until you type exit, quit, or end-of-file. Alternatives to the Standard Spooler If you have been reading straight through this manual, by now you have learned just about everything there is to know about the LPD spooling system that comes with &os;. You can probably appreciate many of its shortcomings, which naturally leads to the question: What other spooling systems are out there (and work with &os;)? LPRng - LPRng - - LPRng, which purportedly + LPRngLPRng, which purportedly means LPR: the Next Generation is a complete rewrite of PLP. Patrick Powell and Justin Mason (the principal maintainer of PLP) collaborated to make LPRng. The main site for LPRng is . CUPS - CUPS - - CUPS, the Common UNIX + CUPSCUPS, the Common UNIX Printing System, provides a portable printing layer for &unix;-based operating systems. It has been developed by Easy Software Products to promote a standard printing solution for all &unix; vendors and users. CUPS uses the Internet Printing Protocol (IPP) as the basis for managing print jobs and queues. The Line Printer Daemon (LPD), Server Message Block (SMB), and AppSocket (aka JetDirect) protocols are also supported with reduced functionality. CUPS adds network printer browsing and PostScript Printer Description (PPD) based printing options to support real-world printing under &unix;. The main site for CUPS is . HPLIP - HPLIP - - HPLIP, the HP &linux; + HPLIPHPLIP, the HP &linux; Imaging and Printing system, is an HP-developed suite of programs that supports printing, scanning and fax facilities for HP appliances. This suite of programs utilizes the CUPS printing system as a backend for some of its printing features. The main site for HPLIP is . Troubleshooting After performing the simple test with &man.lptest.1;, you might have gotten one of the following results instead of the correct printout: It worked, after a while; or, it did not eject a full sheet. The printer printed the above, but it sat for a while and did nothing. In fact, you might have needed to press a PRINT REMAINING or FORM FEED button on the printer to get any results to appear. If this is the case, the printer was probably waiting to see if there was any more data for your job before it printed anything. To fix this problem, you can have the text filter send a FORM FEED character (or whatever is necessary) to the printer. This is usually sufficient to have the printer immediately print any text remaining in its internal buffer. It is also useful to make sure each print job ends on a full sheet, so the next job does not start somewhere on the middle of the last page of the previous job. The following replacement for the shell script /usr/local/libexec/if-simple prints a form feed after it sends the job to the printer: #!/bin/sh # # if-simple - Simple text input filter for lpd # Installed in /usr/local/libexec/if-simple # # Simply copies stdin to stdout. Ignores all filter arguments. # Writes a form feed character (\f) after printing job. /bin/cat && printf "\f" && exit 0 exit 2 It produced the staircase effect. You got the following on paper: !"#$%&'()*+,-./01234 "#$%&'()*+,-./012345 #$%&'()*+,-./0123456 - MS-DOS - OS/2 - ASCII You have become another victim of the staircase effect, caused by conflicting interpretations of what characters should indicate a new line. &unix; style operating systems use a - single character: ASCII code 10, the line feed (LF). - &ms-dos;, &os2;, and others uses a pair of characters, + single character: ASCIIASCII code 10, the line feed (LF). + &ms-dos;MS-DOS, &os2;OS/2, and others uses a pair of characters, ASCII code 10 and ASCII code 13 (the carriage return or CR). Many printers use the &ms-dos; convention for representing new-lines. When you print with &os;, your text used just the line feed character. The printer, upon seeing a line feed character, advanced the paper one line, but maintained the same horizontal position on the page for the next character to print. That is what the carriage return is for: to move the location of the next character to print to the left edge of the paper. Here is what &os; wants your printer to do: Printer received CR Printer prints CR Printer received LF Printer prints CR + LF Here are some ways to achieve this: Use the printer's configuration switches or control panel to alter its interpretation of these characters. Check your printer's manual to find out how to do this. If you boot your system into other operating systems besides &os;, you may have to reconfigure the printer to use a an interpretation for CR and LF characters that those other operating systems use. You might prefer one of the other solutions, below. Have &os;'s serial line driver automatically convert LF to CR+LF. Of course, this works with printers on serial ports only. To enable this feature, use the ms# capability and set the onlcr mode in the /etc/printcap file for the printer. Send an escape code to the printer to have it temporarily treat LF characters differently. Consult your printer's manual for escape codes that your printer might support. When you find the proper escape code, modify the text filter to send the code first, then send the print job. PCL Here is an example text filter for printers that understand the Hewlett-Packard PCL escape codes. This filter makes the printer treat LF characters as a LF and CR; then it sends the job; then it sends a form feed to eject the last page of the job. It should work with nearly all Hewlett Packard printers. #!/bin/sh # # hpif - Simple text input filter for lpd for HP-PCL based printers # Installed in /usr/local/libexec/hpif # # Simply copies stdin to stdout. Ignores all filter arguments. # Tells printer to treat LF as CR+LF. Ejects the page when done. printf "\033&k2G" && cat && printf "\033&l0H" && exit 0 exit 2 Here is an example /etc/printcap from a host called orchid. It has a single printer attached to its first parallel port, a Hewlett Packard LaserJet 3Si named teak. It is using the above script as its text filter: # # /etc/printcap for host orchid # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ :lp=/dev/lpt0:sh:sd=/var/spool/lpd/teak:mx#0:\ :if=/usr/local/libexec/hpif: It overprinted each line. The printer never advanced a line. All of the lines of text were printed on top of each other on one line. This problem is the opposite of the staircase effect, described above, and is much rarer. Somewhere, the LF characters that &os; uses to end a line are being treated as CR characters to return the print location to the left edge of the paper, but not also down a line. Use the printer's configuration switches or control panel to enforce the following interpretation of LF and CR characters: Printer receives Printer prints CR CR LF CR + LF The printer lost characters. While printing, the printer did not print a few characters in each line. The problem might have gotten worse as the printer ran, losing more and more characters. The problem is that the printer cannot keep up with the speed at which the computer sends data over a serial line (this problem should not occur with printers on parallel ports). There are two ways to overcome the problem: If the printer supports XON/XOFF flow control, have &os; use it by specifying the ixon mode in the ms# capability. If the printer supports the Request to Send / Clear to Send hardware handshake (commonly known as RTS/CTS), specify the crtscts mode in the ms# capability. Make sure the cable connecting the printer to the computer is correctly wired for hardware flow control. It printed garbage. The printer printed what appeared to be random garbage, but not the desired text. This is usually another symptom of incorrect communications parameters with a serial printer. Double-check the bps rate in the br capability, and the parity setting in the ms# capability; make sure the printer is using the same settings as specified in the /etc/printcap file. Nothing happened. If nothing happened, the problem is probably within &os; and not the hardware. Add the log file (lf) capability to the entry for the printer you are debugging in the /etc/printcap file. For example, here is the entry for rattan, with the lf capability: rattan|line|diablo|lp|Diablo 630 Line Printer:\ :sh:sd=/var/spool/lpd/rattan:\ :lp=/dev/lpt0:\ :if=/usr/local/libexec/if-simple:\ :lf=/var/log/rattan.log Then, try printing again. Check the log file (in our example, /var/log/rattan.log) to see any error messages that might appear. Based on the messages you see, try to correct the problem. If you do not specify a lf capability, LPD uses /dev/console as a default. diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.xml b/en_US.ISO8859-1/books/handbook/security/chapter.xml index 6fc287d26b..3c47c57dbe 100644 --- a/en_US.ISO8859-1/books/handbook/security/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/security/chapter.xml @@ -1,3835 +1,3830 @@ Matthew Dillon Much of this chapter has been taken from the security(7) manual page by Security security Synopsis This chapter provides a basic introduction to system security concepts, some general good rules of thumb, and some advanced topics under &os;. Many of the topics covered here can be applied to system and Internet security in general. Securing a system is imperative to protect data, intellectual property, time, and much more from the hands of hackers and the like. &os; provides an array of utilities and mechanisms to protect the integrity and security of the system and network. After reading this chapter, you will know: Basic &os; system security concepts. The various crypt mechanisms available in &os;. How to set up one-time password authentication. How to configure TCP Wrappers for use with &man.inetd.8;. How to set up Kerberos on &os;. How to configure IPsec and create a VPN. How to configure and use OpenSSH on &os;. How to use filesystem ACLs. How to use portaudit to audit third party software packages installed from the Ports Collection. How to utilize &os; security advisories. What Process Accounting is and how to enable it on &os;. Understand the resource limits database and how to utilize it to control user resources. Before reading this chapter, you should: Understand basic &os; and Internet concepts. Additional security topics are covered elsewhere in this Handbook. For example, Mandatory Access Control is discussed in and Internet firewalls are discussed in . Introduction Security is a function that begins and ends with the system administrator. While &os; provides some inherent security, the job of configuring and maintaining additional security mechanisms is probably one of the single largest undertakings of the sysadmin. 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 compromise the root account. Security concerns can be split up into several categories: Denial of service attacks. User account compromises. Root compromise through accessible services. Root compromise via user accounts. Backdoor creation. DoS attacks Denial of Service (DoS) security DoS attacks Denial of Service (DoS) Denial of Service (DoS) A Denial of Service DoS attack is an action that deprives the machine of needed resources. Typically, DoS attacks are brute-force mechanisms that attempt to crash or otherwise make a machine unusable by overwhelming its services or network stack. 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. This type of attack may not be able to take the machine down, but it can saturate the Internet connection. security account compromises A user account compromise is more common than a DoS attack. Many sysadmins still run unencrypted services, meaning that users logging into the system from a remote location are vulnerable to having their password sniffed. The attentive sysadmin analyzes the remote access logs looking for suspicious source addresses and suspicious logins. In a well secured and maintained system, access to a user account does not necessarily give the attacker access to root. Without root access, the attacker cannot generally hide his tracks and may, at best, be able to do nothing more than mess with the user's files or crash the machine. User account compromises are common because users tend not to take the precautions that sysadmins take. security backdoors There are potentially many ways to break root: the attacker may know the root password, the attacker may exploit a bug in a service which runs as root, or the attacker may know of a bug in a SUID-root program. An attacker may utilize a program known as a backdoor to search for vulnerable systems, take advantage of unpatched exploits to access a system, and hide traces of illegal activity. Security remedies should always be implemented with a multi-layered onion peel approach and can be categorized as follows: Secure root and staff accounts. Secure root–run servers and SUID/SGID binaries. Secure user accounts. Secure the password file. Secure the kernel core, raw devices, and filesystems. Quick detection of inappropriate changes made to the system. Paranoia. The next section covers these items in greater depth. Securing &os; security securing &os; This section describes methods for securing a &os; system against the attacks that were mentioned in the previous section. Securing the <username>root</username> Account &man.su.1; Most systems have a password assigned to the root account. Assume that this password is always at risk of being compromised. This does not mean that the password should be disabled as the password is almost always necessary for console access to the machine. However, it should not be possible to use this password outside of the console or possibly even with &man.su.1;. For example, setting the entries in /etc/ttys to insecure prevents root logins to the specified terminals. In &os;, root logins using &man.ssh.1; are disabled by default as PermitRootLogin is set to no in /etc/ssh/sshd_config. Consider every access method as services such as FTP often fall through the cracks. Direct root logins should only be allowed via the system console. wheel Since a sysadmin needs access to root, additional password verification should be configured. One method is to add appropriate user accounts to wheel in /etc/group. Members of wheel are allowed to &man.su.1; to root. Only those users who actually need to have root access should be placed in wheel. When using Kerberos for authentication, create a .k5login in the home directory of root to allow &man.ksu.1; to be used without having to place anyone in wheel. To lock an account completely, use &man.pw.8;: &prompt.root; pw lock staff This will prevent the specified user from logging in using any mechanism, including &man.ssh.1;. Another method of blocking access to accounts would be to replace the encrypted password with a single * character. This character would never match the encrypted password and thus blocks user access. For example, the entry for the following account: foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh could be changed to this using &man.vipw.8;: foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh This prevents foobar from logging in using conventional methods. This method for access restriction is flawed on sites using Kerberos or in situations where the user has set up keys with &man.ssh.1;. These security mechanisms assume that users are logging in from a more restrictive server to a less restrictive server. For example, if the server is running network services, the workstation should not be running any. In order for a workstation to be reasonably secure, run zero or as few services as possible and run a password-protected screensaver. Of course, given physical access to any system, an attacker can break any sort of security. Fortunately, many break-ins occur remotely, over a network, from people who do not have physical access to the system. Using Kerberos provides the ability to disable or change the password for a user in one place, and have it immediately affect all the machines on which the user has an account. If an account is compromised, the ability to instantly change the associated password on all machines should not be underrated. Additional restrictions can be imposed with Kerberos: a Kerberos ticket can be configured to timeout and the Kerberos system can require that the user choose a new password after a configurable period of time. Securing Root-run Servers and SUID/SGID Binaries sandboxes &man.sshd.8; The prudent sysadmin only enables required services and is aware that third party servers are often the most bug-prone. Never run a server that has not been checked out carefully. Think twice before running any service as root as many daemons can be run as a separate service account or can be started in a sandbox. Do not activate insecure services such as &man.telnetd.8; or &man.rlogind.8;. Another potential security hole is SUID-root and SGID binaries. Most of these binaries, such as &man.rlogin.1;, 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. It is recommended to restrict SUID binaries to a special group that only staff can access, and to delete any unused SUID binaries. 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 encrypted password file, potentially compromising user accounts. Alternatively, an intruder who breaks group kmem can monitor keystrokes sent through ptys, including ptys 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. Be vigilant in the monitoring of user accounts. Use of &man.ssh.1; and Kerberos for user accounts requires extra administration and technical support, but provides a good solution compared to an encrypted password file. Securing the Password File The only sure fire way is to star out as many passwords as possible and use &man.ssh.1; or Kerberos for access to those accounts. Even though the encrypted 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. Security scripts should be used to check for and report changes to the password file as described in the Checking file integrity section. Securing the Kernel Core, Raw Devices, and Filesystems Most modern kernels have a packet sniffing device driver built in. Under &os; it is called bpf. This device is needed for DHCP, but can be removed in the custom kernel configuration file of systems that do not provide or use DHCP. &man.sysctl.8; Even if bpf is disabled, /dev/mem and /dev/kmem are still problematic. An intruder can still write to raw disk devices. An enterprising intruder can use &man.kldload.8; to install his own bpf, or another sniffing device, on a running kernel. To avoid these problems, run the kernel at a higher security level, at least security level 1. The security level of the kernel can be set in a variety of ways. The simplest way of raising the security level of a running kernel is to set kern.securelevel: &prompt.root; sysctl kern.securelevel=1 By default, the &os; kernel boots with a security level of -1. This is called insecure mode because immutable file flags may be turned off and all devices may be read from or written to. The security level will remain at -1 unless it is altered, either by the administrator or by &man.init.8;, because of a setting in the startup scripts. The security level may be raised during system startup by setting kern_securelevel_enable to YES in /etc/rc.conf, and the value of kern_securelevel to the desired security level. Once the security level is set to 1 or a higher value, the append-only and immutable files are honored, they cannot be turned off, and access to raw devices is denied. Higher levels restrict even more operations. For a full description of the effect of various security levels, refer to &man.security.7; and &man.init.8;. Bumping the security level to 1 or higher may cause a few problems to &xorg;, as access to /dev/io will be blocked, or to the installation of &os; built from source as installworld needs to temporarily reset the append-only and immutable flags of some files. In the case of &xorg;, it may be possible to work around this by starting &man.xdm.1; early in the boot process, when the security level is still low enough. Workarounds may not be possible for all secure levels or for all the potential restrictions they enforce. A bit of forward planning is a good idea. Understanding the restrictions imposed by each security level is important as they severely diminish the ease of system use. It will also make choosing a default setting much simpler and prevent any surprises. If the kernel's security level is raised to 1 or a higher value, it may be useful to set the schg flag on critical startup binaries, directories, script files, and everything that gets run up to the point where the security level is set. A less strict compromise is to run the system at a higher security level but skip setting the schg flag. Another possibility is to mount / and /usr read-only. It should be noted that being too draconian about what is permitted may prevent detection of an intrusion. Checking File Integrity One can only protect the core system configuration and control files so much before the convenience factor rears its ugly head. For example, using &man.chflags.1; 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 an intrusion detection window. Security measures are useless or, worse, present a false sense of security, if potential intrusions cannot be detected. Half the job of security is to slow down, not stop, an attacker, in order to catch him in the act. The best way to detect an intrusion 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 security scripts on the extra-security limited-access system makes them mostly invisible to potential attackers. In order to take maximum advantage, the limited-access box needs significant access to the other machines, usually either through a read-only NFS export or by setting up &man.ssh.1; key-pairs. Except for its network traffic, NFS is the least visible method, allowing the administrator to monitor the filesystems on each client box virtually undetected. If a limited-access server is connected to the client boxes through a switch, the NFS method is often the better choice. If a limited-access server is connected to the client boxes through several layers of routing, the NFS method may be too insecure and &man.ssh.1; may be the better choice. Once a limited-access box has been given at least read access to the client systems it is supposed to monitor, create the monitoring scripts. Given an NFS mount, write scripts out of simple system utilities such as &man.find.1; and &man.md5.1;. It is best to physically &man.md5.1; the client system's files 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 alert the sysadmin. 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 &man.ssh.1; rather than NFS, writing the security script is more difficult. For example, &man.scp.1; is needed to send the scripts to the client box in order to run them. The &man.ssh.1; client on the client box may already be compromised. Using &man.ssh.1; may be necessary when running over insecure links, but it is harder to deal with. A good security script will also check for changes to hidden configuration files, such as .rhosts and .ssh/authorized_keys, as these files might fall outside the purview of the MD5 check. For a large amount of user disk space, it may take too long to run through every file on those partitions. In this case, consider setting mount flags to disallow SUID binaries by using nosuid with &man.mount.8;. Scan these partitions at least once a week, since the objective is to detect a break-in attempt, whether or not the attempt succeeds. Process accounting (see &man.accton.8;) is a relatively low-overhead feature of &os; which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder broke into a system, assuming the file is still intact after the break-in has occurred. Finally, security scripts should process the log files, and the logs themselves should be generated in as secure a manner as possible and sent to a remote syslog server. An intruder will try 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 to a secure machine monitoring the consoles. Paranoia A little paranoia never hurts. As a rule, a sysadmin can add any number of security features which do not affect convenience and can add security features that do affect convenience with some added thought. More importantly, a security administrator should mix it up a bit. If recommendations, such as those mentioned in this section, are applied verbatim, those methodologies are given to the prospective attacker who also has access to this document. Denial of Service Attacks Denial of Service (DoS) A DoS attack is typically a packet attack. While there is not much one can do about spoofed packet attacks that saturate a network, one can generally limit the damage by ensuring that the attack cannot take down servers by: Limiting server forks. Limiting springboard attacks such as ICMP response attacks and ping broadcasts. Overloading the kernel route cache. A common DoS attack scenario is to force a forking server to spawn so many child processes that the host system eventually runs out of memory and file descriptors, and then grinds to a halt. There are several options to &man.inetd.8; 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 &man.inetd.8; carefully and pay specific attention to , , and . Spoofed IP attacks will circumvent to &man.inetd.8;, so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters. Sendmail provides , which tends to work better than trying to use Sendmail's load limiting options due to the load lag. Specify a MaxDaemonChildren when starting Sendmail which is high enough to handle the expected load, but not so high that the computer cannot handle that number of Sendmail instances. It is prudent to run Sendmail in queued mode using and to run the daemon (sendmail -bd) separate from the queue-runs (sendmail -q15m). For real-time delivery, run the queue at a much lower interval, such as , but be sure to specify a reasonable MaxDaemonChildren to prevent cascade failures. &man.syslogd.8; can be attacked directly and it is strongly recommended to use whenever possible, and otherwise. Be careful with connect-back services such as reverse-identd, which can be attacked directly. The reverse-ident feature of TCP Wrappers is not recommended for this reason. It is recommended to protect internal services from external access by firewalling them at the border routers. This is to prevent saturation attacks from outside the LAN, not so much to protect internal services from network-based root compromise. Always configure an exclusive firewall which denies everything by default except for traffic which is explicitly allowed. The range of port numbers used for dynamic binding in &os; is controlled by several net.inet.ip.portrange &man.sysctl.8; variables. Another common DoS attack, called a springboard attack, causes the server to generate responses which overloads 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 the LAN's broadcast address with the source IP address set to the machine to attack. If the border routers are not configured to drop ping packets sent to broadcast addresses, the LAN generates sufficient responses to the spoofed source address to saturate the victim, especially when the attack is against several dozen broadcast addresses over several dozen different networks at once. A second common springboard attack constructs packets that generate ICMP error responses which can saturate a server's incoming network and cause the server to saturate its outgoing network with ICMP responses. This type of attack can crash the server by running it out of memory, especially if the server cannot drain the ICMP responses it generates fast enough. Use the &man.sysctl.8; variable net.inet.icmp.icmplim to limit these attacks. The last major class of springboard attacks is related to certain internal &man.inetd.8; services such as the UDP echo service. An attacker spoofs a UDP packet with a source address of server A's echo port and a destination address of server B's echo port, where server A and B on the same LAN. The two servers bounce this one packet back and forth between each other. The attacker can overload both servers and the LAN by injecting a few packets in this manner. Similar problems exist with the chargen port. These inetd-internal test services should remain disabled. Spoofed packet attacks may be used to overload the kernel route cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache &man.sysctl.8; 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 than rtminexpire. This creates 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 the 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 as this could crash the machine. Setting both parameters to 2 seconds should be sufficient to protect the route table from attack. Access Issues with Kerberos and &man.ssh.1; &man.ssh.1; There are a few issues with both Kerberos and &man.ssh.1; that need to be addressed if they are used. Kerberos is an excellent authentication protocol, but there are bugs in the kerberized versions of &man.telnet.1; and &man.rlogin.1; that make them unsuitable for dealing with binary streams. By default, Kerberos does not encrypt a session unless is used whereas &man.ssh.1; encrypts everything. While &man.ssh.1; works well, it forwards encryption keys by default. This introduces a security risk to a user who uses &man.ssh.1; to access an insecure machine from a secure workstation. The keys themselves are not exposed, but &man.ssh.1; installs a forwarding port for the duration of the login. If an attacker has broken root on the insecure machine, he can utilize that port to gain access to any other machine that those keys unlock. It is recommended that &man.ssh.1; is used in combination with Kerberos whenever possible for staff logins and &man.ssh.1; can be compiled with Kerberos support. This reduces reliance on potentially exposed SSH keys while protecting passwords via Kerberos. Keys should only be used for automated tasks from secure machines as this is something that Kerberos is unsuited to. It is recommended to either turn off key-forwarding in the SSH configuration, or to make use of from=IP/DOMAIN in authorized_keys to make the key only usable to entities logging in from specific machines. Bill Swingle Parts rewritten and updated by DES, Blowfish, MD5, SHA256, SHA512, and Crypt security crypt crypt Blowfish DES MD5 SHA256 SHA512 Every user on a &unix; system has a password associated with their account. In order to keep these passwords secret, they are encrypted with a one-way hash, as they can be easily encrypted but not decrypted. The operating system itself does not 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. Originally, the only secure way to encrypt passwords in &unix; was based on the Data Encryption Standard (DES). Since the source code for DES could not be exported outside the US, &os; had to find a way to both comply with US law and retain compatibility with other &unix; variants that used DES. The solution was MD5 which is believed to be more secure than DES. Recognizing the Crypt Mechanism Currently the library supports DES, MD5, Blowfish, SHA256, and SHA512 hash functions. To identify which encryption method &os; is set up to use, examine the encrypted passwords in /etc/master.passwd. Passwords encrypted with the MD5 hash are longer than those encrypted with the DES hash and begin with the characters $1$. Passwords starting with $2a$ are encrypted with the Blowfish hash function. 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. Both SHA256 and SHA512 begin with the characters $6$. The password format used for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of des, md5, blf, sha256 or sha512. Refer to &man.login.conf.5; for more information about login capabilities. One-time Passwords one-time passwords security one-time passwords By default, &os; includes support for One-time Passwords In Everything (OPIE), which uses the MD5 hash by default. There are three different types of passwords. The first is the usual &unix; style or Kerberos password. The second is the one-time password which is generated by &man.opiekey.1; and accepted by &man.opiepasswd.1; and the login prompt. The final type of password is the secret password used by &man.opiekey.1;, and sometimes &man.opiepasswd.1;, to generate one-time passwords. The secret password has nothing to do with the &unix; password. They can be the same, but this is not recommended. OPIE secret passwords are not limited to 8 characters like old &unix; passwordsUnder &os; the standard login password may be up to 128 characters in length.. Passwords of six or seven word long phrases are fairly common. For the most part, the OPIE system operates completely independently of the &unix; password system. Besides the password, there are two other pieces of data that are important to OPIE. One is the seed or key, consisting of two letters and five digits. The other is the iteration count, a number between 1 and 100. OPIE creates the one-time password by concatenating the seed and the secret password, applying the MD5 hash as many times as specified by the iteration count, and turning the result into six short English words. These six English words are the one-time password. The authentication system (primarily PAM) keeps 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, OPIE must be reinitialized. There are a few programs involved in this process. &man.opiekey.1; accepts an iteration count, a seed, and a secret password, and generates a one-time password or a consecutive list of one-time passwords. In addition to initializing OPIE, &man.opiepasswd.1; is used to change passwords, iteration counts, or seeds. It takes either a secret passphrase, or an iteration count, seed, and a one-time password. The relevant credential files in /etc/opiekeys are examined by &man.opieinfo.1; which prints out the invoking user's current iteration count and seed. There are four different sorts of operations. The first is to use &man.opiepasswd.1; over a secure connection to set up one-time-passwords for the first time, or to change the password or seed. The second operation is to use &man.opiepasswd.1; over an insecure connection, in conjunction with &man.opiekey.1; over a secure connection, to do the same. The third is to use &man.opiekey.1; to log in over an insecure connection. The fourth is to use &man.opiekey.1; to generate a number of keys which can be written down or printed out to carry to insecure locations in order to make a connection to anywhere. Secure Connection Initialization To initialize OPIE for the first time, execute &man.opiepasswd.1;: &prompt.user; opiepasswd -c [grimreaper] ~ $ opiepasswd -f -c Adding unfurl: Only use this method from the console; NEVER from remote. If you are using telnet, xterm, or a dial-in, type ^C now or exit with no password. Then run opiepasswd without the -c parameter. Using MD5 to compute responses. Enter new secret pass phrase: Again new secret pass phrase: ID unfurl OTP key is 499 to4268 MOS MALL GOAT ARM AVID COED At the Enter new secret pass phrase: or Enter secret password: prompt, enter a password or phrase. This is not the login password as this password is used to generate the one-time login keys. The ID line gives the parameters of the instance: the login name, iteration count, and seed. When logging in, the system will remember these parameters and display them, meaning that they do not have to be memorized. The last line gives the particular one-time password which corresponds to those parameters and the secret password. At the next login, this one-time password is the one to use. Insecure Connection Initialization To initialize or change the secret password over an insecure connection, a secure connection is needed to some place where &man.opiekey.1; can be run. This might be a shell prompt on a trusted machine. An iteration count is needed, where 100 is probably a good value, and the seed can either be specified or the randomly-generated one used. On the insecure connection, the machine being initialized, use &man.opiepasswd.1;: &prompt.user; opiepasswd Updating unfurl: You need the response from an OTP generator. Old secret pass phrase: otp-md5 498 to4268 ext Response: GAME GAG WELT OUT DOWN CHAT New secret pass phrase: otp-md5 499 to4269 Response: LINE PAP MILK NELL BUOY TROY ID mark OTP key is 499 gr4269 LINE PAP MILK NELL BUOY TROY To accept the default seed, press Return. Before entering an access password, move over to the secure connection and give it the same parameters: &prompt.user; opiekey 498 to4268 Using the MD5 algorithm to compute response. Reminder: Do not use opiekey from telnet or dial-in sessions. Enter secret pass phrase: GAME GAG WELT OUT DOWN CHAT Switch back over to the insecure connection, and copy the generated one-time password over to the relevant program. Generating a Single One-time Password After initializing OPIE and logging in, a prompt like this will be displayed: &prompt.user; telnet example.com Trying 10.0.0.1... Connected to example.com Escape character is '^]'. FreeBSD/i386 (example.com) (ttypa) login: <username> otp-md5 498 gr4269 ext Password: The OPIE prompts provides a useful feature. If Return is pressed at the password prompt, the prompt will turn echo on and display what is typed. This can be useful when attempting to type in a password by hand from a printout. MS-DOS Windows MacOS At this point, generate the one-time password to answer this login prompt. This must be done on a trusted system where it is safe to run &man.opiekey.1;. There are versions of this command for &windows;, &macos; and &os;. This command needs the iteration count and the seed as command line options. Use cut-and-paste from the login prompt on the machine being logged in to. On the trusted system: &prompt.user; opiekey 498 to4268 Using the MD5 algorithm to compute response. Reminder: Do not use opiekey from telnet or dial-in sessions. Enter secret pass phrase: GAME GAG WELT OUT DOWN CHAT Once the one-time password is generated, continue to log in. Generating Multiple One-time Passwords Sometimes there is no access to a trusted machine or secure connection. In this case, it is possible to use &man.opiekey.1; to generate a number of one-time passwords beforehand. For example: &prompt.user; opiekey -n 5 30 zz99999 Using the MD5 algorithm to compute response. Reminder: Do not use opiekey from telnet or dial-in sessions. Enter secret pass phrase: <secret password> 26: JOAN BORE FOSS DES NAY QUIT 27: LATE BIAS SLAY FOLK MUCH TRIG 28: SALT TIN ANTI LOON NEAL USE 29: RIO ODIN GO BYE FURY TIC 30: GREW JIVE SAN GIRD BOIL PHI The requests five keys in sequence, and specifies what the last iteration number should be. Note that these are printed out in reverse order of use. The really paranoid might want to write the results down by hand; otherwise, print the list. Each line shows both the iteration count and the one-time password. Scratch off the passwords as they are used. Restricting Use of &unix; Passwords OPIE can restrict the use of &unix; passwords based on the IP address of a login session. The relevant file is /etc/opieaccess, which is present by default. Refer to &man.opieaccess.5; for more information on this file and which security considerations to be aware of when using it. Here is a sample opieaccess: permit 192.168.0.0 255.255.0.0 This line allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use &unix; passwords at any time. If no rules in opieaccess are matched, the default is to deny non-OPIE logins. Tom Rhodes Written by TCP Wrappers TCP Wrappers TCP Wrappers extends the abilities of to provide support for every server daemon under its control. It can be configured to provide logging support, return messages to connections, and permit a daemon to only accept internal connections. While some of these features can be provided by implementing a firewall, TCP Wrappers adds an extra layer of protection and goes beyond the amount of control a firewall can provide. TCP Wrappers should not be considered a replacement for a properly configured firewall. TCP Wrappers should be used in conjunction with a firewall and other security enhancements. Initial Configuration To enable TCP Wrappers in &os;, ensure the &man.inetd.8; server is started from /etc/rc.conf with . Then, properly configure /etc/hosts.allow. Unlike other implementations of TCP Wrappers, the use of hosts.deny has been deprecated. All configuration options should be placed in /etc/hosts.allow. In the simplest configuration, daemon connection policies are set to either be permitted or blocked depending on the options in /etc/hosts.allow. The default configuration in &os; is to allow a connection to every daemon started with &man.inetd.8;. Basic configuration usually takes the form of daemon : address : action, where daemon is the daemon which &man.inetd.8; started, address is a valid hostname, IP address, or an IPv6 address enclosed in brackets ([ ]), and action is either allow or deny. TCP Wrappers uses a first rule match semantic, meaning that the configuration file is scanned in ascending order for a matching rule. When a match is found, the rule is applied and the search process stops. For example, to allow POP3 connections via the mail/qpopper daemon, the following lines should be appended to hosts.allow: # This line is required for POP3 connections: qpopper : ALL : allow After adding this line, &man.inetd.8; needs to be restarted: &prompt.root; service inetd restart Advanced Configuration TCP Wrappers provides advanced options to allow more control over the way connections are handled. In some cases, it may be appropriate to return a comment to certain hosts or daemon connections. In other cases, a log entry should be recorded or an email sent to the administrator. Other situations may require the use of a service for local connections only. This is all possible through the use of configuration options known as wildcards, expansion characters and external command execution. External Commands Suppose that a situation occurs where a connection should be denied yet a reason should be sent to the individual who attempted to establish that connection. That action is possible with . When a connection attempt is made, executes a shell command or script. An example exists in hosts.allow: # The rest of the daemons are protected. ALL : ALL \ : severity auth.info \ : twist /bin/echo "You are not welcome to use %d from %h." In this example, the message You are not allowed to use daemon from hostname. will be returned for any daemon not previously configured in the access file. This is useful for sending a reply back to the connection initiator right after the established connection is dropped. Any message returned must be wrapped in quote (") characters. It may be possible to launch a denial of service attack on the server if an attacker, or group of attackers, could flood these daemons with connection requests. Another possibility is to use . Like , implicitly denies the connection and may be used to run external shell commands or scripts. Unlike , will not send a reply back to the individual who established the connection. For example, consider the following configuration line: # We do not allow connections from example.com: ALL : .example.com \ : spawn (/bin/echo %a from %h attempted to access %d >> \ /var/log/connections.log) \ : deny This will deny all connection attempts from *.example.com and log the hostname, IP address, and the daemon to which access was attempted to /var/log/connections.log. This example uses the substitution characters %a and %h. Refer to &man.hosts.access.5; for the complete list. Wildcard Options The ALL option may be used to match every instance of a daemon, domain, or an IP address. Another wildcard is PARANOID which may be used to match any host which provides an IP address that may be forged. For example, PARANOID may be used to define an action to be taken whenever a connection is made from an IP address that differs from its hostname. In this example, all connection requests to &man.sendmail.8; which have an IP address that varies from its hostname will be denied: # Block possibly spoofed requests to sendmail: sendmail : PARANOID : deny Using the PARANOID wildcard may severely cripple servers if the client or server has a broken DNS setup. Administrator discretion is advised. To learn more about wildcards and their associated functionality, refer to &man.hosts.access.5;. Before any of the specific configuration lines above will work, the first configuration line should be commented out in hosts.allow. Tillman Hodgson Contributed by Mark Murray Based on a contribution by <application>Kerberos5</application> Kerberos is a network add-on system/protocol that allows users to authenticate themselves through the services of a secure server. Kerberos can be described as an identity-verifying proxy system. It can also be described as a trusted third-party authentication system. After a user authenticates with Kerberos, their communications can be encrypted to assure privacy and data integrity. The only function of Kerberos is to provide the secure authentication of users on the network. It does not provide authorization functions (what users are allowed to do) or auditing functions (what those users did). It is recommended that Kerberos be used with other security methods which provide authorization and audit services. This section provides a guide on how to set up Kerberos as distributed for &os;. Refer to the relevant manual pages for more complete descriptions. For purposes of demonstrating a Kerberos installation, the various name spaces will be as follows: The DNS domain (zone) will be example.org. The Kerberos realm will be EXAMPLE.ORG. Use real domain names when setting up Kerberos even if it will run internally. This avoids DNS problems and assures inter-operation with other Kerberos realms. History Kerberos5 history Kerberos was created by MIT as a solution to network security problems. The Kerberos protocol uses strong cryptography so that a client can prove its identity to a server (and vice versa) across an insecure network connection. Kerberos is both the name of a network authentication protocol and an adjective to describe programs that implement it, such as Kerberos telnet. The current version of the protocol is version 5, described in RFC 1510. Several free implementations of this protocol are available, covering a wide range of operating systems. The Massachusetts Institute of Technology (MIT), where Kerberos was originally developed, continues to develop their Kerberos package. It is commonly used in the US as a cryptography product, and has historically been affected by US export regulations. The MIT Kerberos is available as the security/krb5 package or port. Heimdal Kerberos is another version 5 implementation, and was explicitly developed outside of the US to avoid export regulations. The Heimdal Kerberos distribution is available as a the security/heimdal package or port, and a minimal installation is included in the base &os; install. These instructions assume the use of the Heimdal distribution included in &os;. Setting up a Heimdal <acronym>KDC</acronym> Kerberos5 Key Distribution Center The Key Distribution Center (KDC) is the centralized authentication service that Kerberos provides. It is the computer that issues Kerberos tickets. The KDC is considered trusted by all other computers in the Kerberos realm, and thus has heightened security concerns. While running the Kerberos server requires very few computing resources, a dedicated machine acting only as a KDC is recommended for security reasons. To begin setting up a KDC, ensure that /etc/rc.conf contains the correct settings to act as a KDC. As required, adjust paths to reflect the system: kerberos5_server_enable="YES" kadmind5_server_enable="YES" Next, edit /etc/krb5.conf as follows: [libdefaults] default_realm = EXAMPLE.ORG [realms] EXAMPLE.ORG = { kdc = kerberos.example.org admin_server = kerberos.example.org } [domain_realm] .example.org = EXAMPLE.ORG This /etc/krb5.conf implies that the KDC will use the fully-qualified hostname kerberos.example.org. Add a CNAME (alias) entry to the zone file to accomplish this if the KDC has a different hostname. For large networks with a properly configured DNS server, the above example could be trimmed to: [libdefaults] default_realm = EXAMPLE.ORG With the following lines being appended to the example.org zone file: _kerberos._udp IN SRV 01 00 88 kerberos.example.org. _kerberos._tcp IN SRV 01 00 88 kerberos.example.org. _kpasswd._udp IN SRV 01 00 464 kerberos.example.org. _kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org. _kerberos IN TXT EXAMPLE.ORG For clients to be able to find the Kerberos services, it must have either a fully configured /etc/krb5.conf or a minimally configured /etc/krb5.conf and a properly configured DNS server. Next, create the Kerberos database which contains the keys of all principals encrypted with a master password. It is not required to remember this password as it will be stored in /var/heimdal/m-key. To create the master key, run &man.kstash.8; and enter a password. Once the master key has been created, initialize the database using kadmin -l. This option instructs &man.kadmin.8; to modify the local database files directly rather than going through the &man.kadmind.8; network service. This handles the chicken-and-egg problem of trying to connect to the database before it is created. At the &man.kadmin.8; prompt, use init to create the realm's initial database. Lastly, while still in &man.kadmin.8;, create the first principal using add. Stick to the default options for the principal for now, as these can be changed later with modify. Type ? at the &man.kadmin.8; prompt to see the available options. A sample database creation session is shown below: &prompt.root; kstash Master key: xxxxxxxx Verifying password - Master key: xxxxxxxx &prompt.root; kadmin -l kadmin> init EXAMPLE.ORG Realm max ticket life [unlimited]: kadmin> add tillman Max ticket life [unlimited]: Max renewable life [unlimited]: Attributes []: Password: xxxxxxxx Verifying password - Password: xxxxxxxx Next, start the KDC services. Run service kerberos start and service kadmind start to bring up the services. While there will not be any kerberized daemons running at this point, it is possible to confirm that the KDC is functioning by obtaining and listing a ticket for the principal (user) that was just created from the command-line of the KDC itself: &prompt.user; kinit tillman tillman@EXAMPLE.ORG's Password: &prompt.user; klist Credentials cache: FILE:/tmp/krb5cc_500 Principal: tillman@EXAMPLE.ORG Issued Expires Principal Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG The ticket can then be revoked when finished: &prompt.user; kdestroy <application>Kerberos</application> Enabling a Server with Heimdal Services Kerberos5 enabling services First, copy /etc/krb5.conf from the KDC to the client computer in a secure fashion, such as &man.scp.1;, or physically via a removable media. Next, create /etc/krb5.keytab. This is the major difference between a server providing Kerberos enabled daemons and a workstation: the server must have a keytab. This file contains the server's host key, which allows it and the KDC to verify each others identity. It must be transmitted to the server in a secure fashion, as the security of the server can be broken if the key is made public. Typically, the keytab is transferred to the server using &man.kadmin.8;. This is handy because the host principal, the KDC end of the krb5.keytab, is also created using &man.kadmin.8;. A ticket must already be obtained and this ticket must be allowed to use the &man.kadmin.8; interface in the kadmind.acl. See the section titled Remote administration ininfo heimdal for details on designing access control lists. Instead of enabling remote &man.kadmin.8; access, the administrator can securely connect to the KDC via the local console or &man.ssh.1;, and perform administration locally using kadmin -l. After installing /etc/krb5.conf, use add --random-key from the Kerberos server. This adds the server's host principal. Then, use ext to extract the server's host principal to its own keytab. For example: &prompt.root; kadmin kadmin> add --random-key host/myserver.example.org Max ticket life [unlimited]: Max renewable life [unlimited]: Attributes []: kadmin> ext host/myserver.example.org kadmin> exit Note that ext stores the extracted key in /etc/krb5.keytab by default. If &man.kadmind.8; is not running on the KDC and there is no access to &man.kadmin.8; remotely, add the host principal (host/myserver.EXAMPLE.ORG) directly on the KDC and then extract it to a temporary file to avoid overwriting the /etc/krb5.keytab on the KDC, using something like this: &prompt.root; kadmin kadmin> ext --keytab=/tmp/example.keytab host/myserver.example.org kadmin> exit The keytab can then be securely copied to the server using &man.scp.1; or a removable media. Be sure to specify a non-default keytab name to avoid overwriting the keytab on the KDC. At this point, the server can communicate with the KDC using krb5.conf and it can prove its own identity with krb5.keytab. It is now ready for the Kerberos services to be enabled. For this example, the &man.telnetd.8; service is enabled in /etc/inetd.conf and &man.inetd.8; has been restarted with service inetd restart: telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user The critical change is that the authentication type is set to user. Refer to &man.telnetd.8; for more details. <application>Kerberos</application> Enabling a Client with Heimdal Kerberos5 configure clients Setting up a client computer is easy as only /etc/krb5.conf is needed. Securely copy this file over to the client computer from the KDC. Test the client by attempting to use &man.kinit.1;, &man.klist.1;, and &man.kdestroy.1; from the client to obtain, show, and then delete a ticket for the principal created above. Kerberos applications should also be able to connect to Kerberos enabled servers. If that does not work but obtaining a ticket does, the problem is likely with the server and not with the client or the KDC. When testing a Kerberized application, try using a packet sniffer such as &man.tcpdump.1; to confirm that the password is not sent in the clear. Various non-core Kerberos client applications are available. The minimal installation in &os; installs &man.telnetd.8; as the only Kerberos enabled service. The Heimdal port installs Kerberos enabled versions of &man.ftpd.8;, &man.rshd.8;, &man.rcp.1;, &man.rlogind.8;, and a few other less common programs. The MIT port also contains a full suite of Kerberos client applications. User Configuration Files: <filename>.k5login</filename> and <filename>.k5users</filename> .k5login .k5users Users within a realm typically have their Kerberos principal mapped to a local user account. Occasionally, one needs to grant access to a local user account to someone who does not have a matching Kerberos principal. For example, tillman@EXAMPLE.ORG may need access to the local user account webdevelopers. Other principals may also need access to that local account. The .k5login and .k5users files, placed in a user's home directory, can be used to solve this problem. For example, if .k5login with the following contents is placed in the home directory of webdevelopers, both principals listed will have access to that account without requiring a shared password.: tillman@example.org jdoe@example.org Refer to &man.ksu.1; for more information about .k5users. <application>Kerberos</application> Tips, Tricks, and Troubleshooting - - Kerberos5 - troubleshooting - - When using either the Heimdal or MIT - Kerberos ports, ensure that + KerberosKerberos5troubleshooting ports, ensure that the PATH lists the Kerberos versions of the client applications before the system versions. If all the computers in the realm do not have synchronized time settings, authentication may fail. describes how to synchronize clocks using NTP. MIT and Heimdal interoperate except for &man.kadmin.8;, which is not standardized. If the hostname is changed, the host/ principal must be changed and the keytab updated. This also applies to special keytab entries like the www/ principal used for Apache's www/mod_auth_kerb. All hosts in the realm must be both forward and reverse resolvable in DNS or, at a minimum, in /etc/hosts. CNAMEs will work, but the A and PTR records must be correct and in place. The error message for unresolvable hosts is not intuitive: Kerberos5 refuses authentication because Read req failed: Key table entry not found. Some operating systems that act as clients to the KDC do not set the permissions for &man.ksu.1; to be setuid root. This means that &man.ksu.1; does not work. This is not a KDC error. With MIT Kerberos, in order to allow a principal to have a ticket life longer than the default ten hours, use modify_principal at the &man.kadmin.8; prompt to change the maxlife of both the principal in question and the krbtgt principal. Then the principal can use kinit -l to request a ticket with a longer lifetime. When running a packet sniffer on the KDC to aid in troubleshooting while running &man.kinit.1; from a workstation, the Ticket Granting Ticket (TGT) is sent immediately upon running &man.kinit.1;, even before the password is typed. This is because the Kerberos server freely transmits a TGT to any unauthorized request. However, every TGT is encrypted in a key derived from the user's password. When a user types their password, it is not sent to the KDC, it is instead used to decrypt the TGT that &man.kinit.1; already obtained. If the decryption process results in a valid ticket with a valid time stamp, the user has valid Kerberos credentials. These credentials include a session key for establishing secure communications with the Kerberos server in the future, as well as the actual TGT, which is encrypted with the Kerberos server's own key. This second layer of encryption allows the Kerberos server to verify the authenticity of each TGT. To use long ticket lifetimes, such as a week, when using OpenSSH to connect to the machine where the ticket is stored, make sure that Kerberos is set to no in sshd_config or else tickets will be deleted at log out. Host principals can have a longer ticket lifetime. If the user principal has a lifetime of a week but the host being connected to has a lifetime of nine hours, the user cache will have an expired host principal and the ticket cache will not work as expected. When setting up krb5.dict to prevent specific bad passwords from being used as described in &man.kadmind.8;, remember that it only applies to principals that have a password policy assigned to them. The format used in krb5.dict is one string per line. Creating a symbolic link to /usr/share/dict/words might be useful. Differences with the <acronym>MIT</acronym> Port The major difference between MIT and Heimdal relates to &man.kadmin.8; which has a different, but equivalent, set of commands and uses a different protocol. If the KDC is MIT, the Heimdal version of &man.kadmin.8; cannot be used to administer the KDC remotely, and vice versa. The client applications may also use slightly different command line options to accomplish the same tasks. Following the instructions on the MIT Kerberos web site is recommended. Be careful of path issues: the MIT port installs into /usr/local/ by default, and the normal system applications run instead of MIT versions if PATH lists the system directories first. With the &os; MIT security/krb5 port, be sure to read /usr/local/share/doc/krb5/README.FreeBSD installed by the port to understand why logins via &man.telnetd.8; and klogind behave somewhat oddly. Correcting the incorrect permissions on cache file behavior requires that the login.krb5 binary be used for authentication so that it can properly change ownership for the forwarded credentials. The following edits should also be made to rc.conf: kerberos5_server="/usr/local/sbin/krb5kdc" kadmind5_server="/usr/local/sbin/kadmind" kerberos5_server_enable="YES" kadmind5_server_enable="YES" This is done because the applications for MIT Kerberos installs binaries in the /usr/local hierarchy. Mitigating Limitations Found in <application>Kerberos</application> Kerberos5 limitations and shortcomings <application>Kerberos</application> is an All or Nothing Approach Every service enabled on the network must be modified to work with Kerberos, or be otherwise secured against network attacks, or else the user's credentials could be stolen and re-used. An example of this would be Kerberos enabling all remote shells but not converting the POP3 mail server which sends passwords in plain text. <application>Kerberos</application> is Intended for Single-User Workstations In a multi-user environment, Kerberos is less secure. This is because it stores the tickets in /tmp, which is readable by all users. If a user is sharing a computer with other users, it is possible that the user's tickets can be stolen or copied by another user. This can be overcome with the -c command-line option or, preferably, the KRB5CCNAME environment variable. Storing the ticket in the user's home directory and using file permissions are commonly used to mitigate this problem. The KDC is a Single Point of Failure By design, the KDC must be as secure as its master password database. The KDC should have absolutely no other services running on it and should be physically secure. The danger is high because Kerberos stores all passwords encrypted with the same master key which is stored as a file on the KDC. A compromised master key is not quite as bad as one might fear. The master key is only used to encrypt the Kerberos database and as a seed for the random number generator. As long as access to the KDC is secure, an attacker cannot do much with the master key. Additionally, if the KDC is unavailable, network services are unusable as authentication cannot be performed. This can be alleviated with a single master KDC and one or more slaves, and with careful implementation of secondary or fall-back authentication using PAM. <application>Kerberos</application> Shortcomings Kerberos allows users, hosts and services to authenticate between themselves. It does not have a mechanism to authenticate the KDC to the users, hosts or services. This means that a trojanned &man.kinit.1; could record all user names and passwords. Filesystem integrity checking tools like security/tripwire can alleviate this. Resources and Further Information Kerberos5 external resources The Kerberos FAQ Designing an Authentication System: a Dialog in Four Scenes RFC 1510, The Kerberos Network Authentication Service (V5) MIT Kerberos home page Heimdal Kerberos home page Tom Rhodes Written by OpenSSL security OpenSSL The OpenSSL toolkit is included in &os;. It provides an encryption transport layer on top of the normal communications layer, allowing it to be intertwined with many network applications and services. Some uses of OpenSSL may include encrypted authentication of mail clients and web based transactions such as credit card payments. Many ports such as www/apache22, and mail/claws-mail offer compilation support for building with OpenSSL. In most cases, the Ports Collection will attempt to build the security/openssl port unless WITH_OPENSSL_BASE is explicitly set to yes. The version of OpenSSL included in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols and can be used as a general cryptographic library. While OpenSSL supports the IDEA algorithm, it is disabled by default due to United States patents. To use it, the license should be reviewed and, if the restrictions are acceptable, the MAKE_IDEA variable must be set in /etc/make.conf. One of the most common uses of OpenSSL is to provide certificates for use with software applications. These certificates ensure that the credentials of the company or individual are valid and not fraudulent. If the certificate in question has not been verified by a Certificate Authority (CA), a warning is produced. A CA is a company, such as VeriSign, signs certificates in order to validate the credentials of individuals or companies. This process has a cost associated with it and is not a requirement for using certificates; however, it can put users at ease. Generating Certificates OpenSSL certificate generation To generate a certificate, the following command is available: &prompt.root; openssl req -new -nodes -out req.pem -keyout cert.pem Generating a 1024 bit RSA private key ................++++++ .......................................++++++ writing new private key to 'cert.pem' ----- You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:US State or Province Name (full name) [Some-State]:PA Locality Name (eg, city) []:Pittsburgh Organization Name (eg, company) [Internet Widgits Pty Ltd]:My Company Organizational Unit Name (eg, section) []:Systems Administrator Common Name (eg, YOUR name) []:localhost.example.org Email Address []:trhodes@FreeBSD.org Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []:SOME PASSWORD An optional company name []:Another Name Notice the response directly after the Common Name prompt shows a domain name. This prompt requires a server name to be entered for verification purposes and placing anything but a domain name yields a useless certificate. Other options, such as the expire time and alternate encryption algorithms, are available. A complete list of options is described in &man.openssl.1;. Two files should now exist in the directory in which this command was issued. The certificate request, req.pem, may be sent to a CA who will validate the entered credentials, sign the request, and return the signed certificate. The second file is named cert.pem and is the private key for the certificate and should be protected at all costs. If this falls in the hands of others it can be used to impersonate the user or the server. In cases where a signature from a CA is not required, a self signed certificate can be created. First, generate the RSA key: &prompt.root; openssl dsaparam -rand -genkey -out myRSA.key 1024 Next, generate the CA key: &prompt.root; openssl gendsa -des3 -out myca.key myRSA.key Use this key to create the certificate: &prompt.root; openssl req -new -x509 -days 365 -key myca.key -out new.crt Two new files should appear in the directory: a certificate authority signature file, myca.key and the certificate itself, new.crt. These should be placed in a directory, preferably under /etc, which is readable only by root. Permissions of 0700 are appropriate and can be set using &man.chmod.1;. Using Certificates One use for a certificate is to encrypt connections to the Sendmail MTA. This prevents the use of clear text authentication for users who send mail via the local MTA. Some MUAs will display error if the user has not installed the certificate locally. Refer to the documentation included with the software for more information on certificate installation. To configure Sendmail, the following lines should be placed in the local .mc file: dnl SSL Options define(`confCACERT_PATH',`/etc/certs')dnl define(`confCACERT',`/etc/certs/new.crt')dnl define(`confSERVER_CERT',`/etc/certs/new.crt')dnl define(`confSERVER_KEY',`/etc/certs/myca.key')dnl define(`confTLS_SRV_OPTIONS', `V')dnl In this example, /etc/certs/ stores the certificate and key files locally. After saving the edits, rebuild the local .cf file by typing make install within /etc/mail. Follow that up with make restart which should start the Sendmail daemon. If all went well, there will be no error messages in /var/log/maillog and Sendmail will show up in the process list. For a simple test, connect to the mail server using &man.telnet.1;: &prompt.root; telnet example.com 25 Trying 192.0.34.166... Connected to example.com. Escape character is '^]'. 220 example.com ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT) ehlo example.com 250-example.com Hello example.com [192.0.34.166], pleased to meet you 250-ENHANCEDSTATUSCODES 250-PIPELINING 250-8BITMIME 250-SIZE 250-DSN 250-ETRN 250-AUTH LOGIN PLAIN 250-STARTTLS 250-DELIVERBY 250 HELP quit 221 2.0.0 example.com closing connection Connection closed by foreign host. If the STARTTLS line appears in the output, everything is working correctly. Nik Clayton
nik@FreeBSD.org
 Written by <acronym>VPN</acronym> over IPsec IPsec Hiten M. Pandya
hmp@FreeBSD.org
 Written by Understanding IPsec This section demonstrates the process of setting up IPsec. It assumes familiarity with the concepts of building a custom kernel (see ). IPsec is a protocol which sits on top of the Internet Protocol (IP) layer. It allows two or more hosts to communicate in a secure manner. The &os; IPsec network stack is based on the KAME implementation, which has support for both IPv4 and IPv6. IPsec ESP IPsec AH IPsec consists of two sub-protocols: Encapsulated Security Payload ESP): this protocol protects the IP packet data from third party interference by encrypting the contents using symmetric cryptography algorithms such as Blowfish and 3DES. Authentication Header (AH): this protocol protects the IP packet header from third party interference and spoofing by computing a cryptographic checksum and hashing the IP packet header fields with a secure hashing function. This is then followed by an additional header that contains the hash, to allow the information in the packet to be authenticated. ESP and AH can either be used together or separately, depending on the environment. VPN virtual private network VPN IPsec can either be used to directly encrypt the traffic between two hosts using Transport Mode or to build virtual tunnels using Tunnel Mode. The latter mode is more commonly known as a Virtual Private Network (VPN). Consult &man.ipsec.4; for detailed information on the IPsec subsystem in &os;. To add IPsec support to the kernel, add the following options to the custom kernel configuration file: kernel options IPSEC options IPSEC #IP security device crypto kernel options IPSEC_DEBUG If IPsec debugging support is desired, the following kernel option should also be added: options IPSEC_DEBUG #debug for IP security <acronym>VPN</acronym> Between a Home and Corporate Network VPN creating There is no standard for what constitutes a VPN. VPNs can be implemented using a number of different technologies, each of which has their own strengths and weaknesses. This section presents the strategies used for implementing a VPN for the following scenario: There are at least two sites where each site is using IP internally. Both sites are connected to the Internet through a gateway that is running &os;. The gateway on each network has at least one public IP address. The internal addresses of the two networks can be either public or private IP addresses. However, the address space must not collide. For example, both networks cannot use 192.168.1.x. Tom Rhodes
trhodes@FreeBSD.org
 Written by Configuring IPsec on &os; To begin, security/ipsec-tools must be installed from the Ports Collection. This software provides a number of applications which support the configuration. The next requirement is to create two &man.gif.4; pseudo-devices which will be used to tunnel packets and allow both networks to communicate properly. As root, run the following commands, replacing internal and external with the real IP addresses of the internal and external interfaces of the two gateways: &prompt.root; ifconfig gif0 create &prompt.root; ifconfig gif0 internal1 internal2 &prompt.root; ifconfig gif0 tunnel external1 external2 In this example, the corporate LAN's external IP address is 172.16.5.4 and its internal IP address is 10.246.38.1. The home LAN's external IP address is 192.168.1.12 and its internal private IP address is 10.0.0.5. If this is confusing, review the following example output from &man.ifconfig.8;: Gateway 1: gif0: flags=8051 mtu 1280 tunnel inet 172.16.5.4 --> 192.168.1.12 inet6 fe80::2e0:81ff:fe02:5881%gif0 prefixlen 64 scopeid 0x6 inet 10.246.38.1 --> 10.0.0.5 netmask 0xffffff00 Gateway 2: gif0: flags=8051 mtu 1280 tunnel inet 192.168.1.12 --> 172.16.5.4 inet 10.0.0.5 --> 10.246.38.1 netmask 0xffffff00 inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4 Once complete, both internal IP addresses should be reachable using &man.ping.8;: priv-net# ping 10.0.0.5 PING 10.0.0.5 (10.0.0.5): 56 data bytes 64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms 64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms 64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=20.440 ms 64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=21.036 ms --- 10.0.0.5 ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max/stddev = 19.255/25.879/42.786/9.782 ms corp-net# ping 10.246.38.1 PING 10.246.38.1 (10.246.38.1): 56 data bytes 64 bytes from 10.246.38.1: icmp_seq=0 ttl=64 time=28.106 ms 64 bytes from 10.246.38.1: icmp_seq=1 ttl=64 time=42.917 ms 64 bytes from 10.246.38.1: icmp_seq=2 ttl=64 time=127.525 ms 64 bytes from 10.246.38.1: icmp_seq=3 ttl=64 time=119.896 ms 64 bytes from 10.246.38.1: icmp_seq=4 ttl=64 time=154.524 ms --- 10.246.38.1 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms As expected, both sides have the ability to send and receive ICMP packets from the privately configured addresses. Next, both gateways must be told how to route packets in order to correctly send traffic from either network. The following command will achieve this goal: &prompt.root; corp-net# route add 10.0.0.0 10.0.0.5 255.255.255.0 &prompt.root; corp-net# route add net 10.0.0.0: gateway 10.0.0.5 &prompt.root; priv-net# route add 10.246.38.0 10.246.38.1 255.255.255.0 &prompt.root; priv-net# route add host 10.246.38.0: gateway 10.246.38.1 At this point, internal machines should be reachable from each gateway as well as from machines behind the gateways. Again, use &man.ping.8; to confirm: corp-net# ping 10.0.0.8 PING 10.0.0.8 (10.0.0.8): 56 data bytes 64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms 64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms 64 bytes from 10.0.0.8: icmp_seq=2 ttl=63 time=198.022 ms 64 bytes from 10.0.0.8: icmp_seq=3 ttl=63 time=22.241 ms 64 bytes from 10.0.0.8: icmp_seq=4 ttl=63 time=174.705 ms --- 10.0.0.8 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 21.870/101.846/198.022/74.001 ms priv-net# ping 10.246.38.107 PING 10.246.38.1 (10.246.38.107): 56 data bytes 64 bytes from 10.246.38.107: icmp_seq=0 ttl=64 time=53.491 ms 64 bytes from 10.246.38.107: icmp_seq=1 ttl=64 time=23.395 ms 64 bytes from 10.246.38.107: icmp_seq=2 ttl=64 time=23.865 ms 64 bytes from 10.246.38.107: icmp_seq=3 ttl=64 time=21.145 ms 64 bytes from 10.246.38.107: icmp_seq=4 ttl=64 time=36.708 ms --- 10.246.38.107 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms Setting up the tunnels is the easy part. Configuring a secure link is a more in depth process. The following configuration uses pre-shared (PSK) RSA keys. Other than the IP addresses, the /usr/local/etc/racoon/racoon.conf on both gateways will be identical and look similar to: path pre_shared_key "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file log debug; #log verbosity setting: set to 'notify' when testing and debugging is complete padding # options are not to be changed { maximum_length 20; randomize off; strict_check off; exclusive_tail off; } timer # timing options. change as needed { counter 5; interval 20 sec; persend 1; # natt_keepalive 15 sec; phase1 30 sec; phase2 15 sec; } listen # address [port] that racoon will listening on { isakmp 172.16.5.4 [500]; isakmp_natt 172.16.5.4 [4500]; } remote 192.168.1.12 [500] { exchange_mode main,aggressive; doi ipsec_doi; situation identity_only; my_identifier address 172.16.5.4; peers_identifier address 192.168.1.12; lifetime time 8 hour; passive off; proposal_check obey; # nat_traversal off; generate_policy off; proposal { encryption_algorithm blowfish; hash_algorithm md5; authentication_method pre_shared_key; lifetime time 30 sec; dh_group 1; } } sainfo (address 10.246.38.0/24 any address 10.0.0.0/24 any) # address $network/$netmask $type address $network/$netmask $type ( $type being any or esp) { # $network must be the two internal networks you are joining. pfs_group 1; lifetime time 36000 sec; encryption_algorithm blowfish,3des,des; authentication_algorithm hmac_md5,hmac_sha1; compression_algorithm deflate; } For descriptions of each available option, refer to the manual page for racoon.conf. The Security Policy Database (SPD) needs to be configured so that &os; and racoon are able to encrypt and decrypt network traffic between the hosts. This can be achieved with a shell script, similar to the following, on the corporate gateway. This file will be used during system initialization and should be saved as /usr/local/etc/racoon/setkey.conf. flush; spdflush; # To the home network spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec esp/tunnel/172.16.5.4-192.168.1.12/use; spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec esp/tunnel/192.168.1.12-172.16.5.4/use; Once in place, racoon may be started on both gateways using the following command: &prompt.root; /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log The output should be similar to the following: corp-net# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf Foreground mode. 2006-01-30 01:35:47: INFO: begin Identity Protection mode. 2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon 2006-01-30 01:35:55: INFO: received Vendor ID: KAME/racoon 2006-01-30 01:36:04: INFO: ISAKMP-SA established 172.16.5.4[500]-192.168.1.12[500] spi:623b9b3bd2492452:7deab82d54ff704a 2006-01-30 01:36:05: INFO: initiate new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] 2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=28496098(0x1b2d0e2) 2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=47784998(0x2d92426) 2006-01-30 01:36:13: INFO: respond new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] 2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=124397467(0x76a279b) 2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=175852902(0xa7b4d66) To ensure the tunnel is working properly, switch to another console and use &man.tcpdump.1; to view network traffic using the following command. Replace em0 with the network interface card as required: &prompt.root; tcpdump -i em0 host 172.16.5.4 and dst 192.168.1.12 Data similar to the following should appear on the console. If not, there is an issue and debugging the returned data will be required. 01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa) 01:47:33.022442 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xb) 01:47:34.024218 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xc) At this point, both networks should be available and seem to be part of the same network. Most likely both networks are protected by a firewall. To allow traffic to flow between them, rules need to be added to pass packets. For the &man.ipfw.8; firewall, add the following lines to the firewall configuration file: ipfw add 00201 allow log esp from any to any ipfw add 00202 allow log ah from any to any ipfw add 00203 allow log ipencap from any to any ipfw add 00204 allow log udp from any 500 to any The rule numbers may need to be altered depending on the current host configuration. For users of &man.pf.4; or &man.ipf.8;, the following rules should do the trick: pass in quick proto esp from any to any pass in quick proto ah from any to any pass in quick proto ipencap from any to any pass in quick proto udp from any port = 500 to any port = 500 pass in quick on gif0 from any to any pass out quick proto esp from any to any pass out quick proto ah from any to any pass out quick proto ipencap from any to any pass out quick proto udp from any port = 500 to any port = 500 pass out quick on gif0 from any to any Finally, to allow the machine to start support for the VPN during system initialization, add the following lines to /etc/rc.conf: ipsec_enable="YES" ipsec_program="/usr/local/sbin/setkey" ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot racoon_enable="yes" Chern Lee Contributed by OpenSSH OpenSSH security OpenSSH OpenSSH is a set of network connectivity tools used to access remote machines securely. Additionally, TCP/IP connections can be tunneled/forwarded securely through SSH connections. OpenSSH encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks. OpenSSH is maintained by the OpenBSD project and is installed by default in &os;. It is compatible with both SSH version 1 and 2 protocols. Advantages of Using <application>OpenSSH</application> When data is sent over the network in an unencrypted form, network sniffers anywhere in between the client and server can steal user/password information or data transferred during the session. OpenSSH offers a variety of authentication and encryption methods to prevent this from happening. Enabling the SSH Server OpenSSH enabling To see if &man.sshd.8; is enabled, check /etc/rc.conf for this line: sshd_enable="YES" This will start &man.sshd.8;, the daemon program for OpenSSH, the next time the system initializes. Alternatively, it is possible to use &man.service.8; to start OpenSSH now: &prompt.root; service sshd start The SSH Client OpenSSH client To use &man.ssh.1; to connect to a system running &man.sshd.8;, specify the username and host to log into: &prompt.root; ssh user@example.com Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)? yes Host 'example.com' added to the list of known hosts. user@example.com's password: ******* SSH utilizes a key fingerprint system to verify the authenticity of the server when the client connects. The user is prompted to type yes when connecting for the first time. Future attempts to login are verified against the saved fingerprint key and the &man.ssh.1; client will display an alert if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in ~/.ssh/known_hosts. By default, recent versions of &man.sshd.8; only accept SSH v2 connections. The client will use version 2 if possible and will fall back to version 1. The client can also be forced to use one or the other by passing it the or for version 1 or version 2, respectively. The version 1 compatibility is maintained in the client for backwards compatibility with older versions. Secure Copy OpenSSH secure copy &man.scp.1; Use &man.scp.1; to copy a file to or from a remote machine in a secure fashion. &prompt.root; scp user@example.com:/COPYRIGHT COPYRIGHT user@example.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 &man.scp.1; here. The arguments passed to &man.scp.1; are similar to &man.cp.1;, with the file or files to copy in the first argument, and the destination in the second. Since the file is fetched over the network, through an SSH, connection, one or more of the file arguments takes the form . Configuration OpenSSH configuration The system-wide configuration files for both the OpenSSH daemon and client reside in /etc/ssh. ssh_config configures the client settings, while sshd_config configures the daemon. Each file has its own manual page which describes the available configuration options. &man.ssh-keygen.1; Instead of using passwords, &man.ssh-keygen.1; can be used to generate DSA or RSA keys to authenticate a user: &prompt.user; ssh-keygen -t dsa Generating public/private dsa key pair. Enter file in which to save the key (/home/user/.ssh/id_dsa): Created directory '/home/user/.ssh'. Enter passphrase (empty for no passphrase): Enter same passphrase again: Your identification has been saved in /home/user/.ssh/id_dsa. Your public key has been saved in /home/user/.ssh/id_dsa.pub. The key fingerprint is: bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com &man.ssh-keygen.1; will create a public and private key pair for use in authentication. The private key is stored in ~/.ssh/id_dsa or ~/.ssh/id_rsa, whereas the public key is stored in ~/.ssh/id_dsa.pub or ~/.ssh/id_rsa.pub, respectively for the DSA and RSA key types. The public key must be placed in ~/.ssh/authorized_keys on the remote machine for both RSA or DSA keys in order for the setup to work. This setup allows connections to the remote machine based upon SSH keys instead of passwords. Many users believe that keys are secure by design and will use a key without a passphrase. This is dangerous behavior and the method an administrator may use to verify keys have a passphrase is to view the key manually. If the private key file contains the word ENCRYPTED the key owner is using a passphrase. While it may still be a weak passphrase, at least if the system is compromised, access to other sites will still require some level of password guessing. In addition, to better secure end users, the from may be placed in the public key file. For example, adding from="192.168.10.5 in the front of ssh-rsa or rsa-dsa prefix will only allow that specific user to login from that host IP. If a passphrase is used in &man.ssh-keygen.1;, the user will be prompted for the passphrase each time in order to use the private key. &man.ssh-agent.1; can alleviate the strain of repeatedly entering long passphrases, and is explored in . The various options and files can be different according to the OpenSSH version. To avoid problems, consult &man.ssh-keygen.1;. Using SSH Agent to Cache Keys To load SSH keys into memory for use, without needing to type the passphrase each time, use &man.ssh-agent.1; and &man.ssh-add.1;. Authentication is handled by &man.ssh-agent.1;, using the private key(s) that are loaded into it. Then, &man.ssh-agent.1; should be used to launch another application. At the most basic level, it could spawn a shell or a window manager. To use &man.ssh-agent.1; in a shell, start it with a shell as an argument. Next, add the identity by running &man.ssh-add.1; and providing it the passphrase for the private key. Once these steps have been completed, the user will be able to &man.ssh.1; to any host that has the corresponding public key installed. For example: &prompt.user; ssh-agent csh &prompt.user; ssh-add Enter passphrase for /home/user/.ssh/id_dsa: Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) &prompt.user; To use &man.ssh-agent.1; in &xorg;, a call to &man.ssh-agent.1; needs to be placed in ~/.xinitrc. This provides the &man.ssh-agent.1; services to all programs launched in &xorg;. An example ~/.xinitrc might look like this: exec ssh-agent startxfce4 This launches &man.ssh-agent.1;, which in turn launches XFCE, every time &xorg; starts. Once &xorg; has been restarted so that the changes can take effect, run &man.ssh-add.1; to load all of the SSH keys. <acronym>SSH</acronym> Tunneling OpenSSH 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 &man.telnet.1;: &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com &prompt.user; This example uses the following options: Forces &man.ssh.1; to use version 2 to connect to the server. Indicates no command, or tunnel only. If omitted, &man.ssh.1; initiates a normal session. Forces &man.ssh.1; to run in the background. Indicates a local tunnel in localport:remotehost:remoteport format. The login name to use on the specified remote SSH server. An SSH tunnel works by creating a listen socket on localhost on the specified port. It then forwards any connections received on the local host/port via the SSH connection to the specified remote host and port. In the example, port 5023 on localhost is forwarded to port 23 on localhost of the remote machine. Since 23 is used by &man.telnet.1;, this creates an encrypted &man.telnet.1; session through an SSH tunnel. This can be used to wrap any number of insecure TCP protocols such as SMTP, POP3, and FTP. Using &man.ssh.1; to Create a Secure Tunnel for SMTP &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com user@mailserver.example.com's password: ***** &prompt.user; telnet localhost 5025 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 220 mailserver.example.com ESMTP This can be used in conjunction with &man.ssh-keygen.1; and additional user accounts to create a more seamless SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate user. Practical <acronym>SSH</acronym> Tunneling Examples Secure Access of a POP3 Server In this example, there is an SSH server that accepts connections from the outside. On the same network resides a mail server running a POP3 server. To check email in a secure manner, create an SSH connection to the SSH server, and tunnel through to the mail server. &prompt.user; ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com user@ssh-server.example.com's password: ****** Once the tunnel is up and running, point the email client to send POP3 requests to localhost on port 2110. This connection will be forwarded securely across the tunnel to mail.example.com. Bypassing a Draconian Firewall Some network administrators impose firewall rules which filter both incoming and outgoing connections. For example, it might limit access from remote machines to ports 22 and 80 to only allow &man.ssh.1; and web surfing. This prevents access to any other service which uses a port other than 22 or 80. The solution is to create an SSH connection to a machine outside of the network's firewall and use it to tunnel to the desired service. &prompt.user; ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org user@unfirewalled-system.example.org's password: ******* In this example, a streaming Ogg Vorbis client can now be pointed to localhost port 8888, which will be forwarded over to music.example.com on port 8000, successfully bypassing the firewall. The <varname>AllowUsers</varname> Option It is often a good idea to limit which users can log in and from where using AllowUsers. For example, to only allow root to log in from 192.168.1.32, add this line to /etc/ssh/sshd_config: AllowUsers root@192.168.1.32 To allow admin to log in from anywhere, list that username by itself: AllowUsers admin Multiple users should be listed on the same line, like so: AllowUsers root@192.168.1.32 admin It is important to list each user that needs to log into this machine; otherwise, they will be locked out. After making changes to /etc/ssh/sshd_config, tell &man.sshd.8; to reload its configuration file by running: &prompt.root; service sshd reload Further Reading The OpenSSH website. &man.ssh.1;, &man.scp.1;, &man.ssh-keygen.1;, &man.ssh-agent.1;, &man.ssh-add.1;, and &man.ssh.config.5; for client options. &man.sshd.8;, &man.sftp-server.8;, and &man.sshd.config.5; for server options. Tom Rhodes Contributed by Filesystem Access Control Lists (<acronym>ACL</acronym>)s ACL Filesystem Access Control Lists (ACLs) extend the standard &unix; permission model in a &posix;.1e compatible way. This permits an administrator to make use of and take advantage of a more sophisticated security model. The &os; GENERIC kernel provides ACL support for UFS file systems. Users who prefer to compile a custom kernel must include the following option in their custom kernel configuration file: options UFS_ACL If this option is not compiled in, a warning message will be displayed when attempting to mount a filesystem supporting ACLs. ACLs rely on extended attributes being enabled on the filesystem. Extended attributes are natively supported in UFS2. A higher level of administrative overhead is required to configure extended attributes on UFS1 than on UFS2. The performance of extended attributes on UFS2 is also substantially higher. As a result, UFS2 is recommended for use with ACLs. ACLs are enabled by the mount-time administrative flag, , which may be added to /etc/fstab. The mount-time flag can also be automatically set in a persistent manner using &man.tunefs.8; to modify a superblock ACLs flag in the filesystem header. In general, it is preferred to use the superblock flag for several reasons: The mount-time ACLs flag cannot be changed by a remount using . It requires a complete &man.umount.8; and fresh &man.mount.8;. This means that ACLs cannot be enabled on the root filesystem after boot. It also means that the disposition of a filesystem cannot be changed once it is in use. Setting the superblock flag will cause the filesystem to always be mounted with ACLs enabled, even if there is not an fstab entry or if the devices re-order. This prevents accidental mounting of the filesystem without ACLs enabled, which can result in the security problem of ACLs being improperly enforced. It is desirable to discourage accidental mounting without ACLs enabled, because nasty things can happen if ACLs are enabled, then disabled, then re-enabled without flushing the extended attributes. In general, once ACLs are enabled on a filesystem, they should not be disabled, as the resulting file protections may not be compatible with those intended by the users of the system, and re-enabling ACLs may re-attach the previous ACLs to files that have since had their permissions changed, resulting in unpredictable behavior. Filesystems with ACLs enabled will show a + (plus) sign in their permission settings when viewed. For example: drwx------ 2 robert robert 512 Dec 27 11:54 private drwxrwx---+ 2 robert robert 512 Dec 23 10:57 directory1 drwxrwx---+ 2 robert robert 512 Dec 22 10:20 directory2 drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3 drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html In this example, directory1, directory2, and directory3 are all taking advantage of ACLs, whereas public_html is not. Making Use of <acronym>ACL</acronym>s Filesystem ACLs can be viewed using &man.getfacl.1;. For instance, to view the ACL settings on test: &prompt.user; getfacl test #file:test #owner:1001 #group:1001 user::rw- group::r-- other::r-- To change the ACL settings on this file, use &man.setfacl.1;: &prompt.user; setfacl -k test To remove all of the currently defined ACLs from a file or filesystem, one can use . However, the preferred method is to use as it leaves the basic fields required for ACLs to work. &prompt.user; setfacl -m u:trhodes:rwx,group:web:r--,o::--- test In this example, is used to modify the default ACL entries. Since there were no pre-defined entries, as they were removed by the previous command, it restores the default options and assign the options listed. If a user or group is added which does not exist on the system, an Invalid argument error will be displayed. Tom Rhodes Contributed by Monitoring Third Party Security Issues portaudit In recent years, the security world has made many improvements to how vulnerability assessment is handled. The threat of system intrusion increases as third party utilities are installed and configured for virtually any operating system available today. Vulnerability assessment is a key factor in security. While &os; releases advisories for the base system, doing so for every third party utility is beyond the &os; Project's capability. There is a way to mitigate third party vulnerabilities and warn administrators of known security issues. A &os; add on utility known as portaudit exists solely for this purpose. The ports-mgmt/portaudit port polls a database, which is updated and maintained by the &os; Security Team and ports developers, for known security issues. To install portaudit from the Ports Collection: &prompt.root; cd /usr/ports/ports-mgmt/portaudit && make install clean During the installation, the configuration files for &man.periodic.8; will be updated, permitting portaudit output in the daily security runs. Ensure that the daily security run emails, which are sent to root's email account, are being read. No other configuration is required. After installation, an administrator can update the database and view known vulnerabilities in installed packages by invoking the following command: &prompt.root; portaudit -Fda The database is automatically updated during the &man.periodic.8; run. The above command is optional and can be used to manually update the database now. To audit the third party utilities installed as part of the Ports Collection at anytime, an administrator can run the following command: &prompt.root; portaudit -a portaudit will display messages for any installed vulnerable packages: Affected package: cups-base-1.1.22.0_1 Type of problem: cups-base -- HPGL buffer overflow vulnerability. Reference: <http://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html> 1 problem(s) in your installed packages found. You are advised to update or deinstall the affected package(s) immediately. By pointing a web browser to the displayed URL, an administrator may obtain more information about the vulnerability. This will include the versions affected, by &os; port version, along with other web sites which may contain security advisories. portaudit is a powerful utility and is extremely useful when coupled with the portmaster port. Tom Rhodes Contributed by &os; Security Advisories &os; Security Advisories Like many production quality operating systems, &os; publishes Security Advisories. These advisories are usually mailed to the security lists and noted in the Errata only after the appropriate releases have been patched. This section explains what an advisory is, how to understand it, and what measures to take in order to patch a system. What Does an Advisory Look Like? &os; security advisories use the format seen in this example: ============================================================================= FreeBSD-SA-XX:XX.UTIL Security Advisory The FreeBSD Project Topic: denial of service due to some problem Category: core Module: sys Announced: 2003-09-23 Credits: Person Affects: All releases of &os; &os; 4-STABLE prior to the correction date Corrected: 2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE) 2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6) 2003-09-23 20:07:06 UTC (RELENG_5_0, 5.0-RELEASE-p15) 2003-09-23 16:44:58 UTC (RELENG_4_8, 4.8-RELEASE-p8) 2003-09-23 16:47:34 UTC (RELENG_4_7, 4.7-RELEASE-p18) 2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21) 2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33) 2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43) 2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39) CVE Name: CVE-XXXX-XXXX For general information regarding FreeBSD Security Advisories, including descriptions of the fields above, security branches, and the following sections, please visit http://www.FreeBSD.org/security/. I. Background II. Problem Description III. Impact IV. Workaround V. Solution VI. Correction details VII. References The Topic field specifies the problem. It provides an introduction to the security advisory and notes the utility affected by the vulnerability. The Category refers to the affected part of the system which may be one of core, contrib, or ports. The core category means that the vulnerability affects a core component of the &os; operating system. The contrib category means that the vulnerability affects software contributed to the &os; Project, such as Sendmail. The ports category indicates that the vulnerability affects add on software available through the Ports Collection. The Module field refers to the component location. In this example, the sys module is affected; therefore, this vulnerability affects a component used within the kernel. The Announced field reflects the date the security advisory was published, or announced to the world. This means that the security team has verified that the problem exists and that a patch has been committed to the &os; source code repository. The Credits field gives credit to the individual or organization who noticed the vulnerability and reported it. The Affects field explains which releases of &os; are affected by this vulnerability. For the kernel, a quick look over the output from &man.ident.1; on the affected files will help in determining the revision. For ports, the version number is listed after the port name in /var/db/pkg. If the system does not sync with the &os; Subversion repository and is not rebuilt daily, chances are that it is affected. The Corrected field indicates the date, time, time offset, and release that was corrected. Reserved for the identification information used to look up vulnerabilities in the Common Vulnerabilities and Exposures database. The Background field gives information about the affected utility. Most of the time this is why the utility exists in &os;, what it is used for, and a bit of information on how the utility came to be. The Problem Description field explains the security hole in depth. This can include information on flawed code, or even how the utility could be maliciously used to open a security hole. The Impact field describes what type of impact the problem could have on a system. For example, this could be anything from a denial of service attack, to extra privileges available to users, or even giving the attacker superuser access. The Workaround field offers a workaround to system administrators who cannot upgrade the system due to time constraints, network availability, or other reasons. Security should not be taken lightly, and an affected system should either be patched or the workaround implemented. The Solution field offers instructions for patching the affected system. This is a step by step tested and verified method for getting a system patched and working securely. The Correction Details field displays the Subversion branch or release name with the periods changed to underscore characters. It also shows the revision number of the affected files within each branch. The References field usually offers sources of other information. This can include web URLs, books, mailing lists, and newsgroups. Tom Rhodes Contributed by Process Accounting Process Accounting Process accounting is a security method in which an administrator may keep track of system resources used and their allocation among users, provide for system monitoring, and minimally track a user's commands. This indeed has both positive and negative points. One of the positives is that an intrusion may be narrowed down to the point of entry. A negative is the amount of logs generated by process accounting, and the disk space they may require. This section walks an administrator through the basics of process accounting. Enabling and Utilizing Process Accounting Before using process accounting, it must be enabled using the following commands: &prompt.root; touch /var/account/acct &prompt.root; accton /var/account/acct &prompt.root; echo 'accounting_enable="YES"' >> /etc/rc.conf Once enabled, accounting will begin to track information such as CPU statistics and executed commands. All accounting logs are in a non-human readable format which can be viewed using &man.sa.8;. If issued without any options, &man.sa.8; prints information relating to the number of per-user calls, the total elapsed time in minutes, total CPU and user time in minutes, and the average number of I/O operations. To view information about commands being issued, use &man.lastcomm.1;. This command displays the commands issued by users on specific &man.ttys.5;. For example, this command prints out all known usage of &man.ls.1; by trhodes on the ttyp1 terminal: &prompt.root; lastcomm ls trhodes ttyp1 Many other useful options exist and are explained in the &man.lastcomm.1;, &man.acct.5;, and &man.sa.8;. Tom Rhodes Contributed by Resource Limits Resource limits For years, &os; has used a resource limits database controlled through a flat file, /etc/login.conf. While it has been discussed previously and is still supported, it is not the most optimal method of controlling resources. The flat file requires users to be divided into various group labels known as classes, which require changes not only to this flat file but also the password database. Potentially a single, more constrained user would require an additional label to be added, the resource database rebuilt using cap_mkdb, and edits made to /etc/master.passwd. In addition, the password database must be rebuilt using pwd_mkdb. This multi-step process could be very time consuming depending on how many users must be singled out. A new command in &os;, &man.rctl.8;, allows for a more fine grained method of controlling resources limits for users. This command will support much more than users, it will also set resource constraints on processes, jails, and the original login class. These advanced features provide administrators and users with methods to control resources through the command line and set rules on system initialization using a configuration file. To enable this feature, add these lines to GENERIC, or the custom kernel configuration file, and rebuild.: options RACCT options RCTL The entire system will need rebuilt. See , which will provide instructions for the process. Once this is complete, the rctl may be used to set rules for the system. Rule syntax is simple, controlled through the use of a subject, a subject-id, resource, and action. Take the following example rule: user:trhodes:maxproc:deny=10/user This rule shows a basic premise of a rule, here the subject is user and the subject-id is trhodes. The maxproc is, of course, max number of processes, which is considered the resource. The action here is set to deny, which blocks any new processes from being created. In the previous example, the user, trhodes will be constrained to 10 (ten) processes and no greater. Other actions are available and could be log to the console, pass a notification to &man.devd.8;, or send a sigterm to the process. Some care must be taken while adding rules. The one above will unfortunately block my user from doing the most simple tasks after I have logged in and executed a screen session. When a resource limit has been hit, an error will be printed, as in this example: &prompt.user; man test /usr/bin/man: Cannot fork: Resource temporarily unavailable eval: Cannot fork: Resource temporarily unavailable For another example, &man.rctl.8; can be used to prevent a jail from exceeding a memory limit. This rule could be written as: &prompt.root; rctl -a jail:httpd:memoryuse:deny=2G/jail Rules may also persist across reboots if they have been added to /etc/rctl.conf. The format is a rule, without the preceding command. For example, the previous rule could be added like the following: # Block jail from using more than 2G memory: jail:httpd:memoryuse:deny=2G/jail To remove a rule, just ask rctl to remove it from the list: &prompt.root; rctl -r user:trhodes:maxproc:deny=10/user The manual page shows a method for removing all rules; however, if removing all rules for a single user is required, this command may be issued: &prompt.root; rctl -r user:trhodes Many other resources exist which can be used to exert additional control over various subjects. See &man.rctl.8; to learn about them. diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml index 86436fe80a..fd92268b25 100644 --- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml @@ -1,2870 +1,2863 @@ Serial Communications Synopsis serial communications &unix; has always had support for serial communications as the very first &unix; machines relied on serial lines for user input and output. Things have changed a lot from the days when the average terminal consisted of a 10-character-per-second serial printer and a keyboard. This chapter covers some of the ways serial communications can be used on &os;. After reading this chapter, you will know: How to connect terminals to a &os; system. How to use a modem to dial out to remote hosts. How to allow remote users to login to a &os; system with a modem. How to boot a &os; system from a serial console. Before reading this chapter, you should: Know how to configure and install a custom kernel. Understand &os; permissions and processes. Have access to the technical manual for the serial hardware to be used with &os;. Introduction Terminology - bits-per-second bps - Bits per Second (bps) is the rate + Bits per Secondbits-per-second (bps) is the rate at which data is transmitted. DTE - DTE - - An example of a Data Terminal Equipment + An example of a Data Terminal EquipmentDTE (DTE) is a computer. DCE - DCE - - An example of a Data Communications Equipment + An example of a Data Communications EquipmentDCE (DTE) is a modem. RS-232 - RS-232C cables - The original standard for hardware serial communications. It is now usually referred to as - TIA-232 + TIA-232RS-232C cables. When talking about communications data rates, this section does not use the term baud. Baud refers to the number of electrical state transitions that may be made in a period of time, while bps is the correct term to use. Cables and Ports To connect a modem or serial terminal to a &os; system, a serial port on the computer and the proper cable to connect to the serial device are needed. Users who are already familiar with serial hardware and cabling can safely skip this section. Cables There are several different kinds of serial cables. The two most common types are null-modem cables and standard RS-232 cables. The documentation for the hardware should describe the type of cable required. Null-modem Cables null-modem cable A null-modem cable passes some signals, such as Signal Ground, straight through, but switches other signals. For example, the Transmitted Data pin on one end goes to the Received Data pin on the other end. A null-modem cable can be constructed for use with terminals. The following table shows the RS-232C signal names and the pin numbers on a DB-25 connector. While the standard calls for a straight-through pin 1 to pin 1 Protective Ground line, it is often omitted. Some terminals work using only pins 2, 3, and 7, while others require different configurations than the examples shown below. DB-25 to DB-25 Null-Modem Cable Signal Pin # Pin # Signal SG 7 connects to 7 SG TD 2 connects to 3 RD RD 3 connects to 2 TD RTS 4 connects to 5 CTS CTS 5 connects to 4 RTS DTR 20 connects to 6 DSR DTR 20 connects to 8 DCD DSR 6 connects to 20 DTR DCD 8 connects to 20 DTR
The next two tables show two other common schemes. DB-9 to DB-9 Null-Modem Cable Signal Pin # Pin # Signal RD 2 connects to 3 TD TD 3 connects to 2 RD DTR 4 connects to 6 DSR DTR 4 connects to 1 DCD SG 5 connects to 5 SG DSR 6 connects to 4 DTR DCD 1 connects to 4 DTR RTS 7 connects to 8 CTS CTS 8 connects to 7 RTS
DB-9 to DB-25 Null-Modem Cable Signal Pin # Pin # Signal RD 2 connects to 2 TD TD 3 connects to 3 RD DTR 4 connects to 6 DSR DTR 4 connects to 8 DCD SG 5 connects to 7 SG DSR 6 connects to 20 DTR DCD 1 connects to 20 DTR RTS 7 connects to 5 CTS CTS 8 connects to 4 RTS
When one pin at one end connects to a pair of pins at the other end, it is usually implemented with one short wire between the pair of pins in their connector and a long wire to the other single pin. The above designs seem to be the most popular. In another variation, SG connects to SG, TD connects to RD, RTS and CTS connect to DCD, DTR connects to DSR, and vice-versa. Standard RS-232C Cables RS-232C cables A standard serial cable passes all of the RS-232C signals straight through. The Transmitted Data pin on one end of the cable goes to the Transmitted Data pin on the other end. This is the type of cable used to connect a modem to the &os; system, and is also appropriate for some terminals. Ports Serial ports are the devices through which data is transferred between the &os; host computer and the terminal. This section describes the kinds of ports that exist and how they are addressed in &os;. Kinds of Ports Several kinds of serial ports exist. Before purchasing or constructing a cable, make sure it will fit the ports on the terminal and on the &os; system. Most terminals have DB-25 ports. Personal computers may have DB-25 or DB-9 ports. A multiport serial card may have RJ-12 or RJ-45 ports. See the documentation that accompanied the hardware for specifications on the kind of port or visually verify the type of port. Port Names In &os;, each serial port is accessed through an entry in /dev. There are two different kinds of entries: Call-in ports are named /dev/ttyuN where N is the port number, starting from zero. Generally, the call-in port is used for terminals. Call-in ports require that the serial line assert the Data Carrier Detect (DCD) signal to work correctly. Call-out ports are named /dev/cuauN. Call-out ports are usually not used for terminals, but are used for modems. The call-out port can be used if the serial cable or the terminal does not support the carrier detect signal. If a terminal is connected to the first serial port(COM1), use /dev/ttyu0 to refer to the terminal. If the terminal is on the second serial port (COM2), use /dev/ttyu1, and so forth. Kernel Configuration &os; supports four serial ports by default. In the &ms-dos; world, these are known as COM1, COM2, COM3, and COM4. &os; currently supports dumb multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion Technologies. However, the default kernel only looks for the standard COM ports. To see if the kernel recognizes the serial ports, watch for messages while the kernel is booting, or use /sbin/dmesg to replay the kernel's boot messages. Look for messages that start with the characters uart: &prompt.root; /sbin/dmesg | grep 'uart' If the kernel does not recognize all of the serial ports, configure /boot/device.hints. When editing this file, one can comment out or completely remove lines for devices that do not exist on the system. port IO_COM1 is a substitution for port 0x3f8, IO_COM2 is 0x2f8, IO_COM3 is 0x3e8, and IO_COM4 is 0x2e8. These are fairly common port addresses for their respective serial ports and interrupts 4, 3, 5, and 9 are fairly common interrupt request lines. Regular serial ports cannot share interrupts on ISA-bus PCs. Multiport boards have on-board electronics that allow all the 16550A's on the board to share one or two interrupt request lines. Device Special Files Most devices in the kernel are accessed through device special files which are located in /dev. The sio devices are accessed through the /dev/ttyuN (dial-in) and /dev/cuauN (call-out) devices. &os; also provides initialization devices (/dev/ttyuN.init and /dev/cuauN.init) and locking devices (/dev/ttyuN.lock and /dev/cuauN.lock). The initialization devices are used to initialize communications port parameters each time a port is opened, such as crtscts for modems which use RTS/CTS signaling for flow control. The locking devices are used to lock flags on ports to prevent users or programs changing certain parameters. Refer to &man.termios.4;, &man.sio.4;, and &man.stty.1; for information on terminal settings, locking and initializing devices, and setting terminal options, respectively. Serial Port Configuration ttyu cuau The ttyuN (or cuauN) is the regular device to open for applications. When a process opens the device, it will have a default set of terminal I/O settings. These settings can be viewed with the command: &prompt.root; stty -a -f /dev/ttyu1 When the settings are changed for a device, the settings are in effect until the device is closed. When the device is reopened, it goes back to the default set. To permanently change the default set, open and adjust the settings of the initial state device. For example, to turn on mode, 8 bit communication, and flow control for ttyu5, type: &prompt.root; stty -f /dev/ttyu5.init clocal cs8 ixon ixoff rc files rc.serial System-wide initialization of serial devices is controlled by /etc/rc.d/serial. This file affects the default settings of serial devices. To prevent certain settings from being changed by an application, make adjustments to the lock state device. For example, to lock the speed of ttyu5 to 57600 bps, type: &prompt.root; stty -f /dev/ttyu5.lock 57600 Now, an application that opens ttyu5 and tries to change the speed of the port will be stuck with 57600 bps. The initial state and lock state devices should only be writable by root. Sean Kelly Contributed by Terminals terminals Terminals provide a convenient and low-cost way to access a &os; system when not at the computer's console or on a connected network. This section describes how to use terminals with &os;. Uses and Types of Terminals The original &unix; systems did not have consoles. Instead, users logged in and ran programs through terminals that were connected to the computer's serial ports. The ability to establish a login session on a serial port still exists in nearly every &unix;-like operating system today, including &os;. By using a terminal attached to an unused serial port, a user can log in and run any text program that can normally be run on the console or in an xterm window. Many terminals can be attached to a &os; system. An older spare computer can be used as a terminal wired into a more powerful computer running &os;. This can turn what might otherwise be a single-user computer into a powerful multiple user system. This section describes three kinds of terminals supported by &os;: dumb terminals, computers acting as terminals, and X terminals. Dumb Terminals Dumb terminals are specialized hardware that connect to computers over serial lines. They are called dumb because they have only enough computational power to display, send, and receive text. No programs can be run on these devices. Dumb terminals connect to a computer that has all the power to run text editors, compilers, email, games, and so forth. There are hundreds of kinds of dumb terminals made by many manufacturers, and just about any kind will work with &os;. Some high-end terminals can even display graphics, but only certain software packages can take advantage of these advanced features. Dumb terminals are popular in work environments where workers do not need access to graphical applications. Computers Acting as Terminals If a dumb terminal has just enough ability to display, send, and receive text, any spare computer can be a dumb terminal. All that is needed is the proper cable and some terminal emulation software to run on the computer. This configuration can be useful. For example, if one user is busy working at the &os; system's console, another user can do some text-only work at the same time from a less powerful personal computer hooked up as a terminal to the &os; system. There are at least two utilities in the base-system of &os; that can be used to work through a serial connection: &man.cu.1; and &man.tip.1;. To connect from a client system that runs &os; to the serial connection of another system, use: &prompt.root; cu -l serial-port-device Where serial-port-device is the name of a special device file denoting a serial port on the system. These device files are called /dev/cuauN. The N-part of a device name is the serial port number. Note that device numbers in &os; start from zero and not one. This means that COM1 is /dev/cuau0 in &os;. Some people prefer to use other programs available through the Ports Collection, such as comms/minicom. X Terminals X terminals are the most sophisticated kind of terminal available. Instead of connecting to a serial port, they usually connect to a network like Ethernet. Instead of being relegated to text-only applications, they can display any X application. This chapter does not cover the setup, configuration, or use of X terminals. Configuration This section describes how to configure a &os; system to enable a login session on a terminal. It assumes that the kernel is configured to support the serial port to which the terminal is connected and that the terminal is connected. The init process is responsible for all process control and initialization at system startup. One of the tasks performed by init is to read /etc/ttys and start a getty process on the available terminals. The getty process is responsible for reading a login name and starting the login program. To configure terminals for a &os; system, the following steps should be taken as root: Add a line to /etc/ttys for the entry in /dev for the serial port if it is not already there. Specify that /usr/libexec/getty be run on the port, and specify the appropriate getty type from /etc/gettytab. Specify the default terminal type. Set the port to on. Specify whether the port should be secure. Force init to reread /etc/ttys. As an optional step, create a custom getty type for use in step 2 by making an entry in /etc/gettytab. For more information, refer to &man.gettytab.5; and &man.getty.8;. Adding an Entry to <filename>/etc/ttys</filename> /etc/ttys lists all of the ports on the &os; system which allow logins. For example, the first virtual console, ttyv0, has an entry in this file, allowing logins on the console. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, list the serial port's /dev entry without the /dev part. For example, /dev/ttyv0 would be listed as ttyv0. A default &os; install includes an /etc/ttys with support for the first four serial ports: ttyu0 through ttyu3. When attaching a terminal to one of those ports, this file does not need to be edited. Adding Terminal Entries to <filename>/etc/ttys</filename> This example configures two terminals: a Wyse-50 and an old 286 IBM PC running Procomm terminal software emulating a VT-100 terminal. The Wyse is connected to the second serial port and the 286 to the sixth serial port on a multiport serial card. The corresponding entries in /etc/ttys would look like this: ttyu1 "/usr/libexec/getty std.38400" wy50 on insecure ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure The first field normally specifies the name of the terminal special file as it is found in /dev. The second field is the command to execute for this line, which is usually &man.getty.8;. getty initializes and opens the line, sets the speed, prompts for a user name, and then executes &man.login.1;. The getty program accepts one (optional) parameter on its command line, the getty type. A getty type configures characteristics on the terminal line, like bps rate and parity. getty reads these characteristics from /etc/gettytab. /etc/gettytab contains many entries for terminal lines, both old and new. In almost all cases, the entries that start with the text std will work for hardwired terminals as these entries ignore parity. There is a std entry for each bps rate from 110 to 115200. &man.gettytab.5; provides more information. When setting the getty type in /etc/ttys, make sure that the communications settings on the terminal match. For this example, the Wyse-50 uses no parity and connects at 38400 bps. The 286 PC uses no parity and connects at 19200 bps. The third field is the type of terminal usually connected to that terminal line. For dial-up ports, unknown or dialup is typically used since users may dial up with practically any type of terminal or software. Since the terminal type does not change for hardwired terminals, a real terminal type from &man.termcap.5; can be used in this field. For this example, the Wyse-50 uses the real terminal type while the 286 PC running Procomm will be set to emulate at VT-100. The fourth field specifies if the port should be enabled. If set to on, the init process will start the program in the second field, getty. If this field is set to off, there will be no getty, and hence no logins on the port. The final field is used to specify whether the port is secure. Marking a port as secure means that it is trusted enough to allow root, or any account with a UID of 0, to login from that port. Insecure ports do not allow root logins. On an insecure port, users must login from unprivileged accounts and then use &man.su.1; or a similar mechanism to gain superuser privileges. It is highly recommended to use insecure, even for terminals that are behind locked doors. It is quite easy to login and use su when superuser privileges are needed. Force <command>init</command> to Reread <filename>/etc/ttys</filename> After making any changes to /etc/ttys, send a SIGHUP (hangup) signal to the init process to force it to re-read its configuration file: &prompt.root; kill -HUP 1 init is always the first process run on a system, therefore it will always have a process ID of 1. If everything is set up correctly, all cables are in place, and the terminals are powered up, then a getty process should be running on each terminal and login prompts should be available on each terminal. Troubleshooting the Connection Even with the most meticulous attention to detail, something could still go wrong while setting up a terminal. Here is a list of common symptoms and some suggested fixes. No Login Prompt Appears Make sure the terminal is plugged in and powered up. If it is a personal computer acting as a terminal, make sure it is running terminal emulation software on the correct serial port. Make sure the cable is connected firmly to both the terminal and the &os; computer. Make sure it is the right kind of cable. Make sure the terminal and &os; agree on the bps rate and parity settings. For a video display terminal, make sure the contrast and brightness controls are turned up. If it is a printing terminal, make sure paper and ink are in good supply. Make sure that a getty process is running and serving the terminal. For example, to get a list of running getty processes with ps, type: &prompt.root; ps -axww|grep getty There should be an entry for the terminal. For example, the following display shows that a getty is running on the second serial port, ttyu1, and is using the std.38400 entry in /etc/gettytab: 22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyu1 If no getty process is running, make sure the port is enabled in /etc/ttys. Remember to run kill -HUP 1 after modifying /etc/ttys. If the getty process is running but the terminal still does not display a login prompt, or if it displays a prompt but will not accept typed input, the terminal or cable may not support hardware handshaking. Try changing the entry in /etc/ttys from std.38400 to 3wire.38400, then run kill -HUP 1 after modifying /etc/ttys. The 3wire entry is similar to std, but ignores hardware handshaking. The baud rate may need to be reduced or software flow control enabled when using 3wire to prevent buffer overflows. If Garbage Appears Instead of a Login Prompt Make sure the terminal and &os; agree on the bps rate and parity settings. Check the getty processes to make sure the correct getty type is in use. If not, edit /etc/ttys and run kill -HUP 1. Characters Appear Doubled and the Password Appears When Typed Switch the terminal, or the terminal emulation software, from half duplex or local echo to full duplex. Guy Helmer Contributed by Sean Kelly Additions by Dial-in Service dial-in service Configuring a &os; system for dial-in service is similar to connecting terminals except that modems are used instead of terminal devices. External Versus Internal Modems External modems are more convenient for dial-up because they often can be semi-permanently configured via parameters stored in non-volatile RAM and they usually provide lighted indicators that display the state of important RS-232 signals, indicating whether the modem is operating properly. Internal modems usually lack non-volatile RAM, so their configuration may be limited to setting DIP switches. If the internal modem has any signal indicator lights, they are difficult to view when the system's cover is in place. Modems and Cables modem When using an external modem, a proper cable is needed. A standard RS-232C serial cable should suffice as long as all of the normal signals are wired: Signal Names Acronyms Names RD Received Data TD Transmitted Data DTR Data Terminal Ready DSR Data Set Ready DCD Data Carrier Detect (RS-232's Received Line Signal Detector) SG Signal Ground RTS Request to Send CTS Clear to Send
&os; needs the RTS and CTS signals for flow control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if a login session does not go away when the line hangs up, there may be a problem with the cable. Like other &unix;-like operating systems, &os; uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. &os; avoids sending commands to the modem or watching for status reports from the modem. Serial Interface Considerations &os; supports the NS8250-, NS16450-, NS16550-, and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and 16450 devices have single-character buffers. The 16550 device provides a 16-character buffer, which allows for better system performance. Bugs in plain 16550's prevent the use of the 16-character buffer, so use 16550A's if possible. Because single-character-buffer devices require more work by the operating system than the 16-character-buffer devices, 16550A-based serial interface cards are preferred. If the system has many active serial ports or will have a heavy load, 16550A-based cards are better for low-error-rate communications. Quick Overview getty As with terminals, init spawns a getty process for each configured serial port for dial-in connections. For example, if a modem is attached to /dev/ttyu0, ps ax might show this: 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyu0 When a user dials the modem's line and the modems connect, the Carrier Detect (CD) line is reported by the modem. The kernel notices that the carrier has been detected and instructs getty to open the port. getty sends a login: prompt at the specified initial line speed. getty watches to see if legitimate characters are received, and, in a typical configuration, if it finds junk (probably due to the modem's connection speed being different than getty's speed), getty tries adjusting the line speeds until it receives reasonable characters. /usr/bin/login After the user enters their login name, getty executes /usr/bin/login, which completes the login by asking for the user's password and then starting the user's shell. Configuration Files There are three system configuration files in /etc that probably need to be edited to allow dial-up access to the &os; system. /etc/gettytab contains configuration information for the /usr/libexec/getty daemon. /etc/ttys holds information that tells init which ttys should have getty processes running on them. Lastly, port initialization commands can be placed in /etc/rc.d/serial. There are two schools of thought regarding dial-up modems on &unix;. One group likes to configure their modems and systems so that no matter at what speed a remote user dials in, the local computer-to-modem RS-232 interface runs at a locked speed. The benefit of this configuration is that the remote user always sees a system login prompt immediately. The downside is that the system does not know what a user's true data rate is, so full-screen programs like Emacs will not adjust their screen-painting methods to make their response better for slower connections. The other group configures their modems' RS-232 interface to vary its speed based on the remote user's connection speed. For example, V.32bis (14.4 Kbps) connections to the modem might make the modem run its RS-232 interface at 19.2 Kbps, while 2400 bps connections make the modem's RS-232 interface run at 2400 bps. Because getty does not understand any particular modem's connection speed reporting, getty gives a login: message at an initial speed and watches the characters that come back in response. If the user sees junk, it is assumed that they know they should press Enter until they see a recognizable prompt. If the data rates do not match, getty sees anything the user types as junk, tries going to the next speed and gives the login: prompt again. This procedure normally only takes a keystroke or two before the user sees a good prompt. This login sequence does not look as clean as the locked-speed method, but a user on a low-speed connection should receive better interactive response from full-screen programs. This section will try to give balanced configuration information, but is biased towards having the modem's data rate follow the connection rate. <filename>/etc/gettytab</filename> /etc/gettytab /etc/gettytab is a &man.termcap.5;-style file of configuration information for &man.getty.8;. Refer to &man.gettytab.5; for complete information on the format of the file and the list of capabilities. Locked-speed Config When locking a modem's data communications rate at a particular speed, no changes to /etc/gettytab should be needed. Matching-speed Config Set up an entry in /etc/gettytab to give getty information about the speeds to use for the modem. For a 2400 bps modem, use the existing D2400 entry. # # Fast dialup terminals, 2400/1200/300 rotary (can start either way) # D2400|d2400|Fast-Dial-2400:\ :nx=D1200:tc=2400-baud: 3|D1200|Fast-Dial-1200:\ :nx=D300:tc=1200-baud: 5|D300|Fast-Dial-300:\ :nx=D2400:tc=300-baud: For a higher speed modem, add an entry in /etc/gettytab. This entry is for a 14.4 Kbps modem with a top interface speed of 19.2 Kbps: # # Additions for a V.32bis Modem # um|V300|High Speed Modem at 300,8-bit:\ :nx=V19200:tc=std.300: un|V1200|High Speed Modem at 1200,8-bit:\ :nx=V300:tc=std.1200: uo|V2400|High Speed Modem at 2400,8-bit:\ :nx=V1200:tc=std.2400: up|V9600|High Speed Modem at 9600,8-bit:\ :nx=V2400:tc=std.9600: uq|V19200|High Speed Modem at 19200,8-bit:\ :nx=V9600:tc=std.19200: This will result in 8-bit, no parity connections. The example above starts the communications rate at 19.2 Kbps (for a V.32bis connection), then cycles through 9600 bps (for V.32), 2400 bps, 1200 bps, 300 bps, and back to 19.2 Kbps. Communications rate cycling is implemented with the nx= (next table) capability. Each of the lines uses a tc= (table continuation) entry to pick up the rest of the standard settings for a particular data rate. For a 28.8 Kbps modem or to take advantage of compression on a 14.4 Kbps modem, use a higher communications rate than 19.2 Kbps. Here is an example of a gettytab entry starting a 57.6 Kbps: # # Additions for a V.32bis or V.34 Modem # Starting at 57.6 Kbps # vm|VH300|Very High Speed Modem at 300,8-bit:\ :nx=VH57600:tc=std.300: vn|VH1200|Very High Speed Modem at 1200,8-bit:\ :nx=VH300:tc=std.1200: vo|VH2400|Very High Speed Modem at 2400,8-bit:\ :nx=VH1200:tc=std.2400: vp|VH9600|Very High Speed Modem at 9600,8-bit:\ :nx=VH2400:tc=std.9600: vq|VH57600|Very High Speed Modem at 57600,8-bit:\ :nx=VH9600:tc=std.57600: For a slow CPU or a heavily loaded system without 16550A-based serial ports, there may be sio silo errors at 57.6 Kbps. <filename>/etc/ttys</filename> /etc/ttys Configuration of /etc/ttys is covered in . Configuration for modems is similar, but a different argument is passed to getty and a different terminal type is specified. The general format for both locked-speed and matching-speed configurations is: ttyu0 "/usr/libexec/getty xxx" dialup on The first item in the above line is the device special file for this entry. ttyu0 indicates that getty is watching /dev/ttyu0. The xxx will replace the initial gettytab capability and is the process init will run on the device. The third item, dialup, is the default terminal type. The fourth parameter, on, indicates to init that the line is operational. There can be a fifth parameter, secure, but it should only be used for terminals which are physically secure, such as the system console. The default terminal type, dialup in this example, may depend on local preferences. dialup is the traditional default terminal type on dial-up lines so that users may customize their login scripts to notice when the terminal is dialup and automatically adjust their terminal type. Setting vt102 as the default terminal type allows users to use VT102 emulation on their remote systems. After editing /etc/ttys, send the init process a HUP signal to re-read the file: &prompt.root; kill -HUP 1 Wait until the modem is properly configured and connected before signaling init. Locked-speed Config For a locked-speed configuration, the ttys entry needs to have a fixed-speed entry provided to getty. For a modem whose port speed is locked at 19.2 Kbps, the ttys entry might look like this: ttyu0 "/usr/libexec/getty std.19200" dialup on If the modem is locked at a different data rate, substitute the appropriate value for std.speed instead of std.19200. Make sure to use a valid type listed in /etc/gettytab. Matching-speed Config In a matching-speed configuration, the ttys entry needs to reference the appropriate beginning auto-baud entry in /etc/gettytab. For example, for the above suggested entry for a matching-speed modem that starts at 19.2 Kbps, the /etc/ttys entry might look like this: ttyu0 "/usr/libexec/getty V19200" dialup on <filename>/etc/rc.d/serial</filename> rc files rc.serial High-speed modems, like V.32, V.32bis, and V.34 modems, need to use hardware (RTS/CTS) flow control. stty can be used to set the hardware flow control flag in the &os; kernel for the modem ports. For example, to set the termios flag crtscts on COM2's dial-in and dial-out initialization devices, the following lines could be added to /etc/rc.d/serial: # Serial port initial configuration stty -f /dev/ttyu1.init crtscts stty -f /dev/cuau1.init crtscts Modem Settings For a modem whose parameters may be permanently set in non-volatile RAM, a terminal program such as tip can be used to set the parameters. Connect to the modem using the same communications speed as the initial speed getty will use and configure the modem's non-volatile RAM to match these requirements: CD asserted when connected. DTR asserted for operation and dropping DTR hangs up the line and resets the modem. CTS transmitted data flow control. Disable XON/XOFF flow control. RTS received data flow control. Quiet mode (no result codes). No command echo. Read the documentation for the modem to find out which commands and/or DIP switch settings are needed. For example, to set the above parameters on a &usrobotics; &sportster; 14,400 external modem, give these commands to the modem: ATZ AT&C1&D2&H1&I0&R2&W Other settings can be adjusted in the modem, such as whether it will use V.42bis and/or MNP5 compression. The &usrobotics; &sportster; 14,400 external modem also has some DIP switches that need to be set. Other modems, may need these settings: Switch 1: UP — DTR Normal Switch 2: N/A (Verbal Result Codes/Numeric Result Codes) Switch 3: UP — Suppress Result Codes Switch 4: DOWN — No echo, offline commands Switch 5: UP — Auto Answer Switch 6: UP — Carrier Detect Normal Switch 7: UP — Load NVRAM Defaults Switch 8: N/A (Smart Mode/Dumb Mode) Result codes should be disabled/suppressed for dial-up modems to avoid problems that can occur if getty mistakenly gives a login: prompt to a modem that is in command mode and the modem echoes the command or returns a result code. This sequence can result in an extended, silly conversation between getty and the modem. Locked-speed Config For a locked-speed configuration, configure the modem to maintain a constant modem-to-computer data rate independent of the communications rate. On a &usrobotics; &sportster; 14,400 external modem, these commands will lock the modem-to-computer data rate at the speed used to issue the commands: ATZ AT&B1&W Matching-speed Config For a variable-speed configuration, configure the modem to adjust its serial port data rate to match the incoming call rate. On a &usrobotics; &sportster; 14,400 external modem, these commands will lock the modem's error-corrected data rate to the speed used to issue the commands, while allowing the serial port rate to vary for non-error-corrected connections: ATZ AT&B2&W Checking the Modem's Configuration Most high-speed modems provide commands to view the modem's current operating parameters in a somewhat human-readable fashion. On the &usrobotics; &sportster; 14,400 external modem, ATI5 displays the settings that are stored in the non-volatile RAM. To see the true operating parameters of the modem, as influenced by the modem's DIP switch settings, use ATZ and then ATI4. For a different brand of modem, check the modem's manual to see how to double-check the modem's configuration parameters. Troubleshooting Here are a few steps for troubleshooting a dial-up modem on a &os; system. Checking Out the &os; System Hook up the modem to the &os; system, boot the system, and, if the modem has status indication lights, watch to see whether the modem's DTR indicator lights when the login: prompt appears on the system's console. If it lights up, that should mean that &os; has started a getty process on the appropriate communications port and is waiting for the modem to accept a call. If the DTR indicator does not light, login to the &os; system through the console and type ps ax to see if &os; is trying to run a getty process on the correct port: 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu0 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu1 If something like this is displayed instead: 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyu0 and the modem has not accepted a call yet, this means that getty has completed its open on the communications port. This could indicate a problem with the cabling or a misconfigured modem, because getty should not be able to open the communications port until carrier detect has been asserted by the modem. If no getty processes are waiting to open the desired ttyuN port, double-check the entries in /etc/ttys to see if there are any mistakes. Also, check /var/log/messages to see if there are any log messages from init or getty. If there are any messages, triple-check /etc/ttys and /etc/gettytab, as well as the appropriate device special files, /dev/ttyuN, for any mistakes, missing entries, or missing device special files. Try Dialing In Try dialing into the system. Be sure to use 8 bits, no parity, and 1 stop bit on the remote system. If a prompt does not appear right away, or the prompt shows garbage, try pressing Enter about once per second. If there is still no login: prompt after a while, try sending a BREAK. When using a high-speed modem, try dialing again after locking the dialing modem's interface speed. If there is still no login: prompt, check /etc/gettytab again and double-check that: The initial capability name specified in the entry in /etc/ttys matches the name of a capability in /etc/gettytab. Each nx= entry matches another gettytab capability name. Each tc= entry matches another gettytab capability name. If the modem on the &os; system will not answer, make sure that the modem is configured to answer the phone when DTR is asserted. If the modem seems to be configured correctly, verify that the DTR line is asserted by checking the modem's indicator lights. If it still does not work, take a break and come back to it later. If it still does not work, try sending an email message to the &a.questions; describing the modem and the problem. Dial-out Service dial-out service The following are tips for getting the host to connect over the modem to another computer. This is appropriate for establishing a terminal session with a remote host. This kind of connection can be helpful to get a file on the Internet if there are problems using PPP. If PPP is not working, use the terminal session to FTP the needed file. Then use zmodem to transfer it to the machine. Using a Stock Hayes Modem A generic Hayes dialer is built into tip. Use at=hayes in /etc/remote. The Hayes driver is not smart enough to recognize some of the advanced features of newer modems messages like BUSY, NO DIALTONE, or CONNECT 115200. Turn those messages off when using tip with ATX0&W. The dial timeout for tip is 60 seconds. The modem should use something less, or else tip will think there is a communication problem. Try ATS7=45&W. Using <literal>AT</literal> Commands /etc/remote Create a direct entry in /etc/remote. For example, if the modem is hooked up to the first serial port, /dev/cuau0, use the following line: cuau0:dv=/dev/cuau0:br#19200:pa=none Use the highest bps rate the modem supports in the br capability. Then, type tip cuau0 to connect to the modem. Or, use cu as root with the following command: &prompt.root; cu -lline -sspeed line is the serial port, such as /dev/cuau0, and speed is the speed, such as 57600. When finished entering the AT commands, type ~. to exit. The <literal>@</literal> Sign Does Not Work The @ sign in the phone number capability tells tip to look in /etc/phones for a phone number. But, the @ sign is also a special character in capability files like /etc/remote, so it needs to be escaped with a backslash: pn=\@ Dialing from the Command Line Put a generic entry in /etc/remote. For example: tip115200|Dial any phone number at 115200 bps:\ :dv=/dev/cuau0:br#115200:at=hayes:pa=none:du: tip57600|Dial any phone number at 57600 bps:\ :dv=/dev/cuau0:br#57600:at=hayes:pa=none:du: This should now work: &prompt.root; tip -115200 5551234 Users who prefer cu over tip, can use a generic cu entry: cu115200|Use cu to dial any number at 115200bps:\ :dv=/dev/cuau1:br#57600:at=hayes:pa=none:du: and type: &prompt.root; cu 5551234 -s 115200 Setting the <acronym>bps</acronym> Rate Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps rate is appropriate with the br capability. tip thinks a good default is 1200 bps which is why it looks for a tip1200 entry. 1200 bps does not have to be used, though. Accessing a Number of Hosts Through a Terminal Server Rather than waiting until connected and typing CONNECT host each time, use tip's cm capability. For example, these entries in /etc/remote will let you type tip pain or tip muffin to connect to the hosts pain or muffin, and tip deep13 to connect to the terminal server. pain|pain.deep13.com|Forrester's machine:\ :cm=CONNECT pain\n:tc=deep13: muffin|muffin.deep13.com|Frank's machine:\ :cm=CONNECT muffin\n:tc=deep13: deep13:Gizmonics Institute terminal server:\ :dv=/dev/cuau2:br#38400:at=hayes:du:pa=none:pn=5551234: Using More Than One Line with <command>tip</command> This is often a problem where a university has several modem lines and several thousand students trying to use them. Make an entry in /etc/remote and use @ for the pn capability: big-university:\ :pn=\@:tc=dialout dialout:\ :dv=/dev/cuau3:br#9600:at=courier:du:pa=none: Then, list the phone numbers in /etc/phones: big-university 5551111 big-university 5551112 big-university 5551113 big-university 5551114 tip will try each number in the listed order, then give up. To keep retrying, run tip in a while loop. Using the Force Character Ctrl P is the default force character, used to tell tip that the next character is literal data. The force character can be set to any other character with the ~s escape, which means set a variable. Type ~sforce=single-char followed by a newline. single-char is any single character. If single-char is left out, then the force character is the null character, which is accessed by typing Ctrl2 or CtrlSpace . A pretty good value for single-char is Shift Ctrl 6 , which is only used on some terminal servers. To change the force character, specify the following in ~/.tiprc: force=single-char Upper Case Characters This happens when Ctrl A is pressed, which is tip's raise character, specially designed for people with broken caps-lock keys. Use ~s to set raisechar to something reasonable. It can be set to be the same as the force character, if neither feature is used. Here is a sample ~/.tiprc for Emacs users who need to type Ctrl 2 and Ctrl A : force=^^ raisechar=^^ The ^^ is ShiftCtrl6 . File Transfers with <command>tip</command> When talking to another &unix;-like operating system, files can be sent and received using ~p (put) and ~t (take). These commands run cat and echo on the remote system to accept and send files. The syntax is: ~p local-file remote-file ~t remote-file local-file There is no error checking, so another protocol, like zmodem, should probably be used. Using <application>zmodem</application> with <command>tip</command>? To receive files, start the sending program on the remote end. Then, type ~C rz to begin receiving them locally. To send files, start the receiving program on the remote end. Then, type ~C sz files to send them to the remote system. Kazutaka YOKOTA Contributed by Bill Paul Based on a document by Setting Up the Serial Console serial console Introduction &os; has the ability to boot a system with a dumb terminal on a serial port as a console. This configuration is useful for system administrators who wish to install &os; on machines that have no keyboard or monitor attached, and developers who want to debug the kernel or device drivers. As described in , &os; employs a three stage bootstrap. The first two stages are in the boot block code which is stored at the beginning of the &os; slice on the boot disk. The boot block then loads and runs the boot loader as the third stage code. In order to set up booting from a serial console, the boot block code, the boot loader code, and the kernel need to be configured. Quick Serial Console Configuration This section assumes the default setup and provides a fast overview of setting up the serial console. Connect the serial cable to COM1 and the controlling terminal. To see all the boot messages on the serial console, issue the following command as the superuser: &prompt.root; echo 'console="comconsole"' >> /boot/loader.conf Edit /etc/ttys and change off to on and dialup to vt100 for the ttyu0 entry. Otherwise, a password will not be required to connect via the serial console, resulting in a potential security hole. Reboot the system to see if the changes took effect. If a different configuration is required, see the next section for a more in-depth configuration explanation. In-Depth Serial Console Configuration Prepare a serial cable. null-modem cable Use either a null-modem cable or a standard serial cable and a null-modem adapter. See for a discussion on serial cables. Unplug the keyboard. Many PC systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected. Some machines will refuse to boot until the keyboard is plugged in. If the computer complains about the error, but boots anyway, no further configuration is needed. If the computer refuses to boot without a keyboard attached, the BIOS needs to be configured so that it ignores this error (if it can). Consult the motherboard's manual for details on how to do this. Try setting the keyboard to Not installed in the BIOS. The keyboard can still be used as this setting just tells the BIOS not to probe for a keyboard at power-on. The BIOS should not complain if the keyboard is absent. You can leave the keyboard plugged in even with this flag set to Not installed and the keyboard will still work. If the above option is not present in the BIOS, look for an Halt on Error option instead. Setting this to All but Keyboard or even to No Errors, will have the same effect. If the system has a &ps2; mouse, chances are good that both the mouse and keyboard need to be unplugged. This is because &ps2; mice share some hardware with the keyboard and leaving the mouse plugged in can fool the keyboard probe into thinking the keyboard is still there. Plug a dumb terminal into COM1 (sio0). If a dumb terminal is not available, use an old computer with a modem program, or the serial port on another &unix; box. If there is no COM1 (sio0), get one. At this time, there is no way to select a port other than COM1 for the boot blocks without recompiling the boot blocks. If COM1 is being used by another device, temporarily remove that device and install a new boot block and kernel once &os; is up and running. Make sure the configuration file of the custom kernel has appropriate flags set for COM1 (sio0). Relevant flags are: 0x10 Enables console support for this unit. The other console flags are ignored unless this is set. Currently, at most one unit can have console support. The first one, in config file order, with this flag set is preferred. This option alone will not make the serial port the console. Set the following flag or use as described below, together with this flag. 0x20 Forces this unit to be the console, unless there is another higher priority console, regardless of as discussed below. The flag 0x20 must be used together with the flag. 0x40 Reserves this unit (in conjunction with 0x10) and makes the unit unavailable for normal access. This flag should not be set to the serial port to use as the serial console. The only use of this flag is to designate the unit for kernel remote debugging. See The Developer's Handbook for more information on remote debugging. Here is an example setting: device sio0 flags 0x10 Refer to &man.sio.4; for more details. If the flags were not set, run UserConfig on a different console or recompile the kernel. Create boot.config in the root directory of the a partition on the boot drive. This file instructs the boot block code how to boot the system. In order to activate the serial console, one or more of the following options are needed. When using multiple options, include them all on the same line: Toggles between the internal and serial consoles. Use this to switch console devices. For instance, to boot from the internal (video) console, use to direct the boot loader and the kernel to use the serial port as its console device. Alternatively, to boot from the serial port, use to tell the boot loader and the kernel to use the video display as the console instead. Toggles between the single and dual console configurations. In the single configuration, the console will be either the internal console (video display) or the serial port, depending on the state of . In the dual console configuration, both the video display and the serial port will become the console at the same time, regardless of the state of . However, the dual console configuration takes effect only while the boot block is running. Once the boot loader gets control, the console specified by becomes the only console. Makes the boot block probe the keyboard. If no keyboard is found, the and options are automatically set. Due to space constraints in the current version of the boot blocks, is capable of detecting extended keyboards only. Keyboards with less than 101 keys and without F11 and F12 keys may not be detected. Keyboards on some laptops may not be properly found because of this limitation. If this is the case, do not use . Unfortunately there is no workaround for this problem. Use either to select the console automatically, or to activate the serial console. Other options are described in &man.boot.8;. The options, except for , are passed to the boot loader. The boot loader will determine whether the internal video or the serial port should become the console by examining the state of . This means that if is specified but is not specified in /boot.config, the serial port can be used as the console only during the boot block as the boot loader will use the internal video display as the console. Boot the machine. When &os; starts, the boot blocks echo the contents of /boot.config to the console. For example: /boot.config: -P Keyboard: no The second line appears only if is in /boot.config and indicates the presence or absence of the keyboard. These messages go to either the serial or internal console, or both, depending on the option in /boot.config. Options Message goes to none internal console serial console serial and internal consoles serial and internal consoles , keyboard present internal console , keyboard absent serial console After the message, there will be a small pause before the boot blocks continue loading the boot loader and before any further messages are printed to the console. Under normal circumstances, there is no need to interrupt the boot blocks, but one can do so in order to make sure things are set up correctly. Press any key, other than Enter, at the console to interrupt the boot process. The boot blocks will then prompt for further action: >> FreeBSD/i386 BOOT Default: 0:ad(0,a)/boot/loader boot: Verify that the above message appears on either the serial or internal console, or both, according to the options in /boot.config. If the message appears in the correct console, press Enter to continue the boot process. If there is no prompt on the serial terminal, something is wrong with the settings. Enter then Enter or Return to tell the boot block (and then the boot loader and the kernel) to choose the serial port for the console. Once the system is up, go back and check what went wrong. During the third stage of the boot process, one can still switch between the internal console and the serial console by setting appropriate environment variables in the boot loader. See for more information. Summary Here is the summary of the various settings discussed in this section: Case 1: Set the Flags to 0x10 for <devicename>sio0</devicename> device sio0 flags 0x10 Options in /boot.config Console during boot blocks Console during boot loader Console in kernel nothing internal internal internal serial serial serial serial and internal internal internal serial and internal serial serial , keyboard present internal internal internal , keyboard absent serial and internal serial serial Case 2: Set the Flags to 0x30 for <devicename>sio0</devicename> device sio0 flags 0x30 Options in /boot.config Console during boot blocks Console during boot loader Console in kernel nothing internal internal serial serial serial serial serial and internal internal serial serial and internal serial serial , keyboard present internal internal serial , keyboard absent serial and internal serial serial Tips for the Serial Console Setting a Faster Serial Port Speed By default, the serial port settings are 9600 baud, 8 bits, no parity, and 1 stop bit. To change the default console speed, the following options are available: Recompile the boot blocks with BOOT_COMCONSOLE_SPEED set to the new console speed. See for detailed instructions about building and installing new boot blocks. If the serial console is configured in some other way than by booting with , or if the serial console used by the kernel is different from the one used by the boot blocks, add the following option to a custom kernel configuration file and compile a new kernel: options CONSPEED=19200 Add the boot option to /boot.config. See &man.boot.8; for a description of how to add options to /boot.config and a list of the supported options. Enable comconsole_speed in /boot/loader.conf. This option depends on console, boot_serial, and boot_multicons being set in /boot/loader.conf too. An example of using comconsole_speed to change the serial console speed is: boot_multicons="YES" boot_serial="YES" comconsole_speed="115200" console="comconsole,vidconsole" Using a Serial Port Other Than <devicename>sio0</devicename> for the Console Using a port other than sio0 as the console requires the boot blocks, the boot loader, and the kernel to be recompiled as follows. Get the kernel source as described in . Edit /etc/make.conf and set BOOT_COMCONSOLE_PORT to the address of the port to use: 0x3F8, 0x2F8, 0x3E8 or 0x2E8. Only sio0 through sio3 (COM1 through COM4) can be used as multiport serial cards will not work. No interrupt setting is needed. Create a custom kernel configuration file and add appropriate flags for the serial port to use. For example, to make sio1 (COM2) the console: device sio1 flags 0x10 or device sio1 flags 0x30 The console flags for the other serial ports should not be set. Recompile and install the boot blocks and the boot loader: &prompt.root; cd /sys/boot &prompt.root; make clean &prompt.root; make &prompt.root; make install Rebuild and install the kernel. Write the boot blocks to the boot disk with &man.bsdlabel.8; and boot from the new kernel. Entering the DDB Debugger from the Serial Line To drop into the kernel debugger from the serial console, compile a custom kernel with the following options. Note that while this is useful for remote diagnostics, it is also dangerous if a spurious BREAK is generated on the serial port. options BREAK_TO_DEBUGGER options DDB Getting a Login Prompt on the Serial Console While this is not required, it is possible to get a login prompt over the serial line. First, make sure that the boot messages are displayed and it is possible to enter the kernel debugging session through the serial console. Open /etc/ttys with a text editor and locate the lines: ttyu0 "/usr/libexec/getty std.9600" unknown off secure ttyu1 "/usr/libexec/getty std.9600" unknown off secure ttyu2 "/usr/libexec/getty std.9600" unknown off secure ttyu3 "/usr/libexec/getty std.9600" unknown off secure ttyu0 through ttyu3 correspond to COM1 through COM4. Change off to on for the desired port. If the speed of the serial port has been changed, change std.9600 to match the new setting. The terminal type can also be changed from unknown to the actual type of the serial terminal. After editing the file, type kill -HUP 1 to make this change take effect. Changing Console from the Boot Loader Previous sections described how to set up the serial console by tweaking the boot block. This section shows how to specify the console by entering some commands and environment variables in the boot loader. As the boot loader is invoked at the third stage of the boot process, the settings in the boot loader will override the settings in the boot block. Setting Up the Serial Console The boot loader and the kernel to use the serial console can be specified by writing one line in /boot/loader.conf: console="comconsole" This will take effect regardless of the settings in the boot block discussed in the previous section. This line should be the first line of /boot/loader.conf so as to see boot messages on the serial console as early as possible. Likewise, to specify the internal console: console="vidconsole" If the boot loader environment variable console is not set, the boot loader, and subsequently the kernel, will use whichever console is indicated by in the boot block. The console can be specified in /boot/loader.conf.local or in /boot/loader.conf. See &man.loader.conf.5; for more information. At the moment, the boot loader has no option equivalent to in the boot block, and there is no provision to automatically select the internal console and the serial console based on the presence of the keyboard. Using a Serial Port Other Than <devicename>sio0</devicename> for the Console The boot loader needs to be compiled in order to use a serial port other than sio0 for the serial console. Follow the procedure described in . Caveats While most systems will boot without a keyboard, quite a few will not boot without a graphics adapter. Machines with AMI BIOSes can be configured to boot with no graphics adapter installed by changing the graphics adapter setting in the CMOS configuration to Not installed. However, many machines do not support this option and will refuse to boot if there is no display hardware in the system. With these machines, leave some kind of graphics card plugged in, even if it is just a junky mono board. A monitor does not need to be attached. One might also try installing an AMI BIOS. diff --git a/en_US.ISO8859-1/books/handbook/users/chapter.xml b/en_US.ISO8859-1/books/handbook/users/chapter.xml index 4ac3616b48..39f145021d 100644 --- a/en_US.ISO8859-1/books/handbook/users/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/users/chapter.xml @@ -1,1082 +1,1043 @@ Neil Blakey-Milner Contributed by Users and Basic Account Management Synopsis &os; allows multiple users to use the computer at the same time. While only one user can sit in front of the screen and use the keyboard at any one time, any number of users can log in to the system through the network. To use the system, every user must have a user account. After reading this chapter, you will know: The differences between the various user accounts on a &os; system. How to add and remove user accounts. How to change account details, such as the user's full name or preferred shell. How to set limits on a per-account basis to control the resources, such as memory and CPU time, that accounts and groups of accounts are allowed to access. How to use groups to make account management easier. Before reading this chapter, you should: Understand the basics of &unix; and &os;. Introduction Since all access to the &os; system is achieved via accounts and all processes are run by users, user and account management is important. Every account on a &os; system has certain information associated with it to identify the account. User name The user name is typed at the login: prompt. User names must be unique on the system as no two users can have the same user name. There are a number of rules for creating valid user names, documented in &man.passwd.5;. Typically user names consist of eight or fewer all lower case characters in order to maintain backwards compatibility with applications. Password Each account has an associated password. While the password can be blank, this is highly discouraged and every account should have a password. User ID (UID) The User ID (UID) is a number, traditionally from 0 to 65535 It is possible to use UIDs/GIDs as large as 4294967295, but such IDs can cause serious problems with software that makes assumptions about the values of IDs. , used to uniquely identify the user to the system. Internally, &os; uses the UID to identify users. Commands that allow a user name to be specified will first convert it to the UID. Though unlikely, it is possible for several accounts with different user names to share the same UID. As far as &os; is concerned, these accounts are one user. Group ID (GID) The Group ID (GID) is a number, traditionally from 0 to 65535, used to uniquely identify the primary group that the user belongs to. Groups are a mechanism for controlling access to resources based on a user's GID rather than their UID. This can significantly reduce the size of some configuration files. A user may also be a member of more than one group. Login class Login classes are an extension to the group mechanism that provide additional flexibility when tailoring the system to different users. Password change time By default &os; does not force users to change their passwords periodically. Password expiration can be enforced on a per-user basis, forcing some or all users to change their passwords after a certain amount of time has elapsed. Account expiry time By default &os; does not expire accounts. When creating accounts that need a limited lifespan, such as student accounts in a school, specify the account expiry date. After the expiry time has elapsed, the account cannot be used to log in to the system, although the account's directories and files will remain. User's full name The user name uniquely identifies the account to &os;, but does not necessarily reflect the user's real name. This information can be associated with the account. Home directory The home directory is the full path to a directory on the system. This is the user's starting directory when the user logs in. A common convention is to put all user home directories under /home/username or /usr/home/username. Each user stores their personal files and subdirectories in their own home directory. User shell The shell provides the default environment users use to interact with the system. There are many different kinds of shells, and experienced users will have their own preferences, which can be reflected in their account settings. There are three main types of accounts: the superuser, system accounts, and user accounts. The superuser account, usually called root, is used to manage the system with no limitations on privileges. System accounts are used to run services. User accounts are assigned to real people and are used to log in and use the system. The Superuser Account accounts superuser (root) The superuser account, usually called root, is used to perform system administration tasks and should not be used for day-to-day tasks like sending and receiving mail, general exploration of the system, or programming. This is because the superuser, unlike normal user accounts, can operate without limits, and misuse of the superuser account may result in spectacular disasters. User accounts are unable to destroy the system by mistake, so it is generally best to use normal user accounts whenever possible, unless extra privilege is required. Always double and triple-check any commands issued as the superuser, since an extra space or missing character can mean irreparable data loss. Always create a user account for the system administrator and use this account to log in to the system for general usage. This applies equally to multi-user or single-user systems. Later sections will discuss how to create additional accounts and how to change between the normal user and superuser. System Accounts accounts system System accounts are used to run services such as DNS, mail, and web servers. The reason for this is security; if all services ran as the superuser, they could act without restriction. accounts daemon accounts operator Examples of system accounts are daemon, operator, bind, news, and www. accounts nobody nobody is the generic unprivileged system account. However, the more services that use nobody, the more files and processes that user will become associated with, and hence the more privileged that user becomes. User Accounts accounts user User accounts are the primary means of access for real people to the system. User accounts insulate the user and the environment, preventing users from damaging the system or other users, and allowing users to customize their environment without affecting others. Every person accessing the system should have a unique user account. This allows the administrator to find out who is doing what, prevents users from clobbering each others' settings or reading each others' mail, and so forth. Each user can set up their own environment to accommodate their use of the system, by using alternate shells, editors, key bindings, and language. Modifying Accounts accounts modifying &os; provides a variety of different commands to manage user accounts. The most common commands are summarized below, followed by more detailed examples of their usage. Command Summary &man.adduser.8; The recommended command-line application for adding new users. &man.rmuser.8; The recommended command-line application for removing users. &man.chpass.1; A flexible tool for changing user database information. &man.passwd.1; The simple command-line tool to change user passwords. &man.pw.8; A powerful and flexible tool for modifying all aspects of user accounts. <command>adduser</command> accounts adding adduser /usr/share/skel skeleton directory &man.adduser.8; is a simple program for adding new users When a new user is added, this program automatically updates /etc/passwd and /etc/group. It also creates a home directory for the new user, copies in the default configuration files from /usr/share/skel, and can optionally mail the new user a welcome message. Adding a User on &os; &prompt.root; adduser Username: jru Full name: J. Random User Uid (Leave empty for default): Login group [jru]: Login group is jru. Invite jru into other groups? []: wheel Login class [default]: Shell (sh csh tcsh zsh nologin) [sh]: zsh Home directory [/home/jru]: Home directory permissions (Leave empty for default): Use password-based authentication? [yes]: Use an empty password? (yes/no) [no]: Use a random password? (yes/no) [no]: Enter password: Enter password again: Lock out the account after creation? [no]: Username : jru Password : **** Full Name : J. Random User Uid : 1001 Class : Groups : jru wheel Home : /home/jru Shell : /usr/local/bin/zsh Locked : no OK? (yes/no): yes adduser: INFO: Successfully added (jru) to the user database. Add another user? (yes/no): no Goodbye! &prompt.root; Since the password is not echoed when typed, be careful to not mistype the password when creating the user account. <command>rmuser</command> rmuser accounts removing To completely remove a user from the system use &man.rmuser.8;. This command performs the following steps: Removes the user's &man.crontab.1; entry if one exists. Removes any &man.at.1; jobs belonging to the user. Kills all processes owned by the user. Removes the user from the system's local password file. Removes the user's home directory, if it is owned by the user. Removes the incoming mail files belonging to the user from /var/mail. Removes all files owned by the user from temporary file storage areas such as /tmp. Finally, removes the username from all groups to which it belongs in /etc/group. If a group becomes empty and the group name is the same as the username, the group is removed. This complements the per-user unique groups created by &man.adduser.8;. &man.rmuser.8; cannot be used to remove superuser accounts since that is almost always an indication of massive destruction. By default, an interactive mode is used, as shown in the following example. <command>rmuser</command> Interactive Account Removal &prompt.root; rmuser jru Matching password entry: jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh Is this the entry you wish to remove? y Remove user's home directory (/home/jru)? y Updating password file, updating databases, done. Updating group file: trusted (removing group jru -- personal group is empty) done. Removing user's incoming mail file /var/mail/jru: done. Removing files belonging to jru from /tmp: done. Removing files belonging to jru from /var/tmp: done. Removing files belonging to jru from /var/tmp/vi.recover: done. &prompt.root; <command>chpass</command> chpass &man.chpass.1; can be used to change user database information such as passwords, shells, and personal information. Only the superuser can change other users' information and passwords with &man.chpass.1;. When passed no options, aside from an optional username, &man.chpass.1; displays an editor containing user information. When the user exists from the editor, the user database is updated with the new information. You will be asked for your password after exiting the editor if you are not the superuser. Interactive <command>chpass</command> by Superuser #Changing user database information for jru. Login: jru Password: * Uid [#]: 1001 Gid [# or name]: 1001 Change [month day year]: Expire [month day year]: Class: Home directory: /home/jru Shell: /usr/local/bin/zsh Full Name: J. Random User Office Location: Office Phone: Home Phone: Other information: A user can change only a small subset of this information, and only for their own user account. Interactive <command>chpass</command> by Normal User #Changing user database information for jru. Shell: /usr/local/bin/zsh Full Name: J. Random User Office Location: Office Phone: Home Phone: Other information: &man.chfn.1; and &man.chsh.1; are links to &man.chpass.1;, as are &man.ypchpass.1;, &man.ypchfn.1;, and &man.ypchsh.1;. NIS support is automatic, so specifying the yp before the command is not necessary. How to configure NIS is covered in . <command>passwd</command> passwd accounts changing password &man.passwd.1; is the usual way to change your own password as a user, or another user's password as the superuser. To prevent accidental or unauthorized changes, the user must enter their original password before a new password can be set. This is not the case when the superuser changes a user's password. Changing Your Password &prompt.user; passwd Changing local password for jru. Old password: New password: Retype new password: passwd: updating the database... passwd: done Changing Another User's Password as the Superuser &prompt.root; passwd jru Changing local password for jru. New password: Retype new password: passwd: updating the database... passwd: done As with &man.chpass.1;, &man.yppasswd.1; is a link to &man.passwd.1;, so NIS works with either command. <command>pw</command> pw &man.pw.8; is a command line utility to create, remove, modify, and display users and groups. It functions as a front end to the system user and group files. &man.pw.8; has a very powerful set of command line options that make it suitable for use in shell scripts, but new users may find it more complicated than the other commands presented in this section. Limiting Users limiting users accounts limiting &os; provides several methods for an administrator to limit the amount of system resources an individual may use. These limits are discussed in two sections: disk quotas and other resource limits. quotas limiting users quotas disk quotas Disk quotas limit the amount of disk space available to users and provide a way to quickly check that usage without calculating it every time. Quotas are discussed in . The other resource limits include ways to limit the amount of CPU, memory, and other resources a user may consume. These are defined using login classes and are discussed here. /etc/login.conf Login classes are defined in /etc/login.conf and are described in detail in &man.login.conf.5;. Each user account is assigned to a login class, default by default, and each login class has a set of login capabilities associated with it. A login capability is a name=value pair, where name is a well-known identifier and value is an arbitrary string which is processed accordingly depending on the name. Setting up login classes and capabilities is rather straightforward and is also described in &man.login.conf.5;. &os; does not normally read the configuration in /etc/login.conf directly, but instead reads the /etc/login.conf.db database which provides faster lookups. Whenever /etc/login.conf is edited, the /etc/login.conf.db must be updated by executing the following command: &prompt.root; cap_mkdb /etc/login.conf Resource limits differ from the default login capabilities in two ways. First, for every limit, there is a soft (current) and hard limit. A soft limit may be adjusted by the user or application, but may not be set higher than the hard limit. The hard limit may be lowered by the user, but can only be raised by the superuser. Second, most resource limits apply per process to a specific user, not to the user as a whole. These differences are mandated by the specific handling of the limits, not by the implementation of the login capability framework. Below are the most commonly used resource limits. The rest of the limits, along with all the other login capabilities, can be found in &man.login.conf.5;. coredumpsize - coredumpsize - limiting users - coredumpsize - - The limit on the size of a core file generated by a - program is subordinate to other limits on disk usage, such + The limit on the size of a core filecoredumpsize generated by a + program is subordinate to other limitslimiting userscoredumpsize on disk usage, such as filesize, or disk quotas. This limit is often used as a less-severe method of controlling disk space consumption. Since users do not generate core files themselves, and often do not delete them, setting this may save them from running out of disk space should a large program crash. cputime - cputime - - limiting users - cputime - - The maximum amount of CPU time a user's process may + The maximum amount of CPUcputimelimiting userscputime time a user's process may consume. Offending processes will be killed by the kernel. This is a limit on CPU time consumed, not percentage of the CPU as displayed in some fields by &man.top.1; and &man.ps.1;. filesize - filesize - - limiting users - filesize - - The maximum size of a file the user may own. Unlike + The maximum size of a filefilesizelimiting usersfilesize the user may own. Unlike disk quotas, this limit is enforced on individual files, not the set of all files a user owns. maxproc - maxproc - - limiting users - maxproc - - The maximum number of processes a user can run. This + The maximum number of processesmaxproclimiting usersmaxproc a user can run. This includes foreground and background processes. This limit may not be larger than the system limit specified by the kern.maxproc &man.sysctl.8;. Setting this limit too small may hinder a user's productivity as it is often useful to be logged in multiple times or to execute pipelines. Some tasks, such as compiling a large program, spawn multiple processes and other intermediate preprocessors. memorylocked - memorylocked - - limiting users - memorylocked - - The maximum amount of memory a process may request + The maximum amount of memorymemorylockedlimiting usersmemorylocked a process may request to be locked into main memory using &man.mlock.2;. Some system-critical programs, such as &man.amd.8;, lock into main memory so that if the system begins to swap, they do not contribute to disk thrashing. memoryuse - memoryuse - limiting users - memoryuse - The maximum amount of memory a process may consume at + The maximum amount of memorymemoryuselimiting usersmemoryuse a process may consume at any given time. It includes both core memory and swap usage. This is not a catch-all limit for restricting memory consumption, but is a good start. openfiles - openfiles - limiting users - openfiles - - The maximum number of files a process may have open. + The maximum number of files a process may have openopenfileslimiting usersopenfiles. In &os;, files are used to represent sockets and IPC channels, so be careful not to set this too low. The system-wide limit for this is defined by the kern.maxfiles &man.sysctl.8;. sbsize - sbsize - limiting users - sbsize - The limit on the amount of network memory, and - thus mbufs, a user may consume in order to limit network + thus mbufssbsizelimiting userssbsize, a user may consume in order to limit network communications. stacksize - stacksize - limiting users - stacksize - - The maximum size of a process stack. This alone is + The maximum size of a process stackstacksizelimiting usersstacksize. This alone is not sufficient to limit the amount of memory a program may use so it should be used in conjunction with other limits. There are a few other things to remember when setting resource limits. Following are some general tips, suggestions, and miscellaneous comments. Processes started at system startup by /etc/rc are assigned to the daemon login class. Although the /etc/login.conf that comes with the system is a good source of reasonable values for most limits, they may not be appropriate for every system. Setting a limit too high may open the system up to abuse, while setting it too low may put a strain on productivity. Users of &xorg; should probably be granted more resources than other users. &xorg; by itself takes a lot of resources, but it also encourages users to run more programs simultaneously. Many limits apply to individual processes, not the user as a whole. For example, setting openfiles to 50 means that each process the user runs may open up to 50 files. The total amount of files a user may open is the value of openfiles multiplied by the value of maxproc. This also applies to memory consumption. For further information on resource limits and login classes and capabilities in general, refer to &man.cap.mkdb.1;, &man.getrlimit.2;, and &man.login.conf.5;. Groups groups /etc/groups accounts groups A group is a list of users. A group is identified by its group name and GID. In &os;, the kernel uses the UID of a process, and the list of groups it belongs to, to determine what the process is allowed to do. Most of the time, the GID of a user or process usually means the first group in the list. The group name to GID mapping is listed in /etc/group. This is a plain text file with four colon-delimited fields. The first field is the group name, the second is the encrypted password, the third the GID, and the fourth the comma-delimited list of members. For a more complete description of the syntax, refer to &man.group.5;. The superuser can modify /etc/group using a text editor. Alternatively, &man.pw.8; can be used to add and edit groups. For example, to add a group called teamtwo and then confirm that it exists: Adding a Group Using &man.pw.8; &prompt.root; pw groupadd teamtwo &prompt.root; pw groupshow teamtwo teamtwo:*:1100: In this example, 1100 is the GID of teamtwo. Right now, teamtwo has no members. This command will add jru as a member of teamtwo. Adding User Accounts to a New Group Using &man.pw.8; &prompt.root; pw groupmod teamtwo -M jru &prompt.root; pw groupshow teamtwo teamtwo:*:1100:jru The argument to is a comma-delimited list of users to be added to a new (empty) group or to replace the members of an existing group. To the user, this group membership is different from (and in addition to) the user's primary group listed in the password file. This means that the user will not show up as a member when using with &man.pw.8;, but will show up when the information is queried via &man.id.1; or a similar tool. When &man.pw.8; is used to add a user to a group, it only manipulates /etc/group and does not attempt to read additional data from /etc/passwd. Adding a New Member to a Group Using &man.pw.8; &prompt.root; pw groupmod teamtwo -m db &prompt.root; pw groupshow teamtwo teamtwo:*:1100:jru,db In this example, the argument to is a comma-delimited list of users who are to be added to the group. Unlike the previous example, these users are appended to the group list and do not replace the list of existing users in the group. Using &man.id.1; to Determine Group Membership &prompt.user; id jru uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo) In this example, jru is a member of the groups jru and teamtwo. For more information about this command and the format of /etc/group, refer to &man.pw.8; and &man.group.5;. Becoming Superuser There are several ways to do things as the superuser. The worst way is to log in as root directly. Usually very little activity requires root so logging off and logging in as root, performing tasks, then logging off and on again as a normal user is a waste of time. A better way is to use &man.su.1; without providing a login but using - to inherit the root environment. Not providing a login will imply super user. For this to work the login that must be in the wheel group. An example of a typical software installation would involve the administrator unpacking the software as a normal user and then elevating their privileges for the build and installation of the software. Install a Program As The Superuser &prompt.user; configure &prompt.user; make &prompt.user; su - Password: &prompt.root; make install &prompt.root; exit &prompt.user; Note in this example the transition to root is less painful than logging off and back on twice. Using &man.su.1; works well for single systems or small networks with just one system administrator. For more complex environments (or even for these simple environments) sudo should be used. It is provided as a port, security/sudo. It allows for things like activity logging, granting users the ability to only run certain commands as the superuser, and several other options.