diff --git a/en_US.ISO8859-1/articles/contributing/article.xml b/en_US.ISO8859-1/articles/contributing/article.xml index b0a45facaa..bcd1f4af45 100644 --- a/en_US.ISO8859-1/articles/contributing/article.xml +++ b/en_US.ISO8859-1/articles/contributing/article.xml @@ -1,549 +1,550 @@
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: - The BSD copyrightBSD 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. 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 5d92602d5d..f22afca2f2 100644 --- a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml @@ -1,2006 +1,2010 @@ 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. - If a SCSI card has multiple SCSI busesSCSIbus on it then each bus - requires its own cam_sim + If a SCSI card has multiple SCSI buses + SCSIbus + 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. Finally we register the SCSI buses associated with our SCSI - adapterSCSIadapter: + 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; } Then allocate whatever data structures (such as - 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 + card-dependent hardware control block + hardware 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. XPT_CALC_GEOMETRY - calculate logical (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 If the returned geometry differs much enough from what the - 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 + SCSI controller BIOSSCSI + BIOS 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 fc90285e3e..5b6ae42863 100644 --- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml @@ -1,686 +1,687 @@ 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); - Most sound driversdevice driverssound need to store additional private + Most sound driversdevice drivers + sound 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 75a575f28a..a2895fb241 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml @@ -1,558 +1,560 @@ 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: - The Core teamcore team decides if + The Core team + core team decides if the code should be part of make world. - The Release Engineeringrelease engineering + The Release Engineering + release 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 55da99f249..d451643383 100644 --- a/en_US.ISO8859-1/books/handbook/boot/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/boot/chapter.xml @@ -1,1016 +1,1017 @@ 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: 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: unload load kernel.old Use kernel.GENERIC to refer to the default kernel that comes with an installation, or - kernel.oldkernel.old to refer to the - previously installed kernel before a system upgrade or - before configuring a custom kernel. + kernel.old + kernel.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 d240376426..5e44f6f878 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml @@ -1,3103 +1,3115 @@ 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: - Use svnSubversion-CURRENTSyncing with Subversion to check out + Use svnSubversion + -CURRENT + Syncing 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. Use the CTM-CURRENTSyncing with 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. - Before compiling &os.current;-CURRENTcompiling, read + Before compiling &os.current;-CURRENT + compiling, 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;: - Use svnSubversion to check out + Use svn + Subversion 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-STABLEsyncing with Subversion + page, such as stable/9 + -STABLE + syncing 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. Consider using CTM-STABLEsyncing with CTM if you do + linkend="ctm">CTM + -STABLEsyncing with CTM + if you do not have a fast connection to the Internet. - Before compiling &os.stable;-STABLEcompiling, read + Before compiling &os.stable;-STABLE + compiling, 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 60a7ac871f..d2de5ad2e4 100644 --- a/en_US.ISO8859-1/books/handbook/install/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/install/chapter.xml @@ -1,4879 +1,4881 @@ 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 This option instructs &man.sysinstall.8; - to use passive modeFTPpassive mode for all FTP - operations. + to use passive mode + FTPpassive 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 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 - proxyFTPvia a HTTP proxy. + proxyFTP + via 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 eac6e1decb..bbd7817705 100644 --- a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml @@ -1,884 +1,922 @@ 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 multitaskingpreemptive multitasking with + Preemptive multitasking + preemptive 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 facilitiesmulti-user facilities which allow + Multi-user facilities + multi-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. - Strong TCP/IP networkingTCP/IP networking with + Strong TCP/IP networking + TCP/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 protectionmemory protection ensures that + Memory protection + memory protection ensures that applications (or users) cannot interfere with each other. One application crashing will not affect others in any way. The industry standard X Window - SystemX Window System (X11R7) provides a graphical user + System + X 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 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. - Demand paged virtual memoryvirtual memory and + Demand paged virtual memory + virtual memory and merged VM/buffer cache design efficiently satisfies applications with large appetites for memory while still maintaining interactive response to other users. - SMPSymmetric Multi-Processing (SMP) support for machines with - multiple CPUs. + SMP + Symmetric Multi-Processing (SMP) + support for machines with multiple CPUs. compilers C compilers 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 codesource code for the entire system + Source code + source 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! - &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 + &os; is based on the 4.4BSD-Lite + 4.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 serversFTP servers + FTP servers + FTP servers - World Wide Web serversweb servers (standard or secure + World Wide Web servers + web servers (standard or secure [SSL]) IPv4 and IPv6 routing - Firewallsfirewall and NATNAT (IP masquerading) - gateways + Firewallsfirewall + and NATNAT + (IP masquerading) gateways electronic mail email email Electronic Mail servers - USENETUSENET 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. - Networking: Need a new router?router - A name server (DNS)?DNS Server 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 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. Software Development: The basic &os; system comes with a full complement of development - tools including the renowned GNU C/C++GNU Compiler Collection compiler and - debugger. + 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: AppleApple + url="http://www.apple.com/">Apple + Apple CiscoCisco + url="http://www.cisco.com/">Cisco + Cisco Juniper NetAppNetApp + url="http://www.netapp.com/">NetApp + NetApp &os; is also used to power some of the biggest sites on the Internet, including: Yahoo!Yahoo! + url="http://www.yahoo.com/">Yahoo! + Yahoo! YandexYandex + url="http://www.yandex.ru/">Yandex + Yandex ApacheApache + url="http://www.apache.org/">Apache + Apache RamblerRambler + url="http://www.rambler.ru/">Rambler + Rambler - SinaSina + Sina + Sina Pair NetworksPair Networks + url="http://www.pair.com/">Pair Networks + Pair Networks Sony JapanSony Japan + url="http://www.sony.co.jp/">Sony Japan + Sony Japan NetcraftNetcraft + url="http://www.netcraft.com/">Netcraft + Netcraft NetEaseNetEase + url="http://www.163.com/">NetEase + NetEase WeathernewsWeathernews + url="http://www.weathernews.com/">Weathernews + Weathernews TELEHOUSE - AmericaTELEHOUSE America + AmericaTELEHOUSE America + Experts - ExchangeExperts 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; 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 - The committerscommitters + The committers + committers 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 - The &os; core teamcore team + The &os; core team + core 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 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 Listcontributors is a long + &os; Contributors List + contributors 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 1b4b618de7..596bb28c35 100644 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.xml @@ -1,974 +1,975 @@ 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: - LANG for &posix;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/network-servers/chapter.xml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml index ac804104c2..94812d3870 100644 --- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml @@ -1,6319 +1,6323 @@ 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 - A NIS master serverNISmaster server. This + A NIS master server + NISmaster 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 serversNISslave server. Similar to - the &windowsnt; backup domain controllers, NIS slave + NIS slave servers + NISslave 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 clientsNISclient. NIS clients, like + NIS clients + NISclient. + 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.