diff --git a/en_US.ISO8859-1/articles/releng-packages/article.sgml b/en_US.ISO8859-1/articles/releng-packages/article.sgml index 05216d8f23..8ec0804d77 100644 --- a/en_US.ISO8859-1/articles/releng-packages/article.sgml +++ b/en_US.ISO8859-1/articles/releng-packages/article.sgml @@ -1,366 +1,366 @@ %man; %teams; %freebsd; %authors; ]>
FreeBSD Release Engineering for Third Party Software Packages Steve Price
steve@FreeBSD.org
 $FreeBSD$ This paper describes the approach used by the FreeBSD release engineering team to produce a high quality package set suitable for official FreeBSD release media. This document is a work in progress, but eventually it will cover the process used to build a clean package set on the FreeBSD.org Ports Cluster, how to configure any other set of machines as a ports cluster, how to split up the packages for the release media, and how to verify that a package set is consistent. Building packages from the Ports Collection The FreeBSD Ports collection is a collection of over &os.numports; third-party software packages available for FreeBSD. The &a.portmgr; is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany a given FreeBSD release. The Ports Cluster In order to provide a consistent set of third-party packages for FreeBSD releases, every port is built in a separate chroot environment, starting with an empty /usr/local and /usr/X11R6. The requisite dependencies are installed as packages before the build proceeds. This enforces consistency in the package build process. By starting the package build in a pristine environment, we can assure that the package metadata (such as required dependencies) is accurate. This way, we will never generate packages that might work on some systems and not on others depending on what software was previously installed. The Ports Cluster for the x86 architecture currently consists of a master node (Dual Pentium III 733MHz) and 8 slave nodes (Pentium III 800MHz) to do the actual package builds. With this configuration, a complete package build takes over 24 hours. These machines are co-located with the other FreeBSD Project equipment at Yahoo's corner of Exodus in Santa Clara, CA. The Ports Cluster for the Alpha architecture consists of 7 PWS 500A machines donated by Compaq and also co-located with Yahoo's facilities. The Package Split For FreeBSD 4.4 over 4.1 gigabytes of packages were created. This causes a problem for CDROM distributions because we would like to ship as many packages as possible without making the user insert another disc to satisfy dependencies. The solution is to create clusters of like packages with similar dependencies and group these onto specific discs. This section describes the software and methodology used to create those package sets for the official FreeBSD release discs. The scripts and other files needed to produce a package split can be found in the CVS tree in ports/Tools/scripts/release. Copy this directory to a machine that has enough free disk space to hold 2 to 3 times the size of the package set that you wish to split. The following scripts are present in this directory: config This file contains the free space on each disc and whether packages, distfiles, or both are allowed on any given disc. The first column is the disc name. It must be of the form disc[0-9a-z]. Currently it is setup to allow for 10 discs (4 for the release set and 6 for the toolkit). There is an implied extra disc called scratch where all of the remaining distfiles/packages land if they do not fit elsewhere. The second column can be either a 1 or 0, where 1 says that it is okay to place packages on this disc. The third column works the same way, but it controls whether distfiles are placed on this disc. The last column denotes the number of bytes of free space on a disc. doit.sh This is the workhorse. Once you have all the files in place and things properly configured this script directs the process of splitting packages. Beware it is interactive so you need to keep an eye on it as it runs. More details on what happens in this script will follow. checkdeps.pl Makes sure all packages dependencies are satisfied given an INDEX file and a directory of packages. oneshot.pl This is where all the magic (and I use that term loosely as it is mostly just a brute force approach) happens. Given a list of required packages for each disc and a set of packages/distfiles this is the script that places a package or distfile on a disc along with all of its dependencies. print-cdrom-packages.sh This file is a copy of src/release/scripts/print-cdrom-packages.sh from the release you are working on. scrubindex.pl This script removes lines from an INDEX file for packages that are not present. It also removes the XFree86 dependencies. NOTE: you will need to tweak the value of the xdep variable to make sure the version number is correct. setup.sh This is a helper script that I use on the bento cluster to grab a copy of the ports tree and the matching set of the packages/distfiles. Here is a checklist of things you will need to check or configure before going any further. Edit config to denote the number of discs you have, their sizes, and whether you want them want to contain packages, distfiles, both, or neither. Make sure you remove the gen directory if there is an old one laying around. This directory contains working files that will only be valid for the current split. On your first pass through a split it is best to fake the copying of packages and distfiles. This will save both time and diskspace while you do a couple of trial runs to make sure things fit, etc. In the oneshot.pl set the fake variable to 1 and instead of actually copying the files it will &man.touch.1; them. Be sure you turn this off or set fake to 0 before you give the resultant discs to the person that will be mastering the discs otherwise they will get a directory full of zero-sized files. Make sure you have a recent copy of the print-cdrom-packages.sh and that it is from the correct release. Check to make sure the XFree86 dependency in scrubindex.pl has the correct version number. You will also need to make sure this value is correct in doit.sh as well. Next you will need to get a copy of the ports tree, packages, and distfiles from a recent build on the package cluster. See the setup.sh for a working example but essentially here is what needs to be done. Grab a copy of ports.tar.gz and extract it into the ports directory alongside doit.sh and the - scripts directory. + scripts directory. Remove the packages/distfiles directories or symlinks. Bento has these as symlinks and you will have mixed results if you do not get rid of them before proceeding. Create a new ports/packages directory and copy the package set from the package building cluster. Create a new ports/distfiles directory and copy the distfiles from the package building cluster. NOTE: if you do not want any distfiles simply create the directory and leave it empty. This directory must be present even if it does not contain anything. Now we are finally ready for the fun task of actually splitting the packages. You start the processing by running ./doit.sh. Here is what it does the first time you run it. Create a list of the restricted (can not be on the master FTP site) ports. Asks you if you would like to remove the restricted ports. Most of the time you will want to answer (y)es here. Create a list of the packages/distfiles that can not be put on the discs. Asks you if you would like to remove the non-cdromable packages/distfiles. Most of the time you will want to answer (y)es here. Copies the INDEX from the ports directory to the gen directory. In doing so it removes the lines for ports where the packages do not exist. It also checks to make sure that all of the required dependency packages are present. Create a list of packages that are required on each disc. Asks you if you would like to populate the discs. After populating each disc it will check for missing dependencies, scrub the INDEX file, and create the CHECKSUM.MD5 file. Check to make sure the required packages made it on each disc and gives you a summary of the sizes of each disc. After going through this the first time if you are lucky enough that all of the required packages built and fit on each disc. All you need to do is set fake to 0 in - oneshot.pl and re-run + oneshot.pl and re-run ./doit.sh. The second and subsequent times around it will skip steps 1-5 above. If you want to re-run any of those steps refer to doit.sh for which files need to be removed to not short-circuit those steps. If you want to repeat all of these steps then the easiest way is to rm -rf gen. Upon successful completion the packages/distfiles will be in the disc* directories and the leftover will be in the scratch directory. What to do if things go wrong? Here is some common gotchas and workarounds. Missing required packages This is a pretty common occurrence. You will either need to wait for a new set of packages where the missing packages were built or get someone to re-start the package build for you. Do not attempt to build the missing packages on your own machine and add them into the fray. While you might be able to get away with this if you are extremely careful the vast majority of the time you will miss some little detail and the simple process of adding a package could make hundreds of others come up mysteriously broken. Required packages will not fit This happens on occasion too and is relatively easy to fix. Simply edit print-cdrom-packages.sh to move packages around until they fit. Yes this is an iterative process and one of the reasons why you should enable fake in oneshot.pl until you have gotten things the way you want them. Re-run ./doit.sh after you made your adjustments. Required packages not on the right (or any) disc This usually means you did not add them to print-cdrom-packages.sh or you put them on the wrong disc. This script is the gospel by which this whole process determines where a package must be. If you want to force a package to land on a particular disc this is the only way to ensure that it will happen. If you get completely stuck and can not figure out why things are borked or how to fix them then email &a.steve; for assistance.
diff --git a/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml b/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml index 58b93c41ce..4569b0a490 100644 --- a/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/mac/chapter.sgml @@ -1,7821 +1,7821 @@ Chris Costello TrustedBSD Project
chris@FreeBSD.org
 Robert Watson TrustedBSD Project
rwatson@FreeBSD.org
 The TrustedBSD MAC Framework MAC Documentation Copyright This documentation was developed for the FreeBSD Project by Chris Costello at Safeport Network Services and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 (CBOSS), as part of the DARPA CHATS research program. Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met: Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) 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 DOCUMENTATION IS PROVIDED BY THE NETWORKS ASSOCIATES TECHNOLOGY, INC "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 NETWORKS ASSOCIATES TECHNOLOGY, INC 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 DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Synopsis FreeBSD includes experimental support for several mandatory access control policies, as well as a framework for kernel security extensibility, the TrustedBSD MAC Framework. The MAC Framework provides a pluggable access control framework, permitting new security policies to be easily linked into the kernel, loaded at boot, or loaded dynamically at run-time. The framework provides a variety of features to make it easier to implement new policies, including the ability to easily tag security labels (such as confidentiality information) onto system objects. This chapter introduces the MAC policy framework and provides documentation for a sample MAC policy module. Introduction The TrustedBSD MAC framework provides a mechanism to allow the compile-time or run-time extension of the kernel access control model. New system policies may be implemented as kernel modules and linked to the kernel; if multiple policy modules are present, their results will be composed. The MAC Framework provides a variety of access control infrastructure services to assist policy writers, including support for transient and persistent policy-agnostic object security labels. This support is currently considered experimental. Policy Background Mandatory Access Control (MAC), refers to a set of access control policies that are mandatorily enforced on users by the operating system. MAC policies may be contrasted with Discretionary Access Control (DAC) protections, by which non-administrative users may (at their discretion) protect objects. In traditional UNIX systems, DAC protections include file permissions and access control lists; MAC protections include process controls preventing inter-user debugging and firewalls. A variety of MAC policies have been formulated by operating system designers and security researches, including the Multi-Level Security (MLS) confidentiality policy, the Biba integrity policy, Role-Based Access Control (RBAC), and Type Enforcement (TE). Each model bases decisions on a variety of factors, including user identity, role, and security clearance, as well as security labels on objects representing concepts such as data sensitivity and integrity. The TrustedBSD MAC Framework is capable of supporting policy modules that implement all of these policies, as well as a broad class of system hardening policies. In addition, despite the name, the MAC Framework can also be used to implement purely discretionary policies, as policy modules are given substantial flexibility in how they authorize protections. MAC Framework Kernel Architecture The TrustedBSD MAC Framework permits kernel modules to extend the operating system security policy, as well as providing infrastructure functionality required by many access control modules. If multiple policies are simultaneously loaded, the MAC Framework will usefully (for some definition of useful) compose the results of the policies. Kernel Elements The MAC Framework contains a number of kernel elements: Framework management interfaces Concurrency and synchronization primitives. Policy registration Extensible security label for kernel objects Policy entry point composition operators Label management primitives Entry point API invoked by kernel services Entry point API to policy modules Entry points implementations (policy life cycle, object life cycle/label management, access control checks). Policy-agnostic label-management system calls mac_syscall() multiplex system call Various security policies implemented as MAC policy modules Management Interfaces The TrustedBSD MAC Framework may be directly managed using sysctls, loader tunables, and system calls. In most cases, sysctls and loader tunables modify the same parameters, and control behavior such as enforcement of protections relating to various kernel subsystems. In addition, if MAC debugging support is compiled into the kernel, a variety of counters will be maintained tracking label allocation. In most cases, it is advised that per-subsystem enforcement controls not be used to control policy behavior in production environments, as they broadly impact the operation of all active policies. Instead, per-policy controls should be preferred to ensure proper policy operation. Loading and unloading of policy modules is performed using the system module management system calls and other system interfaces, including loader variables. Concurrency and Synchronization As the set of active policies may change at run-time, and the invocation of entry points is non-atomic, synchronization is required to prevent unloading or loading of new policies while an entry point invocation is progress, freezing the list of policies for the duration. This is accomplished by means of a Framework busy count. Whenever an entry point is entered, the busy count is incremented; whenever it is exited, the busy count is decremented. While the busy count is elevated, policy list changes are not permitted, and threads attempting to modify the policy list will sleep until the list is not busy. The busy count is protected by a mutex, and a condition variable is used to wake up sleepers waiting on policy list modifications. Various optimizations are used to reduce the overhead of the busy count, including avoiding the full cost of incrementing and decrementing if the list is empty or contains only static entries (policies that are loaded before the system starts, and cannot be unloaded). Policy Registration The MAC Framework maintains two lists of active policies: a static list, and a dynamic list. The lists differ only with regards to their locking semantics: an elevated reference count is not required to make use of the static list. When kernel modules containing MAC Framework policies are loaded, the policy module will use SYSINIT to invoke a registration function; when a policy module is unloaded, SYSINIT will likewise invoke a de-registration function. Registration may fail if a policy module is loaded more than once, if insufficient resources are available for the registration (for example, the policy might require labeling and insufficient labeling state might be available), or other policy prerequisites might not be met (some policies may only be loaded prior to boot). Likewise, de-registration may fail if a policy refuses an unload. Entry Points Kernel services interact with the MAC Framework in two ways: they invoke a series of APIs to notify the framework of relevant events, and they a policy-agnostic label structure in security-relevant objects. This label structure is maintained by the MAC Framework via label management entry points, and permits the Framework to offer a labeling service to policy modules through relatively non-invasive changes to the kernel subsystem maintaining the object. For example, label structures have been added to processes, process credentials, sockets, pipes, vnodes, Mbufs, network interfaces, IP reassembly queues, and a variety of other security-relevant structures. Kernel services also invoke the MAC Framework when they perform important security decisions, permitting policy modules to augment those decisions based on their own criteria (possibly including data stored in security labels). Policy Composition When more than one policy module is loaded into the kernel at a time, the results of the policy modules will be composed by the framework using a composition operator. This operator is currently hard-coded, and requires that all active policies must approve a request for it to occur. As policies may return a variety of error conditions (success, access denied, object doesn't exist, ...), a precedence operator selects the resulting error from the set of errors returned by policies. While it is not guaranteed that the resulting composition will be useful or secure, we've found that it is for many useful selections of policies. Labeling Support As many interesting access control extensions rely on security labels on objects, the MAC Framework provides a set of policy-agnostic label management system calls covering a variety of user-exposed objects. Common label types include partition identifiers, sensitivity labels, integrity labels, compartments, domains, roles, and types. Policy modules participate in the internalization and externalization of string-based labels provides by user applications, and can expose multiple label elements to applications if desired. In-memory labels are stored in struct label, which consists of a fixed-length array of unions, each holding a void * pointer and a long. Policies registering for label storage will be assigned a "slot" identifier, which may be used to dereference the label storage. The semantics of the storage are left entirely up to the policy module: modules are provided with a variety of entry points associated with the kernel object life cycle, including initialization, association/creation, and destruction. Using these interfaces, it is possible to implement reference counting and other storage mechanisms. Direct access to the kernel object is generally not required by policy modules to retrieve a label, as the MAC Framework generally passes both a pointer to the object and a direct pointer to the object's label into entry points. Initialization entry points frequently include a blocking disposition flag indicating whether or not an initialization is permitted to block; if blocking is not permitted, a failure may be returned to cancel allocation of the label. This may occur, for example, in the network stack during interrupt handling, where blocking is not permitted. Due to the performance cost of maintaining labels on in-flight network packets (Mbufs), policies must specifically declare a requirement that Mbuf labels be allocated. Dynamically loaded policies making use of labels must be able to handle the case where their init function has not been called on an object, as objects may already exist when the policy is loaded. In the case of file system labels, special support is provided for the persistent storage of security labels in extended attributes. Where available, EA transactions are used to permit consistent compound updates of security labels on vnodes. Currently, if a labeled policy permits dynamic unloading, its state slot cannot be reclaimed. System Calls The MAC Framework implements a number of system calls: most of these calls support the policy-agnostic label retrieval and manipulation APIs exposed to user applications. The label management calls accept a label description structure, struct mac, which contains a series of MAC label elements. Each element contains a character string name, and character string value. Each policy will be given the chance to claim a particular element name, permitting policies to expose multiple independent elements if desired. Policy modules perform the internalization and externalization between kernel labels and user-provided labels via entry points, permitting a variety of semantics. Label management system calls are generally wrapped by user library functions to perform memory allocation and error handling. In addition, mac_syscall() permits policy modules to create new system calls without allocating system calls. mac_execve() permits an atomic process credential label change when executing a new image. MAC Policy Architecture Security policies are either linked directly into the kernel, or compiled into loadable kernel modules that may be loaded at boot, or dynamically using the module loading system calls at runtime. Policy modules interact with the system through a set of declared entry points, providing access to a stream of system events and permitting the policy to influence access control decisions. Each policy contains a number of elements: Optional configuration parameters for policy. Centralized implementation of the policy logic and parameters. Optional implementation of policy life cycle events, such as initialization and destruction. Optional support for initializing, maintaining, and destroying labels on selected kernel objects. Optional support for user process inspection and modification of labels on selected objects. Implementation of selected access control entry points that are of interest to the policy. Declaration of policy identity, module entry points, and policy properties. Policy Declaration Modules may be declared using the MAC_POLICY_SET() macro, which names the policy, provides a reference to the MAC entry point vector, provides load-time flags determining how the policy framework should handle the policy, and optionally requests the allocation of label state by the framework. static struct mac_policy_ops mac_policy_ops = { .mpo_destroy = mac_policy_destroy, .mpo_init = mac_policy_init, .mpo_init_bpfdesc_label = mac_policy_init_bpfdesc_label, .mpo_init_cred_label = mac_policy_init_label, /* ... */ .mpo_check_vnode_setutimes = mac_policy_check_vnode_setutimes, .mpo_check_vnode_stat = mac_policy_check_vnode_stat, .mpo_check_vnode_write = mac_policy_check_vnode_write, }; The MAC policy entry point vector, mac_policy_ops in this example, associates functions defined in the module with specific entry points. A complete listing of available entry points and their prototypes may be found in the MAC entry point reference section. Of specific interest during module registration are the .mpo_destroy and .mpo_init entry points. .mpo_init will be invoked once a policy is successfully registered with the module framework but prior to any other entry points becoming active. This permits the policy to perform any policy-specific allocation and initialization, such as initialization of any data or locks. .mpo_destroy will be invoked when a policy module is unloaded to permit releasing of any allocated memory and destruction of locks. Currently, these two entry points are invoked with the MAC policy list mutex held to prevent any other entry points from being invoked: this will be changed, but in the mean time, policies should be careful about what kernel primitives they invoke so as to avoid lock ordering or sleeping problems. The policy declaration's module name field exists so that the module may be uniquely identified for the purposes of module dependencies. An appropriate string should be selected. The full string name of the policy is displayed to the user via the kernel log during load and unload events, and also exported when providing status information to userland processes. Policy Flags The policy declaration flags field permits the module to provide the framework with information about its capabilities at the time the module is loaded. Currently, three flags are defined: MPC_LOADTIME_FLAG_UNLOADOK This flag indicates that the policy module may be unloaded. If this flag is not provided, then the policy framework will reject requests to unload the module. This flag might be used by modules that allocate label state and are unable to free that state at runtime. MPC_LOADTIME_FLAG_NOTLATE This flag indicates that the policy module must be loaded and initialized early in the boot process. If the flag is specified, attempts to register the module following boot will be rejected. The flag may be used by policies that require pervasive labeling of all system objects, and cannot handle objects that have not been properly initialized by the policy. MPC_LOADTIME_FLAG_LABELMBUFS This flag indicates that the policy module requires labeling of Mbufs, and that memory should always be allocated for the storage of Mbuf labels. By default, the MAC Framework will not allocate label storage for Mbufs unless at least one loaded policy has this flag set. This measurably improves network performance when policies do not require Mbuf labeling. A kernel option, MAC_ALWAYS_LABEL_MBUF, exists to force the MAC Framework to allocate Mbuf label storage regardless of the setting of this flag, and may be useful in some environments. Policies using the MPC_LOADTIME_FLAG_LABELMBUFS without the MPC_LOADTIME_FLAG_NOTLATE flag set must be able to correctly handle NULL Mbuf label pointers passed into entry points. This is necessary as in-flight Mbufs without label storage may persist after a policy enabling Mbuf labeling has been loaded. If a policy is loaded before the network subsystem is active (i.e., the policy is not being loaded late), then all Mbufs are guaranteed to have label storage. Policy Entry Points Four classes of entry points are offered to policies registered with the framework: entry points associated with the registration and management of policies, entry points denoting initialization, creation, destruction, and other life cycle events for kernel objects, events associated with access control decisions that the policy module may influence, and calls associated with the management of labels on objects. In addition, a mac_syscall() entry point is provided so that policies may extend the kernel interface without registering new system calls. Policy module writers should be aware of the kernel locking strategy, as well as what object locks are available during which entry points. Writers should attempt to avoid deadlock scenarios by avoiding grabbing non-leaf locks inside of entry points, and also follow the locking protocol for object access and modification. In particular, writers should be aware that while necessary locks to access objects and their labels are generally held, sufficient locks to modify an object or its label may not be present for all entry points. Locking information for arguments is documented in the MAC framework entry point document. Policy entry points will pass a reference to the object label along with the object itself. This permits labeled policies to be unaware of the internals of the object yet still make decisions based on the label. The exception to this is the process credential, which is assumed to be understood by policies as a first class security object in the kernel. Policies that do not implement labels on kernel objects will be passed NULL pointers for label arguments to entry points. MAC Policy Entry Point Reference General-Purpose Module Entry Points <function>&mac.mpo;_init</function> void &mac.mpo;_init struct mac_policy_conf *conf &mac.thead; conf MAC policy definition Policy load event. The policy list mutex is held, so caution should be applied. <function>&mac.mpo;_destroy</function> void &mac.mpo;_destroy struct mac_policy_conf *conf &mac.thead; conf MAC policy definition Policy load event. The policy list mutex is held, so caution should be applied. <function>&mac.mpo;_syscall</function> int &mac.mpo;_syscall struct thread *td int call void *arg &mac.thead; td Calling thread call Syscall number arg Pointer to syscall arguments This entry point provides a policy-multiplexed system call so that policies may provide additional services to user processes without registering specific system calls. The policy name provided during registration is used to demux calls from userland, and the arguments will be forwarded to this entry point. When implementing new services, security modules should be sure to invoke appropriate access control checks from the MAC framework as needed. For example, if a policy implements an augmented signal functionality, it should call the necessary signal access control checks to invoke the MAC framework and other registered policies. Modules must currently perform the copyin() of the syscall data on their own. <function>&mac.mpo;_thread_userret</function> void &mac.mpo;_thread_userret struct thread *td &mac.thead; td Returning thread This entry point permits policy modules to perform MAC-related events when a thread returns to user space. This is required for policies that have floating process labels, as it's not always possible to acquire the process lock at arbitrary points in the stack during system call processing; process labels might represent traditional authentication data, process history information, or other data. Label Operations <function>&mac.mpo;_init_bpfdesc_label</function> void &mac.mpo;_init_bpfdesc_label struct label *label &mac.thead; label New label to apply Initialize the label on a newly instantiated bpfdesc (BPF descriptor) <function>&mac.mpo;_init_cred_label</function> void &mac.mpo;_init_cred_label struct label *label &mac.thead; label New label to initialize Initialize the label for a newly instantiated user credential. <function>&mac.mpo;_init_devfsdirent_label</function> void &mac.mpo;_init_devfsdirent_label struct label *label &mac.thead; label New label to apply Initialize the label on a newly instantiated devfs entry. <function>&mac.mpo;_init_ifnet_label</function> void &mac.mpo;_init_ifnet_label struct label *label &mac.thead; label New label to apply Initialize the label on a newly instantiated network interface. <function>&mac.mpo;_init_ipq_label</function> void &mac.mpo;_init_ipq_label struct label *label int flag &mac.thead; label New label to apply flag Blocking/non-blocking &man.malloc.9;; see below Initialize the label on a newly instantiated IP fragment reassembly queue. The flag field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a blocking &man.malloc.9; during this initialization call. IP fragment reassembly queue allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid blocking or long-lived operations. This entry point is permitted to fail resulting in the failure to allocate the IP fragment reassembly queue. <function>&mac.mpo;_init_mbuf_label</function> void &mac.mpo;_init_mbuf_label int flag struct label *label &mac.thead; flag Blocking/non-blocking &man.malloc.9;; see below label Policy label to initialize Initialize the label on a newly instantiated mbuf packet header (mbuf). The flag field may be one of M_WAITOK and M_NOWAIT, and should be employed to avoid performing a blocking &man.malloc.9; during this initialization call. Mbuf allocation frequently occurs in performance sensitive environments, and the implementation should be careful to avoid blocking or long-lived operations. This entry point is permitted to fail resulting in the failure to allocate the mbuf header. <function>&mac.mpo;_init_mount_label</function> void &mac.mpo;_init_mount_label struct label *mntlabel struct label *fslabel &mac.thead; mntlabel Policy label to be initialized for the mount itself fslabel Policy label to be initialized for the file system Initialize the labels on a newly instantiated mount point. <function>&mac.mpo;_init_mount_fs_label</function> void &mac.mpo;_init_mount_fs_label struct label *label &mac.thead; label Label to be initialized Initialize the label on a newly mounted file system. <function>&mac.mpo;_init_pipe_label</function> void &mac.mpo;_init_pipe_label struct label*label &mac.thead; label Label to be filled in Initialize a label for a newly instantiated pipe. <function>&mac.mpo;_init_socket_label</function> void &mac.mpo;_init_socket_label struct label *label int flag &mac.thead; label New label to initialize flag &man.malloc.9; flags Initialize a label for a newly instantiated socket. <function>&mac.mpo;_init_socket_peer_label</function> void &mac.mpo;_init_socket_peer_label struct label *label int flag &mac.thead; label New label to initialize flag &man.malloc.9; flags Initialize the peer label for a newly instantiated socket. <function>&mac.mpo;_init_proc_label</function> void &mac.mpo;_init_proc_label struct label *label &mac.thead; label New label to initialize Initialize the label for a newly instantiated process. <function>&mac.mpo;_init_vnode_label</function> void &mac.mpo;_init_vnode_label struct label *label &mac.thead; label New label to initialize Initialize the label on a newly instantiated vnode. <function>&mac.mpo;_destroy_bpfdesc_label</function> void &mac.mpo;_destroy_bpfdesc_label struct label *label &mac.thead; label bpfdesc label Destroy the label on a BPF descriptor. In this entry point a policy should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_cred_label</function> void &mac.mpo;_destroy_cred_label struct label *label &mac.thead; label Label being destroyed Destroy the label on a credential. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_devfsdirent_label</function> void &mac.mpo;_destroy_devfsdirent_label struct label *label &mac.thead; label Label being destroyed Destroy the label on a devfs entry. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_ifnet_label</function> void &mac.mpo;_destroy_ifnet_label struct label *label &mac.thead; label Label being destroyed Destroy the label on a removed interface. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_ipq_label</function> void &mac.mpo;_destroy_ipq_label struct label *label &mac.thead; label Label being destroyed Destroy the label on an IP fragment queue. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_mbuf_label</function> void &mac.mpo;_destroy_mbuf_label struct label *label &mac.thead; label Label being destroyed Destroy the label on an mbuf header. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_mount_label</function> void &mac.mpo;_destroy_mount_label struct label *label &mac.thead; label Mount point label being destroyed Destroy the labels on a mount point. In this entry point, a policy module should free the internal storage associated with mntlabel so that they may be destroyed. <function>&mac.mpo;_destroy_mount_label</function> void &mac.mpo;_destroy_mount_label struct label *mntlabel struct label *fslabel &mac.thead; mntlabel Mount point label being destroyed fslabel File system label being destroyed> Destroy the labels on a mount point. In this entry point, a policy module should free the internal storage associated with mntlabel and fslabel so that they may be destroyed. <function>&mac.mpo;_destroy_socket_label</function> void &mac.mpo;_destroy_socket_label struct label *label &mac.thead; label Socket label being destroyed Destroy the label on a socket. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_socket_peer_label</function> void &mac.mpo;_destroy_socket_peer_label struct label *peerlabel &mac.thead; peerlabel Socket peer label being destroyed Destroy the peer label on a socket. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_pipe_label</function> void &mac.mpo;_destroy_pipe_label struct label *label &mac.thead; label Pipe label Destroy the label on a pipe. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_proc_label</function> void &mac.mpo;_destroy_proc_label struct label *label &mac.thead; label Process label Destroy the label on a process. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_destroy_vnode_label</function> void &mac.mpo;_destroy_vnode_label struct label *label &mac.thead; label Process label Destroy the label on a vnode. In this entry point, a policy module should free any internal storage associated with label so that it may be destroyed. <function>&mac.mpo;_copy_mbuf_label</function> void &mac.mpo;_copy_mbuf_label struct label *src struct label *dest &mac.thead; src Source label dest Destination label Copy the label information in src into dest. <function>&mac.mpo;_copy_pipe_label</function> void &mac.mpo;_copy_pipe_label struct label *src struct label *dest &mac.thead; src Source label dest Destination label Copy the label information in src into dest. <function>&mac.mpo;_copy_vnode_label</function> void &mac.mpo;_copy_vnode_label struct label *src struct label *dest &mac.thead; src Source label dest Destination label Copy the label information in src into dest. <function>&mac.mpo;_externalize_cred_label</function> int &mac.mpo;_externalize_cred_label &mac.externalize.paramdefs; &mac.thead; &mac.externalize.tbody; &mac.externalize.para; <function>&mac.mpo;_externalize_ifnet_label</function> int &mac.mpo;_externalize_ifnet_label &mac.externalize.paramdefs; &mac.thead; &mac.externalize.tbody; &mac.externalize.para; <function>&mac.mpo;_externalize_pipe_label</function> int &mac.mpo;_externalize_pipe_label &mac.externalize.paramdefs; &mac.thead; &mac.externalize.tbody; &mac.externalize.para; <function>&mac.mpo;_externalize_socket_label</function> int &mac.mpo;_externalize_socket_label &mac.externalize.paramdefs; &mac.thead; &mac.externalize.tbody; &mac.externalize.para; <function>&mac.mpo;_externalize_socket_peer_label</function> int &mac.mpo;_externalize_socket_peer_label &mac.externalize.paramdefs; &mac.thead; &mac.externalize.tbody; &mac.externalize.para; <function>&mac.mpo;_externalize_vnode_label</function> int &mac.mpo;_externalize_vnode_label &mac.externalize.paramdefs; &mac.thead; &mac.externalize.tbody; &mac.externalize.para; <function>&mac.mpo;_internalize_cred_label</function> int &mac.mpo;_internalize_cred_label &mac.internalize.paramdefs; &mac.thead; &mac.internalize.tbody; &mac.internalize.para; <function>&mac.mpo;_internalize_ifnet_label</function> int &mac.mpo;_internalize_ifnet_label &mac.internalize.paramdefs; &mac.thead; &mac.internalize.tbody; &mac.internalize.para; <function>&mac.mpo;_internalize_pipe_label</function> int &mac.mpo;_internalize_pipe_label &mac.internalize.paramdefs; &mac.thead; &mac.internalize.tbody; &mac.internalize.para; <function>&mac.mpo;_internalize_socket_label</function> int &mac.mpo;_internalize_socket_label &mac.internalize.paramdefs; &mac.thead; &mac.internalize.tbody; &mac.internalize.para; <function>&mac.mpo;_internalize_vnode_label</function> int &mac.mpo;_internalize_vnode_label &mac.internalize.paramdefs; &mac.thead; &mac.internalize.tbody; &mac.internalize.para; Label Events This class of entry points is used by the MAC framework to permit policies to maintain label information on kernel objects. For each labeled kernel object of interest to a MAC policy, entry points may be registered for relevant life cycle events. All objects implement initialization, creation, and destruction hooks. Some objects will also implement relabeling, allowing user processes to change the labels on objects. Some objects will also implement object-specific events, such as label events associated with IP reassembly. A typical labeled object will have the following life cycle of entry points: Label initialization o (object-specific wait) \ Label creation o \ Relabel events, o--<--. Various object-specific, | | Access control events ~-->--o \ Label destruction o Label initialization permits policies to allocate memory and set initial values for labels without context for the use of the object. The label slot allocated to a policy will be zeroed by default, so some policies may not need to perform initialization. Label creation occurs when the kernel structure is associated with an actual kernel object. For example, Mbufs may be allocated and remain unused in a pool until they are required. mbuf allocation causes label initialization on the mbuf to take place, but mbuf creation occurs when the mbuf is associated with a datagram. Typically, context will be provided for a creation event, including the circumstances of the creation, and labels of other relevant objects in the creation process. For example, when an mbuf is created from a socket, the socket and its label will be presented to registered policies in addition to the new mbuf and its label. Memory allocation in creation events is discouraged, as it may occur in performance sensitive ports of the kernel; in addition, creation calls are not permitted to fail so a failure to allocate memory cannot be reported. Object specific events do not generally fall into the other broad classes of label events, but will generally provide an opportunity to modify or update the label on an object based on additional context. For example, the label on an IP fragment reassembly queue may be updated during the MAC_UPDATE_IPQ entry point as a result of the acceptance of an additional mbuf to that queue. Access control events are discussed in detail in the following section. Label destruction permits policies to release storage or state associated with a label during its association with an object so that the kernel data structures supporting the object may be reused or released. In addition to labels associated with specific kernel objects, an additional class of labels exists: temporary labels. These labels are used to store update information submitted by user processes. These labels are initialized and destroyed as with other label types, but the creation event is MAC_INTERNALIZE, which accepts a user label to be converted to an in-kernel representation. File System Object Labeling Event Operations <function>&mac.mpo;_associate_vnode_devfs</function> void &mac.mpo;_associate_vnode_devfs struct mount *mp struct label *fslabel struct devfs_dirent *de struct label *delabel struct vnode *vp struct label *vlabel &mac.thead; mp Devfs mount point fslabel Devfs file system label (mp->mnt_fslabel) de Devfs directory entry delabel Policy label associated with de vp vnode associated with de vlabel Policy label associated with vp Fill in the label (vlabel) for a newly created devfs vnode based on the devfs directory entry passed in de and its label. <function>&mac.mpo;_associate_vnode_extattr</function> int &mac.mpo;_associate_vnode_extattr struct mount *mp struct label *fslabel struct vnode *vp struct label *vlabel &mac.thead; mp File system mount point fslabel File system label vp Vnode to label vlabel Policy label associated with vp Attempt to retrieve the label for vp from the file system extended attributes. Upon success, the value 0 is returned. Should extended attribute retrieval not be supported, an accepted fallback is to copy fslabel into vlabel. In the event of an error, an appropriate value for errno should be returned. <function>&mac.mpo;_associate_vnode_singlelabel</function> void &mac.mpo;_associate_vnode_singlelabel struct mount *mp struct label *fslabel struct vnode *vp struct label *vlabel &mac.thead; mp File system mount point fslabel File system label vp Vnode to label vlabel Policy label associated with vp On non-multilabel file systems, this entry point is called to set the policy label for vp based on the file system label, fslabel. <function>&mac.mpo;_create_devfs_device</function> void &mac.mpo;_create_devfs_device dev_t dev struct devfs_dirent *devfs_dirent struct label *label &mac.thead; dev Device corresponding with devfs_dirent devfs_dirent Devfs directory entry to be labeled. label Label for devfs_dirent to be filled in. Fill out the label on a devfs_dirent being created for the passed device. This call will be made when the device file system is mounted, regenerated, or a new device is made available. <function>&mac.mpo;_create_devfs_directory</function> void &mac.mpo;_create_devfs_directory char *dirname int dirnamelen struct devfs_dirent *devfs_dirent struct label *label &mac.thead; dirname Name of directory being created namelen Length of string dirname devfs_dirent Devfs directory entry for directory being created. Fill out the label on a devfs_dirent being created for the passed directory. This call will be made when the device file system is mounted, regenerated, or a new device requiring a specific directory hierarchy is made available. <function>&mac.mpo;_create_devfs_symlink</function> void &mac.mpo;_create_devfs_symlink struct ucred *cred struct mount *mp struct devfs_dirent *dd struct label *ddlabel struct devfs_dirent *de struct label *delabel &mac.thead; cred Subject credential mp Devfs mount point dd Link destination ddlabel Label associated with dd de Symlink entry delabel Label associated with de Fill in the label (delabel) for a newly created &man.devfs.5; symbolic link entry. <function>&mac.mpo;_create_vnode_extattr</function> int &mac.mpo;_create_vnode_extattr struct ucred *cred struct mount *mp struct label *fslabel struct vnode *dvp struct label *dlabel struct vnode *vp struct label *vlabel struct componentname *cnp &mac.thead; cred Subject credential mount File system mount point label File system label dvp Parent directory vnode dlabel Label associated with dvp vp Newly created vnode vlabel Policy label associated with vp cnp Component name for vp Write out the label for vp to the appropriate extended attribute. If the write succeeds, fill in vlabel with the label, and return 0. Otherwise, return an appropriate error. <function>&mac.mpo;_create_mount</function> void &mac.mpo;_create_mount struct ucred *cred struct mount *mp struct label *mnt struct label *fslabel &mac.thead; cred Subject credential mp Object; file system being mounted mntlabel Policy label to be filled in for mp fslabel Policy label for the file system mp mounts. Fill out the labels on the mount point being created by the passed subject credential. This call will be made when a new file system is mounted. <function>&mac.mpo;_create_root_mount</function> void &mac.mpo;_create_root_mount struct ucred *cred struct mount *mp struct label *mntlabel struct label *fslabel &mac.thead; See . Fill out the labels on the mount point being created by the passed subject credential. This call will be made when the root file system is mounted, after &mac.mpo;_create_mount;. <function>&mac.mpo;_relabel_vnode</function> void &mac.mpo;_relabel_vnode struct ucred *cred struct vnode *vp struct label *vnodelabel struct label *newlabel &mac.thead; cred Subject credential vp vnode to relabel vnodelabel Existing policy label for vp newlabel New, possibly partial label to replace vnodelabel Update the label on the passed vnode given the passed update vnode label and the passed subject credential. <function>&mac.mpo;_setlabel_vnode_extattr</function> int &mac.mpo;_setlabel_vnode_extattr struct ucred *cred struct vnode *vp struct label *vlabel struct label *intlabel &mac.thead; cred Subject credential vp Vnode for which the label is being written vlabel Policy label associated with vp intlabel Label to write out Write out the policy from intlabel to an extended attribute. This is called from vop_stdcreatevnode_ea. <function>&mac.mpo;_update_devfsdirent</function> void &mac.mpo;_update_devfsdirent struct devfs_dirent *devfs_dirent struct label *direntlabel struct vnode *vp struct label *vnodelabel &mac.thead; devfs_dirent Object; devfs directory entry direntlabel Policy label for devfs_dirent to be updated. vp Parent vnode Locked vnodelabel Policy label for vp Update the devfs_dirent label from the passed devfs vnode label. This call will be made when a devfs vnode has been successfully relabeled to commit the label change such that it lasts even if the vnode is recycled. It will also be made when when a symlink is created in devfs, following a call to mac_vnode_create_from_vnode to initialize the vnode label. IPC Object Labeling Event Operations <function>&mac.mpo;_create_mbuf_from_socket</function> void &mac.mpo;_create_mbuf_from_socket struct socket *so struct label *socketlabel struct mbuf *m struct label *mbuflabel &mac.thead; socket Socket Socket locking WIP socketlabel Policy label for socket m Object; mbuf mbuflabel Policy label to fill in for m Set the label on a newly created mbuf header from the passed socket label. This call is made when a new datagram or message is generated by the socket and stored in the passed mbuf. <function>&mac.mpo;_create_pipe</function> void &mac.mpo;_create_pipe struct ucred *cred struct pipe *pipe struct label *pipelabel &mac.thead; cred Subject credential pipe Pipe pipelabel Policy label associated with pipe Set the label on a newly created pipe from the passed subject credential. This call is made when a new pipe is created. <function>&mac.mpo;_create_socket</function> void &mac.mpo;_create_socket struct ucred *cred struct socket *so struct label *socketlabel &mac.thead; cred Subject credential Immutable so Object; socket to label socketlabel Label to fill in for so Set the label on a newly created socket from the passed subject credential. This call is made when a socket is created. <function>&mac.mpo;_create_socket_from_socket</function> void &mac.mpo;_create_socket_from_socket struct socket *oldsocket struct label *oldsocketlabel struct socket *newsocket struct label *newsocketlabel &mac.thead; oldsocket Listening socket oldsocketlabel Policy label associated with oldsocket newsocket New socket newsocketlabel Policy label associated with newsocketlabel Label a socket, newsocket, newly &man.accept.2;ed, based on the &man.listen.2; socket, oldsocket. <function>&mac.mpo;_relabel_pipe</function> void &mac.mpo;_relabel_pipe struct ucred *cred struct pipe *pipe struct label *oldlabel struct label *newlabel &mac.thead; cred Subject credential pipe Pipe oldlabel Current policy label associated with pipe newlabel Policy label update to apply to pipe Apply a new label, newlabel, to pipe. <function>&mac.mpo;_relabel_socket</function> void &mac.mpo;_relabel_socket struct ucred *cred struct socket *so struct label *oldlabel struct label *newlabel &mac.thead; cred Subject credential Immutable so Object; socket oldlabel Current label for so newlabel Label update for so Update the label on a socket from the passed socket label update. <function>&mac.mpo;_set_socket_peer_from_mbuf</function> void &mac.mpo;_set_socket_peer_from_mbuf struct mbuf *mbuf struct label *mbuflabel struct label *oldlabel struct label *newlabel &mac.thead; mbuf First datagram received over socket mbuflabel Label for mbuf oldlabel Current label for the socket newlabel Policy label to be filled out for the socket Set the peer label on a stream socket from the passed mbuf label. This call will be made when the first datagram is received by the stream socket, with the exception of Unix domain sockets. <function>&mac.mpo;_set_socket_peer_from_socket</function> void &mac.mpo;_set_socket_peer_from_socket struct socket *oldsocket struct label *oldsocketlabel struct socket *newsocket struct label *newsocketpeerlabel &mac.thead; oldsocket Local socket oldsocketlabel Policy label for oldsocket newsocket Peer socket newsocketpeerlabel Policy label to fill in for newsocket Set the peer label on a stream UNIX domain socket from the passed remote socket endpoint. This call will be made when the socket pair is connected, and will be made for both endpoints. Network Object Labeling Event Operations <function>&mac.mpo;_create_bpfdesc</function> void &mac.mpo;_create_bpfdesc struct ucred *cred struct bpf_d *bpf_d struct label *bpflabel &mac.thead; cred Subject credential Immutable bpf_d Object; bpf descriptor bpf Policy label to be filled in for bpf_d Set the label on a newly created BPF descriptor from the passed subject credential. This call will be made when a BPF device node is opened by a process with the passed subject credential. <function>&mac.mpo;_create_ifnet</function> void &mac.mpo;_create_ifnet struct ifnet *ifnet struct label - *ifnetlabel + *ifnetlabel &mac.thead; ifnet Network interface ifnetlabel Policy label to fill in for ifnet Set the label on a newly created interface. This call may be made when a new physical interface becomes available to the system, or when a pseudo-interface is instantiated during the boot or as a result of a user action. <function>&mac.mpo;_create_ipq</function> void &mac.mpo;_create_ipq struct mbuf *fragment struct label *fragmentlabel struct ipq *ipq struct label *ipqlabel &mac.thead; fragment First received IP fragment fragmentlabel Policy label for fragment ipq IP reassembly queue to be labeled ipqlabel Policy label to be filled in for ipq Set the label on a newly created IP fragment reassembly queue from the mbuf header of the first received fragment. <function>&mac.mpo;_create_datagram_from_ipq</function> void &mac.mpo;_create_create_datagram_from_ipq struct ipq *ipq struct label *ipqlabel struct mbuf *datagram struct label *datagramlabel &mac.thead; ipq IP reassembly queue ipqlabel Policy label for ipq datagram Datagram to be labeled datagramlabel Policy label to be filled in for datagramlabel Set the label on a newly reassembled IP datagram from the IP fragment reassembly queue from which it was generated. <function>&mac.mpo;_create_fragment</function> void &mac.mpo;_create_fragment struct mbuf *datagram struct label *datagramlabel struct mbuf *fragment struct label *fragmentlabel &mac.thead; datagram Datagram datagramlabel Policy label for datagram fragment Fragment to be labeled fragmentlabel Policy label to be filled in for datagram Set the label on the mbuf header of a newly created IP fragment from the label on the mbuf header of the datagram it was generate from. <function>&mac.mpo;_create_mbuf_from_mbuf</function> void &mac.mpo;_create_mbuf_from_mbuf struct mbuf *oldmbuf struct label *oldmbuflabel struct mbuf *newmbuf struct label *newmbuflabel &mac.thead; oldmbuf Existing (source) mbuf oldmbuflabel Policy label for oldmbuf newmbuf New mbuf to be labeled newmbuflabel Policy label to be filled in for newmbuf Set the label on the mbuf header of a newly created datagram from the mbuf header of an existing datagram. This call may be made in a number of situations, including when an mbuf is re-allocated for alignment purposes. <function>&mac.mpo;_create_mbuf_linklayer</function> void &mac.mpo;_create_mbuf_linklayer struct ifnet *ifnet struct label *ifnetlabel struct mbuf *mbuf struct label *mbuflabel &mac.thead; ifnet Network interface ifnetlabel Policy label for ifnet mbuf mbuf header for new datagram mbuflabel Policy label to be filled in for mbuf Set the label on the mbuf header of a newly created datagram generated for the purposes of a link layer response for the passed interface. This call may be made in a number of situations, including for ARP or ND6 responses in the IPv4 and IPv6 stacks. <function>&mac.mpo;_create_mbuf_from_bpfdesc</function> void &mac.mpo;_create_mbuf_from_bpfdesc struct bpf_d *bpf_d struct label *bpflabel struct mbuf *mbuf struct label *mbuflabel &mac.thead; bpf_d BPF descriptor bpflabel Policy label for bpflabel mbuf New mbuf to be labeled mbuflabel Policy label to fill in for mbuf Set the label on the mbuf header of a newly created datagram generated using the passed BPF descriptor. This call is made when a write is performed to the BPF device associated with the passed BPF descriptor. <function>&mac.mpo;_create_mbuf_from_ifnet</function> void &mac.mpo;_create_mbuf_from_ifnet struct ifnet *ifnet struct label *ifnetlabel struct mbuf *mbuf struct label *mbuflabel &mac.thead; ifnet Network interface ifnetlabel Policy label for ifnetlabel mbuf mbuf header for new datagram mbuflabel Policy label to be filled in for mbuf Set the label on the mbuf header of a newly created datagram generated from the passed network interface. <function>&mac.mpo;_create_mbuf_multicast_encap</function> void &mac.mpo;_create_mbuf_multicast_encap struct mbuf *oldmbuf struct label *oldmbuflabel struct ifnet *ifnet struct label *ifnetlabel struct mbuf *newmbuf struct label *newmbuflabel &mac.thead; oldmbuf mbuf header for existing datagram oldmbuflabel Policy label for oldmbuf ifnet Network interface ifnetlabel Policy label for ifnet newmbuf mbuf header to be labeled for new datagram newmbuflabel Policy label to be filled in for newmbuf Set the label on the mbuf header of a newly created datagram generated from the existing passed datagram when it is processed by the passed multicast encapsulation interface. This call is made when an mbuf is to be delivered using the virtual interface. <function>&mac.mpo;_create_mbuf_netlayer</function> void &mac.mpo;_create_mbuf_netlayer struct mbuf *oldmbuf struct label *oldmbuflabel struct mbuf *newmbuf struct label *newmbuflabel &mac.thead; oldmbuf Received datagram oldmbuflabel Policy label for oldmbuf newmbuf Newly created datagram newmbuflabel Policy label for newmbuf Set the label on the mbuf header of a newly created datagram generated by the IP stack in response to an existing received datagram (oldmbuf). This call may be made in a number of situations, including when responding to ICMP request datagrams. <function>&mac.mpo;_fragment_match</function> int &mac.mpo;_fragment_match struct mbuf *fragment struct label *fragmentlabel struct ipq *ipq struct label *ipqlabel &mac.thead; fragment IP datagram fragment fragmentlabel Policy label for fragment ipq IP fragment reassembly queue ipqlabel Policy label for ipq Determine whether an mbuf header containing an IP datagram (fragment) fragment matches the label of the passed IP fragment reassembly queue (ipq). Return (1) for a successful match, or (0) for no match. This call is made when the IP stack attempts to find an existing fragment reassembly queue for a newly received fragment; if this fails, a new fragment reassembly queue may be instantiated for the fragment. Policies may use this entry point to prevent the reassembly of otherwise matching IP fragments if policy does not permit them to be reassembled based on the label or other information. <function>&mac.mpo;_relabel_ifnet</function> void &mac.mpo;_relabel_ifnet struct ucred *cred struct ifnet *ifnet struct label *ifnetlabel struct label *newlabel &mac.thead; cred Subject credential ifnet Object; Network interface ifnetlabel Policy label for ifnet newlabel Label update to apply to ifnet Update the label of network interface, ifnet, based on the passed update label, newlabel, and the passed subject credential, cred. <function>&mac.mpo;_update_ipq</function> void &mac.mpo;_update_ipq struct mbuf *fragment struct label *fragmentlabel struct ipq *ipq struct label *ipqlabel &mac.thead; mbuf IP fragment mbuflabel Policy label for mbuf ipq IP fragment reassembly queue ipqlabel Policy label to be updated for ipq Update the label on an IP fragment reassembly queue (ipq) based on the acceptance of the passed IP fragment mbuf header (mbuf). Process Labeling Event Operations <function>&mac.mpo;_create_cred</function> void &mac.mpo;_create_cred struct ucred *parent_cred struct ucred *child_cred &mac.thead; parent_cred Parent subject credential child_cred Child subject credential Set the label of a newly created subject credential from the passed subject credential. This call will be made when &man.crcopy.9; is invoked on a newly created struct ucred. This call should not be confused with a process forking or creation event. <function>&mac.mpo;_execve_transition</function> void &mac.mpo;_execve_transition struct ucred *old struct ucred *new struct vnode *vp struct label *vnodelabel &mac.thead; old Existing subject credential Immutable new New subject credential to be labeled vp File to execute Locked vnodelabel Policy label for vp Update the label of a newly created subject credential (new) from the passed existing subject credential (old) based on a label transition caused by executing the passed vnode (vp). This call occurs when a process executes the passed vnode and one of the policies returns a success from the mpo_execve_will_transition entry point. Policies may choose to implement this call simply by invoking mpo_create_cred and passing the two subject credentials so as not to implement a transitioning event. Policies should not leave this entry point unimplemented if they implement mpo_create_cred, even if they do not implement mpo_execve_will_transition. <function>&mac.mpo;_execve_will_transition</function> int &mac.mpo;_execve_will_transition struct ucred *old struct vnode *vp struct label *vnodelabel &mac.thead; old Subject credential prior to &man.execve.2; Immutable vp File to execute vnodelabel Policy label for vp Determine whether the policy will want to perform a transition event as a result of the execution of the passed vnode by the passed subject credential. Return 1 if a transition is required, 0 if not. Even if a policy returns 0, it should behave correctly in the presence of an unexpected invocation of mpo_execve_transition, as that call may happen as a result of another policy requesting a transition. <function>&mac.mpo;_create_proc0</function> void &mac.mpo;_create_proc0 struct ucred *cred &mac.thead; cred Subject credential to be filled in Create the subject credential of process 0, the parent of all kernel processes. <function>&mac.mpo;_create_proc1</function> void &mac.mpo;_create_proc1 struct ucred *cred &mac.thead; cred Subject credential to be filled in Create the subject credential of process 1, the parent of all user processes. <function>&mac.mpo;_relabel_cred</function> void &mac.mpo;_relabel_cred struct ucred *cred struct label *newlabel &mac.thead; cred Subject credential newlabel Label update to apply to cred Update the label on a subject credential from the passed update label. Access Control Checks Access control entry points permit policy modules to influence access control decisions made by the kernel. Generally, although not always, arguments to an access control entry point will include one or more authorizing credentials, information (possibly including a label) for any other objects involved in the operation. An access control entry point may return 0 to permit the operation, or an &man.errno.2; error value. The results of invoking the entry point across various registered policy modules will be composed as follows: if all modules permit the operation to succeed, success will be returned. If one or modules returns a failure, a failure will be returned. If more than one module returns a failure, the errno value to return to the user will be selected using the following precedence, implemented by the error_select() function in kern_mac.c: Most precedence EDEADLK EINVAL ESRCH EACCES Least precedence EPERM If none of the error values returned by all modules are listed in the precedence chart then an arbitrarily selected value from the set will be returned. In general, the rules provide precedence to errors in the following order: kernel failures, invalid arguments, object not present, access not permitted, other. <function>&mac.mpo;_check_bpfdesc_receive</function> int &mac.mpo;_check_bpfdesc_receive struct bpf_d *bpf_d struct label *bpflabel struct ifnet *ifnet struct label *ifnetlabel &mac.thead; bpf_d Subject; BPF descriptor bpflabel Policy label for bpf_d ifnet Object; network interface ifnetlabel Policy label for ifnet Determine whether the MAC framework should permit datagrams from the passed interface to be delivered to the buffers of the passed BPF descriptor. Return (0) for success, or an errno value for failure Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. <function>&mac.mpo;_check_kenv_dump</function> int &mac.mpo;_check_kenv_dump struct ucred *cred &mac.thead; cred Subject credential Determine whether the subject should be allowed to retrieve the kernel environment (see &man.kenv.2;). <function>&mac.mpo;_check_kenv_get</function> int &mac.mpo;_check_kenv_get struct ucred *cred char *name &mac.thead; cred Subject credential name Kernel environment variable name Determine whether the subject should be allowed to retrieve the value of the specified kernel environment variable. <function>&mac.mpo;_check_kenv_set</function> int &mac.mpo;_check_kenv_set struct ucred *cred char *name &mac.thead; cred Subject credential name Kernel environment variable name Determine whether the subject should be allowed to set the specified kernel environment variable. <function>&mac.mpo;_check_kenv_unset</function> int &mac.mpo;_check_kenv_unset struct ucred *cred char *name &mac.thead; cred Subject credential name Kernel environment variable name Determine whether the subject should be allowed to unset the specified kernel environment variable. <function>&mac.mpo;_check_kld_load</function> int &mac.mpo;_check_kld_load struct ucred *cred struct vnode *vp struct label *vlabel &mac.thead; cred Subject credential vp Kernel module vnode vlabel Label associated with vp Determine whether the subject should be allowed to load the specified module file. <function>&mac.mpo;_check_kld_stat</function> int &mac.mpo;_check_kld_stat struct ucred *cred &mac.thead; cred Subject credential Determine whether the subject should be allowed to retrieve a list of loaded kernel module files and associated statistics. <function>&mac.mpo;_check_kld_unload</function> int &mac.mpo;_check_kld_unload struct ucred *cred &mac.thead; cred Subject credential Determine whether the subject should be allowed to unload a kernel module. <function>&mac.mpo;_check_pipe_ioctl</function> int &mac.mpo;_check_pipe_ioctl struct ucred *cred struct pipe *pipe struct label *pipelabel unsigned long cmd void *data &mac.thead; cred Subject credential pipe Pipe pipelabel Policy label associated with pipe cmd &man.ioctl.2; command data &man.ioctl.2; data Determine whether the subject should be allowed to make the specified &man.ioctl.2; call. <function>&mac.mpo;_check_pipe_poll</function> int &mac.mpo;_check_pipe_poll struct ucred *cred struct pipe *pipe struct label *pipelabel &mac.thead; cred Subject credential pipe Pipe pipelabel Policy label associated with pipe Determine whether the subject should be allowed to poll pipe. <function>&mac.mpo;_check_pipe_read</function> int &mac.mpo;_check_pipe_read struct ucred *cred struct pipe *pipe struct label *pipelabel &mac.thead; cred Subject credential pipe Pipe pipelabel Policy label associated with pipe Determine whether the subject should be allowed read access to pipe. <function>&mac.mpo;_check_pipe_relabel</function> int &mac.mpo;_check_pipe_relabel struct ucred *cred struct pipe *pipe struct label *pipelabel struct label *newlabel &mac.thead; cred Subject credential pipe Pipe pipelabel Current policy label associated with pipe newlabel Label update to pipelabel Determine whether the subject should be allowed to relabel pipe. <function>&mac.mpo;_check_pipe_stat</function> int &mac.mpo;_check_pipe_stat struct ucred *cred struct pipe *pipe struct label *pipelabel &mac.thead; cred Subject credential pipe Pipe pipelabel Policy label associated with pipe Determine whether the subject should be allowed to retrieve statistics related to pipe. <function>&mac.mpo;_check_pipe_write</function> int &mac.mpo;_check_pipe_write struct ucred *cred struct pipe *pipe struct label *pipelabel &mac.thead; cred Subject credential pipe Pipe pipelabel Policy label associated with pipe Determine whether the subject should be allowed to write to pipe. <function>&mac.mpo;_check_socket_bind</function> int &mac.mpo;_check_socket_bind struct ucred *cred struct socket *socket struct label *socketlabel struct sockaddr *sockaddr &mac.thead; cred Subject credential socket Socket to be bound socketlabel Policy label for socket sockaddr Address of socket <function>&mac.mpo;_check_socket_connect</function> int &mac.mpo;_check_socket_connect struct ucred *cred struct socket *socket struct label *socketlabel struct sockaddr *sockaddr &mac.thead; cred Subject credential socket Socket to be connected socketlabel Policy label for socket sockaddr Address of socket Determine whether the subject credential (cred) can connect the passed socket (socket) to the passed socket address (sockaddr). Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege. <function>&mac.mpo;_check_socket_receive</function> int &mac.mpo;_check_socket_receive struct ucred *cred struct socket *so struct label *socketlabel &mac.thead; cred Subject credential so Socket socketlabel Policy label associated with so Determine whether the subject should be allowed to receive information from the socket so. <function>&mac.mpo;_check_socket_send</function> int &mac.mpo;_check_socket_send struct ucred *cred struct socket *so struct label *socketlabel &mac.thead; cred Subject credential so Socket socketlabel Policy label associated with so Determine whether the subject should be allowed to send information across the socket so. <function>&mac.mpo;_check_cred_visible</function> int &mac.mpo;_check_cred_visible struct ucred *u1 struct ucred *u2 &mac.thead; u1 Subject credential u2 Object credential Determine whether the subject credential u1 can see other subjects with the passed subject credential u2. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. This call may be made in a number of situations, including inter-process status sysctls used by ps, and in procfs lookups. <function>&mac.mpo;_check_socket_visible</function> int &mac.mpo;_check_socket_visible struct ucred *cred struct socket *socket struct label *socketlabel &mac.thead; cred Subject credential socket Object; socket socketlabel Policy label for socket <function>&mac.mpo;_check_ifnet_relabel</function> int &mac.mpo;_check_ifnet_relabel struct ucred *cred struct ifnet *ifnet struct label *ifnetlabel struct label *newlabel &mac.thead; cred Subject credential ifnet Object; network interface ifnetlabel Existing policy label for ifnet newlabel Policy label update to later be applied to ifnet Determine whether the subject credential can relabel the passed network interface to the passed label update. <function>&mac.mpo;_check_socket_relabel</function> int &mac.mpo;_check_socket_relabel struct ucred *cred struct socket *socket struct label *socketlabel struct label *newlabel &mac.thead; cred Subject credential socket Object; socket socketlabel Existing policy label for socket newlabel Label update to later be applied to socketlabel Determine whether the subject credential can relabel the passed socket to the passed label update. <function>&mac.mpo;_check_cred_relabel</function> int &mac.mpo;_check_cred_relabel struct ucred *cred struct label *newlabel &mac.thead; cred Subject credential newlabel Label update to later be applied to cred Determine whether the subject credential can relabel itself to the passed label update. <function>&mac.mpo;_check_vnode_relabel</function> int &mac.mpo;_check_vnode_relabel struct ucred *cred struct vnode *vp struct label *vnodelabel struct label *newlabel &mac.thead; cred Subject credential Immutable vp Object; vnode Locked vnodelabel Existing policy label for vp newlabel Policy label update to later be applied to vp Determine whether the subject credential can relabel the passed vnode to the passed label update. <function>&mac.mpo;_check_mount_stat</function> int &mac.mpo;_check_mount_stat struct ucred *cred struct mount *mp struct label *mountlabel &mac.thead; cred Subject credential mp Object; file system mount mountlabel Policy label for mp Determine whether the subject credential can see the results of a statfs performed on the file system. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. This call may be made in a number of situations, including during invocations of &man.statfs.2; and related calls, as well as to determine what file systems to exclude from listings of file systems, such as when &man.getfsstat.2; is invoked. <function>&mac.mpo;_check_proc_debug</function> int &mac.mpo;_check_proc_debug struct ucred *cred struct proc *proc &mac.thead; cred Subject credential Immutable proc Object; process Determine whether the subject credential can debug the passed process. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to hide visibility of the target. This call may be made in a number of situations, including use of the &man.ptrace.2; and &man.ktrace.2; APIs, as well as for some types of procfs operations. <function>&mac.mpo;_check_vnode_access</function> int &mac.mpo;_check_vnode_access struct ucred *cred struct vnode *vp struct label *label int flags &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp flags &man.access.2; flags Determine how invocations of &man.access.2; and related calls by the subject credential should return when performed on the passed vnode using the passed access flags. This should generally be implemented using the same semantics used in &mac.mpo;_check_vnode_open. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatches or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_chdir</function> int &mac.mpo;_check_vnode_chdir struct ucred *cred struct vnode *dvp struct label *dlabel &mac.thead; cred Subject credential dvp Object; vnode to &man.chdir.2; into dlabel Policy label for dvp Determine whether the subject credential can change the process working directory to the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_chroot</function> int &mac.mpo;_check_vnode_chroot struct ucred *cred struct vnode *dvp struct label *dlabel &mac.thead; cred Subject credential dvp Directory vnode dlabel Policy label associated with dvp Determine whether the subject should be allowed to &man.chroot.2; into the specified directory (dvp). <function>&mac.mpo;_check_vnode_create</function> int &mac.mpo;_check_vnode_create struct ucred *cred struct vnode *dvp struct label *dlabel struct componentname *cnp struct vattr *vap &mac.thead; cred Subject credential dvp Object; vnode dlabel Policy label for dvp cnp Component name for dvp vap vnode attributes for vap Determine whether the subject credential can create a vnode with the passed parent directory, passed name information, and passed attribute information. Return 0 for success, or an errno value for failure. Suggested failure: EACCES. for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including as a result of calls to &man.open.2; with O_CREAT, &man.mknod.2;, &man.mkfifo.2;, and others. <function>&mac.mpo;_check_vnode_delete</function> int &mac.mpo;_check_vnode_delete struct ucred *cred struct vnode *dvp struct label *dlabel struct vnode *vp void *label struct componentname *cnp &mac.thead; cred Subject credential dvp Parent directory vnode dlabel Policy label for dvp vp Object; vnode to delete label Policy label for vp cnp Component name for vp Determine whether the subject credential can delete a vnode from the passed parent directory and passed name information. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including as a result of calls to &man.unlink.2; and &man.rmdir.2;. Policies implementing this entry point should also implement mpo_check_rename_to to authorize deletion of objects as a result of being the target of a rename. <function>&mac.mpo;_check_vnode_deleteacl</function> int &mac.mpo;_check_vnode_deleteacl struct ucred *cred struct vnode *vp struct label *label acl_type_t type &mac.thead; cred Subject credential Immutable vp Object; vnode Locked label Policy label for vp type ACL type Determine whether the subject credential can delete the ACL of passed type from the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_exec</function> int &mac.mpo;_check_vnode_exec struct ucred *cred struct vnode *vp struct label *label &mac.thead; cred Subject credential vp Object; vnode to execute label Policy label for vp Determine whether the subject credential can execute the passed vnode. Determination of execute privilege is made separately from decisions about any transitioning event. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_getacl</function> int &mac.mpo;_check_vnode_getacl struct ucred *cred struct vnode *vp struct label *label acl_type_t type &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp type ACL type Determine whether the subject credential can retrieve the ACL of passed type from the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_getextattr</function> int &mac.mpo;_check_vnode_getextattr struct ucred *cred struct vnode *vp struct label *label int attrnamespace const char *name struct uio *uio &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp attrnamespace Extended attribute namespace name Extended attribute name uio I/O structure pointer; see &man.uio.9; Determine whether the subject credential can retrieve the extended attribute with the passed namespace and name from the passed vnode. Policies implementing labeling using extended attributes may be interested in special handling of operations on those extended attributes. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_link</function> int &mac.mpo;_check_vnode_link struct ucred *cred struct vnode *dvp struct label *dlabel struct vnode *vp struct label *label struct componentname *cnp &mac.thead; cred Subject credential dvp Directory vnode dlabel Policy label associated with dvp vp Link destination vnode label Policy label associated with vp cnp Component name for the link being created Determine whether the subject should be allowed to create a link to the vnode vp with the name specified by cnp. <function>&mac.mpo;_check_vnode_mmap</function> int &mac.mpo;_check_vnode_mmap struct ucred *cred struct vnode *vp struct label *label int prot &mac.thead; cred Subject credential vp Vnode to map label Policy label associated with vp prot Mmap protections (see &man.mmap.2;) Determine whether the subject should be allowed to map the vnode vp with the protections specified in prot. <function>&mac.mpo;_check_vnode_mmap_downgrade</function> void &mac.mpo;_check_vnode_mmap_downgrade struct ucred *cred struct vnode *vp struct label *label int *prot &mac.thead; cred See . vp label prot Mmap protections to be downgraded Downgrade the mmap protections based on the subject and object labels. <function>&mac.mpo;_check_vnode_mprotect</function> int &mac.mpo;_check_vnode_mprotect struct ucred *cred struct vnode *vp struct label *label int prot &mac.thead; cred Subject credential vp Mapped vnode prot Memory protections Determine whether the subject should be allowed to set the specified memory protections on memory mapped from the vnode vp. <function>&mac.mpo;_check_vnode_poll</function> int &mac.mpo;_check_vnode_poll struct ucred *active_cred struct ucred *file_cred struct vnode *vp struct label *label &mac.thead; active_cred Subject credential file_cred Credential associated with the struct file vp Polled vnode label Policy label associated with vp Determine whether the subject should be allowed to poll the vnode vp. <function>&mac.mpo;_check_vnode_rename_from</function> int &mac.mpo;_vnode_rename_from struct ucred *cred struct vnode *dvp struct label *dlabel struct vnode *vp struct label *label struct componentname *cnp &mac.thead; cred Subject credential dvp Directory vnode dlabel Policy label associated with dvp vp Vnode to be renamed label Policy label associated with vp cnp Component name for vp Determine whether the subject should be allowed to rename the vnode vp to something else. <function>&mac.mpo;_check_vnode_rename_to</function> int &mac.mpo;_check_vnode_rename_to struct ucred *cred struct vnode *dvp struct label *dlabel struct vnode *vp struct label *label int samedir struct componentname *cnp &mac.thead; cred Subject credential dvp Directory vnode dlabel Policy label associated with dvp vp Overwritten vnode label Policy label associated with vp samedir Boolean; 1 if the source and destination directories are the same cnp Destination component name Determine whether the subject should be allowed to rename to the vnode vp, into the directory dvp, or to the name represented by cnp. If there is no existing file to overwrite, vp and label will be NULL. <function>&mac.mpo;_check_socket_listen</function> int &mac.mpo;_check_socket_listen struct ucred *cred struct socket *socket struct label *socketlabel &mac.thead; cred Subject credential socket Object; socket socketlabel Policy label for socket Determine whether the subject credential can listen on the passed socket. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_lookup</function> int &mac.mpo;_check_vnode_lookup struct ucred *cred struct vnode *dvp struct label *dlabel struct componentname *cnp &mac.thead; cred Subject credential dvp Object; vnode dlabel Policy label for dvp cnp Component name being looked up Determine whether the subject credential can perform a lookup in the passed directory vnode for the passed name. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_open</function> int &mac.mpo;_check_vnode_open struct ucred *cred struct vnode *vp struct label *label int acc_mode &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp acc_mode &man.open.2; access mode Determine whether the subject credential can perform an open operation on the passed vnode with the passed access mode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_readdir</function> int &mac.mpo;_check_vnode_readdir struct ucred *cred struct vnode *dvp struct label *dlabel &mac.thead; cred Subject credential dvp Object; directory vnode dlabel Policy label for dvp Determine whether the subject credential can perform a readdir operation on the passed directory vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_readlink</function> int &mac.mpo;_check_vnode_readlink struct ucred *cred struct vnode *vp struct label *label &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp Determine whether the subject credential can perform a readlink operation on the passed symlink vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. This call may be made in a number of situations, including an explicit readlink call by the user process, or as a result of an implicit readlink during a name lookup by the process. <function>&mac.mpo;_check_vnode_revoke</function> int &mac.mpo;_check_vnode_revoke struct ucred *cred struct vnode *vp struct label *label &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp Determine whether the subject credential can revoke access to the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_setacl</function> int &mac.mpo;_check_vnode_setacl struct ucred *cred struct vnode *vp struct label *label acl_type_t type struct acl *acl &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp type ACL type acl ACL Determine whether the subject credential can set the passed ACL of passed type on the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_setextattr</function> int &mac.mpo;_check_vnode_setextattr struct ucred *cred struct vnode *vp struct label *label int attrnamespace const char *name struct uio *uio &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp attrnamespace Extended attribute namespace name Extended attribute name uio I/O structure pointer; see &man.uio.9; Determine whether the subject credential can set the extended attribute of passed name and passed namespace on the passed vnode. Policies implementing security labels backed into extended attributes may want to provide additional protections for those attributes. Additionally, policies should avoid making decisions based on the data referenced from uio, as there is a potential race condition between this check and the actual operation. The uio may also be NULL if a delete operation is being performed. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_setflags</function> int &mac.mpo;_check_vnode_setflags struct ucred *cred struct vnode *vp struct label *label u_long flags &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp flags File flags; see &man.chflags.2; Determine whether the subject credential can set the passed flags on the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_setmode</function> int &mac.mpo;_check_vnode_setmode struct ucred *cred struct vnode *vp struct label *label mode_t mode &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp mode File mode; see &man.chmod.2; Determine whether the subject credential can set the passed mode on the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_setowner</function> int &mac.mpo;_check_vnode_setowner struct ucred *cred struct vnode *vp struct label *label uid_t uid gid_t gid &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp uid User ID gid Group ID Determine whether the subject credential can set the passed uid and passed gid as file uid and file gid on the passed vnode. The IDs may be set to (-1) to request no update. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_vnode_setutimes</function> int &mac.mpo;_check_vnode_setutimes struct ucred *cred struct vnode *vp struct label *label struct timespec atime struct timespec mtime &mac.thead; cred Subject credential vp Object; vp label Policy label for vp atime Access time; see &man.utimes.2; mtime Modification time; see &man.utimes.2; Determine whether the subject credential can set the passed access timestamps on the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_proc_sched</function> int &mac.mpo;_check_proc_sched struct ucred *ucred struct proc *proc &mac.thead; cred Subject credential proc Object; process Determine whether the subject credential can change the scheduling parameters of the passed process. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. See &man.setpriority.2; for more information. <function>&mac.mpo;_check_proc_signal</function> int &mac.mpo;_check_proc_signal struct ucred *cred struct proc *proc int signal &mac.thead; cred Subject credential proc Object; process signal Signal; see &man.kill.2; Determine whether the subject credential can deliver the passed signal to the passed process. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, EPERM for lack of privilege, or ESRCH to limit visibility. <function>&mac.mpo;_check_vnode_stat</function> int &mac.mpo;_check_vnode_stat struct ucred *cred struct vnode *vp struct label *label &mac.thead; cred Subject credential vp Object; vnode label Policy label for vp Determine whether the subject credential can stat the passed vnode. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. See &man.stat.2; for more information. <function>&mac.mpo;_check_ifnet_transmit</function> int &mac.mpo;_check_ifnet_transmit struct ucred *cred struct ifnet *ifnet struct label *ifnetlabel struct mbuf *mbuf struct label *mbuflabel &mac.thead; cred Subject credential ifnet Network interface ifnetlabel Policy label for ifnet mbuf Object; mbuf to be sent mbuflabel Policy label for mbuf Determine whether the network interface can transmit the passed mbuf. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_socket_deliver</function> int &mac.mpo;_check_socket_deliver struct ucred *cred struct ifnet *ifnet struct label *ifnetlabel struct mbuf *mbuf struct label *mbuflabel &mac.thead; cred Subject credential ifnet Network interface ifnetlabel Policy label for ifnet mbuf Object; mbuf to be delivered mbuflabel Policy label for mbuf Determine whether the socket may receive the datagram stored in the passed mbuf header. Return 0 for success, or an errno value for failure. Suggested failures: EACCES for label mismatch, or EPERM for lack of privilege. <function>&mac.mpo;_check_socket_visible</function> int &mac.mpo;_check_socket_visible struct ucred *cred struct socket *so struct label *socketlabel &mac.thead; cred Subject credential Immutable so Object; socket socketlabel Policy label for so Determine whether the subject credential cred can "see" the passed socket (socket) using system monitoring functions, such as those employed by &man.netstat.8; and &man.sockstat.1;. Return 0 for success, or an errno value for failure. Suggested failure: EACCES for label mismatches, EPERM for lack of privilege, or ESRCH to hide visibility. <function>&mac.mpo;_check_system_acct</function> int &mac.mpo;_check_system_acct struct ucred *ucred struct vnode *vp struct label *vlabel &mac.thead; ucred Subject credential vp Accounting file; &man.acct.5; vlabel Label associated with vp Determine whether the subject should be allowed to enable accounting, based on its label and the label of the accounting log file. <function>&mac.mpo;_check_system_nfsd</function> int &mac.mpo;_check_system_nfsd struct ucred *cred &mac.thead; cred Subject credential Determine whether the subject should be allowed to call &man.nfssvc.2;. <function>&mac.mpo;_check_system_reboot</function> int &mac.mpo;_check_system_reboot struct ucred *cred int howto &mac.thead; cred Subject credential howto howto parameter from &man.reboot.2; Determine whether the subject should be allowed to reboot the system in the specified manner. <function>&mac.mpo;_check_system_settime</function> int &mac.mpo;_check_system_settime struct ucred *cred &mac.thead; cred Subject credential Determine whether the user should be allowed to set the system clock. <function>&mac.mpo;_check_system_swapon</function> int &mac.mpo;_check_system_swapon struct ucred *cred struct vnode *vp struct label *vlabel &mac.thead; cred Subject credential vp Swap device vlabel Label associated with vp Determine whether the subject should be allowed to add vp as a swap device. <function>&mac.mpo;_check_system_sysctl</function> int &mac.mpo;_check_system_sysctl struct ucred *cred int *name u_int *namelen void *old size_t *oldlenp int inkernel void *new size_t newlen &mac.thead; cred Subject credential name See &man.sysctl.3; namelen old oldlenp inkernel Boolean; 1 if called from kernel new See &man.sysctl.3; newlen Determine whether the subject should be allowed to make the specified &man.sysctl.3; transaction. Label Management Calls Relabel events occur when a user process has requested that the label on an object be modified. A two-phase update occurs: first, an access control check will be performed to determine if the update is both valid and permitted, and then the update itself is performed via a separate entry point. Relabel entry points typically accept the object, object label reference, and an update label submitted by the process. Memory allocation during relabel is discouraged, as relabel calls are not permitted to fail (failure should be reported earlier in the relabel check). Userland Architecture The TrustedBSD MAC Framework includes a number of policy-agnostic elements, including MAC library interfaces for abstractly managing labels, modifications to the system credential management and login libraries to support the assignment of MAC labels to users, and a set of tools to monitor and modify labels on processes, files, and network interfaces. More details on the user architecture will be added to this section in the near future. APIs for Policy-Agnostic Label Management The TrustedBSD MAC Framework provides a number of library and system calls permitting applications to manage MAC labels on objects using a policy-agnostic interface. This permits applications to manipulate labels for a variety of policies without being written to support specific policies. These interfaces are used by general-purpose tools such as &man.ifconfig.8;, &man.ls.1; and &man.ps.1; to view labels on network interfaces, files, and processes. The APIs also support MAC management tools including &man.getfmac.8;, &man.getpmac.8;, &man.setfmac.8;, &man.setfsmac.8;, and &man.setpmac.8;. The MAC APIs are documented in &man.mac.3;. Applications handle MAC labels in two forms: an internalized form used to return and set labels on processes and objects (mac_t), and externalized form based on C strings appropriate for storage in configuration files, display to the user, or input from the user. Each MAC label contains a number of elements, each consisting of a name and value pair. Policy modules in the kernel bind to specific names and interpret the values in policy-specific ways. In the externalized string form, labels are represented by a comma-delimited list of name and value pairs separated by the / character. Labels may be directly converted to and from text using provided APIs; when retrieving labels from the kernel, internalized label storage must first be prepared for the desired label element set. Typically, this is done in one of two ways: using &man.mac.prepare.3; and an arbitrary list of desired label elements, or one of the variants of the call that loads a default element set from the &man.mac.conf.5; configuration file. Per-object defaults permit application writers to usefully display labels associated with objects without being aware of the policies present in the system. Currently, direct manipulation of label elements other than by conversion to a text string, string editing, and conversion back to an internalized label is not supported by the MAC library. Such interfaces may be added in the future if they prove necessary for application writers. Binding of Labels to Users The standard user context management interface, &man.setusercontext.3;, has been modified to retrieve MAC labels associated with a user's class from &man.login.conf.5;. These labels are then set along with other user context when either LOGIN_SETALL is specified, or when LOGIN_SETMAC is explicitly specified. It is expected that, in a future version of FreeBSD, the MAC label database will be separated from the login.conf user class abstraction, and be maintained in a separate database. However, the &man.setusercontext.3; API should remain the same following such a change. Conclusion The TrustedBSD MAC framework permits kernel modules to augment the system security policy in a highly integrated manner. They may do this based on existing object properties, or based on label data that is maintained with the assistance of the MAC framework. The framework is sufficiently flexible to implement a variety of policy types, including information flow security policies such as MLS and Biba, as well as policies based on existing BSD credentials or file protections. Policy authors may wish to consult this documentation as well as existing security modules when implementing a new security service. diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 1fd60b06c9..c62e3a8338 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -1,2692 +1,2692 @@ SGML Markup This chapter describes the two markup languages you will encounter when you contribute to the FreeBSD documentation project. Each section describes the markup language, and details the markup that you are likely to want to use, or that is already in use. These markup languages contain a large number of elements, and it can be confusing sometimes to know which element to use for a particular situation. This section goes through the elements you are most likely to need, and gives examples of how you would use them. This is not an exhaustive list of elements, since that would just reiterate the documentation for each language. The aim of this section is to list those elements more likely to be useful to you. If you have a question about how best to markup a particular piece of content, please post it to the &a.doc;. Inline vs. block In the remainder of this document, when describing elements, inline means that the element can occur within a block element, and does not cause a line break. A block element, by comparison, will cause a line break (and other processing) when it is encountered. HTML HTML, the HyperText Markup Language, is the markup language of choice on the World Wide Web. More information can be found at <URL:>. HTML is used to markup pages on the FreeBSD web site. It should not (generally) be used to mark up other documentation, since DocBook offers a far richer set of elements to choose from. Consequently, you will normally only encounter HTML pages if you are writing for the web site. HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the latest, 4.0 (available in both strict and loose variants). The HTML DTDs are available from the ports collection in the textproc/html port. They are automatically installed as part of the textproc/docproj port. Formal Public Identifier (FPI) There are a number of HTML FPIs, depending upon the version (also known as the level) of HTML that you want to declare your document to be compliant with. The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0. PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Sectional elements An HTML document is normally split into two sections. The first section, called the head, contains meta-information about the document, such as its title, the name of the author, the parent document, and so on. The second section, the body, contains the content that will be displayed to the user. These sections are indicated with head and body elements respectively. These elements are contained within the top-level html element. Normal HTML document structure <html> <head> <title>The document's title</title> </head> <body> … </body> </html> Block elements Headings HTML allows you to denote headings in your document, at up to six different levels. The largest and most prominent heading is h1, then h2, continuing down to h6. The element's content is the text of the heading. <sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc. Use: First section

This is the heading for the first section

This is the heading for the first sub-section

This is the heading for the second section

]]> Generally, an HTML page should have one first level heading (h1). This can contain many second level headings (h2), which can in turn contain many third level headings. Each hn element should have the same element, but one further up the hierarchy, preceding it. Leaving gaps in the numbering is to be avoided. Bad ordering of <sgmltag>h<replaceable>n</replaceable></sgmltag> elements Use: First section

Sub-section

]]> Paragraphs HTML supports a single paragraph element, p. <sgmltag>p</sgmltag> Use: This is a paragraph. It can contain just about any other element.

]]> Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. <sgmltag>blockquote</sgmltag> Use: A small excerpt from the US Constitution:

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Lists You can present the user with three types of lists, ordered, unordered, and definition. Typically, each entry in an ordered list will be numbered, while each entry in an unordered list will be preceded by a bullet point. Definition lists are composed of two sections for each entry. The first section is the term being defined, and the second section is the definition of the term. Ordered lists are indicated by the ol element, unordered lists by the ul element, and definition lists by the dl element. Ordered and unordered lists contain listitems, indicated by the li element. A listitem can contain textual content, or it may be further wrapped in one or more p elements. Definition lists contain definition terms (dt) and definition descriptions (dd). A definition term can only contain inline elements. A definition description can contain other block elements. <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag> Use: An unordered list. Listitems will probably be preceded by bullets.

  • First item
  • Second item
  • Third item

An ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be numbered.

  1. This is the first item. It only has one paragraph.

  2. This is the first paragraph of the second item.

    This is the second paragraph of the second item.

  3. This is the first and only paragraph of the third item.

]]> Definition lists with <sgmltag>dl</sgmltag> Use:
Term 1

Paragraph 1 of definition 1.

Paragraph 2 of definition 1.

Term 2

Paragraph 1 of definition 2.

Term 3
Paragraph 1 of definition 3. Note that the <p> element is not required in the single paragraph case.
]]> Pre-formatted text You can indicate that text should be shown to the user exactly as it is in the file. Typically, this means that the text is shown in a fixed font, multiple spaces are not merged into one, and line breaks in the text are significant. In order to do this, wrap the content in the pre element. <sgmltag>pre</sgmltag> You could use pre to mark up an e-mail message; From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available There is a new copy of my primer for contributors to the FreeBSD Documentation Project available at Comments appreciated. N]]> Tables Most text-mode browsers (such as Lynx) do not render tables particularly effectively. If you are relying on the tabular display of your content, you should consider using alternative markup to prevent confusion. Mark up tabular information using the table element. A table consists of one or more table rows (tr), each containing one or more cells of table data (td). Each cell can contain other block elements, such as paragraphs or lists. It can also contain another table (this nesting can repeat indefinitely). If the cell only contains one paragraph then you do not need to include the p element. Simple use of <sgmltag>table</sgmltag> Use: This is a simple 2x2 table.

Top left cell Top right cell
Bottom left cell Bottom right cell
]]> A cell can span multiple rows and columns. To indicate this, add the rowspan and/or colspan attributes, with values indicating the number of rows of columns that should be spanned. Using <literal>rowspan</literal> Use: One tall thin cell on the left, two short cells next to it on the right.

Long and thin
Top cell Bottom cell
]]> Using <literal>colspan</literal> Use: One long cell on top, two short cells below it.

Top cell
Bottom left cell Bottom right cell
]]> Using <literal>rowspan</literal> and <literal>colspan</literal> together Use: On a 3x3 grid, the top left block is a 2x2 set of cells merged into one. The other cells are normal.

Top left large cell Top right cell
Middle right cell
Bottom left cell Bottom middle cell Bottom right cell
]]> In-line elements Emphasising information You have two levels of emphasis available in HTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis. Typically, em is rendered in italic and strong is rendered in bold. This is not always the case, however, and you should not rely on it. <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag> Use: This has been emphasised, while this has been strongly emphasised.

]]> Bold and italics Because HTML includes presentational markup, you can also indicate that particular content should be rendered in bold or italic. The elements are b and i respectively. <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag> This is in bold, while this is in italics.

]]> Indicating fixed pitch text If you have content that should be rendered in a fixed pitch (typewriter) typeface, use tt (for teletype). <sgmltag>tt</sgmltag> Use: This document was originally written by Nik Clayton, who can be reached by e-mail as nik@FreeBSD.org.

]]> Content size You can indicate that content should be shown in a larger or smaller font. There are three ways of doing this. Use big and small around the content you wish to change size. These tags can be nested, so <big><big>This is much bigger</big></big> is possible. Use font with the size attribute set to +1 or -1 respectively. This has the same effect as using big or small. However, the use of this approach is deprecated. Use font with the size attribute set to a number between 1 and 7. The default font size is 3. This approach is deprecated. <sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and <sgmltag>font</sgmltag> The following fragments all do the same thing. This text is slightly smaller. But this text is slightly bigger.

This text is slightly smaller. But this text is slightly bigger

This text is slightly smaller. But this text is slightly bigger.

]]> Links Links are also in-line elements. Linking to other documents on the WWW In order to include a link to another document on the WWW you must know the URL of the document you want to link to. The link is indicated with a, and the href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of color, different mouse cursor when over the link, and so on). Using <literal><a href="..."></literal> Use: More information is available at the FreeBSD web site.

]]> These links will take the user to the top of the chosen document. Linking to other parts of documents Linking to a point within another document (or within the same document) requires that the document author include anchors that you can link to. Anchors are indicated with a and the name attribute instead of href. Using <literal><a name="..."></literal> Use: This paragraph can be referenced in other links with the name para1.

]]> To link to a named part of a document, write a normal link to that document, but include the name of the anchor after a # symbol. Linking to a named part of another document Assume that the para1 example resides in a document called foo.html. More information can be found in the first paragraph of foo.html.

]]> If you are linking to a named anchor within the same document then you can omit the document's URL, and just include the name of the anchor (with the preceding #). Linking to a named part of the same document Assume that the para1 example resides in this document More information can be found in the first paragraph of this document.

]]> DocBook DocBook was originally developed by HaL Computer Systems and O'Reilly & Associates to be a DTD for writing technical documentation A short history can be found under http://www.oasis-open.org/committees/docbook/intro.shtml. . Since 1998 it is maintained by the DocBook Technical Committee. As such, and unlike LinuxDoc and HTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented. <literal>formal</literal> vs. <literal>informal</literal> Some elements may exist in two forms, formal and informal. Typically, the formal version of the element will consist of a title followed by the informal version of the element. The informal version will not have a title. The DocBook DTD is available from the ports collection in the textproc/docbook port. It is automatically installed as part of the textproc/docproj port. FreeBSD extensions The FreeBSD Documentation Project has extended the DocBook DTD by adding some new elements. These elements serve to make some of the markup more precise. Where a FreeBSD specific element is listed below it is clearly marked. Throughout the rest of this document, the term DocBook is used to mean the FreeBSD extended DocBook DTD. There is nothing about these extensions that is FreeBSD specific, it was just felt that they were useful enhancements for this particular project. Should anyone from any of the other *nix camps (NetBSD, OpenBSD, Linux, …) be interested in collaborating on a standard DocBook extension set, please get in touch with &a.nik;. The FreeBSD extensions are not (currently) in the ports collection. They are stored in the FreeBSD CVS tree, as doc/share/sgml/freebsd.dtd. Formal Public Identifier (FPI) In compliance with the DocBook guidelines for writing FPIs for DocBook customisations, the FPI for the FreeBSD extended DocBook DTD is; PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" Document structure DocBook allows you to structure your documentation in several ways. In the FreeBSD Documentation Project we are using two primary types of DocBook document: the book and the article. A book is organized into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organisation. The Handbook is arranged in this way. A chapter may (or may not) contain one or more sections. These are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5. Chapters and sections contain the remainder of the content. An article is simpler than a book, and does not use chapters. Instead, the content of an article is organized into one or more sections, using the same sect1 (and sect2 and so on) elements that are used in books. Obviously, you should consider the nature of the documentation you are writing in order to decide whether it is best marked up as a book or an article. Articles are well suited to information that does not need to be broken down into several chapters, and that is, relatively speaking, quite short, at up to 20-25 pages of content. Books are best suited to information that can be broken up into several chapters, possibly with appendices and similar content as well. The FreeBSD tutorials are all marked up as articles, while this document, the FreeBSD FAQ, and the FreeBSD Handbook are all marked up as books. Starting a book The content of the book is contained within the book element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within bookinfo. Boilerplate <sgmltag>book</sgmltag> with <sgmltag>bookinfo</sgmltag> <book> <bookinfo> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <releaseinfo>$FreeBSD$</releaseinfo> <abstract> <para>Include an abstract of the book's contents here.</para> </abstract> </bookinfo> … </book> Starting an article The content of the article is contained within the article element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page. This additional information should be contained within articleinfo. Boilerplate <sgmltag>article</sgmltag> with <sgmltag>articleinfo</sgmltag> <article> <articleinfo> <title>Your title here</title> <author> <firstname>Your first name</firstname> <surname>Your surname</surname> <affiliation> <address><email>Your e-mail address</email></address> </affiliation> </author> <copyright> <year>1998</year> <holder role="mailto:your e-mail address">Your name</holder> </copyright> <releaseinfo>$FreeBSD$</releaseinfo> <abstract> <para>Include an abstract of the article's contents here.</para> </abstract> </articleinfo> … </article> Indicating chapters Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books. A simple chapter The chapter's title ... ]]> A chapter cannot be empty; it must contain elements in addition to title. If you need to include an empty chapter then just use an empty paragraph. Empty chapters This is an empty chapter ]]> Sections below chapters In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the sectn element. The n indicates the section number, which identifies the section level. The first sectn is sect1. You can have one or more of these in a chapter. They can contain one or more sect2 elements, and so on, down to sect5. Sections in chapters A sample chapter Some text in the chapter. First section (1.1) … Second section (1.2) First sub-section (1.2.1) First sub-sub-section (1.2.1.1) … Second sub-section (1.2.2) … ]]> This example includes section numbers in the section titles. You should not do this in your documents. Adding the section numbers is carried out by the stylesheets (of which more later), and you do not need to manage them yourself. Subdividing using <sgmltag>part</sgmltag>s You can introduce another layer of organisation between book and chapter with one or more parts. This cannot be done in an article. Introduction Overview ... What is FreeBSD? ... History ... ]]> Block elements Paragraphs DocBook supports three types of paragraphs: formalpara, para, and simpara. Most of the time you will only need to use para. formalpara includes a title element, and simpara disallows some elements from within para. Stick with para. <sgmltag>para</sgmltag> Use: This is a paragraph. It can contain just about any other element. ]]> Appearance: This is a paragraph. It can contain just about any other element. Block quotations A block quotation is an extended quotation from another document that should not appear within the current paragraph. You will probably only need it infrequently. Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed). <sgmltag>blockquote</sgmltag> Use: A small excerpt from the US Constitution;
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
]]> Appearance:
Preamble to the Constitution of the United States Copied from a web site somewhere We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
Tips, notes, warnings, cautions, important information and sidebars. You may need to include extra information separate from the main body of the text. Typically this is meta information that the user should be aware of. Depending on the nature of the information, one of tip, note, warning, caution, and important should be used. Alternatively, if the information is related to the main text but is not one of the above, use sidebar. The circumstances in which to choose one of these elements over another is unclear. The DocBook documentation suggests; A Note is for information that should be heeded by all readers. An Important element is a variation on Note. A Caution is for information regarding possible data loss or software damage. A Warning is for information regarding possible hardware damage or injury to life or limb. <sgmltag>warning</sgmltag> Use: Installing FreeBSD may make you want to delete Windows from your hard disk. ]]> Installing FreeBSD may make you want to delete Windows from your hard disk. Lists and procedures You will often need to list pieces of information to the user, or present them with a number of steps that must be carried out in order to accomplish a particular goal. In order to do this, use itemizedlist, orderedlist, or procedureThere are other types of list element in DocBook, but we are not concerned with those at the moment. itemizedlist and orderedlist are similar to their counterparts in HTML, ul and ol. Each one consists of one or more listitem elements, and each listitem contains one or more block elements. The listitem elements are analogous to HTML's li tags. However, unlike HTML, they are required. procedure is slightly different. It consists of steps, which may in turn consists of more steps or substeps. Each step contains block elements. <sgmltag>itemizedlist</sgmltag>, <sgmltag>orderedlist</sgmltag>, and <sgmltag>procedure</sgmltag> Use: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. ]]> Appearance: This is the first itemized item. This is the second itemized item. This is the first ordered item. This is the second ordered item. Do this. Then do this. And now do this. Showing file samples If you want to show a fragment of a file (or perhaps a complete file) to the user, wrap it in the programlisting element. White space and line breaks within programlisting are significant. In particular, this means that the opening tag should appear on the same line as the first line of the output, and the closing tag should appear on the same line as the last line of the output, otherwise spurious blank lines may be included. <sgmltag>programlisting</sgmltag> Use: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); }]]> Notice how the angle brackets in the #include line need to be referenced by their entities instead of being included literally. Appearance: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } Callouts A callout is a mechanism for referring back to an earlier piece of text or specific position within an earlier example without linking to it within the text. To do this, mark areas of interest in your example (programlisting, literallayout, or whatever) with the co element. Each element must have a unique id assigned to it. After the example include a calloutlist that refers back to the example and provides additional commentary. <sgmltag>co</sgmltag> and <sgmltag>calloutlist</sgmltag> When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } Includes the standard IO header file. Specifies that main() returns an int. The printf() call that writes hello, world to standard output. ]]> Appearance: When you have finished, your program should look like this; #include <stdio.h> int main(void) { printf("hello, world\n"); } Includes the standard IO header file. Specifies that main() returns an int. The printf() call that writes hello, world to standard output. Tables Unlike HTML, you do not need to use tables for layout purposes, as the stylesheet handles those issues for you. Instead, just use tables for marking up tabular data. In general terms (and see the DocBook documentation for more detail) a table (which can be either formal or informal) consists of a table element. This contains at least one tgroup element, which specifies (as an attribute) the number of columns in this table group. Within the tablegroup you can then have one thead element, which contains elements for the table headings (column headings), and one tbody which contains the body of the table. Both tgroup and thead contain row elements, which in turn contain entry elements. Each entry element specifies one cell in the table. <sgmltag>informaltable</sgmltag> Use: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 ]]> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 If you do not want a border around the table the frame attribute can be added to the informaltable element with a value of none (i.e., <informaltable frame="none">). Tables where <literal>frame="none"</literal> Appearance: This is column head 1 This is column head 2 Row 1, column 1 Row 1, column 2 Row 2, column 1 Row 2, column 2 Examples for the user to follow A lot of the time you need to show examples for the user to follow. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, they type in another command, and so on. A number of distinct elements and entities come into play here. screen Everything the user sees in this example will be on the computer screen, so the next element is screen. Within screen, white space is significant. prompt, &prompt.root; and &prompt.user; Some of the things the user will be seeing on the screen are prompts from the computer (either from the operating system, command shell, or application). These should be marked up using prompt. As a special case, the two shell prompts for the normal user and the root user have been provided as entities. Every time you want to indicate the user is at a shell prompt, use one of &prompt.root; and &prompt.user; as necessary. They do not need to be inside prompt. &prompt.root; and &prompt.user; are FreeBSD extensions to DocBook, and are not part of the original DTD. userinput When displaying text that the user should type in, wrap it in userinput tags. It will probably be displayed differently to the user. <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and <sgmltag>userinput</sgmltag> Use: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2']]> Appearance: &prompt.user; ls -1 foo1 foo2 foo3 &prompt.user; ls -1 | grep foo2 foo2 &prompt.user; su Password: &prompt.root; cat foo2 This is the file called 'foo2' Even though we are displaying the contents of the file foo2, it is not marked up as programlisting. Reserve programlisting for showing fragments of files outside the context of user actions. In-line elements Emphasising information When you want to emphasise a particular word or phrase, use emphasis. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system. There is no way to change the presentation of the emphasis within your document, no equivalent of HTML's b and i. If the information you are presenting is important then consider presenting it in important rather than emphasis. <sgmltag>emphasis</sgmltag> Use: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture.]]> Appearance: FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture. Quotations To quote text from another document or source, or to denote a phrase that is used figuratively, use quote. Within a quote tag, you may use most of the markup tags available for normal text. Quotations Use: However, make sure that the search does not go beyond the boundary between local and public administration, as RFC 1535 calls it.]]> Appearance: However, make sure that the search does not go beyond the boundary between local and public administration, as RFC 1535 calls it. Keys, mouse buttons, and combinations To refer to a specific key on the keyboard, use keycap. To refer to a mouse button, use mousebutton. And to refer to combinations of key presses or mouse clicks, wrap them all in keycombo. keycombo has an attribute called action, which may be one of click, double-click, other, press, seq, or simul. The last two values denote whether the keys or buttons should be pressed in sequence, or simultaneously. The stylesheets automatically add any connecting symbols, such as +, between the key names, when wrapped in keycombo. Keys, mouse buttons, and combinations Use: To switch to the second virtual terminal, press Alt F1. To exit vi without saving your work, type Esc: q!. My window manager is configured so that Alt right mouse button is used to move windows.]]> Appearance: To switch to the second virtual terminal, press Alt F1. To exit vi without saving your work, type Esc: q!. My window manager is configured so that Alt right mouse button is used to move windows. Applications, commands, options, and cites You will frequently want to refer to both applications and commands when writing for the Handbook. The distinction between them is simple: an application is the name for a suite (or possibly just 1) of programs that fulfil a particular task. A command is the name of a program that the user can run. In addition, you will occasionally need to list one or more of the options that a command might take. Finally, you will often want to list a command with its manual section number, in the command(number) format so common in Unix manuals. Mark up application names with application. When you want to list a command with its manual section number (which should be most of the time) the DocBook element is citerefentry. This will contain a further two elements, refentrytitle and manvolnum. The content of refentrytitle is the name of the command, and the content of manvolnum is the manual page section. This can be cumbersome to write, and so a series of general entities have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;. The file that contains these entities is in doc/share/sgml/man-refs.ent, and can be referred to using this FPI: PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" Therefore, the introduction to your documentation will probably look like this: <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man; … ]> Use command when you want to include a command name in-line but present it as something the user should type in. Use option to mark up a command's options. When referring to the same command multiple times in close proximity it is preferred to use the &man.command.section; notation to markup the first reference and use command to markup subsequent references. This makes the generated output, especially HTML, appear visually better. This can be confusing, and sometimes the choice is not always clear. Hopefully this example makes it clearer. Applications, commands, and options. Use: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , &man.mailq.8;, and &man.newaliases.8; programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp.]]> Appearance: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , mailq 8 , and newaliases 8 programs. One of the command line parameters to sendmail 8 , , will display the current status of messages in the mail queue. Check this on the command line by running sendmail -bp. Notice how the &man.command.section; notation is easier to follow. Files, directories, extensions Whenever you wish to refer to the name of a file, a directory, or a file extension, use filename. <sgmltag>filename</sgmltag> Use: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension.]]> Appearance: The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile and a number of files with a .ent extension. The name of ports FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. You might need to include the name of a program from the FreeBSD Ports Collection in the documentation. Use the filename tag with the role attribute set to package to identify these. Since ports can be installed in any number of locations, only include the category and the port name; do not include /usr/ports. <sgmltag>filename</sgmltag> tag with <literal>package</literal> role Use: Install the net/ethereal port to view network traffic.]]> Appearance: Install the net/ethereal port to view network traffic. Devices FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When referring to devices you have two choices. You can either refer to the device as it appears in /dev, or you can use the name of the device as it appears in the kernel. For this latter course, use devicename. Sometimes you will not have a choice. Some devices, such as networking cards, do not have entries in /dev, or the entries are markedly different from those entries. <sgmltag>devicename</sgmltag> Use: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as - ed0 do not appear in /dev. + ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0.]]> Appearance: sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. By contrast, the networking devices, such as ed0 do not appear in /dev. In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD it is /dev/fd0. Hosts, domains, IP addresses, and so forth FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. You can markup identification information for networked computers (hosts) in several ways, depending on the nature of the information. All of them use hostid as the element, with the role attribute selecting the type of the marked up information. No role attribute, or role="hostname" With no role attribute (i.e., hostid.../hostid) the marked up information is the simple hostname, such as freefall or wcarchive. You can explicitly specify this with role="hostname". role="domainname" The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component. role="fqdn" The text is a Fully Qualified Domain Name, with both hostname and domain name parts. role="ipaddr" The text is an IP address, probably expressed as a dotted quad. role="ip6addr" The text is an IPv6 address. role="netmask" The text is a network mask, which might be expressed as a dotted quad, a hexadecimal string, or as a / followed by a number. role="mac" The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons. <sgmltag>hostid</sgmltag> and roles Use: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]> Appearance: The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org. When adding an IP alias to an interface (using ifconfig) always use a netmask of 255.255.255.255 (which can also be expressed as 0xffffffff. The MAC address uniquely identifies every network card in existence. A typical MAC address looks like 08:00:20:87:ef:d0. Usernames FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. When you need to refer to a specific username, such as root or bin, use username. <sgmltag>username</sgmltag> Use: To carry out most system administration functions you will need to be root.]]> Appearance: To carry out most system administration functions you will need to be root. Describing <filename>Makefile</filename>s FreeBSD extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. Two elements exist to describe parts of Makefiles, maketarget and makevar. maketarget identifies a build target exported by a Makefile that can be given as a parameter to make. makevar identifies a variable that can be set (in the environment, on the make command line, or within the Makefile) to influence the process. <sgmltag>maketarget</sgmltag> and <sgmltag>makevar</sgmltag> Use: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE.]]> Appearance: Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the application, and invoking clean will remove the temporary files (.o for example) created by the build process. clean may be controlled by a number of variables, including CLOBBER and RECURSE. Literal text You will often need to include literal text in the Handbook. This is text that is excerpted from another file, or which should be copied from the Handbook into another file verbatim. Some of the time, programlisting will be sufficient to denote this text. programlisting is not always appropriate, particularly when you want to include a portion of a file in-line with the rest of the paragraph. On these occasions, use literal. <sgmltag>literal</sgmltag> Use: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.]]> Appearance: The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. Showing items that the user <emphasis>must</emphasis> fill in There will often be times when you want to show the user what to do, or refer to a file, or command line, or similar, where the user cannot simply copy the examples that you provide, but must instead include some information themselves. replaceable is designed for this eventuality. Use it inside other elements to indicate parts of that element's content that the user must replace. <sgmltag>replaceable</sgmltag> Use: &prompt.user; man command ]]> Appearance: &prompt.user; man command replaceable can be used in many different elements, including literal. This example also shows that replaceable should only be wrapped around the content that the user is meant to provide. The other content should be left alone. Use: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n.]]> Appearance: The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. For a desktop workstation, 32 is a good value for n. Quoting system errors You might want to show errors generated by FreeBSD. Mark these with errorname. This indicates the exact error that appears. <sgmltag>errorname</sgmltag> Use: Panic: cannot mount root ]]> Appearance: Panic: cannot mount root Images Image support in the documentation is currently extremely experimental. I think the mechanisms described here are unlikely to change, but that is not guaranteed. You will also need to install the graphics/ImageMagick port, which is used to convert between the different image formats. This is a big port, and most of it is not required. However, while we are working on the Makefiles and other infrastructure it makes things easier. This port is not in the textproc/docproj meta port, you must install it by hand. The best example of what follows in practice is the doc/en_US.ISO8859-1/articles/vm-design/ document. If you are unsure of the description that follows, take a look at the files in that directory to see how everything hangs together. Experiment with creating different formatted versions of the document to see how the image markup appears in the formatted output. Image formats We currently support two formats for images. The format you should use will depend on the nature of your image. For images that are primarily vector based, such as network diagrams, time lines, and similar, use Encapsulated Postscript, and make sure that your images have the .eps extension. For bitmaps, such as screen captures, use the Portable Network Graphic format, and make sure that your images have the .png extension. These are the only formats in which images should be committed to the CVS repository. Use the right format for the right image. It is to be expected that your documentation will have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format that you use for your documentation. Do not commit the same image to the repository in two different formats. It is anticipated that the Documentation Project will switch to using the Scalable Vector Graphic (SVG) format for vector images. However, the current state of SVG capable editing tools makes this impractical. Markup The markup for an image is relatively simple. First, markup a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject. You should include one imageobject, and two textobject elements. The imageobject will point to the name of the image file that will be used (without the extension). The textobject elements contain information that will be presented to the user as well as, or instead of, the image. There are two circumstances where this can happen. When the reader is viewing the documentation in HTML. In this case, each image will need to have associated alternate text to show the user, typically whilst the image is loading, or if they hover the mouse pointer over the image. When the reader is viewing the documentation in plain text. In this case, each image should have an ASCII art equivalent to show the user. An example will probably make things easier to understand. Suppose you have an image, called fig1, that you want to include in the document. This image is of a rectangle with an A inside it. The markup for this would be as follows. <mediaobject> <imageobject> <imagedata fileref="fig1"> </imageobject> <textobject> <literallayout class="monospaced">+---------------+ | A | +---------------+</literallayout> </textobject> <textobject> <phrase>A picture</phrase> </textobject> </mediaobject> Include an imagedata element inside the imageobject element. The fileref attribute should contain the filename of the image to include, without the extension. The stylesheets will work out which extension should be added to the filename automatically. The first textobject should contain a literallayout element, where the class attribute is set to monospaced. This is your opportunity to demonstrate your ASCII art skills. This content will be used if the document is converted to plain text. Notice how the first and last lines of the content of the literallayout element butt up next to the element's tags. This ensures no extraneous white space is included. The second textobject should contain a single phrase element. The contents of this will become the alt attribute for the image when this document is converted to HTML. <filename>Makefile</filename> entries Your images must be listed in the Makefile in the IMAGES variable. This variable should contain the name of all your source images. For example, if you have created three figures, fig1.eps, fig2.png, fig3.png, then your Makefile should have lines like this in it. … IMAGES= fig1.eps fig2.png fig3.png … or … IMAGES= fig1.eps IMAGES+= fig2.png IMAGES+= fig3.png … Again, the Makefile will work out the complete list of images it needs to build your source document, you only need to list the image files you provided. Images and chapters in subdirectories You must be careful when you separate your documentation into smaller files (see ) in different directories. Suppose you have a book with three chapters, and the chapters are stored in their own directories, called chapter1/chapter.sgml, chapter2/chapter.sgml, and chapter3/chapter.sgml. If each chapter has images associated with it, I suggest you place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/). However, if you do this you must include the directory names in the IMAGES variable in the Makefile, and you must include the directory name in the imagedata element in your document. For example, if you have chapter1/fig1.png, then chapter1/chapter.sgml should contain <mediaobject> <imageobject> <imagedata fileref="chapter1/fig1"> </imageobject> … </mediaobject> The directory name must be included in the fileref attribute The Makefile must contain … IMAGES= chapter1/fig1.png … Then everything should just work. Links Links are also in-line elements. Linking to other parts of the same document Linking within the same document requires you to specify where you are linking from (i.e., the text the user will click, or otherwise indicate, as the source of the link) and where you are linking to (the link's destination). Each element within DocBook has an attribute called id. You can place text in this attribute to uniquely name the element it is attached to. This value will be used when you specify the link source. Normally, you will only be linking to chapters or sections, so you would add the id attribute to these elements. <literal>id on chapters and sections</literal> Introduction This is the introduction. It contains a subsection, which is identified as well. Sub-sect 1 This is the subsection. ]]> Obviously, you should use more descriptive values. The values must be unique within the document (i.e., not just the file, but the document the file might be included in as well). Notice how the id for the subsection is constructed by appending text to the id of the chapter. This helps to ensure that they are unique. If you want to allow the user to jump into a specific portion of the document (possibly in the middle of a paragraph or an example), use anchor. This element has no content, but takes an id attribute. <sgmltag>anchor</sgmltag> This paragraph has an embedded link target in it. It will not show up in the document.]]> When you want to provide the user with a link they can activate (probably by clicking) to go to a section of the document that has an id attribute, you can use either xref or link. Both of these elements have a linkend attribute. The value of this attribute should be the value that you have used in a id attribute (it does not matter if that value has not yet occurred in your document; this will work for forward links as well as backward links). If you use xref then you have no control over the text of the link. It will be generated for you. Using <sgmltag>xref</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example; More information can be found in . More specific information can be found in .]]> The text of the link will be generated automatically, and will look like (emphasised text indicates the text that will be the link);
More information can be found in Chapter One. More specific information can be found in the section called Sub-sect 1.
Notice how the text from the link is derived from the section title or the chapter number. This means that you cannot use xref to link to an id attribute on an anchor element. The anchor has no content, so the xref cannot generate the text for the link. If you want to control the text of the link then use link. This element wraps content, and the content will be used for the link. Using <sgmltag>link</sgmltag> Assume that this fragment appears somewhere in a document that includes the id example. More information can be found in the first chapter. More specific information can be found in this section.]]> This will generate the following (emphasised text indicates the text that will be the link);
More information can be found in the first chapter. More specific information can be found in this section.
That last one is a bad example. Never use words like this or here as the source for the link. The reader will need to hunt around the surrounding context to see where the link is actually taking them. You can use link to include a link to an id on an anchor element, since the link content defines the text that will be used for the link. Linking to documents on the WWW Linking to external documents is much simpler, as long as you know the URL of the document you want to link to. Use ulink. The url attribute is the URL of the page that the link points to, and the content of the element is the text that will be displayed for the user to activate. <sgmltag>ulink</sgmltag> Use: Of course, you could stop reading this document and go to the FreeBSD home page instead.]]> Appearance: Of course, you could stop reading this document and go to the FreeBSD home page instead. diff --git a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml index c6a78b70fa..6697b725ad 100644 --- a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml @@ -1,3234 +1,3237 @@ Storage Synopsis This chapter covers the use of disks in FreeBSD. This includes memory-backed disks, network-attached disks, and standard SCSI/IDE storage devices. After reading this chapter, you will know: The terminology FreeBSD uses to describe the organization of data on a physical disk (partitions and slices). How to mount and unmount file systems. How to add additional hard disks to your system. How to setup virtual file systems, such as memory disks. How to use quotas to limit disk space usage. How to encrypt disks to secure them against attackers. How to create and burn CDs and DVDs on FreeBSD. The various storage media options for backups. How to use backup programs available under FreeBSD. How to backup to floppy disks. What snapshots are and how to use them efficiently. Device Names The following is a list of physical storage devices supported in FreeBSD, and the device names associated with them. Physical Disk Naming Conventions Drive type Drive device name IDE hard drives ad IDE CDROM drives acd SCSI hard drives and USB Mass storage devices da SCSI CDROM drives cd Assorted non-standard CDROM drives mcd for Mitsumi CD-ROM, scd for Sony CD-ROM, matcd for Matsushita/Panasonic CD-ROM The &man.matcd.4; driver has been removed in FreeBSD 4.X branch since October 5th, 2002 and does not exist in FreeBSD 5.0 and 5.1 releases. However this driver is back in the FreeBSD 5.X branch since June 16th, 2003. Floppy drives fd SCSI tape drives sa IDE tape drives ast Flash drives fla for &diskonchip; Flash device RAID drives aacd for &adaptec; AdvancedRAID, mlxd and mlyd for &mylex;, amrd for AMI &megaraid;, idad for Compaq Smart RAID, twed for &tm.3ware; RAID.
David O'Brien Originally contributed by Adding Disks disks adding Lets say we want to add a new SCSI disk to a machine that currently only has a single drive. First turn off the computer and install the drive in the computer following the instructions of the computer, controller, and drive manufacturer. Due to the wide variations of procedures to do this, the details are beyond the scope of this document. Login as user root. After you have installed the drive, inspect /var/run/dmesg.boot to ensure the new disk was found. Continuing with our example, the newly added drive will be da1 and we want to mount it on /1 (if you are adding an IDE drive, the device name will be wd1 in pre-4.0 systems, or ad1 in most 4.X systems). partitions slices fdisk Because FreeBSD runs on IBM-PC compatible computers, it must take into account the PC BIOS partitions. These are different from the traditional BSD partitions. A PC disk has up to four BIOS partition entries. If the disk is going to be truly dedicated to FreeBSD, you can use the dedicated mode. Otherwise, FreeBSD will have to live within one of the PC BIOS partitions. FreeBSD calls the PC BIOS partitions slices so as not to confuse them with traditional BSD partitions. You may also use slices on a disk that is dedicated to FreeBSD, but used in a computer that also has another operating system installed. This is to not confuse the fdisk utility of the other operating system. In the slice case the drive will be added as /dev/da1s1e. This is read as: SCSI disk, unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1), and e BSD partition. In the dedicated case, the drive will be added simply as /dev/da1e. Using &man.sysinstall.8; sysinstall adding disks su Navigating <application>Sysinstall</application> You may use /stand/sysinstall to partition and label a new disk using its easy to use menus. Either login as user root or use the su command. Run /stand/sysinstall and enter the Configure menu. Within the FreeBSD Configuration Menu, scroll down and select the Fdisk option. <application>fdisk</application> Partition Editor Once inside fdisk, we can type A to use the entire disk for FreeBSD. When asked if you want to remain cooperative with any future possible operating systems, answer YES. Write the changes to the disk using W. Now exit the FDISK editor by typing q. Next you will be asked about the Master Boot Record. Since you are adding a disk to an already running system, choose None. Disk Label Editor BSD partitions Next, you need to exit sysinstall and start it again. Follow the directions above, although this time choose the Label option. This will enter the Disk Label Editor. This is where you will create the traditional BSD partitions. A disk can have up to eight partitions, labeled a-h. A few of the partition labels have special uses. The a partition is used for the root partition (/). Thus only your system disk (e.g, the disk you boot from) should have an a partition. The b partition is used for swap partitions, and you may have many disks with swap partitions. The c partition addresses the entire disk in dedicated mode, or the entire FreeBSD slice in slice mode. The other partitions are for general use. sysinstall's Label editor favors the e partition for non-root, non-swap partitions. Within the Label editor, create a single file system by typing C. When prompted if this will be a FS (file system) or swap, choose FS and type in a mount point (e.g, /mnt). When adding a disk in post-install mode, sysinstall will not create entries in /etc/fstab for you, so the mount point you specify is not important. You are now ready to write the new label to the disk and create a file system on it. Do this by typing W. Ignore any errors from sysinstall that it could not mount the new partition. Exit the Label Editor and sysinstall completely. Finish The last step is to edit /etc/fstab to add an entry for your new disk. Using Command Line Utilities Using Slices This setup will allow your disk to work correctly with other operating systems that might be installed on your computer and will not confuse other operating systems' fdisk utilities. It is recommended to use this method for new disk installs. Only use dedicated mode if you have a good reason to do so! &prompt.root; dd if=/dev/zero of=/dev/da1 bs=1k count=1 &prompt.root; fdisk -BI da1 #Initialize your new disk &prompt.root; disklabel -B -w -r da1s1 auto #Label it. &prompt.root; disklabel -e da1s1 # Edit the disklabel just created and add any partitions. &prompt.root; mkdir -p /1 &prompt.root; newfs /dev/da1s1e # Repeat this for every partition you created. &prompt.root; mount /dev/da1s1e /1 # Mount the partition(s) &prompt.root; vi /etc/fstab # Add the appropriate entry/entries to your /etc/fstab. If you have an IDE disk, substitute ad for da. On pre-4.X systems use wd. Dedicated OS/2 If you will not be sharing the new drive with another operating system, you may use the dedicated mode. Remember this mode can confuse Microsoft operating systems; however, no damage will be done by them. IBM's &os2; however, will appropriate any partition it finds which it does not understand. &prompt.root; dd if=/dev/zero of=/dev/da1 bs=1k count=1 &prompt.root; disklabel -Brw da1 auto &prompt.root; disklabel -e da1 # create the `e' partition &prompt.root; newfs -d0 /dev/da1e &prompt.root; mkdir -p /1 &prompt.root; vi /etc/fstab # add an entry for /dev/da1e &prompt.root; mount /1 An alternate method is: &prompt.root; dd if=/dev/zero of=/dev/da1 count=2 &prompt.root; disklabel /dev/da1 | disklabel -BrR da1 /dev/stdin &prompt.root; newfs /dev/da1e &prompt.root; mkdir -p /1 &prompt.root; vi /etc/fstab # add an entry for /dev/da1e &prompt.root; mount /1 Since &os; 5.1-RELEASE, the &man.bsdlabel.8; utility replaces the old &man.disklabel.8; program. With &man.bsdlabel.8; a number of obsolete options and parameters have been retired; in the examples above the option should be removed with &man.bsdlabel.8;. For more information, please refer to the &man.bsdlabel.8; manual page. RAID Software RAID Christopher Shumway Original work by Jim Brown Revised by RAIDsoftware RAIDCCD Concatenated Disk Driver (CCD) Configuration When choosing a mass storage solution the most important factors to consider are speed, reliability, and cost. It is rare to have all three in balance; normally a fast, reliable mass storage device is expensive, and to cut back on cost either speed or reliability must be sacrificed. In designing the system described below, cost was chosen as the most important factor, followed by speed, then reliability. Data transfer speed for this system is ultimately constrained by the network. And while reliability is very important, the CCD drive described below serves online data that is already fully backed up on CD-R's and can easily be replaced. Defining your own requirements is the first step in choosing a mass storage solution. If your requirements prefer speed or reliability over cost, your solution will differ from the system described in this section. Installing the Hardware In addition to the IDE system disk, three Western Digital 30GB, 5400 RPM IDE disks form the core of the CCD disk described below providing approximately 90GB of online storage. Ideally, each IDE disk would have its own IDE controller and cable, but to minimize cost, additional IDE controllers were not used. Instead the disks were configured with jumpers so that each IDE controller has one master, and one slave. Upon reboot, the system BIOS was configured to automatically detect the disks attached. More importantly, FreeBSD detected them on reboot: ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33 ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33 ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33 ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33 If FreeBSD does not detect all the disks, ensure that you have jumpered them correctly. Most IDE drives also have a Cable Select jumper. This is not the jumper for the master/slave relationship. Consult the drive documentation for help in identifying the correct jumper. Next, consider how to attach them as part of the file system. You should research both &man.vinum.8; () and &man.ccd.4;. In this particular configuration, &man.ccd.4; was chosen. Setting Up the CCD The driver &man.ccd.4; allows you to take several identical disks and concatenate them into one logical file system. In order to use &man.ccd.4;, you need a kernel with &man.ccd.4; support built in. Add this line to your kernel configuration file, rebuild, and reinstall the kernel: pseudo-device ccd 4 On 5.X systems, you have to use instead the following line: device ccd In FreeBSD 5.X, it is not necessary to specify a number of &man.ccd.4; devices, as the &man.ccd.4; device driver is now self-cloning — new device instances will automatically be created on demand. The &man.ccd.4; support can also be loaded as a kernel loadable module in FreeBSD 3.0 or later. To set up &man.ccd.4;, you must first use &man.disklabel.8; to label the disks: disklabel -r -w ad1 auto disklabel -r -w ad2 auto disklabel -r -w ad3 auto This creates a disklabel for ad1c, ad2c and ad3c that spans the entire disk. Since &os; 5.1-RELEASE, the &man.bsdlabel.8; utility replaces the old &man.disklabel.8; program. With &man.bsdlabel.8; a number of obsolete options and parameters have been retired; in the examples above the option should be removed. For more information, please refer to the &man.bsdlabel.8; manual page. The next step is to change the disk label type. You can use &man.disklabel.8; to edit the disks: disklabel -e ad1 disklabel -e ad2 disklabel -e ad3 This opens up the current disk label on each disk with the editor specified by the EDITOR environment variable, typically &man.vi.1;. An unmodified disk label will look something like this: 8 partitions: # size offset fstype [fsize bsize bps/cpg] c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) Add a new e partition for &man.ccd.4; to use. This can usually be copied from the c partition, but the must be 4.2BSD. The disk label should now look something like this: 8 partitions: # size offset fstype [fsize bsize bps/cpg] c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597) Building the File System The device node for ccd0c may not exist yet, so to create it, perform the following commands: cd /dev sh MAKEDEV ccd0 In FreeBSD 5.0, &man.devfs.5; will automatically manage device nodes in /dev, so use of MAKEDEV is not necessary. Now that you have all of the disks labeled, you must build the &man.ccd.4;. To do that, use &man.ccdconfig.8;, with options similar to the following: ccdconfig ccd0 32 0 /dev/ad1e /dev/ad2e /dev/ad3e The use and meaning of each option is shown below: The first argument is the device to configure, in this case, /dev/ccd0c. The /dev/ portion is optional. The interleave for the file system. The interleave defines the size of a stripe in disk blocks, each normally 512 bytes. So, an interleave of 32 would be 16,384 bytes. Flags for &man.ccdconfig.8;. If you want to enable drive mirroring, you can specify a flag here. This configuration does not provide mirroring for &man.ccd.4;, so it is set at 0 (zero). The final arguments to &man.ccdconfig.8; are the devices to place into the array. Use the complete pathname for each device. After running &man.ccdconfig.8; the &man.ccd.4; is configured. A file system can be installed. Refer to &man.newfs.8; for options, or simply run: newfs /dev/ccd0c Making it All Automatic Generally, you will want to mount the &man.ccd.4; upon each reboot. To do this, you must configure it first. Write out your current configuration to /etc/ccd.conf using the following command: ccdconfig -g > /etc/ccd.conf During reboot, the script /etc/rc runs ccdconfig -C if /etc/ccd.conf exists. This automatically configures the &man.ccd.4; so it can be mounted. If you are booting into single user mode, before you can &man.mount.8; the &man.ccd.4;, you need to issue the following command to configure the array: ccdconfig -C To automatically mount the &man.ccd.4;, place an entry for the &man.ccd.4; in /etc/fstab so it will be mounted at boot time: /dev/ccd0c /media ufs rw 2 2 The Vinum Volume Manager RAIDsoftware RAID Vinum The Vinum Volume Manager is a block device driver which implements virtual disk drives. It isolates disk hardware from the block device interface and maps data in ways which result in an increase in flexibility, performance and reliability compared to the traditional slice view of disk storage. &man.vinum.8; implements the RAID-0, RAID-1 and RAID-5 models, both individually and in combination. See for more information about &man.vinum.8;. Hardware RAID RAID hardware FreeBSD also supports a variety of hardware RAID controllers. These devices control a RAID subsystem without the need for FreeBSD specific software to manage the array. Using an on-card BIOS, the card controls most of the disk operations itself. The following is a brief setup description using a Promise IDE RAID controller. When this card is installed and the system is started up, it displays a prompt requesting information. Follow the instructions to enter the card's setup screen. From here, you have the ability to combine all the attached drives. After doing so, the disk(s) will look like a single drive to FreeBSD. Other RAID levels can be set up accordingly. Rebuilding ATA RAID1 Arrays FreeBSD allows you to hot-replace a failed disk in an array. This requires that you catch it before you reboot. You will probably see something like the following in /var/log/messages or in the &man.dmesg.8; output: ad6 on monster1 suffered a hard error. ad6: READ command timeout tag=0 serv=0 - resetting ad6: trying fallback to PIO mode ata3: resetting devices .. done ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11) status=59 error=40 ar0: WARNING - mirror lost Using &man.atacontrol.8;, check for further information: &prompt.root; atacontrol list ATA channel 0: Master: no device present Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0 ATA channel 1: Master: no device present Slave: no device present ATA channel 2: Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 Slave: no device present ATA channel 3: Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 Slave: no device present &prompt.root; atacontrol status ar0 ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED You will first need to detach the disk from the array so that you can safely remove it: &prompt.root; atacontrol detach 3 Replace the disk. Reattach the disk as a spare: &prompt.root; atacontrol attach 3 Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 Slave: no device present + Rebuild the array: &prompt.root; atacontrol rebuild ar0 The rebuild command hangs until complete. However, it is possible to open another terminal (using Alt Fn) and check on the progress by issuing the following command: &prompt.root; dmesg | tail -10 [output removed] ad6: removed from configuration ad6: deleted from ar0 disk1 ad6: inserted into ar0 disk1 as spare &prompt.root; atacontrol status ar0 ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed Wait until this operation completes. Mike Meyer Contributed by Creating and Using Optical Media (CDs & DVDs) CDROMs creating Introduction CDs have a number of features that differentiate them from conventional disks. Initially, they were not writable by the user. They are designed so that they can be read continuously without delays to move the head between tracks. They are also much easier to transport between systems than similarly sized media were at the time. CDs do have tracks, but this refers to a section of data to be read continuously and not a physical property of the disk. To produce a CD on FreeBSD, you prepare the data files that are going to make up the tracks on the CD, then write the tracks to the CD. ISO 9660 file systems ISO 9660 The ISO 9660 file system was designed to deal with these differences. It unfortunately codifies file system limits that were common then. Fortunately, it provides an extension mechanism that allows properly written CDs to exceed those limits while still working with systems that do not support those extensions. sysutils/mkisofs The sysutils/mkisofs program is used to produce a data file containing an ISO 9660 file system. It has options that support various extensions, and is described below. You can install it with the sysutils/mkisofs port. CD burner ATAPI Which tool to use to burn the CD depends on whether your CD burner is ATAPI or something else. ATAPI CD burners use the burncd program that is part of the base system. SCSI and USB CD burners should use cdrecord from the sysutils/cdrtools port. burncd has a limited number of supported drives. To find out if a drive is supported, see the CD-R/RW supported drives list. CD burner ATAPI/CAM driver If you run &os; 5.X, &os; 4.8-RELEASE version or higher, it will be possible to use cdrecord and other tools for SCSI drives on an ATAPI hardware with the ATAPI/CAM module. mkisofs sysutils/mkisofs produces an ISO 9660 file system that is an image of a directory tree in the &unix; file system name space. The simplest usage is: &prompt.root; mkisofs -o imagefile.iso /path/to/tree file systems ISO 9660 This command will create an imagefile.iso containing an ISO 9660 file system that is a copy of the tree at /path/to/tree. In the process, it will map the file names to names that fit the limitations of the standard ISO 9660 file system, and will exclude files that have names uncharacteristic of ISO file systems. file systems HFS file systems Joliet A number of options are available to overcome those restrictions. In particular, enables the Rock Ridge extensions common to &unix; systems, enables Joliet extensions used by Microsoft systems, and can be used to create HFS file systems used by &macos;. For CDs that are going to be used only on FreeBSD systems, can be used to disable all filename restrictions. When used with , it produces a file system image that is identical to the FreeBSD tree you started from, though it may violate the ISO 9660 standard in a number of ways. CDROMs creating bootable The last option of general use is . This is used to specify the location of the boot image for use in producing an El Torito bootable CD. This option takes an argument which is the path to a boot image from the top of the tree being written to the CD. So, given that /tmp/myboot holds a bootable FreeBSD system with the boot image in /tmp/myboot/boot/cdboot, you could produce the image of an ISO 9660 file system in /tmp/bootable.iso like so: &prompt.root; mkisofs -U -R -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot Having done that, if you have vn (FreeBSD 4.X), or md (FreeBSD 5.X) configured in your kernel, you can mount the file system with: &prompt.root; vnconfig -e vn0c /tmp/bootable.iso &prompt.root; mount -t cd9660 /dev/vn0c /mnt for FreeBSD 4.X, and for FreeBSD 5.X: &prompt.root; mdconfig -a -t vnode -f /tmp/bootable.iso -u 0 &prompt.root; mount -t cd9660 /dev/md0 /mnt At which point you can verify that /mnt and /tmp/myboot are identical. There are many other options you can use with sysutils/mkisofs to fine-tune its behavior. In particular: modifications to an ISO 9660 layout and the creation of Joliet and HFS discs. See the &man.mkisofs.8; manual page for details. burncd CDROMs burning If you have an ATAPI CD burner, you can use the burncd command to burn an ISO image onto a CD. burncd is part of the base system, installed as /usr/sbin/burncd. Usage is very simple, as it has few options: &prompt.root; burncd -f cddevice data imagefile.iso fixate Will burn a copy of imagefile.iso on cddevice. The default device is /dev/acd0c. See &man.burncd.8; for options to set the write speed, eject the CD after burning, and write audio data. cdrecord If you do not have an ATAPI CD burner, you will have to use cdrecord to burn your CDs. cdrecord is not part of the base system; you must install it from either the port at sysutils/cdrtools or the appropriate package. Changes to the base system can cause binary versions of this program to fail, possibly resulting in a coaster. You should therefore either upgrade the port when you upgrade your system, or if you are tracking -STABLE, upgrade the port when a new version becomes available. While cdrecord has many options, basic usage is even simpler than burncd. Burning an ISO 9660 image is done with: &prompt.root; cdrecord dev=device imagefile.iso The tricky part of using cdrecord is finding the to use. To find the proper setting, use the flag of cdrecord, which might produce results like this: CDROMs burning &prompt.root; cdrecord -scanbus Cdrecord 1.9 (i386-unknown-freebsd4.2) Copyright (C) 1995-2000 Jörg Schilling Using libscg version 'schily-0.1' scsibus0: 0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk 0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk 0,2,0 2) * 0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk 0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM 0,5,0 5) * 0,6,0 6) * 0,7,0 7) * scsibus1: 1,0,0 100) * 1,1,0 101) * 1,2,0 102) * 1,3,0 103) * 1,4,0 104) * 1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM 1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner 1,7,0 107) * This lists the appropriate value for the devices on the list. Locate your CD burner, and use the three numbers separated by commas as the value for . In this case, the CRW device is 1,5,0, so the appropriate input would be . There are easier ways to specify this value; see &man.cdrecord.1; for details. That is also the place to look for information on writing audio tracks, controlling the speed, and other things. Duplicating Audio CDs You can duplicate an audio CD by extracting the audio data from the CD to a series of files, and then writing these files to a blank CD. The process is slightly different for ATAPI and SCSI drives. SCSI Drives Use cdda2wav to extract the audio. &prompt.user; cdda2wav -v255 -D2,0 -B -Owav Use cdrecord to write the .wav files. &prompt.user; cdrecord -v dev=2,0 -dao -useinfo *.wav Make sure that 2.0 is set appropriately, as described in . ATAPI Drives The ATAPI CD driver makes each track available as /dev/acddtnn, where d is the drive number, and nn is the track number written with two decimal digits, prefixed with zero as needed. So the first track on the first disk is /dev/acd0t01, the second is /dev/acd0t02, the third is /dev/acd0t03, and so on. Make sure the appropriate files exist in /dev. &prompt.root; cd /dev &prompt.root; sh MAKEDEV acd0t99 In FreeBSD 5.0, &man.devfs.5; will automatically create and manage entries in /dev for you, so it is not necessary to use MAKEDEV. Extract each track using &man.dd.1;. You must also use a specific block size when extracting the files. &prompt.root; dd if=/dev/acd0t01 of=track1.cdr bs=2352 &prompt.root; dd if=/dev/acd0t02 of=track2.cdr bs=2352 ... Burn the extracted files to disk using burncd. You must specify that these are audio files, and that burncd should fixate the disk when finished. &prompt.root; burncd -f /dev/acd0c audio track1.cdr track2.cdr ... fixate Duplicating Data CDs You can copy a data CD to a image file that is functionally equivalent to the image file created with sysutils/mkisofs, and you can use it to duplicate any data CD. The example given here assumes that your CDROM device is acd0. Substitute your correct CDROM device. A c must be appended to the end of the device name to indicate the entire partition or, in the case of CDROMs, the entire disc. &prompt.root; dd if=/dev/acd0c of=file.iso bs=2048 Now that you have an image, you can burn it to CD as described above. Using Data CDs Now that you have created a standard data CDROM, you probably want to mount it and read the data on it. By default, &man.mount.8; assumes that a file system is of type ufs. If you try something like: &prompt.root; mount /dev/cd0c /mnt you will get a complaint about Incorrect super block, and no mount. The CDROM is not a UFS file system, so attempts to mount it as such will fail. You just need to tell &man.mount.8; that the file system is of type ISO9660, and everything will work. You do this by specifying the option &man.mount.8;. For example, if you want to mount the CDROM device, /dev/cd0c, under /mnt, you would execute: &prompt.root; mount -t cd9660 /dev/cd0c /mnt Note that your device name (/dev/cd0c in this example) could be different, depending on the interface your CDROM uses. Also, the option just executes &man.mount.cd9660.8;. The above example could be shortened to: &prompt.root; mount_cd9660 /dev/cd0c /mnt You can generally use data CDROMs from any vendor in this way. Disks with certain ISO 9660 extensions might behave oddly, however. For example, Joliet disks store all filenames in two-byte Unicode characters. The FreeBSD kernel does not speak Unicode (yet!), so non-English characters show up as question marks. (If you are running FreeBSD 4.3 or later, the CD9660 driver includes hooks to load an appropriate Unicode conversion table on the fly. Modules for some of the common encodings are available via the sysutils/cd9660_unicode port.) Occasionally, you might get Device not configured when trying to mount a CDROM. This usually means that the CDROM drive thinks that there is no disk in the tray, or that the drive is not visible on the bus. It can take a couple of seconds for a CDROM drive to realize that it has been fed, so be patient. Sometimes, a SCSI CDROM may be missed because it didn't have enough time to answer the bus reset. If you have a SCSI CDROM please add the following option to your kernel configuration and rebuild your kernel. options SCSI_DELAY=15000 This tells your SCSI bus to pause 15 seconds during boot, to give your CDROM drive every possible chance to answer the bus reset. Burning Raw Data CDs You can choose to burn a file directly to CD, without creating an ISO 9660 file system. Some people do this for backup purposes. This runs more quickly than burning a standard CD: &prompt.root; burncd -f /dev/acd1c -s 12 data archive.tar.gz fixate In order to retrieve the data burned to such a CD, you must read data from the raw device node: &prompt.root; tar xzvf /dev/acd1c You cannot mount this disk as you would a normal CDROM. Such a CDROM cannot be read under any operating system except FreeBSD. If you want to be able to mount the CD, or share data with another operating system, you must use sysutils/mkisofs as described above. CD burner ATAPI/CAM driver Using the ATAPI/CAM Driver This driver allows ATAPI devices (CD-ROM, CD-RW, DVD drives etc...) to be accessed through the SCSI subsystem, and so allows the use of applications like sysutils/cdrdao or &man.cdrecord.1;. To use this driver, you will need to add the following lines to your kernel configuration file: device atapicam device scbus device cd device pass You also need the following lines in your kernel configuration file: device ata device atapicd Both of which should already be present. Then rebuild, install your new kernel, and reboot your machine. During the boot process, your burner should show up, like so: acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4 cd0 at ata1 bus 0 target 0 lun 0 cd0: <MATSHITA CDRW/DVD UJDA740 1.00> Removable CD-ROM SCSI-0 device cd0: 16.000MB/s transfers cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed The drive could now be accessed via the /dev/cd0 device name, for example to mount a CD-ROM on /mnt, just type the following: &prompt.root; mount -t cd9660 /dev/cd0c /mnt As root, you can run the following command to get the SCSI address of the burner: &prompt.root; camcontrol devlist <MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0) So 1,0,0 will be the SCSI address to use with &man.cdrecord.1; and other SCSI application. For more information about ATAPI/CAM and SCSI system, refer to the &man.atapicam.4; and &man.cam.4; manual pages. Julio Merino Original work by Martin Karlsson Rewritten by Creating and Using Floppy Disks Storing data on floppy disks is sometimes useful, for example when one does not have any other removable storage media or when one needs to transfer small amounts of data to another computer. This section will explain how to use floppy disks in FreeBSD. It will primarily cover formatting and usage of 3.5inch DOS floppies, but the concepts are similar for other floppy disk formats. Formatting Floppies The Device Floppy disks are accessed through entries in /dev, just like other devices. To access the raw floppy disk in 4.X and earlier releases, one uses /dev/fdN, where N stands for the drive number, usually 0, or /dev/fdNX, where X stands for a letter. In 5.0 or newer releases, simply use /dev/fdN. The Disk Size in 4.X and Earlier Releases There are also /dev/fdN.size devices, where size is a floppy disk size in kilobytes. These entries are used at low-level format time to determine the disk size. 1440kB is the size that will be used in the following examples. Sometimes the entries under /dev will have to be (re)created. To do that, issue: &prompt.root; cd /dev && ./MAKEDEV "fd*" The Disk Size in 5.0 and Newer Releases In 5.0, &man.devfs.5; will automatically manage device nodes in /dev, so use of MAKEDEV is not necessary. The desired disk size is passed to &man.fdformat.1; through the flag. Supported sizes are listed in &man.fdcontrol.8;, but be advised that 1440kB is what works best. Formatting A floppy disk needs to be low-level formated before it can be used. This is usually done by the vendor, but formatting is a good way to check media integrity. Although it is possible to force larger (or smaller) disk sizes, 1440kB is what most floppy disks are designed for. To low-level format the floppy disk you need to use &man.fdformat.1;. This utility expects the device name as an argument. Make note of any error messages, as these can help determine if the disk is good or bad. Formatting in 4.X and Earlier Releases Use the /dev/fdN.size devices to format the floppy. Insert a new 3.5inch floppy disk in your drive and issue: &prompt.root; /usr/sbin/fdformat /dev/fd0.1440 Formatting in 5.0 and Newer Releases Use the /dev/fdN devices to format the floppy. Insert a new 3.5inch floppy disk in your drive and issue: &prompt.root; /usr/sbin/fdformat -f 1440 /dev/fd0 The Disk Label After low-level formatting the disk, you will need to place a disk label on it. This disk label will be destroyed later, but it is needed by the system to determine the size of the disk and its geometry later. The new disk label will take over the whole disk, and will contain all the proper information about the geometry of the floppy. The geometry values for the disk label are listed in /etc/disktab. You can run now &man.disklabel.8; like so: &prompt.root; /sbin/disklabel -B -r -w /dev/fd0 fd1440 Since &os; 5.1-RELEASE, the &man.bsdlabel.8; utility replaces the old &man.disklabel.8; program. With &man.bsdlabel.8; a number of obsolete options and parameters have been retired; in the example above the option should be removed. For more information, please refer to the &man.bsdlabel.8; manual page. The File System Now the floppy is ready to be high-level formated. This will place a new file system on it, which will let FreeBSD read and write to the disk. After creating the new file system, the disk label is destroyed, so if you want to reformat the disk, you will have to recreate the disk label. The floppy's file system can be either UFS or FAT. FAT is generally a better choice for floppies. To put a new file system on the floppy, issue: &prompt.root; /sbin/newfs_msdos /dev/fd0 The disk is now ready for use. Using the Floppy To use the floppy, mount it with &man.mount.msdos.8; (in 4.X and earlier releases) or &man.mount.msdosfs.8; (in 5.0 or newer releases). One can also use emulators/mtools from the ports collection. Creating and Using Data Tapes tape media The major tape media are the 4mm, 8mm, QIC, mini-cartridge and DLT. 4mm (DDS: Digital Data Storage) tape media DDS (4mm) tapes tape media QIC tapes 4mm tapes are replacing QIC as the workstation backup media of choice. This trend accelerated greatly when Conner purchased Archive, a leading manufacturer of QIC drives, and then stopped production of QIC drives. 4mm drives are small and quiet but do not have the reputation for reliability that is enjoyed by 8mm drives. The cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51 x 12 mm) than 8mm cartridges. 4mm, like 8mm, has comparatively short head life for the same reason, both use helical scan. Data throughput on these drives starts ~150 kB/s, peaking at ~500 kB/s. Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware compression, available with most of these drives, approximately doubles the capacity. Multi-drive tape library units can have 6 drives in a single cabinet with automatic tape changing. Library capacities reach 240 GB. The DDS-3 standard now supports tape capacities up to 12 GB (or 24 GB compressed). 4mm drives, like 8mm drives, use helical-scan. All the benefits and drawbacks of helical-scan apply to both 4mm and 8mm drives. Tapes should be retired from use after 2,000 passes or 100 full backups. 8mm (Exabyte) tape media Exabyte (8mm) tapes 8mm tapes are the most common SCSI tape drives; they are the best choice of exchanging tapes. Nearly every site has an Exabyte 2 GB 8mm tape drive. 8mm drives are reliable, convenient and quiet. Cartridges are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). One downside of 8mm tape is relatively short head and tape life due to the high rate of relative motion of the tape across the heads. Data throughput ranges from ~250 kB/s to ~500 kB/s. Data sizes start at 300 MB and go up to 7 GB. Hardware compression, available with most of these drives, approximately doubles the capacity. These drives are available as single units or multi-drive tape libraries with 6 drives and 120 tapes in a single cabinet. Tapes are changed automatically by the unit. Library capacities reach 840+ GB. The Exabyte Mammoth model supports 12 GB on one tape (24 GB with compression) and costs approximately twice as much as conventional tape drives. Data is recorded onto the tape using helical-scan, the heads are positioned at an angle to the media (approximately 6 degrees). The tape wraps around 270 degrees of the spool that holds the heads. The spool spins while the tape slides over the spool. The result is a high density of data and closely packed tracks that angle across the tape from one edge to the other. QIC tape media QIC-150 QIC-150 tapes and drives are, perhaps, the most common tape drive and media around. QIC tape drives are the least expensive serious backup drives. The downside is the cost of media. QIC tapes are expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB data storage. But, if your needs can be satisfied with a half-dozen tapes, QIC may be the correct choice. QIC is the most common tape drive. Every site has a QIC drive of some density or another. Therein lies the rub, QIC has a large number of densities on physically similar (sometimes identical) tapes. QIC drives are not quiet. These drives audibly seek before they begin to record data and are clearly audible whenever reading, writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x 10.2 x 1.7 mm). Mini-cartridges, which also use 1/4" wide tape are discussed separately. Tape libraries and changers are not available. Data throughput ranges from ~150 kB/s to ~500 kB/s. Data capacity ranges from 40 MB to 15 GB. Hardware compression is available on many of the newer QIC drives. QIC drives are less frequently installed; they are being supplanted by DAT drives. Data is recorded onto the tape in tracks. The tracks run along the long axis of the tape media from one end to the other. The number of tracks, and therefore the width of a track, varies with the tape's capacity. Most if not all newer drives provide backward-compatibility at least for reading (but often also for writing). QIC has a good reputation regarding the safety of the data (the mechanics are simpler and more robust than for helical scan drives). Tapes should be retired from use after 5,000 backups. XXX* Mini-Cartridge DLT tape media DLT DLT has the fastest data transfer rate of all the drive types listed here. The 1/2" (12.5mm) tape is contained in a single spool cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). The cartridge has a swinging gate along one entire side of the cartridge. The drive mechanism opens this gate to extract the tape leader. The tape leader has an oval hole in it which the drive uses to hook the tape. The take-up spool is located inside the tape drive. All the other tape cartridges listed here (9 track tapes are the only exception) have both the supply and take-up spools located inside the tape cartridge itself. Data throughput is approximately 1.5 MB/s, three times the throughput of 4mm, 8mm, or QIC tape drives. Data capacities range from 10 GB to 20 GB for a single drive. Drives are available in both multi-tape changers and multi-tape, multi-drive tape libraries containing from 5 to 900 tapes over 1 to 20 drives, providing from 50 GB to 9 TB of storage. With compression, DLT Type IV format supports up to 70 GB capacity. Data is recorded onto the tape in tracks parallel to the direction of travel (just like QIC tapes). Two tracks are written at once. Read/write head lifetimes are relatively long; once the tape stops moving, there is no relative motion between the heads and the tape. AIT tape media AIT AIT is a new format from Sony, and can hold up to 50 GB (with compression) per tape. The tapes contain memory chips which retain an index of the tape's contents. This index can be rapidly read by the tape drive to determine the position of files on the tape, instead of the several minutes that would be required for other tapes. Software such as SAMS:Alexandria can operate forty or more AIT tape libraries, communicating directly with the tape's memory chip to display the contents on screen, determine what files were backed up to which tape, locate the correct tape, load it, and restore the data from the tape. Libraries like this cost in the region of $20,000, pricing them a little out of the hobbyist market. Using a New Tape for the First Time The first time that you try to read or write a new, completely blank tape, the operation will fail. The console messages should be similar to: sa0(ncr1:4:0): NOT READY asc:4,1 sa0(ncr1:4:0): Logical unit is in process of becoming ready The tape does not contain an Identifier Block (block number 0). All QIC tape drives since the adoption of QIC-525 standard write an Identifier Block to the tape. There are two solutions: mt fsf 1 causes the tape drive to write an Identifier Block to the tape. Use the front panel button to eject the tape. Re-insert the tape and dump data to the tape. dump will report DUMP: End of tape detected and the console will show: HARDWARE FAILURE info:280 asc:80,96. rewind the tape using: mt rewind. Subsequent tape operations are successful. Backups to Floppies Can I Use Floppies for Backing Up My Data? backup floppies floppy disks Floppy disks are not really a suitable media for making backups as: The media is unreliable, especially over long periods of time. Backing up and restoring is very slow. They have a very limited capacity (the days of backing up an entire hard disk onto a dozen or so floppies has long since passed). However, if you have no other method of backing up your data then floppy disks are better than no backup at all. If you do have to use floppy disks then ensure that you use good quality ones. Floppies that have been lying around the office for a couple of years are a bad choice. Ideally use new ones from a reputable manufacturer. So How Do I Backup My Data to Floppies? The best way to backup to floppy disk is to use &man.tar.1; with the (multi volume) option, which allows backups to span multiple floppies. To backup all the files in the current directory and sub-directory use this (as root): &prompt.root; tar Mcvf /dev/fd0 * When the first floppy is full &man.tar.1; will prompt you to insert the next volume (because &man.tar.1; is media independent it refers to volumes; in this context it means floppy disk). Prepare volume #2 for /dev/fd0 and hit return: This is repeated (with the volume number incrementing) until all the specified files have been archived. Can I Compress My Backups? tar gzip compression Unfortunately, &man.tar.1; will not allow the option to be used for multi-volume archives. You could, of course, &man.gzip.1; all the files, &man.tar.1; them to the floppies, then &man.gunzip.1; the files again! How Do I Restore My Backups? To restore the entire archive use: &prompt.root; tar Mxvf /dev/fd0 There are two ways that you can use to restore only specific files. First, you can start with the first floppy and use: &prompt.root; tar Mxvf /dev/fd0 filename The utility &man.tar.1; will prompt you to insert subsequent floppies until it finds the required file. Alternatively, if you know which floppy the file is on then you can simply insert that floppy and use the same command as above. Note that if the first file on the floppy is a continuation from the previous one then &man.tar.1; will warn you that it cannot restore it, even if you have not asked it to! Backup Basics The three major backup programs are &man.dump.8;, &man.tar.1;, and &man.cpio.1;. Dump and Restore backup software dump / restore dump restore The traditional &unix; backup programs are dump and restore. They operate on the drive as a collection of disk blocks, below the abstractions of files, links and directories that are created by the file systems. dump backs up an entire file system on a device. It is unable to backup only part of a file system or a directory tree that spans more than one file system. dump does not write files and directories to tape, but rather writes the raw data blocks that comprise files and directories. If you use dump on your root directory, you would not back up /home, /usr or many other directories since these are typically mount points for other file systems or symbolic links into those file systems. dump has quirks that remain from its early days in Version 6 of AT&T UNIX (circa 1975). The default parameters are suitable for 9-track tapes (6250 bpi), not the high-density media available today (up to 62,182 ftpi). These defaults must be overridden on the command line to utilize the capacity of current tape drives. .rhosts It is also possible to backup data across the network to a tape drive attached to another computer with rdump and rrestore. Both programs rely upon rcmd and ruserok to access the remote tape drive. Therefore, the user performing the backup must be listed in the .rhosts file on the remote computer. The arguments to rdump and rrestore must be suitable to use on the remote computer. When rdumping from a FreeBSD computer to an Exabyte tape drive connected to a Sun called komodo, use: &prompt.root; /sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1 Beware: there are security implications to allowing .rhosts authentication. Evaluate your situation carefully. It is also possible to use dump and restore in a more secure fashion over ssh. Using <command>dump</command> over <application>ssh</application> &prompt.root; /sbin/dump -0uan -f - /usr | gzip -2 | ssh1 -c blowfish \ targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz <command>tar</command> backup software tar &man.tar.1; also dates back to Version 6 of AT&T UNIX (circa 1975). tar operates in cooperation with the file system; tar writes files and directories to tape. tar does not support the full range of options that are available from &man.cpio.1;, but tar does not require the unusual command pipeline that cpio uses. tar Most versions of tar do not support backups across the network. The GNU version of tar, which FreeBSD utilizes, supports remote devices using the same syntax as rdump. To tar to an Exabyte tape drive connected to a Sun called komodo, use: &prompt.root; /usr/bin/tar cf komodo:/dev/nsa8 . 2>&1 For versions without remote device support, you can use a pipeline and rsh to send the data to a remote tape drive. &prompt.root; tar cf - . | rsh hostname dd of=tape-device obs=20b If you are worried about the security of backing up over a network you should use the ssh command instead of rsh. <command>cpio</command> backup software cpio &man.cpio.1; is the original &unix; file interchange tape program for magnetic media. cpio has options (among many others) to perform byte-swapping, write a number of different archive formats, and pipe the data to other programs. This last feature makes cpio an excellent choice for installation media. cpio does not know how to walk the directory tree and a list of files must be provided through stdin. cpio cpio does not support backups across the network. You can use a pipeline and rsh to send the data to a remote tape drive. &prompt.root; for f in directory_list; do find $f >> backup.list done &prompt.root; cpio -v -o --format=newc < backup.list | ssh user@host "cat > backup_device" Where directory_list is the list of directories you want to back up, user@host is the user/hostname combination that will be performing the backups, and backup_device is where the backups should be written to (e.g., /dev/nsa0). <command>pax</command> backup software pax pax POSIX IEEE &man.pax.1; is IEEE/&posix;'s answer to tar and cpio. Over the years the various versions of tar and cpio have gotten slightly incompatible. So rather than fight it out to fully standardize them, &posix; created a new archive utility. pax attempts to read and write many of the various cpio and tar formats, plus new formats of its own. Its command set more resembles cpio than tar. <application>Amanda</application> backup software Amanda Amanda Amanda (Advanced Maryland Network Disk Archiver) is a client/server backup system, rather than a single program. An Amanda server will backup to a single tape drive any number of computers that have Amanda clients and a network connection to the Amanda server. A common problem at sites with a number of large disks is that the length of time required to backup to data directly to tape exceeds the amount of time available for the task. Amanda solves this problem. Amanda can use a holding disk to backup several file systems at the same time. Amanda creates archive sets: a group of tapes used over a period of time to create full backups of all the file systems listed in Amanda's configuration file. The archive set also contains nightly incremental (or differential) backups of all the file systems. Restoring a damaged file system requires the most recent full backup and the incremental backups. The configuration file provides fine control of backups and the network traffic that Amanda generates. Amanda will use any of the above backup programs to write the data to tape. Amanda is available as either a port or a package, it is not installed by default. Do Nothing Do nothing is not a computer program, but it is the most widely used backup strategy. There are no initial costs. There is no backup schedule to follow. Just say no. If something happens to your data, grin and bear it! If your time and your data is worth little to nothing, then Do nothing is the most suitable backup program for your computer. But beware, &unix; is a useful tool, you may find that within six months you have a collection of files that are valuable to you. Do nothing is the correct backup method for /usr/obj and other directory trees that can be exactly recreated by your computer. An example is the files that comprise the HTML or &postscript; version of this Handbook. These document formats have been created from SGML input files. Creating backups of the HTML or &postscript; files is not necessary. The SGML files are backed up regularly. Which Backup Program Is Best? LISA &man.dump.8; Period. Elizabeth D. Zwicky torture tested all the backup programs discussed here. The clear choice for preserving all your data and all the peculiarities of &unix; file systems is dump. Elizabeth created file systems containing a large variety of unusual conditions (and some not so unusual ones) and tested each program by doing a backup and restore of those file systems. The peculiarities included: files with holes, files with holes and a block of nulls, files with funny characters in their names, unreadable and unwritable files, devices, files that change size during the backup, files that are created/deleted during the backup and more. She presented the results at LISA V in Oct. 1991. See torture-testing Backup and Archive Programs. Emergency Restore Procedure Before the Disaster There are only four steps that you need to perform in preparation for any disaster that may occur. disklabel First, print the disklabel from each of your disks (e.g. disklabel da0 | lpr), your file system table (/etc/fstab) and all boot messages, two copies of each. fix-it floppies Second, determine that the boot and fix-it floppies (boot.flp and fixit.flp) have all your devices. The easiest way to check is to reboot your machine with the boot floppy in the floppy drive and check the boot messages. If all your devices are listed and functional, skip on to step three. Otherwise, you have to create two custom bootable floppies which have a kernel that can mount all of your disks and access your tape drive. These floppies must contain: fdisk, disklabel, newfs, mount, and whichever backup program you use. These programs must be statically linked. If you use dump, the floppy must contain restore. Third, create backup tapes regularly. Any changes that you make after your last backup may be irretrievably lost. Write-protect the backup tapes. Fourth, test the floppies (either boot.flp and fixit.flp or the two custom bootable floppies you made in step two.) and backup tapes. Make notes of the procedure. Store these notes with the bootable floppy, the printouts and the backup tapes. You will be so distraught when restoring that the notes may prevent you from destroying your backup tapes (How? In place of tar xvf /dev/sa0, you might accidentally type tar cvf /dev/sa0 and over-write your backup tape). For an added measure of security, make bootable floppies and two backup tapes each time. Store one of each at a remote location. A remote location is NOT the basement of the same office building. A number of firms in the World Trade Center learned this lesson the hard way. A remote location should be physically separated from your computers and disk drives by a significant distance. A Script for Creating a Bootable Floppy /mnt/sbin/init gzip -c -best /sbin/fsck > /mnt/sbin/fsck gzip -c -best /sbin/mount > /mnt/sbin/mount gzip -c -best /sbin/halt > /mnt/sbin/halt gzip -c -best /sbin/restore > /mnt/sbin/restore gzip -c -best /bin/sh > /mnt/bin/sh gzip -c -best /bin/sync > /mnt/bin/sync cp /root/.profile /mnt/root cp -f /dev/MAKEDEV /mnt/dev chmod 755 /mnt/dev/MAKEDEV chmod 500 /mnt/sbin/init chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt chmod 555 /mnt/bin/sh /mnt/bin/sync chmod 6555 /mnt/sbin/restore # # create the devices nodes # cd /mnt/dev ./MAKEDEV std ./MAKEDEV da0 ./MAKEDEV da1 ./MAKEDEV da2 ./MAKEDEV sa0 ./MAKEDEV pty0 cd / # # create minimum file system table # cat > /mnt/etc/fstab < /mnt/etc/passwd < /mnt/etc/master.passwd < After the Disaster The key question is: did your hardware survive? You have been doing regular backups so there is no need to worry about the software. If the hardware has been damaged, the parts should be replaced before attempting to use the computer. If your hardware is okay, check your floppies. If you are using a custom boot floppy, boot single-user (type -s at the boot: prompt). Skip the following paragraph. If you are using the boot.flp and fixit.flp floppies, keep reading. Insert the boot.flp floppy in the first floppy drive and boot the computer. The original install menu will be displayed on the screen. Select the Fixit--Repair mode with CDROM or floppy. option. Insert the fixit.flp when prompted. restore and the other programs that you need are located in /mnt2/stand. Recover each file system separately. mount root partition disklabel newfs Try to mount (e.g. mount /dev/da0a /mnt) the root partition of your first disk. If the disklabel was damaged, use disklabel to re-partition and label the disk to match the label that you printed and saved. Use newfs to re-create the file systems. Re-mount the root partition of the floppy read-write (mount -u -o rw /mnt). Use your backup program and backup tapes to recover the data for this file system (e.g. restore vrf /dev/sa0). Unmount the file system (e.g. umount /mnt). Repeat for each file system that was damaged. Once your system is running, backup your data onto new tapes. Whatever caused the crash or data loss may strike again. Another hour spent now may save you from further distress later. * I Did Not Prepare for the Disaster, What Now? ]]> Marc Fonvieille Reorganized and enhanced by Network, Memory, and File-Backed File Systems virtual disks disks virtual Aside from the disks you physically insert into your computer: floppies, CDs, hard drives, and so forth; other forms of disks are understood by FreeBSD - the virtual disks. NFS Coda disks memory These include network file systems such as the Network File System and Coda, memory-based file systems and file-backed file systems. According to the FreeBSD version you run, you will have to use different tools for creation and use of file-backed and memory-based file systems. The FreeBSD 4.X users will have to use &man.MAKEDEV.8; to create the required devices. FreeBSD 5.0 and later use &man.devfs.5; to allocate device nodes transparently for the user. File-Backed File System under FreeBSD 4.X disks file-backed (4.X) The utility &man.vnconfig.8; configures and enables vnode pseudo-disk devices. A vnode is a representation of a file, and is the focus of file activity. This means that &man.vnconfig.8; uses files to create and operate a file system. One possible use is the mounting of floppy or CD images kept in files. To use &man.vnconfig.8;, you need &man.vn.4; support in your kernel configuration file: pseudo-device vn To mount an existing file system image: Using vnconfig to Mount an Existing File System Image under FreeBSD 4.X &prompt.root; vnconfig vn0 diskimage &prompt.root; mount /dev/vn0c /mnt To create a new file system image with &man.vnconfig.8;: Creating a New File-Backed Disk with <command>vnconfig</command> &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k 5120+0 records in 5120+0 records out &prompt.root; vnconfig -s labels -c vn0 newimage &prompt.root; disklabel -r -w vn0 auto &prompt.root; newfs vn0c Warning: 2048 sector(s) in last cylinder unallocated /dev/vn0c: 10240 sectors in 3 cylinders of 1 tracks, 4096 sectors 5.0MB in 1 cyl groups (16 c/g, 32.00MB/g, 1280 i/g) super-block backups (for fsck -b #) at: 32 &prompt.root; mount /dev/vn0c /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/vn0c 4927 1 4532 0% /mnt File-Backed File System under FreeBSD 5.X disks file-backed (5.X) The utility &man.mdconfig.8; is used to configure and enable memory disks, &man.md.4;, under FreeBSD 5.X. To use &man.mdconfig.8;, you have to load &man.md.4; module or to add the support in your kernel configuration file: device md The &man.mdconfig.8; command supports three kinds of memory backed virtual disks: memory disks allocated with &man.malloc.9;, memory disks using a file or swap space as backing. One possible use is the mounting of floppy or CD images kept in files. To mount an existing file system image: Using <command>mdconfig</command> to Mount an Existing File System Image under FreeBSD 5.X &prompt.root; mdconfig -a -t vnode -f diskimage -u 0 &prompt.root; mount /dev/md0c /mnt To create a new file system image with &man.mdconfig.8;: Creating a New File-Backed Disk with <command>mdconfig</command> &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k 5120+0 records in 5120+0 records out &prompt.root; mdconfig -a -t vnode -f newimage -u 0 &prompt.root; disklabel -r -w md0 auto &prompt.root; newfs md0c /dev/md0c: 5.0MB (10240 sectors) block size 16384, fragment size 2048 using 4 cylinder groups of 1.27MB, 81 blks, 256 inodes. super-block backups (for fsck -b #) at: 32, 2624, 5216, 7808 &prompt.root; mount /dev/md0c /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0c 4846 2 4458 0% /mnt If you do not specify the unit number with the option, &man.mdconfig.8; will use the &man.md.4; automatic allocation to select an unused device. The name of the allocated unit will be output on stdout like md4. For more details about &man.mdconfig.8;, please refer to the manual page. Since &os; 5.1-RELEASE, the &man.bsdlabel.8; utility replaces the old &man.disklabel.8; program. With &man.bsdlabel.8; a number of obsolete options and parameters have been retired; in the example above the option should be removed. For more information, please refer to the &man.bsdlabel.8; manual page. The utility &man.mdconfig.8; is very useful, however it asks many command lines to create a file-backed file system. FreeBSD 5.0 also comes with a tool called &man.mdmfs.8;, this program configures a &man.md.4; disk using &man.mdconfig.8;, puts a UFS file system on it using &man.newfs.8;, and mounts it using &man.mount.8;. For example, if you want to create and mount the same file system image as above, simply type the following: &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k 5120+0 records in 5120+0 records in 5120+0 records out &prompt.root; mdmfs -F newimage -s 5m md0 /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0 4846 2 4458 0% /mnt If you use the option without unit number, &man.mdmfs.8; will use &man.md.4; auto-unit feature to automatically select an unused device. For more details about &man.mdmfs.8;, please refer to the manual page. Memory-Based File System under FreeBSD 4.X disks memory file system (4.X) The &man.md.4; driver is a simple, efficient means to create memory file systems under FreeBSD 4.X. &man.malloc.9; is used to allocate the memory. Simply take a file system you have prepared with, for example, &man.vnconfig.8;, and: md Memory Disk under FreeBSD 4.X &prompt.root; dd if=newimage of=/dev/md0 5120+0 records in 5120+0 records out &prompt.root; mount /dev/md0c /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0c 4927 1 4532 0% /mnt For more details, please refer to &man.md.4; manual page. + Memory-Based File System under FreeBSD 5.X disks memory file system (5.X) The same tools are used for memory-based and file-backed file systems: &man.mdconfig.8; or &man.mdmfs.8;. The storage for memory-based file system is allocated with &man.malloc.9;. Creating a New Memory-Based Disk with <command>mdconfig</command> &prompt.root; mdconfig -a -t malloc -s 5m -u 1 &prompt.root; newfs -U md1 /dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048 using 4 cylinder groups of 1.27MB, 81 blks, 256 inodes. with soft updates super-block backups (for fsck -b #) at: 32, 2624, 5216, 7808 &prompt.root; mount /dev/md1 /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md1 4846 2 4458 0% /mnt Creating a New Memory-Based Disk with <command>mdmfs</command> &prompt.root; mdmfs -M -s 5m md2 /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md2 4846 2 4458 0% /mnt Instead of using a &man.malloc.9; backed file system, it is possible to use swap, for that just replace with in the command line of &man.mdconfig.8;. The &man.mdmfs.8; utility by default (without ) creates a swap-based disk. For more details, please refer to &man.mdconfig.8; and &man.mdmfs.8; manual pages. Detaching a Memory Disk from the System disks detaching a memory disk When a memory-based or file-based file system is not used, you should release all resources to the system. The first thing to do is to unmount the file system, then use &man.mdconfig.8; to detach the disk from the system and release the resources. For example to detach and free all resources used by /dev/md4: &prompt.root; mdconfig -d -u 4 It is possible to list information about configured &man.md.4; devices in using the command mdconfig -l. For FreeBSD 4.X, &man.vnconfig.8; is used to detach the device. For example to detach and free all resources used by /dev/vn4: &prompt.root; vnconfig -u vn4 Tom Rhodes Contributed by File System Snapshots file systems snapshots FreeBSD 5.0 offers a new feature in conjunction with Soft Updates: File system snapshots. Snapshots allow a user to create images of specified file systems, and treat them as a file. Snapshot files must be created in the file system that the action is performed on, and a user may create no more than 20 snapshots per file system. Active snapshots are recorded in the superblock so they are persistent across unmount and remount operations along with system reboots. When a snapshot is no longer required, it can be removed with the standard &man.rm.1; command. Snapshots may be removed in any order, however all the used space may not be acquired because another snapshot will possibly claim some of the released blocks. During initial creation, the flag (see the &man.chflags.1; manual page) is set to ensure that even root cannot write to the snapshot. The &man.unlink.1; command makes an exception for snapshot files since it allows them to be removed with the flag set, so it is not necessary to clear the flag before removing a snapshot file. Snapshots are created with the &man.mount.8; command. To place a snapshot of /var in the file /var/snapshot/snap use the following command: &prompt.root; mount -u -o snapshot /var/snapshot/snap /var Once a snapshot has been created, they have several uses: Some administrators will use a snapshot file for backup purposes, because the snapshot can be transfered to CDs or tape. File integrity, &man.fsck.8; may be ran on the snapshot. Assuming that the file system was clean when it was mounted, you should always get a clean (and unchanging) result. This is essentially what the background &man.fsck.8; process does. Run the &man.dump.8; utility on the snapshot. A dump will be returned that is consistent with the file system and the timestamp of the snapshot. &man.dump.8; can also take a snapshot, create a dump image and then remove the snapshot in one command using the flag. &man.mount.8; the snapshot as a frozen image of the file system. To &man.mount.8; the snapshot /var/snapshot/snap run: &prompt.root; mdconfig -a -t vnode -f /var/snapshot/snap -u 4 &prompt.root; mount -r /dev/md4 /mnt You can now walk the hierarchy of your frozen /var file system mounted at /mnt. Everything will be in the same state it was during the snapshot creation time. The only exception is that any earlier snapshots will appear as zero length files. When the use of a snapshot has delimited, it can be unmounted with: &prompt.root; umount /mnt &prompt.root; mdconfig -d -u 4 For more information about and file system snapshots, including technical papers, you can visit Marshall Kirk McKusick's website at http://www.mckusick.com. File System Quotas accounting disk space disk quotas Quotas are an optional feature of the operating system that allow you to limit the amount of disk space and/or the number of files a user or members of a group may allocate on a per-file system basis. This is used most often on timesharing systems where it is desirable to limit the amount of resources any one user or group of users may allocate. This will prevent one user or group of users from consuming all of the available disk space. Configuring Your System to Enable Disk Quotas Before attempting to use disk quotas, it is necessary to make sure that quotas are configured in your kernel. This is done by adding the following line to your kernel configuration file: options QUOTA The stock GENERIC kernel does not have this enabled by default, so you will have to configure, build and install a custom kernel in order to use disk quotas. Please refer to for more information on kernel configuration. Next you will need to enable disk quotas in /etc/rc.conf. This is done by adding the line: enable_quotas="YES" disk quotas checking For finer control over your quota startup, there is an additional configuration variable available. Normally on bootup, the quota integrity of each file system is checked by the &man.quotacheck.8; program. The &man.quotacheck.8; facility insures that the data in the quota database properly reflects the data on the file system. This is a very time consuming process that will significantly affect the time your system takes to boot. If you would like to skip this step, a variable in /etc/rc.conf is made available for the purpose: check_quotas="NO" If you are running FreeBSD prior to 3.2-RELEASE, the configuration is simpler, and consists of only one variable. Set the following in your /etc/rc.conf: check_quotas="YES" Finally you will need to edit /etc/fstab to enable disk quotas on a per-file system basis. This is where you can either enable user or group quotas or both for all of your file systems. To enable per-user quotas on a file system, add the option to the options field in the /etc/fstab entry for the file system you want to enable quotas on. For example: /dev/da1s2g /home ufs rw,userquota 1 2 Similarly, to enable group quotas, use the option instead of . To enable both user and group quotas, change the entry as follows: /dev/da1s2g /home ufs rw,userquota,groupquota 1 2 By default, the quota files are stored in the root directory of the file system with the names quota.user and quota.group for user and group quotas respectively. See &man.fstab.5; for more information. Even though the &man.fstab.5; manual page says that you can specify an alternate location for the quota files, this is not recommended because the various quota utilities do not seem to handle this properly. At this point you should reboot your system with your new kernel. /etc/rc will automatically run the appropriate commands to create the initial quota files for all of the quotas you enabled in /etc/fstab, so there is no need to manually create any zero length quota files. In the normal course of operations you should not be required to run the &man.quotacheck.8;, &man.quotaon.8;, or &man.quotaoff.8; commands manually. However, you may want to read their manual pages just to be familiar with their operation. Setting Quota Limits disk quotas limits Once you have configured your system to enable quotas, verify that they really are enabled. An easy way to do this is to run: &prompt.root; quota -v You should see a one line summary of disk usage and current quota limits for each file system that quotas are enabled on. You are now ready to start assigning quota limits with the &man.edquota.8; command. You have several options on how to enforce limits on the amount of disk space a user or group may allocate, and how many files they may create. You may limit allocations based on disk space (block quotas) or number of files (inode quotas) or a combination of both. Each of these limits are further broken down into two categories: hard and soft limits. hard limit A hard limit may not be exceeded. Once a user reaches his hard limit he may not make any further allocations on the file system in question. For example, if the user has a hard limit of 500 blocks on a file system and is currently using 490 blocks, the user can only allocate an additional 10 blocks. Attempting to allocate an additional 11 blocks will fail. soft limit Soft limits, on the other hand, can be exceeded for a limited amount of time. This period of time is known as the grace period, which is one week by default. If a user stays over his or her soft limit longer than the grace period, the soft limit will turn into a hard limit and no further allocations will be allowed. When the user drops back below the soft limit, the grace period will be reset. The following is an example of what you might see when you run the &man.edquota.8; command. When the &man.edquota.8; command is invoked, you are placed into the editor specified by the EDITOR environment variable, or in the vi editor if the EDITOR variable is not set, to allow you to edit the quota limits. &prompt.root; edquota -u test Quotas for user test: /usr: blocks in use: 65, limits (soft = 50, hard = 75) inodes in use: 7, limits (soft = 50, hard = 60) /usr/var: blocks in use: 0, limits (soft = 50, hard = 75) inodes in use: 0, limits (soft = 50, hard = 60) You will normally see two lines for each file system that has quotas enabled. One line for the block limits, and one line for inode limits. Simply change the value you want updated to modify the quota limit. For example, to raise this user's block limit from a soft limit of 50 and a hard limit of 75 to a soft limit of 500 and a hard limit of 600, change: /usr: blocks in use: 65, limits (soft = 50, hard = 75) to: /usr: blocks in use: 65, limits (soft = 500, hard = 600) The new quota limits will be in place when you exit the editor. Sometimes it is desirable to set quota limits on a range of UIDs. This can be done by use of the option on the &man.edquota.8; command. First, assign the desired quota limit to a user, and then run edquota -p protouser startuid-enduid. For example, if user test has the desired quota limits, the following command can be used to duplicate those quota limits for UIDs 10,000 through 19,999: &prompt.root; edquota -p test 10000-19999 For more information see &man.edquota.8; manual page. Checking Quota Limits and Disk Usage disk quotas checking You can use either the &man.quota.1; or the &man.repquota.8; commands to check quota limits and disk usage. The &man.quota.1; command can be used to check individual user or group quotas and disk usage. A user may only examine his own quota, and the quota of a group he is a member of. Only the super-user may view all user and group quotas. The &man.repquota.8; command can be used to get a summary of all quotas and disk usage for file systems with quotas enabled. The following is some sample output from the quota -v command for a user that has quota limits on two file systems. Disk quotas for user test (uid 1002): Filesystem blocks quota limit grace files quota limit grace /usr 65* 50 75 5days 7 50 60 /usr/var 0 50 75 0 50 60 grace period On the /usr file system in the above example, this user is currently 15 blocks over the soft limit of 50 blocks and has 5 days of the grace period left. Note the asterisk * which indicates that the user is currently over his quota limit. Normally file systems that the user is not using any disk space on will not show up in the output from the &man.quota.1; command, even if he has a quota limit assigned for that file system. The option will display those file systems, such as the /usr/var file system in the above example. Quotas over NFS NFS Quotas are enforced by the quota subsystem on the NFS server. The &man.rpc.rquotad.8; daemon makes quota information available to the &man.quota.1; command on NFS clients, allowing users on those machines to see their quota statistics. Enable rpc.rquotad in /etc/inetd.conf like so: rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad Now restart inetd: &prompt.root; kill -HUP `cat /var/run/inetd.pid` Lucky Green Contributed by
shamrock@cypherpunks.to
 Encrypting Disk Partitions disks encrypting FreeBSD offers excellent online protections against unauthorized data access. File permissions and Mandatory Access Control (MAC) (see ) help prevent unauthorized third-parties from accessing data while the operating system is active and the computer is powered up. However, the permissions enforced by the operating system are irrelevant if an attacker has physical access to a computer and can simply move the computer's hard drive to another system to copy and analyze the sensitive data. Regardless of how an attacker may have come into possession of a hard drive or powered-down computer, GEOM Based Disk Encryption (gbde) can protect the data on the computer's file systems against even highly-motivated attackers with significant resources. Unlike cumbersome encryption methods that encrypt only individual files, gbde transparently encrypts entire file systems. No cleartext ever touches the hard drive's platter. Enabling gbde in the Kernel Become <username>root</username> Configuring gbde requires super-user privileges. &prompt.user; su - Password: Verify the Operating System Version &man.gbde.4; requires FreeBSD 5.0 or higher. &prompt.root; uname -r 5.0-RELEASE Add &man.gbde.4; Support to the Kernel Configuration File Using your favorite text editor, add the following line to your kernel configuration file: options GEOM_BDE Configure, recompile, and install the FreeBSD kernel. This process is described in . Reboot into the new kernel. Preparing the Encrypted Hard Drive The following example assumes that you are adding a new hard drive to your system that will hold a single encrypted partition. This partition will be mounted as /private. gbde can also be used to encrypt /home and /var/mail, but this requires more complex instructions which exceed the scope of this introduction. Add the New Hard Drive Install the new drive to the system as explained in . For the purposes of this example, a new hard drive partition has been added as /dev/ad4s1c. The /dev/ad0s1* devices represent existing standard FreeBSD partitions on the example system. &prompt.root; ls /dev/ad* /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c /dev/ad0s1a /dev/ad0s1d /dev/ad4 Create a Directory to Hold gbde Lock Files &prompt.root; mkdir /etc/gbde The gbde lock file contains information that gbde requires to access encrypted partitions. Without access to the lock file, gbde will not be able to decrypt the data contained in the encrypted partition without significant manual intervention which is not supported by the software. Each encrypted partition uses a separate lock file. Initialize the gbde Partition A gbde partition must be initialized before it can be used. This initialization needs to be performed only once: &prompt.root; gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c &man.gbde.8; will open your editor, permitting you to set various configuration options in a template. For use with UFS1 or UFS2, set the sector_size to 2048: $FreeBSD: src/sbin/gbde/template.txt,v 1.1 2002/10/20 11:16:13 phk Exp $ # # Sector size is the smallest unit of data which can be read or written. # Making it too small decreases performance and decreases available space. # Making it too large may prevent filesystems from working. 512 is the # minimum and always safe. For UFS, use the fragment size # sector_size = 2048 [...] &man.gbde.8; will ask you twice to type the passphrase that should be used to secure the data. The passphrase must be the same both times. gbde's ability to protect your data depends entirely on the quality of the passphrase that you choose. For tips on how to select a secure passphrase that is easy to remember, see the Diceware Passphrase website. The gbde init command creates a lock file for your gbde partition that in this example is stored as /etc/gbde/ad4s1c. gbde lock files must be backed up together with the contents of any encrypted partitions. While deleting a lock file alone cannot prevent a determined attacker from decrypting a gbde partition, without the lock file, the legitimate owner will be unable to access the data on the encrypted partition without a significant amount of work that is totally unsupported by &man.gbde.8; and its designer. Attach the Encrypted Partition to the Kernel &prompt.root; gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c You will be asked to provide the passphrase that you selected during the initialization of the encrypted partition. The new encrypted device will show up in /dev as /dev/device_name.bde: &prompt.root; ls /dev/ad* /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c /dev/ad0s1a /dev/ad0s1d /dev/ad4 /dev/ad4s1c.bde Create a File System on the Encrypted Device Once the encrypted device has been attached to the kernel, you can create a file system on the device. To create a file system on the encrypted device, use &man.newfs.8;. Since it is much faster to initialize a new UFS2 file system than it is to initialize the old UFS1 file system, using &man.newfs.8; with the option is recommended. The option is the default with &os; 5.1-RELEASE and later. &prompt.root; newfs -U -O2 /dev/ad4s1c.bde The &man.newfs.8; command must be performed on an attached gbde partition which is identified by a *.bde extension to the device name. Mount the Encrypted Partition Create a mount point for the encrypted file system. &prompt.root; mkdir /private Mount the encrypted file system. &prompt.root; mount /dev/ad4s1c.bde /private Verify That the Encrypted File System is Available The encrypted file system should now be visible to &man.df.1; and be available for use. &prompt.user; df -H Filesystem Size Used Avail Capacity Mounted on /dev/ad0s1a 1037M 72M 883M 8% / /devfs 1.0K 1.0K 0B 100% /dev /dev/ad0s1f 8.1G 55K 7.5G 0% /home /dev/ad0s1e 1037M 1.1M 953M 0% /tmp /dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr /dev/ad4s1c.bde 150G 4.1K 138G 0% /private Mounting Existing Encrypted File Systems After each boot, any encrypted file systems must be re-attached to the kernel, checked for errors, and mounted, before the file systems can be used. The required commands must be executed as user root. Attach the gbde Partition to the Kernel &prompt.root; gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c You will be asked to provide the passphrase that you selected during initialization of the encrypted gbde partition. Check the File System for Errors Since encrypted file systems cannot yet be listed in /etc/fstab for automatic mounting, the file systems must be checked for errors by running &man.fsck.8; manually before mounting. &prompt.root; fsck -p -t ffs /dev/ad4s1c.bde Mount the Encrypted File System &prompt.root; mount /dev/ad4s1c.bde /private The encrypted file system is now available for use. Automatically Mounting Encrypted Partitions It is possible to create a script to automatically attach, check, and mount an encrypted partition, but for security reasons the script should not contain the &man.gbde.8; password. Instead, it is recommended that such scripts be run manually while providing the password via the console or &man.ssh.1;. + Cryptographic Protections Employed by gbde &man.gbde.8; encrypts the sector payload using 128-bit AES in CBC mode. Each sector on the disk is encrypted with a different AES key. For more information on gbde's cryptographic design, including how the sector keys are derived from the user-supplied passphrase, see &man.gbde.4;. Compatibility Issues &man.sysinstall.8; is incompatible with gbde-encrypted devices. All *.bde devices must be detached from the kernel before starting &man.sysinstall.8; or it will crash during its initial probing for devices. To detach the encrypted device used in our example, use the following command: &prompt.root; gbde detach /dev/ad4s1c Also note that, as &man.vinum.4; does not use the &man.geom.4; subsystem, you cannot use gbde with vinum volumes. diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml index cff134a677..365bd39125 100644 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml @@ -1,3284 +1,3286 @@ Jim Mock Restructured and parts updated by Brian N. Handy Originally contributed by Rich Murphey Linux Binary Compatibility Synopsis Linux binary compatibility binary compatibility Linux FreeBSD provides binary compatibility with several other Unix-like operating systems, including Linux. At this point, you may be asking yourself why exactly, does FreeBSD need to be able to run Linux binaries? The answer to that question is quite simple. Many companies and developers develop only for Linux, since it is the latest hot thing in the computing world. That leaves the rest of us FreeBSD users bugging these same companies and developers to put out native FreeBSD versions of their applications. The problem is, that most of these companies do not really realize how many people would use their product if there were FreeBSD versions too, and most continue to only develop for Linux. So what is a FreeBSD user to do? This is where the Linux binary compatibility of FreeBSD comes into play. In a nutshell, the compatibility allows FreeBSD users to run about 90% of all Linux applications without modification. This includes applications such as Star Office, the Linux version of Netscape, Adobe Acrobat, RealPlayer 5 and 7, VMWare, Oracle, WordPerfect, Doom, Quake, and more. It is also reported that in some situations, Linux binaries perform better on FreeBSD than they do under Linux. Linux /proc file system There are, however, some Linux-specific operating system features that are not supported under FreeBSD. Linux binaries will not work on FreeBSD if they overly use the Linux /proc file system (which is different from FreeBSD's /proc file system), or i386-specific calls, such as enabling virtual 8086 mode. After reading this chapter, you will know: How to enable Linux binary compatibility on your system. How to install additional Linux shared libraries. How to install Linux applications on your FreeBSD system. The implementation details of Linux compatibility in FreeBSD. Before reading this chapter, you should: Know how to install additional third-party software (). Installation KLD (kernel loadable object) Linux binary compatibility is not turned on by default. The easiest way to enable this functionality is to load the linux KLD object (Kernel LoaDable object). You can load this module by simply typing linux at the command prompt. If you would like Linux compatibility to always be enabled, then you should add the following line to /etc/rc.conf: linux_enable="YES" The &man.kldstat.8; command can be used to verify that the KLD is loaded: &prompt.user; kldstat Id Refs Address Size Name 1 2 0xc0100000 16bdb8 kernel 7 1 0xc24db000 d000 linux.ko kernel options LINUX If for some reason you do not want to or cannot load the KLD, then you may statically link Linux binary compatibility into the kernel by adding options LINUX to your kernel configuration file. Then install your new kernel as described in . Installing Linux Runtime Libraries Linux installing Linux libraries This can be done one of two ways, either by using the linux_base port, or by installing them manually. Installing Using the linux_base Port ports collection This is by far the easiest method to use when installing the runtime libraries. It is just like installing any other port from the ports collection. Simply do the following: &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make install distclean You should now have working Linux binary compatibility. Some programs may complain about incorrect minor versions of the system libraries. In general, however, this does not seem to be a problem. There may be multiple versions of the emulators/linux_base port available, corresponding to different versions of various Linux distributions. You should install the port most closely resembling the requirements of the Linux applications you would like to install. Installing Libraries Manually If you do not have the ports collection installed, you can install the libraries by hand instead. You will need the Linux shared libraries that the program depends on and the runtime linker. Also, you will need to create a shadow root directory, /compat/linux, for Linux libraries on your FreeBSD system. Any shared libraries opened by Linux programs run under FreeBSD will look in this tree first. So, if a Linux program loads, for example, /lib/libc.so, FreeBSD will first try to open /compat/linux/lib/libc.so, and if that does not exist, it will then try /lib/libc.so. Shared libraries should be installed in the shadow tree /compat/linux/lib rather than the paths that the Linux ld.so reports. Generally, you will need to look for the shared libraries that Linux binaries depend on only the first few times that you install a Linux program on your FreeBSD system. After a while, you will have a sufficient set of Linux shared libraries on your system to be able to run newly imported Linux binaries without any extra work. How to Install Additional Shared Libraries shared libraries What if you install the linux_base port and your application still complains about missing shared libraries? How do you know which shared libraries Linux binaries need, and where to get them? Basically, there are 2 possibilities (when following these instructions you will need to be root on your FreeBSD system). If you have access to a Linux system, see what shared libraries the application needs, and copy them to your FreeBSD system. Look at the following example: Let us assume you used FTP to get the Linux binary of Doom, and put it on a Linux system you have access to. You then can check which shared libraries it needs by running ldd linuxdoom, like so: &prompt.user; ldd linuxdoom libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 symbolic links You would need to get all the files from the last column, and put them under /compat/linux, with the names in the first column as symbolic links pointing to them. This means you eventually have these files on your FreeBSD system: /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
Note that if you already have a Linux shared library with a matching major revision number to the first column of the ldd output, you will not need to copy the file named in the last column to your system, the one you already have should work. It is advisable to copy the shared library anyway if it is a newer version, though. You can remove the old one, as long as you make the symbolic link point to the new one. So, if you have these libraries on your system: /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 and you find a new binary that claims to require a later version according to the output of ldd: libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 If it is only one or two versions out of date in the in the trailing digit then do not worry about copying /lib/libc.so.4.6.29 too, because the program should work fine with the slightly older version. However, if you like, you can decide to replace the libc.so anyway, and that should leave you with: /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
The symbolic link mechanism is only needed for Linux binaries. The FreeBSD runtime linker takes care of looking for matching major revision numbers itself and you do not need to worry about it.
Installing Linux ELF Binaries Linux ELF binaries ELF binaries sometimes require an extra step of branding. If you attempt to run an unbranded ELF binary, you will get an error message like the following: &prompt.user; ./my-linux-elf-binary ELF binary type not known Abort To help the FreeBSD kernel distinguish between a FreeBSD ELF binary from a Linux binary, use the &man.brandelf.1; utility. &prompt.user; brandelf -t Linux my-linux-elf-binary GNU toolchain The GNU toolchain now places the appropriate branding information into ELF binaries automatically, so this step should become increasingly unnecessary in the future. Configuring the Hostname Resolver If DNS does not work or you get this message: resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword You will need to configure a /compat/linux/etc/host.conf file containing: order hosts, bind multi on The order here specifies that /etc/hosts is searched first and DNS is searched second. When /compat/linux/etc/host.conf is not installed, Linux applications find FreeBSD's /etc/host.conf and complain about the incompatible FreeBSD syntax. You should remove bind if you have not configured a name server using the /etc/resolv.conf file. Murray Stokely Updated for Mathematica 4.X by Bojan Bistrovic Merged with work by Installing Mathematica applications Mathematica This document describes the process of installing the Linux version of Mathematica 4.X onto a FreeBSD system. The Linux version of Mathematica runs perfectly under FreeBSD however the binaries shipped by Wolfram need to be branded so that FreeBSD knows to use the Linux ABI to execute them. The Linux version of Mathematica or Mathematica for Students can be ordered directly from Wolfram at . Branding the Linux Binaries The Linux binaries are located in the Unix directory of the Mathematica CDROM distributed by Wolfram. You need to copy this directory tree to your local hard drive so that you can brand the Linux binaries with &man.brandelf.1; before running the installer: &prompt.root; mount /cdrom &prompt.root; cp -rp /cdrom/Unix/ /localdir/ &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm &prompt.root; cd /localdir/Installers/Linux/ &prompt.root; ./MathInstaller Alternatively, you can simply set the default ELF brand to Linux for all unbranded binaries with the command: &prompt.root; sysctl kern.fallback_elf_brand=3 This will make FreeBSD assume that unbranded ELF binaries use the Linux ABI and so you should be able to run the installer straight from the CDROM. Obtaining Your Mathematica Password Before you can run Mathematica you will have to obtain a password from Wolfram that corresponds to your machine ID. Ethernet MAC address Once you have installed the Linux compatibility runtime libraries and unpacked Mathematica you can obtain the machine ID by running the program mathinfo in the installation directory. This machine ID is based solely on the MAC address of your first Ethernet card. &prompt.root; cd /localdir/Files/SystemFiles/Installation/Binaries/Linux &prompt.root; mathinfo disco.example.com 7115-70839-20412 When you register with Wolfram, either by email, phone or fax, you will give them the machine ID and they will respond with a corresponding password consisting of groups of numbers. You can then enter this information when you attempt to run Mathematica for the first time exactly as you would for any other Mathematica platform. Running the Mathematica Frontend over a Network Mathematica uses some special fonts to display characters not present in any of the standard font sets (integrals, sums, Greek letters, etc.). The X protocol requires these fonts to be install locally. This means you will have to copy these fonts from the CDROM or from a host with Mathematica installed to your local machine. These fonts are normally stored in /cdrom/Unix/Files/SystemFiles/Fonts on the CDROM, or /usr/local/mathematica/SystemFiles/Fonts on your hard drive. The actual fonts are in the subdirectories Type1 and X. There are several ways to use them, as described below. The first way is to copy them into one of the existing font directories in /usr/X11R6/lib/X11/fonts. This will require editing the fonts.dir file, adding the font names to it, and changing the number of fonts on the first line. Alternatively, you should also just be able to run &man.mkfontdir.1; in the directory you have copied them to. The second way to do this is to copy the directories to /usr/X11R6/lib/X11/fonts: &prompt.root; cd /usr/X11R6/lib/X11/fonts &prompt.root; mkdir X &prompt.root; mkdir MathType1 &prompt.root; cd /cdrom/Unix/Files/SystemFiles/Fonts &prompt.root; cp X/* /usr/X11R6/lib/X11/fonts/X &prompt.root; cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; cd /usr/X11R6/lib/X11/fonts/X &prompt.root; mkfontdir &prompt.root; cd ../MathType1 &prompt.root; mkfontdir Now add the new font directories to your font path: &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/X &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; xset fp rehash If you are using the XFree86 server, you can have these font directories loaded automatically by adding them to your XF86Config file. fonts If you do not already have a directory called /usr/X11R6/lib/X11/fonts/Type1, you can change the name of the MathType1 directory in the example above to Type1. Aaron Kaplan Contributed by Robert Getschmann Thanks to Installing Maple applications Maple Maple is a commercial mathematics program similar to Mathematica. You must purchase this software from and then register there for a license file. To install this software on FreeBSD, please follow these simple steps. Execute the INSTALL shell script from the product distribution. Choose the RedHat option when prompted by the installation program. A typical installation directory might be /usr/local/maple. If you have not done so, order a license for Maple from Maple Waterloo Software () and copy it to /usr/local/maple/license/license.dat. Install the FLEXlm license manager by running the INSTALL_LIC install shell script that comes with Maple. Specify the primary hostname for your machine for the license server. Patch the /usr/local/maple/bin/maple.system.type file with the following: ----- snip ------------------ *** maple.system.type.orig Sun Jul 8 16:35:33 2001 --- maple.system.type Sun Jul 8 16:35:51 2001 *************** *** 72,77 **** --- 72,78 ---- # the IBM RS/6000 AIX case MAPLE_BIN="bin.IBM_RISC_UNIX" ;; + "FreeBSD"|\ "Linux") # the Linux/x86 case # We have two Linux implementations, one for Red Hat and ----- snip end of patch ----- Please note that after the "FreeBSD"|\ no other whitespace should be present. This patch instructs Maple to recognize FreeBSD as a type of Linux system. The bin/maple shell script calls the bin/maple.system.type shell script which in turn calls uname -a to find out the operating system name. Depending on the OS name it will find out which binaries to use. Start the license server. The following script, installed as /usr/local/etc/rc.d/lmgrd.sh is a convenient way to start up lmgrd: ----- snip ------------ #! /bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX export PATH LICENSE_FILE=/usr/local/maple/license/license.dat LOG=/var/log/lmgrd.log case "$1" in start) lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2 echo -n " lmgrd" ;; stop) lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2 ;; *) echo "Usage: `basename $0` {start|stop}" 1>&2 exit 64 ;; esac exit 0 ----- snip ------------ Test-start Maple: &prompt.user; cd /usr/local/maple/bin &prompt.user; ./xmaple You should be up and running. Make sure to write Maplesoft to let them know you would like a native FreeBSD version! Common Pitfalls The FLEXlm license manager can be a difficult tool to work with. Additional documentation on the subject can be found at . lmgrd is known to be very picky about the license file and to core dump if there are any problems. A correct license file should look like this: # ======================================================= # License File for UNIX Installations ("Pointer File") # ======================================================= SERVER chillig ANY #USE_SERVER VENDOR maplelmg FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \ ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \ SN=XXXXXXXXX Serial number and key 'X''ed out. chillig is a hostname. Editing the license file works as long as you do not touch the FEATURE line (which is protected by the license key). Dan Pelleg Contributed by Installing MATLAB applications MATLAB This document describes the process of installing the Linux version of MATLAB version 6.5 onto a &os; system. It works quite well, with the exception of the Java Virtual Machine (see ). The Linux version of MATLAB can be ordered directly from The MathWorks at . Make sure you also get the license file or instructions how to create it. Installing MATLAB To install MATLAB, do the following: Insert the installation CD and mount it. Become root, as recommended by the installation script. To start the installation script type: &prompt.root; /compat/linux/bin/sh /cdrom/install The installer is graphical. If you get errors about not being able to open a display, type setenv HOME ~USER, where USER is the user you did a &man.su.1; as. When asked for the MATLAB root directory, type: /compat/linux/usr/local/matlab. For easier typing on the rest of the installation process, type this at your shell prompt: set MATLAB=/compat/linux/usr/local/matlab Edit the license file as instructed when obtaining the MATLAB license. You can prepare this file in advance using your favorite editor, and copy it to $MATLAB/etc/license.dat before the installer asks you to edit it. Complete the installation process. At this point your MATLAB installation is complete. The following steps apply glue to connect it to your &os; system. License Manager Startup Create symlinks for the license manager scripts: &prompt.root; ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW &prompt.root; ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW Create a startup file at /usr/local/etc/rc.d/flexlm.sh. The example below is a modified version of the distributed $MATLAB/etc/rc.lm.glnx86. The changes are file locations, and startup of the license manager under Linux emulation. #!/bin/sh case "$1" in start) if [ -f /usr/local/etc/lmboot_TMW ]; then /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u username && echo 'MATLAB_lmgrd' fi ;; stop) if [ -f /usr/local/etc/lmdown_TMW ]; then /compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1 fi ;; *) echo "Usage: $0 {start|stop}" exit 1 ;; esac exit 0 The file must be made executable: &prompt.root; chmod +x /usr/local/etc/rc.d/flexlm.sh You must also replace username above with the name of a valid user on your system (and not root). Start the license manager with the command: &prompt.root; /usr/local/etc/rc.d/flexlm.sh start Creating a MATLAB Startup Script Place the following startup script in /usr/local/bin/matlab: #!/bin/sh /compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@" Then type the command chmod +x /usr/local/bin/matlab. Using MATLAB At this point you are ready to type matlab and start using it. Note that the version of Java shipped with MATLAB does not work under &os;. Therefore you will have to start MATLAB with either the or the switch. Marcel Moolenaar Contributed by Installing Oracle applications Oracle Preface This document describes the process of installing Oracle 8.0.5 and Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD machine. Installing the Linux Environment Make sure you have both emulators/linux_base and devel/linux_devtools from the ports collection installed. If you run into difficulties with these ports, you may have to use the packages or older versions available in the ports collection. If you want to run the intelligent agent, you will also need to install the Red Hat Tcl package: tcl-8.0.3-20.i386.rpm. The general command for installing packages with the official RPM port (archivers/rpm) is: &prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package Installation of the package should not generate any errors. Creating the Oracle Environment Before you can install Oracle, you need to set up a proper environment. This document only describes what to do specially to run Oracle for Linux on FreeBSD, not what has been described in the Oracle installation guide. Kernel Tuning kernel tuning As described in the Oracle installation guide, you need to set the maximum size of shared memory. Do not use SHMMAX under FreeBSD. SHMMAX is merely calculated out of SHMMAXPGS and PGSIZE. Therefore define SHMMAXPGS. All other options can be used as described in the guide. For example: options SHMMAXPGS=10000 options SHMMNI=100 options SHMSEG=10 options SEMMNS=200 options SEMMNI=70 options SEMMSL=61 Set these options to suit your intended use of Oracle. Also, make sure you have the following options in your kernel configuration file: options SYSVSHM #SysV shared memory options SYSVSEM #SysV semaphores options SYSVMSG #SysV interprocess communication Oracle Account Create an oracle account just as you would create any other account. The oracle account is special only that you need to give it a Linux shell. Add /compat/linux/bin/bash to /etc/shells and set the shell for the oracle account to /compat/linux/bin/bash. Environment Besides the normal Oracle variables, such as ORACLE_HOME and ORACLE_SID you must set the following environment variables: Variable Value LD_LIBRARY_PATH $ORACLE_HOME/lib CLASSPATH $ORACLE_HOME/jdbc/lib/classes111.zip PATH /compat/linux/bin /compat/linux/sbin /compat/linux/usr/bin /compat/linux/usr/sbin /bin /sbin /usr/bin /usr/sbin /usr/local/bin $ORACLE_HOME/bin It is advised to set all the environment variables in .profile. A complete example is: ORACLE_BASE=/oracle; export ORACLE_BASE ORACLE_HOME=/oracle; export ORACLE_HOME LD_LIBRARY_PATH=$ORACLE_HOME/lib export LD_LIBRARY_PATH ORACLE_SID=ORCL; export ORACLE_SID ORACLE_TERM=386x; export ORACLE_TERM CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip export CLASSPATH PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin export PATH Installing Oracle Due to a slight inconsistency in the Linux emulator, you need to create a directory named .oracle in /var/tmp before you start the installer. Either make it world writable or let it be owned by the oracle user. You should be able to install Oracle without any problems. If you have problems, check your Oracle distribution and/or configuration first! After you have installed Oracle, apply the patches described in the next two subsections. A frequent problem is that the TCP protocol adapter is not installed right. As a consequence, you cannot start any TCP listeners. The following actions help solve this problem: &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk ntcontab.o &prompt.root; cd $ORACLE_HOME/lib &prompt.root; ar r libnetwork.a ntcontab.o &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk install Do not forget to run root.sh again! Patching root.sh When installing Oracle, some actions, which need to be performed as root, are recorded in a shell script called root.sh. This script is written in the orainst directory. Apply the following patch to root.sh, to have it use to proper location of chown or alternatively run the script under a Linux native shell. *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 --- orainst/root.sh Mon Dec 28 15:58:53 1998 *************** *** 31,37 **** # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/bin/chown # # Define variables to be used in this script --- 31,37 ---- # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/usr/sbin/chown # # Define variables to be used in this script When you do not install Oracle from CD, you can patch the source for root.sh. It is called rthd.sh and is located in the orainst directory in the source tree. Patching genclntsh The script genclntsh is used to create a single shared client library. It is used when building the demos. Apply the following patch to comment out the definition of PATH: *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 --- bin/genclntsh Tue Dec 22 15:36:49 1998 *************** *** 32,38 **** # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst --- 32,38 ---- # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst Running Oracle When you have followed the instructions, you should be able to run Oracle as if it was run on Linux itself. Holger Kipp Contributed by Valentino Vaschetto Original version converted to SGML by Installing SAP R/3 applications SAP R/3 Installations of SAP Systems using FreeBSD will not be supported by the SAP support team — they only offer support for certified platforms. Preface This document describes a possible way of installing a SAP R/3-System with Oracle Database for Linux onto a FreeBSD machine, including the installation of FreeBSD and Oracle. Two different configurations will be described: SAP R/3 4.6B (IDES) with Oracle 8.0.5 on FreeBSD 4.3-STABLE SAP R/3 4.6C with Oracle 8.1.7 on FreeBSD 4.5-STABLE Even though this document tries to describe all important steps in a greater detail, it is not intended as a replacement for the Oracle and SAP R/3 installation guides. Please see the documentation that comes with the SAP R/3 Linux edition for SAP- and Oracle-specific questions, as well as resources from Oracle and SAP OSS. Software The following CD-ROMs have been used for SAP-installations: SAP R/3 4.6B, Oracle 8.0.5 Name Number Description KERNEL 51009113 SAP Kernel Oracle / Installation / AIX, Linux, Solaris RDBMS 51007558 Oracle / RDBMS 8.0.5.X / Linux EXPORT1 51010208 IDES / DB-Export / Disc 1 of 6 EXPORT2 51010209 IDES / DB-Export / Disc 2 of 6 EXPORT3 51010210 IDES / DB-Export / Disc 3 of 6 EXPORT4 51010211 IDES / DB-Export / Disc 4 of 6 EXPORT5 51010212 IDES / DB-Export / Disc 5 of 6 EXPORT6 51010213 IDES / DB-Export / Disc 6 of 6 Additionally, I used the Oracle 8 Server (Pre-production version 8.0.5 for Linux, Kernel Version 2.0.33) CD which is not really necessary, and of course FreeBSD 4.3-STABLE (it was only a few days past 4.3 RELEASE). SAP R/3 4.6C SR2, Oracle 8.1.7 Name Number Description KERNEL 51014004 SAP Kernel Oracle / SAP Kernel Version 4.6D / DEC, Linux RDBMS 51012930 Oracle 8.1.7/ RDBMS / Linux EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 1 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 2 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 3 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 4 of 4 LANG1 51013954 Release 4.6C SR2 / Language / DE, EN, FR / Disc 1 of 3 Depending on the languages you would like to install, additional language CDs might be necessary. Here we're just using DE and EN, so the first Language-CD is the only one needed. As a little note, the numbers for all four export CDs are identical. All three language CDs also have the same number (this is different from the 4.6B IDES release CD numbering). At the time of writing this installation is running on FreeBSD 4.5-STABLE (20.03.2002). SAP Notes The following notes should be read before installing SAP R/3 or proved to be useful during installation: SAP R/3 4.6B, Oracle 8.0.5 Number Title 0171356 SAP Software on Linux: Essential Comments 0201147 INST: 4.6C R/3 Inst. on UNIX - Oracle 0373203 Update / Migration Oracle 8.0.5 --> 8.0.6/8.1.6 LINUX 0072984 Release of Digital UNIX 4.0B for Oracle 0130581 R3SETUP step DIPGNTAB terminates 0144978 Your system has not been installed correctly 0162266 Questions and tips for R3SETUP on Windows NT / W2K SAP R/3 4.6C, Oracle 8.1.7 Number Title 0015023 Initializing table TCPDB (RSXP0004) (EBCDIC) 0045619 R/3 with several languages or typefaces 0171356 SAP Software on Linux: Essential Comments 0195603 RedHat 6.1 Enterprise version: Known problems 0212876 The new archiving tool SAPCAR 0300900 Linux: Released DELL Hardware 0377187 RedHat 6.2: important remarks 0387074 INST: R/3 4.6C SR2 Installation on UNIX 0387077 INST: R/3 4.6C SR2 Inst. on UNIX - Oracle 0387078 SAP Software on UNIX: OS Dependencies 4.6C SR2 Hardware Requirements The following equipment is sufficient for the installation of a SAP R/3 System. For production use, a more exact sizing is of course needed: Component 4.6B 4.6C Processor 2 x 800MHz Pentium III 2 x 800MHz Pentium III Memory 1GB ECC 2GB ECC Hard Disk Space 50-60GB (IDES) 50-60GB (IDES) For use in production, Xeon-Processors with large cache, high-speed disk access (SCSI, RAID hardware controller), USV and ECC-RAM is recommended. The large amount of hard disk space is due to the preconfigured IDES System, which creates 27 GB of database files during installation. This space is also sufficient for initial production systems and application data. SAP R/3 4.6B, Oracle 8.0.5 The following off-the-shelf hardware was used: a dual processor board with 2 800 MHz Pentium III processors, Adaptec 29160 Ultra160 SCSI adapter (for accessing a 40/80 GB DLT tape drive and CDROM), Mylex AcceleRAID (2 channels, firmware 6.00-1-00 with 32 MB RAM). To the Mylex Raid-controller are attached two 17 GB hard disks (mirrored) and four 36 GB hard disks (RAID level 5). SAP R/3 4.6C, Oracle 8.1.7 For this installation a DELL PowerEdge 2500 was used: a dual processor board with two 1000 MHz Pentium III processors (256 kB Cache), 2 GB PC133 ECC SDRAM, PERC/3 DC PCI Raid Controller with 128 MB, and an EIDE DVD-ROM drive. To the RAID-controller are attached two 18 GB hard disks (mirrored) and four 36 GB hard disks (RAID level 5). Installation of FreeBSD First you have to install FreeBSD. There are several ways to do this (FreeBSD 4.3 was installed via FTP, FreeBSD 4.5 directly from release-CD). Disk Layout To keep it simple, the same disk layout both for the SAP R/3 46B- and SAP R/3 46C SR2-installation was used. Only the device names changed, as the installations were on different hardware (/dev/da and /dev/amr respectively, so if using an AMI MegaRAID, one will see /dev/amr0s1a instead of /dev/da0s1a): File system Size (1k-blocks) Size (GB) Mounted on /dev/da0s1a 1.016.303 1 / /dev/da0s1b 6 swap /dev/da0s1e 2.032.623 2 /var /dev/da0s1f 8.205.339 8 /usr /dev/da1s1e 45.734.361 45 /compat/linux/oracle /dev/da1s1f 2.032.623 2 /compat/linux/sapmnt /dev/da1s1g 2.032.623 2 /compat/linux/usr/sap Configure and initialize the two logical drives with the Mylex- or PERC/3 RAID software beforehand. The software can be started during the bios boot phase. Please note that this disk layout differs slightly from the SAP recommendations, as SAP suggests mounting the oracle-subdirectories (and some others) separately - I decided to just create them as real subdirectories for simplicity. <command>make world</command> and a New Kernel Download the latest stable-sources. Rebuild world and your custom kernel after configuring your kernel configuration file. Here you should also include the kernel parameters which are required for both SAP R/3 and Oracle. Installing the Linux Environment During the first installation with FreeBSD 4.3-STABLE I had some trouble downloading the required RPM-files (for 4.3 stable, 2nd May 2001), but with FreeBSD 4.5-STABLE, everything went very smooth. Should you encounter some problems, try to download those files by hand. For a list of RPM-Mirrors and required files, see the corresponding makefile. Installing the Linux Base System First the linux_base port needs to be installed (as root). This is currently linux_base-6. &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make package Installing Linux Development The Linux development is needed, if you want to install Oracle on FreeBSD according to the corresponding description in the handbook: &prompt.root; cd /usr/ports/devel/linux_devtools &prompt.root; make package Linux Development has only been installed for the SAP R/3 46B IDES-installation. It is not needed, if the Oracle DB is not relinked on the FreeBSD system. This is the case if you are using the Oracle tarball from a Linux system. Installing the Necessary RPMs RPMs To start the R3SETUP-Program, PAM support is needed. During the first SAP-Installation on FreeBSD 4.3-STABLE I tried to install PAM with all the required packages and finally forced the installation of the PAM package, which worked. For SAP R/3 4.6C SR2 I directly forced the installation of the PAM-RPM, which also works, so it seems the dependent packages are not needed: &prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \ pam-0.68-7.i386.rpm For Oracle 8.0.5 to run the intelligent agent, I also had to install the RedHat Tcl package tcl-8.0.5-30.i386.rpm (otherwise the relinking during Oracle install will not work). There are some other issues regarding relinking of Oracle, but that is a Oracle-Linux issue, not FreeBSD specific. Some Additional Hints It might also be a good idea to add linprocfs to /etc/fstab. See man linprocfs. Another parameter to set is kern.fallback_elf_brand=3 which is done in file /etc/sysctl.conf. Creating the SAP/R3 Environment Creating the Necessary File Systems and Mountpoints For a simple installation, it is sufficient to create the following file systems: mount point size in GB /compat/linux/oracle 45 GB /compat/linux/sapmnt 2 GB /compat/linux/usr/sap 2 GB It is also necessary to created some links. Otherwise the SAP-Installer will complain, as it is checking the created links: &prompt.root; ln -s /compat/linux/oracle /oracle &prompt.root; ln -s /compat/linux/sapmnt /sapmnt &prompt.root; ln -s /compat/linux/usr/sap /usr/sap Possible error message during installation (here with System PRD and the SAP R/3 4.6C SR2 installation): INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200 Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to /sapmnt/PRD/exe. Creating if it does not exist... WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400 Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The program cannot go on as long as this link exists at this location. Move the link to another location. ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0 can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content '/sapmnt/PRD/exe' Creating Users and Directories SAP R/3 needs two users and three groups. The user names depend on the SAP system id (SID) which consists of three letters. Some of these SIDs are reserved by SAP (for example SAP and NIX. For a complete list please see the SAP documentation). For the IDES installation I used IDS, for the 4.6C SR2 installation PRD, as that system is intended for production use. We have therefore the following groups (group ids might differ, these are just the values I used with my installation): group id group name description 100 dba Data Base Administrator 101 sapsys SAP System 102 oper Data Base Operator For a default Oracle-Installation, only group dba is used. As oper-group, one also uses group dba (see Oracle- and SAP-documentation for further information). We also need the following users: user id user name generic name group additional groups description 1000 idsadm/prdadm sidadm sapsys oper SAP Administrator 1002 oraids/oraprd orasid dba oper DB Administrator Adding the users with adduser requires the following (please note shell and home directory) entries for SAP-Administrator: Name: sidadm Password: ****** Fullname: SAP Administrator SID Uid: 1000 Gid: 101 (sapsys) Class: Groups: sapsys dba HOME: /home/sidadm Shell: bash (/compat/linux/bin/bash) and for Database-Administrator: Name: orasid Password: ****** Fullname: Oracle Administrator SID Uid: 1002 Gid: 100 (dba) Class: Groups: dba HOME: /oracle/sid Shell: bash (/compat/linux/bin/bash) This should also include group oper in case you are using both groups dba and oper. Creating Directories These directories are usually created as separate file systems. This depends entirely on your requirements. I choose to create them as simple directories, as they are all located on the same RAID 5 anyway: First we will set owners and rights of some directories (as user root): &prompt.root; chmod 775 /oracle &prompt.root; chmod 777 /sapmnt &prompt.root; chown root:dba /oracle &prompt.root; chown sidadm:sapsys /compat/linux/usr/sap &prompt.root; chmod 775 /compat/linux/usr/sap Second we will create directories as user orasid. These will all be subdirectories of /oracle/SID: &prompt.root; su - orasid &prompt.root; cd /oracle/SID &prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB &prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6 &prompt.root; mkdir saparch sapreorg &prompt.root; exit For the Oracle 8.1.7-installation some additional directories are needed: &prompt.root; su - orasid &prompt.root; cd /oracle &prompt.root; mkdir 805_32 &prompt.root; mkdir client stage &prompt.root; mkdir client/80x_32 &prompt.root; mkdir stage/817_32 &prompt.root; cd /oracle/SID &prompt.root; mkdir 817_32 The directory client/80x_32 is used with exactly this name. Don't replace the x with some number or anything. In the third step we create directories as user sidadm: &prompt.root; su - sidadm &prompt.root; cd /usr/sap &prompt.root; mkdir SID &prompt.root; mkdir trans &prompt.root; exit Entries in /etc/services SAP R/3 requires some entries in file /etc/services, which will not be set correctly during installation under FreeBSD. Please add the following entries (you need at least those entries corresponding to the instance number - in this case, 00. It will do no harm adding all entries from 00 to 99 for dp, gw, sp and ms). If you are going to use a saprouter or need to access SAP OSS, you also need 99, as port 3299 is usually used for the saprouter process on the target system: sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number sapsp00 3400/tcp # 3400 + Instance-Number sapms00 3500/tcp # 3500 + Instance-Number sapmsSID 3600/tcp # SAP Message Server. 3600 + Instance-Number sapgw00s 4800/tcp # SAP Secure Gateway 4800 + Instance-Number Necessary Locales locale SAP requires at least two locales that are not part of the default RedHat installation. SAP offers the required RPMs as download from their FTP-server (which is only accessible if you are a customer with OSS-access). See note 0171356 for a list of RPMs you need. It is also possible to just create appropriate links (for example from de_DE and en_US ), but I would not recommend this for a production system (so far it worked with the IDES system without any problems, though). The following locales are needed: de_DE.ISO-8859-1 en_US.ISO-8859-1 Create the links like this: &prompt.root; cd /compat/linux/usr/share/locale &prompt.root; ln -s de_DE de_DE.ISO-8859-1 &prompt.root; ln -s en_US en_US.ISO-8859-1 If they are not present, there will be some problems during the installation. If these are then subsequently ignored (by setting the status of the offending steps to OK in file CENTRDB.R3S), it will be impossible to log onto the SAP-system without some additional effort. Kernel Tuning kernel tuning SAP R/3 Systems need a lot of resources. I therefore added the following parameters to my kernel config-file: # Set these for memory pigs (SAP and Oracle): options MAXDSIZ="(1024*1024*1024)" options DFLDSIZ="(1024*1024*1024)" # System V options needed. options SYSVSHM #SYSV-style shared memory options SHMMAXPGS=262144 #max amount of shared mem. pages #options SHMMAXPGS=393216 #use this for the 46C inst.parameters options SHMMNI=256 #max number of shared memory ident if. options SHMSEG=100 #max shared mem.segs per process options SYSVMSG #SYSV-style message queues options MSGSEG=32767 #max num. of mes.segments in system options MSGSSZ=32 #size of msg-seg. MUST be power of 2 options MSGMNB=65535 #max char. per message queue options MSGTQL=2046 #max amount of msgs in system options SYSVSEM #SYSV-style semaphores options SEMMNU=256 #number of semaphore UNDO structures options SEMMNS=1024 #number of semaphores in system options SEMMNI=520 #number of semaphore identifiers options SEMUME=100 #number of UNDO keys The minimum values are specified in the documentation that comes from SAP. As there is no description for Linux, see the HP-UX-section (32-bit) for further information. As the system for the 4.6C SR2 installation has more main memory, the shared segments can be larger both for SAP and Oracle, therefore choose a larger number of shared memory pages. With the default installation of FreeBSD 4.5 on x386, leave MAXDSIZ and DFLDSIZ at 1 GB maximum. Otherwise, strange errors like ORA-27102: out of memory and Linux Error: 12: Cannot allocate memory might happen. Installing SAP R/3 Preparing SAP CDROMs There are many CDROMs to mount and unmount during the installation. Assuming you have enough CDROM-drives, you can just mount them all. I decided to copy the CDROM contents to corresponding directories: /oracle/SID/sapreorg/cd-name where cd-name was one of KERNEL, RDBMS, EXPORT1, EXPORT2, EXPORT3, EXPORT4, EXPORT5 and EXPORT6 for the 4.6B/IDES-installation, and KERNEL, RDBMS, DISK1, DISK2, DISK3, DISK4 and LANG for the 4.6C SR2-installation. All the filenames on the mounted CDs should be in capital letters, otherwise use the option for mounting. So use the following commands: &prompt.root; mount_cd9660 -g /dev/cd0a /mnt &prompt.root; cp -R /mnt/* /oracle/SID/sapreorg/cd-name &prompt.root; umount /mnt Running the Install Script First you have to prepare an install-directory: &prompt.root; cd /oracle/SID/sapreorg &prompt.root; mkdir install &prompt.root; cd install Then the install-script is started, which will copy nearly all the relevant files into the install-directory: &prompt.root; /oracle/SID/sapreorg/KERNEL/UNIX/INSTTOOL.SH The IDES-Installation (4.6B) comes with a fully customized SAP R/3 Demo-System, so there are six instead of just three EXPORT-CDs. At this point the installation template CENTRDB.R3S is for installing a standard central instance (R/3 and Database), not the IDES central instance, so one needs to copy the corresponding CENTRDB.R3S from the EXPORT1 directory, otherwise R3SETUP will only ask for three EXPORT-CDs. The newer SAP 4.6C SR2-release comes with four EXPORT-CDs. The parameter-file that controls the installation-steps is CENTRAL.R3S. Contrary to earlier releases there are no separate installation templates for a central instance with or without database. SAP is using a separate template for DB-installation. To restart the installation later it is however sufficient to restart with the original file. During and after installation, SAP requires hostname to return the computer name only, not the fully qualified domain name. So either set the hostname accordingly, or set an alias with alias hostname='hostname -s' for both orasid and sidadm (and for root at least during installation steps performed as root). It is also possible to adjust the installed profile- and login-scripts of both users that are installed during SAP-installation. Start R3SETUP 4.6B Make sure LD_LIBRARY_PATH is set correctly: &prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib Start R3SETUP as root from installation directory: &prompt.root; cd /oracle/IDS/sapreorg/install &prompt.root; ./R3SETUP -f CENTRDB.R3S The script then asks some questions (defaults in brackets, followed by actual input): Question Default Input Enter SAP System ID [C11] IDSEnter Enter SAP Instance Number [00] Enter Enter SAPMOUNT Directory [/sapmnt] Enter Enter name of SAP central host [troubadix.domain.de] Enter Enter name of SAP db host [troubadix] Enter Select character set [1] (WE8DEC) Enter Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6 1Enter Extract Oracle Client archive [1] (Yes, extract) Enter Enter path to KERNEL CD [/sapcd] /oracle/IDS/sapreorg/KERNEL Enter path to RDBMS CD [/sapcd] /oracle/IDS/sapreorg/RDBMS Enter path to EXPORT1 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT1 Directory to copy EXPORT1 CD [/oracle/IDS/sapreorg/CD4_DIR] Enter Enter path to EXPORT2 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT2 Directory to copy EXPORT2 CD [/oracle/IDS/sapreorg/CD5_DIR] Enter Enter path to EXPORT3 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT3 Directory to copy EXPORT3 CD [/oracle/IDS/sapreorg/CD6_DIR] Enter Enter path to EXPORT4 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT4 Directory to copy EXPORT4 CD [/oracle/IDS/sapreorg/CD7_DIR] Enter Enter path to EXPORT5 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT5 Directory to copy EXPORT5 CD [/oracle/IDS/sapreorg/CD8_DIR] Enter Enter path to EXPORT6 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT6 Directory to copy EXPORT6 CD [/oracle/IDS/sapreorg/CD9_DIR] Enter Enter amount of RAM for SAP + DB 850Enter (in Megabytes) Service Entry Message Server [3600] Enter Enter Group-ID of sapsys [101] Enter Enter Group-ID of oper [102] Enter Enter Group-ID of dba [100] Enter Enter User-ID of sidadm [1000] Enter Enter User-ID of orasid [1002] Enter Number of parallel procs [2] Enter If you had not copied the CDs to the different locations, then the SAP-Installer cannot find the CD needed (identified by the LABEL.ASC-File on CD) and would then ask you to insert and mount the CD and confirm or enter the mount path. The CENTRDB.R3S might not be error-free. In my case, it requested EXPORT4 again (but indicated the correct key (6_LOCATION, then 7_LOCATION etc.), so one can just continue with entering the correct values. Do not get irritated. Apart from some problems mentioned below, everything should go straight through up to the point where the Oracle database software needs to be installed. Start R3SETUP 4.6C SR2 Make sure LD_LIBRARY_PATH is set correctly. This is a different value from the 4.6B installation with Oracle 8.0.5: &prompt.root; export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib Start R3SETUP as user root from installation directory: &prompt.root; cd /oracle/PRD/sapreorg/install &prompt.root; ./R3SETUP -f CENTRAL.R3S The script then asks some questions (defaults in brackets, followed by actual input): Question Default Input Enter SAP System ID [C11] PRDEnter Enter SAP Instance Number [00] Enter Enter SAPMOUNT Directory [/sapmnt] Enter Enter name of SAP central host [majestix] Enter Enter Database System ID [PRD] PRDEnter Enter name of SAP db host [majestix] Enter Select character set [1] (WE8DEC) Enter Enter Oracle server version (2) Oracle 8.1.7 2Enter Extract Oracle Client archive [1] (Yes, extract) Enter Enter path to KERNEL CD [/sapcd] /oracle/PRD/sapreorg/KERNEL Enter amount of RAM for SAP + DB 2044 1800Enter (in Megabytes) Service Entry Message Server [3600] Enter Enter Group-ID of sapsys [100] Enter Enter Group-ID of oper [101] Enter Enter Group-ID of dba [102] Enter Enter User-ID of oraprd [1002] Enter Enter User-ID of prdadm [1000] Enter LDAP support 3Enter (no support) Installation step completed [1] (continue) Enter Choose installation service [1] (DB inst,file) Enter So far, creation of users gives an error during installation in phases OSUSERDBSID_IND_ORA (for creating user orasid) and OSUSERSIDADM_IND_ORA (creating user sidadm). Apart from some problems mentioned below, everything should go straight through up to the point where the Oracle database software needs to be installed. Installing Oracle 8.0.5 Please see the corresponding SAP-Notes and Oracle Readmes regarding Linux and Oracle DB for possible problems. Most if not all problems stem from incompatible libraries. For more information on installing Oracle, refer to the Installing Oracle chapter. Installing the Oracle 8.0.5 with orainst If Oracle 8.0.5 is to be used, some additional libraries are needed for successfully relinking, as Oracle 8.0.5 was linked with an old glibc (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So you have to install the following additional packages to ensure that linking will work: compat-libs-5.2-2.i386.rpm compat-glibc-5.2-2.0.7.2.i386.rpm compat-egcs-5.2-1.0.3a.1.i386.rpm compat-egcs-c++-5.2-1.0.3a.1.i386.rpm compat-binutils-5.2-2.9.1.0.23.1.i386.rpm See the corresponding SAP-Notes or Oracle Readmes for further information. If this is no option (at the time of installation I did not have enough time to check this), one could use the original binaries, or use the relinked binaries from an original RedHat System. For compiling the intelligent agent, the RedHat Tcl package must be installed. If you cannot get tcl-8.0.3-20.i386.rpm, a newer one like tcl-8.0.5-30.i386.rpm for RedHat 6.1 should also do. Apart from relinking, the installation is straightforward: &prompt.root; su - oraids &prompt.root; export TERM=xterm &prompt.root; export ORACLE_TERM=xterm &prompt.root; export ORACLE_HOME=/oracle/IDS &prompt.root; cd /ORACLE_HOME/orainst_sap &prompt.root; ./orainst Confirm all Screens with Enter until the software is installed, except that one has to deselect the Oracle On-Line Text Viewer, as this is not currently available for Linux. Oracle then wants to relink with i386-glibc20-linux-gcc instead of the available gcc, egcs or i386-redhat-linux-gcc . Due to time constrains I decided to use the binaries from an Oracle 8.0.5 PreProduction release, after the first attempt at getting the version from the RDBMS-CD working, failed, and finding and accessing the correct RPMs was a nightmare at that time. Installing the Oracle 8.0.5 Pre-production Release for Linux (Kernel 2.0.33) This installation is quite easy. Mount the CD, start the installer. It will then ask for the location of the Oracle home directory, and copy all binaries there. I did not delete the remains of my previous RDBMS-installation tries, though. Afterwards, Oracle Database could be started with no problems. Installing the Oracle 8.1.7 Linux Tarball Take the tarball oracle81732.tgz you produced from the installation directory on a Linux system and untar it to /oracle/SID/817_32/. Continue with SAP R/3 Installation First check the environment settings of users idsamd (sidadm) and oraids (orasid). They should now both have the files .profile, .login and .cshrc which are all using hostname. In case the system's hostname is the fully qualified name, you need to change hostname to hostname -s within all three files. Database Load Afterwards, R3SETUP can either be restarted or continued (depending on whether exit was chosen or not). R3SETUP then creates the tablespaces and loads the data (for 46B IDES, from EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) with R3load into the database. When the database load is finished (might take a few hours), some passwords are requested. For test installations, one can use the well known default passwords (use different ones if security is an issue!): Question Input Enter Password for sapr3 sapEnter Confirum Password for sapr3 sapEnter Enter Password for sys change_on_installEnter Confirm Password for sys change_on_installEnter Enter Password for system managerEnter Confirm Password for system managerEnter At this point I had a few problems with dipgntab during the 4.6B installation. Listener Start the Oracle-Listener as user orasid as follows: &prompt.user; umask 0; lsnrctl start Otherwise you might get ORA-12546 as the sockets will not have the correct permissions. See SAP note 072984. Updating MNLS Tables If you plan to import non-Latin-1 languages into the SAP-System, you have to update the Multi National Language Support tables. This is described in the SAP OSS-Notes 15023 and 45619. Otherwise, you can skip this question during SAP installation. If you don't need MNLS, it is still necessary to check table TCPDB and initializing it if this hasn't been done. See SAP note 0015023 and 0045619 for further information. Post-installation Steps Request SAP R/3 License Key You have to request your SAP R/3 License Key. This is needed, as the temporary license that was installed during installation is only valid for four weeks. First get the hardware key. Log on as user idsadm and call saplicense: &prompt.root; /sapmnt/IDS/exe/saplicense -get Calling saplicense without options gives a list of options. Upon receiving the license key, it can be installed using: &prompt.root; /sapmnt/IDS/exe/saplicense -install You are then required to enter the following values: SAP SYSTEM ID = SID, 3 chars CUSTOMER KEY = hardware key, 11 chars INSTALLATION NO = installation, 10 digits EXPIRATION DATE = yyyymmdd, usually "99991231" LICENSE KEY = license key, 24 chars Creating Users Create a user within client 000 (for some tasks required to be done within client 000, but with a user different from users sap* and ddic). As a user name, I usually choose wartung (or service in English). Profiles required are sap_new and sap_all. For additional safety the passwords of default users within all clients should be changed (this includes users sap* and ddic). Configure Transport System, Profile, Operation Modes, Etc. Within client 000, user different from ddic and sap*, do at least the following: Task Transaction Configure Transport System, eg as Stand-Alone Transport Domain Entity STMS Create / Edit Profile for System RZ10 Maintain Operation Modes and Instances RZ04 These and all the other post-installation steps are thoroughly described in SAP installation guides. Edit init<replaceable>sid</replaceable>.sap (initIDS.sap) The file /oracle/IDS/dbs/initIDS.sap contains the SAP backup profile. Here the size of the tape to be used, type of compression and so on need to be defined. To get this running with sapdba / brbackup, I changed the following values: compress = hardware archive_function = copy_delete_save cpio_flags = "-ov --format=newc --block-size=128 --quiet" cpio_in_flags = "-iuv --block-size=128 --quiet" tape_size = 38000M tape_address = /dev/nsa0 tape_address_rew = /dev/sa0 Explanations: compress The tape I use is a HP DLT1 which does hardware compression. archive_function This defines the default behavior for saving Oracle archive logs: New logfiles are saved to tape, already saved logfiles are saved again and are then deleted. This prevents lots of trouble if you need to recover the database, and one of the archive-tapes has gone bad. cpio_flags Default is to use -B which sets block size to 5120 Bytes. For DLT-Tapes, HP recommends at least 32 K block size, so I used --block-size=128 for 64 K. --format=newc is needed I have inode numbers greater than 65535. The last option --quiet is needed as otherwise brbackup complains as soon as cpio outputs the numbers of blocks saved. cpio_in_flags Flags needed for loading data back from tape. Format is recognized automatically. tape_size This usually gives the raw storage capability of the tape. For security reason (we use hardware compression), the value is slightly lower than the actual value. tape_address The non-rewindable device to be used with cpio. tape_address_rew The rewindable device to be used with cpio. Configuration Issues after Installation The following SAP-parameters should be tuned after installation (examples for IDES 46B, 1 GB memory): Name Value ztta/roll_extension 250000000 abap/heap_area_dia 300000000 abap/heap_area_nondia 400000000 em/initial_size_MB 256 em/blocksize_kB 1024 ipc/shm_psize_40 70000000 SAP-Note 0013026: Name Value + ztta/dynpro_area 2500000 SAP-Note 0157246: Name Value + rdisp/ROLL_MAXFS 16000 rdisp/PG_MAXFS 30000 With the above parameters, on a system with 1 gigabyte of memory, one may find memory consumption similar to: Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free Problems during Installation Restart R3SETUP after Fixing a Problem R3SETUP stops if it encounters an error. If you have looked at the corresponding logfiles and fixed the error, you have to start R3SETUP again, usually selecting REPEAT as option for the last step R3SETUP complained about. To restart R3SETUP, just start it with the corresponding R3S-file: &prompt.root; ./R3SETUP -f CENTRDB.R3S for 4.6B, or with &prompt.root; ./R3SETUP -f CENTRAL.R3S for 4.6C, no matter whether the error occurred with CENTRAL.R3S or DATABASE.R3S. At some stages, R3SETUP assumes that both database- and SAP-processes are up and running (as those were steps it already completed). Should errors occur and for example the database could not be started, you have to start both database and SAP by hand after you fixed the errors and before starting R3SETUP again. Don't forget to also start the oracle listener again (as orasid with umask 0; lsnrctl start) if it was also stopped (for example due to a necessary reboot of the system). OSUSERSIDADM_IND_ORA during R3SETUP If R3SETUP complains at this stage, edit the template file R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S (4.6C)). Locate [OSUSERSIDADM_IND_ORA] or search for the only STATUS=ERROR-entry and edit the following values: HOME=/home/sidadm (was empty) STATUS=OK (had status ERROR) Then you can restart R3SETUP again. OSUSERDBSID_IND_ORA during R3SETUP Possibly R3SETUP also complains at this stage. The error here is similar to the one in phase OSUSERSIDADM_IND_ORA. Just edit the template file R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S (4.6C)). Locate [OSUSERDBSID_IND_ORA] or search for the only STATUS=ERROR-entry and edit the following value in that section: STATUS=OK Then restart R3SETUP. <errorname>oraview.vrf FILE NOT FOUND</errorname> during Oracle Installation You have not deselected Oracle On-Line Text Viewer before starting the installation. This is marked for installation even though this option is currently not available for Linux. Deselect this product inside the Oracle installation menu and restart installation. <errorname>TEXTENV_INVALID</errorname> during R3SETUP, RFC or SAPGUI Start If this error is encountered, the correct locale is missing. SAP note 0171356 lists the necessary RPMs that need be installed (eg saplocales-1.0-3, saposcheck-1.0-1 for RedHat 6.1). In case you ignored all the related errors and set the corresponding status from ERROR to OK (in CENTRDB.R3S) every time R3SETUP complained and just restarted R3SETUP, the SAP-System will not be properly configured and you will then not be able to connect to the system with a sapgui, even though the system can be started. Trying to connect with the old Linux sapgui gave the following messages: Sat May 5 14:23:14 2001 *** ERROR => no valid userarea given [trgmsgo. 0401] Sat May 5 14:23:22 2001 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410] *** ERROR => Error when generating text environment. [trgmsgi. 0435] *** ERROR => function failed [trgmsgi. 0447] *** ERROR => no socket operation allowed [trxio.c 3363] Speicherzugriffsfehler This behavior is due to SAP R/3 being unable to correctly assign a locale and also not being properly configured itself (missing entries in some database tables). To be able to connect to SAP, add the following entries to file DEFAULT.PFL (see note 0043288): abap/set_etct_env_at_new_mode = 0 install/collate/active = 0 rscp/TCP0B = TCP0B Restart the SAP system. Now you can connect to the system, even though country-specific language settings might not work as expected. After correcting country-settings (and providing the correct locales), these entries can be removed from DEFAULT.PFL and the SAP system can be restarted. <errorcode>ORA-00001</errorcode> This error only happened with Oracle 8.1.7 on FreeBSD 4.5. The reason was that the Oracle database could not initialize itself properly and crashed, leaving semaphores and shared memory on the system. The next try to start the database then returned ORA-00001. Find them with ipcs -a and remove them with ipcrm. <errorcode>ORA-00445</errorcode> (Background Process PMON Did Not Start) This error happened with Oracle 8.1.7. This error is reported if the Database is started with the usual startsap-script (for example startsap_majestix_00) as user prdadm. A possible workaround is to start the database as user oraprd instead with svrmgrl: &prompt.user; svrmgrl SVRMGR> connect internal; SVRMGR> startup; SVRMGR> exit <errorcode>ORA-12546</errorcode> (Start Listener with Correct Permissions) Start the Oracle Listener as user oraids with the following commands: &prompt.root; umask 0; lsnrctl start Otherwise you might get ORA-12546 as the sockets will not have the correct permissions. See SAP note 0072984. <errorcode>ORA-27102</errorcode> (Out of Memory) This error happened whilst trying to use values for MAXDSIZ and DFLDSIZ greater than 1 GB (1024x1024x1024). Additionally, I got Linux Error 12: Cannot allocate memory. [DIPGNTAB_IND_IND] during R3SETUP In general, see SAP note 0130581 (R3SETUP step DIPGNTAB terminates). During the IDES-specific installation, for some reasons the installation process was not using the proper SAP system name IDS, but the empty string "" instead. This lead to some minor problems with accessing directories, as the paths are generated dynamically using SID (in this case IDS). So instead of accessing: /usr/sap/IDS/SYS/... /usr/sap/IDS/DVMGS00 the following paths were used: /usr/sap//SYS/... /usr/sap/D00 To continue with the installation, I created a link and an additional directory: &prompt.root; pwd /compat/linux/usr/sap &prompt.root; ls -l total 4 drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00 drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans I also found SAP notes (0029227 and 0008401) describing this behavior. I did not encounter any of these problems with the SAP 4.6C-installation. [RFCRSWBOINI_IND_IND] during R3SETUP During installation of SAP 4.6C, this error was just the result of another error happening earlier during installation. In this case, you have to look through the corresponding logfiles and correct the real problem. If after looking through the logfiles this error is indeed the correct one (check the SAP-notes), you can set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RSWBOINS from transaction SE38. See SAP note 0162266 for additional information about phase RFCRSWBOINI and RFCRADDBDIF. [RFCRADDBDIF_IND_IND] during R3SETUP Here the same restrictions apply: Make sure by looking through the logfiles, that this error is not caused by some previous problems. If you can confirm that SAP-Note 0162266 applies, just set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RADDBDIF from transaction SE38. <errorcode>sigaction sig31: File size limit exceeded</errorcode> This error occurred during start of SAP-processes disp+work. If starting SAP with the startsap-script, subprocesses are then started which detach and do the dirty work of starting all other SAP processes. As a result, the script itself won't notice if something goes wrong. To check whether the SAP processes did start properly, have a look at the process status with ps ax | grep SID, which will give you a list of all Oracle- and SAP-processes. If it looks like some processes are missing or if you can't connect to the SAP-System, look at the corresponding logfiles which can be found at /usr/sap/SID/DVEBMGSnr/work/. The files to look at are dev_ms and dev_disp. Signal 31 happens here if the amount of shared memory used by Oracle and SAP exceed the one defined within the kernel configuration file and could be resolved by using a larger value: # larger value for 46C production systems: options SHMMAXPGS=393216 # smaller value sufficient for 46B: #options SHMMAXPGS=262144 Start of saposcol Failed There are some problems with Program saposcol (version 4.6D). The SAP-System is using saposcol to collect data about the system performance. This program is not needed to use the SAP-System, so this problem can be considered a minor one. The older versions (4.6B) does work, but doesn't collect all the data (many calls will just return 0, for example for CPU usage). Advanced Topics If you are curious as to how the Linux binary compatibility works, this is the section you want to read. Most of what follows is based heavily on an email written to &a.chat; by Terry Lambert tlambert@primenet.com (Message ID: <199906020108.SAA07001@usr09.primenet.com>). How Does It Work? execution class loader FreeBSD has an abstraction called an execution class loader. This is a wedge into the &man.execve.2; system call. What happens is that FreeBSD has a list of loaders, instead of a single loader with a fallback to the #! loader for running any shell interpreters or shell scripts. Historically, the only loader on the Unix platform examined the magic number (generally the first 4 or 8 bytes of the file) to see if it was a binary known to the system, and if so, invoked the binary loader. If it was not the binary type for the system, the &man.execve.2; call returned a failure, and the shell attempted to start executing it as shell commands. The assumption was a default of whatever the current shell is. Later, a hack was made for &man.sh.1; to examine the first two characters, and if they were :\n, then it invoked the &man.csh.1; shell instead (we believe SCO first made this hack). What FreeBSD does now is go through a list of loaders, with a generic #! loader that knows about interpreters as the characters which follow to the next whitespace next to last, followed by a fallback to /bin/sh. ELF For the Linux ABI support, FreeBSD sees the magic number as an ELF binary (it makes no distinction between FreeBSD, Solaris, Linux, or any other OS which has an ELF image type, at this point). Solaris The ELF loader looks for a specialized brand, which is a comment section in the ELF image, and which is not present on SVR4/Solaris ELF binaries. For Linux binaries to function, they must be branded as type Linux; from &man.brandelf.1;: &prompt.root; brandelf -t Linux file When this is done, the ELF loader will see the Linux brand on the file. ELF branding When the ELF loader sees the Linux brand, the loader replaces a pointer in the proc structure. All system calls are indexed through this pointer (in a traditional Unix system, this would be the sysent[] structure array, containing the system calls). In addition, the process is flagged for special handling of the trap vector for the signal trampoline code, and several other (minor) fix-ups that are handled by the Linux kernel module. The Linux system call vector contains, among other things, a list of sysent[] entries whose addresses reside in the kernel module. When a system call is called by the Linux binary, the trap code dereferences the system call function pointer off the proc structure, and gets the Linux, not the FreeBSD, system call entry points. In addition, the Linux mode dynamically reroots lookups; this is, in effect, what the union option to FS mounts (not the unionfs!) does. First, an attempt is made to lookup the file in the /compat/linux/original-path directory, then only if that fails, the lookup is done in the /original-path directory. This makes sure that binaries that require other binaries can run (e.g., the Linux toolchain can all run under Linux ABI support). It also means that the Linux binaries can load and exec FreeBSD binaries, if there are no corresponding Linux binaries present, and that you could place a &man.uname.1; command in the /compat/linux directory tree to ensure that the Linux binaries could not tell they were not running on Linux. In effect, there is a Linux kernel in the FreeBSD kernel; the various underlying functions that implement all of the services provided by the kernel are identical to both the FreeBSD system call table entries, and the Linux system call table entries: file system operations, virtual memory operations, signal delivery, System V IPC, etc… The only difference is that FreeBSD binaries get the FreeBSD glue functions, and Linux binaries get the Linux glue functions (most older OS's only had their own glue functions: addresses of functions in a static global sysent[] structure array, instead of addresses of functions dereferenced off a dynamically initialized pointer in the proc structure of the process making the call). Which one is the native FreeBSD ABI? It does not matter. Basically the only difference is that (currently; this could easily be changed in a future release, and probably will be after this) the FreeBSD glue functions are statically linked into the kernel, and the Linux glue functions can be statically linked, or they can be accessed via a kernel module. Yeah, but is this really emulation? No. It is an ABI implementation, not an emulation. There is no emulator (or simulator, to cut off the next question) involved. So why is it sometimes called Linux emulation? To make it hard to sell FreeBSD! Really, it is because the historical implementation was done at a time when there was really no word other than that to describe what was going on; saying that FreeBSD ran Linux binaries was not true, if you did not compile the code in or load a module, and there needed to be a word to describe what was being loaded—hence the Linux emulator. diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml index 97cebcf810..6277e8be60 100644 --- a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml @@ -1,1492 +1,1493 @@ Bill Lloyd Original work by Jim Mock Rewritten by Electronic Mail Synopsis email electronic mail Electronic Mail, better known as email, is one of the most widely used forms of communication today. This chapter provides a basic introduction to running a mail server on FreeBSD. However, it is not a complete reference and in fact many important considerations are omitted. For more complete coverage of the subject, the reader is referred to the many excellent books listed in . After reading this chapter, you will know: What software components are involved in sending and receiving electronic mail. Where basic sendmail configuration files are located in FreeBSD. How to block spammers from illegally using your mail server as a relay. How to install and configure an alternate mail transfer agent on your system, replacing sendmail. How to troubleshoot common mail server problems. How to configure SMTP Authentication for added security. Before reading this chapter, you should: Properly setup your network connection (). Properly setup the DNS information for your mail host (). Know how to install additional third-party software (). Using Electronic Mail POP IMAP DNS There are five major parts involved in an email exchange. They are: the user program, the server daemon, DNS, a POP or IMAP daemon, and of course, the mailhost itself. The User Program This includes command line programs such as mutt, pine, elm, and mail, and GUI programs such as balsa, xfmail to name a few, and something more sophisticated like a WWW browser. These programs simply pass off the email transactions to the local mailhost, either by calling one of the server daemons available or delivering it over TCP. Mailhost Server Daemon mail server daemons sendmail mail server daemons postfix mail server daemons qmail mail server daemons exim This is usually sendmail (by default with FreeBSD) or one of the other mail server daemons such as qmail, postfix, or exim. There are others, but those are the most widely used. The server daemon usually has two functions—it looks after receiving incoming mail and delivers outgoing mail. It does not allow you to connect to it via POP or IMAP to read your mail. You need an additional daemon for that. Be aware that some older versions of sendmail have some serious security problems, however as long as you run a current version of it you should not have any problems. As always, it is a good idea to stay up-to-date with any software you run. Email and DNS The Domain Name System (DNS) and its daemon named play a large role in the delivery of email. In order to deliver mail from your site to another, the server daemon will look up the site in the DNS to determine the host that will receive mail for the destination. It works the same way when you have mail sent to you. The DNS contains the database mapping hostname to an IP address, and a hostname to mailhost. The IP address is specified in an A record. The MX (Mail eXchanger) record specifies the mailhost that will receive mail for you. If you do not have an MX record for your hostname, the mail will be delivered directly to your host. Receiving Mail email receiving Receiving mail for your domain is done by the mail host. It will collect mail sent to you and store it for reading or pickup. In order to pick the stored mail up, you will need to connect to the mail host. This is done by either using POP or IMAP. If you want to read mail directly on the mail host, then a POP or IMAP server is not needed. POP IMAP If you want to run a POP or IMAP server, there are two things you need to do: Get a POP or IMAP daemon from the ports collection and install it on your system. Modify /etc/inetd.conf to load the POP or IMAP server. The Mail Host mail host The mail host is the name given to a server that is responsible for delivering and receiving mail for your host, and possibly your network. Christopher Shumway Contributed by <application>sendmail</application> Configuration sendmail &man.sendmail.8; is the default Mail Transfer Agent (MTA) in FreeBSD. sendmail's job is to accept mail from Mail User Agents (MUA) and deliver it to the appropriate mailer as defined by its configuration file. sendmail can also accept network connections and deliver mail to local mailboxes or deliver it to another program. sendmail uses the following configuration files: /etc/mail/access /etc/mail/aliases /etc/mail/local-host-names /etc/mail/mailer.conf /etc/mail/mailertable /etc/mail/sendmail.cf /etc/mail/virtusertable Filename Function /etc/mail/access sendmail access database file /etc/mail/aliases Mailbox aliases /etc/mail/local-host-names Lists of hosts sendmail accepts mail for /etc/mail/mailer.conf Mailer program configuration /etc/mail/mailertable Mailer delivery table /etc/mail/sendmail.cf sendmail master configuration file /etc/mail/virtusertable Virtual users and domain tables <filename>/etc/mail/access</filename> The access database defines what host(s) or IP addresses have access to the local mail server and what kind of access they have. Hosts can be listed as , , or simply passed to sendmail's error handling routine with a given mailer error. Hosts that are listed as , which is the default, are allowed to send mail to this host as long as the mail's final destination is the local machine. Hosts that are listed as are rejected for all mail connections. Hosts that have the option for their hostname are allowed to send mail for any destination through this mail server. Configuring the <application>sendmail</application> Access Database cyberspammer.com 550 We don't accept mail from spammers FREE.STEALTH.MAILER@ 550 We don't accept mail from spammers another.source.of.spam REJECT okay.cyberspammer.com OK 128.32 RELAY In this example we have five entries. Mail senders that match the left hand side of the table are affected by the action on the right side of the table. The first two examples give an error code to sendmail's error handling routine. The message is printed to the remote host when a mail matches the left hand side of the table. The next entry rejects mail from a specific host on the Internet, another.source.of.spam. The next entry accepts mail connections from a host okay.cyberspammer.com, which is more exact than the cyberspammer.com line above. More specific matches override less exact matches. The last entry allows relaying of electronic mail from hosts with an IP address that begins with 128.32. These hosts would be able to send mail through this mail server that are destined for other mail servers. When this file is updated, you need to run make in /etc/mail/ to update the database. <filename>/etc/mail/aliases</filename> The aliases database contains a list of virtual mailboxes that are expanded to other user(s), files, programs or other aliases. Here are a few examples that can be used in /etc/mail/aliases: Mail Aliases root: localuser ftp-bugs: joe,eric,paul bit.bucket: /dev/null procmail: "|/usr/local/bin/procmail" The file format is simple; the mailbox name on the left side of the colon is expanded to the target(s) on the right. The first example simply expands the mailbox root to the mailbox localuser, which is then looked up again in the aliases database. If no match is found, then the message is delivered to the local user localuser. The next example shows a mail list. Mail to the mailbox ftp-bugs is expanded to the three local mailboxes joe, eric, and paul. Note that a remote mailbox could be specified as user@example.com. The next example shows writing mail to a file, in this case /dev/null. The last example shows sending mail to a program, in this case the mail message is written to the standard input of /usr/local/bin/procmail through a Unix pipe. When this file is updated, you need to run make in /etc/mail/ to update the database. <filename>/etc/mail/local-host-names</filename> This is a list of hostnames &man.sendmail.8; is to accept as the local host name. Place any domains or hosts that sendmail is to be receiving mail for. For example, if this mail server was to accept mail for the domain example.com and the host mail.example.com, its local-host-names might look something like this: example.com mail.example.com When this file is updated, &man.sendmail.8; needs to be restarted to read the changes. <filename>/etc/mail/sendmail.cf</filename> sendmail's master configuration file, sendmail.cf controls the overall behavior of sendmail, including everything from rewriting e-mail addresses to printing rejection messages to remote mail servers. Naturally, with such a diverse role, this configuration file is quite complex and its details are a bit out of the scope of this section. Fortunately, this file rarely needs to be changed for standard mail servers. The master sendmail configuration file can be built from &man.m4.1; macros that define the features and behavior of sendmail. Please see /usr/src/contrib/sendmail/cf/README for some of the details. When changes to this file are made, sendmail needs to be restarted for the changes to take effect. <filename>/etc/mail/virtusertable</filename> The virtusertable maps mail addresses for virtual domains and mailboxes to real mailboxes. These mailboxes can be local, remote, aliases defined in /etc/mail/aliases or files. Example Virtual Domain Mail Map root@example.com root postmaster@example.com postmaster@noc.example.net @example.com joe In the above example, we have a mapping for a domain example.com. This file is processed in a first match order down the file. The first item maps root@example.com to the local mailbox root. The next entry maps postmaster@example.com to the mailbox postmaster on the host noc.example.net. Finally, if nothing from example.com has matched so far, it will match the last mapping, which matches every other mail message addressed to someone at example.com. This will be mapped to the local mailbox joe. Andrew Boothman Written by Gregory Neil Shapiro Information taken from e-mails written by Changing Your Mail Transfer Agent email change mta As already mentioned, FreeBSD comes with sendmail already installed as your MTA (Mail Transfer Agent). Therefore by default it is in charge of your outgoing and incoming mail. However, for a variety of reasons, some system administrators want to change their system's MTA. These reasons range from simply wanting to try out another MTA to needing a specific feature or package which relies on another mailer. Fortunately, whatever the reason, FreeBSD makes it easy to make the change. Install a New MTA You have a wide choice of MTAs available. A good starting point is the FreeBSD Ports Collection where you will be able to find many. Of course you are free to use any MTA you want from any location, as long as you can make it run under FreeBSD. Start by installing your new MTA. Once it is installed it gives you a chance to decide if it really fulfills your needs, and also gives you the opportunity to configure your new software before getting it to take over from sendmail. When doing this, you should be sure that installing the new software will not attempt to overwrite system binaries such as /usr/bin/sendmail. Otherwise, your new mail software has essentially been put into service before you have configured it. Please refer to your chosen MTA's documentation for information on how to configure the software you have chosen. Disable <application>sendmail</application> The procedure used to start sendmail changed significantly between 4.5-RELEASE and 4.6-RELEASE. Therefore, the procedure used to disable it is subtly different. FreeBSD 4.5-STABLE before 2002/4/4 and Earlier (Including 4.5-RELEASE and Earlier) Enter: sendmail_enable="NO" into /etc/rc.conf. This will disable sendmail's incoming mail service, but if /etc/mail/mailer.conf (see below) is not changed, sendmail will still be used to send e-mail. FreeBSD 4.5-STABLE after 2002/4/4 (Including 4.6-RELEASE and Later) In order to completely disable sendmail you must use sendmail_enable="NONE" in /etc/rc.conf. If you disable sendmail's outgoing mail service in this way, it is important that you replace it with a fully working alternative mail delivery system. If you choose not to, system functions such as &man.periodic.8; will be unable to deliver their results by e-mail as they would normally expect to. Many parts of your system may expect to have a functional sendmail-compatible system. If applications continue to use sendmail's binaries to try and send e-mail after you have disabled them, mail could go into an inactive sendmail queue, and never be delivered. If you only want to disable sendmail's incoming mail service, you should set sendmail_enable="NO" in /etc/rc.conf. More information on sendmail's startup options is available from the &man.rc.sendmail.8; manual page. + Running Your New MTA on Boot You may have a choice of two methods for running your new MTA on boot, again depending on what version of FreeBSD you are running. FreeBSD 4.5-STABLE before 2002/4/11 (Including 4.5-RELEASE and Earlier) Add a script to /usr/local/etc/rc.d/ that ends in .sh and is executable by root. The script should accept start and stop parameters. At startup time the system scripts will execute the command /usr/local/etc/rc.d/supermailer.sh start which you can also use to manually start the server. At shutdown time, the system scripts will use the stop option, running the command /usr/local/etc/rc.d/supermailer.sh stop which you can also use to manually stop the server while the system is running. FreeBSD 4.5-STABLE after 2002/4/11 (Including 4.6-RELEASE and Later) With later versions of FreeBSD, you can use the above method or you can set mta_start_script="filename" in /etc/rc.conf, where filename is the name of some script that you want executed at boot to start your MTA. Replacing <application>sendmail</application> as the System's Default Mailer The program sendmail is so ubiquitous as standard software on Unix systems that some software just assumes it is already installed and configured. For this reason, many alternative MTA's provide their own compatible implementations of the sendmail command-line interface; this facilitates using them as drop-in replacements for sendmail. Therefore, if you are using an alternative mailer, you will need to make sure that software trying to execute standard sendmail binaries such as /usr/bin/sendmail actually executes your chosen mailer instead. Fortunately, FreeBSD provides a system called &man.mailwrapper.8; that does this job for you. When sendmail is operating as installed, you will find something like the following in /etc/mail/mailer.conf: sendmail /usr/libexec/sendmail/sendmail send-mail /usr/libexec/sendmail/sendmail mailq /usr/libexec/sendmail/sendmail newaliases /usr/libexec/sendmail/sendmail hoststat /usr/libexec/sendmail/sendmail purgestat /usr/libexec/sendmail/sendmail This means that when any of these common commands (such as sendmail itself) are run, the system actually invokes a copy of mailwrapper named sendmail, which checks mailer.conf and executes /usr/libexec/sendmail/sendmail instead. This system makes it easy to change what binaries are actually executed when these default sendmail functions are invoked. Therefore if you wanted /usr/local/supermailer/bin/sendmail-compat to be run instead of sendmail, you could change /etc/mail/mailer.conf to read: sendmail /usr/local/supermailer/bin/sendmail-compat send-mail /usr/local/supermailer/bin/sendmail-compat mailq /usr/local/supermailer/bin/mailq-compat newaliases /usr/local/supermailer/bin/newaliases-compat hoststat /usr/local/supermailer/bin/hoststat-compat purgestat /usr/local/supermailer/bin/purgestat-compat Finishing Once you have everything configured the way you want it, you should either kill the sendmail processes that you no longer need and start the processes belonging to your new software, or simply reboot. Rebooting will also give you the opportunity to ensure that you have correctly configured your system to start your new MTA automatically on boot. Troubleshooting email troubleshooting Why do I have to use the FQDN for hosts on my site? You will probably find that the host is actually in a different domain; for example, if you are in foo.bar.edu and you wish to reach a host called mumble in the bar.edu domain, you will have to refer to it by the fully-qualified domain name, mumble.bar.edu, instead of just mumble. BIND Traditionally, this was allowed by BSD BIND resolvers. However the current version of BIND that ships with FreeBSD no longer provides default abbreviations for non-fully qualified domain names other than the domain you are in. So an unqualified host mumble must either be found as mumble.foo.bar.edu, or it will be searched for in the root domain. This is different from the previous behavior, where the search continued across mumble.bar.edu, and mumble.edu. Have a look at RFC 1535 for why this was considered bad practice, or even a security hole. As a good workaround, you can place the line: search foo.bar.edu bar.edu instead of the previous: domain foo.bar.edu into your /etc/resolv.conf. However, make sure that the search order does not go beyond the boundary between local and public administration, as RFC 1535 calls it. sendmail says mail loops back to myself This is answered in the sendmail FAQ as follows: I am getting Local configuration error messages, such as: 553 relay.domain.net config error: mail loops back to myself 554 <user@domain.net>... Local configuration error How can I solve this problem? You have asked mail to the domain (e.g., domain.net) to be forwarded to a specific host (in this case, relay.domain.net) by using an MX record, but the relay machine does not recognize itself as domain.net. Add domain.net to /etc/mail/local-host-names (if you are using FEATURE(use_cw_file)) or add Cw domain.net to /etc/mail/sendmail.cf. The sendmail FAQ can be found at and is recommended reading if you want to do any tweaking of your mail setup. PPP How can I run a mail server on a dial-up PPP host? You want to connect a FreeBSD box on a LAN to the Internet. The FreeBSD box will be a mail gateway for the LAN. The PPP connection is non-dedicated. UUCP There are at least two ways to do this. One way is to use UUCP. Another way is to get a full-time Internet server to provide secondary MX services for your domain. For example, if your company's domain is example.com and your Internet service provider has set example.net up to provide secondary MX services to your domain: example.com. MX 10 example.com. MX 20 example.net. Only one host should be specified as the final recipient (add Cw example.com in /etc/mail/sendmail.cf on example.com). When the sending sendmail is trying to deliver the mail it will try to connect to you (example.com) over the modem link. It will most likely time out because you are not online. The program sendmail will automatically deliver it to the secondary MX site, i.e. your Internet provider (example.net). The secondary MX site will then periodically try to connect to your host and deliver the mail to the primary MX host (example.com). You might want to use something like this as a login script: #!/bin/sh # Put me in /usr/local/bin/pppmyisp ( sleep 60 ; /usr/sbin/sendmail -q ) & /usr/sbin/ppp -direct pppmyisp If you are going to create a separate login script for a user you could use sendmail -qRexample.com instead in the script above. This will force all mail in your queue for example.com to be processed immediately. A further refinement of the situation is as follows: Message stolen from the &a.isp;. > we provide the secondary MX for a customer. The customer connects to > our services several times a day automatically to get the mails to > his primary MX (We do not call his site when a mail for his domains > arrived). Our sendmail sends the mailqueue every 30 minutes. At the > moment he has to stay 30 minutes online to be sure that all mail is > gone to the primary MX. > > Is there a command that would initiate sendmail to send all the mails > now? The user has not root-privileges on our machine of course. In the privacy flags section of sendmail.cf, there is a definition Opgoaway,restrictqrun Remove restrictqrun to allow non-root users to start the queue processing. You might also like to rearrange the MXs. We are the 1st MX for our customers like this, and we have defined: # If we are the best MX for a host, try directly instead of generating # local config error. OwTrue That way a remote site will deliver straight to you, without trying the customer connection. You then send to your customer. Only works for hosts, so you need to get your customer to name their mail machine customer.com as well as hostname.customer.com in the DNS. Just put an A record in the DNS for customer.com. Why do I keep getting Relaying Denied errors when sending mail from other hosts? In default FreeBSD installations, sendmail is configured to only send mail from the host it is running on. For example, if a POP3 server is installed, then users will be able to check mail from school, work, or other remote locations but they still will not be able to send outgoing emails from outside locations. Typically, a few moments after the attempt, an email will be sent from MAILER-DAEMON with a 5.7 Relaying Denied error message. There are several ways to get around this. The most straightforward solution is to put your ISP's address in a relay-domains file at /etc/mail/relay-domains. A quick way to do this would be: &prompt.root; echo "your.isp.example.com" > /etc/mail/relay-domains After creating or editing this file you must restart sendmail. This works great if you are a server administrator and do not wish to send mail locally, or would like to use a point and click client/system on another machine or even another ISP. It is also very useful if you only have one or two email accounts set up. If there is a large number of addresses to add, you can simply open this file in your favorite text editor and then add the domains, one per line: your.isp.example.com other.isp.example.net users-isp.example.org www.example.org Now any mail sent through your system, by any host in this list (provided the user has an account on your system), will succeed. This is a very nice way to allow users to send mail from your system remotely without allowing people to send SPAM through your system. Advanced Topics The following section covers more involved topics such as mail configuration and setting up mail for your entire domain. Basic Configuration email configuration Out of the box, you should be able to send email to external hosts as long as you have set up /etc/resolv.conf or are running your own name server. If you would like to have mail for your host delivered to the MTA (e.g., sendmail) on your own FreeBSD host, there are two methods: Run your own name server and have your own domain. For example, FreeBSD.org Get mail delivered directly to your host. This is done by delivering mail directly to the current DNS name for your machine. For example, example.FreeBSD.org. SMTP Regardless of which of the above you choose, in order to have mail delivered directly to your host, it must have a permanent static IP address (not a dynamic address, as with most PPP dial-up configurations). If you are behind a firewall, it must pass SMTP traffic on to you. If you want to receive mail directly at your host, you need to be sure of either of two things: MX record Make sure that the (lowest-numbered) MX record in your DNS points to your host's IP address. Make sure there is no MX entry in your DNS for your host. Either of the above will allow you to receive mail directly at your host. Try this: &prompt.root; hostname example.FreeBSD.org &prompt.root; host example.FreeBSD.org example.FreeBSD.org has address 204.216.27.XX If that is what you see, mail directly to yourlogin@example.FreeBSD.org should work without problems (assuming sendmail is running correctly on example.FreeBSD.org). If instead you see something like this: &prompt.root; host example.FreeBSD.org example.FreeBSD.org has address 204.216.27.XX example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org All mail sent to your host (example.FreeBSD.org) will end up being collected on hub under the same username instead of being sent directly to your host. The above information is handled by your DNS server. The DNS record that carries mail routing information is the Mail eXchange entry. If no MX record exists, mail will be delivered directly to the host by way of its IP address. The MX entry for freefall.FreeBSD.org at one time looked like this: freefall MX 30 mail.crl.net freefall MX 40 agora.rdrop.com freefall MX 10 freefall.FreeBSD.org freefall MX 20 who.cdrom.com As you can see, freefall had many MX entries. The lowest MX number is the host that receives mail directly if available; if it's not accessible for some reason, the others (sometimes called backup MXes) accept messages temporarily, and pass it along when a lower-numbered host becomes available, eventually to the lowest-numbered host. Alternate MX sites should have separate Internet connections from your own in order to be most useful. Your ISP or another friendly site should have no problem providing this service for you. Mail for Your Domain In order to set up a mailhost (a.k.a. mail server) you need to have any mail sent to various workstations directed to it. Basically, you want to claim any mail for any hostname in your domain (in this case *.FreeBSD.org) and divert it to your mail server so your users can receive their mail on the master mail server. DNS To make life easiest, a user account with the same username should exist on both machines. Use &man.adduser.8; to do this. The mailhost you will be using must be the designated mail exchanger for each workstation on the network. This is done in your DNS configuration like so: example.FreeBSD.org A 204.216.27.XX ; Workstation MX 10 hub.FreeBSD.org ; Mailhost This will redirect mail for the workstation to the mailhost no matter where the A record points. The mail is sent to the MX host. You cannot do this yourself unless you are running a DNS server. If you are not, or cannot run your own DNS server, talk to your ISP or whoever provides your DNS. If you are doing virtual email hosting, the following information will come in handy. For this example, we will assume you have a customer with his own domain, in this case customer1.org, and you want all the mail for customer1.org sent to your mailhost, mail.myhost.com. The entry in your DNS should look like this: customer1.org MX 10 mail.myhost.com You do not need an A record for customer1.org if you only want to handle email for that domain. Be aware that pinging customer1.org will not work unless an A record exists for it. The last thing that you must do is tell sendmail on your mailhost what domains and/or hostnames it should be accepting mail for. There are a few different ways this can be done. Either of the following will work: Add the hosts to your /etc/mail/local-host-names file if you are using the FEATURE(use_cw_file). If you are using a version of sendmail earlier than 8.10, the file is /etc/sendmail.cw. Add a Cwyour.host.com line to your /etc/sendmail.cf or /etc/mail/sendmail.cf if you are using sendmail 8.10 or higher. SMTP with UUCP The sendmail configuration that ships with FreeBSD is designed for sites that connect directly to the Internet. Sites that wish to exchange their mail via UUCP must install another sendmail configuration file. Tweaking /etc/mail/sendmail.cf manually is an advanced topic. sendmail version 8 generates config files via &man.m4.1; preprocessing, where the actual configuration occurs on a higher abstraction level. The &man.m4.1 configuration files can be found under /usr/src/usr.sbin/sendmail/cf. If you did not install your system with full sources, the sendmail config stuff has been broken out into a separate source distribution tarball. Assuming you have your FreeBSD source code CDROM mounted, do: &prompt.root; cd /cdrom/src &prompt.root; cat scontrib.?? | tar xzf - -C /usr/src contrib/sendmail This extracts to only a few hundred kilobytes. The file README in the cf directory can serve as a basic introduction to m4 configuration. The best way to support UUCP delivery is to use the mailertable feature. This creates a database that sendmail can use to make routing decisions. First, you have to create your .mc file. The directory /usr/src/usr.sbin/sendmail/cf/cf contains a few examples. Assuming you have named your file foo.mc, all you need to do in order to convert it into a valid sendmail.cf is: &prompt.root; cd /usr/src/usr.sbin/sendmail/cf/cf &prompt.root; make foo.cf &prompt.root; cp foo.cf /etc/mail/sendmail.cf A typical .mc file might look like: VERSIONID(`Your version number') OSTYPE(bsd4.4) FEATURE(accept_unresolvable_domains) FEATURE(nocanonify) FEATURE(mailertable, `hash -o /etc/mail/mailertable') define(`UUCP_RELAY', your.uucp.relay) define(`UUCP_MAX_SIZE', 200000) define(`confDONT_PROBE_INTERFACES') MAILER(local) MAILER(smtp) MAILER(uucp) Cw your.alias.host.name Cw youruucpnodename.UUCP The lines containing accept_unresolvable_domains, nocanonify, and confDONT_PROBE_INTERFACES features will prevent any usage of the DNS during mail delivery. The UUCP_RELAY clause is needed to support UUCP delivery. Simply put an Internet hostname there that is able to handle .UUCP pseudo-domain addresses; most likely, you will enter the mail relay of your ISP there. Once you have this, you need an /etc/mail/mailertable file. If you have only one link to the outside that is used for all your mails, the following file will suffice: # # makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable . uucp-dom:your.uucp.relay A more complex example might look like this: # # makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable # horus.interface-business.de uucp-dom:horus .interface-business.de uucp-dom:if-bus interface-business.de uucp-dom:if-bus .heep.sax.de smtp8:%1 horus.UUCP uucp-dom:horus if-bus.UUCP uucp-dom:if-bus . uucp-dom: The first three lines handle special cases where domain-addressed mail should not be sent out to the default route, but instead to some UUCP neighbor in order to shortcut the delivery path. The next line handles mail to the local Ethernet domain that can be delivered using SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP pseudo-domain notation, to allow for a uucp-neighbor !recipient override of the default rules. The last line is always a single dot, matching everything else, with UUCP delivery to a UUCP neighbor that serves as your universal mail gateway to the world. All of the node names behind the uucp-dom: keyword must be valid UUCP neighbors, as you can verify using the command uuname. As a reminder that this file needs to be converted into a DBM database file before use. The command line to accomplish this is best placed as a comment at the top of the mailertable. You always have to execute this command each time you change your mailertable. Final hint: if you are uncertain whether some particular mail routing would work, remember the option to sendmail. It starts sendmail in address test mode; simply enter 3,0, followed by the address you wish to test for the mail routing. The last line tells you the used internal mail agent, the destination host this agent will be called with, and the (possibly translated) address. Leave this mode by typing Control-D. &prompt.user; sendmail -bt ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) Enter <ruleset> <address> > 3,0 foo@example.com canonify input: foo @ example . com ... parse returns: $# uucp-dom $@ your.uucp.relay $: foo < @ example . com . > > ^D Using Mail with a Dialup Connection If you have a static IP address, you should not need to adjust anything from the defaults. Set your host name to your assigned Internet name and sendmail will do the rest. If you have a dynamically assigned IP number and use a dialup PPP connection to the Internet, you will probably have a mailbox on your ISPs mail server. Let's assume your ISP's domain is example.net, and that your user name is user, you have called your machine bsd.home, and your ISP has told you that you may use relay.example.net as a mail relay. In order to retrieve mail from your mailbox, you must install a retrieval agent. The fetchmail utility is a good choice as it supports many different protocols. Usually, your ISP will provide POP3. If you are using user-PPP, you can automatically fetch your mail when an Internet connection is established with the following entry in /etc/ppp/ppp.linkup: MYADDR: !bg su user -c fetchmail If you are using sendmail (as shown below) to deliver mail to non-local accounts, you probably want to have sendmail process your mailqueue as soon as your Internet connection is established. To do this, put this command after the fetchmail command in /etc/ppp/ppp.linkup. !bg su user -c "sendmail -q" Assume that you have an account for user on bsd.home. In the home directory of user on bsd.home, create a .fetchmailrc file: poll example.net protocol pop3 fetchall pass MySecret This file should not be readable by anyone except user as it contains the password MySecret. In order to send mail with the correct from: header, you must tell sendmail to use user@example.net rather than user@bsd.home. You may also wish to tell sendmail to send all mail via relay.example.net, allowing quicker mail transmission. The following .mc file should suffice: VERSIONID(`bsd.home.mc version 1.0') OSTYPE(bsd4.4)dnl FEATURE(nouucp)dnl MAILER(local)dnl MAILER(smtp)dnl Cwlocalhost Cwbsd.home MASQUERADE_AS(`example.net')dnl FEATURE(allmasquerade)dnl FEATURE(masquerade_envelope)dnl FEATURE(nocanonify)dnl FEATURE(nodns)dnl define(`SMART_HOST', `relay.example.net') Dmbsd.home define(`confDOMAIN_NAME',`bsd.home')dnl define(`confDELIVERY_MODE',`deferred')dnl Refer to the previous section for details of how to turn this .mc file into a sendmail.cf file. Also, do not forget to restart sendmail after updating sendmail.cf. SMTP Authentication Having SMTP Authentication in place on your mail server has a number of benefits. SMTP Authentication can add another layer of security to sendmail, and has the benefit of giving mobile users who switch hosts the ability to use the same mail server without the need to reconfigure their mail client settings each time. Install security/cyrus-sasl from the ports. You can find this port in security/cyrus-sasl. security/cyrus-sasl has a number of compile time options to choose from and, for the method we will be using here, make sure to select the option. After installing security/cyrus-sasl, edit /usr/local/lib/sasl/Sendmail.conf (or create it if it does not exist) and add the following line: pwcheck_method: passwd This method will enable sendmail to authenticate against your FreeBSD passwd database. This saves the trouble of creating a new set of usernames and passwords for each user that needs to use SMTP authentication, and keeps the login and mail password the same. Now edit /etc/make.conf and add the following lines: SENDMAIL_CFLAGS=-I/usr/local/include/sasl1 -DSASL SENDMAIL_LDFLAGS=-L/usr/local/lib SENDMAIL_LDADD=-lsasl These lines will give sendmail the proper configuration options for linking to cyrus-sasl at compile time. Make sure that cyrus-sasl has been installed before recompiling sendmail. Recompile sendmail by executing the following commands: &prompt.root; cd /usr/src/usr.sbin/sendmail &prompt.root; make cleandir &prompt.root; make obj &prompt.root; make &prompt.root; make install The compile of sendmail should not have any problems if /usr/src has not been changed extensively and the shared libraries it needs are available. After sendmail has been compiled and reinstalled, edit your /etc/mail/freebsd.mc file (or whichever file you use as your .mc file. Many administrators choose to use the output from &man.hostname.1; as the .mc file for uniqueness). Add these lines to it: dnl set SASL options TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl define(`confDEF_AUTH_INFO', `/etc/mail/auth-info')dnl These options configure the different methods available to sendmail for authenticating users. If you would like to use a method other than pwcheck, please see the included documentation. Finally, run &man.make.1; while in /etc/mail. That will run your new .mc file and create a .cf file named freebsd.cf (or whatever name you have used for your .mc file). Then use the command make install restart, which will copy the file to sendmail.cf, and will properly restart sendmail. For more information about this process, you should refer to /etc/mail/Makefile. If all has gone correctly, you should be able to enter your login information into the mail client and send a test message. For further investigation, set the of sendmail to 13 and watch /var/log/maillog for any errors. You may wish to add the following lines to /etc/rc.conf so this service will be available after every system boot: sasl_pwcheck_enable="YES" sasl_pwcheck_program="/usr/local/sbin/pwcheck" This will ensure the initialization of SMTP_AUTH upon system boot. For more information, please see the sendmail page regarding SMTP authentication. diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml index 74565d0f77..912cefe1d8 100644 --- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml @@ -1,4900 +1,4901 @@ Obtaining FreeBSD CDROM and DVD Publishers Retail Boxed Products FreeBSD is available as a boxed product (FreeBSD CDs, additional software, and printed documentation) from several retailers:
CompUSA WWW:
Frys Electronics WWW:
CD and DVD Sets FreeBSD CD and DVD sets are available from many online retailers:
Daemon News Mall 560 South State Street, Suite A2 Orem, UT 84058 USA Phone: +1 800 407-5170 Fax: +1 1 801 765-0877 Email: sales@bsdmall.com WWW:
FreeBSD Mall, Inc. 3623 Sanford Street Concord, CA 94520-1405 USA Phone: +1 925 674-0783 Fax: +1 925 674-0821 Email: info@freebsdmall.com WWW:
FreeBSD Services Ltd 11 Lapwing Close Bicester OX26 6XR United Kingdom WWW:
Hinner EDV St. Augustinus-Str. 10 D-81825 München Germany Phone: (089) 428 419 WWW:
Ikarios 22-24 rue Voltaire 92000 Nanterre France WWW:
Ingram Micro 1600 E. St. Andrew Place Santa Ana, CA 92705-4926 USA Phone: 1 (800) 456-8000 WWW:
JMC Software Ireland Phone: 353 1 6291282 WWW:
The Linux Emporium Hilliard House, Lester Way Wallingford OX10 9TA United Kingdom Phone: +44 1491 837010 Fax: +44 1491 837016 WWW:
Linux System Labs Australia 21 Ray Drive Balwyn North VIC - 3104 Australia Phone: +61 3 9857 5918 Fax: +61 3 9857 8974 WWW:
UNIXDVD.COM LTD 57 Primrose Avenue Sheffield S5 6FS United Kingdom WWW:
Distributors If you are a reseller and want to carry FreeBSD CDROM products, please contact a distributor:
Cylogistics 2672 Bayshore Parkway, Suite 610 Mountain View, CA 94043 USA Phone: +1 650 694-4949 Fax: +1 650 694-4953 Email: sales@cylogistics.com WWW:
FreeBSD Services Ltd 11 Lapwing Close Bicester OX26 6XR United Kingdom WWW:
Kudzu, LLC 7375 Washington Ave. S. Edina, MN 55439 USA Phone: +1 952 947-0822 Fax: +1 952 947-0876 Email: sales@kudzuenterprises.com
Navarre Corp 7400 49th Ave South New Hope, MN 55428 USA Phone: +1 763 535-8333 Fax: +1 763 535-0341 WWW:
FTP Sites The official sources for FreeBSD are available via anonymous FTP from a worldwide set of mirror sites. The site is well connected and allows a large number of connections to it, but you are probably better off finding a closer mirror site (especially if you decide to set up some sort of mirror site). The FreeBSD mirror sites database is more accurate than the mirror listing in the Handbook, as it gets its information from the DNS rather than relying on static lists of hosts. Additionally, FreeBSD is available via anonymous FTP from the following mirror sites. If you choose to obtain FreeBSD via anonymous FTP, please try to use a site near you. The mirror sites listed in the Top Level Domain typically have the entire FreeBSD archive (all the currently available versions for each of the architectures) but you will probably have faster download times from a site that is in your country. The sites in each country carry the most recent versions for the most popular architecture(s) but might not carry the entire FreeBSD archive. Top Level Domain Argentina, Australia, Austria, Brazil, Bulgaria, Canada, China, Croatia, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hong Kong, Hungary, Iceland, Ireland, Italy, Japan, Korea, Lithuania, Netherlands, New Zealand, Norway, Poland, Romania, Russia, Saudi Arabia, Singapore, Slovak Republic, Slovenia, South Africa, Spain, Sweden, Switzerland, Taiwan, Thailand, UK, Ukraine, USA. Top Level Domain In case of problems, please contact the hostmaster mirror-admin@FreeBSD.org for this domain. Argentina In case of problems, please contact the hostmaster hostmaster@ar.FreeBSD.org for this domain. Australia In case of problems, please contact the hostmaster hostmaster@au.FreeBSD.org for this domain. Austria In case of problems, please contact the hostmaster hostmaster@at.FreeBSD.org for this domain. Brazil In case of problems, please contact the hostmaster hostmaster@br.FreeBSD.org for this domain. Bulgaria In case of problems, please contact the hostmaster hostmaster@bg.FreeBSD.org for this domain. Canada In case of problems, please contact the hostmaster hostmaster@ca.FreeBSD.org for this domain. China In case of problems, please contact the hostmaster phj@cn.FreeBSD.org for this domain. Croatia In case of problems, please contact the hostmaster hostmaster@hr.FreeBSD.org for this domain. Czech Republic In case of problems, please contact the hostmaster hostmaster@cz.FreeBSD.org for this domain. Contact: calda@dzungle.ms.mff.cuni.cz Denmark In case of problems, please contact the hostmaster hostmaster@dk.FreeBSD.org for this domain. Estonia In case of problems, please contact the hostmaster hostmaster@ee.FreeBSD.org for this domain. Finland In case of problems, please contact the hostmaster hostmaster@fi.FreeBSD.org for this domain. France In case of problems, please contact the hostmaster hostmaster@fr.FreeBSD.org for this domain. Germany In case of problems, please contact the mirror admins de-bsd-hubs@de.FreeBSD.org for this domain. Greece In case of problems, please contact the hostmaster hostmaster@gr.FreeBSD.org for this domain. Hong Kong Hungary In case of problems, please contact the hostmaster mohacsi@ik.bme.hu for this domain. Iceland In case of problems, please contact the hostmaster hostmaster@is.FreeBSD.org for this domain. Ireland In case of problems, please contact the hostmaster hostmaster@ie.FreeBSD.org for this domain. Italy In case of problems, please contact the hostmaster hostmaster@it.FreeBSD.org for this domain. Japan In case of problems, please contact the hostmaster hostmaster@jp.FreeBSD.org for this domain. Korea In case of problems, please contact the hostmaster hostmaster@kr.FreeBSD.org for this domain. Lithuania In case of problems, please contact the hostmaster hostmaster@lt.FreeBSD.org for this domain. Netherlands In case of problems, please contact the hostmaster hostmaster@nl.FreeBSD.org for this domain. New Zealand In case of problems, please contact the hostmaster hostmaster@nz.FreeBSD.org for this domain. Norway In case of problems, please contact the hostmaster hostmaster@no.FreeBSD.org for this domain. Poland In case of problems, please contact the hostmaster hostmaster@pl.FreeBSD.org for this domain. Romania In case of problems, please contact the hostmaster hostmaster@ro.FreeBSD.org for this domain. Russia In case of problems, please contact the hostmaster hostmaster@ru.FreeBSD.org for this domain. Saudi Arabia In case of problems, please contact ftpadmin@isu.net.sa Singapore In case of problems, please contact the hostmaster hostmaster@sg.FreeBSD.org for this domain. South Africa In case of problems, please contact the hostmaster hostmaster@za.FreeBSD.org for this domain. Slovak Republic In case of problems, please contact the hostmaster hostmaster@sk.FreeBSD.org for this domain. Slovenia In case of problems, please contact the hostmaster hostmaster@si.FreeBSD.org for this domain. Spain In case of problems, please contact the hostmaster hostmaster@es.FreeBSD.org for this domain. Sweden In case of problems, please contact the hostmaster hostmaster@se.FreeBSD.org for this domain. Switzerland In case of problems, please contact the hostmaster hostmaster@ch.FreeBSD.org for this domain. Taiwan In case of problems, please contact the hostmaster hostmaster@tw.FreeBSD.org for this domain. Thailand Contact: ftpadmin@ftp.nectec.or.th. Ukraine Contact: freebsd-mnt@lucky.net. UK In case of problems, please contact the hostmaster hostmaster@uk.FreeBSD.org for this domain. USA In case of problems, please contact the hostmaster hostmaster@us.FreeBSD.org for this domain. Anonymous CVS <anchor id="anoncvs-intro">Introduction Anonymous CVS (or, as it is otherwise known, anoncvs) is a feature provided by the CVS utilities bundled with FreeBSD for synchronizing with a remote CVS repository. Among other things, it allows users of FreeBSD to perform, with no special privileges, read-only CVS operations against one of the FreeBSD project's official anoncvs servers. To use it, one simply sets the CVSROOT environment variable to point at the appropriate anoncvs server, provides the well-known password anoncvs with the cvs login command, and then uses the &man.cvs.1; command to access it like any local repository. The cvs login command, stores the passwords that are used for authenticating to the CVS server in a file called .cvspass in your HOME directory. If this file does not exist, you might get an error when trying to use cvs login for the first time. Just make an empty .cvspass file, and retry to login. While it can also be said that the CVSup and anoncvs services both perform essentially the same function, there are various trade-offs which can influence the user's choice of synchronization methods. In a nutshell, CVSup is much more efficient in its usage of network resources and is by far the most technically sophisticated of the two, but at a price. To use CVSup, a special client must first be installed and configured before any bits can be grabbed, and then only in the fairly large chunks which CVSup calls collections. Anoncvs, by contrast, can be used to examine anything from an individual file to a specific program (like ls or grep) by referencing the CVS module name. Of course, anoncvs is also only good for read-only operations on the CVS repository, so if it is your intention to support local development in one repository shared with the FreeBSD project bits then CVSup is really your only option. <anchor id="anoncvs-usage">Using Anonymous CVS Configuring &man.cvs.1; to use an Anonymous CVS repository is a simple matter of setting the CVSROOT environment variable to point to one of the FreeBSD project's anoncvs servers. At the time of this writing, the following servers are available: USA: :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs (Use cvs login and enter the password anoncvs when prompted.) Germany: :pserver:anoncvs@anoncvs.de.FreeBSD.org:/home/ncvs (Use cvs login and enter the password anoncvs when prompted.) Germany: :pserver:anoncvs@anoncvs2.de.FreeBSD.org:/home/ncvs (rsh, pserver, ssh, ssh/2022) Japan: :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs (Use cvs login and enter the password anoncvs when prompted.) Austria: :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs (Use cvs login and enter any password when prompted.) Since CVS allows one to check out virtually any version of the FreeBSD sources that ever existed (or, in some cases, will exist), you need to be familiar with the revision () flag to &man.cvs.1; and what some of the permissible values for it in the FreeBSD Project repository are. There are two kinds of tags, revision tags and branch tags. A revision tag refers to a specific revision. Its meaning stays the same from day to day. A branch tag, on the other hand, refers to the latest revision on a given line of development, at any given time. Because a branch tag does not refer to a specific revision, it may mean something different tomorrow than it means today. contains revision tags that users might be interested in. Again, none of these are valid for the ports collection since the ports collection does not have multiple revisions. When you specify a branch tag, you normally receive the latest versions of the files on that line of development. If you wish to receive some past version, you can do so by specifying a date with the flag. See the &man.cvs.1; manual page for more details. Examples While it really is recommended that you read the manual page for &man.cvs.1; thoroughly before doing anything, here are some quick examples which essentially show how to use Anonymous CVS: Checking Out Something from -CURRENT (&man.ls.1;) and Deleting It Again: &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co ls &prompt.user; cvs release -d ls &prompt.user; cvs logout Checking Out the Version of &man.ls.1; in the 3.X-STABLE Branch: &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co -rRELENG_3 ls &prompt.user; cvs release -d ls &prompt.user; cvs logout Creating a List of Changes (as Unified Diffs) to &man.ls.1; &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs rdiff -u -rRELENG_3_0_0_RELEASE -rRELENG_3_4_0_RELEASE ls &prompt.user; cvs logout Finding Out What Other Module Names Can Be Used: &prompt.user; setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs &prompt.user; cvs login At the prompt, enter the password anoncvs. &prompt.user; cvs co modules &prompt.user; more modules/modules &prompt.user; cvs release -d modules &prompt.user; cvs logout Other Resources The following additional resources may be helpful in learning CVS: CVS Tutorial from Cal Poly. CVS Home, the CVS development and support community. CVSweb is the FreeBSD Project web interface for CVS. Using CTM CTM is a method for keeping a remote directory tree in sync with a central one. It has been developed for usage with FreeBSD's source trees, though other people may find it useful for other purposes as time goes by. Little, if any, documentation currently exists at this time on the process of creating deltas, so talk to &a.phk; for more information should you wish to use CTM for other things. Why Should I Use <application>CTM</application>? CTM will give you a local copy of the FreeBSD source trees. There are a number of flavors of the tree available. Whether you wish to track the entire CVS tree or just one of the branches, CTM can provide you the information. If you are an active developer on FreeBSD, but have lousy or non-existent TCP/IP connectivity, or simply wish to have the changes automatically sent to you, CTM was made for you. You will need to obtain up to three deltas per day for the most active branches. However, you should consider having them sent by automatic email. The sizes of the updates are always kept as small as possible. This is typically less than 5K, with an occasional (one in ten) being 10-50K and every now and then a large 100K+ or more coming around. You will also need to make yourself aware of the various caveats related to working directly from the development sources rather than a pre-packaged release. This is particularly true if you choose the current sources. It is recommended that you read Staying current with FreeBSD. What Do I Need to Use <application>CTM</application>? You will need two things: The CTM program, and the initial deltas to feed it (to get up to current levels). The CTM program has been part of FreeBSD ever since version 2.0 was released, and lives in /usr/src/usr.sbin/ctm if you have a copy of the source available. If you are running a pre-2.0 version of FreeBSD, you can fetch the current CTM sources directly from: The deltas you feed CTM can be had two ways, FTP or email. If you have general FTP access to the Internet then the following FTP sites support access to CTM: or see section mirrors. FTP the relevant directory and fetch the README file, starting from there. If you wish to get your deltas via email: Subscribe to one of the CTM distribution lists. &a.ctm-cvs-cur.name; supports the entire CVS tree. &a.ctm-src-cur.name; supports the head of the development branch. &a.ctm-src-4.name; supports the 4.X release branch, etc.. (If you do not know how to subscribe yourself to a list, click on the list name above or go to &a.mailman.lists.link; and click on the list that you wish to subscribe to. The list page should contain all of the necessary subscription instructions.) When you begin receiving your CTM updates in the mail, you may use the ctm_rmail program to unpack and apply them. You can actually use the ctm_rmail program directly from a entry in /etc/aliases if you want to have the process run in a fully automated fashion. Check the ctm_rmail manual page for more details. No matter what method you use to get the CTM deltas, you should subscribe to the &a.ctm-announce.name; mailing list. In the future, this will be the only place where announcements concerning the operations of the CTM system will be posted. Click on the list name above and follow the instructions to subscribe to the list. Using <application>CTM</application> for the First Time Before you can start using CTM deltas, you will need to get to a starting point for the deltas produced subsequently to it. First you should determine what you already have. Everyone can start from an empty directory. You must use an initial Empty delta to start off your CTM supported tree. At some point it is intended that one of these started deltas be distributed on the CD for your convenience, however, this does not currently happen. Since the trees are many tens of megabytes, you should prefer to start from something already at hand. If you have a -RELEASE CD, you can copy or extract an initial source from it. This will save a significant transfer of data. You can recognize these starter deltas by the X appended to the number (src-cur.3210XEmpty.gz for instance). The designation following the X corresponds to the origin of your initial seed. Empty is an empty directory. As a rule a base transition from Empty is produced every 100 deltas. By the way, they are large! 70 to 80 Megabytes of gzip'd data is common for the XEmpty deltas. Once you have picked a base delta to start from, you will also need all deltas with higher numbers following it. Using <application>CTM</application> in Your Daily Life To apply the deltas, simply say: &prompt.root; cd /where/ever/you/want/the/stuff &prompt.root; ctm -v -v /where/you/store/your/deltas/src-xxx.* CTM understands deltas which have been put through gzip, so you do not need to gunzip them first, this saves disk space. Unless it feels very secure about the entire process, CTM will not touch your tree. To verify a delta you can also use the flag and CTM will not actually touch your tree; it will merely verify the integrity of the delta and see if it would apply cleanly to your current tree. There are other options to CTM as well, see the manual pages or look in the sources for more information. That is really all there is to it. Every time you get a new delta, just run it through CTM to keep your sources up to date. Do not remove the deltas if they are hard to download again. You just might want to keep them around in case something bad happens. Even if you only have floppy disks, consider using fdwrite to make a copy. Keeping Your Local Changes As a developer one would like to experiment with and change files in the source tree. CTM supports local modifications in a limited way: before checking for the presence of a file foo, it first looks for foo.ctm. If this file exists, CTM will operate on it instead of foo. This behavior gives us a simple way to maintain local changes: simply copy the files you plan to modify to the corresponding file names with a .ctm suffix. Then you can freely hack the code, while CTM keeps the .ctm file up-to-date. Other Interesting <application>CTM</application> Options Finding Out Exactly What Would Be Touched by an Update You can determine the list of changes that CTM will make on your source repository using the option to CTM. This is useful if you would like to keep logs of the changes, pre- or post- process the modified files in any manner, or just are feeling a tad paranoid. Making Backups Before Updating Sometimes you may want to backup all the files that would be changed by a CTM update. Specifying the option causes CTM to backup all files that would be touched by a given CTM delta to backup-file. Restricting the Files Touched by an Update Sometimes you would be interested in restricting the scope of a given CTM update, or may be interested in extracting just a few files from a sequence of deltas. You can control the list of files that CTM would operate on by specifying filtering regular expressions using the and options. For example, to extract an up-to-date copy of lib/libc/Makefile from your collection of saved CTM deltas, run the commands: &prompt.root; cd /where/ever/you/want/to/extract/it/ &prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.* For every file specified in a CTM delta, the and options are applied in the order given on the command line. The file is processed by CTM only if it is marked as eligible after all the and options are applied to it. Future Plans for <application>CTM</application> Tons of them: Use some kind of authentication into the CTM system, so as to allow detection of spoofed CTM updates. Clean up the options to CTM, they became confusing and counter intuitive. Miscellaneous Stuff There is a sequence of deltas for the ports collection too, but interest has not been all that high yet. CTM Mirrors CTM/FreeBSD is available via anonymous FTP from the following mirror sites. If you choose to obtain CTM via anonymous FTP, please try to use a site near you. In case of problems, please contact &a.phk;. California, Bay Area, official source South Africa, backup server for old deltas Taiwan/R.O.C. If you did not find a mirror near to you or the mirror is incomplete, try to use a search engine such as alltheweb. Using CVSup Introduction CVSup is a software package for distributing and updating source trees from a master CVS repository on a remote server host. The FreeBSD sources are maintained in a CVS repository on a central development machine in California. With CVSup, FreeBSD users can easily keep their own source trees up to date. CVSup uses the so-called pull model of updating. Under the pull model, each client asks the server for updates, if and when they are wanted. The server waits passively for update requests from its clients. Thus all updates are instigated by the client. The server never sends unsolicited updates. Users must either run the CVSup client manually to get an update, or they must set up a cron job to run it automatically on a regular basis. The term CVSup, capitalized just so, refers to the entire software package. Its main components are the client cvsup which runs on each user's machine, and the server cvsupd which runs at each of the FreeBSD mirror sites. As you read the FreeBSD documentation and mailing lists, you may see references to sup. Sup was the predecessor of CVSup, and it served a similar purpose. CVSup is used much in the same way as sup and, in fact, uses configuration files which are backward-compatible with sup's. Sup is no longer used in the FreeBSD project, because CVSup is both faster and more flexible. Installation The easiest way to install CVSup is to use the precompiled net/cvsup package from the FreeBSD packages collection. If you prefer to build CVSup from source, you can use the net/cvsup port instead. But be forewarned: the net/cvsup port depends on the Modula-3 system, which takes a substantial amount of time and disk space to download and build. If you are going to be using CVSup on a machine which will not have XFree86 installed, such as a server, be sure to use the port which does not include the CVSup GUI, net/cvsup-without-gui. If you do not know anything about CVSup at all and want a single package which will install it, set up the configuration file and start the transfer via a pointy-clicky type of interface, then get the net/cvsupit package. Just hand it to &man.pkg.add.1; and it will lead you through the configuration process in a menu-oriented fashion. CVSup Configuration CVSup's operation is controlled by a configuration file called the supfile. There are some sample supfiles in the directory /usr/share/examples/cvsup/. The information in a supfile answers the following questions for CVSup: Which files do you want to receive? Which versions of them do you want? Where do you want to get them from? Where do you want to put them on your own machine? Where do you want to put your status files? In the following sections, we will construct a typical supfile by answering each of these questions in turn. First, we describe the overall structure of a supfile. A supfile is a text file. Comments begin with # and extend to the end of the line. Lines that are blank and lines that contain only comments are ignored. Each remaining line describes a set of files that the user wishes to receive. The line begins with the name of a collection, a logical grouping of files defined by the server. The name of the collection tells the server which files you want. After the collection name come zero or more fields, separated by white space. These fields answer the questions listed above. There are two types of fields: flag fields and value fields. A flag field consists of a keyword standing alone, e.g., delete or compress. A value field also begins with a keyword, but the keyword is followed without intervening white space by = and a second word. For example, release=cvs is a value field. A supfile typically specifies more than one collection to receive. One way to structure a supfile is to specify all of the relevant fields explicitly for each collection. However, that tends to make the supfile lines quite long, and it is inconvenient because most fields are the same for all of the collections in a supfile. CVSup provides a defaulting mechanism to avoid these problems. Lines beginning with the special pseudo-collection name *default can be used to set flags and values which will be used as defaults for the subsequent collections in the supfile. A default value can be overridden for an individual collection, by specifying a different value with the collection itself. Defaults can also be changed or augmented in mid-supfile by additional *default lines. With this background, we will now proceed to construct a supfile for receiving and updating the main source tree of FreeBSD-CURRENT. Which files do you want to receive? The files available via CVSup are organized into named groups called collections. The collections that are available are described in the following section. In this example, we wish to receive the entire main source tree for the FreeBSD system. There is a single large collection src-all which will give us all of that. As a first step toward constructing our supfile, we simply list the collections, one per line (in this case, only one line): src-all Which version(s) of them do you want? With CVSup, you can receive virtually any version of the sources that ever existed. That is possible because the cvsupd server works directly from the CVS repository, which contains all of the versions. You specify which one of them you want using the tag= and value fields. Be very careful to specify any tag= fields correctly. Some tags are valid only for certain collections of files. If you specify an incorrect or misspelled tag, CVSup will delete files which you probably do not want deleted. In particular, use only tag=. for the ports-* collections. The tag= field names a symbolic tag in the repository. There are two kinds of tags, revision tags and branch tags. A revision tag refers to a specific revision. Its meaning stays the same from day to day. A branch tag, on the other hand, refers to the latest revision on a given line of development, at any given time. Because a branch tag does not refer to a specific revision, it may mean something different tomorrow than it means today. contains branch tags that users might be interested in. When specifying a tag in CVSup's configuration file, it must be preceded with tag= (RELENG_4 will become tag=RELENG_4). Keep in mind that only the tag=. is relevant for the ports collection. Be very careful to type the tag name exactly as shown. CVSup cannot distinguish between valid and invalid tags. If you misspell the tag, CVSup will behave as though you had specified a valid tag which happens to refer to no files at all. It will delete your existing sources in that case. When you specify a branch tag, you normally receive the latest versions of the files on that line of development. If you wish to receive some past version, you can do so by specifying a date with the value field. The &man.cvsup.1; manual page explains how to do that. For our example, we wish to receive FreeBSD-CURRENT. We add this line at the beginning of our supfile: *default tag=. There is an important special case that comes into play if you specify neither a tag= field nor a date= field. In that case, you receive the actual RCS files directly from the server's CVS repository, rather than receiving a particular version. Developers generally prefer this mode of operation. By maintaining a copy of the repository itself on their systems, they gain the ability to browse the revision histories and examine past versions of files. This gain is achieved at a large cost in terms of disk space, however. Where do you want to get them from? We use the host= field to tell cvsup where to obtain its updates. Any of the CVSup mirror sites will do, though you should try to select one that is close to you in cyberspace. In this example we will use a fictional FreeBSD distribution site, cvsup666.FreeBSD.org: *default host=cvsup666.FreeBSD.org You will need to change the host to one that actually exists before running CVSup. On any particular run of cvsup, you can override the host setting on the command line, with . Where do you want to put them on your own machine? The prefix= field tells cvsup where to put the files it receives. In this example, we will put the source files directly into our main source tree, /usr/src. The src directory is already implicit in the collections we have chosen to receive, so this is the correct specification: *default prefix=/usr Where should cvsup maintain its status files? The CVSup client maintains certain status files in what is called the base directory. These files help CVSup to work more efficiently, by keeping track of which updates you have already received. We will use the standard base directory, /usr/local/etc/cvsup: *default base=/usr/local/etc/cvsup This setting is used by default if it is not specified in the supfile, so we actually do not need the above line. If your base directory does not already exist, now would be a good time to create it. The cvsup client will refuse to run if the base directory does not exist. Miscellaneous supfile settings: There is one more line of boiler plate that normally needs to be present in the supfile: *default release=cvs delete use-rel-suffix compress release=cvs indicates that the server should get its information out of the main FreeBSD CVS repository. This is virtually always the case, but there are other possibilities which are beyond the scope of this discussion. delete gives CVSup permission to delete files. You should always specify this, so that CVSup can keep your source tree fully up-to-date. CVSup is careful to delete only those files for which it is responsible. Any extra files you happen to have will be left strictly alone. use-rel-suffix is ... arcane. If you really want to know about it, see the &man.cvsup.1; manual page. Otherwise, just specify it and do not worry about it. compress enables the use of gzip-style compression on the communication channel. If your network link is T1 speed or faster, you probably should not use compression. Otherwise, it helps substantially. Putting it all together: Here is the entire supfile for our example: *default tag=. *default host=cvsup666.FreeBSD.org *default prefix=/usr *default base=/usr/local/etc/cvsup *default release=cvs delete use-rel-suffix compress src-all The <filename>refuse</filename> File As mentioned above, CVSup uses a pull method. Basically, this means that you connect to the CVSup server, and it says, Here is what you can download from me..., and your client responds OK, I will take this, this, this, and this. In the default configuration, the CVSup client will take every file associated with the collection and tag you chose in the configuration file. However, this is not always what you want, especially if you are synching the doc, ports, or www trees — most people cannot read four or five languages, and therefore they do not need to download the language-specific files. If you are CVSuping the ports collection, you can get around this by specifying each collection individually (e.g., ports-astrology, ports-biology, etc instead of simply saying ports-all). However, since the doc and www trees do not have language-specific collections, you must use one of CVSup's many nifty features: the refuse file. The refuse file essentially tells CVSup that it should not take every single file from a collection; in other words, it tells the client to refuse certain files from the server. The refuse file can be found (or, if you do not yet have one, should be placed) in base/sup/. base is defined in your supfile; by default, base is /usr/local/etc/cvsup, which means that by default the refuse file is /usr/local/etc/cvsup/sup/refuse. The refuse file has a very simple format; it simply contains the names of files or directories that you do not wish to download. For example, if you cannot speak any languages other than English and some German, and you do not feel the need to use the German applications (or applications for any other languages, except for English), you can put the following in your refuse file: ports/chinese ports/french ports/german ports/hebrew ports/hungarian ports/japanese ports/korean ports/portuguese ports/russian ports/ukrainian ports/vietnamese doc/da_* doc/de_* doc/el_* doc/es_* doc/fr_* doc/it_* doc/ja_* doc/nl_* doc/no_* doc/pl_* doc/pt_* doc/ru_* doc/sr_* doc/zh_* and so forth for the other languages (you can find the full list by browsing the FreeBSD CVS repository). With this very useful feature, those users who are on slow links or pay by the minute for their Internet connection will be able to save valuable time as they will no longer need to download files that they will never use. For more information on refuse files and other neat features of CVSup, please view its manual page. Running <application>CVSup</application> You are now ready to try an update. The command line for doing this is quite simple: &prompt.root; cvsup supfile where supfile is of course the name of the supfile you have just created. Assuming you are running under X11, cvsup will display a GUI window with some buttons to do the usual things. Press the go button, and watch it run. Since you are updating your actual /usr/src tree in this example, you will need to run the program as root so that cvsup has the permissions it needs to update your files. Having just created your configuration file, and having never used this program before, that might understandably make you nervous. There is an easy way to do a trial run without touching your precious files. Just create an empty directory somewhere convenient, and name it as an extra argument on the command line: &prompt.root; mkdir /var/tmp/dest &prompt.root; cvsup supfile /var/tmp/dest The directory you specify will be used as the destination directory for all file updates. CVSup will examine your usual files in /usr/src, but it will not modify or delete any of them. Any file updates will instead land in /var/tmp/dest/usr/src. CVSup will also leave its base directory status files untouched when run this way. The new versions of those files will be written into the specified directory. As long as you have read access to /usr/src, you do not even need to be root to perform this kind of trial run. If you are not running X11 or if you just do not like GUIs, you should add a couple of options to the command line when you run cvsup: &prompt.root; cvsup -g -L 2 supfile The tells CVSup not to use its GUI. This is automatic if you are not running X11, but otherwise you have to specify it. The tells CVSup to print out the details of all the file updates it is doing. There are three levels of verbosity, from to . The default is 0, which means total silence except for error messages. There are plenty of other options available. For a brief list of them, type cvsup -H. For more detailed descriptions, see the manual page. Once you are satisfied with the way updates are working, you can arrange for regular runs of CVSup using &man.cron.8;. Obviously, you should not let CVSup use its GUI when running it from &man.cron.8;. <application>CVSup</application> File Collections The file collections available via CVSup are organized hierarchically. There are a few large collections, and they are divided into smaller sub-collections. Receiving a large collection is equivalent to receiving each of its sub-collections. The hierarchical relationships among collections are reflected by the use of indentation in the list below. The most commonly used collections are src-all, and ports-all. The other collections are used only by small groups of people for specialized purposes, and some mirror sites may not carry all of them. cvs-all release=cvs The main FreeBSD CVS repository, including the cryptography code. distrib release=cvs Files related to the distribution and mirroring of FreeBSD. doc-all release=cvs Sources for the FreeBSD Handbook and other documentation. This does not include files for the FreeBSD web site. ports-all release=cvs The FreeBSD Ports Collection. If you do not want to update the whole of ports-all (the whole ports tree), but use one of the subcollections listed below, make sure that you always update the ports-base subcollection! Whenever something changes in the ports build infrastructure represented by ports-base, it is virtually certain that those changes will be used by real ports real soon. Thus, if you only update the real ports and they use some of the new features, there is a very high chance that their build will fail with some mysterious error message. The very first thing to do in this case is to make sure that your ports-base subcollection is up to date. ports-archivers release=cvs Archiving tools. ports-astro release=cvs Astronomical ports. ports-audio release=cvs Sound support. ports-base release=cvs The Ports Collection build infrastructure - various files located in the Mk/ and Tools/ subdirectories of /usr/ports. Please see the important warning above: you should always update this subcollection, whenever you update any part of the FreeBSD Ports Collection! ports-benchmarks release=cvs Benchmarks. ports-biology release=cvs Biology. ports-cad release=cvs Computer aided design tools. ports-chinese release=cvs Chinese language support. ports-comms release=cvs Communication software. ports-converters release=cvs character code converters. ports-databases release=cvs Databases. ports-deskutils release=cvs Things that used to be on the desktop before computers were invented. ports-devel release=cvs Development utilities. ports-editors release=cvs Editors. ports-emulators release=cvs Emulators for other operating systems. ports-finance release=cvs Monetary, financial and related applications. ports-ftp release=cvs FTP client and server utilities. ports-games release=cvs Games. ports-german release=cvs German language support. ports-graphics release=cvs Graphics utilities. ports-hungarian release=cvs Hungarian language support. ports-irc release=cvs Internet Relay Chat utilities. ports-japanese release=cvs Japanese language support. ports-java release=cvs Java utilities. ports-korean release=cvs Korean language support. ports-lang release=cvs Programming languages. ports-mail release=cvs Mail software. ports-math release=cvs Numerical computation software. ports-mbone release=cvs MBone applications. ports-misc release=cvs Miscellaneous utilities. ports-multimedia release=cvs Multimedia software. ports-net release=cvs Networking software. ports-news release=cvs USENET news software. ports-palm release=cvs Software support for Palm series. ports-portuguese release=cvs Portuguese language support. ports-print release=cvs Printing software. ports-russian release=cvs Russian language support. ports-security release=cvs Security utilities. ports-shells release=cvs Command line shells. ports-sysutils release=cvs System utilities. ports-textproc release=cvs text processing utilities (does not include desktop publishing). ports-vietnamese release=cvs Vietnamese language support. ports-www release=cvs Software related to the World Wide Web. ports-x11 release=cvs Ports to support the X window system. ports-x11-clocks release=cvs X11 clocks. ports-x11-fm release=cvs X11 file managers. ports-x11-fonts release=cvs X11 fonts and font utilities. ports-x11-toolkits release=cvs X11 toolkits. ports-x11-servers X11 servers. ports-x11-wm X11 window managers. src-all release=cvs The main FreeBSD sources, including the cryptography code. src-base release=cvs Miscellaneous files at the top of /usr/src. src-bin release=cvs User utilities that may be needed in single-user mode (/usr/src/bin). src-contrib release=cvs Utilities and libraries from outside the FreeBSD project, used relatively unmodified (/usr/src/contrib). src-crypto release=cvs Cryptography utilities and libraries from outside the FreeBSD project, used relatively unmodified (/usr/src/crypto). src-eBones release=cvs Kerberos and DES (/usr/src/eBones). Not used in current releases of FreeBSD. src-etc release=cvs System configuration files (/usr/src/etc). src-games release=cvs Games (/usr/src/games). src-gnu release=cvs Utilities covered by the GNU Public License (/usr/src/gnu). src-include release=cvs Header files (/usr/src/include). src-kerberos5 release=cvs Kerberos5 security package (/usr/src/kerberos5). src-kerberosIV release=cvs KerberosIV security package (/usr/src/kerberosIV). src-lib release=cvs Libraries (/usr/src/lib). src-libexec release=cvs System programs normally executed by other programs (/usr/src/libexec). src-release release=cvs Files required to produce a FreeBSD release (/usr/src/release). src-sbin release=cvs System utilities for single-user mode (/usr/src/sbin). src-secure release=cvs Cryptographic libraries and commands (/usr/src/secure). src-share release=cvs Files that can be shared across multiple systems (/usr/src/share). src-sys release=cvs The kernel (/usr/src/sys). src-sys-crypto release=cvs Kernel cryptography code (/usr/src/sys/crypto). src-tools release=cvs Various tools for the maintenance of FreeBSD (/usr/src/tools). src-usrbin release=cvs User utilities (/usr/src/usr.bin). src-usrsbin release=cvs System utilities (/usr/src/usr.sbin). www release=cvs The sources for the FreeBSD WWW site. distrib release=self The CVSup server's own configuration files. Used by CVSup mirror sites. gnats release=current The GNATS bug-tracking database. mail-archive release=current FreeBSD mailing list archive. www release=current The pre-processed FreeBSD WWW site files (not the source files). Used by WWW mirror sites. For More Information For the CVSup FAQ and other information about CVSup, see The CVSup Home Page. Most FreeBSD-related discussion of CVSup takes place on the &a.hackers;. New versions of the software are announced there, as well as on the &a.announce;. Questions and bug reports should be addressed to the author of the program at cvsup-bugs@polstra.com. CVSup Sites CVSup servers for FreeBSD are running at the following sites: Top Level Domain cvsup1.FreeBSD.org (maintainer cwt@networks.cwu.edu), Washington state cvsup2.FreeBSD.org (maintainers djs@secure.net and &a.nectar;), Virginia cvsup3.FreeBSD.org (maintainer &a.wollman;), Massachusetts cvsup5.FreeBSD.org (maintainer mjr@blackened.com), Arizona cvsup6.FreeBSD.org (maintainer cvsup@cvsup.adelphiacom.net), Illinois cvsup7.FreeBSD.org (maintainer &a.jdp;), Washington state cvsup8.FreeBSD.org (maintainer hostmaster@bigmirror.com), Washington state cvsup9.FreeBSD.org (maintainer &a.jdp;), Minnesota cvsup10.FreeBSD.org (maintainer &a.jdp;), California cvsup11.FreeBSD.org (maintainer cvsup@research.uu.net), Virginia cvsup12.FreeBSD.org (maintainer &a.will;), Indiana cvsup13.FreeBSD.org (maintainer dima@valueclick.com), California cvsup14.FreeBSD.org (maintainer freebsd-cvsup@mfnx.net), California cvsup15.FreeBSD.org (maintainer cvsup@math.uic.edu), Illinois cvsup16.FreeBSD.org (maintainer pth3k@virginia.edu), Virginia cvsup18.FreeBSD.org (maintainer cvsup@aphix.com), Wisconsin state Argentina cvsup.ar.FreeBSD.org (maintainer msagre@cactus.fi.uba.ar) Australia cvsup.au.FreeBSD.org (maintainer cvsup@ntt.net.au) cvsup2.au.FreeBSD.org (maintainer cvsup@isp.net.au) cvsup3.au.FreeBSD.org (maintainer cvsup@speednet.com.au) cvsup4.au.FreeBSD.org (maintainer cvsup@ideal.net.au) cvsup5.au.FreeBSD.org (maintainer cvsup@netlead.com.au) Austria cvsup.at.FreeBSD.org (maintainer postmaster@wu-wien.ac.at) cvsup2.at.FreeBSD.org (maintainer ftp-admin.zid@univie.ac.at) Brazil cvsup.br.FreeBSD.org (maintainer cvsup@cvsup.br.FreeBSD.org) cvsup2.br.FreeBSD.org (maintainer tps@ti.sk) cvsup3.br.FreeBSD.org (maintainer camposr@matrix.com.br) cvsup4.br.FreeBSD.org (maintainer cvsup@tcoip.com.br) cvsup5.br.FreeBSD.org (maintainer hostmaster@br.FreeBSD.org) Bulgaria cvsup.bg.FreeBSD.org (maintainer hostmaster@bg.FreeBSD.org) Canada cvsup.ca.FreeBSD.org (maintainer cvsup@cvsup.ca.FreeBSD.org) China cvsup.cn.FreeBSD.org (maintainer phj@cn.FreeBSD.org) Czech Republic cvsup.cz.FreeBSD.org (maintainer cejkar@fit.vutbr.cz) Denmark cvsup.dk.FreeBSD.org (maintainer jesper@FreeBSD.org) Estonia cvsup.ee.FreeBSD.org (maintainer taavi@uninet.ee) Finland cvsup.fi.FreeBSD.org (maintainer count@key.sms.fi) cvsup2.fi.FreeBSD.org (maintainer count@key.sms.fi) France cvsup.fr.FreeBSD.org (maintainer hostmaster@fr.FreeBSD.org) cvsup2.fr.FreeBSD.org (maintainer ftpmaint@uvsq.fr) cvsup3.fr.FreeBSD.org (maintainer ftpmaint@enst.fr) cvsup4.fr.FreeBSD.org (maintainer ftpmaster@t-online.fr) cvsup5.fr.FreeBSD.org (maintainer freebsdcvsup@teaser.net) cvsup8.fr.FreeBSD.org (maintainer ftpmaint@crc.u-strasbg.fr) Germany cvsup.de.FreeBSD.org (maintainer cvsup@cosmo-project.de) cvsup2.de.FreeBSD.org (maintainer cvsup@apfel.de) cvsup3.de.FreeBSD.org (maintainer ag@leo.org) cvsup4.de.FreeBSD.org (maintainer cvsup@cosmo-project.de) cvsup5.de.FreeBSD.org (maintainer &a.rse;) cvsup6.de.FreeBSD.org (maintainer adminmail@heitec.net) cvsup7.de.FreeBSD.org (maintainer karsten@rohrbach.de) Greece cvsup.gr.FreeBSD.org (maintainer ftpadm@duth.gr) cvsup2.gr.FreeBSD.org (maintainer paschos@cs.uoi.gr) Hungary cvsup.hu.FreeBSD.org (maintainer janos.mohacsi@bsd.hu) Iceland cvsup.is.FreeBSD.org (maintainer hostmaster@is.FreeBSD.org) Ireland cvsup.ie.FreeBSD.org (maintainer dwmalone@maths.tcd.ie), Trinity College, Dublin. Japan cvsup.jp.FreeBSD.org (maintainer cvsupadm@jp.FreeBSD.org) cvsup2.jp.FreeBSD.org (maintainer &a.max;) cvsup3.jp.FreeBSD.org (maintainer shige@cin.nihon-u.ac.jp) cvsup4.jp.FreeBSD.org (maintainer cvsup-admin@ftp.media.kyoto-u.ac.jp) cvsup5.jp.FreeBSD.org (maintainer cvsup@imasy.or.jp) cvsup6.jp.FreeBSD.org (maintainer cvsupadm@jp.FreeBSD.org) Korea cvsup.kr.FreeBSD.org (maintainer cjh@kr.FreeBSD.org) cvsup2.kr.FreeBSD.org (maintainer holywar@mail.holywar.net) cvsup3.kr.FreeBSD.org (maintainer leo@florida.sarang.net) Kuwait cvsup1.kw.FreeBSD.org (maintainer sysadmin@kems.net) Latvia cvsup.lv.FreeBSD.org (maintainer system@soft.lv) Lithuania cvsup.lt.FreeBSD.org (maintainer domas.mituzas@delfi.lt) cvsup2.lt.FreeBSD.org (maintainer vaidas.damosevicius@if.lt) New Zealand cvsup.nz.FreeBSD.org (maintainer cvsup@langille.org) Netherlands cvsup.nl.FreeBSD.org (maintainer xaa@xaa.iae.nl) cvsup2.nl.FreeBSD.org (maintainer cvsup@nl.uu.net) cvsup3.nl.FreeBSD.org (maintainer cvsup@vuurwerk.nl) cvsup4.nl.FreeBSD.org (maintainer hostmaster@cvsup4.nl.FreeBSD.org) cvsup5.nl.FreeBSD.org (maintainer vincent@nlisp.nl) Norway cvsup.no.FreeBSD.org (maintainer Per.Hove@math.ntnu.no) Philippines cvsup1.ph.FreeBSD.org (maintainer cvsadmin@freebsd.org.ph) Poland cvsup.pl.FreeBSD.org (maintainer mariusz@provector.pl) cvsup2.pl.FreeBSD.org (maintainer hostmaster@cvsup2.pl.FreeBSD.org) cvsup3.pl.FreeBSD.org (maintainer hostmaster@cvsup3.pl.FreeBSD.org) Portugal cvsup.pt.FreeBSD.org (maintainer jpedras@webvolution.net) Romania cvsup.ro.FreeBSD.org (maintainer razor@ldc.ro) cvsup2.ro.FreeBSD.org (maintainer hostmaster@rofug.ro) cvsup3.ro.FreeBSD.org (maintainer veedee@c7.campus.utcluj.ro) Russia cvsup.ru.FreeBSD.org (maintainer ache@nagual.pp.ru) cvsup2.ru.FreeBSD.org (maintainer dv@dv.ru) cvsup3.ru.FreeBSD.org (maintainer fjoe@iclub.nsu.ru) cvsup4.ru.FreeBSD.org (maintainer maxim@macomnet.ru) cvsup5.ru.FreeBSD.org (maintainer maxim@macomnet.ru) cvsup6.ru.FreeBSD.org (maintainer pvr@corbina.net) San Marino cvsup.sm.FreeBSD.org (maintainer sysadmin@alexdupre.com) Singapore cvsup.sg.FreeBSD.org (maintainer mirror-maintainer@mirror.averse.net) Slovak Republic cvsup.sk.FreeBSD.org (maintainer scorp@scorp.sk) cvsup2.sk.FreeBSD.org (maintainer scorp@scorp.sk) Slovenia cvsup.si.FreeBSD.org (maintainer blaz@si.FreeBSD.org) cvsup2.si.FreeBSD.org (maintainer cuk@cuk.nu) South Africa cvsup.za.FreeBSD.org (maintainer &a.markm;) cvsup2.za.FreeBSD.org (maintainer &a.markm;) Spain cvsup.es.FreeBSD.org (maintainer &a.jesusr;) cvsup2.es.FreeBSD.org (maintainer &a.jesusr;) cvsup3.es.FreeBSD.org (maintainer jose@we.lc.ehu.es) Sweden cvsup.se.FreeBSD.org (maintainer pantzer@ludd.luth.se) cvsup2.se.FreeBSD.org (maintainer cvsup@dataphone.net) Taiwan cvsup.tw.FreeBSD.org (maintainer ijliao@FreeBSD.org) cvsup3.tw.FreeBSD.org (maintainer foxfair@FreeBSD.org) cvsup4.tw.FreeBSD.org (maintainer einstein@NHCTC.edu.tw) cvsup5.tw.FreeBSD.org (maintainer einstein@NHCTC.edu.tw) cvsup6.tw.FreeBSD.org (maintainer jason@tw.FreeBSD.org) cvsup7.tw.FreeBSD.org (maintainer cvsup@abpe.org) cvsup8.tw.FreeBSD.org (maintainer heboy@FreeBSD.tku.edu.tw) cvsup9.tw.FreeBSD.org (maintainer cs871256@csie.ncu.edu.tw) cvsup10.tw.FreeBSD.org (maintainer rafan@infor.org) cvsup11.tw.FreeBSD.org (maintainer vanilla@FreeBSD.org) cvsup12.tw.FreeBSD.org (maintainer GEO.bbs@birdnest.twbbs.org) cvsup13.tw.FreeBSD.org (maintainer cdsheen@tw.FreeBSD.org) Turkey cvsup.tr.FreeBSD.org (maintainer roots@enderunix.org) Ukraine cvsup2.ua.FreeBSD.org (maintainer freebsd-mnt@lucky.net) cvsup3.ua.FreeBSD.org (maintainer ftpmaster@ukr.net), Kiev cvsup4.ua.FreeBSD.org (maintainer phantom@cris.net) cvsup5.ua.FreeBSD.org (maintainer never@nevermind.kiev.ua) cvsup6.ua.FreeBSD.org (maintainer freebsd-cvs@colocall.net) cvsup7.ua.FreeBSD.org (maintainer never@nevermind.kiev.ua) United Kingdom cvsup.uk.FreeBSD.org (maintainer ftp-admin@plig.net) cvsup2.uk.FreeBSD.org (maintainer &a.brian;) cvsup3.uk.FreeBSD.org (maintainer ejb@leguin.org.uk) cvsup4.uk.FreeBSD.org (maintainer mirror@teleglobe.net) USA cvsup1.us.FreeBSD.org (maintainer cwt@networks.cwu.edu), Washington state cvsup2.us.FreeBSD.org (maintainers djs@secure.net and &a.nectar;), Virginia cvsup3.us.FreeBSD.org (maintainer &a.wollman;), Massachusetts cvsup5.us.FreeBSD.org (maintainer mjr@blackened.com), Arizona cvsup6.us.FreeBSD.org (maintainer cvsup@cvsup.adelphiacom.net), Illinois cvsup7.us.FreeBSD.org (maintainer &a.jdp;), Washington state cvsup8.us.FreeBSD.org (maintainer hostmaster@bigmirror.com), Washington state cvsup9.us.FreeBSD.org (maintainer &a.jdp;), Minnesota cvsup10.us.FreeBSD.org (maintainer &a.jdp;), California cvsup11.us.FreeBSD.org (maintainer cvsup@research.uu.net), Virginia cvsup12.us.FreeBSD.org (maintainer &a.will;), Indiana cvsup13.us.FreeBSD.org (maintainer dima@valueclick.com), California cvsup14.us.FreeBSD.org (maintainer freebsd-cvsup@mfnx.net), California cvsup15.us.FreeBSD.org (maintainer cvsup@math.uic.edu), Illinois cvsup16.us.FreeBSD.org (maintainer pth3k@virginia.edu), Virginia cvsup17.us.FreeBSD.org (maintainer cvsup@mirrortree.com), Washington state cvsup18.us.FreeBSD.org (maintainer cvsup@aphix.com), Wisconsin state CVS Tags When obtaining or updating sources from cvs and CVSup a revision tag (reference to a date in time) must be specified. A revision tag refers to either a particular line of FreeBSD development, or a specific point in time. The first type are called branch tags, the second type are called release tags. Branch Tags All of these, with the exception of HEAD (which is always a valid tag), only apply to the src/ tree. The ports/, doc/, and www/ trees are not branched. HEAD Symbolic name for the main line, or FreeBSD-CURRENT. Also the default when no revision is specified. In CVSup, this tag is represented by a . (not punctuation, but a literal . character). In CVS, this is the default when no revision tag is specified. It is usually not a good idea to checkout or update to CURRENT sources on a STABLE machine, unless that is your intent. RELENG_5_1 The release branch for FreeBSD-5.1, used only for security advisories and other seriously critical fixes. RELENG_5_0 The release branch for FreeBSD-5.0, used only for security advisories and other seriously critical fixes. RELENG_4 The line of development for FreeBSD-4.X, also known as FreeBSD-STABLE. RELENG_4_8 The release branch for FreeBSD-4.8, used only for security advisories and other seriously critical fixes. RELENG_4_7 The release branch for FreeBSD-4.7, used only for security advisories and other seriously critical fixes. RELENG_4_6 The release branch for FreeBSD-4.6 and FreeBSD-4.6.2, used only for security advisories and other seriously critical fixes. RELENG_4_5 The release branch for FreeBSD-4.5, used only for security advisories and other seriously critical fixes. RELENG_4_4 The release branch for FreeBSD-4.4, used only for security advisories and other seriously critical fixes. RELENG_4_3 The release branch for FreeBSD-4.3, used only for security advisories and other seriously critical fixes. RELENG_3 The line of development for FreeBSD-3.X, also known as 3.X-STABLE. RELENG_2_2 The line of development for FreeBSD-2.2.X, also known as 2.2-STABLE. This branch is mostly obsolete. + Release Tags These tags correspond to the FreeBSD src/ tree (and ports/, doc/, and www/ trees) at a specific point in time, when a particular version of FreeBSD was released. RELENG_5_1_0_RELEASE FreeBSD 5.1 RELENG_4_8_0_RELEASE FreeBSD 4.8 RELENG_5_0_0_RELEASE FreeBSD 5.0 RELENG_4_7_0_RELEASE FreeBSD 4.7 RELENG_4_6_2_RELEASE FreeBSD 4.6.2 RELENG_4_6_1_RELEASE FreeBSD 4.6.1 RELENG_4_6_0_RELEASE FreeBSD 4.6 RELENG_4_5_0_RELEASE FreeBSD 4.5 RELENG_4_4_0_RELEASE FreeBSD 4.4 RELENG_4_3_0_RELEASE FreeBSD 4.3 RELENG_4_2_0_RELEASE FreeBSD 4.2 RELENG_4_1_1_RELEASE FreeBSD 4.1.1 RELENG_4_1_0_RELEASE FreeBSD 4.1 RELENG_4_0_0_RELEASE FreeBSD 4.0 RELENG_3_5_0_RELEASE FreeBSD-3.5 RELENG_3_4_0_RELEASE FreeBSD-3.4 RELENG_3_3_0_RELEASE FreeBSD-3.3 RELENG_3_2_0_RELEASE FreeBSD-3.2 RELENG_3_1_0_RELEASE FreeBSD-3.1 RELENG_3_0_0_RELEASE FreeBSD-3.0 RELENG_2_2_8_RELEASE FreeBSD-2.2.8 RELENG_2_2_7_RELEASE FreeBSD-2.2.7 RELENG_2_2_6_RELEASE FreeBSD-2.2.6 RELENG_2_2_5_RELEASE FreeBSD-2.2.5 RELENG_2_2_2_RELEASE FreeBSD-2.2.2 RELENG_2_2_1_RELEASE FreeBSD-2.2.1 RELENG_2_2_0_RELEASE FreeBSD-2.2.0 AFS Sites AFS servers for FreeBSD are running at the following sites: Sweden The path to the files are: /afs/stacken.kth.se/ftp/pub/FreeBSD/ stacken.kth.se # Stacken Computer Club, KTH, Sweden 130.237.234.43 #hot.stacken.kth.se 130.237.237.230 #fishburger.stacken.kth.se 130.237.234.3 #milko.stacken.kth.se Maintainer ftp@stacken.kth.se rsync Sites The following sites make FreeBSD available through the rsync protocol. The rsync utility works in much the same way as the &man.rcp.1; command, but has more options and uses the rsync remote-update protocol which transfers only the differences between two sets of files, thus greatly speeding up the synchronization over the network. This is most useful if you are a mirror site for the FreeBSD FTP server, or the CVS repository. The rsync suite is available for many operating systems, on FreeBSD, see the net/rsync port or use the package. Czech Republic rsync://ftp.cz.FreeBSD.org/ Available collections: ftp: A partial mirror of the FreeBSD FTP server. FreeBSD: A full mirror of the FreeBSD FTP server. Germany rsync://grappa.unix-ag.uni-kl.de/ Available collections: freebsd-cvs: The full FreeBSD CVS repository. This machine also mirrors the CVS repositories of the NetBSD and the OpenBSD projects, among others. Netherlands rsync://ftp.nl.FreeBSD.org/ Available collections: vol/3/freebsd-core: A full mirror of the FreeBSD FTP server. United Kingdom rsync://rsync.mirror.ac.uk/ Available collections: ftp.freebsd.org: A full mirror of the FreeBSD FTP server. United States of America rsync://ftp-master.FreeBSD.org/ This server may only be used by FreeBSD primary mirror sites. Available collections: FreeBSD: The master archive of the FreeBSD FTP server. acl: The FreeBSD master ACL list. rsync://ftp13.FreeBSD.org/ Available collections: FreeBSD: A full mirror of the FreeBSD FTP server. diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml index da97da5064..c8be7cf5d9 100644 --- a/en_US.ISO8859-1/books/handbook/security/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml @@ -1,4558 +1,4559 @@ Matthew Dillon Much of this chapter has been taken from the security(7) manual page by Security security Synopsis This chapter will provide a basic introduction to system security concepts, some general good rules of thumb, and some advanced topics under FreeBSD. A lot of the topics covered here can be applied to system and Internet security in general as well. The Internet is no longer a friendly place in which everyone wants to be your kind neighbor. Securing your system is imperative to protect your data, intellectual property, time, and much more from the hands of hackers and the like. FreeBSD provides an array of utilities and mechanisms to ensure the integrity and security of your system and network. After reading this chapter, you will know: Basic system security concepts, in respect to FreeBSD. About the various crypt mechanisms available in FreeBSD, such as DES and MD5. How to set up one-time password authentication. How to set up Kerberos, another alternative authentication system. How to create firewalls using IPFW. How to configure IPsec and create a VPN between FreeBSD/&windows; machines. How to configure and use OpenSSH, FreeBSD's SSH implementation. How to configure and load access control extension modules using the TrustedBSD MAC Framework. What file system ACLs are and how to use them. Before reading this chapter, you should: Understand basic FreeBSD and Internet concepts. Introduction Security is a function that begins and ends with the system administrator. While all BSD &unix; multi-user systems have some inherent security, the job of building and maintaining additional security mechanisms to keep those users honest is probably one of the single largest undertakings of the sysadmin. Machines are only as secure as you make them, and security concerns are ever competing with the human necessity for convenience. &unix; systems, in general, are capable of running a huge number of simultaneous processes and many of these processes operate as servers – meaning that external entities can connect and talk to them. As yesterday's mini-computers and mainframes become today's desktops, and as computers become networked and internetworked, security becomes an even bigger issue. Security is best implemented through a layered onion approach. In a nutshell, what you want to do is to create as many layers of security as are convenient and then carefully monitor the system for intrusions. You do not want to overbuild your security or you will interfere with the detection side, and detection is one of the single most important aspects of any security mechanism. For example, it makes little sense to set the schg flags (see &man.chflags.1;) on every system binary because while this may temporarily protect the binaries, it prevents an attacker who has broken in from making an easily detectable change that may result in your security mechanisms not detecting the attacker at all. System security also pertains to dealing with various forms of attack, including attacks that attempt to crash, or otherwise make a system unusable, but do not attempt to compromise the root account (break root). Security concerns can be split up into several categories: Denial of service attacks. User account compromises. Root compromise through accessible servers. Root compromise via user accounts. Backdoor creation. DoS attacks Denial of Service (DoS) security DoS attacks Denial of Service (DoS) Denial of Service (DoS) A denial of service attack is an action that deprives the machine of needed resources. Typically, DoS attacks are brute-force mechanisms that attempt to crash or otherwise make a machine unusable by overwhelming its servers or network stack. Some DoS attacks try to take advantage of bugs in the networking stack to crash a machine with a single packet. The latter can only be fixed by applying a bug fix to the kernel. Attacks on servers can often be fixed by properly specifying options to limit the load the servers incur on the system under adverse conditions. Brute-force network attacks are harder to deal with. A spoofed-packet attack, for example, is nearly impossible to stop, short of cutting your system off from the Internet. It may not be able to take your machine down, but it can saturate your Internet connection. security account compromises A user account compromise is even more common than a DoS attack. Many sysadmins still run standard telnetd, rlogind, rshd, and ftpd servers on their machines. These servers, by default, do not operate over encrypted connections. The result is that if you have any moderate-sized user base, one or more of your users logging into your system from a remote location (which is the most common and convenient way to login to a system) will have his or her password sniffed. The attentive system admin will analyze his remote access logs looking for suspicious source addresses even for successful logins. One must always assume that once an attacker has access to a user account, the attacker can break root. However, the reality is that in a well secured and maintained system, access to a user account does not necessarily give the attacker access to root. The distinction is important because without access to root the attacker cannot generally hide his tracks and may, at best, be able to do nothing more than mess with the user's files, or crash the machine. User account compromises are very common because users tend not to take the precautions that sysadmins take. security backdoors System administrators must keep in mind that there are potentially many ways to break root on a machine. The attacker may know the root password, the attacker may find a bug in a root-run server and be able to break root over a network connection to that server, or the attacker may know of a bug in a suid-root program that allows the attacker to break root once he has broken into a user's account. If an attacker has found a way to break root on a machine, the attacker may not have a need to install a backdoor. Many of the root holes found and closed to date involve a considerable amount of work by the attacker to cleanup after himself, so most attackers install backdoors. A backdoor provides the attacker with a way to easily regain root access to the system, but it also gives the smart system administrator a convenient way to detect the intrusion. Making it impossible for an attacker to install a backdoor may actually be detrimental to your security, because it will not close off the hole the attacker found to break in the first place. Security remedies should always be implemented with a multi-layered onion peel approach and can be categorized as follows: Securing root and staff accounts. Securing root – root-run servers and suid/sgid binaries. Securing user accounts. Securing the password file. Securing the kernel core, raw devices, and filesystems. Quick detection of inappropriate changes made to the system. Paranoia. The next section of this chapter will cover the above bullet items in greater depth. Securing FreeBSD security securing FreeBSD Command vs. Protocol Throughout this document, we will use bold text to refer to a command or application. This is used for instances such as ssh, since it is a protocol as well as command. The sections that follow will cover the methods of securing your FreeBSD system that were mentioned in the last section of this chapter. Securing the <username>root</username> Account and Staff Accounts su First off, do not bother securing staff accounts if you have not secured the root account. Most systems have a password assigned to the root account. The first thing you do is assume that the password is always compromised. This does not mean that you should remove the password. The password is almost always necessary for console access to the machine. What it does mean is that you should not make it possible to use the password outside of the console or possibly even with the &man.su.1; command. For example, make sure that your pty's are specified as being insecure in the /etc/ttys file so that direct root logins via telnet or rlogin are disallowed. If using other login services such as sshd, make sure that direct root logins are disabled there as well. You can do this by editing your /etc/ssh/sshd_config file, and making sure that PermitRootLogin is set to NO. Consider every access method – services such as FTP often fall through the cracks. Direct root logins should only be allowed via the system console. wheel Of course, as a sysadmin you have to be able to get to root, so we open up a few holes. But we make sure these holes require additional password verification to operate. One way to make root accessible is to add appropriate staff accounts to the wheel group (in /etc/group). The staff members placed in the wheel group are allowed to su to root. You should never give staff members native wheel access by putting them in the wheel group in their password entry. Staff accounts should be placed in a staff group, and then added to the wheel group via the /etc/group file. Only those staff members who actually need to have root access should be placed in the wheel group. It is also possible, when using an authentication method such as Kerberos, to use Kerberos' .k5login file in the root account to allow a &man.ksu.1; to root without having to place anyone at all in the wheel group. This may be the better solution since the wheel mechanism still allows an intruder to break root if the intruder has gotten hold of your password file and can break into a staff account. While having the wheel mechanism is better than having nothing at all, it is not necessarily the safest option. An indirect way to secure staff accounts, and ultimately root access is to use an alternative login access method and do what is known as starring out the encrypted password for the staff accounts. Using the &man.vipw.8; command, one can replace each instance of an encrypted password with a single * character. This command will update the /etc/master.passwd file and user/password database to disable password-authenticated logins. A staff account entry such as: foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh Should be changed to this: foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh This change will prevent normal logins from occurring, since the encrypted password will never match *. With this done, staff members must use another mechanism to authenticate themselves such as &man.kerberos.1; or &man.ssh.1; using a public/private key pair. When using something like Kerberos, one generally must secure the machines which run the Kerberos servers and your desktop workstation. When using a public/private key pair with ssh, one must generally secure the machine used to login from (typically one's workstation). An additional layer of protection can be added to the key pair by password protecting the key pair when creating it with &man.ssh-keygen.1;. Being able to star out the passwords for staff accounts also guarantees that staff members can only login through secure access methods that you have set up. This forces all staff members to use secure, encrypted connections for all of their sessions, which closes an important hole used by many intruders: sniffing the network from an unrelated, less secure machine. The more indirect security mechanisms also assume that you are logging in from a more restrictive server to a less restrictive server. For example, if your main box is running all sorts of servers, your workstation should not be running any. In order for your workstation to be reasonably secure you should run as few servers as possible, up to and including no servers at all, and you should run a password-protected screen blanker. Of course, given physical access to a workstation an attacker can break any sort of security you put on it. This is definitely a problem that you should consider, but you should also consider the fact that the vast majority of break-ins occur remotely, over a network, from people who do not have physical access to your workstation or servers. Kerberos Using something like Kerberos also gives you the ability to disable or change the password for a staff account in one place, and have it immediately effect all the machines on which the staff member may have an account. If a staff member's account gets compromised, the ability to instantly change his password on all machines should not be underrated. With discrete passwords, changing a password on N machines can be a mess. You can also impose re-passwording restrictions with Kerberos: not only can a Kerberos ticket be made to timeout after a while, but the Kerberos system can require that the user choose a new password after a certain period of time (say, once a month). Securing Root-run Servers and SUID/SGID Binaries ntalk comsat finger sandboxes sshd telnetd rshd rlogind The prudent sysadmin only runs the servers he needs to, no more, no less. Be aware that third party servers are often the most bug-prone. For example, running an old version of imapd or popper is like giving a universal root ticket out to the entire world. Never run a server that you have not checked out carefully. Many servers do not need to be run as root. For example, the ntalk, comsat, and finger daemons can be run in special user sandboxes. A sandbox is not perfect, unless you go through a large amount of trouble, but the onion approach to security still stands: If someone is able to break in through a server running in a sandbox, they still have to break out of the sandbox. The more layers the attacker must break through, the lower the likelihood of his success. Root holes have historically been found in virtually every server ever run as root, including basic system servers. If you are running a machine through which people only login via sshd and never login via telnetd or rshd or rlogind, then turn off those services! FreeBSD now defaults to running ntalkd, comsat, and finger in a sandbox. Another program which may be a candidate for running in a sandbox is &man.named.8;. /etc/defaults/rc.conf includes the arguments necessary to run named in a sandbox in a commented-out form. Depending on whether you are installing a new system or upgrading an existing system, the special user accounts used by these sandboxes may not be installed. The prudent sysadmin would research and implement sandboxes for servers whenever possible. sendmail There are a number of other servers that typically do not run in sandboxes: sendmail, popper, imapd, ftpd, and others. There are alternatives to some of these, but installing them may require more work than you are willing to perform (the convenience factor strikes again). You may have to run these servers as root and rely on other mechanisms to detect break-ins that might occur through them. The other big potential root holes in a system are the suid-root and sgid binaries installed on the system. Most of these binaries, such as rlogin, reside in /bin, /sbin, /usr/bin, or /usr/sbin. While nothing is 100% safe, the system-default suid and sgid binaries can be considered reasonably safe. Still, root holes are occasionally found in these binaries. A root hole was found in Xlib in 1998 that made xterm (which is typically suid) vulnerable. It is better to be safe than sorry and the prudent sysadmin will restrict suid binaries, that only staff should run, to a special group that only staff can access, and get rid of (chmod 000) any suid binaries that nobody uses. A server with no display generally does not need an xterm binary. Sgid binaries can be almost as dangerous. If an intruder can break an sgid-kmem binary, the intruder might be able to read /dev/kmem and thus read the encrypted password file, potentially compromising any passworded account. Alternatively an intruder who breaks group kmem can monitor keystrokes sent through pty's, including pty's used by users who login through secure methods. An intruder that breaks the tty group can write to almost any user's tty. If a user is running a terminal program or emulator with a keyboard-simulation feature, the intruder can potentially generate a data stream that causes the user's terminal to echo a command, which is then run as that user. Securing User Accounts User accounts are usually the most difficult to secure. While you can impose Draconian access restrictions on your staff and star out their passwords, you may not be able to do so with any general user accounts you might have. If you do have sufficient control, then you may win out and be able to secure the user accounts properly. If not, you simply have to be more vigilant in your monitoring of those accounts. Use of ssh and Kerberos for user accounts is more problematic, due to the extra administration and technical support required, but still a very good solution compared to a crypted password file. Securing the Password File The only sure fire way is to * out as many passwords as you can and use ssh or Kerberos for access to those accounts. Even though the encrypted password file (/etc/spwd.db) can only be read by root, it may be possible for an intruder to obtain read access to that file even if the attacker cannot obtain root-write access. Your security scripts should always check for and report changes to the password file (see the Checking file integrity section below). Securing the Kernel Core, Raw Devices, and Filesystems If an attacker breaks root he can do just about anything, but there are certain conveniences. For example, most modern kernels have a packet sniffing device driver built in. Under FreeBSD it is called the bpf device. An intruder will commonly attempt to run a packet sniffer on a compromised machine. You do not need to give the intruder the capability and most systems do not have the need for the bpf device compiled in. sysctl But even if you turn off the bpf device, you still have /dev/mem and /dev/kmem to worry about. For that matter, the intruder can still write to raw disk devices. Also, there is another kernel feature called the module loader, &man.kldload.8;. An enterprising intruder can use a KLD module to install his own bpf device, or other sniffing device, on a running kernel. To avoid these problems you have to run the kernel at a higher secure level, at least securelevel 1. The securelevel can be set with a sysctl on the kern.securelevel variable. Once you have set the securelevel to 1, write access to raw devices will be denied and special chflags flags, such as schg, will be enforced. You must also ensure that the schg flag is set on critical startup binaries, directories, and script files – everything that gets run up to the point where the securelevel is set. This might be overdoing it, and upgrading the system is much more difficult when you operate at a higher secure level. You may compromise and run the system at a higher secure level but not set the schg flag for every system file and directory under the sun. Another possibility is to simply mount / and /usr read-only. It should be noted that being too Draconian in what you attempt to protect may prevent the all-important detection of an intrusion. Checking File Integrity: Binaries, Configuration Files, Etc. When it comes right down to it, you can only protect your core system configuration and control files so much before the convenience factor rears its ugly head. For example, using chflags to set the schg bit on most of the files in / and /usr is probably counterproductive, because while it may protect the files, it also closes a detection window. The last layer of your security onion is perhaps the most important – detection. The rest of your security is pretty much useless (or, worse, presents you with a false sense of safety) if you cannot detect potential incursions. Half the job of the onion is to slow down the attacker, rather than stop him, in order to give the detection side of the equation a chance to catch him in the act. The best way to detect an incursion is to look for modified, missing, or unexpected files. The best way to look for modified files is from another (often centralized) limited-access system. Writing your security scripts on the extra-secure limited-access system makes them mostly invisible to potential attackers, and this is important. In order to take maximum advantage you generally have to give the limited-access box significant access to the other machines in the business, usually either by doing a read-only NFS export of the other machines to the limited-access box, or by setting up ssh key-pairs to allow the limited-access box to ssh to the other machines. Except for its network traffic, NFS is the least visible method – allowing you to monitor the filesystems on each client box virtually undetected. If your limited-access server is connected to the client boxes through a switch, the NFS method is often the better choice. If your limited-access server is connected to the client boxes through a hub, or through several layers of routing, the NFS method may be too insecure (network-wise) and using ssh may be the better choice even with the audit-trail tracks that ssh lays. Once you give a limited-access box, at least read access to the client systems it is supposed to monitor, you must write scripts to do the actual monitoring. Given an NFS mount, you can write scripts out of simple system utilities such as &man.find.1; and &man.md5.1;. It is best to physically md5 the client-box files at least once a day, and to test control files such as those found in /etc and /usr/local/etc even more often. When mismatches are found, relative to the base md5 information the limited-access machine knows is valid, it should scream at a sysadmin to go check it out. A good security script will also check for inappropriate suid binaries and for new or deleted files on system partitions such as / and /usr. When using ssh rather than NFS, writing the security script is much more difficult. You essentially have to scp the scripts to the client box in order to run them, making them visible, and for safety you also need to scp the binaries (such as find) that those scripts use. The ssh client on the client box may already be compromised. All in all, using ssh may be necessary when running over insecure links, but it is also a lot harder to deal with. A good security script will also check for changes to user and staff members access configuration files: .rhosts, .shosts, .ssh/authorized_keys and so forth… files that might fall outside the purview of the MD5 check. If you have a huge amount of user disk space, it may take too long to run through every file on those partitions. In this case, setting mount flags to disallow suid binaries and devices on those partitions is a good idea. The nodev and nosuid options (see &man.mount.8;) are what you want to look into. You should probably scan them anyway, at least once a week, since the object of this layer is to detect a break-in whether or not the break-in is effective. Process accounting (see &man.accton.8;) is a relatively low-overhead feature of the operating system which might help as a post-break-in evaluation mechanism. It is especially useful in tracking down how an intruder has actually broken into a system, assuming the file is still intact after the break-in occurs. Finally, security scripts should process the log files, and the logs themselves should be generated in as secure a manner as possible – remote syslog can be very useful. An intruder tries to cover his tracks, and log files are critical to the sysadmin trying to track down the time and method of the initial break-in. One way to keep a permanent record of the log files is to run the system console to a serial port and collect the information on a continuing basis through a secure machine monitoring the consoles. Paranoia A little paranoia never hurts. As a rule, a sysadmin can add any number of security features, as long as they do not effect convenience, and can add security features that do effect convenience with some added thought. Even more importantly, a security administrator should mix it up a bit – if you use recommendations such as those given by this document verbatim, you give away your methodologies to the prospective attacker who also has access to this document. Denial of Service Attacks Denial of Service (DoS) This section covers Denial of Service attacks. A DoS attack is typically a packet attack. While there is not much you can do about modern spoofed packet attacks that saturate your network, you can generally limit the damage by ensuring that the attacks cannot take down your servers. Limiting server forks. Limiting springboard attacks (ICMP response attacks, ping broadcast, etc.). Kernel Route Cache. A common DoS attack is against a forking server that attempts to cause the server to eat processes, file descriptors, and memory, until the machine dies. inetd (see &man.inetd.8;) has several options to limit this sort of attack. It should be noted that while it is possible to prevent a machine from going down, it is not generally possible to prevent a service from being disrupted by the attack. Read the inetd manual page carefully and pay specific attention to the , , and options. Note that spoofed-IP attacks will circumvent the option to inetd, so typically a combination of options must be used. Some standalone servers have self-fork-limitation parameters. Sendmail has its option, which tends to work much better than trying to use sendmail's load limiting options due to the load lag. You should specify a MaxDaemonChildren parameter, when you start sendmail, high enough to handle your expected load, but not so high that the computer cannot handle that number of sendmails without falling on its face. It is also prudent to run sendmail in queued mode () and to run the daemon (sendmail -bd) separate from the queue-runs (sendmail -q15m). If you still want real-time delivery you can run the queue at a much lower interval, such as , but be sure to specify a reasonable MaxDaemonChildren option for that sendmail to prevent cascade failures. Syslogd can be attacked directly and it is strongly recommended that you use the option whenever possible, and the option otherwise. You should also be fairly careful with connect-back services such as tcpwrapper's reverse-identd, which can be attacked directly. You generally do not want to use the reverse-ident feature of tcpwrappers for this reason. It is a very good idea to protect internal services from external access by firewalling them off at your border routers. The idea here is to prevent saturation attacks from outside your LAN, not so much to protect internal services from network-based root compromise. Always configure an exclusive firewall, i.e., firewall everything except ports A, B, C, D, and M-Z. This way you can firewall off all of your low ports except for certain specific services such as named (if you are primary for a zone), ntalkd, sendmail, and other Internet-accessible services. If you try to configure the firewall the other way – as an inclusive or permissive firewall, there is a good chance that you will forget to close a couple of services, or that you will add a new internal service and forget to update the firewall. You can still open up the high-numbered port range on the firewall, to allow permissive-like operation, without compromising your low ports. Also take note that FreeBSD allows you to control the range of port numbers used for dynamic binding, via the various net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange), which can also ease the complexity of your firewall's configuration. For example, you might use a normal first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then block off everything under 4000 in your firewall (except for certain specific Internet-accessible ports, of course). ICMP_BANDLIM Another common DoS attack is called a springboard attack – to attack a server in a manner that causes the server to generate responses which overloads the server, the local network, or some other machine. The most common attack of this nature is the ICMP ping broadcast attack. The attacker spoofs ping packets sent to your LAN's broadcast address with the source IP address set to the actual machine they wish to attack. If your border routers are not configured to stomp on ping's to broadcast addresses, your LAN winds up generating sufficient responses to the spoofed source address to saturate the victim, especially when the attacker uses the same trick on several dozen broadcast addresses over several dozen different networks at once. Broadcast attacks of over a hundred and twenty megabits have been measured. A second common springboard attack is against the ICMP error reporting system. By constructing packets that generate ICMP error responses, an attacker can saturate a server's incoming network and cause the server to saturate its outgoing network with ICMP responses. This type of attack can also crash the server by running it out of mbuf's, especially if the server cannot drain the ICMP responses it generates fast enough. The FreeBSD kernel has a new kernel compile option called which limits the effectiveness of these sorts of attacks. The last major class of springboard attacks is related to certain internal inetd services such as the udp echo service. An attacker simply spoofs a UDP packet with the source address being server A's echo port, and the destination address being server B's echo port, where server A and B are both on your LAN. The two servers then bounce this one packet back and forth between each other. The attacker can overload both servers and their LANs simply by injecting a few packets in this manner. Similar problems exist with the internal chargen port. A competent sysadmin will turn off all of these inetd-internal test services. Spoofed packet attacks may also be used to overload the kernel route cache. Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache sysctl parameters. A spoofed packet attack that uses a random source IP will cause the kernel to generate a temporary cached route in the route table, viewable with netstat -rna | fgrep W3. These routes typically timeout in 1600 seconds or so. If the kernel detects that the cached route table has gotten too big it will dynamically reduce the rtexpire but will never decrease it to less than rtminexpire. There are two problems: The kernel does not react quickly enough when a lightly loaded server is suddenly attacked. The rtminexpire is not low enough for the kernel to survive a sustained attack. If your servers are connected to the Internet via a T3 or better, it may be prudent to manually override both rtexpire and rtminexpire via &man.sysctl.8;. Never set either parameter to zero (unless you want to crash the machine). Setting both parameters to 2 seconds should be sufficient to protect the route table from attack. Access Issues with Kerberos and SSH ssh Kerberos There are a few issues with both Kerberos and ssh that need to be addressed if you intend to use them. Kerberos V is an excellent authentication protocol, but there are bugs in the kerberized telnet and rlogin applications that make them unsuitable for dealing with binary streams. Also, by default Kerberos does not encrypt a session unless you use the option. ssh encrypts everything by default. ssh works quite well in every respect except that it forwards encryption keys by default. What this means is that if you have a secure workstation holding keys that give you access to the rest of the system, and you ssh to an insecure machine, your keys are usable. The actual keys themselves are not exposed, but ssh installs a forwarding port for the duration of your login, and if an attacker has broken root on the insecure machine he can utilize that port to use your keys to gain access to any other machine that your keys unlock. We recommend that you use ssh in combination with Kerberos whenever possible for staff logins. ssh can be compiled with Kerberos support. This reduces your reliance on potentially exposable ssh keys while at the same time protecting passwords via Kerberos. ssh keys should only be used for automated tasks from secure machines (something that Kerberos is unsuited to do). We also recommend that you either turn off key-forwarding in the ssh configuration, or that you make use of the from=IP/DOMAIN option that ssh allows in its authorized_keys file to make the key only usable to entities logging in from specific machines. Bill Swingle Parts rewritten and updated by DES, MD5, and Crypt security crypt crypt DES MD5 Every user on a &unix; system has a password associated with their account. It seems obvious that these passwords need to be known only to the user and the actual operating system. In order to keep these passwords secret, they are encrypted with what is known as a one-way hash, that is, they can only be easily encrypted but not decrypted. In other words, what we told you a moment ago was obvious is not even true: the operating system itself does not really know the password. It only knows the encrypted form of the password. The only way to get the plain-text password is by a brute force search of the space of possible passwords. Unfortunately the only secure way to encrypt passwords when &unix; came into being was based on DES, the Data Encryption Standard. This was not such a problem for users resident in the US, but since the source code for DES could not be exported outside the US, FreeBSD had to find a way to both comply with US law and retain compatibility with all the other &unix; variants that still used DES. The solution was to divide up the encryption libraries so that US users could install the DES libraries and use DES but international users still had an encryption method that could be exported abroad. This is how FreeBSD came to use MD5 as its default encryption method. MD5 is believed to be more secure than DES, so installing DES is offered primarily for compatibility reasons. Recognizing Your Crypt Mechanism Before FreeBSD 4.4 libcrypt.a was a symbolic link pointing to the library which was used for encryption. FreeBSD 4.4 changed libcrypt.a to provide a configurable password authentication hash library. Currently the library supports DES, MD5 and Blowfish hash functions. By default FreeBSD uses MD5 to encrypt passwords. It is pretty easy to identify which encryption method FreeBSD is set up to use. Examining the encrypted passwords in the /etc/master.passwd file is one way. Passwords encrypted with the MD5 hash are longer than those encrypted with the DES hash and also begin with the characters $1$. Passwords starting with $2$ are encrypted with the Blowfish hash function. DES password strings do not have any particular identifying characteristics, but they are shorter than MD5 passwords, and are coded in a 64-character alphabet which does not include the $ character, so a relatively short string which does not begin with a dollar sign is very likely a DES password. The password format used for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of des, md5 or blf. See the &man.login.conf.5; manual page for more information about login capabilities. One-time Passwords one-time passwords security one-time passwords S/Key is a one-time password scheme based on a one-way hash function. FreeBSD uses the MD4 hash for compatibility but other systems have used MD5 and DES-MAC. S/Key has been part of the FreeBSD base system since version 1.1.5 and is also used on a growing number of other operating systems. S/Key is a registered trademark of Bell Communications Research, Inc. From version 5.0 of FreeBSD, S/Key has been replaced with the functionally equivalent OPIE (One-time Passwords In Everything). OPIE uses the MD5 hash by default. There are three different sorts of passwords which we will discuss below. The first is your usual &unix; style or Kerberos password; we will call this a &unix; password. The second sort is the one-time password which is generated by the S/Key key program or the OPIE &man.opiekey.1; program and accepted by the keyinit or &man.opiepasswd.1; programs and the login prompt; we will call this a one-time password. The final sort of password is the secret password which you give to the key/opiekey programs (and sometimes the keyinit/opiepasswd programs) which it uses to generate one-time passwords; we will call it a secret password or just unqualified password. The secret password does not have anything to do with your &unix; password; they can be the same but this is not recommended. S/Key and OPIE secret passwords are not limited to 8 characters like old &unix; passwordsUnder &os; the standard login password may be up to 128 characters in length., they can be as long as you like. Passwords of six or seven word long phrases are fairly common. For the most part, the S/Key or OPIE system operates completely independently of the &unix; password system. Besides the password, there are two other pieces of data that are important to S/Key and OPIE. One is what is known as the seed or key, consisting of two letters and five digits. The other is what is called the iteration count, a number between 1 and 100. S/Key creates the one-time password by concatenating the seed and the secret password, then applying the MD4/MD5 hash as many times as specified by the iteration count and turning the result into six short English words. These six English words are your one-time password. The authentication system (primarily PAM) keeps track of the last one-time password used, and the user is authenticated if the hash of the user-provided password is equal to the previous password. Because a one-way hash is used it is impossible to generate future one-time passwords if a successfully used password is captured; the iteration count is decremented after each successful login to keep the user and the login program in sync. When the iteration count gets down to 1, S/Key and OPIE must be reinitialized. There are three programs involved in each system which we will discuss below. The key and opiekey programs accept an iteration count, a seed, and a secret password, and generate a one-time password or a consecutive list of one-time passwords. The keyinit and opiepasswd programs are used to initialize S/Key and OPIE respectively, and to change passwords, iteration counts, or seeds; they take either a secret passphrase, or an iteration count, seed, and one-time password. The keyinfo and opieinfo programs examine the relevant credentials files (/etc/skeykeys or /etc/opiekeys) and print out the invoking user's current iteration count and seed. There are four different sorts of operations we will cover. The first is using keyinit or opiepasswd over a secure connection to set up one-time-passwords for the first time, or to change your password or seed. The second operation is using keyinit or opiepasswd over an insecure connection, in conjunction with key or opiekey over a secure connection, to do the same. The third is using key/opiekey to log in over an insecure connection. The fourth is using key or opiekey to generate a number of keys which can be written down or printed out to carry with you when going to some location without secure connections to anywhere. Secure Connection Initialization To initialize S/Key for the first time, change your password, or change your seed while logged in over a secure connection (e.g., on the console of a machine or via ssh), use the keyinit command without any parameters while logged in as yourself: &prompt.user; keyinit Adding unfurl: Reminder - Only use this method if you are directly connected. If you are using telnet or rlogin exit with no password and use keyinit -s. Enter secret password: Again secret password: ID unfurl s/key is 99 to17757 DEFY CLUB PRO NASH LACE SOFT For OPIE, opiepasswd is used instead: &prompt.user; opiepasswd -c [grimreaper] ~ $ opiepasswd -f -c Adding unfurl: Only use this method from the console; NEVER from remote. If you are using telnet, xterm, or a dial-in, type ^C now or exit with no password. Then run opiepasswd without the -c parameter. Using MD5 to compute responses. Enter new secret pass phrase: Again new secret pass phrase: ID unfurl OTP key is 499 to4268 MOS MALL GOAT ARM AVID COED At the Enter new secret pass phrase: or Enter secret password: prompts, you should enter a password or phrase. Remember, this is not the password that you will use to login with, this is used to generate your one-time login keys. The ID line gives the parameters of your particular instance: your login name, the iteration count, and seed. When logging in the system will remember these parameters and present them back to you so you do not have to remember them. The last line gives the particular one-time password which corresponds to those parameters and your secret password; if you were to re-login immediately, this one-time password is the one you would use. Insecure Connection Initialization To initialize or change your secret password over an insecure connection, you will need to already have a secure connection to some place where you can run key or opiekey; this might be in the form of a desk accessory on a &macintosh;, or a shell prompt on a machine you trust. You will also need to make up an iteration count (100 is probably a good value), and you may make up your own seed or use a randomly-generated one. Over on the insecure connection (to the machine you are initializing), use the keyinit -s command: &prompt.user; keyinit -s Updating unfurl: Old key: to17758 Reminder you need the 6 English words from the key command. Enter sequence count from 1 to 9999: 100 Enter new key [default to17759]: s/key 100 to 17759 s/key access password: s/key access password:CURE MIKE BANE HIM RACY GORE For OPIE, you need to use opiepasswd: &prompt.user; opiepasswd Updating unfurl: You need the response from an OTP generator. Old secret pass phrase: otp-md5 498 to4268 ext Response: GAME GAG WELT OUT DOWN CHAT New secret pass phrase: otp-md5 499 to4269 Response: LINE PAP MILK NELL BUOY TROY ID mark OTP key is 499 gr4269 LINE PAP MILK NELL BUOY TROY To accept the default seed (which the keyinit program confusingly calls a key), press Return. Then before entering an access password, move over to your secure connection or S/Key desk accessory, and give it the same parameters: &prompt.user; key 100 to17759 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> CURE MIKE BANE HIM RACY GORE Or for OPIE: &prompt.user; opiekey 498 to4268 Using the MD5 algorithm to compute response. Reminder: Don't use opiekey from telnet or dial-in sessions. Enter secret pass phrase: GAME GAG WELT OUT DOWN CHAT Now switch back over to the insecure connection, and copy the one-time password generated over to the relevant program. Generating a Single One-time Password Once you have initialized S/Key or OPIE, when you login you will be presented with a prompt like this: &prompt.user; telnet example.com Trying 10.0.0.1... Connected to example.com Escape character is '^]'. FreeBSD/i386 (example.com) (ttypa) login: <username> s/key 97 fw13894 Password: Or for OPIE: &prompt.user; telnet example.com Trying 10.0.0.1... Connected to example.com Escape character is '^]'. FreeBSD/i386 (example.com) (ttypa) login: <username> otp-md5 498 gr4269 ext Password: As a side note, the S/Key and OPIE prompts have a useful feature (not shown here): if you press Return at the password prompt, the prompter will turn echo on, so you can see what you are typing. This can be extremely useful if you are attempting to type in a password by hand, such as from a printout. MS-DOS Windows MacOS At this point you need to generate your one-time password to answer this login prompt. This must be done on a trusted system that you can run key or opiekey on. (There are versions of these for DOS, &windows; and &macos; as well.) They need both the iteration count and the seed as command line options. You can cut-and-paste these right from the login prompt on the machine that you are logging in to. On the trusted system: &prompt.user; key 97 fw13894 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: WELD LIP ACTS ENDS ME HAAG For OPIE: &prompt.user; opiekey 498 to4268 Using the MD5 algorithm to compute response. Reminder: Don't use opiekey from telnet or dial-in sessions. Enter secret pass phrase: GAME GAG WELT OUT DOWN CHAT Now that you have your one-time password you can continue logging in: login: <username> s/key 97 fw13894 Password: <return to enable echo> s/key 97 fw13894 Password [echo on]: WELD LIP ACTS ENDS ME HAAG Last login: Tue Mar 21 11:56:41 from 10.0.0.2 ... Generating Multiple One-time Passwords Sometimes you have to go places where you do not have access to a trusted machine or secure connection. In this case, it is possible to use the key and opiekey commands to generate a number of one-time passwords beforehand to be printed out and taken with you. For example: &prompt.user; key -n 5 30 zz99999 Reminder - Do not use this program while logged in via telnet or rlogin. Enter secret password: <secret password> 26: SODA RUDE LEA LIND BUDD SILT 27: JILT SPY DUTY GLOW COWL ROT 28: THEM OW COLA RUNT BONG SCOT 29: COT MASH BARR BRIM NAN FLAG 30: CAN KNEE CAST NAME FOLK BILK Or for OPIE: &prompt.user; opiekey -n 5 30 zz99999 Using the MD5 algorithm to compute response. Reminder: Don't use opiekey from telnet or dial-in sessions. Enter secret pass phrase: <secret password> 26: JOAN BORE FOSS DES NAY QUIT 27: LATE BIAS SLAY FOLK MUCH TRIG 28: SALT TIN ANTI LOON NEAL USE 29: RIO ODIN GO BYE FURY TIC 30: GREW JIVE SAN GIRD BOIL PHI The requests five keys in sequence, the specifies what the last iteration number should be. Note that these are printed out in reverse order of eventual use. If you are really paranoid, you might want to write the results down by hand; otherwise you can cut-and-paste into lpr. Note that each line shows both the iteration count and the one-time password; you may still find it handy to scratch off passwords as you use them. Restricting Use of &unix; Passwords S/Key can place restrictions on the use of &unix; passwords based on the host name, user name, terminal port, or IP address of a login session. These restrictions can be found in the configuration file /etc/skey.access. The &man.skey.access.5; manual page has more information on the complete format of the file and also details some security cautions to be aware of before depending on this file for security. If there is no /etc/skey.access file (this is the default on FreeBSD 4.X systems), then all users will be allowed to use &unix; passwords. If the file exists, however, then all users will be required to use S/Key unless explicitly permitted to do otherwise by configuration statements in the skey.access file. In all cases, &unix; passwords are permitted on the console. Here is a sample skey.access configuration file which illustrates the three most common sorts of configuration statements: permit internet 192.168.0.0 255.255.0.0 permit user fnord permit port ttyd0 The first line (permit internet) allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use &unix; passwords. This should not be considered a security mechanism, but rather, a means to remind authorized users that they are using an insecure network and need to use S/Key for authentication. The second line (permit user) allows the specified username, in this case fnord, to use &unix; passwords at any time. Generally speaking, this should only be used for people who are either unable to use the key program, like those with dumb terminals, or those who are uneducable. The third line (permit port) allows all users logging in on the specified terminal line to use &unix; passwords; this would be used for dial-ups. OPIE can restrict the use of &unix; passwords based on the IP address of a login session just like S/Key does. The relevant file is /etc/opieaccess, which is present by default on FreeBSD 5.0 and newer systems. Please check &man.opieaccess.5; for more information on this file and which security considerations you should be aware of when using it. Here is a sample opieaccess file: permit 192.168.0.0 255.255.0.0 This line allows users whose IP source address (which is vulnerable to spoofing) matches the specified value and mask, to use &unix; passwords at any time. If no rules in opieaccess are matched, the default is to deny non-OPIE logins. Mark Murray Contributed by Mark Dapoz Based on a contribution by Kerberos Kerberos Kerberos is a network add-on system/protocol that allows users to authenticate themselves through the services of a secure server. Services such as remote login, remote copy, secure inter-system file copying and other high-risk tasks are made considerably safer and more controllable. The following instructions can be used as a guide on how to set up Kerberos as distributed for FreeBSD. However, you should refer to the relevant manual pages for a complete description. Installing Kerberos MIT Kerberos installing Kerberos is an optional component of FreeBSD. The easiest way to install this software is by selecting the krb4 or krb5 distribution in sysinstall during the initial installation of FreeBSD. This will install the eBones (KerberosIV) or Heimdal (Kerberos5) implementation of Kerberos. These implementations are included because they are developed outside the USA/Canada and were thus available to system owners outside those countries during the era of restrictive export controls on cryptographic code from the USA. Alternatively, the MIT implementation of Kerberos is available from the ports collection as security/krb5. Creating the Initial Database This is done on the Kerberos server only. First make sure that you do not have any old Kerberos databases around. You should change to the directory /etc/kerberosIV and check that only the following files are present: &prompt.root; cd /etc/kerberosIV &prompt.root; ls README krb.conf krb.realms If any additional files (such as principal.* or master_key) exist, then use the kdb_destroy command to destroy the old Kerberos database, or if Kerberos is not running, simply delete the extra files. You should now edit the krb.conf and krb.realms files to define your Kerberos realm. In this case the realm will be EXAMPLE.COM and the server is grunt.example.com. We edit or create the krb.conf file: &prompt.root; cat krb.conf EXAMPLE.COM EXAMPLE.COM grunt.example.com admin server CS.BERKELEY.EDU okeeffe.berkeley.edu ATHENA.MIT.EDU kerberos.mit.edu ATHENA.MIT.EDU kerberos-1.mit.edu ATHENA.MIT.EDU kerberos-2.mit.edu ATHENA.MIT.EDU kerberos-3.mit.edu LCS.MIT.EDU kerberos.lcs.mit.edu TELECOM.MIT.EDU bitsy.mit.edu ARC.NASA.GOV trident.arc.nasa.gov In this case, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to not include them for simplicity. The first line names the realm in which this system works. The other lines contain realm/host entries. The first item on a line is a realm, and the second is a host in that realm that is acting as a key distribution center. The words admin server following a host's name means that host also provides an administrative database server. For further explanation of these terms, please consult the Kerberos manual pages. Now we have to add grunt.example.com to the EXAMPLE.COM realm and also add an entry to put all hosts in the .example.com domain in the EXAMPLE.COM realm. The krb.realms file would be updated as follows: &prompt.root; cat krb.realms grunt.example.com EXAMPLE.COM .example.com EXAMPLE.COM .berkeley.edu CS.BERKELEY.EDU .MIT.EDU ATHENA.MIT.EDU .mit.edu ATHENA.MIT.EDU Again, the other realms do not need to be there. They are here as an example of how a machine may be made aware of multiple realms. You may wish to remove them to simplify things. The first line puts the specific system into the named realm. The rest of the lines show how to default systems of a particular subdomain to a named realm. Now we are ready to create the database. This only needs to run on the Kerberos server (or Key Distribution Center). Issue the kdb_init command to do this: &prompt.root; kdb_init Realm name [default ATHENA.MIT.EDU ]: EXAMPLE.COM You will be prompted for the database Master Password. It is important that you NOT FORGET this password. Enter Kerberos master key: Now we have to save the key so that servers on the local machine can pick it up. Use the kstash command to do this: &prompt.root; kstash Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! This saves the encrypted master password in /etc/kerberosIV/master_key. Making It All Run Two principals need to be added to the database for each system that will be secured with Kerberos. Their names are kpasswd and rcmd. These two principals are made for each system, with the instance being the name of the individual system. These daemons, kpasswd and rcmd allow other systems to change Kerberos passwords and run commands like &man.rcp.1;, &man.rlogin.1; and &man.rsh.1;. Now let us add these entries: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: passwd Instance: grunt <Not found>, Create [y] ? y Principal: passwd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? y Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: rcmd Instance: grunt <Not found>, Create [y] ? Principal: rcmd, Instance: grunt, kdc_key_ver: 1 New Password: <---- enter RANDOM here Verifying password New Password: <---- enter RANDOM here Random password [y] ? Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Creating the Server File We now have to extract all the instances which define the services on each machine. For this we use the ext_srvtab command. This will create a file which must be copied or moved by secure means to each Kerberos client's /etc/kerberosIV directory. This file must be present on each server and client, and is crucial to the operation of Kerberos. &prompt.root; ext_srvtab grunt Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Generating 'grunt-new-srvtab'.... Now, this command only generates a temporary file which must be renamed to srvtab so that all the servers can pick it up. Use the &man.mv.1; command to move it into place on the original system: &prompt.root; mv grunt-new-srvtab srvtab If the file is for a client system, and the network is not deemed safe, then copy the client-new-srvtab to removable media and transport it by secure physical means. Be sure to rename it to srvtab in the client's /etc/kerberosIV directory, and make sure it is mode 600: &prompt.root; mv grumble-new-srvtab srvtab &prompt.root; chmod 600 srvtab Populating the Database We now have to add some user entries into the database. First let us create an entry for the user jane. Use the kdb_edit command to do this: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: <Not found>, Create [y] ? y Principal: jane, Instance: , kdc_key_ver: 1 New Password: <---- enter a secure password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Testing It All Out First we have to start the Kerberos daemons. Note that if you have correctly edited your /etc/rc.conf then this will happen automatically when you reboot. This is only necessary on the Kerberos server. Kerberos clients will automatically get what they need from the /etc/kerberosIV directory. &prompt.root; kerberos & Kerberos server starting Sleep forever on error Log file is /var/log/kerberos.log Current Kerberos master key version is 1. Master key entered. BEWARE! Current Kerberos master key version is 1 Local realm: EXAMPLE.COM &prompt.root; kadmind -n & KADM Server KADM0.0A initializing Please do not use 'kill -9' to kill this job, use a regular kill instead Current Kerberos master key version is 1. Master key entered. BEWARE! Now we can try using the kinit command to get a ticket for the ID jane that we created above: &prompt.user; kinit jane MIT Project Athena (grunt.example.com) Kerberos Initialization for "jane" Password: Try listing the tokens using klist to see if we really have them: &prompt.user; klist Ticket file: /tmp/tkt245 Principal: jane@EXAMPLE.COM Issued Expires Principal Apr 30 11:23:22 Apr 30 19:23:22 krbtgt.EXAMPLE.COM@EXAMPLE.COM Now try changing the password using &man.passwd.1; to check if the kpasswd daemon can get authorization to the Kerberos database: &prompt.user; passwd realm EXAMPLE.COM Old password for jane: New Password for jane: Verifying password New Password for jane: Password changed. Adding <command>su</command> Privileges Kerberos allows us to give each user who needs root privileges their own separate &man.su.1; password. We could now add an ID which is authorized to &man.su.1; to root. This is controlled by having an instance of root associated with a principal. Using kdb_edit we can create the entry jane.root in the Kerberos database: &prompt.root; kdb_edit Opening database... Enter Kerberos master key: Current Kerberos master key version is 1. Master key entered. BEWARE! Previous or default values are in [brackets] , enter return to leave the same, or new value. Principal name: jane Instance: root <Not found>, Create [y] ? y Principal: jane, Instance: root, kdc_key_ver: 1 New Password: <---- enter a SECURE password here Verifying password New Password: <---- re-enter the password here Principal's new key version = 1 Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ? Max ticket lifetime (*5 minutes) [ 255 ] ? 12 <--- Keep this short! Attributes [ 0 ] ? Edit O.K. Principal name: <---- null entry here will cause an exit Now try getting tokens for it to make sure it works: &prompt.root; kinit jane.root MIT Project Athena (grunt.example.com) Kerberos Initialization for "jane.root" Password: Now we need to add the user to root's .klogin file: &prompt.root; cat /root/.klogin jane.root@EXAMPLE.COM Now try doing the &man.su.1;: &prompt.user; su Password: and take a look at what tokens we have: &prompt.root; klist Ticket file: /tmp/tkt_root_245 Principal: jane.root@EXAMPLE.COM Issued Expires Principal May 2 20:43:12 May 3 04:43:12 krbtgt.EXAMPLE.COM@EXAMPLE.COM Using Other Commands In an earlier example, we created a principal called jane with an instance root. This was based on a user with the same name as the principal, and this is a Kerberos default; that a <principal>.<instance> of the form <username>.root will allow that <username> to &man.su.1; to root if the necessary entries are in the .klogin file in root's home directory: &prompt.root; cat /root/.klogin jane.root@EXAMPLE.COM Likewise, if a user has in their own home directory lines of the form: &prompt.user; cat ~/.klogin jane@EXAMPLE.COM jack@EXAMPLE.COM This allows anyone in the EXAMPLE.COM realm who has authenticated themselves as jane or jack (via kinit, see above) to access to jane's account or files on this system (grunt) via &man.rlogin.1;, &man.rsh.1; or &man.rcp.1;. For example, jane now logs into another system using Kerberos: &prompt.user; kinit MIT Project Athena (grunt.example.com) Password: &prompt.user; rlogin grunt Last login: Mon May 1 21:14:47 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Or jack logs into jane's account on the same machine (jane having set up the .klogin file as above, and the person in charge of Kerberos having set up principal jack with a null instance): &prompt.user; kinit &prompt.user; rlogin grunt -l jane MIT Project Athena (grunt.example.com) Password: Last login: Mon May 1 21:16:55 from grumble Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995 Gary Palmer Contributed by Alex Nash Firewalls firewall security firewalls Firewalls are an area of increasing interest for people who are connected to the Internet, and are even finding applications on private networks to provide enhanced security. This section will hopefully explain what firewalls are, how to use them, and how to use the facilities provided in the FreeBSD kernel to implement them. People often think that having a firewall between your internal network and the Big Bad Internet will solve all your security problems. It may help, but a poorly set up firewall system is more of a security risk than not having one at all. A firewall can add another layer of security to your systems, but it cannot stop a really determined cracker from penetrating your internal network. If you let internal security lapse because you believe your firewall to be impenetrable, you have just made the crackers job that much easier. What Is a Firewall? There are currently two distinct types of firewalls in common use on the Internet today. The first type is more properly called a packet filtering router. This type of firewall utilizes a multi-homed machine and a set of rules to determine whether to forward or block individual packets. A multi-homed machine is simply a device with multiple network interfaces. The second type, known as a proxy server, relies on daemons to provide authentication and to forward packets, possibly on a multi-homed machine which has kernel packet forwarding disabled. Sometimes sites combine the two types of firewalls, so that only a certain machine (known as a bastion host) is allowed to send packets through a packet filtering router onto an internal network. Proxy services are run on the bastion host, which are generally more secure than normal authentication mechanisms. FreeBSD comes with a kernel packet filter (known as IPFW), which is what the rest of this section will concentrate on. Proxy servers can be built on FreeBSD from third party software, but there is such a variety of proxy servers available that it would be impossible to cover them in this section. Packet Filtering Routers A router is a machine which forwards packets between two or more networks. A packet filtering router is programmed to compare each packet to a list of rules before deciding if it should be forwarded or not. Most modern IP routing software includes packet filtering functionality that defaults to forwarding all packets. To enable the filters, you need to define a set of rules. To decide whether a packet should be passed on, the firewall looks through its set of rules for a rule which matches the contents of the packet's headers. Once a match is found, the rule action is obeyed. The rule action could be to drop the packet, to forward the packet, or even to send an ICMP message back to the originator. Only the first match counts, as the rules are searched in order. Hence, the list of rules can be referred to as a rule chain. The packet-matching criteria varies depending on the software used, but typically you can specify rules which depend on the source IP address of the packet, the destination IP address, the source port number, the destination port number (for protocols which support ports), or even the packet type (UDP, TCP, ICMP, etc). Proxy Servers Proxy servers are machines which have had the normal system daemons (telnetd, ftpd, etc) replaced with special servers. These servers are called proxy servers, as they normally only allow onward connections to be made. This enables you to run (for example) a proxy telnet server on your firewall host, and people can telnet in to your firewall from the outside, go through some authentication mechanism, and then gain access to the internal network (alternatively, proxy servers can be used for signals coming from the internal network and heading out). Proxy servers are normally more secure than normal servers, and often have a wider variety of authentication mechanisms available, including one-shot password systems so that even if someone manages to discover what password you used, they will not be able to use it to gain access to your systems as the password expires immediately after the first use. As they do not actually give users access to the host machine, it becomes a lot more difficult for someone to install backdoors around your security system. Proxy servers often have ways of restricting access further, so that only certain hosts can gain access to the servers. Most will also allow the administrator to specify which users can talk to which destination machines. Again, what facilities are available depends largely on what proxy software you choose. What Does IPFW Allow Me to Do? ipfw IPFW, the software supplied with FreeBSD, is a packet filtering and accounting system which resides in the kernel, and has a user-land control utility, &man.ipfw.8;. Together, they allow you to define and query the rules used by the kernel in its routing decisions. There are two related parts to IPFW. The firewall section performs packet filtering. There is also an IP accounting section which tracks usage of the router, based on rules similar to those used in the firewall section. This allows the administrator to monitor how much traffic the router is getting from a certain machine, or how much WWW traffic it is forwarding, for example. As a result of the way that IPFW is designed, you can use IPFW on non-router machines to perform packet filtering on incoming and outgoing connections. This is a special case of the more general use of IPFW, and the same commands and techniques should be used in this situation. Enabling IPFW on FreeBSD ipfw enabling As the main part of the IPFW system lives in the kernel, you will need to add one or more options to your kernel configuration file, depending on what facilities you want, and recompile your kernel. See "Reconfiguring your Kernel" () for more details on how to recompile your kernel. IPFW defaults to a policy of deny ip from any to any. If you do not add other rules during startup to allow access, you will lock yourself out of the server upon rebooting into a firewall-enabled kernel. We suggest that you set firewall_type=open in your /etc/rc.conf file when first enabling this feature, then refining the firewall rules in /etc/rc.firewall after you have tested that the new kernel feature works properly. To be on the safe side, you may wish to consider performing the initial firewall configuration from the local console rather than via ssh. Another option is to build a kernel using both the IPFIREWALL and IPFIREWALL_DEFAULT_TO_ACCEPT options. This will change the default rule of IPFW to allow ip from any to any and avoid the possibility of a lockout. There are currently four kernel configuration options relevant to IPFW: options IPFIREWALL Compiles into the kernel the code for packet filtering. options IPFIREWALL_VERBOSE Enables code to allow logging of packets through &man.syslogd.8;. Without this option, even if you specify that packets should be logged in the filter rules, nothing will happen. options IPFIREWALL_VERBOSE_LIMIT=10 Limits the number of packets logged through &man.syslogd.8; on a per entry basis. You may wish to use this option in hostile environments in which you want to log firewall activity, but do not want to be open to a denial of service attack via syslog flooding. When a chain entry reaches the packet limit specified, logging is turned off for that particular entry. To resume logging, you will need to reset the associated counter using the &man.ipfw.8; utility: &prompt.root; ipfw zero 4500 Where 4500 is the chain entry you wish to continue logging. options IPFIREWALL_DEFAULT_TO_ACCEPT This changes the default rule action from deny to allow. This avoids the possibility of locking yourself out if you happen to boot a kernel with IPFIREWALL support but have not configured your firewall yet. It is also very useful if you often use &man.ipfw.8; as a filter for specific problems as they arise. Use with care though, as this opens up the firewall and changes the way it works. Previous versions of FreeBSD contained an IPFIREWALL_ACCT option. This is now obsolete as the firewall code automatically includes accounting facilities. Configuring IPFW ipfw configuring The configuration of the IPFW software is done through the &man.ipfw.8; utility. The syntax for this command looks quite complicated, but it is relatively simple once you understand its structure. There are currently four different command categories used by the utility: addition/deletion, listing, flushing, and clearing. Addition/deletion is used to build the rules that control how packets are accepted, rejected, and logged. Listing is used to examine the contents of your rule set (otherwise known as the chain) and packet counters (accounting). Flushing is used to remove all entries from the chain. Clearing is used to zero out one or more accounting entries. Altering the IPFW Rules The syntax for this form of the command is: ipfw -N command index action log protocol addresses options There is one valid flag when using this form of the command: -N Resolve addresses and service names in output. The command given can be shortened to the shortest unique form. The valid commands are: add Add an entry to the firewall/accounting rule list delete Delete an entry from the firewall/accounting rule list Previous versions of IPFW used separate firewall and accounting entries. The present version provides packet accounting with each firewall entry. If an index value is supplied, it is used to place the entry at a specific point in the chain. Otherwise, the entry is placed at the end of the chain at an index 100 greater than the last chain entry (this does not include the default policy, rule 65535, deny). The log option causes matching rules to be output to the system console if the kernel was compiled with IPFIREWALL_VERBOSE. Valid actions are: reject Drop the packet, and send an ICMP host or port unreachable (as appropriate) packet to the source. allow Pass the packet on as normal. (aliases: pass, permit, and accept) deny Drop the packet. The source is not notified via an ICMP message (thus it appears that the packet never arrived at the destination). count Update packet counters but do not allow/deny the packet based on this rule. The search continues with the next chain entry. Each action will be recognized by the shortest unambiguous prefix. The protocols which can be specified are: all Matches any IP packet icmp Matches ICMP packets tcp Matches TCP packets udp Matches UDP packets The address specification is: from address/maskport to address/maskport via interface You can only specify port in conjunction with protocols which support ports (UDP and TCP). The is optional and may specify the IP address or domain name of a local IP interface, or an interface name (e.g. ed0) to match only packets coming through this interface. Interface unit numbers can be specified with an optional wildcard. For example, ppp* would match all kernel PPP interfaces. The syntax used to specify an address/mask is: address or address/mask-bits or address:mask-pattern A valid hostname may be specified in place of the IP address. is a decimal number representing how many bits in the address mask should be set. e.g. specifying 192.216.222.1/24 will create a mask which will allow any address in a class C subnet (in this case, 192.216.222) to be matched. is an IP address which will be logically AND'ed with the address given. The keyword any may be used to specify any IP address. The port numbers to be blocked are specified as: port,port,port… to specify either a single port or a list of ports, or port-port to specify a range of ports. You may also combine a single range with a list, but the range must always be specified first. The options available are: frag Matches if the packet is not the first fragment of the datagram. in Matches if the packet is on the way in. out Matches if the packet is on the way out. ipoptions spec Matches if the IP header contains the comma separated list of options specified in spec. The supported IP options are: ssrr (strict source route), lsrr (loose source route), rr (record packet route), and ts (time stamp). The absence of a particular option may be specified with a leading !. established Matches if the packet is part of an already established TCP connection (i.e. it has the RST or ACK bits set). You can optimize the performance of the firewall by placing established rules early in the chain. setup Matches if the packet is an attempt to establish a TCP connection (the SYN bit is set but the ACK bit is not). tcpflags flags Matches if the TCP header contains the comma separated list of flags. The supported flags are fin, syn, rst, psh, ack, and urg. The absence of a particular flag may be indicated by a leading !. icmptypes types Matches if the ICMP type is present in the list types. The list may be specified as any combination of ranges and/or individual types separated by commas. Commonly used ICMP types are: 0 echo reply (ping reply), 3 destination unreachable, 5 redirect, 8 echo request (ping request), and 11 time exceeded (used to indicate TTL expiration as with &man.traceroute.8;). Listing the IPFW Rules The syntax for this form of the command is: ipfw -a -c -d -e -t -N -S list There are seven valid flags when using this form of the command: -a While listing, show counter values. This option is the only way to see accounting counters. -c List rules in compact form. -d Show dynamic rules in addition to static rules. -e If was specified, also show expired dynamic rules. -t Display the last match times for each chain entry. The time listing is incompatible with the input syntax used by the &man.ipfw.8; utility. -N Attempt to resolve given addresses and service names. -S Show the set each rule belongs to. If this flag is not specified, disabled rules will not be listed. Flushing the IPFW Rules The syntax for flushing the chain is: ipfw flush This causes all entries in the firewall chain to be removed except the fixed default policy enforced by the kernel (index 65535). Use caution when flushing rules; the default deny policy will leave your system cut off from the network until allow entries are added to the chain. Clearing the IPFW Packet Counters The syntax for clearing one or more packet counters is: ipfw zero index When used without an index argument, all packet counters are cleared. If an index is supplied, the clearing operation only affects a specific chain entry. Example Commands for <application>ipfw</application> This command will deny all packets from the host evil.crackers.org to the telnet port of the host nice.people.org: &prompt.root; ipfw add deny tcp from evil.crackers.org to nice.people.org 23 The next example denies and logs any TCP traffic from the entire crackers.org network (a class C) to the nice.people.org machine (any port). &prompt.root; ipfw add deny log tcp from evil.crackers.org/24 to nice.people.org If you do not want people sending X sessions to your internal network (a subnet of a class C), the following command will do the necessary filtering: &prompt.root; ipfw add deny tcp from any to my.org/28 6000 setup To see the accounting records: &prompt.root; ipfw -a list or in the short form &prompt.root; ipfw -a l You can also see the last time a chain entry was matched with: &prompt.root; ipfw -at l Building a Packet Filtering Firewall The following suggestions are just that: suggestions. The requirements of each firewall are different and we cannot tell you how to build a firewall to meet your particular requirements. When initially setting up your firewall, unless you have a test bench setup where you can configure your firewall host in a controlled environment, it is strongly recommend you use the logging version of the commands and enable logging in the kernel. This will allow you to quickly identify problem areas and cure them without too much disruption. Even after the initial setup phase is complete, I recommend using the logging for `deny' as it allows tracing of possible attacks and also modification of the firewall rules if your requirements alter. If you use the logging versions of the accept command, be aware that it can generate large amounts of log data. One log entry will be generated for every packet that passes through the firewall, so large FTP/http transfers, etc, will really slow the system down. It also increases the latencies on those packets as it requires more work to be done by the kernel before the packet can be passed on. syslogd will also start using up a lot more processor time as it logs all the extra data to disk, and it could quite easily fill the partition /var/log is located on. You should enable your firewall from /etc/rc.conf.local or /etc/rc.conf. The associated manual page explains which knobs to fiddle and lists some preset firewall configurations. If you do not use a preset configuration, ipfw list will output the current ruleset into a file that you can pass to rc.conf. If you do not use /etc/rc.conf.local or /etc/rc.conf to enable your firewall, it is important to make sure your firewall is enabled before any IP interfaces are configured. The next problem is what your firewall should actually do! This is largely dependent on what access to your network you want to allow from the outside, and how much access to the outside world you want to allow from the inside. Some general rules are: Block all incoming access to ports below 1024 for TCP. This is where most of the security sensitive services are, like finger, SMTP (mail) and telnet. Block all incoming UDP traffic. There are very few useful services that travel over UDP, and what useful traffic there is, is normally a security threat (e.g. Suns RPC and NFS protocols). This has its disadvantages also, since UDP is a connectionless protocol, denying incoming UDP traffic also blocks the replies to outgoing UDP traffic. This can cause a problem for people (on the inside) using external archie (prospero) servers. If you want to allow access to archie, you will have to allow packets coming from ports 191 and 1525 to any internal UDP port through the firewall. ntp is another service you may consider allowing through, which comes from port 123. Block traffic to port 6000 from the outside. Port 6000 is the port used for access to X11 servers, and can be a security threat (especially if people are in the habit of doing xhost + on their workstations). X11 can actually use a range of ports starting at 6000, the upper limit being how many X displays you can run on the machine. The upper limit as defined by RFC 1700 (Assigned Numbers) is 6063. Check what ports any internal servers use (e.g. SQL servers, etc). It is probably a good idea to block those as well, as they normally fall outside the 1-1024 range specified above. Another checklist for firewall configuration is available from CERT at As stated above, these are only guidelines. You will have to decide what filter rules you want to use on your firewall yourself. We cannot accept ANY responsibility if someone breaks into your network, even if you follow the advice given above. IPFW Overhead and Optimization Many people want to know how much overhead IPFW adds to a system. The answer to this depends mostly on your rule set and processor speed. For most applications dealing with Ethernet and small rule sets, the answer is negligible. For those of you that need actual measurements to satisfy your curiosity, read on. The following measurements were made using 2.2.5-STABLE on a 486-66. (While IPFW has changed slightly in later releases of FreeBSD, it still performs with similar speed.) IPFW was modified to measure the time spent within the ip_fw_chk routine, displaying the results to the console every 1000 packets. Two rule sets, each with 1000 rules, were tested. The first set was designed to demonstrate a worst case scenario by repeating the rule: &prompt.root; ipfw add deny tcp from any to any 55555 This demonstrates a worst case scenario by causing most of IPFW's packet check routine to be executed before finally deciding that the packet does not match the rule (by virtue of the port number). Following the 999th iteration of this rule was an allow ip from any to any. The second set of rules were designed to abort the rule check quickly: &prompt.root; ipfw add deny ip from 1.2.3.4 to 1.2.3.4 The non-matching source IP address for the above rule causes these rules to be skipped very quickly. As before, the 1000th rule was an allow ip from any to any. The per-packet processing overhead in the former case was approximately 2.703 ms/packet, or roughly 2.7 microseconds per rule. Thus the theoretical packet processing limit with these rules is around 370 packets per second. Assuming 10 Mbps Ethernet and a ~1500 byte packet size, we would only be able to achieve 55.5% bandwidth utilization. For the latter case each packet was processed in approximately 1.172 ms, or roughly 1.2 microseconds per rule. The theoretical packet processing limit here would be about 853 packets per second, which could consume 10 Mbps Ethernet bandwidth. The excessive number of rules tested and the nature of those rules do not provide a real-world scenario -- they were used only to generate the timing information presented here. Here are a few things to keep in mind when building an efficient rule set: Place an established rule early on to handle the majority of TCP traffic. Do not put any allow tcp statements before this rule. Place heavily triggered rules earlier in the rule set than those rarely used (without changing the permissiveness of the firewall, of course). You can see which rules are used most often by examining the packet counting statistics with ipfw -a l. OpenSSL security OpenSSL OpenSSL As of FreeBSD 4.0, the OpenSSL toolkit is a part of the base system. OpenSSL provides a general-purpose cryptography library, as well as the Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and Transport Layer Security v1 (TLSv1) network security protocols. However, one of the algorithms (specifically IDEA) included in OpenSSL is protected by patents in the USA and elsewhere, and is not available for unrestricted use. IDEA is included in the OpenSSL sources in FreeBSD, but it is not built by default. If you wish to use it, and you comply with the license terms, enable the MAKE_IDEA switch in /etc/make.conf and rebuild your sources using make world. Today, the RSA algorithm is free for use in USA and other countries. In the past it was protected by a patent. OpenSSL install Source Code Installations OpenSSL is part of the src-crypto and src-secure CVSup collections. See the Obtaining FreeBSD section for more information about obtaining and updating FreeBSD source code. Nik Clayton
nik@FreeBSD.org
 Written by VPN over IPsec Creating a VPN between two networks, separated by the Internet, using FreeBSD gateways. Hiten M. Pandya
hmp@FreeBSD.org
 Written by Understanding IPsec This section will guide you through the process of setting up IPsec, and to use it in an environment which consists of FreeBSD and µsoft.windows; 2000/XP machines, to make them communicate securely. In order to set up IPsec, it is necessary that you are familiar with the concepts of building a custom kernel (see ). IPsec is a protocol which sits on top of the Internet Protocol (IP) layer. It allows two or more hosts to communicate in a secure manner (hence the name). The FreeBSD IPsec network stack is based on the KAME implementation, which has support for both protocol families, IPv4 and IPv6. FreeBSD 5.X contains a hardware accelerated IPsec stack, known as Fast IPsec, that was obtained from OpenBSD. It employs cryptographic hardware (whenever possible) via the &man.crypto.4; subsystem to optimize the performance of IPsec. This subsystem is new, and does not support all the features that are available in the KAME version of IPsec. However, in order to enable hardware-accelerated IPsec, the following kernel option has to be added to your kernel configuration file: options FAST_IPSEC # new IPsec (cannot define w/ IPSEC) Note, that it is not currently possible to use the Fast IPsec subsystem in lue with the KAME implementation of IPsec. Consult the &man.fast.ipsec.4; manual page for more information. IPsec consists of two sub-protocols: Encapsulated Security Payload (ESP), protects the IP packet data from third party interference, by encrypting the contents using symmetric cryptography algorithms (like Blowfish, 3DES). Authentication Header (AH), protects the IP packet header from third party interference and spoofing, by computing a cryptographic checksum and hashing the IP packet header fields with a secure hashing function. This is then followed by an additional header that contains the hash, to allow the information in the packet to be authenticated. ESP and AH can either be used together or seperately, depending on the environment. IPsec can either be used to directly encrypt the traffic between two hosts (known as Transport Mode); or to build virtual tunnels between two subnets, which could be used for secure communication between two corporate networks (known as Tunnel Mode). The latter is more commonly known as a Virtual Private Network (VPN). The &man.ipsec.4; manual page should be consulted for detailed information on the IPsec subsystem in FreeBSD. To add IPsec support to your kernel, add the following options to your kernel configuration file: options IPSEC #IP security options IPSEC_ESP #IP security (crypto; define w/ IPSEC) If IPsec debugging support is desired, the following kernel option should also be added: options IPSEC_DEBUG #debug for IP security The Problem There's no standard for what constitutes a VPN. VPNs can be implemented using a number of different technologies, each of which have their own strengths and weaknesses. This article presents a number of scenarios, and strategies for implementing a VPN for each scenario. Scenario #1: Two networks, connected to the Internet, to behave as one This is the scenario that caused me to first investigating VPNs. The premise is as follows: You have at least two sites Both sites are using IP internally Both sites are connected to the Internet, through a gateway that is running FreeBSD. The gateway on each network has at least one public IP address. The internal addresses of the two networks can be public or private IP addresses, it doesn't matter. You can be running NAT on the gateway machine if necessary. The internal IP addresses of the two networks do not collide. While I expect it is theoretically possible to use a combination of VPN technology and NAT to get this to work, I expect it to be a configuration nightmare. If you find that you are trying to connect two networks, both of which, internally, use the same private IP address range (e.g., both of them use 192.168.1.x), then one of the networks will have to be renumbered. The network topology might look something like this: Network #1 [ Internal Hosts ] Private Net, 192.168.1.2-254 [ Win9x/NT/2K ] [ UNIX ] | | .---[fxp1]---. Private IP, 192.168.1.1 | FreeBSD | `---[fxp0]---' Public IP, A.B.C.D | | -=-=- Internet -=-=- | | .---[fxp0]---. Public IP, W.X.Y.Z | FreeBSD | `---[fxp1]---' Private IP, 192.168.2.1 | | Network #2 [ Internal Hosts ] [ Win9x/NT/2K ] Private Net, 192.168.2.2-254 [ UNIX ] Notice the two public IP addresses. I'll use the letters to refer to them in the rest of this article. Anywhere you see those letters in this article, replace them with your own public IP addresses. Note also that that internally, the two gateway machines have .1 IP addresses, and that the two networks have different private IP address (192.168.1.x and 192.168.2.x respectively). All the machines on the private networks have been configured to use the .1 machine as their default gateway. The intention is that, from a network point of view, each network should view the machines on the other network as though they were directly attached the same router -- albeit a slightly slow router with an occasional tendency to drop packets. This means that (for example), machine 192.168.1.20 should be able to run ping 192.168.2.34 and have it work, transparently. &windows; machines should be able to see the machines on the other network, browse file shares, and so on, in exactly the same way that they can browse machines on the local network. And the whole thing has to be secure. This means that traffic between the two networks has to be encrypted. Creating a VPN between these two networks is a multi-step process. The stages are as follows: Create a virtual network link between the two networks, across the Internet. Test it, using tools like &man.ping.8;, to make sure it works. Apply security policies to ensure that traffic between the two networks is transparently encrypted and decrypted as necessary. Test this, using tools like &man.tcpdump.1;, to ensure that traffic is encrypted. Configure additional software on the FreeBSD gateways, to allow &windows; machines to see one another across the VPN. Step 1: Creating and testing a <quote>virtual</quote> network link Suppose that you were logged in to the gateway machine on network #1 (with public IP address A.B.C.D, private IP address 192.168.1.1), and you ran ping 192.168.2.1, which is the private address of the machine with IP address W.X.Y.Z. What needs to happen in order for this to work? The gateway machine needs to know how to reach 192.168.2.1. In other words, it needs to have a route to 192.168.2.1. Private IP addresses, such as those in the 192.168.x range are not supposed to appear on the Internet at large. Instead, each packet you send to 192.168.2.1 will need to be wrapped up inside another packet. This packet will need to appear to be from A.B.C.D, and it will have to be sent to W.X.Y.Z. This process is called encapsulation. Once this packet arrives at W.X.Y.Z it will need to unencapsulated, and delivered to 192.168.2.1. + You can think of this as requiring a tunnel between the two networks. The two tunnel mouths are the IP addresses A.B.C.D and W.X.Y.Z, and the tunnel must be told the addresses of the private IP addresses that will be allowed to pass through it. The tunnel is used to transfer traffic with private IP addresses across the public Internet. This tunnel is created by using the generic interface, or gif devices on FreeBSD. As you can imagine, the gif interface on each gateway host must be configured with four IP addresses; two for the public IP addresses, and two for the private IP addresses. Support for the gif device must be compiled in to the FreeBSD kernel on both machines. You can do this by adding the line: pseudo-device gif to the kernel configuration files on both machines, and then compile, install, and reboot as normal. Configuring the tunnel is a two step process. First the tunnel must be told what the outside (or public) IP addresses are, using &man.gifconfig.8;. Then the private IP addresses must be configured using &man.ifconfig.8;. On the gateway machine on network #1 you would run the following two commands to configure the tunnel. gifconfig gif0 A.B.C.D W.X.Y.Z ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff On the other gateway machine you run the same commands, but with the order of the IP addresses reversed. gifconfig gif0 W.X.Y.Z A.B.C.D ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff You can then run: gifconfig gif0 to see the configuration. For example, on the network #1 gateway, you would see this: &prompt.root; gifconfig gif0 gif0: flags=8011<UP,POINTTOPOINT,MULTICAST> mtu 1280 inet 192.168.1.1 --> 192.168.2.1 netmask 0xffffffff physical address inet A.B.C.D --> W.X.Y.Z As you can see, a tunnel has been created between the physical addresses A.B.C.D and W.X.Y.Z, and the traffic allowed through the tunnel is that between 192.168.1.1 and 192.168.2.1. This will also have added an entry to the routing table on both machines, which you can examine with the command netstat -rn. This output is from the gateway host on network #1. &prompt.root; netstat -rn Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire ... 192.168.2.1 192.168.1.1 UH 0 0 gif0 ... As the Flags value indicates, this is a host route, which means that each gateway knows how to reach the other gateway, but they do not know how to reach the rest of their respective networks. That problem will be fixed shortly. It is likely that you are running a firewall on both machines. This will need to be circumvented for your VPN traffic. You might want to allow all traffic between both networks, or you might want to include firewall rules that protect both ends of the VPN from one another. It greatly simplifies testing if you configure the firewall to allow all traffic through the VPN. You can always tighten things up later. If you are using &man.ipfw.8; on the gateway machines then a command like ipfw add 1 allow ip from any to any via gif0 will allow all traffic between the two end points of the VPN, without affecting your other firewall rules. Obviously you will need to run this command on both gateway hosts. This is sufficient to allow each gateway machine to ping the other. On 192.168.1.1, you should be able to run ping 192.168.2.1 and get a response, and you should be able to do the same thing on the other gateway machine. However, you will not be able to reach internal machines on either network yet. This is because of the routing -- although the gateway machines know how to reach one another, they do not know how to reach the network behind each one. To solve this problem you must add a static route on each gateway machine. The command to do this on the first gateway would be: route add 192.168.2.0 192.168.2.1 netmask 0xffffff00 This says In order to reach the hosts on the network 192.168.2.0, send the packets to the host 192.168.2.1. You will need to run a similar command on the other gateway, but with the 192.168.1.x addresses instead. IP traffic from hosts on one network will now be able to reach hosts on the other network. That has now created two thirds of a VPN between the two networks, in as much as it's virtual and it's a network. It's not private yet. You can test this using &man.ping.8; and &man.tcpdump.1;. Log in to the gateway host and run tcpdump dst host 192.168.2.1 In another log in session on the same host run ping 192.168.2.1 You will see output that looks something like this. 16:10:24.018080 192.168.1.1 > 192.168.2.1: icmp: echo request 16:10:24.018109 192.168.1.1 > 192.168.2.1: icmp: echo reply 16:10:25.018814 192.168.1.1 > 192.168.2.1: icmp: echo request 16:10:25.018847 192.168.1.1 > 192.168.2.1: icmp: echo reply 16:10:26.028896 192.168.1.1 > 192.168.2.1: icmp: echo request 16:10:26.029112 192.168.1.1 > 192.168.2.1: icmp: echo reply As you can see, the ICMP messages are going back and forth unencrypted. If you had used the parameter to &man.tcpdump.1; to grab more bytes of data from the packets you would see more information. Obviously this is unacceptable. The next section will discuss securing the link between the two networks so that it all traffic is automatically encrypted. Summary: Configure both kernels with pseudo-device gif Edit /etc/rc.conf on gateway host #1 and add the following lines (replacing IP addresses as necessary). gifconfig_gif0="A.B.C.D W.X.Y.Z" ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff" static_routes="vpn" route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00" Edit your firewall script (/etc/rc.firewall, or similar) on both hosts, and add ipfw add 1 allow ip from any to any via gif0 Make similar changes to /etc/rc.conf on gateway host #2, reversing the order of IP addresses. Step 2: Securing the link To secure the link we will be using IPsec. IPsec provides a mechanism for two hosts to agree on an encryption key, and to then use this key in order to encrypt data between the two hosts. The are two areas of configuration to be considered here. There must be a mechanism for two hosts to agree on the encryption mechanism to use. Once two hosts have agreed on this mechanism there is said to be a security association between them. There must be a mechanism for specifying which traffic should be encrypted. Obviously, you don't want to encrypt all your outgoing traffic -- you only want to encrypt the traffic that is part of the VPN. The rules that you put in place to determine what traffic will be encrypted are called security policies. Security associations and security policies are both maintained by the kernel, and can be modified by userland programs. However, before you can do this you must configure the kernel to support IPsec and the Encapsulated Security Payload (ESP) protocol. This is done by configuring a kernel with: options IPSEC options IPSEC_ESP and recompiling, reinstalling, and rebooting. As before you will need to do this to the kernels on both of the gateway hosts. You have two choices when it comes to setting up security associations. You can configure them by hand between two hosts, which entails choosing the encryption algorithm, encryption keys, and so forth, or you can use daemons that implement the Internet Key Exchange protocol (IKE) to do this for you. I recommend the latter. Apart from anything else, it's easier to set up. Editing and displaying security policies is carried out using &man.setkey.8;. By analogy, setkey is to the kernel's security policy tables as &man.route.8; is to the kernel's routing tables. setkey can also display the current security associations, and to continue the analogy further, is akin to netstat -r in that respect. There are a number of choices for daemons to manage security associations with FreeBSD. This article will describe how to use one of these, racoon. racoon is in the FreeBSD ports collection, in the security/ category, and is installed in the usual way. racoon must be run on both gateway hosts. On each host it is configured with the IP address of the other end of the VPN, and a secret key (which you choose, and must be the same on both gateways). The two daemons then contact one another, confirm that they are who they say they are (by using the secret key that you configured). The daemons then generate a new secret key, and use this to encrypt the traffic over the VPN. They periodically change this secret, so that even if an attacker were to crack one of the keys (which is as theoretically close to unfeasible as it gets) it won't do them much good -- by the time they've cracked the key the two daemons have chosen another one. racoon's configuration is stored in ${PREFIX}/etc/racoon. You should find a configuration file there, which should not need to be changed too much. The other component of racoon's configuration, which you will need to change, is the pre-shared key. The default racoon configuration expects to find this in the file ${PREFIX}/etc/racoon/psk.txt. It is important to note that the pre-shared key is not the key that will be used to encrypt your traffic across the VPN link, it is simply a token that allows the key management daemons to trust one another. psk.txt contains a line for each remote site you are dealing with. In this example, where there are two sites, each psk.txt file will contain one line (because each end of the VPN is only dealing with one other end). On gateway host #1 this line should look like this: W.X.Y.Z secret That is, the public IP address of the remote end, whitespace, and a text string that provides the secret. Obviously, you shouldn't use secret as your key -- the normal rules for choosing a password apply. On gateway host #2 the line would look like this A.B.C.D secret That is, the public IP address of the remote end, and the same secret key. psk.txt must be mode 0600 (i.e., only read/write to root) before racoon will run. You must run racoon on both gateway machines. You will also need to add some firewall rules to allow the IKE traffic, which is carried over UDP to the isakmp (kmp == key management protocol) port. Again, this should be fairly early in your firewall ruleset. ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp Once racoon is running you can try pinging one gateway host from the other. The connection is still not encrypted, but racoon will then set up the security associations between the two hosts -- this might take a moment, and you may see this as a short delay before the ping commands start responding. Once the security association has been set up you can view it using &man.setkey.8;. Run setkey -D on either host to view the security association information. That's one half of the problem. They other half is setting your security policies. To create a sensible security policy, let's review what's been set up so far. This discussions hold for both ends of the link. Each IP packet that you send out has a header that contains data about the packet. The header includes the IP addresses of both the source and destination. As we already know, private IP addresses, such as the 192.168.x.y range are not supposed to appear on the public Internet. Instead, they must first be encapsulated inside another packet. This packet must have the public source and destination IP addresses substituted for the private addresses. So if your outgoing packet started looking like this: .----------------------. | Src: 192.168.1.1 | | Dst: 192.168.2.1 | | <other header info> | +----------------------+ | <packet data> | `----------------------' Then it will be encapsulated inside another packet, looking something like this: .--------------------------. | Src: A.B.C.D | | Dst: W.X.Y.Z | | <other header info> | +--------------------------+ | .----------------------. | | | Src: 192.168.1.1 | | | | Dst: 192.168.2.1 | | | | <other header info> | | | +----------------------+ | | | <packet data> | | | `----------------------' | `--------------------------' This encapsulation is carried out by the gif device. As you can see, the packet now has real IP addresses on the outside, and our original packet has been wrapped up as data inside the packet that will be put out on the Internet. Obviously, we want all traffic between the VPNs to be encrypted. You might try putting this in to words, as: If a packet leaves from A.B.C.D, and it is destined for W.X.Y.Z, then encrypt it, using the necessary security associations. If a packet arrives from W.X.Y.Z, and it is destined for A.B.C.D, then decrypt it, using the necessary security associations. That's close, but not quite right. If you did this, all traffic to and from W.X.Y.Z, even traffic that was not part of the VPN, would be encrypted. That's not quite what you want. The correct policy is as follows If a packet leaves from A.B.C.D, and that packet is encapsulating another packet, and it is destined for W.X.Y.Z, then encrypt it, using the necessary security associations. If a packet arrives from W.X.Y.Z, and that packet is encapsulating another packet, and it is destined for A.B.C.D, then encrypt it, using the necessary security associations. A subtle change, but a necessary one. Security policies are also set using &man.setkey.8;. &man.setkey.8; features a configuration language for defining the policy. You can either enter configuration instructions via stdin, or you can use the option to specify a filename that contains configuration instructions. The configuration on gateway host #1 (which has the public IP address A.B.C.D) to force all outbound traffic to W.X.Y.Z to be encrypted is: spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require; Put these commands in a file (e.g., /etc/ipsec.conf) and then run &prompt.root; setkey -f /etc/ipsec.conf tells &man.setkey.8; that we want to add a rule to the secure policy database. The rest of this line specifies which packets will match this policy. A.B.C.D/32 and W.X.Y.Z/32 are the IP addresses and netmasks that identify the network or hosts that this policy will apply to. In this case, we want it to apply to traffic between these two hosts. tells the kernel that this policy should only apply to packets that encapsulate other packets. says that this policy applies to outgoing packets, and says that the packet will be secured. The second line specifies how this packet will be encrypted. is the protocol that will be used, while indicates that the packet will be further encapsulated in an IPsec packet. The repeated use of A.B.C.D and W.X.Y.Z is used to select the security association to use, and the final mandates that packets must be encrypted if they match this rule. This rule only matches outgoing packets. You will need a similar rule to match incoming packets. spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require; Note the instead of in this case, and the necessary reversal of the IP addresses. The other gateway host (which has the public IP address W.X.Y.Z) will need similar rules. spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require; spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require; Finally, you need to add firewall rules to allow ESP and IPENCAP packets back and forth. These rules will need to be added to both hosts. ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D Because the rules are symmetric you can use the same rules on each gateway host. Outgoing packets will now look something like this: .------------------------------. --------------------------. | Src: A.B.C.D | | | Dst: W.X.Y.Z | | | <other header info> | | Encrypted +------------------------------+ | packet. | .--------------------------. | -------------. | contents | | Src: A.B.C.D | | | | are | | Dst: W.X.Y.Z | | | | completely | | <other header info> | | | |- secure | +--------------------------+ | | Encap'd | from third | | .----------------------. | | -. | packet | party | | | Src: 192.168.1.1 | | | | Original |- with real | snooping | | | Dst: 192.168.2.1 | | | | packet, | IP addr | | | | <other header info> | | | |- private | | | | +----------------------+ | | | IP addr | | | | | <packet data> | | | | | | | | `----------------------' | | -' | | | `--------------------------' | -------------' | `------------------------------' --------------------------' When they are received by the far end of the VPN they will first be decrypted (using the security associations that have been negotiated by racoon). Then they will enter the gif interface, which will unwrap the second layer, until you are left with the innermost packet, which can then travel in to the inner network. You can check the security using the same &man.ping.8; test from earlier. First, log in to the A.B.C.D gateway machine, and run: tcpdump dst host 192.168.2.1 In another log in session on the same host run ping 192.168.2.1 This time you should see output like the following: XXX tcpdump output Now, as you can see, &man.tcpdump.1; shows the ESP packets. If you try and examine them with the option you will see (apparently) gibberish, because of the encryption. Congratulations. You have just set up a VPN between two remote sites. Summary Configure both kernels with: options IPSEC options IPSEC_ESP Install security/racoon. Edit ${PREFIX}/etc/racoon/psk.txt on both gateway hosts, adding an entry for the remote host's IP address and a secret key that they both know. Make sure this file is mode 0600. Add the following lines to /etc/rc.conf on each host: ipsec_enable="YES" ipsec_file="/etc/ipsec.conf" Create an /etc/ipsec.conf on each host that contains the necessary spdadd lines. On gateway host #1 this would be: spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require; spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require; On gateway host #2 this would be: spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require; spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require; Add firewall rules to allow IKE, ESP, and IPENCAP traffic to both hosts: ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D The previous two steps should suffice to get the VPN up and running. Machines on each network will be able to refer to one another using IP addresses, and all traffic across the link will be automatically and securely encrypted. Chern Lee Contributed by OpenSSH OpenSSH security OpenSSH OpenSSH is a set of network connectivity tools used to access remote machines securely. It can be used as a direct replacement for rlogin, rsh, rcp, and telnet. Additionally, any other TCP/IP connections can be tunneled/forwarded securely through SSH. OpenSSH encrypts all traffic to effectively eliminate eavesdropping, connection hijacking, and other network-level attacks. OpenSSH is maintained by the OpenBSD project, and is based upon SSH v1.2.12 with all the recent bug fixes and updates. It is compatible with both SSH protocols 1 and 2. OpenSSH has been in the base system since FreeBSD 4.0. Advantages of Using OpenSSH Normally, when using &man.telnet.1; or &man.rlogin.1;, data is sent over the network in an clear, un-encrypted form. Network sniffers anywhere in between the client and server can steal your user/password information or data transferred in your session. OpenSSH offers a variety of authentication and encryption methods to prevent this from happening. Enabling sshd OpenSSH enabling Be sure to make the following addition to your rc.conf file: sshd_enable="YES" This will load &man.sshd.8;, the daemon program for OpenSSH, the next time your system initializes. Alternatively, you can simply run directly the sshd daemon by typing sshd on the command line. SSH Client OpenSSH client The &man.ssh.1; utility works similarly to &man.rlogin.1;. &prompt.root; ssh user@example.com Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)? yes Host 'example.com' added to the list of known hosts. user@example.com's password: ******* The login will continue just as it would have if a session was created using rlogin or telnet. SSH utilizes a key fingerprint system for verifying the authenticity of the server when the client connects. The user is prompted to enter yes only when connecting for the first time. Future attempts to login are all verified against the saved fingerprint key. The SSH client will alert you if the saved fingerprint differs from the received fingerprint on future login attempts. The fingerprints are saved in ~/.ssh/known_hosts, or ~/.ssh/known_hosts2 for SSH v2 fingerprints. By default, OpenSSH servers are configured to accept both SSH v1 and SSH v2 connections. The client, however, can choose between the two. Version 2 is known to be more robust and secure than its predecessor. The &man.ssh.1; command can be forced to use either protocol by passing it the or argument for v1 and v2, respectively. Secure Copy OpenSSH secure copy scp The &man.scp.1; command works similarly to &man.rcp.1;; it copies a file to or from a remote machine, except in a secure fashion. &prompt.root; scp user@example.com:/COPYRIGHT COPYRIGHT user@example.com's password: ******* COPYRIGHT 100% |*****************************| 4735 00:00 &prompt.root; Since the fingerprint was already saved for this host in the previous example, it is verified when using &man.scp.1; here. The arguments passed to &man.scp.1; are similar to &man.cp.1;, with the file or files in the first argument, and the destination in the second. Since the file is fetched over the network, through SSH, one or more of the file arguments takes on the form . Configuration OpenSSH configuration The system-wide configuration files for both the OpenSSH daemon and client reside within the /etc/ssh directory. ssh_config configures the client settings, while sshd_config configures the daemon. Additionally, the (/usr/sbin/sshd by default), and rc.conf options can provide more levels of configuration. ssh-keygen Instead of using passwords, &man.ssh-keygen.1; can be used to generate RSA keys to authenticate a user: &prompt.user; ssh-keygen -t rsa1 Initializing random number generator... Generating p: .++ (distance 66) Generating q: ..............................++ (distance 498) Computing the keys... Key generation complete. Enter file in which to save the key (/home/user/.ssh/identity): Enter passphrase: Enter the same passphrase again: Your identification has been saved in /home/user/.ssh/identity. ... &man.ssh-keygen.1; will create a public and private key pair for use in authentication. The private key is stored in ~/.ssh/identity, whereas the public key is stored in ~/.ssh/identity.pub. The public key must be placed in ~/.ssh/authorized_keys of the remote machine in order for the setup to work. This will allow connection to the remote machine based upon RSA authentication instead of passwords. The option will create RSA keys for use by SSH protocol version 1. If you want to use RSA keys with the SSH protocol version 2, you have to use the command . If a passphrase is used in &man.ssh-keygen.1;, the user will be prompted for a password each time in order to use the private key. A SSH protocol version 2 DSA key can be created for the same purpose by using the ssh-keygen -t dsa command. This will create a public/private DSA key for use in SSH protocol version 2 sessions only. The public key is stored in ~/.ssh/id_dsa.pub, while the private key is in ~/.ssh/id_dsa. DSA public keys are also placed in ~/.ssh/authorized_keys on the remote machine. &man.ssh-agent.1; and &man.ssh-add.1; are utilities used in managing multiple passworded private keys. The various options and files can be different according to the OpenSSH version you have on your system, to avoid problems you should consult the &man.ssh-keygen.1; manual page. SSH Tunneling OpenSSH tunneling OpenSSH has the ability to create a tunnel to encapsulate another protocol in an encrypted session. The following command tells &man.ssh.1; to create a tunnel for telnet: &prompt.user; ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com &prompt.user; The ssh command is used with the following options: Forces ssh to use version 2 of the protocol. (Do not use if you are working with older SSH servers) Indicates no command, or tunnel only. If omitted, ssh would initiate a normal session. Forces ssh to run in the background. Indicates a local tunnel in localport:remotehost:remoteport fashion. The remote SSH server. An SSH tunnel works by creating a listen socket on localhost on the specified port. It then forwards any connection received on the local host/port via the SSH connection to the specified remote host and port. In the example, port 5023 on localhost is being forwarded to port 23 on localhost of the remote machine. Since 23 is telnet, this would create a secure telnet session through an SSH tunnel. This can be used to wrap any number of insecure TCP protocols such as SMTP, POP3, FTP, etc. Using SSH to Create a Secure Tunnel for SMTP &prompt.user; ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com user@mailserver.example.com's password: ***** &prompt.user; telnet localhost 5025 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'. 220 mailserver.example.com ESMTP This can be used in conjunction with an &man.ssh-keygen.1; and additional user accounts to create a more seamless/hassle-free SSH tunneling environment. Keys can be used in place of typing a password, and the tunnels can be run as a separate user. Practical SSH Tunneling Examples Secure Access of a POP3 Server At work, there is an SSH server that accepts connections from the outside. On the same office network resides a mail server running a POP3 server. The network, or network path between your home and office may or may not be completely trustable. Because of this, you need to check your e-mail in a secure manner. The solution is to create an SSH connection to your office's SSH server, and tunnel through to the mail server. &prompt.user; ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com user@ssh-server.example.com's password: ****** When the tunnel is up and running, you can point your mail client to send POP3 requests to localhost port 2110. A connection here will be forwarded securely across the tunnel to mail.example.com. Bypassing a Draconian Firewall Some network administrators impose extremely draconian firewall rules, filtering not only incoming connections, but outgoing connections. You may be only given access to contact remote machines on ports 22 and 80 for SSH and web surfing. You may wish to access another (perhaps non-work related) service, such as an Ogg Vorbis server to stream music. If this Ogg Vorbis server is streaming on some other port than 22 or 80, you will not be able to access it. The solution is to create an SSH connection to a machine outside of your network's firewall, and use it to tunnel to the Ogg Vorbis server. &prompt.user; ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org user@unfirewalled-system.example.org's password: ******* Your streaming client can now be pointed to localhost port 8888, which will be forwarded over to music.example.com port 8000, successfully evading the firewall. Further Reading OpenSSH &man.ssh.1; &man.scp.1; &man.ssh-keygen.1; &man.ssh-agent.1; &man.ssh-add.1; &man.sshd.8; &man.sftp-server.8; Robert Watson Sponsored by DARPA and Network Associates Laboratories. Contributed by MAC Mandatory Access Control (MAC) FreeBSD 5.0 includes a new kernel security framework, the TrustedBSD MAC Framework. The MAC Framework permits compile-time, boot-time, and run-time extension of the kernel access control policy, and can be used to load support for Mandatory Access Control (MAC), and custom security modules such as hardening modules. The MAC Framework is currently considered to be an experimental feature, and should not yet be used in production environments without careful consideration. It is anticipated that the MAC Framework will be appropriate for more widespread production use by FreeBSD 5.2. When configured into a kernel, the MAC Framework permits security modules to augment the existing kernel access control model, restricting access to system services and objects. For example, the &man.mac.bsdextended.4; module augments file system access control, permitting administrators to provide a firewall-like ruleset constraining access to file system objects based on user ids and group membership. Some modules require little or no configuration, such as &man.mac.seeotheruids.4, whereas others perform ubiquitous object labeling, such as &man.mac.biba.4; and &man.mac.mls.4;, and require extensive configuration. To enable the MAC Framework in your system kernel, you must add the following entry to your kernel configuration: options MAC Security policy modules shipped with the base system may be loaded using &man.kldload.8; or in the boot &man.loader.8; They may also be compiled directly into the kernel using the following options, if the use of modules is not desired. Different MAC policies may be configured in different ways; frequently, MAC policy modules export configuration parameters using the &man.sysctl.8; MIB using the security.mac namespace. Policies relying on file system or other labels may require a configuration step that involves assigning initial labels to system objects or creating a policy configuration file. For information on how to configure and use each policy module, see its man page. A variety of tools are available to configure the MAC Framework and labels maintained by various policies. Extensions have been made to the login and credential management mechanisms (&man.setusercontext.3;) to support initial user labeling using &man.login.conf.5;. In addition, modifications have been made to &man.su.1;, &man.ps.1;, &man.ls.1;, and &man.ifconfig.8; to inspect and set labels on processes, files, and interfaces. In addition, several new tools have been added to manage labels on objects, including &man.getfmac.8;, &man.setfmac.8;, and &man.setfsmac.8; to manage labels on files, and &man.getpmac.8; and &man.setpmac.8;. What follows is a list of policy modules shipped with FreeBSD 5.0. Biba Integrity Policy (mac_biba) Biba Integrity Policy Vendor: TrustedBSD Project Module name: mac_biba.ko Kernel option: MAC_BIBA TCB The Biba Integrity Policy (&man.mac.biba.4;) provides for hierarchical and non-hierarchical labeling of all system objects with integrity data, and the strict enforcement of an information flow policy to prevent corruption of high integrity subjects and data by low-integrity subjects. Integrity is enforced by preventing high integrity subjects (generally processes) from reading low integrity objects (often files), and preventing low integrity subjects from writing to high integrity objects. This security policy is frequently used in commercial trusted systems to provide strong protection for the Trusted Code Base (TCB). Because it provides ubiquitous labeling, the Biba integrity policy must be compiled into the kernel or loaded at boot. File System Firewall Policy (mac_bsdextended) File System Firewall Policy Vendor: TrustedBSD Project Module name: mac_bsdextended.ko Kernel option: MAC_BSDEXTENDED The File System Firewall Policy (&man.mac.bsdextended.4;) provides an extension to the BSD file system permission model, permitting the administrator to define a set of firewall-like rules for limiting access to file system objects owned by other users and groups. Managed using &man.ugidfw.8;, rules may limit access to files and directories based on the uid and gids of the process attempting the access, and the owner and group of the target of the access attempt. All rules are restrictive, so they may be placed in any order. This policy requires no prior configuration or labeling, and may be appropriate in multi-user environments where mandatory limits on inter-user data exchange are required. Caution should be exercised in limiting access to files owned by the super-user or other system user ids, as many useful programs and directories are owned by these users. As with a network firewall, improper application of file system firewall rules may render the system unusable. New tools to manage the rule set may be easily written using the &man.libugidfw.3; library. Interface Silencing Policy (mac_ifoff) Interface Silencing Policy Vendor: TrustedBSD Project Module name: mac_ifoff.ko Kernel option: MAC_IFOFF The interface silencing policy (&man.mac.ifoff.4;) prohibits the use of network interfaces during the boot until explicitly enabled, preventing spurious stack output stack response to incoming packets. This is appropriate for use in environments where the monitoring of packets is required, but no traffic may be generated. Low-Watermark Mandatory Access Control (LOMAC) (mac_lomac) MAC Low-Watermark LOMAC Vendor: Network Associates Laboratories Module name: mac_lomac.ko Kernel option: MAC_LOMAC Similar to the Biba Integrity Policy, the LOMAC policy (&man.mac.lomac.4;) relies on the ubiquitous labeling of all system objects with integrity labels. Unlike Biba, LOMAC permits high integrity subjects to read from low integrity objects, but then downgrades the label on the subject to prevent future writes to high integrity objects. This policy may provide for greater compatibility, as well as require less initial configuration than Biba. However, as with Biba, it ubiquitously labels objects and must therefore be compiled into the kernel or loaded at boot. Multi-Level Security Policy (MLS) (mac_mls) Multi-Level Security Policy MAC Multi-Level Vendor: TrustedBSD Project Module name: mac_mls.ko Kernel option: MAC_MLS Multi-Level Security (MLS) (&man.mac.mls.4;) provides for hierarchical and non-hierarchical labeling of all system objects with sensitivity data, and the strict enforcement of an information flow policy to prevent the leakage of confidential data to untrusted parties. The logical conjugate of the Biba Integrity Policy, MLS is frequently shipped in commercial trusted operating systems to protect data secrecy in multi-user environments. Hierarchal labels provide support for the notion of clearances and classifications in traditional parlance; non-hierarchical labels provide support for need-to-know. As with Biba, ubiquitous labeling of objects occurs, and it must therefore be compiled into the kernel or loaded at boot. As with Biba, extensive initial configuration may be required. MAC Stub Policy (mac_none) MAC Stub Policy Vendor: TrustedBSD Project Module name: mac_none.ko Kernel option: MAC_NONE The None policy (&man.mac.none.4;) provides a stub sample policy for developers, implementing all entry points, but not changing the system access control policy. Running this on a production system would not be highly beneficial. Process Partition Policy (mac_partition) Process Partition Policy Vendor: TrustedBSD Project Module name: mac_partition.ko Kernel option: MAC_PARTITION The Partition policy (&man.mac.partition.4;) provides for a simple process visibility limitation, assigning labels to processes identifying what numeric system partition they are present in. If none, all other processes are visible using standard monitoring tools; if a partition identifier is present, then only other processes in the same partition are visible. This policy may be compiled into the kernel, loaded at boot, or loaded at run-time. See Other Uids Policy (mac_seeotheruids) See Other Uids Policy Vendor: TrustedBSD Project Module name: mac_seeotheruids.ko Kernel option: MAC_SEEOTHERUIDS The See Other Uids policy (&man.mac.seeotheruids.4;) implements a similar process visibility model to mac_partition, except that it relies on process credentials to control visibility of processes, rather than partition labels. This policy may be configured to exempt certain users and groups, including permitting system operators to view all processes without special privilege. This policy may be compiled into the kernel, loaded at boot, or loaded at run-time. MAC Framework Test Policy (mac_test) MAC Framework Test Policy Vendor: TrustedBSD Project Module name: mac_test.ko Kernel option: MAC_TEST The Test policy (&man.mac.test.4;) provides a regression test environment for the MAC Framework, and will cause a fail-stop in the event that internal MAC Framework assertions about proper data labeling fail. This module can be used to detect failures to properly label system objects in the kernel implementation. This policy may be compiled into the kernel, loaded at boot, or loaded at run-time. Tom Rhodes Contributed by ACL File System Access Control Lists In conjunction with file system enhancements like snapshots, FreeBSD 5.0 and later offers the security of File System Access Control Lists (ACLs). Access Control Lists extend the standard &unix; permission model in a highly compatible (&posix;.1e) way. This feature permits an administrator to make use of and take advantage of a more sophisticated security model. To enable ACL support for UFS file systems, the following: options UFS_ACL must be compiled into the kernel. If this option has not been compiled in, a warning message will be displayed when attempting to mount a file system supporting ACLs. This option is included in the GENERIC kernel. ACLs rely on extended attributes being enabled on the file system. Extended attributes are natively supported in the next generation &unix; file system, UFS2. A higher level of administrative overhead is required to configure extended attributes on UFS1 than on UFS2. The performance of extended attributes on UFS2 is also substantially higher. As a result, UFS2 is generally recommended in preference to UFS1 for use with access control lists. ACLs are enabled by the mount-time administrative flag, , which may be added to /etc/fstab. The mount-time flag can also be automatically set in a persistent manner using &man.tunefs.8; to modify a superblock ACLs flag in the file system header. In general, it is preferred to use the superblock flag for several reasons: The mount-time ACLs flag cannot be changed by a remount (&man.mount.8; ), only by means of a complete &man.umount.8; and fresh &man.mount.8;. This means that ACLs cannot be enabled on the root file system after boot. It also means that you cannot change the disposition of a file system once it is in use. Setting the superblock flag will cause the file system to always be mounted with ACLs enabled even if there is not an fstab entry or if the devices re-order. This prevents accidental mounting of the file system without ACLs enabled, which can result in ACLs being improperly enforced, and hence security problems. We may change the ACLs behavior to allow the flag to be enabled without a complete fresh &man.mount.8;, but we consider it desirable to discourage accidental mounting without ACLs enabled, because you can shoot your feet quite nastily if you enable ACLs, then disable them, then re-enable them without flushing the extended attributes. In general, once you have enabled ACLs on a file system, they should not be disabled, as the resulting file protections may not be compatible with those intended by the users of the system, and re-enabling ACLs may re-attach the previous ACLs to files that have since had their permissions changed, resulting in other unpredictable behavior. File systems with ACLs enabled will show a + (plus) sign in their permission settings when viewed. For example: drwx------ 2 robert robert 512 Dec 27 11:54 private drwxrwx---+ 2 robert robert 512 Dec 23 10:57 directory1 drwxrwx---+ 2 robert robert 512 Dec 22 10:20 directory2 drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3 drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html Here we see that the directory1, directory2, and directory3 directories are all taking advantage of ACLs. The public_html directory is not. diff --git a/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml index fa3ab831c4..8971955f2c 100644 --- a/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml @@ -1,1453 +1,1454 @@ The Vinum Volume Manager Synopsis No matter what disks you have, there will always be limitations: They can be too small. They can be too slow. They can be too unreliable. Greg Lehey Originally written by Disks Are Too Small Vinum RAID Software Vinum is a so-called Volume Manager, a virtual disk driver that addresses these three problems. Let us look at them in more detail. Various solutions to these problems have been proposed and implemented: Disks are getting bigger, but so are data storage requirements. Often you will find you want a file system that is bigger than the disks you have available. Admittedly, this problem is not as acute as it was ten years ago, but it still exists. Some systems have solved this by creating an abstract device which stores its data on a number of disks. Access Bottlenecks Modern systems frequently need to access data in a highly concurrent manner. For example, large FTP or HTTP servers can maintain thousands of concurrent sessions and have multiple 100 Mbit/s connections to the outside world, well beyond the sustained transfer rate of most disks. Current disk drives can transfer data sequentially at up to 70 MB/s, but this value is of little importance in an environment where many independent processes access a drive, where they may achieve only a fraction of these values. In such cases it is more interesting to view the problem from the viewpoint of the disk subsystem: the important parameter is the load that a transfer places on the subsystem, in other words the time for which a transfer occupies the drives involved in the transfer. In any disk transfer, the drive must first position the heads, wait for the first sector to pass under the read head, and then perform the transfer. These actions can be considered to be atomic: it does not make any sense to interrupt them. Consider a typical transfer of about 10 kB: the current generation of high-performance disks can position the heads in an average of 3.5 ms. The fastest drives spin at 15,000 rpm, so the average rotational latency (half a revolution) is 2 ms. At 70 MB/s, the transfer itself takes about 150 μs, almost nothing compared to the positioning time. In such a case, the effective transfer rate drops to a little over 1 MB/s and is clearly highly dependent on the transfer size. The traditional and obvious solution to this bottleneck is more spindles: rather than using one large disk, it uses several smaller disks with the same aggregate storage space. Each disk is capable of positioning and transferring independently, so the effective throughput increases by a factor close to the number of disks used. The exact throughput improvement is, of course, smaller than the number of disks involved: although each drive is capable of transferring in parallel, there is no way to ensure that the requests are evenly distributed across the drives. Inevitably the load on one drive will be higher than on another. disk concatenation Vinum concatenation The evenness of the load on the disks is strongly dependent on the way the data is shared across the drives. In the following discussion, it is convenient to think of the disk storage as a large number of data sectors which are addressable by number, rather like the pages in a book. The most obvious method is to divide the virtual disk into groups of consecutive sectors the size of the individual physical disks and store them in this manner, rather like taking a large book and tearing it into smaller sections. This method is called concatenation and has the advantage that the disks are not required to have any specific size relationships. It works well when the access to the virtual disk is spread evenly about its address space. When access is concentrated on a smaller area, the improvement is less marked. illustrates the sequence in which storage units are allocated in a concatenated organization.
Concatenated Organization
disk striping Vinum striping An alternative mapping is to divide the address space into smaller, equal-sized components and store them sequentially on different devices. For example, the first 256 sectors may be stored on the first disk, the next 256 sectors on the next disk and so on. After filling the last disk, the process repeats until the disks are full. This mapping is called striping or RAID-0 RAID RAID stands for Redundant Array of Inexpensive Disks and offers various forms of fault tolerance, though the latter term is somewhat misleading: it provides no redundancy. . Striping requires somewhat more effort to locate the data, and it can cause additional I/O load where a transfer is spread over multiple disks, but it can also provide a more constant load across the disks. illustrates the sequence in which storage units are allocated in a striped organization.
Striped Organization
Data Integrity The final problem with current disks is that they are unreliable. Although disk drive reliability has increased tremendously over the last few years, they are still the most likely core component of a server to fail. When they do, the results can be catastrophic: replacing a failed disk drive and restoring data to it can take days. disk mirroring Vinum mirroring RAID-1 The traditional way to approach this problem has been mirroring, keeping two copies of the data on different physical hardware. Since the advent of the RAID levels, this technique has also been called RAID level 1 or RAID-1. Any write to the volume writes to both locations; a read can be satisfied from either, so if one drive fails, the data is still available on the other drive. Mirroring has two problems: The price. It requires twice as much disk storage as a non-redundant solution. The performance impact. Writes must be performed to both drives, so they take up twice the bandwidth of a non-mirrored volume. Reads do not suffer from a performance penalty: it even looks as if they are faster. RAID-5An alternative solution is parity, implemented in the RAID levels 2, 3, 4 and 5. Of these, RAID-5 is the most interesting. As implemented in Vinum, it is a variant on a striped organization which dedicates one block of each stripe to parity of the other blocks. As implemented by Vinum, a RAID-5 plex is similar to a striped plex, except that it implements RAID-5 by including a parity block in each stripe. As required by RAID-5, the location of this parity block changes from one stripe to the next. The numbers in the data blocks indicate the relative block numbers.
RAID-5 Organization
Compared to mirroring, RAID-5 has the advantage of requiring significantly less storage space. Read access is similar to that of striped organizations, but write access is significantly slower, approximately 25% of the read performance. If one drive fails, the array can continue to operate in degraded mode: a read from one of the remaining accessible drives continues normally, but a read from the failed drive is recalculated from the corresponding block from all the remaining drives. Vinum Objects In order to address these problems, Vinum implements a four-level hierarchy of objects: The most visible object is the virtual disk, called a volume. Volumes have essentially the same properties as a &unix; disk drive, though there are some minor differences. They have no size limitations. Volumes are composed of plexes, each of which represent the total address space of a volume. This level in the hierarchy thus provides redundancy. Think of plexes as individual disks in a mirrored array, each containing the same data. Since Vinum exists within the &unix; disk storage framework, it would be possible to use &unix; partitions as the building block for multi-disk plexes, but in fact this turns out to be too inflexible: &unix; disks can have only a limited number of partitions. Instead, Vinum subdivides a single &unix; partition (the drive) into contiguous areas called subdisks, which it uses as building blocks for plexes. Subdisks reside on Vinum drives, currently &unix; partitions. Vinum drives can contain any number of subdisks. With the exception of a small area at the beginning of the drive, which is used for storing configuration and state information, the entire drive is available for data storage. The following sections describe the way these objects provide the functionality required of Vinum. Volume Size Considerations Plexes can include multiple subdisks spread over all drives in the Vinum configuration. As a result, the size of an individual drive does not limit the size of a plex, and thus of a volume. Redundant Data Storage Vinum implements mirroring by attaching multiple plexes to a volume. Each plex is a representation of the data in a volume. A volume may contain between one and eight plexes. Although a plex represents the complete data of a volume, it is possible for parts of the representation to be physically missing, either by design (by not defining a subdisk for parts of the plex) or by accident (as a result of the failure of a drive). As long as at least one plex can provide the data for the complete address range of the volume, the volume is fully functional. Performance Issues Vinum implements both concatenation and striping at the plex level: A concatenated plex uses the address space of each subdisk in turn. A striped plex stripes the data across each subdisk. The subdisks must all have the same size, and there must be at least two subdisks in order to distinguish it from a concatenated plex. Which Plex Organization? The version of Vinum supplied with FreeBSD &rel.current; implements two kinds of plex: Concatenated plexes are the most flexible: they can contain any number of subdisks, and the subdisks may be of different length. The plex may be extended by adding additional subdisks. They require less CPU time than striped plexes, though the difference in CPU overhead is not measurable. On the other hand, they are most susceptible to hot spots, where one disk is very active and others are idle. The greatest advantage of striped (RAID-0) plexes is that they reduce hot spots: by choosing an optimum sized stripe (about 256 kB), you can even out the load on the component drives. The disadvantages of this approach are (fractionally) more complex code and restrictions on subdisks: they must be all the same size, and extending a plex by adding new subdisks is so complicated that Vinum currently does not implement it. Vinum imposes an additional, trivial restriction: a striped plex must have at least two subdisks, since otherwise it is indistinguishable from a concatenated plex. summarizes the advantages and disadvantages of each plex organization. Vinum Plex Organizations Plex type Minimum subdisks Can add subdisks Must be equal size Application concatenated 1 yes no Large data storage with maximum placement flexibility and moderate performance striped 2 no yes High performance in combination with highly concurrent access
Some Examples Vinum maintains a configuration database which describes the objects known to an individual system. Initially, the user creates the configuration database from one or more configuration files with the aid of the &man.vinum.8; utility program. Vinum stores a copy of its configuration database on each disk slice (which Vinum calls a device) under its control. This database is updated on each state change, so that a restart accurately restores the state of each Vinum object. The Configuration File The configuration file describes individual Vinum objects. The definition of a simple volume might be: drive a device /dev/da3h volume myvol plex org concat sd length 512m drive a This file describes four Vinum objects: The drive line describes a disk partition (drive) and its location relative to the underlying hardware. It is given the symbolic name a. This separation of the symbolic names from the device names allows disks to be moved from one location to another without confusion. The volume line describes a volume. The only required attribute is the name, in this case myvol. The plex line defines a plex. The only required parameter is the organization, in this case concat. No name is necessary: the system automatically generates a name from the volume name by adding the suffix .px, where x is the number of the plex in the volume. Thus this plex will be called myvol.p0. The sd line describes a subdisk. The minimum specifications are the name of a drive on which to store it, and the length of the subdisk. As with plexes, no name is necessary: the system automatically assigns names derived from the plex name by adding the suffix .sx, where x is the number of the subdisk in the plex. Thus Vinum gives this subdisk the name myvol.p0.s0. After processing this file, &man.vinum.8; produces the following output: &prompt.root; vinum -> create config1 Configuration summary Drives: 1 (4 configured) Volumes: 1 (4 configured) Plexes: 1 (8 configured) Subdisks: 1 (16 configured) D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%) V myvol State: up Plexes: 1 Size: 512 MB P myvol.p0 C State: up Subdisks: 1 Size: 512 MB S myvol.p0.s0 State: up PO: 0 B Size: 512 MB This output shows the brief listing format of &man.vinum.8;. It is represented graphically in .
A Simple Vinum Volume
This figure, and the ones which follow, represent a volume, which contains the plexes, which in turn contain the subdisks. In this trivial example, the volume contains one plex, and the plex contains one subdisk. This particular volume has no specific advantage over a conventional disk partition. It contains a single plex, so it is not redundant. The plex contains a single subdisk, so there is no difference in storage allocation from a conventional disk partition. The following sections illustrate various more interesting configuration methods. Increased Resilience: Mirroring The resilience of a volume can be increased by mirroring. When laying out a mirrored volume, it is important to ensure that the subdisks of each plex are on different drives, so that a drive failure will not take down both plexes. The following configuration mirrors a volume: drive b device /dev/da4h volume mirror plex org concat sd length 512m drive a plex org concat sd length 512m drive b In this example, it was not necessary to specify a definition of drive a again, since Vinum keeps track of all objects in its configuration database. After processing this definition, the configuration looks like: Drives: 2 (4 configured) Volumes: 2 (4 configured) Plexes: 3 (8 configured) Subdisks: 3 (16 configured) D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%) D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%) V myvol State: up Plexes: 1 Size: 512 MB V mirror State: up Plexes: 2 Size: 512 MB P myvol.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB S myvol.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB shows the structure graphically.
A Mirrored Vinum Volume
In this example, each plex contains the full 512 MB of address space. As in the previous example, each plex contains only a single subdisk. Optimizing Performance The mirrored volume in the previous example is more resistant to failure than an unmirrored volume, but its performance is less: each write to the volume requires a write to both drives, using up a greater proportion of the total disk bandwidth. Performance considerations demand a different approach: instead of mirroring, the data is striped across as many disk drives as possible. The following configuration shows a volume with a plex striped across four disk drives: drive c device /dev/da5h drive d device /dev/da6h volume stripe plex org striped 512k sd length 128m drive a sd length 128m drive b sd length 128m drive c sd length 128m drive d As before, it is not necessary to define the drives which are already known to Vinum. After processing this definition, the configuration looks like: Drives: 4 (4 configured) Volumes: 3 (4 configured) Plexes: 4 (8 configured) Subdisks: 7 (16 configured) D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%) D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%) D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%) D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%) V myvol State: up Plexes: 1 Size: 512 MB V mirror State: up Plexes: 2 Size: 512 MB V striped State: up Plexes: 1 Size: 512 MB P myvol.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB P striped.p1 State: up Subdisks: 1 Size: 512 MB S myvol.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB S striped.p0.s0 State: up PO: 0 B Size: 128 MB S striped.p0.s1 State: up PO: 512 kB Size: 128 MB S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB
A Striped Vinum Volume
This volume is represented in . The darkness of the stripes indicates the position within the plex address space: the lightest stripes come first, the darkest last. Resilience and Performance With sufficient hardware, it is possible to build volumes which show both increased resilience and increased performance compared to standard &unix; partitions. A typical configuration file might be: volume raid10 plex org striped 512k sd length 102480k drive a sd length 102480k drive b sd length 102480k drive c sd length 102480k drive d sd length 102480k drive e plex org striped 512k sd length 102480k drive c sd length 102480k drive d sd length 102480k drive e sd length 102480k drive a sd length 102480k drive b The subdisks of the second plex are offset by two drives from those of the first plex: this helps ensure that writes do not go to the same subdisks even if a transfer goes over two drives. represents the structure of this volume.
A Mirrored, Striped Vinum Volume
Object Naming As described above, Vinum assigns default names to plexes and subdisks, although they may be overridden. Overriding the default names is not recommended: experience with the VERITAS volume manager, which allows arbitrary naming of objects, has shown that this flexibility does not bring a significant advantage, and it can cause confusion. Names may contain any non-blank character, but it is recommended to restrict them to letters, digits and the underscore characters. The names of volumes, plexes and subdisks may be up to 64 characters long, and the names of drives may be up to 32 characters long. Vinum objects are assigned device nodes in the hierarchy /dev/vinum. The configuration shown above would cause Vinum to create the following device nodes: The control devices /dev/vinum/control and /dev/vinum/controld, which are used by &man.vinum.8; and the Vinum daemon respectively. Block and character device entries for each volume. These are the main devices used by Vinum. The block device names are the name of the volume, while the character device names follow the BSD tradition of prepending the letter r to the name. Thus the configuration above would include the block devices /dev/vinum/myvol, /dev/vinum/mirror, /dev/vinum/striped, /dev/vinum/raid5 and /dev/vinum/raid10, and the character devices /dev/vinum/rmyvol, /dev/vinum/rmirror, /dev/vinum/rstriped, /dev/vinum/rraid5 and /dev/vinum/rraid10. There is obviously a problem here: it is possible to have two volumes called r and rr, but there will be a conflict creating the device node /dev/vinum/rr: is it a character device for volume r or a block device for volume rr? Currently Vinum does not address this conflict: the first-defined volume will get the name. A directory /dev/vinum/drive with entries for each drive. These entries are in fact symbolic links to the corresponding disk nodes. A directory /dev/vinum/volume with entries for each volume. It contains subdirectories for each plex, which in turn contain subdirectories for their component subdisks. The directories /dev/vinum/plex, /dev/vinum/sd, and /dev/vinum/rsd, which contain block device nodes for each plex and block and character device nodes respectively for each subdisk. For example, consider the following configuration file: drive drive1 device /dev/sd1h drive drive2 device /dev/sd2h drive drive3 device /dev/sd3h drive drive4 device /dev/sd4h volume s64 setupstate plex org striped 64k sd length 100m drive drive1 sd length 100m drive drive2 sd length 100m drive drive3 sd length 100m drive drive4 After processing this file, &man.vinum.8; creates the following structure in /dev/vinum: brwx------ 1 root wheel 25, 0x40000001 Apr 13 16:46 Control brwx------ 1 root wheel 25, 0x40000002 Apr 13 16:46 control brwx------ 1 root wheel 25, 0x40000000 Apr 13 16:46 controld drwxr-xr-x 2 root wheel 512 Apr 13 16:46 drive drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 rs64 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rsd drwxr-xr-x 2 root wheel 512 Apr 13 16:46 rvol brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd drwxr-xr-x 3 root wheel 512 Apr 13 16:46 vol /dev/vinum/drive: total 0 lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive1 -> /dev/sd1h lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive2 -> /dev/sd2h lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive3 -> /dev/sd3h lrwxr-xr-x 1 root wheel 9 Apr 13 16:46 drive4 -> /dev/sd4h /dev/vinum/plex: total 0 brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0 /dev/vinum/rsd: total 0 crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0 crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1 crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2 crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3 /dev/vinum/rvol: total 0 crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64 /dev/vinum/sd: total 0 brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0 brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1 brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2 brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3 /dev/vinum/vol: total 1 brwxr-xr-- 1 root wheel 25, 2 Apr 13 16:46 s64 drwxr-xr-x 3 root wheel 512 Apr 13 16:46 s64.plex /dev/vinum/vol/s64.plex: total 1 brwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 s64.p0.sd /dev/vinum/vol/s64.plex/s64.p0.sd: total 0 brwxr-xr-- 1 root wheel 25, 0x20000002 Apr 13 16:46 s64.p0.s0 brwxr-xr-- 1 root wheel 25, 0x20100002 Apr 13 16:46 s64.p0.s1 brwxr-xr-- 1 root wheel 25, 0x20200002 Apr 13 16:46 s64.p0.s2 brwxr-xr-- 1 root wheel 25, 0x20300002 Apr 13 16:46 s64.p0.s3 Although it is recommended that plexes and subdisks should not be allocated specific names, Vinum drives must be named. This makes it possible to move a drive to a different location and still recognize it automatically. Drive names may be up to 32 characters long. Creating File Systems Volumes appear to the system to be identical to disks, with one exception. Unlike &unix; drives, Vinum does not partition volumes, which thus do not contain a partition table. This has required modification to some disk utilities, notably &man.newfs.8;, which previously tried to interpret the last letter of a Vinum volume name as a partition identifier. For example, a disk drive may have a name like /dev/ad0a or /dev/da2h. These names represent the first partition (a) on the first (0) IDE disk (ad) and the eighth partition (h) on the third (2) SCSI disk (da) respectively. By contrast, a Vinum volume might be called /dev/vinum/concat, a name which has no relationship with a partition name. Normally, &man.newfs.8; interprets the name of the disk and complains if it cannot understand it. For example: &prompt.root; newfs /dev/vinum/concat newfs: /dev/vinum/concat: can't figure out file system partition The following is only valid for FreeBSD versions prior to 5.0: In order to create a file system on this volume, use the option to &man.newfs.8;: &prompt.root; newfs -v /dev/vinum/concat Configuring Vinum The GENERIC kernel does not contain Vinum. It is possible to build a special kernel which includes Vinum, but this is not recommended. The standard way to start Vinum is as a kernel module (kld). You do not even need to use &man.kldload.8; for Vinum: when you start &man.vinum.8;, it checks whether the module has been loaded, and if it is not, it loads it automatically. Startup Vinum stores configuration information on the disk slices in essentially the same form as in the configuration files. When reading from the configuration database, Vinum recognizes a number of keywords which are not allowed in the configuration files. For example, a disk configuration might contain the following text: volume myvol state up volume bigraid state down plex name myvol.p0 state up org concat vol myvol plex name myvol.p1 state up org concat vol myvol plex name myvol.p2 state init org striped 512b vol myvol plex name bigraid.p0 state initializing org raid5 512b vol bigraid sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b The obvious differences here are the presence of explicit location information and naming (both of which are also allowed, but discouraged, for use by the user) and the information on the states (which are not available to the user). Vinum does not store information about drives in the configuration information: it finds the drives by scanning the configured disk drives for partitions with a Vinum label. This enables Vinum to identify drives correctly even if they have been assigned different &unix; drive IDs. Automatic Startup In order to start Vinum automatically when you boot the system, ensure that you have the following line in your /etc/rc.conf: start_vinum="YES" # set to YES to start vinum If you do not have a file /etc/rc.conf, create one with this content. This will cause the system to load the Vinum kld at startup, and to start any objects mentioned in the configuration. This is done before mounting file systems, so it is possible to automatically &man.fsck.8; and mount file systems on Vinum volumes. When you start Vinum with the vinum start command, Vinum reads the configuration database from one of the Vinum drives. Under normal circumstances, each drive contains an identical copy of the configuration database, so it does not matter which drive is read. After a crash, however, Vinum must determine which drive was updated most recently and read the configuration from this drive. It then updates the configuration if necessary from progressively older drives. Using Vinum for the Root Filesystem For a machine that has fully-mirrored filesystems using Vinum, it is desirable to also mirror the root filesystem. Setting up such a configuration is less trivial than mirroring an arbitrary filesystem because: The root filesystem must be available very early during the boot process, so the Vinum infrastructure must already be available at this time. The volume containing the root filesystem also contains the system bootstrap and the kernel, which must be read using the host system's native utilities (e. g. the BIOS on PC-class machines) which often cannot be taught about the details of Vinum. In the following sections, the term root volume is generally used to describe the Vinum volume that contains the root filesystem. It is probably a good idea to use the name "root" for this volume, but this is not technically required in any way. All command examples in the following sections assume this name though. Starting up Vinum Early Enough for the Root Filesystem There are several measures to take for this to happen: Vinum must be available in the kernel at boot-time. Thus, the method to start Vinum automatically described in is not applicable to accomplish this task, and the start_vinum parameter must actually not be set when the following setup is being arranged. The first option would be to compile Vinum statically into the kernel, so it is available all the time, but this is usually not desirable. There is another option as well, to have /boot/loader () load the vinum kernel module early, before starting the kernel. This can be accomplished by putting the line vinum_load="YES" into the file /boot/loader.conf. Vinum must be initialized early since it needs to supply the volume for the root filesystem. By default, the Vinum kernel part is not looking for drives that might contain Vinum volume information until the administrator (or one of the startup scripts) issues a vinum start command. The following paragraphs are outlining the steps needed for FreeBSD 5.x and above. The setup required for FreeBSD 4.x differs, and is described below in . By placing the line: vinum.autostart="YES" into /boot/loader.conf, Vinum is instructed to automatically scan all drives for Vinum information as part of the kernel startup. Note that it is not necessary to instruct the kernel where to look for the root filesystem. /boot/loader looks up the name of the root device in /etc/fstab, and passes this information on to the kernel. When it comes to mount the root filesystem, the kernel figures out from the devicename provided which driver to ask to translate this into the internal device ID (major/minor number). Making a Vinum-based Root Volume Accessible to the Bootstrap Since the current FreeBSD bootstrap is only 7.5 KB of code, and already has the burden of reading files (like /boot/loader) from the UFS filesystem, it is sheer impossible to also teach it about internal Vinum structures so it could parse the Vinum configuration data, and figure out about the elements of a boot volume itself. Thus, some tricks are necessary to provide the bootstrap code with the illusion of a standard "a" partition that contains the root filesystem. For this to be possible at all, the following requirements must be met for the root volume: The root volume must not be striped or RAID-5. The root volume must not contain more than one concatenated subdisk per plex. + Note that it is desirable and possible that there are multiple plexes, each containing one replica of the root filesystem. The bootstrap process will, however, only use one of these replica for finding the bootstrap and all the files, until the kernel will eventually mount the root filesystem itself. Each single subdisk within these plexes will then need its own "a" partition illusion, for the respective device to become bootable. It is not strictly needed that each of these faked "a" partitions is located at the same offset within its device, compared with other devices containing plexes of the root volume. However, it is probably a good idea to create the Vinum volumes that way so the resulting mirrored devices are symmetric, to avoid confusion. In order to setup these "a" partitions, for each device containing part of the root volume, the following needs to be done: The location (offset from the beginning of the device) and size of this device's subdisk that is part of the root volume need to be examined, using the command vinum l -rv root Note that Vinum offsets and sizes are measured in bytes. They must be divided by 512 in order to obtain the block numbers that are to be used in the disklabel command. Run the command disklabel -e devname for each device that participates in the root volume. devname must be either the name of the disk (like da0) for disks without a slice (aka. fdisk) table, or the name of the slice (like ad0s1). If there is already an "a" partition on the device (presumably, containing a pre-Vinum root filesystem), it should be renamed to something else, so it remains accessible (just in case), but will no longer be used by default to bootstrap the system. Note that active partitions (like a root filesystem currently mounted) cannot be renamed, so this must be executed either when being booted from a Fixit medium, or in a two-step process, where (in a mirrored situation) the disk that has not been currently booted is being manipulated first. Then, the offset the Vinum partition on this device (if any) must be added to the offset of the respective root volume subdisk on this device. The resulting value will become the "offset" value for the new "a" partition. The "size" value for this partition can be taken verbatim from the calculation above. The "fstype" should be 4.2BSD. The "fsize", "bsize", and "cpg" values should best be chosen to match the actual filesystem, though they are fairly unimportant within this context. That way, a new "a" partition will be established that overlaps the Vinum partition on this device. Note that the disklabel will only allow for this overlap if the Vinum partition has properly been marked using the "vinum" fstype. That's all! A faked "a" partition does exist now on each device that has one replica of the root volume. It is highly recommendable to verify the result again, using a command like fsck -n /dev/devnamea It should be remembered that all files containing control information must be relative to the root filesystem in the Vinum volume which, when setting up a new Vinum root volume, might not match the root filesystem that is currently active. So in particular, the files /etc/fstab and /boot/loader.conf need to be taken care of. At next reboot, the bootstrap should figure out the appropriate control information from the new Vinum-based root filesystem, and act accordingly. At the end of the kernel initialization process, after all devices have been announced, the prominent notice that shows the success of this setup is a message like: Mounting root from ufs:/dev/vinum/root Example of a Vinum-based Root Setup After the Vinum root volume has been set up, the output of vinum l -rv root could look like: ... Subdisk root.p0.s0: Size: 125829120 bytes (120 MB) State: up Plex root.p0 at offset 0 (0 B) Drive disk0 (/dev/da0h) at offset 135680 (132 kB) Subdisk root.p1.s0: Size: 125829120 bytes (120 MB) State: up Plex root.p1 at offset 0 (0 B) Drive disk1 (/dev/da1h) at offset 135680 (132 kB) The values to note are 135680 for the offset (relative to partition /dev/da0h). This translates to 265 512-byte disk blocks in disklabel's terms. Likewise, the size of this root volume is 245760 512-byte blocks. /dev/da1h, containing the second replica of this root volume, has a symmetric setup. The disklabel for these devices might look like: ... 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*) c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*) h: 71771672 16 vinum # (Cyl. 0*- 4467*) It can be observed that the "size" parameter for the faked "a" partition matches the value outlined above, while the "offset" parameter is the sum of the offset within the Vinum partition "h", and the offset of this partition within the device (or slice). This is a typical setup that is necessary to avoid the problem described in . It can also be seen that the entire "a" partition is completely within the "h" partition containing all the Vinum data for this device. Note that in the above example, the entire device is dedicated to Vinum, and there is no leftover pre-Vinum root partition, since this has been a newly set-up disk that was only meant to be part of a Vinum configuration, ever. Troubleshooting If something goes wrong, a way is needed to recover from the situation. The following list contains few known pitfalls and solutions. System Bootstrap Loads, but System Does Not Boot If for any reason the system does not continue to boot, the bootstrap can be interrupted with by pressing the space key at the 10-seconds warning. The loader variables (like vinum.autostart) can be examined using the show, and manipulated using set or unset commands. If the only problem was that the Vinum kernel module was not yet in the list of modules to load automatically, a simple load vinum will help. When ready, the boot process can be continued with a boot -as. The options will request the kernel to ask for the root filesystem to mount (), and make the boot process stop in single-user mode (), where the root filesystem is mounted read-only. That way, even if only one plex of a multi-plex volume has been mounted, no data inconsistency between plexes is being risked. At the prompt asking for a root filesystem to mount, any device that contains a valid root filesystem can be entered. If /etc/fstab had been set up correctly, the default should be something like ufs:/dev/vinum/root. A typical alternate choice would be something like ufs:da0d which could be a hypothetical partition that contains the pre-Vinum root filesystem. Care should be taken if one of the alias "a" partitions are entered here that are actually reference to the subdisks of the Vinum root device, because in a mirrored setup, this would only mount one piece of a mirrored root device. If this filesystem is to be mounted read-write later on, it is necessary to remove the other plex(es) of the Vinum root volume since these plexes would otherwise carry inconsistent data. Only Primary Bootstrap Loads If /boot/loader fails to load, but the primary bootstrap still loads (visible by a single dash in the left column of the screen right after the boot process starts), an attempt can be made to interrupt the primary bootstrap at this point, using the space key. This will make the bootstrap stop in stage two, see . An attempt can be made here to boot off an alternate partition, like the partition containing the previous root filesystem that has been moved away from "a" above. Nothing Boots, the Bootstrap Panics This situation will happen if the bootstrap had been destroyed by the Vinum installation. Unfortunately, Vinum accidentally currently leaves only 4 KB at the beginning of its partition free before starting to write its Vinum header information. However, the stage one and two bootstraps plus the disklabel embedded between them currently require 8 KB. So if a Vinum partition was started at offset 0 within a slice or disk that was meant to be bootable, the Vinum setup will trash the bootstrap. Similarly, if the above situation has been recovered, for example by booting from a Fixit medium, and the bootstrap has been re-installed using disklabel -B as described in , the bootstrap will trash the Vinum header, and Vinum will no longer find its disk(s). Though no actual Vinum configuration data or data in Vinum volumes will be trashed by this, and it would be possible to recover all the data by entering exact the same Vinum configuration data again, the situation is hard to fix at all. It would be necessary to move the entire Vinum partition by at least 4 KB off, in order to have the Vinum header and the system bootstrap no longer collide. Differences for FreeBSD 4.x Under FreeBSD 4.x, some internal functions required to make Vinum automatically scan all disks are missing, and the code that figures out the internal ID of the root device is not smart enough to handle a name like /dev/vinum/root automatically. Therefore, things are a little different here. Vinum must explicitly be told which disks to scan, using a line like the following one in /boot/loader.conf: vinum.drives="/dev/da0 /dev/da1" It is important that all drives are mentioned that could possibly contain Vinum data. It does not harm if more drives are listed, nor is it necessary to add each slice and/or partition explicitly, since Vinum will scan all slices and partitions of the named drives for valid Vinum headers. Since the routines used to parse the name of the root filesystem, and derive the device ID (major/minor number) are only prepared to handle classical device names like /dev/ad0s1a, they cannot make any sense out of a root volume name like /dev/vinum/root. For that reason, Vinum itself needs to pre-setup the internal kernel parameter that holds the ID of the root device during its own initialization. This is requested by passing the name of the root volume in the loader variable vinum.root. The entry in /boot/loader.conf to accomplish this looks like: vinum.root="root" Now, when the kernel initialization tries to find out the root device to mount, it sees whether some kernel module has already pre-initialized the kernel parameter for it. If that is the case, and the device claiming the root device matches the major number of the driver as figured out from the name of the root device string being passed (that is, "vinum" in our case), it will use the pre-allocated device ID, instead of trying to figure out one itself. That way, during the usual automatic startup, it can continue to mount the Vinum root volume for the root filesystem. However, when boot -a has been requesting to ask for entering the name of the root device manually, it must be noted that this routine still cannot actually parse a name entered there that refers to a Vinum volume. If any device name is entered that does not refer to a Vinum device, the mismatch between the major numbers of the pre-allocated root parameter and the driver as figured out from the given name will make this routine enter its normal parser, so entering a string like ufs:da0d will work as expected. Note that if this fails, it is however no longer possible to re-enter a string like ufs:vinum/root again, since it cannot be parsed. The only way out is to reboot again, and start over then. (At the askroot prompt, the initial /dev/ can always be omitted.)