diff --git a/en_US.ISO8859-1/articles/5-roadmap/article.sgml b/en_US.ISO8859-1/articles/5-roadmap/article.sgml index 41ff26fda3..26f2c82f11 100644 --- a/en_US.ISO8859-1/articles/5-roadmap/article.sgml +++ b/en_US.ISO8859-1/articles/5-roadmap/article.sgml @@ -1,660 +1,644 @@ -%man; - - -%freebsd; - - -%authors; - - -%teams; - - -%mailing-lists; - - -%trademarks; + +%articles.ent; RELENG_3"> RELENG_4"> RELENG_5"> RELENG_5_1"> RELENG_5_2"> RELENG_5_3"> HEAD"> - ]>
The Road Map for 5-STABLE The &os; Release Engineering Team $FreeBSD$ 2003 The &os; Release Engineering Team &tm-attrib.freebsd; &tm-attrib.ieee; &tm-attrib.intel; &tm-attrib.sparc; &tm-attrib.sun; &tm-attrib.opengroup; &tm-attrib.general; Introduction and Background After nearly three years of work, &os; 5.0 was released in January of 2003. Features like the GEOM block layer, Mandatory Access Controls, ACPI, &sparc64; and ia64 platform support, and UFS snapshots, background filesystem checks, and 64-bit inode sizes make it an exciting operating system for both desktop and enterprise users. However, some important features are not complete. The foundations for fine-grained locking and preemption in the kernel exist, but much more work is left to be done. Performance and stability compared to &os; 4.X has declined and must be restored and surpassed. This is somewhat similar to the situation that &os; faced in the 3.X series. Work on 3-CURRENT trudged along seemingly forever, and finally a cry was made to just ship it and clean up later. This decision resulted in the 3.0 and 3.1 releases being very unsatisfying for most, and it wasn't until 3.2 that the series was considered stable. To make matters worse, the &t.releng.3; branch was created along with the 3.0 release, and the &t.releng.head; branch was allowed to advance immediately towards 4-CURRENT. This resulted in a quick divergence between &t.releng.head; and &t.releng.3;, making maintenance of the &t.releng.3; branch very difficult. &os; 2.2.8 was left for quite a while as the last production-quality version of &os;. Our intent is to avoid repeating that scenario with &os; 5.x. Delaying the &t.releng.5; branch until it is stable and production quality will ensure that it stays maintainable and provides a compelling reason to upgrade from 4.X. To do this, we must identify the current areas of weakness and set clear goals for resolving them. This document contains what we as the release engineering team feel are the milestones and issues that must be resolved for the &t.releng.5; branch. It does not dictate every aspect of &os; development, and we welcome further input. Nothing that follows is meant to be a sleight against any person or group, or to trivialize any work that has been done. There are some significant issues, though, that need decisive and unbiased action. Major issues The success of the 5.X series hinges on the ability to deliver fine-grained threading and re-entrancy in the kernel (also known as SMPng) and kernel-supported POSIX threads in userland, while not sacrificing overall system stability or performance. SMPng The state of SMPng and kernel lockdown is the biggest concern for 5.X. To date, few major systems have come out from under the kernel-wide mutex known as Giant. The SMP status page at provides a comprehensive breakdown of the overall SMPng status. Status specific to SMPng progress in device drivers can be found at at . In summary: VM: Kernel malloc is locked and free of Giant. The UMA zone allocator is also free of Giant. vm_object locking is in progress and is an important step to making the buffer/cache free of Giant. Pmap locking remains to be started. GEOM: The GEOM block layer was designed to run free of Giant and allow GEOM modules and underlying block drivers to run free of Giant. Currently, only the &man.ata.4; and &man.aac.4; drivers are locked and run without Giant. Work on other block drivers is in progress. Locking the CAM subsystem is required for nearly all SCSI drivers to run without Giant; this work has not started yet. Additionally, GEOM has the potential to suffer performance loss due to its upcall and downcall data paths happening in kernel threads. Improved lightweight context switches might help this. Network: Work has restarted on locking the network stack. Routing tables, ARP, bridge, IPFW, Fast-Forward, TCP, UDP, IP, Fast IPSEC, and interface layers are being targeted initially, along with several Ethernet device drivers. The socket layer, IPv6, and other protocol layers will be targeted later. The primary goal of this work is to regain the performance found in &os; 4.X. The cost of context switching to the device driver ithreads and the netisr is still hampering performance. VFS: Initial pre-cleanup started. buffer/cache: Initial work complete on locking the buffer. Proc: Initial proc locking is in place, further progress is expected for &os; 5.2. CAM: No significant work has occurred on the CAM SCSI layer. Newbus: some work has started on locking down the device_t structure. Pipes: complete File descriptors: complete. Process accounting: jails, credentials, MAC labels, and scheduler are out from under Giant. MAC Framework: complete Timekeeping: complete kernel encryption: crypto drivers and core &man.crypto.4; framework are Giant-free. KAME IPsec has not been locked. Sound subsystem: complete, but lock order reversal problems seem to persist. kernel preemption: preemption for interrupt threads is enabled. However, contention due to Giant covering much of the kernel and most of the device driver interrupt routines causes excessive context switches and might actually be hurting performance. Work is underway to explore ways to make preemption be conditional. Interrupt latency and servicing SMPng introduced the concept of dedicating kernel threads, known as ithreads, to servicing interrupts. With this, driver interrupt service routines are allowed to block for mutexes, memory allocations, etc. While this makes writing drivers easier, it introduces considerable latency into the system due to the complete process context switch must be performed in order to service the ithread. This is aggravated by the extensive coverage over the kernel by the Giant mutex, and often results in multiple sleeps and context switches in order to service an interrupt. Drivers that register their interrupt as INTR_MPSAFE are less likely to feel these aggravating effects, but the overhead of doing a context switch remains. Interrupt service routines that are registered as INTR_FAST are run directly from the interrupt context and do not suffer these problems at all. However, the INTR_FAST property forces the interrupt line to be exclusive; no sharing can occur on it. The proliferation of shared interrupts on PC systems makes this undesirable. Several ideas have been proposed to help combat this problem: Special casing ithreads to be lightweight is a possibility. This might involve reducing the amount of saved context for the ithread, stack-borrowing from another kthread, and/or creating a new fast-path to avoid the mi_switch() routine. A new interrupt model can be introduced to allow drivers to register an 'interrupt filter' along with a normal service routine. This would be similar to the Mac OS X model in use today. Interrupt filter routines would allow the driver to determine if it is interested in servicing the interrupt, allow it to squelch the interrupt source, and possibly determine and schedule service actions. It would run in the same context as the low-level interrupt service routine, so sleeping would be strictly forbidden. If actions that result in sleeping or blocking for long periods are required, the filter would signal to the caller that its normal ithread routine should be scheduled. Kernel-supported application threads The FreeBSD 5.1 development cycle saw the KSE package jump into a highly usable state. THR, an alternate threading package based on some of the KSE kernel primitives but implementing purely 1:1 scheduling semantics also appeared and is in a similarly experimental but usable state. Users may interchange these two libraries along with the legacy libc_r library via relinking their apps or by using the new libmap feature of the runtime linker. This excellent progress must be driven to completion before the &t.releng.5; branch point so that the libc_r package can be deprecated. The kernel and userland components for KSE and THR must be completed for all Tier-1 platforms. The decision on which thread package to sanction as the default will likely be made on a per-platform basis depending on the stability and completeness of each package. KSE Status Platform Kernel Userland Works? i386 YES YES YES alpha NO YES NO sparc64 YES NO NO ia64 YES YES YES amd64 YES YES YES
THR Status Platform Kernel Userland Works? i386 YES YES YES alpha YES YES YES sparc64 YES YES NO ia64 YES YES YES amd64 NO NO NO
KSE must pass the ACE test suite on all Tier-1 platforms. Additional real-world testing must also be performed to ensure that the libraries are indeed useful. At a minimum, the following packages should be tested: OpenOffice KDE Desktop Apache 2.x BIND 9.2.x MySQL &java; 1.4.x Requirements for 5-STABLE The &t.releng.5 branch must offer users the same stability and performance that is currently enjoyed in the &t.releng.4 branch. While the goal of SMPng is to allow performance to far exceed what is found in &t.releng.4; and its siblings BSD's, regaining performance to the basic level is of the utmost importance. The branch must also be mature enough to avoid ABI and API changes while still allowing potential problems to be resolved. ABI/API/Infrastructure stability Enough infrastructure must be in place and stable to allow fixes from &t.releng.head; to easily and safely be merged into &t.releng.5;. Also, we must draw a line as to what subsystems are to be locked down when we go into 5-STABLE. KSE: Both kernel and userland components must reach the same level of functionality for all Tier-1 platforms in both UP and SMP configurations. The definition of Tier-1 platforms can be found in . Continued testing against the ACE test suite must be made as the &t.releng.5; branch draws near. KSE must pose no functional regressions for the ongoing &java; certification program. Common desktop and server applications must run seamlessly under KSE. A policy must be decided on as to which platforms will enable KSE as the default threading package, how to allow the user to switch threading packages, and how third-party packages will be made aware of these choices. busdma interface and drivers: architectures like PAE/&i386; and sparc64 which don't have a direct mapping between host memory address space and expansion bus address space require the elimination for vtophys() and friends. The busdma interface was created to handle exactly this problem, but many drivers do not use it yet. The busdma project at tracks the progress of this and should be used to determine which drivers must be converted for &t.releng.5; and which can be left behind. No new storage or network drivers shall be allowed into the &os; source tree. Exceptions for other classes of drivers must be justified in public discussion. PCI resource allocation: PC2003 compliance requires that x86 systems no longer configure PCI devices from the system BIOS, leaving this task solely to the OS. &os; must gain the ability to manage and allocate PCI memory resources on its own. Implementing this should take into account cardbus, PCI-HotPlug, and laptop dock station requirements. This feature will become increasingly critical through the lifetime of &t.releng.5;, and therefore is a requirement for the &t.releng.5; branch. Performance Performance hinges on the progress of SMPng infrastructure and the following areas: Storage: The GEOM block layer allows storage drivers to run without Giant. All drivers that interface directly with GEOM (as opposed to sitting underneath CAM or another middleware) must be locked and free of Giant in both their strategy and completion paths. Their interrupt handlers must also run free of Giant. Network: The layers in the IPv4 path below the socket layer must be locked and free of Giant. This includes the protocol, routing, bridging, filtering, and hardware layers. Allowances must be made for protocols that are not locked, especially IPv6. Testing must also be performed to ensure stability, correctness, and performance. Interrupt and context switching: As discussed above, interrupt latency and context switching have a severe impact of performance. Context switching for ithreads and kthreads must be improved on platforms. New interrupt handling models that allow for faster more flexible handling of both traditional and MSI interrupts must be investigated and implemented. Benchmarks and performance testing Having a source of reliable and useful benchmarks is essential to identifying performance problems and guarding against performance regressions. A performance team that is made up of people and resources for formulating, developing, and executing benchmark tests should be put into place soon. Comparisons should be made against both &os; 4.X and Linux 2.4/2.6. Tests to consider are: the classic worldstone webstone: www/webstone Fstress: ApacheBench: www/p5-ApacheBench netperf: benchmarks/netperf Web Polygraph: Note: does not compile with gcc 3.x yet. Features: NEWCARD/OLDCARD: The NEWCARD subsystem was made the default for &os; 5.0. Unfortunately, it contains no support for non-Cardbus bridges and falls victim to interrupt routing problems on some laptops. The classic 16-bit bridge support, OLDCARD, still exists and can be compiled in, but this is highly inconvenient for users of older laptops. If OLDCARD cannot be completely deprecated for &t.releng.5;, then provisions must be made to allow users to easily install an OLDCARD-enabled kernel. Documentation should be written to help transition users from OLDCARD to NEWCARD and from &man.pccardd.8; to &man.devd.8;. The power management and dumpcis functionality of &man.pccardc.8; needs to be brought forward to work with NEWCARD, along with the ability to load CIS quirk entries. Most of this functionality can be integrated into &man.devd.8; and &man.devctl.4;. New scheduler framework: The new scheduler framework is in place, and users can select between the classic 44BSD scheduler and the new ULE scheduler. A scheduler that demonstrates processor affinity, HyperThreading and KSE awareness, and no regressions in performance or interactivity characteristics must be available for &t.releng.5;. GDB: GDB in the base system must work for sparc64, and must also understand KSE thread semantics. GDB 5.3 is available and is reported to address the sparc64 issues. Documentation: The manual pages, Handbook, and FAQ should be free from content specific to &os; 4.X, i.e. all text should be equally applicable to &os; 5.X. The installation section of the handbook needs the most work in this area. The release documentation needs to be complete and accurate for all Tier-1 architectures. The hardware notes and installation guides need specific attention. Schedule The original schedule of releasing &os; 5.2 and branching &t.releng.5; in September 2003 is being pushed back due to the complexity of the remaining tasks. The new schedule follows: Nov 18, 2003: 5.2-BETA, general code freeze Dec 6, 2003: 5.2-RC1, &t.releng.5.2; branched Dec 9, 2003: 5.2-RC2 Dec 16, 2003: 5.2-RELEASE Mar 1, 2004: 5.3-BETA, general code freeze Mar 15, 2004: 5.3-RC1, &t.releng.5; and &t.releng.5.3; branched Mar 22, 2004: 5.3-RC2 Mar 29, 2004: 5.3-RELEASE Post &t.releng.5; direction The focus should be bug fixes and incremental improvements, as with all the -STABLE development branches. Following the usual procedure, everything should be vetted through the &t.releng.head; branch first and committed to &t.releng.5; with caution. New device drivers, incremental features, etc, will be welcome in the branch once they have been tested in &t.releng.head; and found stable enough. Further SMPng lockdowns will be divided into two categories: driver and subsystem. The only subsystem that will be sufficiently locked down for &t.releng.5; will be GEOM, so incrementally locking down device drivers under it is a worthy goal for the branch. Full subsystem lockdowns will have to be fully tested and proven in &t.releng.head; before consideration will be given to merging them into &t.releng.5;.
diff --git a/en_US.ISO8859-1/articles/checkpoint/article.sgml b/en_US.ISO8859-1/articles/checkpoint/article.sgml index 662ff7cb2e..4d95533a2c 100644 --- a/en_US.ISO8859-1/articles/checkpoint/article.sgml +++ b/en_US.ISO8859-1/articles/checkpoint/article.sgml @@ -1,438 +1,435 @@ -%man; + +%articles.ent; - - -%trademarks; ]>
Integration of Check Point <trademark class='registered'>VPN-1</trademark>/<trademark class='registered'>Firewall-1</trademark> and FreeBSD IPsec Jon Orbeton
jono@securityreports.com
 Matt Hite
mhite@hotmail.com
 $FreeBSD$ 2001, 2002, 2003 Jon Orbeton &legalnotice; &tm-attrib.freebsd; &tm-attrib.check-point; &tm-attrib.general; This document explains how to configure a VPN tunnel between FreeBSD and Check Point's VPN-1/ Firewall-1. Other documents provide similar information, but do not contain instructions specific to VPN-1/Firewall-1 and its integration with FreeBSD. These documents are listed at the conclusion of this paper for further reference. Prerequisites The following is a diagram of the machines and networks referenced in this document. External Interface External Interface 208.229.100.6 216.218.197.2 | | +--> Firewall-1 <--> Internet <--> FreeBSD GW <--+ | | FW-1 Protected Nets Internal Nets 199.208.192.0/24 192.168.10.0/24 FW-1 net and FreeBSD net The FreeBSD gateway GW serves as a firewall and NAT device for internal nets. The FreeBSD kernel must be compiled to support IPsec. Use the following kernel options to enable IPsec support in your kernel: options IPSEC options IPSEC_ESP options IPSEC_DEBUG For instructions on building a custom kernel, refer to the FreeBSD handbook. Please note that IP protocol 50 (ESP) and UDP port 500 must be open between the Firewall-1 host and the FreeBSD GW. Also, racoon must be installed to support key exchange. Racoon is part of the FreeBSD ports collection in security/racoon. The racoon configuration file will be covered later in this document. Firewall-1 Network Object Configuration Begin by configuring the Firewall-1 Policy. Open the Policy Editor on the Firewall-1 Management server and create a new Workstation Network Object representing FreeBSD GW. General Tab: Set name and IP address VPN Tab: Encryption Schemes Defined: IKE ---> Edit IKE Properties: Key Negotiation Encryption Methods: 3DES Authentication Method: Pre-Shared Secret ---> Edit Select the Firewall Object and set a pre-shared secret. (Do not use our example.) Support Aggressive Mode: Checked Supports Subnets: Checked After setting the pre-shared secret in the Firewall-1 Network Object definition, place this secret in the /usr/local/etc/racoon/psk.txt file on FreeBSD GW. The format for psk.txt is: 208.229.100.6 rUac0wtoo? Firewall-1 VPN Rule Configuration Next, create a Firewall-1 rule enabling encryption between the FreeBSD GW and the Firewall-1 protected network. In this rule, the network services permitted through the VPN must be defined. Source | Destination | Service | Action | Track ------------------------------------------------------------------------ FreeBSD GW | FW-1 Protected Net | VPN services | Encrypt | Long FW-1 Protected Net| FreeBSD GW | | | VPN services are any services (i.e. telnet, SSH, NTP, etc.) which remote hosts are permitted to access through the VPN. Use caution when permitting services; hosts connecting through a VPN still represent a potential security risk. Encrypting the traffic between the two networks offers little protection if a host on either side of the tunnel has been compromised. Once the rule specifying data encryption between the FreeBSD GW and the Firewall-1 protected network has been configured, review the Action Encrypt settings. Encryption Schemes Defined: IKE ---> Edit Transform: Encryption + Data Integrity (ESP) Encryption Algorithm: 3DES Data Integrity: MD5 Allowed Peer Gateway: Any or Firewall Object Use Perfect Forward Secrecy: Checked The use of Perfect Forward Secrecy (PFS) is optional. Enabling PFS will add another layer of encryption security, but does come at the cost of increased CPU overhead. If PFS is not used, uncheck the box above and comment out the pfs_group 1 line in the racoon.conf file on FreeBSD GW. An example racoon.conf file is provided later in this document. FreeBSD <acronym>VPN</acronym> Policy Configuration At this point, the VPN policy on FreeBSD GW must be defined. The &man.setkey.8; tool performs this function. Below is an example shell script which will flush &man.setkey.8; and add your VPN policy rules. # # /etc/vpn1-ipsec.sh # # IP addresses # # External Interface External Interface # 208.229.100.6 216.218.197.2 # | | # +--> Firewall-1 <--> Internet <--> FreeBSD GW <--+ # | | # FW-1 Protected Nets Internal Nets # 199.208.192.0/24 192.168.10.0/24 # # Flush the policy # setkey -FP setkey -F # # Configure the Policy # setkey -c << END spdadd 216.218.197.2/32 199.208.192.0/24 any -P out ipsec esp/tunnel/216.218.197.2-208.229.100.6/require; spdadd 199.208.192.0/24 216.218.197.2/32 any -P in ipsec esp/tunnel/208.229.100.6-216.218.197.2/require; END # Execute the &man.setkey.8; commands: &prompt.root; sh /etc/vpn1-ipsec.sh FreeBSD <application>Racoon</application> Configuration To facilitate the negotiation of IPsec keys on the FreeBSD GW, the security/racoon port must be installed and configured. The following is a racoon configuration file suitable for use with the examples outlined in this document. Please make sure you fully understand this file before using it in a production environment. # racoon.conf for use with Check Point VPN-1/Firewall-1 # # search this file for pre_shared_key with various ID key. # path pre_shared_key "/usr/local/etc/racoon/psk.txt" ; log debug; # # "padding" defines some parameter of padding. You should not touch these. # padding { maximum_length 20; # maximum padding length. randomize off; # enable randomize length. strict_check off; # enable strict check. exclusive_tail off; # extract last one octet. } listen { #isakmp ::1 [7000]; #isakmp 0.0.0.0 [500]; #admin [7002]; # administrative port by kmpstat. #strict_address; # required all addresses must be bound. } # # Specification of default various timers. # timer { # # These values can be changed per remote node. # counter 5; # maximum trying count to send. interval 20 sec; # maximum interval to resend. persend 1; # the number of packets per a send. # # timer for waiting to complete each phase. # phase1 30 sec; phase2 15 sec; } remote anonymous { exchange_mode aggressive,main; # For Firewall-1 Aggressive mode #my_identifier address; #my_identifier user_fqdn ""; #my_identifier address ""; #peers_identifier address ""; #certificate_type x509 "" ""; nonce_size 16; lifetime time 10 min; # sec,min,hour lifetime byte 5 MB; # B,KB,GB initial_contact on; support_mip6 on; proposal_check obey; # obey, strict or claim proposal { encryption_algorithm 3des; hash_algorithm md5; authentication_method pre_shared_key; dh_group 2 ; } } sainfo anonymous { pfs_group 1; lifetime time 10 min; lifetime byte 50000 KB; encryption_algorithm 3des; authentication_algorithm hmac_md5; compression_algorithm deflate ; } Ensure that the /usr/local/etc/racoon/psk.txt file contains the pre-shared secret configured in the Firewall-1 Network Object Configuration section of this document and has mode 600 permissions. &prompt.root; chmod 600 /usr/local/etc/racoon/psk.txt Starting the <acronym>VPN</acronym> You are now ready to launch racoon and test the VPN tunnel. For debugging purposes, open the Firewall-1 Log Viewer and define a log filter to isolate entries pertaining to FreeBSD GW. You may also find it helpful to &man.tail.1; the racoon log: &prompt.root; tail -f /var/log/racoon.log Start racoon using the following command: &prompt.root; /usr/local/sbin/racoon -f /usr/local/etc/racoon/racoon.conf Once racoon has been launched, &man.telnet.1; to a host on the Firewall-1 protected network. &prompt.root; telnet -s 192.168.10.3 199.208.192.66 22 This command attempts to connect to the &man.ssh.1; port on 199.208.192.66, a machine in the Firewall-1 protected network. The switch indicates the source interface of the outbound connection. This is particularly important when running NAT and IPFW on FreeBSD GW. Using -s and specifying an explicit source address prevents NAT from mangling the packet prior to tunneling. A successful racoon key exchange will output the following to the racoon.log log file: pfkey UPDATE succeeded: ESP/Tunnel 216.218.197.2->208.229.100.6 pk_recvupdate(): IPSec-SA established: ESP/Tunnel 216.218.197.2->208.229.100.6 get pfkey ADD message IPsec-SA established: ESP/Tunnel 208.229.100.6->216.218.197.2 Once key exchange completes (which takes a few seconds), an &man.ssh.1; banner will appear. If all went well, two Key Install messages will be logged in the Firewall-1 Log Viewer. Action | Source | Dest. | Info. Key Install | 216.218.197.2 | 208.229.100.6 | IKE Log: Phase 1 (aggressive) completion. Key Install | 216.218.197.2 | 208.229.100.6 | scheme: IKE methods Under the information column, the full log detail will read: IKE Log: Phase 1 (aggressive) completion. 3DES/MD5/Pre shared secrets Negotiation Id: scheme: IKE methods: Combined ESP: 3DES + MD5 + PFS (phase 2 completion) for host: References The FreeBSD Handbook: VPN over IPsec. KAME Project. FreeBSD IPsec mini-HOWTO.
diff --git a/en_US.ISO8859-1/articles/committers-guide/article.sgml b/en_US.ISO8859-1/articles/committers-guide/article.sgml index ac3ef5246f..1cc7043e53 100644 --- a/en_US.ISO8859-1/articles/committers-guide/article.sgml +++ b/en_US.ISO8859-1/articles/committers-guide/article.sgml @@ -1,3199 +1,3181 @@ -%man; - - -%freebsd; - - -%authors; - - -%teams; - - -%mailing-lists; - - -%trademarks; - - -%urls; + +%articles.ent; ]>
Committer's Guide The FreeBSD Documentation Project $FreeBSD$ 1999 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.ibm; &tm-attrib.intel; &tm-attrib.sparc; &tm-attrib.general; This document provides information for the FreeBSD committer community. All new committers should read this document before they start, and existing committers are strongly encouraged to review it from time to time. Administrative Details Main Repository Host ncvs.FreeBSD.org Login Methods &man.ssh.1;, protocol 2 only Main CVSROOT ncvs.FreeBSD.org:/home/ncvs (although also see ). Main &a.cvs; &a.peter; and &a.markm;, as well as &a.joe; and &a.marcus; for ports/ Mailing Lists &a.doc-developers;, &a.doc-committers;; &a.ports-developers;, &a.ports-committers;; &a.src-developers;, &a.src-committers;. (Each project repository has its own -developers and -committers mailing lists. Archives for these lists may be found in files /home/mail/repository-name-developers-archive and /home/mail/repository-name-committers-archive on the FreeBSD.org cluster.) Core Team monthly reports /home/core/public/monthly-report on the FreeBSD.org cluster. Noteworthy CVS Tags RELENG_4 (4.X-STABLE), HEAD (-CURRENT) It is required that you use &man.ssh.1; or &man.telnet.1; with Kerberos 5 to connect to the project hosts. For &man.ssh.1; only protocol 2 is allowed. These are generally more secure than plain &man.telnet.1; or &man.rlogin.1; since credential negotiation will always be encrypted. All traffic is encrypted by default with &man.ssh.1;. With utilities like &man.ssh-agent.1; and &man.scp.1; also available, &man.ssh.1; is also far more convenient. If you do not know anything about &man.ssh.1;, please see . Commit Bit Types The FreeBSD CVS repository has a number of components which, when combined, support the basic operating system source, documentation, third party application ports infrastructure, and various maintained utilities. When FreeBSD commit bits are allocated, the areas of the tree where the bit may be used are specified. Generally, the areas associated with a bit reflect who authorized the allocation of the commit bit. Additional areas of authority may be added at a later date: when this occurs, the committer should follow normal commit bit allocation procedures for that area of the tree, seeking approval from the appropriate entity and possibly getting a mentor for that area for some period of time. Committer Type Responsible Tree Components src core@ src/, doc/ subject to appropriate review doc doceng@ doc/, www/, src/ documentation ports portmgr@ ports/ Commit bits allocated prior to the development of the notion of areas of authority may be appropriate for use in many parts of the tree. However, common sense dictates that a committer who has not previously worked in an area of the tree seek review prior to committing, seek approval from the appropriate responsible party, and/or work with a mentor. Since the rules regarding code maintenance differ by area of the tree, this is as much for the benefit of the committer working in an area of less familiarity as it is for others working on the tree. Committers are encouraged to seek review for their work as part of the normal development process, regardless of the area of the tree where the work is occurring. Policy for <filename>doc/</filename> committer activity in <filename>src/</filename> doc committers may commit documentation changes to src files, such as man pages, READMEs, fortune databases, calendar files, and comment fixes without approval from a src committer, subject to the normal care and tending of commits. doc committers may commit minor src changes and fixes, such as build fixes, small features, etc, with an "Approved by" from a src committer. doc committers may seek an upgrade to a src commit bit by acquiring a mentor, who will propose the doc committer to core. When approved, they will be added to 'access' and the normal mentoring period will ensue, which will involve a continuing of Approved by for some period. "Approved by" is only acceptable from non-mentored src committers -- mentored committers can provide a "Reviewed by" but not an "Approved by". CVS Operations It is assumed that you are already familiar with the basic operation of CVS. The &a.cvs; are the owners of the CVS repository and are responsible for direct modification of it for the purposes of cleanup or fixing some grievous abuse of CVS by a committer. Should you cause some repository accident, say a bad cvs import or cvs tag operation, mail the &a.cvs; (or call one of them) and report the problem to one of them. The only ones able to directly fiddle the repository bits on the repository hosts are the repomeisters. To enforce this, there are no login shells available on the repository machines, except to the repomeisters. The CVS tree is currently split into four distinct repositories, namely doc, ports, projects and src. These are combined under a single CVSROOT when distributed via CVSup for the convenience of our users. Note that the www module containing sources for the FreeBSD website is contained within the doc repository. The CVS repositories are hosted on the repository machines. Currently, each of the repositories above reside on the same physical machine, ncvs.FreeBSD.org, but to allow for the possibility of placing each on a separate machine in the future, there is a separate hostname for each that committers should use. Additionally, each repository is stored in a separate directory. The following table summarizes the situation. &os; CVS Repositories, Hosts and Directories Repository Host Directory doc dcvs.FreeBSD.org /home/dcvs ports pcvs.FreeBSD.org /home/pcvs projects projcvs.FreeBSD.org /home/projcvs src ncvs.FreeBSD.org /home/ncvs
CVS operations are done remotely by setting the CVSROOT environment variable to the appropriate host and top-level directory (for example, ncvs.FreeBSD.org:/home/ncvs), the CVS_RSH variable to ssh, and then doing the appropriate check-out/check-in operations. Many committers define aliases which expand to the correct cvs invocation for the appropriate repository. For example, a &man.tcsh.1; user may add the following to their .cshrc for this purpose: alias dcvs env CVS_RSH=ssh cvs -d user@dcvs.FreeBSD.org:/home/dcvs alias pcvs env CVS_RSH=ssh cvs -d user@pcvs.FreeBSD.org:/home/pcvs alias projcvs env CVS_RSH=ssh cvs -d user@projcvs.FreeBSD.org:/home/projcvs alias scvs env CVS_RSH=ssh cvs -d user@ncvs.FreeBSD.org:/home/ncvs This way they can do all CVS operations locally and use Xcvs commit for committing to the official CVS tree. If you wish to add something which is wholly new (like contrib-ified sources, etc), cvs import should be used. Refer to the &man.cvs.1; manual page for usage. Please do not use cvs checkout or update with the official repository machine set as the CVS Root for keeping your source tree up to date. Remote CVS is not optimized for network distribution and requires a big work/administrative overhead on the server side. Please use our advanced cvsup distribution method for obtaining the repository bits, and only do the actual commit operation on the repository host. We provide an extensive cvsup replication network for this purpose, as well as give access to cvsup-master if you really need to stay current to the latest changes. cvsup-master has got the horsepower to deal with this, the repository master server does not. &a.kuriyama; is in charge of cvsup-master. If you need to use CVS add and delete operations in a manner that is effectively a &man.mv.1; operation, then a repository copy is in order rather than using CVS add and delete. In a repository copy, a CVS Meister will copy the file(s) to their new name and/or location and let you know when it is done. The purpose of a repository copy is to preserve file change history, or logs. We in the FreeBSD Project greatly value the change history that CVS gives to the project. CVS reference information, tutorials, and FAQs can be found at: . The information in Karl Fogel's chapters from Open Source Development with CVS is also very useful. &a.des; also supplied the following mini primer for CVS. Check out a module with the co or checkout command. &prompt.user; cvs checkout shazam This checks out a copy of the shazam module. If there is no shazam module in the modules file, it looks for a top-level directory named shazam instead. Useful <command>cvs checkout</command> options Do not create empty directories Check out a single level, no subdirectories Check out revision, branch or tag rev Check out the sources as they were on date date
Practical FreeBSD examples: Check out the miscfs module, which corresponds to src/sys/miscfs: &prompt.user; cvs co miscfs You now have a directory named miscfs with subdirectories CVS, deadfs, devfs, and so on. One of these (linprocfs) is empty. Check out the same files, but with full path: &prompt.user; cvs co src/sys/miscfs You now have a directory named src, with subdirectories CVS and sys. The src/sys directory has subdirectories CVS and miscfs, etc. Check out the same files, but prunes empty directories: &prompt.user; cvs co -P miscfs You now have a directory named miscfs with subdirectories CVS, deadfs, devfs... but note that there is no linprocfs subdirectory, because there are no files in it. Check out the directory miscfs, but none of the subdirectories: &prompt.user; cvs co -l miscfs You now have a directory named miscfs with just one subdirectory named CVS. Check out the miscfs module as it is in the 4.X branch: &prompt.user; cvs co -rRELENG_4 miscfs You can modify the sources and commit along this branch. Check out the miscfs module as it was in 3.4-RELEASE. &prompt.user; cvs co -rRELENG_3_4_0_RELEASE miscfs You will not be able to commit modifications, since RELENG_3_4_0_RELEASE is a point in time, not a branch. Check out the miscfs module as it was on Jan 15 2000. &prompt.user; cvs co -D'01/15/2000' miscfs You will not be able to commit modifications. Check out the miscfs module as it was one week ago. &prompt.user; cvs co -D'last week' miscfs You will not be able to commit modifications. Note that cvs stores metadata in subdirectories named CVS. Arguments to and are sticky, which means cvs will remember them later, e.g. when you do a cvs update. Check the status of checked-out files with the status command. &prompt.user; cvs status shazam This displays the status of the file shazam or of every file in the shazam directory. For every file, the status is given as one of: Up-to-date File is up-to-date and unmodified. Needs Patch File is unmodified, but there is a newer revision in the repository. Locally Modified File is up-to-date, but modified. Needs Merge File is modified, and there is a newer revision in the repository. File had conflicts on merge There were conflicts the last time this file was updated, and they have not been resolved yet. You will also see the local revision and date, the revision number of the newest applicable version (newest applicable because if you have a sticky date, tag or branch, it may not be the actual newest revision), and any sticky tags, dates or options. Once you have checked something out, you can update it with the update command. &prompt.user; cvs update shazam This updates the file shazam or the contents of the shazam directory to the latest version along the branch you checked out. If you checked out a point in time, does nothing unless the tags have moved in the repository or some other weird stuff is going on. Useful options, in addition to those listed above for checkout: Check out any additional missing directories. Update to head of main branch. More magic (see below). If you checked out a module with or , running cvs update with a different or argument or with will select a new branch, revision or date. The option clears all sticky tags, dates or revisions whereas and set new ones. Theoretically, specifying HEAD as the argument to will give you the same result as , but that is just theory. The option is useful if: somebody has added subdirectories to the module you have checked out after you checked it out. you checked out with , and later change your mind and want to check out the subdirectories as well. you deleted some subdirectories and want to check them all back out. Watch the output of the cvs update with care. The letter in front of each filename indicates what was done with it: U The file was updated without trouble. P The file was updated without trouble (you will only see this when working against a remote repository). M The file had been modified, and was merged without conflicts. C The file had been modified, and was merged with conflicts. Merging is what happens if you check out a copy of some source code, modify it, then someone else commits a change, and you run cvs update. CVS notices that you have made local changes, and tries to merge your changes with the changes between the version you originally checked out and the one you updated to. If the changes are to separate portions of the file, it will almost always work fine (though the result might not be syntactically or semantically correct). CVS will print an M in front of every locally modified file even if there is no newer version in the repository, so cvs update is handy for getting a summary of what you have changed locally. If you get a C, then your changes conflicted with the changes in the repository (the changes were to the same lines, or neighboring lines, or you changed the local file so much that cvs can not figure out how to apply the repository's changes). You will have to go through the file manually and resolve the conflicts; they will be marked with rows of <, = and > signs. For every conflict, there will be a marker line with seven < signs and the name of the file, followed by a chunk of what your local file contained, followed by a separator line with seven = signs, followed by the corresponding chunk in the repository version, followed by a marker line with seven > signs and the revision number you updated to. The option is slightly voodoo. It updates the local file to the specified revision as if you used , but it does not change the recorded revision number or branch of the local file. It is not really useful except when used twice, in which case it will merge the changes between the two specified versions into the working copy. For instance, say you commit a change to shazam/shazam.c in &os.current; and later want to MFC it. The change you want to MFC was revision 1.15: Check out the &os.stable; version of the shazam module: &prompt.user; cvs co -rRELENG_4 shazam Apply the changes between rev 1.14 and 1.15: &prompt.user; cvs update -j1.14 -j1.15 shazam/shazam.c You will almost certainly get a conflict because - of the $Id: article.sgml,v 1.206 2004-08-08 10:01:19 blackend Exp $ (or in FreeBSD's case, + of the $Id: article.sgml,v 1.207 2004-08-08 13:43:53 hrs Exp $ (or in FreeBSD's case, $FreeBSD$) lines, so you will have to edit the file to resolve the conflict - (remove the marker lines and the second $Id: article.sgml,v 1.206 2004-08-08 10:01:19 blackend Exp $ line, - leaving the original $Id: article.sgml,v 1.206 2004-08-08 10:01:19 blackend Exp $ line intact). + (remove the marker lines and the second $Id: article.sgml,v 1.207 2004-08-08 13:43:53 hrs Exp $ line, + leaving the original $Id: article.sgml,v 1.207 2004-08-08 13:43:53 hrs Exp $ line intact). View differences between the local version and the repository version with the diff command. &prompt.user; cvs diff shazam shows you every modification you have made to the shazam file or module. Useful <command>cvs diff</command> options Uses the unified diff format. Uses the context diff format. Shows missing or added files.
You always want to use , since unified diffs are much easier to read than almost any other diff format (in some circumstances, context diffs generated with the option may be better, but they are much bulkier). A unified diff consists of a series of hunks. Each hunk begins with a line that starts with two @ signs and specifies where in the file the differences are and how many lines they span. This is followed by a number of lines; some (preceded by a blank) are context; some (preceded by a - sign) are outtakes and some (preceded by a +) are additions. You can also diff against a different version than the one you checked out by specifying a version with or as in checkout or update, or even view the diffs between two arbitrary versions (without regard for what you have locally) by specifying two versions with or . View log entries with the log command. &prompt.user; cvs log shazam If shazam is a file, this will print a header with information about this file, such as where in the repository this file is stored, which revision is the HEAD for this file, what branches this file is in, and any tags that are valid for this file. Then, for each revision of this file, a log message is printed. This includes the date and time of the commit, who did the commit, how many lines were added and/or deleted, and finally the log message that the committer who did the change wrote. If shazam is a directory, then the log information described above is printed for each file in the directory in turn. Unless you give the to log, the log for all subdirectories of shazam is printed too, in a recursive manner. Use the log command to view the history of one or more files, as it is stored in the CVS repository. You can even use it to view the log message of a specific revision, if you add the to the log command: &prompt.user; cvs log -r1.2 shazam This will print only the log message for revision 1.2 of file shazam if it is a file, or the log message for revision 1.2 of each file under shazam if it is a directory. See who did what with the annotate command. This command shows you each line of the specified file or files, along with which user most recently changed that line. &prompt.user; cvs annotate shazam Add new files with the add command. Create the file, cvs add it, then cvs commit it. Similarly, you can add new directories by creating them and then cvs adding them. Note that you do not need to commit directories. Remove obsolete files with the remove command. Remove the file, then cvs rm it, then cvs commit it. Commit with the commit or checkin command. Useful <command>cvs commit</command> options Force a commit of an unmodified file. Specify a commit message on the command line rather than invoking an editor.
Use the option if you realize that you left out important information from the commit message. Good commit messages are important. They tell others why you did the changes you did, not just right here and now, but months or years from now when someone wonders why some seemingly illogical or inefficient piece of code snuck into your source file. It is also an invaluable aid to deciding which changes to MFC and which not to MFC. Commit messages should be clear, concise and provide a reasonable summary to give an indication of what was changed and why. Commit messages should provide enough information to enable a third party to decide if the change is relevant to them and if they need to read the change itself. Avoid committing several unrelated changes in one go. It makes merging difficult, and also makes it harder to determine which change is the culprit if a bug crops up. Avoid committing style or whitespace fixes and functionality fixes in one go. It makes merging difficult, and also makes it harder to understand just what functional changes were made. In the case of documentation files, it can make the job of the translation teams more complicated, as it becomes difficult for them to determine exactly what content changes need to be translated. Avoid committing changes to multiple files in one go with a generic, vague message. Instead, commit each file (or small, related groups of files) with tailored commit messages. Before committing, always: verify which branch you are committing to, using cvs status. review your diffs, using cvs diff Also, ALWAYS specify which files to commit explicitly on the command line, so you do not accidentally commit other files than the ones you intended - cvs commit without any arguments will commit every modification in your current working directory and every subdirectory. Additional tips and tricks: You can place commonly used options in your ~/.cvsrc, like this: cvs -z3 diff -Nu update -Pd checkout -P This example says: always use compression level 3 when talking to a remote server. This is a life-saver when working over a slow connection. always use the (show added or removed files) and (unified diff format) options to &man.diff.1;. always use the (prune empty directories) and (check out new directories) options when updating. always use the (prune empty directories) option when checking out. Use Eivind Eklund's cdiff script to view unidiffs. It is a wrapper for &man.less.1; that adds ANSI color codes to make hunk headers, outtakes and additions stand out; context and garbage are unmodified. It also expands tabs properly (tabs often look wrong in diffs because of the extra character in front of each line). Simply use it instead of &man.more.1; or &man.less.1;: &prompt.user; cvs diff -Nu shazam | cdiff Alternatively some editors like &man.vim.1; (editors/vim5) have color support and when used as a pager with color syntax highlighting switched on will highlight many types of file, including diffs, patches, and CVS/RCS logs. &prompt.user; echo "syn on" >> ~/.vimrc &prompt.user; cvs diff -Nu shazam | vim - &prompt.user; cvs log shazam | vim - CVS is old, arcane, crufty and buggy, and sometimes exhibits non-deterministic behavior which some claim as proof that it is actually merely the Newtonian manifestation of a sentient transdimensional entity. It is not humanly possible to know its every quirk inside out, so do not be afraid to ask the resident AI (&a.cvs;) for help. Do not leave the cvs commit command in commit message editing mode for too long (more than 2–3 minutes). It locks the directory you are working with and will prevent other developers from committing into the same directory. If you have to type a long commit message, type it before executing cvs commit, and insert it into the commit message. Conventions and Traditions As a new committer there are a number of things you should do first. Add your author entity to doc/en_US.ISO8859-1/share/sgml/authors.ent; this should be done first since an omission of this commit will cause the next commits to break the doc/ build. This is a relatively easy task, but remains a good first test of your CVS skills. Add yourself to the Developers section of the Contributors List and remove yourself from the Additional Contributors section. Add an entry for yourself to www/en/news/news.xml. Look for the other entries that look like A new committer and follow the format. You should add your PGP or GnuPG key to doc/share/pgpkeys (and if you do not have a key, you should create one). Do not forget to commit the updated doc/share/pgpkeys/pgpkeys.ent. &a.des; has written a shell script to make this extremely simple. See the README file for more information. It is important to have an up-to-date PGP/GnuPG key in the Handbook, since the key may be required for positive identification of a committer, e.g. by the &a.admins; for account recovery. A complete keyring of FreeBSD.org users is available for download from http://www.FreeBSD.org/doc/pgpkeyring.txt. Some people add an entry for themselves to ports/astro/xearth/files/freebsd.committers.markers. Some people add an entry for themselves to src/usr.bin/calendar/calendars/calendar.freebsd. Introduce yourself to the other committers, otherwise no one will have any idea who you are or what you are working on. You do not have to write a comprehensive biography, just write a paragraph or two about who you are and what you plan to be working on as a committer in FreeBSD. Email this to the &a.developers; and you will be on your way! Log into hub.FreeBSD.org and create a /var/forward/user (where user is your username) file containing the e-mail address where you want mail addressed to yourusername@FreeBSD.org to be forwarded. This includes all of the commit messages as well as any other mail addressed to the &a.committers; and the &a.developers;. Really large mailboxes which have taken up permanent residence on hub often get accidentally truncated without warning, so forward it or read it and you will not lose it. Due to the severe load dealing with SPAM places on the central mail servers that do the mailing list processing the front-end server does do some basic checks and will drop some messages based on these checks. At the moment proper DNS information for the connecting host is the only check in place but that may change. Some people blame these checks for bouncing valid email. If you want these checks turned off for your email you can place a file named ~/.spam_lover in your home directory on freefall.FreeBSD.org to disable the checks for your email. If you are subscribed to the &a.cvsall;, you will probably want to unsubscribe to avoid receiving duplicate copies of commit messages and their followups. All new committers also have a mentor assigned to them for the first few months. Your mentor is responsible for teaching you the rules and conventions of the project and guiding your first steps in the committer community. He or she is also personally responsible for your actions during this initial period. Until your mentor decides (and announces with a forced commit to access) that you have learned the ropes and are ready to commit on your own, you should not commit anything without first getting your mentor's review and approval, and you should document that approval with an Approved by: line in the commit message. All src commits should go to &os.current; first before being merged to &os.stable;. No major new features or high-risk modifications should be made to the &os.stable; branch. Preferred License for New Files Currently the &os; Project suggests and uses the following text as the preferred license scheme: Copyright © <Year> <Author>. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The &os; project strongly discourages the so called advertising clause in new code. Due to the large number of contributors to the &os; project, complying with this clause for many commercial vendors has become difficult. If you have code in the tree with the advertising clause, please consider removing it. In fact, please consider using the above license for your code. The &os; project discourages completely new licenses and variations on the standard licenses. New licenses require the approval of core@FreeBSD.org to reside in the main repository. The more different licenses that are used in the tree, the more problems that this causes to those wishing to utilize this code, typically from unintended consequences from a poorly worded license. Developer Relations If you are working directly on your own code or on code which is already well established as your responsibility, then there is probably little need to check with other committers before jumping in with a commit. If you see a bug in an area of the system which is clearly orphaned (and there are a few such areas, to our shame), the same applies. If, however, you are about to modify something which is clearly being actively maintained by someone else (and it is only by watching the cvs-committers mailing list that you can really get a feel for just what is and is not) then consider sending the change to them instead, just as you would have before becoming a committer. For ports, you should contact the listed MAINTAINER in the Makefile. For other parts of the repository, if you are unsure who the active maintainer might be, it may help to scan the output of cvs log to see who has committed changes in the past. &a.fenner; has written a nice shell script that can help determine who the active maintainer might be. It lists each person who has committed to a given file along with the number of commits each person has made. It can be found on freefall at ~fenner/bin/whodid. If your queries go unanswered or the committer otherwise indicates a lack of proprietary interest in the area affected, go ahead and commit it. If you are unsure about a commit for any reason at all, have it reviewed by -hackers before committing. Better to have it flamed then and there rather than when it is part of the CVS repository. If you do happen to commit something which results in controversy erupting, you may also wish to consider backing the change out again until the matter is settled. Remember – with CVS we can always change it back. Do not impugn the intentions of someone you disagree with. If they see a different solution to a problem than you, or even a different problem, it is not because they are stupid, because they have questionable parentage, or because they are trying to destroy your hard work, personal image, or FreeBSD, but simply because they have a different outlook on the world. Different is good. Disagree honestly. Argue your position from its merits, be honest about any shortcomings it may have, and be open to seeing their solution, or even their vision of the problem, with an open mind. Accept correction. We are all fallible. When you have made a mistake, apologize and get on with life. Do not beat up yourself, and certainly do not beat up others for your mistake. Do not waste time on embarrassment or recrimination, just fix the problem and move on. Ask for help. Seek out (and give) peer reviews. One of the ways open source software is supposed to excel is in the number of eyeballs applied to it; this does not apply if nobody will review code. GNATS The FreeBSD Project utilizes GNATS for tracking bugs and change requests. Be sure that if you commit a fix or suggestion found in a GNATS PR, you use edit-pr pr-number on freefall to close it. It is also considered nice if you take time to close any PRs associated with your commits, if appropriate. You can also make use of &man.send-pr.1; yourself for proposing any change which you feel should probably be made, pending a more extensive peer-review first. You can find out more about GNATS at: http://www.FreeBSD.org/support.html &man.send-pr.1; You can run a local copy of GNATS, and then integrate the FreeBSD GNATS tree in to it using CVSup. Then you can run GNATS commands locally, or use other interfaces, such as tkgnats. This lets you query the PR database without needing to be connected to the Internet. Using a local GNATS tree If you are not already downloading the GNATS tree, add this line to your supfile, and re-sup. Note that since GNATS is not under CVS control it has no tag, so if you are adding it to your existing supfile it should appear before any tag= entry as these remain active once set. gnats release=current prefix=/usr This will place the FreeBSD GNATS tree in /usr/gnats. You can use a refuse file to control which categories to receive. For example, to only receive docs PRs, put this line in /usr/local/etc/cvsup/sup/refuse The precise path depends on the *default base setting in your supfile. . gnats/[a-ce-z]* The rest of these examples assume you have only supped the docs category. Adjust them as necessary, depending on the categories you are syncing. Install the GNATS port from ports/databases/gnats. This will place the various GNATS directories under $PREFIX/share/gnats. Symlink the GNATS directories you are supping under the version of GNATS you have installed. &prompt.root; cd /usr/local/share/gnats/gnats-db &prompt.root; ln -s /usr/gnats/docs Repeat as necessary, depending on how many GNATS categories you are syncing. Update the GNATS categories file with these categories. The file is $PREFIX/share/gnats/gnats-db/gnats-adm/categories. # This category is mandatory pending:Category for faulty PRs:gnats-admin: # # FreeBSD categories # docs:Documentation Bug:freebsd-doc: Run $PREFIX/libexec/gnats/gen-index to recreate the GNATS index. The output has to be redirected to $PREFIX/share/gnats/gnats-db/gnats-adm/index. You can do this periodically from &man.cron.8;, or run &man.cvsup.1; from a shell script that does this as well. &prompt.root; /usr/local/libexec/gnats/gen-index \ > /usr/local/share/gnats/gnats-db/gnats-adm/index Test the configuration by querying the PR database. This command shows open docs PRs. &prompt.root; query-pr -c docs -s open Other interfaces, such as that provided by the databases/tkgnats port should also work nicely. Pick a PR and close it. This procedure only works to allow you to view and query the PRs locally. To edit or close them you will still have to log in to freefall and do it from there. Who's Who Besides the repository meisters, there are other FreeBSD project members and teams whom you will probably get to know in your role as a committer. Briefly, and by no means all-inclusively, these are: &a.jhb; John is the manager of the SMPng Project, and has authority over the architectural design and implementation of the move to fine-grained kernel threading and locking. He's also the editor of the SMPng Architecture Document. If you are working on fine-grained SMP and locking, please coordinate with John. You can learn more about the SMPng Project on its home page: &a.jake;, &a.tmm; Jake and Thomas are the maintainers of the &sparc64; hardware port. &a.doceng; doceng is the group responsible for the documentation build infrastructure, approving new documentation committers, and ensuring that the FreeBSD website and documentation on the FTP site is up to date with respect to the CVS tree. It is not a conflict resolution body. The vast majority of documentation related discussion takes place on the &a.doc;. More details regarding the doceng team can be found in its charter. Committers interested in contributing to the documentation should familiarize themselves with the Documentation Project Primer. &a.ru; Ruslan is Mister &man.mdoc.7;. If you are writing a manual page and need some advice on the structure, or the markup, ask Ruslan. &a.bde; Bruce is the Style Police-Meister. When you do a commit that could have been done better, Bruce will be there to tell you. Be thankful that someone is. Bruce is also very knowledgeable on the various standards applicable to FreeBSD. &a.gallatin; &a.mjacob; &a.dfr; &a.obrien; These are the primary developers and overseers of the DEC Alpha AXP platform. &a.dg; David is the overseer of the VM system. If you have a VM system change in mind, coordinate it with David. &a.dfr; &a.marcel; &a.peter; &a.ps; These are the primary developers and overseers of the Intel IA-64 platform, officially known as the &itanium; Processor Family (IPF). &a.murray; &a.steve; &a.rwatson; &a.jhb; &a.scottl; &a.kensmith; &a.hrs; These are the members of the &a.re;. This team is responsible for setting release deadlines and controlling the release process. During code freezes, the release engineers have final authority on all changes to the system for whichever branch is pending release status. If there is something you want merged from &os.current; to &os.stable; (whatever values those may have at any given time), these are the people to talk to about it. Hiroki is also the keeper of the release documentation (src/release/doc/*). If you commit a change that you think is worthy of mention in the release notes, please make sure he knows about it. Better still, send him a patch with your suggested commentary. &a.benno; Benno is the official maintainer of the &powerpc; port. &a.brian; Official maintainer of /usr/sbin/ppp. &a.nectar; Jacques is the FreeBSD Security Officer and oversees the &a.security-officer;. &a.wollman; If you need advice on obscure network internals or are not sure of some potential change to the networking subsystem you have in mind, Garrett is someone to talk to. Garrett is also very knowledgeable on the various standards applicable to FreeBSD. &a.committers; cvs-committers is the entity that CVS uses to send you all your commit messages. You should never send email directly to this list. You should only send replies to this list when they are short and are directly related to a commit. &a.developers; All committers are subscribed to -developers. This list was created to be a forum for the committers community issues. Examples are Core voting, announcements, etc. This list is not intended as a place for code reviews or a replacement for the &a.arch; or the &a.audit;. In fact using it as such hurts the FreeBSD Project as it gives a sense of a closed list where general decisions affecting all of the FreeBSD using community are made without being open. Last, but not least never, never ever, email the &a.developers; and CC:/BCC: another FreeBSD list. Never, ever email another FreeBSD email list and CC:/BCC: the &a.developers;. Doing so can greatly diminish the benefits of this list. Also, never publicly post or forward emails sent to the &a.developers;. The act of sending to the &a.developers; vs. a public list means the information in the email is not for public consumption. SSH Quick-Start Guide If you are using FreeBSD 4.0 or later, OpenSSH is included in the base system. If you are using an earlier release, update and install one of the SSH ports. In general, you will probably want to get OpenSSH from the security/openssh port. You may also wish to check out the original ssh1 in the security/ssh port, but make certain you pay attention to its license. Note that both of these ports cannot be installed at the same time. If you do not wish to type your password in every time you use &man.ssh.1;, and you use RSA or DSA keys to authenticate, &man.ssh-agent.1; is there for your convenience. If you want to use &man.ssh-agent.1;, make sure that you run it before running other applications. X users, for example, usually do this from their .xsession or .xinitrc file. See &man.ssh-agent.1; for details. Generate a key pair using &man.ssh-keygen.1;. The key pair will wind up in your $HOME/.ssh/ directory. Send your public key ($HOME/.ssh/id_dsa.pub or $HOME/.ssh/id_rsa.pub) to the person setting you up as a committer so it can be put into yourlogin file in /c/ssh-keys/ on freefall. Now you should be able to use &man.ssh-add.1; for authentication once per session. This will prompt you for your private key's pass phrase, and then store it in your authentication agent (&man.ssh-agent.1;). If you no longer wish to have your key stored in the agent, issuing ssh-add -d will remove it. Test by doing something such as ssh freefall.FreeBSD.org ls /usr. For more information, see security/openssh, &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and &man.scp.1;. The FreeBSD Committers' Big List of Rules Respect other committers. Respect other contributors. Discuss any significant change before committing. Respect existing maintainers (if listed in the MAINTAINER field in Makefile or in the MAINTAINER file in the top-level directory). Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion. Changes go to &os.current; before &os.stable; unless specifically permitted by the release engineer or unless they are not applicable to &os.current;. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in &os.current; for at least 3 days before merging so that it can be given sufficient testing. The release engineer has the same authority over the &os.stable; branch as outlined for the maintainer in rule #5. Do not fight in public with other committers; it looks bad. If you must strongly disagree about something, do so only in private. Respect all code freezes and read the committers and developers mailing lists in a timely manner so you know when a code freeze is in effect. When in doubt on any procedure, ask first! Test your changes before committing them. Do not commit to anything under the src/contrib, src/crypto, and src/sys/contrib trees without explicit approval from the respective maintainer(s). As noted, breaking some of these rules can be grounds for suspension or, upon repeated offense, permanent removal of commit privileges. Individual members of core have the power to temporarily suspend commit privileges until core as a whole has the chance to review the issue. In case of an emergency (a committer doing damage to the repository), a temporary suspension may also be done by the repository meisters. Only a 2/3 majority of core has the authority to suspend commit privileges for longer than a week or to remove them permanently. This rule does not exist to set core up as a bunch of cruel dictators who can dispose of committers as casually as empty soda cans, but to give the project a kind of safety fuse. If someone is out of control, it is important to be able to deal with this immediately rather than be paralyzed by debate. In all cases, a committer whose privileges are suspended or revoked is entitled to a hearing by core, the total duration of the suspension being determined at that time. A committer whose privileges are suspended may also request a review of the decision after 30 days and every 30 days thereafter (unless the total suspension period is less than 30 days). A committer whose privileges have been revoked entirely may request a review after a period of 6 months has elapsed. This review policy is strictly informal and, in all cases, core reserves the right to either act on or disregard requests for review if they feel their original decision to be the right one. In all other aspects of project operation, core is a subset of committers and is bound by the same rules. Just because someone is in core this does not mean that they have special dispensation to step outside any of the lines painted here; core's special powers only kick in when it acts as a group, not on an individual basis. As individuals, the core team members are all committers first and core second. Details Respect other committers. This means that you need to treat other committers as the peer-group developers that they are. Despite our occasional attempts to prove the contrary, one does not get to be a committer by being stupid and nothing rankles more than being treated that way by one of your peers. Whether we always feel respect for one another or not (and everyone has off days), we still have to treat other committers with respect at all times, on public forums and in private email. Being able to work together long term is this project's greatest asset, one far more important than any set of changes to the code, and turning arguments about code into issues that affect our long-term ability to work harmoniously together is just not worth the trade-off by any conceivable stretch of the imagination. To comply with this rule, do not send email when you are angry or otherwise behave in a manner which is likely to strike others as needlessly confrontational. First calm down, then think about how to communicate in the most effective fashion for convincing the other person(s) that your side of the argument is correct, do not just blow off some steam so you can feel better in the short term at the cost of a long-term flame war. Not only is this very bad energy economics, but repeated displays of public aggression which impair our ability to work well together will be dealt with severely by the project leadership and may result in suspension or termination of your commit privileges. The project leadership will take into account both public and private communications brought before it. It will not seek the disclosure of private communications, but it will take it into account if it is volunteered by the committers involved in the complaint. All of this is never an option which the project's leadership enjoys in the slightest, but unity comes first. No amount of code or good advice is worth trading that away. Respect other contributors. You were not always a committer. At one time you were a contributor. Remember that at all times. Remember what it was like trying to get help and attention. Do not forget that your work as a contributor was very important to you. Remember what it was like. Do not discourage, belittle, or demean contributors. Treat them with respect. They are our committers in waiting. They are every bit as important to the project as committers. Their contributions are as valid and as important as your own. After all, you made many contributions before you became a committer. Always remember that. Consider the points raised under and apply them also to contributors. Discuss any significant change before committing. The CVS repository is not where changes should be initially submitted for correctness or argued over, that should happen first in the mailing lists and the commit should only happen once something resembling consensus has been reached. This does not mean that you have to ask permission before correcting every obvious syntax error or manual page misspelling, simply that you should try to develop a feel for when a proposed change is not quite such a no-brainer and requires some feedback first. People really do not mind sweeping changes if the result is something clearly better than what they had before, they just do not like being surprised by those changes. The very best way of making sure that you are on the right track is to have your code reviewed by one or more other committers. When in doubt, ask for review! Respect existing maintainers if listed. Many parts of FreeBSD are not owned in the sense that any specific individual will jump up and yell if you commit a change to their area, but it still pays to check first. One convention we use is to put a maintainer line in the Makefile for any package or subtree which is being actively maintained by one or more people; see for documentation on this. Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other maintainer. In cases where the maintainer-ship of something is not clear, you can also look at the CVS logs for the file(s) in question and see if someone has been working recently or predominantly in that area. Other areas of FreeBSD fall under the control of someone who manages an overall category of FreeBSD evolution, such as internationalization or networking. See http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-who.html for more information on this. Any disputed change must be backed out pending resolution of the dispute if requested by a maintainer. Security related changes may override a maintainer's wishes at the Security Officer's discretion. This may be hard to swallow in times of conflict (when each side is convinced that they are in the right, of course) but CVS makes it unnecessary to have an ongoing dispute raging when it is far easier to simply reverse the disputed change, get everyone calmed down again and then try to figure out what is the best way to proceed. If the change turns out to be the best thing after all, it can be easily brought back. If it turns out not to be, then the users did not have to live with the bogus change in the tree while everyone was busily debating its merits. People very very rarely call for back-outs in the repository since discussion generally exposes bad or controversial changes before the commit even happens, but on such rare occasions the back-out should be done without argument so that we can get immediately on to the topic of figuring out whether it was bogus or not. Changes go to &os.current; before &os.stable; unless specifically permitted by the release engineer or unless they are not applicable to &os.current;. Any non-trivial or non-urgent change which is applicable should also be allowed to sit in &os.current; for at least 3 days before merging so that it can be given sufficient testing. The release engineer has the same authority over the &os.stable; branch as outlined in rule #5. This is another do not argue about it issue since it is the release engineer who is ultimately responsible (and gets beaten up) if a change turns out to be bad. Please respect this and give the release engineer your full cooperation when it comes to the &os.stable; branch. The management of &os.stable; may frequently seem to be overly conservative to the casual observer, but also bear in mind the fact that conservatism is supposed to be the hallmark of &os.stable; and different rules apply there than in &os.current;. There is also really no point in having &os.current; be a testing ground if changes are merged over to &os.stable; immediately. Changes need a chance to be tested by the &os.current; developers, so allow some time to elapse before merging unless the &os.stable; fix is critical, time sensitive or so obvious as to make further testing unnecessary (spelling fixes to manual pages, obvious bug/typo fixes, etc.) In other words, apply common sense. Changes to the security branches (for example, RELENG_4_5) must be approved by a member of the &a.security-officer;, or in some cases, by a member of the &a.re;. Do not fight in public with other committers; it looks bad. If you must strongly disagree about something, do so only in private. This project has a public image to uphold and that image is very important to all of us, especially if we are to continue to attract new members. There will be occasions when, despite everyone's very best attempts at self-control, tempers are lost and angry words are exchanged. The best thing that can be done in such cases is to minimize the effects of this until everyone has cooled back down. That means that you should not air your angry words in public and you should not forward private correspondence to public mailing lists or aliases. What people say one-to-one is often much less sugar-coated than what they would say in public, and such communications therefore have no place there - they only serve to inflame an already bad situation. If the person sending you a flame-o-gram at least had the grace to send it privately, then have the grace to keep it private yourself. If you feel you are being unfairly treated by another developer, and it is causing you anguish, bring the matter up with core rather than taking it public. Core will do its best to play peace makers and get things back to sanity. In cases where the dispute involves a change to the codebase and the participants do not appear to be reaching an amicable agreement, core may appoint a mutually-agreeable 3rd party to resolve the dispute. All parties involved must then agree to be bound by the decision reached by this 3rd party. Respect all code freezes and read the committers and developers mailing list on a timely basis so you know when a code freeze is in effect. Committing unapproved changes during a code freeze is a really big mistake and committers are expected to keep up-to-date on what is going on before jumping in after a long absence and committing 10 megabytes worth of accumulated stuff. People who abuse this on a regular basis will have their commit privileges suspended until they get back from the FreeBSD Happy Reeducation Camp we run in Greenland. When in doubt on any procedure, ask first! Many mistakes are made because someone is in a hurry and just assumes they know the right way of doing something. If you have not done it before, chances are good that you do not actually know the way we do things and really need to ask first or you are going to completely embarrass yourself in public. There is no shame in asking how in the heck do I do this? We already know you are an intelligent person; otherwise, you would not be a committer. Test your changes before committing them. This may sound obvious, but if it really were so obvious then we probably would not see so many cases of people clearly not doing this. If your changes are to the kernel, make sure you can still compile both GENERIC and LINT. If your changes are anywhere else, make sure you can still make world. If your changes are to a branch, make sure your testing occurs with a machine which is running that code. If you have a change which also may break another architecture, be sure and test on all supported architectures. Please refer to the FreeBSD Internal Page for a list of available resources. As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available. Do not commit to anything under the src/contrib, src/crypto, and src/sys/contrib trees without explicit approval from the respective maintainer(s). The trees mentioned above are for contributed software usually imported onto a vendor branch. Committing something there, even if it does not take the file off the vendor branch, may cause unnecessary headaches for those responsible for maintaining that particular piece of software. Thus, unless you have explicit approval from the maintainer (or you are the maintainer), do not commit there! Please note that this does not mean you should not try to improve the software in question; you are still more than welcome to do so. Ideally, you should submit your patches to the vendor. If your changes are FreeBSD-specific, talk to the maintainer; they may be willing to apply them locally. But whatever you do, do not commit there by yourself! Contact the &a.core; if you wish to take up maintainership of an unmaintained part of the tree. Policy on Multiple Architectures FreeBSD has added several new arch ports during the 5.0 release cycle and is truly no longer an &i386; centric operating system. In an effort to make it easier to keep FreeBSD portable across the platforms we support, core has developed the following mandate:
Our 32 bit reference platform is i386, and our 64 bit reference platform is Sparc64. Major design work (including major API and ABI changes) must prove itself on at least one 32 bit and at least one 64 bit platform, preferably the primary reference platforms, before it may be committed to the source tree.
The i386 and Sparc64 platforms were chosen due to being more readily available to developers and as representatives of more diverse processor and system designs - big vs little endian, register file vs register stack, different DMA and cache implementations, hardware page tables vs software TLB management etc. While the Alpha is a 64 bit processor, it is a more traditional processor design and does not provide as good a testbed for many of the challenges that the other 64 bit platform ports face. The ia64 platform has many of the same complications that Sparc64 has, but is still limited in availability to developers. We will continue to re-evaluate this policy as cost and availability of the 64 bit platforms change. Developers should also be aware of our Tier Policy for the long term support of hardware architectures. The rules here are intended to provide guidance during the development process, and are distinct from the requirements for features and architectures listed in that section. The Tier rules for feature support on architectures at release-time are more strict than the rules for changes during the development process. Other Suggestions When committing documentation changes, use a spell checker before committing. For all SGML docs, you should also verify that your formatting directives are correct by running make lint. For all on-line manual pages, run manck (from ports) over the manual page to verify all of the cross references and file references are correct and that the man page has all of the appropriate MLINKs installed. Do not mix style fixes with new functionality. A style fix is any change which does not modify the functionality of the code. Mixing the changes obfuscates the functionality change when using cvs diff, which can hide any new bugs. Do not include whitespace changes with content changes in commits to doc/ or www/. The extra clutter in the diffs makes the translators' job much more difficult. Instead, make any style or whitespace changes in separate commits that are clearly labeled as such in the commit message. Deprecating Features When it is necessary to remove functionality from software in the base system the following guidelines should be followed whenever possible: Mention is made in the manual page and possibly the release notes that the option, utility, or interface is deprecated. Use of the deprecated feature generates a warning. The option, utility, or interface is preserved until the next major (point zero) release. The option, utility, or interface is removed and no longer documented. It is now obsolete. It is also generally a good idea to note its removal in the release notes. Support for Multiple Architectures FreeBSD is a highly portable operating system intended to function on many different types of hardware architectures. Maintaining clean separation of Machine Dependent (MD) and Machine Independent (MI) code, as well as minimizing MD code, is an important part of our strategy to remain agile with regards to current hardware trends. Each new hardware architecture supported by FreeBSD adds substantially to the cost of code maintenance, toolchain support, and release engineering. It also dramatically increases the cost of effective testing of kernel changes. As such, there is strong motivation to differentiate between classes of support for various architectures while remaining strong in a few key architectures that are seen as the FreeBSD "target audience". Statement of General Intent The FreeBSD Project targets "production quality commercial off-the-shelf (COTS) workstation, server, and high-end embedded systems". By retaining a focus on a narrow set of architectures of interest in these environments, the FreeBSD Project is able to maintain high levels of quality, stability, and performance, as well as minimize the load on various support teams on the project, such as the ports team, documentation team, security officer, and release engineering teams. Diversity in hardware support broadens the options for FreeBSD consumers by offering new features and usage opportunities (such as support for 64-bit CPUs, use in embedded environments, etc.), but these benefits must always be carefully considered in terms of the real-world maintenance cost associated with additional platform support. The FreeBSD Project differentiates platform targets into four tiers. Each tier includes a specification of the requirements for an architecture to be in that tier, as well as specifying the obligations of developers with regards to the platform. In addition, a policy is defined regarding the circumstances required to change the tier of an architecture. Tier 1: Fully Supported Architectures Tier 1 platforms are fully supported by the security officer, release engineering, and toolchain maintenance staff. New features added to the operating system must be fully functional across all Tier 1 architectures for every release (features which are inherently architecture-specific, such as support for hardware device drivers, may be exempt from this requirement). In general, all Tier 1 platforms must have build and tinderbox support either in the FreeBSD.org cluster, or easily available for all developers. Tier 1 architectures are expected to be Production Quality with respects to all aspects of the FreeBSD operating system, including installation and development environments. Current Tier 1 platforms are i386, Sparc64, AMD64, and PC98. Tier 2: Developmental Architectures Tier 2 platforms are not supported by the security officer and release engineering teams. At the discretion of the toolchain maintainer, they may be supported in the toolchain. New features added to FreeBSD should be feasible to implement on these platforms, but an implementation is not required before the feature may be added to the FreeBSD source tree. The implementation of a Tier 2 architecture may be committed to the main FreeBSD tree as long as it does not interfere with production work on Tier 1 platforms, or substantially with other Tier 2 platforms. Before a Tier 2 platform can be added to the FreeBSD base source tree, the platform must be able to boot to at least single-user mode on real world commodity hardware. Some exceptions to these rules may be made for new hardware that is under development by hardware vendors, but not yet available to the project. Tier 2 architectures are usually systems targeted at Tier 1 support, but that are still under development. Architectures reaching end of life may also be moved from Tier 1 status to Tier 2 status as the availability of resources to continue to maintain the system in a Production Quality state diminishes. Current Tier 2 platforms are Alpha, PowerPC and ia64. Tier 3: Experimental Architectures Tier 3 platforms are not supported by the security officer and release engineering teams. At the discretion of the toolchain maintainer, they may be supported in the toolchain. Tier 3 platforms are architectures for which hardware is not or will not be available to the project in the foreseeable future, for which there are two or fewer active developers, that can not boot to at least single-user mode on real hardware (or a simulator for new hardware platforms), or which are considered legacy systems unlikely to see broad future use. Tier 3 systems will not be committed to the base source tree, although support for Tier 3 systems may be worked on in the FreeBSD Perforce Repository, providing source control and easier change integration from the main FreeBSD tree. Current Tier 3 platforms are &s390;. Tier 4: Unsupported Architectures Tier 4 systems are not supported in any form by the project. All systems not otherwise classified into a support tier are Tier 4 systems. Policy on Changing the Tier of an Architecture Systems may only be moved from one tier to another by approval of the FreeBSD Core Team, which shall make that decision in collaboration with the Security Officer, Release Engineering, and toolchain maintenance teams. Ports Specific FAQ Adding a New Port How do I add a new port? First, please read the section about repository copies. The easiest way to add a new port is to use the addport script on freefall. It will add a port from the directory you specify, determining the category automatically from the port Makefile. It will also add an entry to the CVSROOT/modules file and the port's category Makefile. It was written by &a.mharo; and &a.will;, but Will is the current maintainer so please send questions/patches about addport to him. Any other things I need to know when I add a new port? Check the port, preferably to make sure it compiles and packages correctly. This is the recommended sequence: &prompt.root; make install &prompt.root; make package &prompt.root; make deinstall &prompt.root; pkg_add package you built above &prompt.root; make deinstall &prompt.root; make reinstall &prompt.root; make package The Porters Handbook contains more detailed instructions. Use &man.portlint.1; to check the syntax of the port. You do not necessarily have to eliminate all warnings but make sure you have fixed the simple ones. If the port came from a submitter who has not contributed to the project before, add that person's name to the Additional Contributors section of the FreeBSD Contributors List. Close the PR if the port came in as a PR. To close a PR, just do edit-pr PR# on freefall and change the state from open to closed. You will be asked to enter a log message and then you are done. Repository Copies When do we need a repository copy? When you want to add a port that is related to any port that is already in the tree in a separate directory, you have to do a repository copy. Here related means it is a different version or a slightly modified version. Examples are print/ghostscript* (different versions) and x11-wm/windowmaker* (English-only and internationalized version). Another example is when a port is moved from one subdirectory to another, or when you want to change the name of a directory because the author(s) renamed their software even though it is a descendant of a port already in a tree. When do we not need a repository copy? When there is no history to preserve. If a port is added into a wrong category and is moved immediately, it suffices to simply cvs remove the old one and addport the new one. What do I need to do? File a PR in GNATS, listing the reasons for the repository copy request. Assign it to portmgr and set state to repocopy. If &a.portmgr; approves it, it will be reassigned to cvs. &a.cvs; will do a repository copy from the old to the new location, and reassign the PR back to you. Once everything is done, perform the following: When a port has been repo copied: Upgrade the copied port to the new version (remember to change the PORTNAME so there are not duplicate ports with the same name). Add the new subdirectory to the SUBDIR listing in the parent directory Makefile. You can run make checksubdirs in the parent directory to check this. If the port changed categories, modify the CATEGORIES line of the port's Makefile accordingly Add the new module entry. Add an entry to ports/MOVED. When removing a port: Perform a thorough check of the ports collection for any dependencies on the old port location/name, and update them. Running grep on INDEX is not enough because some ports have dependencies enabled by compile-time options. A full grep -r of the ports collection is recommended. Remove the old port, the old SUBDIR entry and the old module entry. Add an entry to ports/MOVED. After repo moves (rename operations where a port is copied and the old location is removed): Follow the same steps that are outlined in the previous two entries, to activate the new location of the port and remove the old one. Ports Freeze What is a ports freeze? Before a release, it is necessary to restrict commits to the ports tree for a short period of time while the packages and the release itself are being built. This is to ensure consistency among the various parts of the release, and is called the ports freeze. How long is a ports freeze? Usually an hour or two. What does it mean to me? During the ports freeze, you are not allowed to commit anything to the tree without explicit approval from the ports manager. Explicit approval here means either of the following: You asked the ports manager and got a reply saying, Go ahead and commit it. The ports manager sent a mail to you or the mailing lists during the ports freeze pointing out that the port is broken and has to be fixed. Note that you do not have implicit permission to fix a port during the freeze just because it is broken. How do I know when the ports freeze starts? The ports manager will send out warning messages to the &a.ports; and &a.committers; announcing the start of the impending release, usually two or three weeks in advance. The exact starting time will not be determined until a few days before the actual release. This is because the ports freeze has to be synchronized with the release, and it is usually not known until then when exactly the release will be rolled. When the freeze starts, there will be another announcement to the &a.committers;, of course. How do I know when the ports freeze ends? A few hours after the release, the ports manager will send out a mail to the &a.ports; and &a.committers; announcing the end of the ports freeze. Note that the release being cut does not automatically end the freeze. We have to make sure there will not be any last minute snafus that result in an immediate re-rolling of the release. Creating a New Category What is the procedure for creating a new category? A developer who wishes to propose a new category should submit a detailed rationale for the new category, including why existing categories are not sufficient, and the list of ports proposed to move. Before submitting, keep in mind that there is a fair amount of work involved from multiple parties; that the changes affect everyone who wants to keep up-to-date with the entire ports tree; and that such proposals tend to attract controversy. What do I need to do? The procedure is a strict superset of the one to repocopy individual ports (see above). File a PR in GNATS, listing the reasons for the category request. Preferably, this should also include patches for Makefiles for the old ports, the Makefiles for their old categories, and the VALID_CATEGORIES definition in ports/Mk/bsd.port.mk. Assign the PR to the &a.portmgr; (as portmgr). If they approve it, it will be reassigned to &a.cvs; (as cvs), who will do a repository copy from the old to the new locations and reassign the PR back to you. Once everything is done, perform the following steps: Upgrade each copied port's Makefile. Do not connect the new category to the build yet. To do this, you will need to: Change the port's CATEGORIES (this was the point of the exercise, remember?) The new category should be listed first. This will help to ensure that the the PKGORIGIN is correct. Run a make describe. Since the top-level make index that you will be running in a few steps is an iteration of make describe over the entire ports hierarchy, catching any errors here will save you having to re-run that step later on. If you want to be really thorough, now might be a good time to run &man.portlint.1;. Check that the PKGORIGINs are correct. The ports system uses each port's CATEGORIES entry to create its PKGORIGIN, which is used to connect installed packages to the port directory they were built from. If this entry is wrong, common port tools like &man.pkg.version.1; and &man.portupgrade.1; fail. To do this, use the chkorigin.sh tool, as follows: env PORTSDIR=/path/to/ports sh -e /path/to/ports/Tools/scripts/chkorigin.sh . This will check every port in the ports tree, even those not connected to the build, so you can run it directly after the repocopy. Hint: do not forget to look at the PKGORIGINs of any slave ports of the ports you just repocopied! On your own local system, test the proposed changes: first, comment out the SUBDIR entries in the old ports' categories' Makefiles; then enable building the new category in ports/Makefile. Run make checksubdirs in the affected category directories to check the SUBDIR entries. Next, in the ports/ directory, run make index. This can take over 40 minutes on even modern systems; however, it is a necessary step to prevent problems for other people. Once this is done, you can commit the updated ports/Makefile to connect the new category to the build and also commit the Makefile changes for the old category or categories. Change all the affected module entries in CVSROOT-ports/modules. Add appropriate entries to ports/MOVED. Update the instructions for &man.cvsup.1; by modifying distrib/cvsup/sup/README and adding the following files into cvsup/sup/ports-categoryname: list.cvs and releases. (Note: these are in the src, not the ports, repository). Submit a docs PR to add the new category to both the Porter's Handbook and to www/en/ports/categories. The procedure to update the ports web pages to reflect the new category is not yet defined. Only once all the above have been done, and no one is any longer reporting problems with the new ports, should the old ports be deleted from their previous locations in the repository. Miscellaneous Questions How do I know if my port is building correctly or not? First, go check . There you will find error logs from the latest package building runs on all supported platforms for the most recent branches. However, just because the port does not show up there does not mean it is building correctly. (One of the dependencies may have failed, for instance.) The relevant directories are available on pointyhat under /a/asami/portbuild/<arch>/<major_version> so feel free to dig around. Each architecture and version has the following subdirectories: errors error logs from latest <major_version> run on <arch> logs all logs from latest <major_version> run on <arch> packages packages from latest <major_version> run on <arch> bak/errors error logs from last complete <major_version> run on <arch> bak/logs all logs from last complete <major_version> run on <arch> bak/packages packages from last complete <major_version> run on <arch> Basically, if the port shows up in packages, or it is in logs but not in errors, it built fine. (The errors directories are what you get from the web page.) I added a new port. Do I need to add it to the INDEX? No. The ports manager will regenerate the INDEX and commit it for each &os; release. Are there any other files I am not allowed to touch? Any file directly under ports/, or any file under a subdirectory that starts with an uppercase letter (Mk/, Tools/, etc.). In particular, the ports manager is very protective of ports/Mk/bsd.port*.mk so do not commit changes to those files unless you want to face his wra(i)th. What is the proper procedure for updating the checksum for a port's distfile when the file changes without a version change? When the checksum for a port's distfile is updated due to the author updating the file without changing the port's revision, the commit message should include a summary of the relevant diffs between the original and new distfile to ensure that the distfile has not been corrupted or maliciously altered. If the current version of the port has been in the ports tree for a while, a copy of the old distfile will usually be available on the ftp servers; otherwise the author or maintainer should be contacted to find out why the distfile has changed. Perks of the Job Unfortunately, there are not many perks involved with being a committer. Recognition as a competent software engineer is probably the only thing that will be of benefit in the long run. However, there are at least some perks: Direct access to cvsup-master As a committer, you may apply to &a.kuriyama; for direct access to cvsup-master.FreeBSD.org, providing the public key output from cvpasswd yourusername@FreeBSD.org freefall.FreeBSD.org. Please note: you must specify freefall.FreeBSD.org on the cvpasswd command line even though the actual server is cvsup-master. Access to cvsup-master should not be overused as it is a busy machine. A Free 4-CD Set or DVD Subscription FreeBSD Mall, Inc. offers a free subscription of the 4-CD set or the DVD product to all FreeBSD committers. Information about how to obtain your free media is mailed to developers@FreeBSD.org following each major release. Miscellaneous Questions Why are trivial or cosmetic changes to files on a vendor branch a bad idea? From now on, every new vendor release of that file will need to have patches merged in by hand. From now on, every new vendor release of that file will need to have patches verified by hand. The option does not work very well. Ask &a.obrien; for horror stories. How do I add a new file to a CVS branch? To add a file onto a branch, simply checkout or update to the branch you want to add to and then add the file using cvs add as you normally would. For example, if you wanted to MFC the file src/sys/alpha/include/smp.h from HEAD to RELENG_4 and it does not exist in RELENG_4 yet, you would use the following steps: MFC'ing a New File &prompt.user; cd sys/alpha/include &prompt.user; cvs update -rRELENG_4 cvs update: Updating . U clockvar.h U console.h ... &prompt.user; cvs update -kk -Ap smp.h > smp.h =================================================================== Checking out smp.h RCS: /usr/cvs/src/sys/alpha/include/smp.h,v VERS: 1.1 *************** &prompt.user; cvs add smp.h cvs add: scheduling file `smp.h' for addition on branch `RELENG_4' cvs add: use 'cvs commit' to add this file permanently &prompt.user; cvs commit What meta information should I include in a commit message? As well as including an informative message with each commit you may need to include some additional information as well. This information consists of one or more lines containing the key word or phrase, a colon, tabs for formatting, and then the additional information. The key words or phrases are: PR: The problem report (if any) which is affected (typically, by being closed) by this commit. Submitted by: The name and e-mail address of the person that submitted the fix; for committers, just the username on the FreeBSD cluster. Reviewed by: The name and e-mail address of the person or people that reviewed the change; for committers, just the username on the FreeBSD cluster. If a patch was submitted to a mailing list for review, and the review was favorable, then just include the list name. Approved by: The name and e-mail address of the person or people that approved the change; for committers, just the username on the FreeBSD cluster. It is customary to get prior approval for a commit if it is to an area of the tree to which you do not usually commit. In addition, during the run up to a new release all commits must be approved by the release engineering team. If these are your first commits then you should have passed them past your mentor first, and you should list your mentor, as in ``username-of-mentor (mentor)''. Obtained from: The name of the project (if any) from which the code was obtained. MFC after: If you wish to receive an e-mail reminder to MFC at a later date, specify the number of days, weeks, or months after which an MFC is planned. Commit log for a commit based on a PR You want to commit a change based on a PR submitted by John Smith containing a patch. The end of the commit message should look something like this. ... PR: foo/12345 Submitted by: John Smith <John.Smith@example.com> Commit log for a commit needing review You want to change the virtual memory system. You have posted patches to the appropriate mailing list (in this case, freebsd-arch) and the changes have been approved. ... Reviewed by: -arch Commit log for a commit needing approval You want to commit a change to a section of the tree with a MAINTAINER assigned. You have collaborated with the listed MAINTAINER, who has told you to go ahead and commit. ... Approved by: abc Where abc is the account name of the person who approved. Commit log for a commit bringing in code from OpenBSD You want to commit some code based on work done in the OpenBSD project. ... Obtained from: OpenBSD Commit log for a change to &os.current; with a planned commit to &os.stable; to follow at a later date. You want to commit some code which will be merged from &os.current; into the &os.stable; branch after two weeks. ... MFC after: 2 weeks Where 2 is the number of days, weeks, or months after which an MFC is planned. The weeks option may be day, days, week, weeks, month, months, or may be left off (in which case, days will be assumed). In some cases you may need to combine some of these. Consider the situation where a user has submitted a PR containing code from the NetBSD project. You are looking at the PR, but it is not an area of the tree you normally work in, so you have decided to get the change reviewed by the arch mailing list. Since the change is complex, you opt to MFC after one month to allow adequate testing. The extra information to include in the commit would look something like PR: foo/54321 Submitted by: John Smith <John.Smith@example.com> Reviewed by: -arch Obtained from: NetBSD MFC after: 1 month How do I access people.FreeBSD.org to put up personal or project information? people.FreeBSD.org is the same as freefall.FreeBSD.org. Just create a public_html directory. Anything you place in that directory will automatically be visible under . Where are the mailing list archives stored? The mailing lists are archived under /g/mail which will show up as /hub/g/mail with &man.pwd.1;. This location is accessible from any machine on the FreeBSD cluster.
diff --git a/en_US.ISO8859-1/articles/console-server/article.sgml b/en_US.ISO8859-1/articles/console-server/article.sgml index 6787bc7af1..cc148bda5a 100644 --- a/en_US.ISO8859-1/articles/console-server/article.sgml +++ b/en_US.ISO8859-1/articles/console-server/article.sgml @@ -1,1483 +1,1475 @@ -%man; - -%freebsd; - -%authors; - -%trademark; - -%urls; + +%articles.ent; ]>
Console Server Gregory Bond
gnb@itga.com.au
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cisco; &tm-attrib.intel; &tm-attrib.lantronix; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.sun; &tm-attrib.general; This document describes how you can use &os; to set up a console server. A console server is a machine that you can use to monitor the consoles of many other machines, instead of a bunch of serial terminals. console-server The Problem You have a computer room with lots of &unix; server machines and lots of communications hardware. Each of these machines needs a serial console. But serial terminals are hard to find and quite expensive (especially compared to a much more capable PC). And they take up a lot of precious space in the computer room. You need access to the console because when things break, that is where error messages go. And some tasks have to be done on the console (e.g. boot problems or OS installs/upgrades). Some &unix; systems allow the console to break out to the ROM monitor which can sometimes be the only way to unstick a hung machine. This is often done with a LINE BREAK sent on the console serial port. If we are going to play about with consoles, then there are a couple of other things that would be great: Remote access. Even in the same office, it would be convenient to access all the consoles from your desk without walking into the computer room. But often the machines are off-site, perhaps even in another country. Logging. If something has gone wrong, you would like to be able to have a look at the previous console output to see what is up. Ordinary console screens give you the last 25 lines. More would be better. Network Independence. The solution needs to work even if the network is down. After all, a failed network is when you need consoles the most! Even better is network independence with remote access. No single-point failure. A console system that crashes every machine when it fails is no use. This is particularly tricky with Sun &unix; hosts as they will interpret a powered-off terminal as a BREAK, and drop back to the ROM monitor. Interface with a pager or some similar alerter device. Ability to power-cycle machines remotely. Not be too expensive. Free is even better! Possible Solutions If you use PC hardware for your servers, then a so-called KVM switch is one possible solution. A KVM switch allows the use of a single keyboard, video screen and mouse for multiple boxes. This cuts down on the space problem, but only works for PC hardware (not any communications gear you might have), and is not accessible from outside the computer room. Nor does it have much scroll-back or logging, and you have to handle alerting some other way. The big downside is that it will not work for serial-only devices, such as communications hardware. This means that even with a room full of PC-based servers, you are probably still going to need some sort of serial console solution. Actually, Doug Schache has pointed out that you can get KVM switches that also do serial consoles or Sun compatible KVM switching as well as PCs, but they are expensive. See Avocent for example.) You might be tempted to do without a console terminal, but when things go pear-shaped you really need to see what is on the console. And you have to use the console to boot the machine and do things like OS upgrades or installs. You might try having a single console terminal and switching from server to server as needed, either with a serial switch or just by patching it into the required machine. Serial switches are also hard to come by and not cheap, and may cause problems with sending BREAK when they switch. And (if your computer room is anything like ours) you never seem to have the right combination of patch leads to connect to the machine you need to, and even if the leads are there you can never work out exactly which combination of DTE/DCE headshells goes with which lead goes with which hardware. So you spend the first 10 minutes fooling around with breakout boxes and a box of leads, all while the server is down and the users are screaming. Of course this does not deal with the logging or remote access requirements. And inevitably the console is not switched to the machine you need so you lose all the console messages that might tell you what is going on. One popular solution is to use terminal server hardware. Typically, the serial ports are connected to the various machine consoles, and set up for reverse telnet access. This means a user can telnet to a given IP/port and be connected to the appropriate console. This can be very cost-effective, as suitable old terminal servers can be picked up fairly cheaply (assuming you do not have a couple lying around). And it is of course network-accessible so suitable for remote access. But it suffers from one major drawback: if the network is down, then you have no access to any console, even if you are standing right next to the machine. (This may be partially alleviated by having a suitable terminal connected to one of the terminal server ports and connecting from there, but the terminal server software may not support that.) Also there is no logging or replay of console messages. But with a bit of work, and the addition of some software such as conserver (described below), this can be made to work pretty well. A possibility suggested by Bron Gondwana is similar to the above solution. If you use servers with multiple serial ports, you can connect each spare serial port to the console port of the next server, creating a ring of console connections (in some sort of order). This can be made to work reasonably well with the aid of the conserver software, but can be a bit confusing otherwise (i.e. remembering which port is connected to which console). And you are stuck if you need to use serial ports for other things (such as modems) or you have machines without spare ports. Or, if your budget exceeds your willingness to hack, you can buy an off-the-shelf solution. These vary in price and capability. See, for example, Lightwave, Perle, Avocent or Black Box. These solutions can be quite expensive - typically $USD100 - $USD400 per port. Our Solution In light of the above requirements, we chose a solution based on a dedicated PC running &unix; with a multiport serial card, and some software designed to handle serial consoles. It includes the following elements: A surplus PC. We used a &pentium; 166, with a PCI bus, 2Gbyte hard disk and 64Mb of RAM. This is a massive overkill for this task, and P-100, 500Mb, 32Mb would be more than enough. A PC &unix; system. We used &os; 4.3 as that is used for other tasks within our office. A multi-port serial card. We chose the &easyio; PCI 8-port card from Stallion Technologies. This cost us about $AUD740, or under $100/port, from Harris Technologies (which has lots of stuff but is by no means the cheapest place in town - shop around and you might get it a lot cheaper). This card has a big DB80 connector on the back, and a cable plugs into that which has a block with 8 RJ-45 sockets on it. (We chose the RJ-45 version as our entire cable plant is RJ-45. This allows us to patch connections from the required box to the console server without any special cables.) This is the only thing we needed to buy to make this all happen. We build two servers, one for each computer room, with 8 ports in one and 16 ports (via two &easyio; PCI cards) in the other. If we needed more than 16 ports, then another of the Stallion cards would be more cost-effective. We could conceivably support 128 ports in each server (with 2 EasyConnect 8/64 host cards and 8 16 port RJ-45 modules) for about $AUD12,000. A modem for remote access to the console server host when the network is down. We have not done this yet as the computer room is next door, but when we put a server in Sydney we will add the modem. The idea is that when the network is down, you can dial up and log into the server machine and run the console program locally. For security, we will probably leave the modem powered off and ask the gopher in Sydney to turn on the well-labelled button when we need it. A program called conserver. This program does all the magic required to enable remote access to consoles, and do the replaying and logging etc. It comes in two parts: a server called conserver that runs as a daemon and connects to the serial ports, handles logging etc, and a client program called console that can connect to the server, display console messages, send keystrokes (and BREAK), etc. This design covers all the major requirements except remote power cycling: Remote access comes because the console client program works across the network. Logging is handled by the conserver program. If the network is down, then we can use the console on the PC to run the console client locally. For remote sites, we can add a modem for dial-in access to the the server command line to run the client. By patching the &solaris; servers (see ), we can avoid pranging the whole computer room when the console server PC crashes (or the power supply fails, or whatever). We already have pager alerts from another system we have installed, but the console server has all the required log info so that could easily be implemented if we needed. And it even has a modem for calling the pager company! We do not currently support remote power cycling. Some versions of the conserver program support this, but it does require specialised serial-controlled power boards. We have no immediate need for remote power cycling (we have a gopher in each remote office who can do it by remote control) so this is not a major problem, and we could add it easily should we ever see the need and get the appropriate hardware. This solution was very cheap. Total cost for the 9-port server was $AUD750 for the IO card, as we re-used a surplus PC and already owned the hardware for the special cables. If we had to buy everything, then it would still only cost around $AUD1500 for the 8-port server. Setting Up The Server Checking the Stallion driver &os; has adequate support for modern Stallion cards since 4.4 release. If you are running an older version of &os;, you will need to upgrade to a more modern version of &os; (which you should do anyway, to make sure your system is not vulnerable to known security issues). See the &os; Handbook for information about updating your system. Configuring a new kernel The Stallion driver is not included in the default GENERIC kernel, so you will need to create a kernel config file with the appropriate entries. See &man.stl.4; and the appropriate section of the &os; Handbook. Making The Devices You will need to make the device notes for the Stallion card (which are not made by default). A new version of /dev/MAKEDEV with Stallion support will have been created by the mergemaster run during the above procedure. If you have a Stallion card with more than 8 ports, then you will need to edit /dev/MAKEDEV and change the definition of maxport at about line 250. By default, MAKEDEV only makes device nodes for 8 ports to keep the size of the /dev directory down. Run a command like: &prompt.root; cd /dev/ && sh MAKEDEV cuaE0 to create dial-out devices for the first Stallion card. See the comments in MAKEDEV and the &man.stl.4; man page for more details. Compiling conserver See the section on conserver versions ; the version I use is available in the &os; ports collection; however, it is not the only one.) There are two ways to install conserver. You can either compile from the source or use the &os; ports framework. Using the ports framework Using the ports is a bit cleaner, as the package system can then keep track of installed software and cleanly delete them when not being used. I recommend using the comms/conserver-com port. Change into the port directory and (as root) type: &prompt.root; make DEFAULTHOST=consolehost install where consolehost is the name of the machine running the console server. Specifying this when the binary is compiled will avoid having to either specify it each time the program is run on remote hosts or having to maintain a conserver.cf file on every host. This command will fetch, patch, configure, compile and install the conserver application. You can then run make package to create a binary package that can be installed on all the other &os; hosts with &man.pkg.add.1;. For extra style points, you can make a two versions of the package: one for the console server machine without a DEFAULTHOST argument, and one for all the other hosts with a DEFAULTHOST argument. This will mean the console client program on the console server machine will default to localhost, which will work in the absence of name servers when the network is busted, and also allow trusted (i.e. no password required) connections via the localhost IP address for users logged into the console server machine (either via the console screen or the emergency backup modem). The version for the other machines with a DEFAULTHOST argument means users can just use the console client without specifying a hostname every time, and without needing to configure the conserver.cf file on every machine. From the source tarball If you prefer, you can download conserver and compile it yourself. You might need to do this if you want to install the console client on non-&os; systems. We run the client on our &solaris; hosts and it inter-operates with the &os;-hosted server with no problems. This allows anyone in the whole company (many of whom have PCs and no &os; host access on their desk) to access the console server. Download the file from the conserver.com FTP site. Extract it into a handy directory then configure it by running &prompt.user; ./configure The argument avoids having to specify the master server every time the client is run remotely (or keeping up-to-date config files on all remote hosts). The argument avoids having to update on every machine. Then type make and, as root, make install. Configuring conserver The conserver program is configured via a file called conserver.cf. This file usually lives in /usr/local/etc and is documented in the &man.conserver.cf.5; manual page. Our config file looks like this: LOGDIR=/var/log/consoles gallows:/dev/cuaE0:9600p:&: roo:/dev/cuaE1:9600p:&: kanga:/dev/cuaE2:9600p:&: %% allow: itga.com.au trusted: 127.0.0.1 buzz The first line means all the console log files by default go into the /var/log/consoles directory. The & in each line says the log file for that machine will be /var/log/consoles/machine. The next three lines show three machines to which we need to connect. We use the cuaEx devices rather than the ttyEx devices because console ports typically do not show carrier. This means that opening ttyEx would hang and conserver would never connect. Using the cuaEx device avoids this problem. Another solution would be to use the ttyEx devices and enable soft carrier on these ports, perhaps by setting this using the ttyiEx device in the /etc/rc.serial file. See the comments in this file for more details. Also see &man.sio.4; for information on the initial-state and locked-state devices. (The Stallion driver also supports these conventions). And see the &man.stty.1; for details on setting device modes. The last section shows that any user logged into the server machine has passwordless access to all consoles. We do this because there are no user accounts on this machine and it is safely isolated from the wide world behind our firewall. The allow line allows anyone on a machine inside our organisation to access the console server if they provide their password, which is recorded in the conserver.passwd file (see next section). Setting conserver passwords The conserver.passwd file contains the encrypted version of the password that each user. The file is documented in the conserver.cf(5) manual page. The only tricky bit is loading the file with encoded passwords. It appeared in &os; that was is no obvious way to generate an encrypted password for inclusion in another file (but see below). So I put together a quick hack perl script to do this: @rands = (); foreach (0..4) { push(@rands, rand 64); } $salt = join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[@rands]; $salt = '$1$' . $salt . '$'; print 'Enter password: '; `stty -echo`; $cleartext = <>; `stty echo`; chop($cleartext); print crypt($cleartext, $salt), "\n"; This uses the &os; MD5-style encrypted passwords. Running this on other &unix; variants, or on &os; with DES passwords, will likely need a different style of salt. &a.kris; has since pointed out you can get the same effect using the openssl passwd command: &prompt.user; openssl passwd -1 Password: password $1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/ Starting <application>conserver</application> at system boot time There are two ways this can be done. Firstly, you could start up conserver from init by including an entry in /etc/ttys that is similar to this: cuaE0 "/usr/local/sbin/conserver" unknown on insecure This has two advantages: init will restart the master console server if it ever crashes for any reason (but we have not noticed any crashes so far), and it arranges for standard output of the conserver process to be directed to the named tty (in this case cuaE0). This is useful because you can plug a terminal into this port, and the conserver program will show all console output not otherwise captured by a client console connection. This is useful as a general monitoring tool to see if anything is going on. We set this terminal up in the computer room but visible from the main office. It is a very handy feature. The downside of running conserver from the ttys file is that it cannot run in daemon mode (else &man.init.8; would continually restart it). This means conserver will not write a PID file, which makes it hard to rotate the log files. So we start conserver from an rc.d script. If you installed conserver via the port, there will be a conserver.sh.sample file installed in /usr/local/etc/rc.d. Copy and/or rename this to conserver.sh to enable conserver to start at boot time. In fact we use a modified version of this script which also connects conserver to a terminal via a tty device so we can monitor unwatched console output. Our conserver.sh script looks like this: #!/bin/sh # # Startup for conserver # PATH=/usr/bin:/usr/local/bin case "$1" in 'start') TTY=/dev/cuaE7 conserver -d > $TTY # get NL->CR+NL mapping so msgs look right stty < /dev/cuaE7 opost onlcr echo -n ' conserver' ;; 'stop') kill `cat /var/run/conserver.pid` && echo -n ' conserver' ;; *) echo "Usage: $0 { start | stop }" ;; esac exit 0 Note the use of cuaE0 device and the need to set tty modes for proper NL-<CR handling). Keeping the log files trimmed &os; has a program called newsyslog that will automatically handle log file trimming. Just add some lines to the configuration file /etc/newsyslog.conf for the console logs: # # The log files from conserver /var/log/consoles/gallows 644 10 1000 * Z /var/run/conserver.pid /var/log/consoles/kanga 644 10 1000 * Z /var/run/conserver.pid /var/log/consoles/roo 644 10 1000 * Z /var/run/conserver.pid This tells newsyslog (which is run from cron every hour on the hour) that the console log files should be archived and compressed once they reach 1Mb, that we should keep 10 of them, and that to signal the server program you send a SIGHUP to the process whose PID is in the conserver.pid file. This is the master server, and it will arrange to signal all the child processes. Yes, this will send a HUP to all clients whenever a single log file needs rotating, but that is quite cheap. See &man.newsyslog.8; for details. Cabling This is always the hardest part of this kind of problem. We had only a dozen or so cables/headshells to build, and we already had a collection of the appropriate crimping tools and hardware, so we did it ourselves. But if you are not set up for this, or you have a large number of cables to make, then you might consider getting some cables custom made. Look in the yellow pages, there are a surprising number of places that do this! Getting custom-made cabling is good, and you can get much more professional results, but can be expensive. For example, the RJ-45 to DB-25 adapter kits described below are about $10 each; custom-made headshells are about twice that (and take a couple of weeks to arrive). Similarly, crimping custom RJ-45 to RJ-45 leads is quite cheap (say, $5 each) but it takes a fair amount of time. Custom made RJ-45 socket to RJ-45 plug converters cost about $25 each. We have settled on RJ-45 Cat-V cabling for all our office and computer room cabling needs. This included patching between racks in the computer room. For serial connections, we use patchable headshells that have RJ-45 sockets on the back. This allows us to patch whatever RJ-45–DB-25 connections we need. Which is just as well, because there are many incompatible ways to represent serial connections on the RJ-45 plug. So the cabling has to be very careful to use the right mapping. RJ-45 colors RJ-45 cables and plugs have 8 pins/conductors. These are used as 4 matched pairs. There are a couple of conventions about how the pairs are mapped onto pins, but 100baseT uses the most common (known as EIA 586B). There are three common color-coding conventions for the individual conductors in RJ-45 cables. They are: <!-- XXX: Add title for this table --> Pin Scheme 1 Scheme 2 (EIA 568B) Scheme 3 (EIA 568A) Pair 1 Blue White+Green White+Orange 2+ 2 Orange Green Orange 2- 3 Black White+Orange White+Green 3+ 4 Red Blue Blue 1+ 5 Green White+Blue White+Blue 1- 6 Yellow Orange Green 3- 7 Brown White+Brown White+Brown 4+ 8 White or Grey Brown Brown 4-
Note EIA 468A and EIA 568B are very similar, simply swapping the colors assigned to pair 2 and pair 3. See for example the Cabletron Tech Support Site for more details. The pins in the RJ-45 plug are numbered from 1 to 8. Holding a patch lead with the cable pointing down and the clip away from you, pin 1 is at the left. Or, looking into an RJ-45 socket with the clip to the top, pin 1 is on the right. The following illustration (shamelessly lifted from the Cabletron web site above) shows it pretty well: We have four classes of equipment to deal with in our setup: Sun servers Sun servers operate as DTE (i.e. send data on TxD and read RxD, and assert DTR) with a female DB-25 socket on board. So we need to create a headshell for the Stallion that operates as DCE and has a male DB-25 plug (i.e. acts as a null modem cable as well as converts from RJ-45 to DB-25). We use headshells that have an RJ-45 socket in them and 8 short flyleads with DB-25 pins on the end. These pins can be inserted into the DB-25 plug as required. This allows us to create a custom RJ-45-DB-25 mapping. We used a couple of different sorts, including the MOD-TAP part no. 06-9888-999-00 and the FA730 series from Black Box. On our version of the headshells, these flyleads had the following colours (from Pin 1-8): Blue, Orange, Black, Red, Green, Yellow, Brown, White. (Looking into an RJ-45 socket, with the clip towards the top, pin 1 is on the right.) This is how they are connected to the DB-25 socket: <!-- XXX: Add a title here --> Stallion RJ-45 Pin Colour Signal Sun DB-25 Male Pin RS232 Signal 1 Blue DCD 20 DTR 2 Orange RTS 5 CTS 3 Black Chassis Gnd 1 Chassis Gnd 4 Red TxD 3 RxD 5 Green RxD 2 TxD 6 Yellow Signal Gnd 7 Signal Gnd 7 Brown CTS 4 RTS 8 White RTS 8 DCD
Note that colours may be different for your cables/headshells. In particular, pin 8 may be grey instead of white. Remember to label the headshell clearly, in a way that will not fade/fall off/rub off with time! Cisco 16xx/26xx/36xx Routers I think that all Cisco gear that has RJ-45 console ports and runs &ios; will have the same cable requirements. But best to check first. We have tried this on 1600s and 2600s only. Both the Stallion card and the 2600 have RJ-45 connections, but of course they are not compatible. So you need to crimp up a special RJ-45-RJ-45 cable. And this cable must be plugged in the right way round! We use normal RJ-45 flyleads from the router to the patch panel, then the special flylead from the patch panel to the Stallion card. We built two special Stallion-Cisco leads by cutting in half a 2m flylead and crimping an RJ-45 with the appropriate pinouts to each free end. The original connector will be the Cisco end of the cable, the new crimped connector will be the Stallion end. Holding the RJ-45 connector on the flylead with the cable pointing down and the clip pointing away, this is the order of the colours of the cables in our flylead (pins 1-8, from L to R): white/green, green, white/orange, blue, white/blue, orange, white/brown, brown. For the Stallion end, trim and discard the brown/white+brown and green/white+green pairs. Then holding the RJ-45 plug in the same manner (cable down, clip away), the connections should be (from L to R): None, None, Blue, Orange, White/Orange, White/Blue, None, None, as shown: <!-- XXX: add title for this table --> Cisco RJ-45 Pin Colour Cisco Signal Stallion RJ-45 Pin Stallion Signal 1 White/Green RTS N/C   2 Green DTR N/C   3 White/Orange TxD 5 RxD 4 Blue Gnd 3 Gnd 5 White/Blue Gnd 6 Gnd 6 Orange RxD 4 TxD 7 White/Brown DSR N/C   8 Brown CTS N/C  
Note again that colours may be different for your cables/headshells. Carefully label the cable, and each end of the cable, and test it. If it does not work, testing is really hard as they do not make RJ-45 serial line testers! Let me state this more strongly: Be very sure that you label this cable in a way that is easily, instantly and permanently recognisable as a special cable and not easily confused with normal drop cables. Some suggestions (from Hugh Irvine): Make them out of different coloured cable. For marking the ends, clear heat-shrink tubing slipped over printed labels *before* putting on the connectors is the best way I have seen for marking what they are. You can also use Panduit or similar tags that you put on with nylon tie straps, but I find the ink wears off the tags. Cisco &catalyst; switches Astoundingly, the pinout on the console ports of the &catalyst; switches is actually different to the pinout used on the 26xx-series Cisco hardware. I think the way to tell which is which is by considering the operating software. If it uses &ios;, then the previous pinout is required. If it uses the switch software, then this pinout is required. Fortunately, while the pinouts are different, the &catalyst; pinout is simply a mirror image of the pinout for the 2600. Even more fortunately, the Ciscos (both &catalyst; switches and 2600s) seem to ship with a special rollover cable, which is exactly what is required in this case. We use the rollover cable from the &catalyst; switches to the patch panel, then the same cable as above for the 2600s from the patch panel to the Stallion card, and it all works just fine. This rollover cable is an RJ-45-RJ-45 cable and is intended to be used with the shipped (hardwired) RJ-45 - DB-25 and RJ-45–DB-9 headshells for console connections. Ours are 2m long, either light blue or black, and are quite flat. Attempts to use them for 100baseT Ethernet will fail miserably! You can tell it is a rollover cable by holding both ends with the cable pointing down and the clip pointing away from you. Check the colour of the leads in each pin in the two connectors, they should be mirror images. (In our case, one goes grey-orange-black-red-green-yellow-blue-brown, the other brown-blue-yellow-green-red-black-orange-grey). This is a rollover cable. If you do not have a rollover cable present, then you can use the same cable as for the 26xx except plug it in the other way around (i.e. original 8-pin plug goes into the Stallion, the new crimped plug with only 4 active wires goes into the &catalyst; switch). &os; servers (or any other &i386; PC systems using a serial console) We run &os; 4 on a couple of &i386; PCs for various peripheral uses. &os; usually uses a screen and keyboard for the console, but can be configured to use a serial port (usually the first serial port known as COM1 in DOS/&windows; or ttyd0 in &unix;). The cabling for these servers depends on the PC harware. If the PC has DB-25 female socket on board (as most older PCs do), then the same headshell as works for the Sun server above will work fine. If the PC has DB-9 male plug on board (as more recent PCs tend to do), then there are two choices. Either use a DB-9 to DB-25 converter (this is not recommended as it can lead to unreliable connections over the long term as the adapter is bumped/works loose), or build an RJ-45 to DB-9 cable as follows: <!-- XXX: add title for this table --> Stallion RJ-45 Pin Colour Signal PC DB-9 Female Pin RS232 Signal 1 Blue DCD 4 DTR 2 Orange RTS 8 CTS 3 Black Chassis Gnd N/C   4 Red TxD 2 RxD 5 Green RxD 3 TxD 6 Yellow Signal Gnd 5 Signal Gnd 7 Brown CTS 7 RTS 8 White RTS 1 DCD
See for tips on configuring &os; to use a serial console. On Sun Systems And Break Anyone who has turned off a terminal used as a console for a Sun system will know what happens and why this is a problem. Sun hardware recognises a serial BREAK as a command to halt the OS and return to the ROM monitor prompt. A serial BREAK is an out-of-band signal on an RS-232 serial port that involves making the TX DATA line active (i.e. pulled down to less than -5v) for more than two whole character times (or about 2ms on a 9600bps line). Alas, this BREAK signal is all to easily generated by serial hardware during power-on or power-off. And the Stallion card does, in fact, generate breaks when the power to the PC fails. Unless fixed, this problem would mean that every Sun box connected to the console server would be halted whenever the power failed (due to dead power supplies, or fat-fingered operators unplugging it, or whatever). This is clearly not an acceptable situation. Fortunately, Sun have come up with a set of fixes for this. For &solaris; 2.6 and later, the kbd(1) command can be used to disable the ROM-on-BREAK behaviour. This is a good start, but leaves you out of luck in the situation where a break is needed to get into a broken machine. Starting with &solaris; 8, the kbd command can also be used to enable an alternate break sequence using the kbd -a alternate command. When this is set, the key sequence ReturnTildeCtrlB (within 5 seconds) will drop to the ROM. You can enable this permanently by editing the /etc/default/kbd file; see the kbd(1) man page. Note that this alternate break sequence is only active once the kernel has started running multiuser and processed the default file. While the ROM is active (during power-on and during the boot process) and while running single-user, you still need to use a BREAK to get to the ROM prompt. The console client can cause the server to send a BREAK using the escape sequence Esccl1. If you have a Sun software support contract, there are patches available for &solaris; 2.6 and 2.7 that add the alternate break capability integrated into &solaris; 2.8. &solaris; 2.6 requires patch 105924-10 or higher. &solaris; 2.7 requires patch 107589-02 or higher. We have added this patch to all our &solaris; 2.6 servers, and added it (and the entry in the /etc/default/kbd file) to our jumpstart configuration so it will automatically be added to every new install. We have confirmed by direct testing that neither the Cisco 16xx, 26xx, or &catalyst; hardware suffers from the BREAK sent when the Stallion card loses power. Contemporary Cisco software listens for BREAK signal only for first 30 seconds after power-on or reboot. Using a Serial Console on &os; The procedure for doing this is described in detail in the &os; Handbook. This is a quick summary. Check the kernel configuration Check that the kernel configuration file has flags 0x10 in the config line for the sio0 device. This signals this device (known as COM1 in DOS/&windows; or /dev/ttyd0 in &os;) can be used as a console. This flag is set on the GENERIC and LINT sample configs, so is likely to be set in your kernel. Create the <filename>/boot.conf</filename> file This file should be created containing a single line containing just -h (minus the quotes). This tells the &os; boot blocks to use the serial console. Edit <filename>/etc/ttys</filename> Edit this file and make the following changes. If you are not going to have any keyboard/video screen on this server at all, you should find all the lines for ttyv devices like ttyv1 "/usr/libexec/getty Pc" cons25 on secure Change the on to off. This will stop login screens being run on the useless video consoles. Find the line containing ttyd0. Change it from ttyd0 "/usr/libexec/getty std.9600" dialup off secure to ttyd0 "/usr/libexec/getty std.9600" vt100 on secure (replacing vt100 with the term type of your console. The xterms terminal type might be a good choice). This allows you to log in to the console port once the system is running multi-user. Reboot and off you go! Security Implications The client-server protocol for conserver requires the user of the console client to enter a password. This password is passed across the net in cleartext! This means conserver is not really suitable for use across untrusted networks (such as the Internet). Use of conserver-only passwords (in the conserver.passwd file) slightly mitigate this problem, but anyone sniffing a conserver connection can easily get console access, and from there prang your machine using the console break sequence. For operating across the Internet, use something secure like SSH to log into to the server machine, and run the console client there. On Conserver Versions The conserver program has fractured into a number of versions. The home page referenced below seems to be the latest and most featureful version around, and for July 2004 carries a version number of 8.1.9. This is maintained by Bryan Stansell bryan@conserver.com, who has brought together the work of many people (listed on his webpage). The &os; ports collection contains a port for version 8.5 of conserver at comms/conserver. This seems to be older and less featureful than the 8.1.9 version (in particular, it does not support consoles connected to terminal server ports and does not support a conserver.passwd file), and is written in a fairly idiosyncratic manner (using a preprocessor to generate C code). Version 8.5 is maintained by Kevin S. Braunsdorf ksb+conserver@sa.fedex.com who did most of the original work on conserver, and whose work Bryan Stansell is building on. The 8.5 version does support one feature not in the 8.1.9 version (controlling power to remote machines via a specific serial-interfaced power controller hardware). Beginning with December 2001, Brian's version (currently 8.1.9) is also presented in ports collection at comms/conserver-com. We therefore recommend you to use this version as it is much more appropriate for console server building. Links http://www.conserver.com/ Homepage for the latest version of conserver. ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz The source tarball for version 8.1.9 of conserver. http://www.stallion.com/ Homepage of Stallion Technologies. http://www.conserver.com/consoles/msock.html Davis Harris' Minor Scroll of Console Knowledge contains a heap of useful information on serial consoles and serial communications in general. http://www.conserver.com/consoles/ The Greater Scroll of Console Knowledge contains even more specific information on connecting devices to various other devices. Oh the joy of standards! http://www.eng.auburn.edu/users/doug/console.html Doug Hughes has a similar console server, based on the screen program and an old &sunos; host. http://www.realweasel.com/ The Real Weasel company makes a ISA or PCI video card that looks like a PC video card but actually talks to a serial port. This can be used to implement serial consoles on PC hardware for operating systems that can not be forced to use serial console ports early enough. Manual Pages console(8) conserver(8) conserver.cf(5)
diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml index 000748a1b7..359598150f 100644 --- a/en_US.ISO8859-1/articles/contributing/article.sgml +++ b/en_US.ISO8859-1/articles/contributing/article.sgml @@ -1,564 +1,554 @@ -%man; - %freebsd; - %newsgroups; - -%authors; - %mailing-lists; - -%trademarks; - -%urls; + +%articles.ent; ]>
Contributing to FreeBSD $FreeBSD$ This article describes the different ways in which an individual or organization may contribute to the FreeBSD Project. Jordan Hubbard Contributed by &tm-attrib.freebsd; &tm-attrib.ieee; &tm-attrib.general; contributing So you want to contribute to FreeBSD? That is great! FreeBSD relies on the contributions of its user base to survive. Your contributions are not only appreciated, they are vital to FreeBSD's continued growth. Contrary to what some people might have you believe, you do not need to be a hot-shot programmer or a close personal friend of the FreeBSD core team to have your contributions accepted. A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD. There is always more work to be done than there are people available to do it, and more help is always appreciated. The FreeBSD project is responsible for an entire operating system environment, rather than just a kernel or a few scattered utilities. As such, our TODO lists span a very wide range of tasks: from documentation, beta testing and presentation, to the system installer and highly specialized types of kernel development. People of any skill level, in almost any area, can almost certainly help the project. Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us. Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish. Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it. The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look. What Is Needed The following list of tasks and sub-projects represents something of an amalgam of various TODO lists and user requests. Ongoing Non-Programmer Tasks Many people who are involved in FreeBSD are not programmers. The Project includes documentation writers, Web designers, and support people. All that these people need to contribute is an investment of time and a willingness to learn. Read through the FAQ and Handbook periodically. If anything is badly explained, out of date or even just completely wrong, let us know. Even better, send us a fix (SGML is not difficult to learn, but there is no objection to ASCII submissions). Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date. First take a look at the Translations FAQ in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this — as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. Read the &a.questions; and &ng.misc; occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to work on. Ongoing Programmer Tasks Most of the tasks listed here require either a considerable investment of time, or an in-depth knowledge of the FreeBSD kernel, or both. However, there are also many useful tasks which are suitable for weekend hackers. If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine current.FreeBSD.org which builds a full release once a day—every now and again, try to install the latest release from it and report any failures in the process. Read the &a.bugs;. There might be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. If you know of any bug fixes which have been successfully applied to -CURRENT but have not been merged into -STABLE after a decent interval (normally a couple of weeks), send the committer a polite reminder. Move contributed software to src/contrib in the source tree. Make sure code in src/contrib is up to date. Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings. Fix warnings for ports which do deprecated things like using gets() or including malloc.h. If you have contributed any ports, send your patches back to the original authors (this will make your life easier when they bring out the next version). Get copies of formal standards like &posix;. You can get some links about these standards at the FreeBSD C99 & POSIX Standards Conformance Project web site. Compare FreeBSD's behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. If you are able, figure out how to fix it and include a patch in the PR. If you think the standard is wrong, ask the standards body to consider the question. Suggest further tasks for this list! Work through the PR Database problem reports database The FreeBSD PR list shows all the current active problem reports and requests for enhancement that have been submitted by FreeBSD users. The PR database includes both programmer and non-programmer tasks. Look through the open PRs, and see if anything there takes your interest. Some of these might be very simple tasks that just need an extra pair of eyes to look over them and confirm that the fix in the PR is a good one. Others might be much more complex, or might not even have a fix included at all. Start with the PRs that have not been assigned to anyone else. If a PR is assigned to someone else, but it looks like something you can handle, email the person it is assigned to and ask if you can work on it—they might already have a patch ready to be tested, or further ideas that you can discuss with them. How to Contribute Contributions to the system generally fall into one or more of the following 5 categories: Bug Reports and General Commentary An idea or suggestion of general technical interest should be mailed to the &a.hackers;. Likewise, people with an interest in such things (and a tolerance for a high volume of mail!) may subscribe to the &a.hackers;. See The FreeBSD Handbook for more information about this and other mailing lists. If you find a bug or are submitting a specific change, please report it using the &man.send-pr.1; program or its WEB-based equivalent. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put [PATCH] in the synopsis of the report. When including patches, do not use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. Consider compressing patches and using &man.uuencode.1; if they exceed 20KB. After filing a report, you should receive confirmation along with a tracking number. Keep this tracking number so that you can update us with details about the problem by sending mail to FreeBSD-gnats-submit@FreeBSD.org. Use the number as the message subject, e.g. "Re: kern/3377". Additional information for any bug report should be submitted this way. If you do not receive confirmation in a timely fashion (3 days to a week, depending on your email connection) or are, for some reason, unable to use the &man.send-pr.1; command, then you may ask someone to file it for you by sending mail to the &a.bugs;. See also this article on how to write good problem reports. Changes to the Documentation documentation submissions Changes to the documentation are overseen by the &a.doc;. Please look at the FreeBSD Documentation Project Primer for complete instructions. Send submissions and changes (even small ones are welcome!) using &man.send-pr.1; as described in Bug Reports and General Commentary. Changes to Existing Source Code FreeBSD-CURRENT An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as FreeBSD-CURRENT which is made available in a variety of ways for the convenience of developers working actively on the system. See The FreeBSD Handbook for more information about getting and using FreeBSD-CURRENT. Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the &a.announce; and the &a.current; lists, where discussions on the current state of the system take place. Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the &man.diff.1; command. The preferred &man.diff.1; format for submitting patches is the unified output format generated by diff -u. However, for patches that substantially change a region of code, a context output format diff generated by diff -c may be more readable and thus preferable. diff For example: &prompt.user; diff -c oldfile newfile or &prompt.user; diff -c -r olddir newdir would generate such a set of context diffs for the given source file or directory hierarchy. Likewise, &prompt.user; diff -u oldfile newfile or &prompt.user; diff -u -r olddir newdir would do the same, except in the unified diff format. See the manual page for &man.diff.1; for more details. Once you have a set of diffs (which you may test with the &man.patch.1; command), you should submit them for inclusion with FreeBSD. Use the &man.send-pr.1; program as described in Bug Reports and General Commentary. Do not just send the diffs to the &a.hackers; or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including [PATCH] in the synopsis of the report. uuencode If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a tar file and run the &man.uuencode.1; program on it. Archives created with &man.shar.1; are also welcome. If your change is of a potentially sensitive nature, e.g. you are unsure of copyright issues governing its further distribution or you are simply not ready to release it without a tighter review first, then you should send it to &a.core; directly rather than submitting it with &man.send-pr.1;. The &a.core; reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also very busy and so you should only send mail to them where it is truly necessary. Please refer to &man.intro.9; and &man.style.9; for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. New Code or Major Value-Added Packages In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as uuencoded tar files or upload them to a web or FTP site for other people to access. If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are: BSD copyright The BSD copyright. This copyright is most preferred due to its no strings attached nature and general attractiveness to commercial enterprises. Far from discouraging such commercial use, the FreeBSD Project actively encourages such participation by commercial interests who might eventually be inclined to invest something of their own into FreeBSD. GPLGNU General Public License GNU General Public License The GNU General Public License, or GPL. This license is not quite as popular with us due to the amount of extra effort demanded of anyone using the code for commercial purposes, but given the sheer quantity of GPL'd code we currently require (compiler, assembler, text formatter, etc) it would be silly to refuse additional contributions under this license. Code under the GPL also goes into a different part of the tree, that being /sys/gnu or /usr/src/gnu, and is therefore easily identifiable to anyone for whom the GPL presents a problem. Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will be considered. Contributions for which particularly restrictive commercial copyrights apply are generally rejected, though the authors are always encouraged to make such changes available through their own channels. To place a BSD-style copyright on your work, include the following text at the very beginning of every source code file you wish to protect, replacing the text between the %% with the appropriate information: Copyright (c) %%proper_years_here%% %%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $Id$ For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright. Money, Hardware or Internet Access We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves. <anchor id="donations">Donating Funds The FreeBSD Foundation is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax. Donations to a tax-exempt entity are often deductible from taxable federal income. Donations may be sent in check form to:
The FreeBSD Foundation 7321 Brockway Dr. Boulder, CO 80303 USA
The FreeBSD Foundation is now able to accept donations through the web with PayPal. To place a donation, please visit the Foundation web site. More information about the FreeBSD Foundation can be found in The FreeBSD Foundation -- an Introduction. To contact the Foundation by email, write to bod@FreeBSDFoundation.org. Donating Hardware donations The FreeBSD Project happily accepts donations of hardware that it can find good use for. If you are interested in donating hardware, please contact the Donations Liaison Office. Donating Internet Access We can always use new mirror sites for FTP, WWW or cvsup. If you would like to be such a mirror, please see the Mirroring FreeBSD article for more information.
diff --git a/en_US.ISO8859-1/articles/contributors/article.sgml b/en_US.ISO8859-1/articles/contributors/article.sgml index fef0c1f7d4..969db3ffa4 100644 --- a/en_US.ISO8859-1/articles/contributors/article.sgml +++ b/en_US.ISO8859-1/articles/contributors/article.sgml @@ -1,718 +1,704 @@ -%man; - -%authors; - -%teams; - -%mailing-lists; - -%freebsd; - - -%trademarks; - -%urls; - + +%articles.ent; %contrib.ent; ]>
Contributors to FreeBSD $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.sun; &tm-attrib.general; This article lists individuals and organizations who have made a contribution to FreeBSD. Donors Gallery The FreeBSD Project is indebted to the following donors and would like to publicly thank them here! Contributors to the central server project: The following individuals and businesses made it possible for the FreeBSD Project to build a new central server machine, which has replaced freefall.FreeBSD.org at one point, by donating the following items: &a.mbarkah; and his employer, Hemisphere Online, donated a Pentium Pro (P6) 200MHz CPU ASA Computers donated a Tyan 1662 motherboard. Joe McGuckin joe@via.net of ViaNet Communications donated a Kingston ethernet controller. Jack O'Neill jack@diamond.xtalwind.net donated an NCR 53C875 SCSI controller card. Ulf Zimmermann ulf@Alameda.net of Alameda Networks donated 128MB of memory, a 4 Gb disk drive and the case. Direct funding: The following individuals and businesses have generously contributed direct funding to the project: Annelise Anderson ANDRSN@HOOVER.STANFORD.EDU &a.dillon; Blue Mountain Arts Epilogue Technology Corporation &a.sef; Global Technology Associates, Inc Don Scott Wilde Gianmarco Giovannelli gmarco@masternet.it Josef C. Grosch joeg@truenorth.org Robert T. Morris &a.chuckr; Kenneth P. Stox ken@stox.sa.enteract.com of Imaginary Landscape, LLC. Dmitry S. Kohmanyuk dk@dog.farm.org Laser5 of Japan (a portion of the profits from sales of their various FreeBSD CDROMs). Fuki Shuppan Publishing Co. donated a portion of their profits from Hajimete no FreeBSD (FreeBSD, Getting started) to the FreeBSD and XFree86 projects. ASCII Corp. donated a portion of their profits from several FreeBSD-related books to the FreeBSD project. Yokogawa Electric Corp has generously donated significant funding to the FreeBSD project. BuffNET Pacific Solutions Siemens AG via Andre Albsmeier andre.albsmeier@mchp.siemens.de Chris Silva ras@interaccess.com Hardware contributors: The following individuals and businesses have generously contributed hardware for testing and device driver development/support: BSDi for providing the Pentium P5-90 and 486/DX2-66 EISA/VL systems that are being used for our development work, to say nothing of the network access and other donations of hardware resources. Compaq has donated a variety of Alpha systems to the FreeBSD Project. Among the many generous donations are 4 AlphaStation DS10s, an AlphaServer DS20, AlphaServer 2100s, an AlphaServer 4100, 8 500Mhz Personal Workstations, 4 433Mhz Personal Workstations, and more! These machines are used for release engineering, package building, SMP development, and general development on the Alpha architecture. TRW Financial Systems, Inc. provided 130 PCs, three 68 GB file servers, twelve Ethernets, two routers and an ATM switch for debugging the diskless code. Dermot McDonnell donated the Toshiba XM3401B CDROM drive currently used in freefall. Chuck Robey chuckr@glue.umd.edu contributed his floppy tape streamer for experimental work. Larry Altneu larry@ALR.COM, and &a.wilko;, provided Wangtek and Archive QIC-02 tape drives in order to improve the wt driver. Ernst Winter ewinter@lobo.muc.de contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. Tekram Technologies sent one each of their DC-390, DC-390U and DC-390F FAST and ULTRA SCSI host adapter cards for regression testing of the NCR and AMD drivers with their cards. They are also to be applauded for making driver sources for free operating systems available from their FTP server . Larry M. Augustin contributed not only a Symbios Sym8751S SCSI card, but also a set of data books, including one about the forthcoming Sym53c895 chip with Ultra-2 and LVD support, and the latest programming manual with information on how to safely use the advanced features of the latest Symbios SCSI chips. Thanks a lot! Christoph Kukulies kuku@FreeBSD.org donated an FX120 12 speed Mitsumi CDROM drive for IDE CDROM driver development. Mike Tancsa mike@sentex.ca donated four various ATM PCI cards in order to help increase support of these cards as well as help support the development effort of the netatm ATM stack. Special contributors: BSDi (formerly Walnut Creek CDROM) has donated almost more than we can say (see the 'About the FreeBSD Project' section of the FreeBSD Handbook for more details). In particular, we would like to thank them for the original hardware used for freefall.FreeBSD.org, our primary development machine, and for thud.FreeBSD.org, a testing and build box. We are also indebted to them for funding various contributors over the years and providing us with unrestricted use of their T1 connection to the Internet. The interface business GmbH, Dresden has been patiently supporting &a.joerg; who has often preferred FreeBSD work over paid work, and used to fall back to their (quite expensive) EUnet Internet connection whenever his private connection became too slow or flaky to work with it... Berkeley Software Design, Inc. has contributed their DOS emulator code to the remaining BSD world, which is used in the doscmd command. The FreeBSD Core Team The FreeBSD core team constitutes the project's Board of Directors, responsible for deciding the project's overall goals and direction as well as managing specific areas of the FreeBSD project landscape. (in alphabetical order by last name): &contrib.core; Other &os; Teams The &os; project delegates certain individuals to work on various teams according to project needs. The following list contains the current information on those individuals and their designated areas: &contrib.staff; The FreeBSD Developers These are the people who have commit privileges and do the engineering work on the FreeBSD source tree. All core team members are also developers. (in alphabetical order by last name): &contrib.committers; The FreeBSD Documentation Project The FreeBSD Documentation Project is responsible for a number of different services, each service being run by an individual and his deputies (if any): Documentation Project Architect &a.doceng; Handbook Editor &a.doc; FAQ Editor &a.doc; News Editor &a.www; In the Press Editor &a.jkoshy; FreeBSD Really-Quick NewsLetter Editor Chris Coleman chrisc@vmunix.com Gallery Editor &a.phantom; Commercial Gallery Editor &a.josef; User Groups Editor &a.grog; FreeBSD &java; Project &a.patrick; Who is Responsible for What Documentation Project Manager &a.doceng; CVSup Mirror Site Coordinator &a.cvsup-master; which includes: &a.kuriyama; (responsible), &a.jdp; (advisor) FTP/WWW Mirror Site Coordinator &a.mirror-admin; which includes: &a.kuriyama;, &a.kensmith; Localization &a.ache; Postmaster &a.dhw;, &a.jmb; Release Coordination &a.re; headed by &a.murray; Public Relations & Corporate Liaison Seat open Security Officers &a.security-officer; headed by &a.nectar; Source Repository Managers Principal: &a.peter; Assistants: &a.markm;, &a.joe; Website Management &a.www; Ports Manager &a.portmgr; which includes: &a.kris;, &a.marcus;, &a.will;, &a.linimon;, &a.eik;, &a.krion;, &a.erwin; (secretary) Standards &a.wollman; XFree86 Project, Inc. Liaison &a.rich; GNATS Administrators &a.ceri; &a.keramida; &a.linimon; Bugmeisters &a.ceri; &a.keramida; &a.linimon; Donations Liaison Office &a.donations; which includes: &a.mwlucas &a.nsayer &a.obrien &a.rwatson &a.trhodes Core Team Alumni core team The following people were members of the FreeBSD core team during the periods indicated. We thank them for their past efforts in the service of the FreeBSD project. In rough chronological order: &contrib.corealumni; Development Team Alumni development team The following people were members of the FreeBSD development team during the periods indicated. We thank them for their past efforts in the service of the FreeBSD project. In rough chronological order: &contrib.develalumni; Derived Software Contributors This software was originally derived from William F. Jolitz's 386BSD release 0.1, though almost none of the original 386BSD specific code remains. This software has been essentially re-implemented from the 4.4BSD-Lite release provided by the Computer Science Research Group (CSRG) at the University of California, Berkeley and associated academic contributors. There are also portions of NetBSD and OpenBSD that have been integrated into FreeBSD as well, and we would therefore like to thank all the contributors to NetBSD and OpenBSD for their work. Additional FreeBSD Contributors (in alphabetical order by first name): &contrib.additional; 386BSD Patch Kit Patch Contributors (in alphabetical order by first name): &contrib.386bsd;
diff --git a/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml b/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml index 014627f14f..25f16e6a31 100644 --- a/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml +++ b/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml @@ -1,692 +1,686 @@ -%man; - -%authors; - -%trademarks; - -%urls; + +%articles.ent; ]>
Setting up a CVS repository - the FreeBSD way Stijn Hoop
stijn@win.tue.nl
 2001 2002 2003 Stijn Hoop $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; This article describes the steps I took to set up a CVS repository that uses the same scripts the FreeBSD project uses in their setup. This has several advantages over a stock CVS setup, including more granular access control to the source tree and generation of readable email of every commit. Introduction Most of the open source software projects use CVS as their source code control system. While CVS is pretty good at this, it has its share of flaws and weaknesses. One of these is that sharing a source tree with other developers can quickly lead to a system administration nightmare, especially if one wishes to protect parts of the tree from general access. FreeBSD is one of the projects using CVS. It also has a large base of developers located around the world. They developed some scripts to make management of the repository easier. Recently, these scripts were revisited and normalized by &a.joe; to make it easier to reuse them in other projects. This article describes one method of using the new scripts. To make the most use of the information in this article, you need to be familiar with the basic method of operation of CVS. First setup It might be best to first perform this procedure with an empty test repository, to make sure you understand all consequences. As always, make sure you have recent, readable backups! Initializing the repository The first thing to do when setting up a new repository is to tell CVS to initialize it: &prompt.user; cvs -d path-to-repository init This tells CVS to create the CVSROOT administrative directory, where all the customization takes place. The repository group Now we will create the group which will own the repository. All committers need to be in this group, so that they can write to the repository. We will assume the FreeBSD default of ncvs for this group. &prompt.root; pw groupadd ncvs Next, you should &man.chown.8; the directory to the group you just added: &prompt.root; chown -R :ncvs path-to-your-repository This ensures that no one can write to the repository without proper group permissions. Getting the sources Now you need to obtain the CVSROOT directory from the FreeBSD repository. This is most easily done by checking it out from a FreeBSD anonymous CVS mirror. See the relevant chapter in the handbook for more information. Let us assume that the sources are stored in CVSROOT-freebsd in the current directory. Copying the FreeBSD scripts Next, we will copy the FreeBSD CVSROOT sources into your own repository. If you are accustomed to CVS, you might be thinking that you can just import the scripts, in an attempt to make synchronizing with later versions easier. However, it turns out that CVS has a deficiency in this area: when importing sources into the CVSROOT directory, it will not update the needed administrative files. In order to make it recognize those, you will need to checkin each file after importing them, losing the value of cvs import. Therefore, the recommended method is to simply copy over the scripts. It does not matter if the above paragraph did not make sense to you—the end result is the same. Simply check out your CVSROOT and copy the FreeBSD files over your local (untouched) copies: &prompt.user; cvs -d path-to-your-repository checkout CVSROOT &prompt.user; cd CVSROOT &prompt.user; cp ../CVSROOT-freebsd/* . &prompt.user; cvs add * Note that you will probably get a few warnings about some directories not being copied; this is normal, you do not need those. The scripts Now you have in your working directory an exact copy of the scripts that the FreeBSD project itself uses for their repository. A summary of what each file is used for is included below. access - this file is not used in the default setup. It is used in the FreeBSD project specific setup, where it controls access to the repository. You can remove this file if you do not wish to use this setup. avail - this file controls access to the repository. In this, you can specify groups of people that are allowed access to the repository, as well as disallow commits on a per-directory basis. You should tailor it to contain the groups and directories that will be in your repository. cfg.pm - this file parses your configuration, and provides the default configuration. You should not make changes to this file. Instead, put your configuration changes in cfg_local.pm. cfg_local.pm - this file contains all configurable parameters of the system. You should configure all sorts of settings here, such as where commit mail is send, on what hosts people can commit, and others. More information on this below. checkoutlist - this files lists all files under control of CVS in this directory, apart from the standard ones created by cvs init. You should edit this to remove some FreeBSD-specific files. commit_prep.pl - this script performs various pre-commit checks, based on whether you enabled them in your cfg_local.pm. You should not have to touch this. commitcheck - this script is invoked directly from CVS. It first checks if the committer has access to the specified part of the tree using cvs_acls.pl, and then runs commit_prep.pl for the various pre-commit checks. If those are OK, CVS will allow the commit to proceed. You should not have to touch this file. commitinfo - this file is used by CVS to determine which script to run before a commit—in this case commitcheck. You should not have to touch this file. config - the configuration file for this repository. You should change this as needed, but most administrators can probably leave the defaults. More information on the options that can be set here can be found in the CVS manual. cvs_acls.pl - this script determines the committers identity, and whether he/she is allowed access to the tree. It does this based on the avail file. You should not have to touch this file. cvsignore - this file specifies files that CVS should not checkin in the repository. You can edit this as you wish. More information about this file is available in the CVS manual. cvswrappers - this file is used by CVS to enable or disable keyword expansion, or whether a file should be considered binary. You can edit this as you wish. More information about this file is available in the CVS manual. Note that the -t and -f options do not work correctly with client/server CVS. edithook - this file is not used any more, but kept for historic reasons. You can safely remove this file. editinfo - CVS uses this file for editor overrides. FreeBSD does not use this functionality, as parsing the log message is done by verifymsg and logcheck. This is because the editinfo functionality does not work properly with remote commits, or ones that use the -m or -F options. You should not have to touch this file. exclude - this file lists regular expressions that are used by commit_prep.pl to determine files which cannot contain a revision header. In the FreeBSD setup, all files under revision control need to have a revision header (like $FreeBSD$). All filenames that match one of the lines in this file are exempted from this check. You should add expressions to this file as you checkin files that cannot have a revision header. For the purpose of installing the scripts, it may be best to exclude CVSROOT/ from header checks. log_accum.pl - this is a script that takes the log message as provided by the logcheck script, and appends it to a log file in the repository for backup purposes. It also handles mailing out a message to an email address you provide (in cfg_local.pm). It hooks into CVS via loginfo. You should not have to touch this file. logcheck - this file parses the commit log message that committers provide, and attempts to sanitize it somewhat. It hooks into CVS via verifymsg. You should not have to touch this file. This script depends on a local FreeBSD hack of CVS: this version reads the log message back in after this script has modified it. The stock version of CVS does not do this which makes logcheck unable to clean up the log message, although it is still able to check that it is syntactically OK. CVS 1.11.2 can be configured to have the same behaviour as FreeBSD's version by setting RereadLogAfterVerify=always in the config file. loginfo - this file is used by CVS to control where log information is sent; log_accum.pl hooks in here. You should not have to touch this file. modules - this file retains its traditional meaning in CVS. You should remove the FreeBSD modules from the stock version. You can edit this as you wish. More information about this file is available in the CVS manual. notify - this file is used by CVS in case someone sets a watch on a file. It is not used in the FreeBSD repository. You can edit this as you wish. More information about this file is available in the CVS manual. options - this file is specific to the FreeBSD version of CVS, and is also supported by the Debian version. It contains the keyword to expand in revision headers. You should alter this to match the keyword you specified in cfg_local.pm (if you use that feature, which is FreeBSD specific for now). rcsinfo - this file maps directories in the repository to template files such as rcstemplate. By default, FreeBSD uses one template for the whole repository. You can add others to this file if you wish. rcstemplate - this file is the actual template committers will see when they make a checkin. You should edit this to describe the various extra parameters you defined in cfg_local.pm. tagcheck - this files controls access to tagging in the repository. The stock FreeBSD version disallows tags with names of RELENG*, because of the release engineering process. You should edit this file as desired. taginfo - this file maps tag operations on repository directories to access control scripts such as tagcheck. You should not have to touch this file. unwrap - this script can be used to automatically unwrap binary files (see cvswrappers) on checkout. It is not used in the current FreeBSD setup because the functionality it hooks into does not work well with remote commits. You should not have to touch this file. verifymsg - this file maps repository directories to post processor scripts of log messages such as logcheck. You should not have to touch this file. wrap - this script can be used to automatically wrap binary files (see cvswrappers) on checkin. It is not used in the current FreeBSD setup because the functionality it hooks into does not work well with remote commits. You should not have to touch this file. Customizing the scripts The next step is to set up the scripts so that they work in your environment. You should go over all files in the directory and make your customizations. In particular, you might want to do edit the following files: If you do not wish to use the FreeBSD specific features of the scripts, you can safely remove the access file: &prompt.user; cvs rm -f access Edit avail to contain the various repository directories in which you want to control access. Make sure you retain the avail||CVSROOT line, otherwise you will lock yourself out in the next step. The other thing you can add in this file are committer groups. By default, FreeBSD uses the access file to list all its committers in, but you can use any file you wish. You can also add groups if you want (the syntax is specified at the top of cvs_acls.pl). Edit cfg_local.pm to contain the options you want. In particular, you should take a look at the following configurable items: %TEMPLATE_HEADERS - these get processed by the log scripts, and inserted below the commit mail if present and non-empty in the commit message. You can probably remove the PR and MFC after entries. And of course you can add your own. $MAIL_BRANCH_HDR - if you want to insert a header into each commit mail describing the branch on which the commit was made, define this to match your setup. Or leave it empty if you do not want such a header. @COMMIT_HOSTS - define this to be a list of hosts on which people can commit. $MAILADDRS - set this to the admin or list address that should receive commit mail. @LOG_FILE_MAP - change this array as you wish - each regexp is matched on the directory of the commit, and the commit log message gets stored in the commitlogs subdirectory in the filename mentioned. $COMMITCHECK_EXTRA - if you do not want to use the FreeBSD specific access checks, you should remove the definition of $COMMITCHECK_EXTRA from this file. Changing the $IDHEADER parameter is only guaranteed to work on FreeBSD platforms; it depends on FreeBSD specific modifications to CVS. You can check cfg.pm to see which other options can be changed, but the above is a reasonable subset. Edit exclude to remove the FreeBSD specific entries (such as all lines beginning with ^ports/ etc.). Furthermore, comment out the lines beginning with ^CVSROOT/, and add one line with only ^CVSROOT/ on it. After the wrapper is installed, you can add your header to the files in the CVSROOT directory and restore these lines, but for now they will only be in the way when you try to commit later on. Edit modules, and delete all FreeBSD stuff. Add your own modules if you wish. This step is only necessary if you specified a value for $IDHEADER in cfg_local.pm (which only works using a FreeBSD modified CVS). Edit options to match the tag you specified in cfg_local.pm. A global search and replace of FreeBSD with your tag should suffice. Edit rcstemplate to contain the same keywords as specified in cfg_local.pm. Optionally remove the FreeBSD checks from tagcheck. You can simply add exit 0 to the top of the file to disable all checks on tagging. The last thing to do before you are finished, is to make sure the commitlogs can be stored. By default these are stored in the repository, in the commitlogs subdirectory of the CVSROOT directory. This directory needs to be created, so do the following: &prompt.user; mkdir commitlogs &prompt.user; cvs add commitlogs Now, after careful review, you should commit your changes. Be sure that you have granted yourself access to the CVSROOT directory in your avail before you do this, because otherwise you will lock yourself out. So make sure everything is as you intend, and then do the following: &prompt.user; cvs commit -m '- Initial FreeBSD scripts commit' Testing the setup You are ready for the first test: a forced commit to the avail file, to make sure everything works as expected. &prompt.user; cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' avail If everything works, congratulations! You now have a working setup of the FreeBSD scripts for your repository. If CVS still complains about something, go back and recheck if all of the above steps have been performed correctly. FreeBSD specific setup The FreeBSD project itself uses a slightly different setup, which also uses files from the freebsd subdirectory of the FreeBSD CVSROOT. The project uses this because of the large number of committers, which all would have to be in the same group. So, a simple wrapper was written which ensures that people have the correct credentials to commit, and then sets the group id to that of the repository. If your repository also needs this, the steps to set this up are documented below. But first an overview of the files involved. Files used in the FreeBSD setup access - this file controls access information. You should edit this file to include all members of your project. freebsd/commitmail.pl - this file is not used any more, but kept for historic reasons. You should not have to touch this file. freebsd/cvswrap.c - this is the source to the CVS wrapper that you will need to install to make all access checks actually work. More information on this below. You should edit the paths in the ACCESS and REALCVS macros to match your setup. freebsd/mailsend.c - this file is needed by the FreeBSD setup of the mailing lists. You should not have to touch this file. The procedure Edit the access file to contain only your username. Edit cvswrap.c to contain the correct path for your setup. This is defined in a macro named ACCESS. You should also change the location of the real cvs binary if it is not appropriate to your situation. The stock cvswrap.c expects to be a replacement for the systemwide cvs command, which will be moved to /usr/bin/ncvs. My copy of cvswrap.c has this: #define ACCESS "/local/cvsroot/CVSROOT/access" #define REALCVS "/usr/bin/ncvs" Next up is installing the wrapper to ensure you become the correct group when committing. The sources for this live in cvswrap.c in your CVSROOT. Compile the sources that you edited to include the correct paths: &prompt.user; cc -o cvs cvswrap.c And then install them (you have to be root for this step): &prompt.root; mv /usr/bin/cvs /usr/bin/ncvs &prompt.root; mv cvs /usr/bin/cvs &prompt.root; chown root:ncvs /usr/bin/cvs /usr/bin/ncvs &prompt.root; chmod o-rx /usr/bin/ncvs &prompt.root; chmod u-w,g+s /usr/bin/cvs This installs the wrapper as the default cvs command, making sure that anyone who wants to use the repository has to have the correct access levels. You can now remove everyone from your repository group. All access control is done by your wrapper, and this wrapper will set the correct group for access. Testing the setup Your wrapper should now be setup. You can of course test this by making a forced commit to the access file: &prompt.user; cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' access Again, if this fails, check to see whether all of the above steps have been executed correctly.
diff --git a/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml b/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml index 78f9f8a34d..86a2a800b5 100644 --- a/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml +++ b/en_US.ISO8859-1/articles/cvsup-advanced/article.sgml @@ -1,273 +1,270 @@ -%man; - - -%trademarks; + +%articles.ent; ]>
CVSup Advanced Points Salvo Bartolotta
bartequi@neomedia.it
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.general; The present article assumes a basic understanding of CVSup operation. It documents several delicate issues connected with source synchronization via CVSup, viz. effective solutions to the problem of stale files as well as special source updating cases; which issues are likely to cause apparently inexplicable troubles. Preface This document is the fruit of the author's attempts to fully understand the niceties of CVSup & source updating. :-) While the author has made every effort to make these pages as informative and correct as possible, he is only human and may have made all sorts of typos, mistakes, etc. He will be very grateful for any comments and/or suggestions you send to his e-mail address, bartequi@neomedia.it. Introduction If you have visited John Polstra's site and read his FAQ, you may have noticed Question 12 & 13. When updating any collection of sources (eg /usr/ports), &man.cvsup.1; makes use of the related checkouts file in order to perform the updating process in the most efficient and correct way. In this example (/usr/ports), the related checkouts file is /usr/sup/ports-all/checkouts.cvs:. if your base is /usr. A checkouts file contains information on the current status of your sources—in a way, a sort of photograph. This significant information enables cvsup to retrieve updates most effectively. Further, and maybe more important, it enables cvsup to correctly manage your sources by locally deleting any files no longer present in the repository, thus leaving no stale files on your system. In fact, without a checkouts file, cvsup would not know which files your collection was composed of (cf &man.cvsup.1; and the fallback method for details); as a result, it could not delete on your system those files no longer present in the repository. They would remain on your system (stale files), and might cause you subtle build failures or other trouble. For example, this problem is likely to occur if you first update your ports collection several weeks after you got your installation CD-ROMs. It is therefore recommended that you adopt the two-step procedure outlined in the CVSup FAQ (cf Q12, Q13); in subsequent sections, you will be given interesting and instructive concrete examples. A useful python script: <command>cvsupchk</command> Alternatively, in order to examine your sources for inconsistencies, you may wish to utilize the cvsupchk python script; which script is currently found in /usr/ports/net/cvsup/work/cvsup-16.1/contrib/cvsupchk, together with a nice README. Prerequisites: /usr/ports/net/cvsup &prompt.root; make extract python (also found in the ports collection :-)) a checkouts file for your collection of sources. If you are updating your sources for the very first time, of course you do not have a checkouts file. After installing python and updating your sources (eg /usr/ports), you can check them thus: &prompt.user; /path/to/cvsupchk -d /usr -c /usr/sup/ports-all/checkouts.cvs:. | more If you want to check your RELENG_4 sources: &prompt.user; /path/to/cvsupchk -d /usr -c /usr/sup/src-all/checkouts.cvs:RELENG_4 | more In each case, cvsupchk will inspect your sources for inconsistencies by utilizing the information contained in the related checkouts file. Such anomalies as deleted files being present (aka stale files), missing checked-out files, extra RCS files, and dead directories will be printed to standard output. In the next section, we will provide important, typical examples of source updating; which examples will show you the role of checkouts files and the dangers of negligent source management. Examples of more advanced source management How to safely change tags when updating <literal>src-all</literal> If you specify eg tag=A in your supfile, cvsup will create a checkouts file called checkouts.cvs:A: for instance, if tag=RELENG_4, a checkouts file called checkouts.cvs:RELENG_4 is generated. This file will be used to retrieve and/or store information identifying your 4-STABLE sources. When tracking src-all, if you wish to pass from tag=A to tag=B (A less/greater than B not making any difference) and if your checkouts file is checkouts.cvs:A, the following actions should be performed: &prompt.root; mv checkouts.cvs:A checkouts.cvs:B (This provides the subsequent step with the appropriate checkouts file) write a supfile whose collection line reads: src-all tag=B cvsup your sources using the new supfile. The cvsup utility will look for checkouts.cvs:B—in that the target is B; that is, cvsup will make use of the information contained therein to correctly manage your sources. The benefits: the sources are dealt with correctly (in particular, no stale files) less load is placed on the server, in that cvsup operates in the most efficient way. For example, A=RELENG_4, B=.. The period in B=. means -CURRENT. This is a rather typical update, from 4-STABLE to -CURRENT. While it is straightforward to downgrade your sources (eg from -CURRENT to -STABLE), downgrading a system is quite another matter. You are STRONGLY advised not to attempt such an operation, unless you know exactly what you are doing. Updating to the same tag as of a different date If you wish to switch from tag=A to tag=A as of a different GMT date (say, date=D), you will execute the following: write a supfile whose collection line reads: src-all tag=A date=D update your sources using the new supfile Whether the new date precedes that of the last sync operation with tag=A or not, it is immaterial. For example, in order to specify the date August 27, 2000, 10:00:00 GMT you write the line: src-all tag=RELENG_4 date=2000.08.27.10.00.00 The format of a date is rigid. You have to specify all the components of the date: century (20, ie the 21st century, must be supplied whereas 19, the past century, can be omitted), year, month, day, hour, minutes, seconds—as shown in the above example. For more information, please see &man.cvsup.1;. Whether or not a date is specified, the checkouts file is called checkouts.cvs:A (eg checkouts.cvs:RELENG_4). As a result, no particular action is needed in order to revert to the previous state: you have to modify the date in the supfile, and run csvup again. Updating your ports collection for the first time Since ports are tagged . (ie -CURRENT), you can correctly sync them for the first time by adding the date keyword (cf &man.cvsup.1; for the exact format): you should specify a date as close as possible to that of shipping of your ports tree. After cvsup has correctly created the ports checkouts file, which is precisely the goal of this first special sync operation, the date field must be removed; all subsequent updates will be carried out smoothly. If you have been reading the apparently nit-picking remarks in these sections, you will probably have recognized the potential for trouble in a source updating process. A number of people have actually run into problems. You have been warned. :-)
diff --git a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml index 88fd86c288..a007de13bf 100644 --- a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml +++ b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml @@ -1,327 +1,318 @@ -%man; - - -%freebsd; - - -%trademarks; - - -%urls; + +%articles.ent; ]>
Dialup firewalling with FreeBSD Marc Silver
marcs@draenor.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; This article documents how to set up a firewall using a PPP dialup with FreeBSD and IPFW, and specifically with firewalling over a dialup with a dynamically assigned IP address. This document does not include information on setting up an initial PPP connection. For more information on setting up a PPP connection, consult the &man.ppp.8; manual page. Preface Dialup Firewalling with FreeBSD This document outlines the steps required to set up firewalling with FreeBSD when an IP address is assigned dynamically by your ISP. While every effort has been made to make this document as informative and correct as possible, you are welcome to mail any corrections, comments or suggestions to the author at marcs@draenor.org. Kernel Options In order to use IPFW, support for it must be compiled into the kernel. For more information on how to recompile the kernel, please see the kernel configuration section in the Handbook. The following options must be added into your kernel configuration file for IPFW support: options IPFIREWALL Enables the kernel firewall code. This document assumes that you are running &os; 5.X. Users running &os; 4.X will need to recompile their kernels with IPFW2 support. &os; 4.X users should consult the &man.ipfw.8; manual page for more information on using IPFW2 on their systems, and should pay particular attention to the USING IPFW2 IN FreeBSD-STABLE section. options IPFIREWALL_VERBOSE Sends logged packets to the system logger. options IPFIREWALL_VERBOSE_LIMIT=500 Limits the number of times a matching entry may be logged. This allows you to log firewall activity without the risk of syslog flooding in the event of a denial of service attack. 500 is a reasonable number to use, but may be adjusted based on your requirements. Once the kernel recompile has been completed, do not reboot your system. Doing so may result in you being locked out of your own system. You must only reboot once the ruleset is in place and all the relevant configuration files have been updated. Changing <filename>/etc/rc.conf</filename> to load the firewall /etc/rc.conf needs to be slightly modified in order to tell the system about the firewall and to specify the location for our rules file. Add the following lines to /etc/rc.conf: firewall_enable="YES" firewall_script="/etc/firewall/fwrules" For more information on the functions of these statements take a look at /etc/defaults/rc.conf and read &man.rc.conf.5; Enable PPP's network address translation In order to allow clients on your network to connect via your gateway, you will need to enable PPP's network address translation (NAT). In order to use PPP's NAT functions, add the following lines to /etc/rc.conf: ppp_enable="YES" ppp_mode="auto" ppp_nat="YES" ppp_profile="your_profile" Take care to change your_profile to the name of your own dialup profile. The rule set for the firewall This is the point where we define the firewall rules for your system. The ruleset that we're about to describe is a generic template for most dialup users. While it will not suit the exact needs of every user, it provides you with a basic idea of how IPFW works and should be fairly easy to customize. First, let's start with the basics of closed firewalling. Closed firewalling is based on the idea that everything is denied by default. The system administrator may then explicitly add rules for traffic that he or she would like to allow. Rules should be in the order of allow first, and then deny. The premise is that you add the rules for everything you would like to allow, and then everything else is automatically denied. Following that, let's create the directory where we will store our firewall rules. In this example, we'll use /etc/firewall. Change into the directory and edit the file fwrules as we specified in rc.conf. Please note that you can change this filename to anything you wish. This guide merely gives an example of a filename you may want to use. Now, let's look at a nicely commented sample firewall file. # Define the firewall command (as in /etc/rc.firewall) for easy # reference. Helps to make it easier to read. fwcmd="/sbin/ipfw" # Define our outside interface. With userland-ppp this # defaults to tun0. oif="tun0" # Define our inside interface. This is usually your network # card. Be sure to change this to match your own network # interface. iif="fxp0" # Force a flushing of the current rules before we reload. $fwcmd -f flush # Check the state of all packets. $fwcmd add check-state # Stop spoofing on the outside interface. $fwcmd add deny ip from any to any in via $oif not verrevpath # Allow all connections that we initiate, and keep their state. # but deny established connections that don't have a dynamic rule. $fwcmd add allow ip from me to any out via $oif keep-state $fwcmd add deny tcp from any to any established in via $oif # Allow all connections within our network. $fwcmd add allow ip from any to any via $iif # Allow all local traffic. $fwcmd add allow all from any to any via lo0 $fwcmd add deny all from any to 127.0.0.0/8 $fwcmd add deny ip from 127.0.0.0/8 to any # Allow internet users to connect to the port 22 and 80. # This example specifically allows connections to the sshd and a # webserver. $fwcmd add allow tcp from any to me dst-port 22,80 in via $oif setup keep-state # Allow ICMP packets: remove type 8 if you don't want your host # to be pingable. $fwcmd add allow icmp from any to any via $oif icmptypes 0,3,8,11,12 # Deny and log all the rest. $fwcmd add deny log ip from any to any You now have a fully functional firewall that only allows connections to ports 22 and 80 and will log any other connection attempts. You may now safely reboot and the firewall should be automatically started and the ruleset loaded. If you find this incorrect in any way or experience any problems, or have any suggestions to improve this page, please email me. Questions I get messages like limit 500 reached on entry 2800 and after that I my machine stops logging denied packets that match that rule number. Is my firewall still working? This merely means that the maximum logging count for the rule has been reached. The rule itself is still working, but it will no longer log until such time as you reset the logging counters. An example of how to clear your counters can be found below: &prompt.root; ipfw resetlog Alternatively, you may increase the log limit in your kernel configuration with the option as described above. You may also change this limit (without recompiling your kernel and having to reboot) by using the net.inet.ip.fw.verbose_limit &man.sysctl.8; value. There must be something wrong. I followed your instructions to the letter and now I am locked out. This tutorial assumes that you are running userland-ppp, therefore the supplied rule set operates on the tun0 interface, which corresponds to the first connection made with &man.ppp.8; (a.k.a. user-ppp). Additional connections would use tun1, tun2 and so on. You should also note that &man.pppd.8; uses the ppp0 interface instead, so if you start the connection with &man.pppd.8; you must substitute tun0 for ppp0. A quick way to edit the firewall rules to reflect this change is shown below. The original rule set is backed up as fwrules_tun0. &prompt.user; cd /etc/firewall /etc/firewall&prompt.user; su Password: /etc/firewall&prompt.root; mv fwrules fwrules_tun0 /etc/firewall&prompt.root; cat fwrules_tun0 | sed s/tun0/ppp0/g > fwrules To know whether you are currently using &man.ppp.8; or &man.pppd.8; you can examine the output of &man.ifconfig.8; once the connection is up. E.g., for a connection made with &man.pppd.8; you would see something like this (showing only the relevant lines): &prompt.user; ifconfig (skipped...) ppp0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xff000000 (skipped...) On the other hand, for a connection made with &man.ppp.8; (user-ppp) you should see something similar to this: &prompt.user; ifconfig (skipped...) ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 (skipped...) tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 (IPv6 stuff skipped...) inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xffffff00 Opened by PID xxxxx (skipped...)
diff --git a/en_US.ISO8859-1/articles/diskless-x/article.sgml b/en_US.ISO8859-1/articles/diskless-x/article.sgml index ea08205ceb..f4100741c0 100644 --- a/en_US.ISO8859-1/articles/diskless-x/article.sgml +++ b/en_US.ISO8859-1/articles/diskless-x/article.sgml @@ -1,362 +1,358 @@ -%man; - - -%trademarks; + +%articles.ent; ]>
Diskless X Server: a how to guide Jerry Kendall
jerry@kcis.com
28-December-1996 1996 Jerry Kendall &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.microsoft; &tm-attrib.sun; &tm-attrib.general; With the help of some friends on the FreeBSD-hackers list, I have been able to create a diskless X terminal. The creation of the X terminal required first creating a diskless system with minimal utilities mounted via NFS. These same steps were used to create 2 separate diskless systems. The first is altair.example.com. A diskless X terminal that I run on my old 386DX-40. It has a 340Meg hard disk but, I did not want to change it. So, it boots from antares.example.com across a Ethernet. The second system is a 486DX2-66. I set up a diskless FreeBSD (complete) that uses no local disk. The server in that case is a Sun 670MP running &sunos; 4.1.3. The same setup configuration was needed for both. I am sure that there is stuff that needs to be added to this. Please send me any comments. Creating the boot floppy (On the diskless system) Since the network boot loaders will not work with some of the TSR's and such that &ms-dos; uses, it is best to create a dedicated boot floppy or, if you can, create an &ms-dos; menu that will (via the config.sys/autoexec.bat files) ask what configuration to load when the system starts. The later is the method that I use and it works great. My &ms-dos; (6.x) menu is below. <filename>config.sys</filename> [menu] menuitem=normal, normal menuitem=unix, unix [normal] .... normal config.sys stuff ... [unix] <filename>autoexec.bat</filename> @ECHO OFF goto %config% :normal ... normal autoexec.bat stuff ... goto end :unix cd \netboot nb8390.com :end Getting the network boot programs (On the server) Compile the net-boot programs that are located in /usr/src/sys/i386/boot/netboot. You should read the comments at the top of the Makefile. Adjust as required. Make a backup of the original in case something goes wrong. When the build is done, there should be 2 &ms-dos; executables, nb8390.com and nb3c509.com. One of these two programs will be what you need to run on the diskless server. It will load the kernel from the boot server. At this point, put both programs on the &ms-dos; boot floppy created earlier. Determine which program to run (On the diskless system) If you know the chipset that your Ethernet adapter uses, this is easy. If you have the NS8390 chipset, or a NS8390 based chipset, use nb8390.com. If you have a &tm.3com; 509 based chipset, use the nb3C509.com boot program. If you are not sure which you have, try using one, if it says No adapter found, try the other. Beyond that, you are pretty much on your own. Booting across the network Boot the diskless system with out any config.sys/autoexec.bat files. Try running the boot program for your Ethernet adapter. My Ethernet adapter is running in WD8013 16bit mode so I run nb8390.com C:> cd \netboot C:> nb8390 Boot from Network (Y/N) ? Y BOOTP/TFTP/NFS bootstrap loader ESC for menu Searching for adapter.. WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66 Searching for server... At this point, my diskless system is trying to find a machine to act as a boot server. Make note of the addr line above, you will need this number later. Reset the diskless system and modify your config.sys and autoexec.bat files to do these steps automatically for you. Perhaps in a menu. If you had to run nb3c509.com instead of nb8390.com the output is the same as above. If you got No adapter found at the Searching for adapter... message, verify that you did indeed set the compile time defines in the Makefile correctly. Allowing systems to boot across the network (On the server) Make sure the /etc/inetd.conf file has entries for tftp and bootps. Mine are listed below: tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot # # Additions by who ever you are bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab If you have to change the /etc/inetd.conf file, send a HUP signal to &man.inetd.8;. To do this, get the process ID of inetd with ps -ax | grep inetd | grep -v grep. Once you have it, send it a HUP signal. Do this by kill -HUP <pid>. This will force inetd to re-read its config file. Did you remember to note the addr line from the output of the boot loader on the diskless system? Guess what, here is where you need it. Add an entry to /etc/bootptab (maybe creating the file). It should be laid out identical to this: altair:\ :ht=ether:\ :ha=004001432666:\ :sm=255.255.255.0:\ :hn:\ :ds=199.246.76.1:\ :ip=199.246.76.2:\ :gw=199.246.76.1:\ :vm=rfc1048: The lines are as follows: altair the diskless systems name without the domain name. ht=ether the hardware type of ethernet. ha=004001432666 the hardware address (the number noted above). sm=255.255.255.0 the subnet mask. hn tells server to send client's hostname to the client. ds=199.246.76.1 tells the client who the domain server is. ip=199.246.76.2 tells the client what its IP address is. gw=199.246.76.1 tells the client what the default gateway is. vm=... just leave it there. Be sure to set up the IP addresses correctly, the addresses above are my own. Create the directory /tftpboot on the server it will contain the configuration files for the diskless systems that the server will serve. These files will be named cfg.ip where ip is the IP address of the diskless system. The config file for altair is /tftpboot/cfg.199.246.76.2. The contents is: rootfs 199.246.76.1:/DiskLess/rootfs/altair hostname altair.example.com The line hostname altair.example.com simply tells the diskless system what its fully qualified domain name is. The line rootfs 199.246.76.1:/DiskLess/rootfs/altair tells the diskless system where its NFS mountable root filesystem is located. The NFS mounted root filesystem will be mounted read only. The hierarchy for the diskless system can be re-mounted allowing read-write operations if required. I use my spare 386DX-40 as a dedicated X terminal. The hierarchy for altair is: / /bin /etc /tmp /sbin /dev /dev/fd /usr /var /var/run The actual list of files is: -r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel -r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh -rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc -rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys -rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts -rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair -r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init -r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig -r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs -r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot -r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount -r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local -r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV If you are not using &man.devfs.5; (which is the default in FreeBSD 5.X), you should make sure that you do not forget to run MAKEDEV all in the dev directory. My /etc/rc for altair is: #!/bin/sh # PATH=/bin:/ export PATH # # configure the localhost /sbin/ifconfig lo0 127.0.0.1 # # configure the ethernet card /sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00 # # mount the root filesystem via NFS /sbin/mount antares:/DiskLess/rootfs/altair / # # mount the /usr filesystem via NFS /sbin/mount antares:/DiskLess/usr /usr # /usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1 # # Reboot after X exits /sbin/reboot # # We blew up.... exit 1 Any comments and all questions welcome.
diff --git a/en_US.ISO8859-1/articles/euro/article.sgml b/en_US.ISO8859-1/articles/euro/article.sgml index 3d7cb36628..1e30e30ae2 100644 --- a/en_US.ISO8859-1/articles/euro/article.sgml +++ b/en_US.ISO8859-1/articles/euro/article.sgml @@ -1,358 +1,352 @@ -%man; - - -%trademarks; - - -%urls; + +%articles.ent; ]>
The Euro symbol on <systemitem class="osname">FreeBSD</systemitem> Aaron Kaplan
aaron@lo-res.org
2002 2003 The FreeBSD Documentation Project $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; This document will try to help you in getting started with the new Euro Symbol on your new keyboard that you had to buy in early 2002 because of the switch to the new common currency. We will first focus on the more important parts like being able to correctly display the symbol on the console. Later sections will deal with configuring particular programs like X11. Lots of helpful input came from Oliver Fromme, Tom Rhodes and countless others. Thanks! Without you this article would not have been possible! The Euro in a nutshell If you already feel comfortable with localization as described in the FreeBSD Handbook you might be only interested in the following facts which will get you started quickly: ISO8859-15 This is a slight modification of the commonly used ISO8859-1 character map. It includes the Euro symbol. Used for the LANG, LC_CTYPE environment variables. iso15-8x16.fnt The &man.vidcontrol.1; font for the console /usr/share/syscons/keymaps/*.iso.kbd Appropriate keyboard maps depending on your language. Set your keymap entry in rc.conf to one of these. LC_CTYPE Used to specify the correct character type in your locale. XkbLayout "lang(euro)" XFree86 config option. /usr/X11R6/lib/X11/fonts/*/fonts.alias Be sure to adapt your X11 fonts to -*-..-*-iso8859-15 A general remark In the following sections we will often refer to ISO8859-15. This is the standard notation starting with FreeBSD 4.5. In older versions, the standard notation was either ISO_8859-15 or DIS_8859-15. If you are using an older version of FreeBSD, be sure to take a look at /usr/share/locale/ in order to find out which naming convention is in place. The console Setting up your console font Depending on your console resolution and size you will need one of the following lines in rc.conf: font8x16="iso15-8x16.fnt" # from /usr/share/syscons/fonts/* font8x14="iso15-8x14.fnt" font8x8="iso15-8x8.fnt" This will effectively select the ISO8859-15 also known as Latin-9 font. ISO8859-15 is a variation of ISO8859-1. You can tell the difference between the two by looking at the Euro symbol: its decimal value is 164. In ISO8859-1 you will notice a circle with four little strokes at the corners. This is often termed the universal currency symbol. In ISO8859-15, instead of the little circle, you have the Euro Symbol. Otherwise the fonts are more or less identical. As of the time of this writing the only usable font seems to be iso15-8x16.fnt. The others seem to only show ISO8859-1 even though the name suggest otherwise. By specifying this font some console applications will look garbled. This is due to the fact that they assume you are using a different font/character set such as ANSI 850. One notable example is sysinstall. However most of the time this should not be of much concern. As the next step you should either reboot your system to let the changes take effect or (manually) take the steps that would have been taken at the system startup: &prompt.user; vidcontrol -f iso15-8x16.fnt To check if the font has been selected execute the following short awk script: #!/usr/bin/awk -f BEGIN { for(i=160;i<180;i++) printf"%3d %c\n",i,i } The result should reveal the Euro sign at position 164. Setting up your keyboard for the Euro Most keyboard maps should already be set up correctly. I.e: If you have a german keyboard and your Umlaut keys are working, you can safely skip this section since the keyboard already maps whatever key combination is necessary (e.g.: Alt Gre) to decimal value 164. If running into problems, the best way to check is to take a look at /usr/share/syscons/keymaps/*.kbd. The format of the key mapping files is described in &man.keyboard.4;. &man.kbdcontrol.1; can be used to load a custom keymap. Once the correct keyboard map is selected, it should be added to /etc/rc.conf with the line: keymap="german.iso" # or another map As stated above, this step has most probably already been taken by you at installation time (with sysinstall). If not, either reboot or load the new keymap via &man.kbdcontrol.1;. To verify the keyboard mapping, switch to a new console and at the login prompt, instead of logging in, try to type the Euro key. If it is not working, either file a bug report via &man.send-pr.1; or make sure you in fact chose the right keyboard map. At this stage the Euro key will not yet work in bash or tcsh. Fixing the environment variables The shells (bash, tcsh) revert to the &man.readline.3; library which in turn respects the LC_CTYPE environment variable. LC_CTYPE must be set before the shell is completely running. Luckily it suffices to add the line: export LC_CTYPE=de_DE.ISO8859-15 to your .bash_profile (bash), or: setenv LC_CTYPE de_DE.ISO8859-15 to your .login (tcsh) file. Of course, de_DE should be replaced by your language. Next, log out, log back in again, and verify your Euro key is working. By now most console applications should respond to the Euro key. Extra configuration steps for special programs like pine might still be necessary however. An alternative to modifying .login and .bash_profile is to set the environment variables through the &man.login.conf.5; mechanism. This approach has the advantage of assigning login classes to certain users (e.g. French users, Italian users, etc) in one place. Modifying X11 Modify /etc/XF86Config in the following manner: Option "XkbLayout" "de(euro)" Again, replace de with your language. By now, the keyboard should be set up correctly. As in the console section, the correct font must be chosen. For KDE, go to the KDE control center -> Personalization -> Country & Language -> Charset and change it to ISO8859-15. Similar steps apply to kmail and other applications. Another good idea is to modify your fonts.alias files. Notably the fixed font should be changed to the right character set: The author's /usr/X11R6/lib/X11/fonts/misc/fonts.alias looks like this: ! $Xorg: fonts.alias,v 1.3 2000/08/21 16:42:31 coskrey Exp $ fixed -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-15 variable -*-helvetica-bold-r-normal-*-*-120-*-*-*-*-iso8859-15 (...) As in the console sections, special applications still have ISO8859-1 fonts configured in their respective &man.xrdb.1; databases. One notable example is xterm. As a general rule of thumb it suffices to change the corresponding configuration file in /usr/X11R6/lib/X11/app-defaults and add the correct font. Let us demonstrate this with xterm. &prompt.root; cd /usr/X11R6/lib/X11/app-defaults/ &prompt.root; vi XTerm Add the following line to the beginning of the file: *font: -misc-fixed-medium-r-normal-*-*-120-*-*-c-*-iso8859-15 Finally, restart X and make sure, fonts can be displayed by executing the above awk script. All major applications should respect the keyboard mapping and the font settings. Open problems Of course, the author would like to receive feedback. In addition, at least let me know if you have fixes for one of these open problems: Describe alternative way of setting up XFree86: x11/xkeycaps Settings in GNOME Settings in XFCE Settings for (X)Emacs Describe UTF-8 Describe libiconv as a effective way to convert between ISO8859-15 and UTF-{8,16} from within applications
diff --git a/en_US.ISO8859-1/articles/explaining-bsd/article.sgml b/en_US.ISO8859-1/articles/explaining-bsd/article.sgml index 7baf91824e..34434add36 100644 --- a/en_US.ISO8859-1/articles/explaining-bsd/article.sgml +++ b/en_US.ISO8859-1/articles/explaining-bsd/article.sgml @@ -1,567 +1,561 @@ -%man; - -%freebsd; - -%trademarks; - -%urls; + +%articles.ent; ]>
Explaining BSD Greg Lehey
grog@FreeBSD.org
 &tm-attrib.freebsd; &tm-attrib.apple; &tm-attrib.linux; &tm-attrib.opengroup; &tm-attrib.sun; &tm-attrib.xfree86; &tm-attrib.general; In the open source world, the word Linux is almost synonymous with Operating System, but it is not the only open source &unix; operating system. According to the Internet Operating System Counter, as of April 1999 31.3% of the world's network connected machines run Linux. 14.6% run BSD &unix;. Some of the world's largest web operations, such as Yahoo!, run BSD. The world's busiest FTP server, ftp.cdrom.com, uses BSD to transfer 1.4 TB of data a day. Clearly this is not a niche market: BSD is a well-kept secret. So what is the secret? Why is BSD not better known? This white paper addresses these and other questions. Throughout this paper, differences between BSD and Linux will be noted like this. What is BSD? BSD stands for Berkeley Software Distribution. It is the name of distributions of source code from the University of California, Berkeley, which were originally extensions to AT&T's Research &unix; operating system. Several open source operating system projects are based on a release of this source code known as 4.4BSD-Lite. In addition, they comprise a number of packages from other Open Source projects, including notably the GNU project. The overall operating system comprises: The BSD kernel, which handles process scheduling, memory management, symmetric multi-processing (SMP), device drivers, etc. Unlike the Linux kernel, there are several different BSD kernels with differing capabilities. The C library, the base API for the system. The BSD C library is based on code from Berkeley, not the GNU project. Utilities such as shells, file utilities, compilers and linkers. Some of the utilities are derived from the GNU project, others are not. The X Window system, which handles graphical display. The X Window system used in most versions of BSD is maintained by a separate project, the &xfree86; project. This is the same code as Linux uses. BSD does not normally specify a graphical desktop such as GNOME or KDE, though these are available. Many other programs and utilities. What, a real &unix;? The BSD operating systems are not clones, but open source derivatives of AT&T's Research &unix; operating system, which is also the ancestor of the modern &unix; System V. This may surprise you. How could that happen when AT&T has never released its code as open source? It is true that AT&T &unix; is not open source, and in a copyright sense BSD is very definitely not &unix;, but on the other hand, AT&T has imported sources from other projects, noticeably the Computer Sciences Research Group of the University of California in Berkeley, CA. Starting in 1976, the CSRG started releasing tapes of their software, calling them Berkeley Software Distribution or BSD. Initial BSD releases consisted mainly of user programs, but that changed dramatically when the CSRG landed a contract with the Defense Advanced Projects Research Agency (DARPA) to upgrade the communications protocols on their network, ARPANET. The new protocols were known as the Internet Protocols, later TCP/IP after the most important protocols. The first widely distributed implementation was part of 4.2BSD, in 1982. In the course of the 1980s, a number of new workstation companies sprang up. Many preferred to license &unix; rather than developing operating systems for themselves. In particular, Sun Microsystems licensed &unix; and implemented a version of 4.2BSD, which they called &sunos;. When AT&T themselves were allowed to sell &unix; commercially, they started with a somewhat bare-bones implementation called System III, to be quickly followed by System V. The System V code base did not include networking, so all implementations included additional software from the BSD, including the TCP/IP software, but also utilities such as the csh shell and the vi editor. Collectively, these enhancements were known as the Berkeley Extensions. The BSD tapes contained AT&T source code and thus required a &unix; source license. By 1990, the CSRG's funding was running out, and it faced closure. Some members of the group decided to release the BSD code, which was Open Source, without the AT&T proprietary code. This finally happened with the Networking Tape 2, usually known as Net/2. Net/2 was not a complete operating system: about 20% of the kernel code was missing. One of the CSRG members, William F. Jolitz, wrote the remaining code and released it in early 1992 as 386BSD. At the same time, another group of ex-CSRG members formed a commercial company called Berkeley Software Design Inc. and released a beta version of an operating system called BSD/386, which was based on the same sources. The name of the operating system has since changed to BSD/OS. 386BSD never became a stable operating system. Instead, two other projects split off from it in 1993: NetBSD and FreeBSD. The two projects originally diverged due to differences in patience waiting for improvements to 386BSD: the NetBSD people started early in the year, and the first version of FreeBSD was not ready until the end of the year. In the meantime, the code base had diverged sufficiently to make it difficult to merge. In addition, the projects had different aims, as we will see below. In 1996, a further project, OpenBSD, split off from NetBSD. Why is BSD not better known? For a number of reasons, BSD is relatively unknown: The BSD developers are often more interested in polishing their code than marketing it. Much of Linux's popularity is due to factors external to the Linux projects, such as the press, and to companies formed to provide Linux services. Until recently, the open source BSDs had no such proponents. BSD developers tend to be more experienced than Linux developers, and have less interest in making the system easy to use. Newcomers tend to feel more comfortable with Linux. In 1992, AT&T sued BSDI, the vendor of BSD/386, alleging that the product contained AT&T-copyrighted code. The case was settled out of court in 1994, but the spectre of the litigation continues to haunt people. As recently as March 2000 an article published on the web claimed that the court case had been recently settled. One detail that the lawsuit did clarify is the naming: in the 1980s, BSD was known as BSD &unix;. With the elimination of the last vestige of AT&T code from BSD, it also lost the right to the name &unix;. Thus you will see references in book titles to the 4.3BSD &unix; operating system and the 4.4BSD operating system. There is a perception that the BSD projects are fragmented and belligerent. The Wall Street Journal spoke of balkanization of the BSD projects. Like the law suit, this perception bases mainly on ancient history. Comparing BSD and Linux So what is really the difference between, say, Debian Linux and FreeBSD? For the average user, the difference is surprisingly small: Both are &unix; like operating systems. Both are developed by non-commercial projects (this does not apply to many other Linux distributions, of course). In the following section, we will look at BSD and compare it to Linux. The description applies most closely to FreeBSD, which accounts for an estimated 80% of the BSD installations, but the differences from NetBSD and OpenBSD are small. Who owns BSD? No one person or corporation owns BSD. It is created and distributed by a community of highly technical and committed contributors all over the world. Some of the components of BSD are Open Source projects managed by a different project maintainer. How is BSD developed and updated? The BSD kernels are developed and updated following the Open Source development model. Each project maintains a publicly accessible source tree under the Concurrent Versions System (CVS), which contains all source files for the project, including documentation and other incidental files. CVS allows users to check out (in other words, to extract a copy of) any desired version of the system. A large number of developers worldwide contribute to improvements to BSD. They are divided into three kinds: Contributors write code or documentation. They are not permitted to commit (add code) directly to the source tree. In order for their code to be included in the system, it must be reviewed and checked in by a registered developer, known as a committer. Committers are developers with write access to the source tree. In order to become a committer, an individual must show ability in the area in which he is active. It is at the individual committer's discretion whether he should obtain authority before committing changes to the source tree. In general, an experienced committer may make changes which are obviously correct without obtaining consensus. For example, a documentation project committer may correct typographical or grammatical errors without review. On the other hand, developers making far-reaching or complicated changes are expected to submit their changes for review before committing them. In extreme cases, a core team member with a function such as Principal Architect may order that changes be removed from the tree, a process known as backing out. All committers receive mail describing each individual commit, so it is not possible to commit secretly. The Core team. FreeBSD and NetBSD each have a core team which manages the project. The core teams developed in the course of the projects, and their role is not always well-defined. It is not necessary to be a developer in order to be a core team member, though it is normal. The rules for the core team vary from one project to the other, but in general they have more say in the direction of the project than non-core team members have. This arrangement differs from Linux in a number of ways: No one person controls the content of the system. In practice, this difference is overrated, since the Chief Architect can require that code be backed out, and even in the Linux project several people are permitted to make changes. On the other hand, there is a central repository, a single place where you can find the entire operating system sources, including all older versions. BSD projects maintain the entire Operating System, not only the kernel. This distinction is only marginally useful: neither BSD nor Linux is useful without applications. The applications used under BSD are frequently the same as the applications used under Linux. As a result of the formalized maintenance of a single CVS source tree, BSD development is clear, and it is possible to access any version of the system by release number or by date. CVS also allows incremental updates to the system: for example, the FreeBSD repository is updated about 100 times a day. Most of these changes are small. BSD releases Each BSD project provides the system in three different releases. As with Linux, releases are assigned a number such as 1.4.1 or 3.5. In addition, the version number has a suffix indicating its purpose: The development version of the system is called CURRENT. FreeBSD assigns a number to CURRENT, for example FreeBSD 5.0-CURRENT. NetBSD uses a slightly different naming scheme and appends a single-letter suffix which indicates changes in the internal interfaces, for example NetBSD 1.4.3G. OpenBSD does not assign a number ("OpenBSD-current"). All new development on the system goes into this branch. At regular intervals, between two and four times a year, the projects bring out a RELEASE version of the system, which is available on CD-ROM and for free download from FTP sites, for example OpenBSD 2.6-RELEASE or NetBSD 1.4-RELEASE. The RELEASE version is intended for end users and is the normal version of the system. NetBSD also provides patch releases with a third digit, for example NetBSD 1.4.2. As bugs are found in a RELEASE version, they are fixed, and the fixes are added to the CVS tree. In FreeBSD, the resultant version is called the STABLE version, while in NetBSD and OpenBSD it continues to be called the RELEASE version. Smaller new features can also be added to this branch after a period of test in the CURRENT branch. By contrast, Linux maintains two separate code trees: the stable version and the development version. Stable versions have an even minor version number, such as 2.0, 2.2 or 2.4. Development versions have an odd minor version number, such as 2.1, 2.3 or 2.5. In each case, the number is followed by a further number designating the exact release. In addition, each vendor adds their own userland programs and utilities, so the name of the distribution is also important. Each distribution vendor also assigns version numbers to the distribution, so a complete description might be something like TurboLinux 6.0 with kernel 2.2.14 What versions of BSD are available? In contrast to the numerous Linux distributions, there are only three open source BSDs. Each BSD project maintains its own source tree and its own kernel. In practice, though, there appear to be fewer divergences between the userland code of the projects than there is in Linux. It is difficult to categorize the goals of each project: the differences are very subjective. Basically, FreeBSD aims for high performance and ease of use by end users, and is a favourite of web content providers. It runs on PCs and Compaq's Alpha processors. The FreeBSD project has significantly more users than the other projects. NetBSD aims for maximum portability: of course it runs NetBSD. It runs on machines from palmtops to large servers, and has even been used on NASA space missions. It is a particularly good choice for running on old non-Intel hardware. OpenBSD aims for security and code purity: it uses a combination of the open source concept and rigorous code reviews to create a system which is demonstrably correct, making it the choice of security-conscious organizations such as banks, stock exchanges and US Government departments. Like NetBSD, it runs on a number of platforms. There are also two additional BSD &unix; operating systems which are not open source, BSD/OS and Apple's &macos; X: BSD/OS is the oldest of the 4.4BSD derivatives. It is not open source, though source code licenses are available at relatively low cost. It resembles FreeBSD in many ways. &macos; X is the latest version of the operating system for Apple Computer Inc.'s &macintosh; line. The BSD core of this operating system, Darwin, is available as a fully functional open source operating system for x86 and PPC computers. The Aqua/Quartz graphics system and many other proprietary aspects of &macos; X remain closed-source, however. Several Darwin developers are also FreeBSD committers, and vice-versa. How does the BSD license differ from the GNU Public license? Linux is available under the GNU General Public License (GPL), which is designed to eliminate closed source software. In particular, any derivative work of a product released under the GPL must also be supplied with source code if requested. By contrast, the BSD license is less restrictive: binary-only distributions are allowed. This is particularly attractive for embedded applications. What else should I know? Since fewer applications are available for BSD than Linux, the BSD developers created a Linux compatibility package, which allows Linux programs to run under BSD. The package includes both kernel modifications, in order to correctly perform Linux system calls, and Linux compatibility files such as the C library. There is no noticeable difference in execution speed between a Linux application running on a Linux machine and a Linux application running on a BSD machine of the same speed. The all from one supplier nature of BSD means that upgrades are much easier to handle than is frequently the case with Linux. BSD handles library version upgrades by providing compatibility modules for earlier library versions, so it is possible to run binaries which are several years old with no problems. Which should I use, BSD or Linux? What does this all mean in practice? Who should use BSD, who should use Linux? This is a very difficult question to answer. Here are some guidelines: If it ain't broke, don't fix it: If you already use an open source operating system, and you are happy with it, there is probably no good reason to change. BSD systems, in particular FreeBSD, can have notably higher performance than Linux. But this is not across the board. In many cases, there is little or no difference in performance. In some cases, Linux may perform better than FreeBSD. In general, BSD systems have a better reputation for reliability, mainly as a result of the more mature code base. The BSD license may be more attractive than the GPL. BSD can execute Linux code, while Linux can not execute BSD code. As a result, more software is available for BSD than for Linux. Who provides support, service, and training for BSD? BSDi have always supported BSD/OS, and they have recently announced support contracts for FreeBSD. In addition, each of the projects has a list of consultants for hire: FreeBSD, NetBSD, and OpenBSD.
diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml b/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml index 8be9192048..ea477f5369 100644 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml +++ b/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml @@ -1,646 +1,642 @@ -%man; - -%freebsd; - -%trademarks; + +%articles.ent; FreeBSD From Scratch"> ]>
FreeBSD From Scratch Jens Schweikhardt
schweikh@FreeBSD.org
 2002,2003,2004 Jens Schweikhardt $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.general; This article describes my efforts at &scratch.ap;: a fully automated installation of a customized &os; system compiled from source, including compilation of all your favorite ports and configured to match your idea of the perfect system. If you think make world is a wonderful concept, &scratch.ap; extends it to make evenmore. Introduction Have you ever upgraded your system with make world? There is a problem if you have only one system on your disks. If the installworld fails partway through, you are left with a broken system that might not even boot any longer. Or maybe the installworld runs smoothly but the new kernel does not boot. Then it is time to reach for the Fixit CD and dig for those backups you have taken half a year ago. I believe in the wipe your disks when upgrading systems paradigm. Wiping disks, or rather partitions, makes sure there is no old cruft left lying around, something which most upgrade procedures just do not care about. But wiping the partitions means you have to also recompile/reinstall all your ports and packages and then redo all your carefully crafted configuration tweaks. If you think that this task should be automated as well, read on. Why would I (not) want &scratch.ap;? This is a legitimate question. We have sysinstall and the well known way to compile the kernel and the userland tools. The problem with sysinstall is that it is severely limited in what, where and how it can install. It is normally used to install pre-built distribution sets and packages from some other source (CD, DVD, FTP). It cannot install the result of a make buildworld. It cannot install a second system under a directory in a running system. It cannot install in Vinum partitions. It cannot compile ports, only install precompiled packages. It is hard to script or to make arbitrary post-installation changes. Last but not least, sysinstall is semi-officially at its End-Of-Life. The well known way to build and install the world, as described in the Handbook, by default replaces the existing system. Only the kernel and modules are saved. System binaries, headers and a lot of other files are overwritten; obsolete files are still present and can cause surprises. If the upgrade fails for any reason, it may be hard or even impossible to restore the previous state of the system. &scratch.ap; solves all these problems. The strategy is simple: use a running system to install a new system under an empty directory tree, while new partitions are mounted appropriately in that tree. Many config files can be copied to the appropriate place and &man.mergemaster.8; can take care of those that cannot. Arbitrary post-configuration of the new system can be done from within the old system, up to the point where you can chroot to the new system. In other words, we go through three stages, where each stage consists of either running a shell script or invoke make: stage_1.sh: Create a new bootable system under an empty directory and merge or copy as many files as are necessary. Then boot the new system. stage_2.sh: Install desired ports. stage_3.mk: Do post-configuration for software installed in previous stage. Once you have used &scratch.ap; to build a second system and found it works satisfactorily for a couple of weeks, you can then use it again to reinstall the original system. From now on, whenever you feel like an update is in order, you simply toggle the partitions you want to wipe and reinstall. Maybe you have heard of or even tried Linux From Scratch, or LFS for short. LFS also describes how to build and install a system from scratch in empty partitions using a running system. The focus in LFS seems to be to show the role of each system component (such as kernel, compiler, devices, shell, terminal database, etc) and the details of each component's installation. &scratch.ap; does not go into that much detail. My goal is to provide an automated and complete installation, not explaining all the gory details that go on under the hood when making the world. In case you want to explore &os; at this level of detail, start looking at /usr/src/Makefile and follow the actions of a make buildworld. There are also downsides in the approach taken by &scratch.ap; that you should bear in mind. While compiling the ports during stage two the system can not be used for its usual duties. If you run a production server you have to consider the downtime caused by stage two. The ports compiled by stage_2.conf.default below require about 4 hours to build on an AMD1800+ SCSI system with 10krpm disks and 1GB of RAM. If you prefer to install packages instead of ports, you can significantly reduce the downtime to about 10 minutes. Prerequisites For going the &scratch.ap; way, you need to have: A running &os; system with sources and a ports tree. At least one unused partition where the new system will be installed. Experience with running &man.mergemaster.8;. Or at least no fear doing so. If you have no or only a slow link to the Internet: the distfiles for your favorite ports. Basic knowledge of shell scripting with the Bourne shell, &man.sh.1;. Finally, you should also be able to tell your boot loader how to boot the new system, either interactively, or by means of a config file. Stage One: System Installation The first version of this article used a single shell script for stage one where all your customization had to be done by editing the script. After valuable user feedback I have decided to separate the code and data in the scripts. This allows to have different configuration data sets to install different systems without changing any of the code scripts. The code script for stage one is stage_1.sh and when run with exactly one argument, like &prompt.root; ./stage_1.sh default will read its configuration from stage_1.conf.default and write a log to stage_1.log.default. Further below you find my stage_1.conf.default. You need to customize it in various places to match your idea of the perfect system. I have tried to extensively comment the places you should adapt. The configuration script must provide four shell functions, create_file_systems, create_etc_fstab, copy_files and all_remaining_customization (in case it matters: this is also the sequence in which they will be called from stage_1.sh). The points to ponder are: Partition layout. I do not subscribe to the idea of a single huge partition for the whole system. My systems generally have at least one partition for /, /usr and /var with /tmp symlinked to /var/tmp. In addition I share the file systems for /home (user homes), /home/ncvs (&os; CVS repository replica), /usr/ports (the ports tree), /src (various checked out src trees) and /share (other shared data without the need for backups, like the news spool). Luxury items. What you want immediately after booting the new system and even before starting stage two. The reason for not simply chrooting to the new system during stage one and installing all my beloved ports is that in theory and in practice there are bootstrap and consistency issues: stage one has your old kernel running, but the chrooted environment consists of new binaries and headers. If the new binaries use a new system call, these binaries will die with SIGSYS, Bad system call, because the old kernel does not have that system call. I have seen other issues when I tried building lang/perl5. Before you run stage_1.sh make sure you have completed the usual tasks in preparation for make installworld installkernel, like: configured your kernel config file successfully completed make buildworld successfully completed make buildkernel KERNCONF=whatever When you run stage_1.sh for the first time, and the config files copied from your running system to the new system are not up-to-date with respect to what is under /usr/src, mergemaster will ask you how to proceed. I recommend merging the changes. If you get tired of going through the dialogues you can simply update the files on your running system once (Only if this is an option. You probably do not want to do this if one of your systems runs -STABLE and the other -CURRENT. The changes may be incompatible). Subsequent mergemaster invocations will detect that the RCS version IDs match those under /usr/src and skip the file. The stage_1.sh script will stop at the first command that fails (returns a non-zero exit status) due to set -e, so you cannot overlook errors. It will also stop if you use an unset environment variable, probably due to a typo. You should correct any errors in your version of stage_1.conf.default before you go on. In stage_1.sh we invoke mergemaster. Even if none of the files requires a merge, it will display and ask at the end *** Comparison complete Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] no Please answer no or just hit Enter. The reason is that mergemaster will have left a few zero sized files below /var/tmp/temproot.stage1 which will be copied to the new system later (unless already there). After that it will list the files it installed, making use of a pager, &man.more.1; by default, optionally &man.less.1;: *** You chose the automatic install option for files that did not exist on your system. The following were installed for you: /newroot/etc/defaults/rc.conf ... /newroot/COPYRIGHT (END) Type q to quit the pager. Then you will be informed about login.conf: *** You installed a login.conf file, so make sure that you run '/usr/bin/cap_mkdb /newroot/etc/login.conf' to rebuild your login.conf database Would you like to run it now? y or n [n] The answer does not matter since we will run &man.cap.mkdb.1; in any case. Here is the author's stage_1.conf.default, which you need to modify substantially. The comments give you enough information what to change. Please pay attention to the &man.newfs.8; commands. While you can not create new file systems on mounted partitions, the script will happily erase any unmounted /dev/da0s1a, /dev/da0s1e and /dev/da2s1e. This can be enough to ruin your day, so be sure to modify the device names. Download stage_1.conf.default . Running this script installs a system that when booted provides: Inherited users and groups. Firewalled Internet connectivity over Ethernet and PPP. Correct time zone and NTP. Some more minor configuration, like /etc/ttys and inetd. Other areas are prepared for configuration, but will not work until stage two is completed. For example we have copied files to configure printing and X11. Printing however is likely to need applications not found in the base system, like &postscript; utilities. X11 will not run before we have compiled the server, libraries and programs. Stage Two: Ports Installation It is also possible to install the (precompiled) packages at this stage, instead of compiling ports. In this case, stage_2.sh would be nothing more than a list of pkg_add commands. I trust you know how to write such a script. Here we concentrate on the more flexible and traditional way of using the ports. The following stage_2.sh script is how I install my favorite ports. It can be run any number of times and will skip all ports that are already installed. It supports the dryrun option () to just show what would be done. You run it like stage_1.sh with exactly one argument to denote a config file, e.g. &prompt.root; ./stage_2.sh default which will read the list of ports from stage_2.conf.default. The list of ports consists of lines with two or more space separated words: the category and the port, optionally followed by an installation command that will compile and install the port (default: make install BATCH=yes < /dev/null). Empty lines and lines starting with # are ignored. Most of the time it suffices to only name category and port. A few ports however can be fine tuned by specifying make variables, e.g.: www mozilla make WITHOUT_MAILNEWS=yes WITHOUT_CHATZILLA=yes install In fact you can specify arbitrary shell commands, so you are not restricted to simple make invocations: java linux-sun-jdk13 yes | make install news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install Note that the line for news/inn-stable is an example for a one-shot shell variable assignment to CONFIGURE_ARGS. The port Makefile will use this as an initial value and augment some other essential args. The difference to specifying a make variable on the command line with news inn-stable make CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" install is that the latter will override instead of augment. It depends on the particular port which method you want. Be careful that your ports do not use an interactive install, i.e. they should not try to read from stdin other than what you explicitly give them on stdin. If they do, they will read the next line(s) from your list of ports in the here-document and get confused. If stage_2.sh mysteriously skips a port or stops processing, this is likely the reason. Below is stage_2.conf.default. A log file named LOGDIR/category+port is created for each port it actually installs. Download stage_2.conf.default. Stage Three You have installed your beloved ports during stage two. Some ports require a little bit of configuration. This is what stage three, the post-configuration is for. I could have integrated this post-configuration at the end of the stage_2.sh script. However, I think there is a conceptual difference between installing a port and modifying its out-of-the-box configuration that warrants a separate stage. I have chosen to implement stage three as a Makefile because this allows easy selection of what you want to configure simply by running: &prompt.root; make -f stage_3.mk target As with stage_2.sh make sure you have stage_3.mk available after booting the new system, either by putting it on a shared partition or copying it somewhere on the new system. Limitations The automated installation of a port may prove difficult if it is interactive and does not support make BATCH=YES install. For a few ports the interaction is nothing more than typing yes when asked to accept some license. If such input is read from the standard input, we simply pipe the appropriate answers to the installation command (usually make install; this is how I deal with java/linux-sun-jdk14 in stage_2.conf.default). This strategy for example does not work for editors/staroffice52, which requires that X11 is running. The installation procedure involves a fair amount of clicking and typing, so it cannot be automated like other ports can. However the following workaround does the trick for me: first I create a staroffice package on the old system with &prompt.root; cd /usr/ports/editors/staroffice52 &prompt.root; make package ===> Building package for staroffice-5.2_1 Creating package /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz Registering depends:. Creating bzip'd tar ball in '/usr/ports/editors/staroffice52/staroffice-5.2_1.tbz' and during stage two I simply use: &prompt.root; pkg_add /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz You should also be aware of upgrade issues for config files. In general you do not know when and if the format or contents of a config file changes. A new group may be added to /etc/group, or /etc/passwd may gain another field. All of this has happened in the past. Simply copying a config file from the old to the new system may be enough most of the time, but in these cases it was not. If you update a system the canonical way (by overwriting the old files) you are expected to use mergemaster to deal with changes where you effectively want to merge your local config with potentially new items. Unfortunately, mergemaster is only available for base system files, not for anything installed by ports. Some third party software seems to be especially designed to keep me on my toes by changing the config file format every fortnight. To detect such silent changes, I keep a copy of the modified config files in the same place where I keep stage_3.mk and compare the result with a make rule, e.g. for apache's httpd.conf in target config_apache with @if ! cmp -s /usr/local/etc/apache2/httpd.conf httpd.conf; then \ echo "ATTENTION: the httpd.conf has changed. Please examine if"; \ echo "the modifications are still correct. Here is the diff:"; \ diff -u /usr/local/etc/apache2/httpd.conf httpd.conf; \ fi If the diff is innocuous I can make the message go away with cp /usr/local/etc/apache2/httpd.conf httpd.conf. I have used &scratch.ap; several times to update a 5-CURRENT to 5-CURRENT, i.e. I have never tried to install a 5-CURRENT from a 4-STABLE system or vice versa. Due to the number of changes between different major release numbers I would expect this process to be a bit more involved. Using &scratch.ap; for upgrades within the realm of 4-STABLE should work painlessly (although I have not yet tried it.) Users of 4-STABLE may want to consider the following areas: If you do not use the device file system, &man.devfs.5;, you may want to create devices for some of your hardware with &man.MAKEDEV.8; in all_remaining_customization. The Files Here are the three files you need beside the config files already shown above. This is the stage_1.sh script, which you should not need to modify. Download stage_1.sh. This is the stage_2.sh script. You may want to modify the variables at the beginning. Download stage_2.sh. This is my stage_3.mk to give you an idea how to automate all reconfiguration. Download stage_3.mk.
diff --git a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml b/en_US.ISO8859-1/articles/filtering-bridges/article.sgml index 99c31812d2..123545c19e 100644 --- a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml +++ b/en_US.ISO8859-1/articles/filtering-bridges/article.sgml @@ -1,403 +1,397 @@ -%man; - -%freebsd; - -%trademarks; - -%urls; + +%articles.ent; ]>
Filtering Bridges Alex Dupre
ale@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.intel; &tm-attrib.general; Often it is useful to divide one physical network (like an Ethernet) into two separate segments without having to create subnets, and use a router to link them together. The device that connects the two networks in this way is called a bridge. A FreeBSD system with two network interfaces is enough in order to act as a bridge. A bridge works by scanning the addresses of MAC level (Ethernet addresses) of the devices connected to each of its network interfaces and then forwarding the traffic between the two networks only if the source and the destination are on different segments. Under many points of view a bridge is similar to an Ethernet switch with only two ports. Why use a filtering bridge? More and more frequently, thanks to the lowering costs of broad band Internet connections (xDSL) and also because of the reduction of available IPv4 addresses, many companies are connected to the Internet 24 hours on 24 and with few (sometimes not even a power of 2) IP addresses. In these situations it is often desirable to have a firewall that filters incoming and outgoing traffic from and towards Internet, but a packet filtering solution based on router may not be applicable, either due to subnetting issues, the router is owned by the connectivity supplier (ISP), or because it does not support such functionalities. In these scenarios the use of a filtering bridge is highly advised. A bridge-based firewall can be configured and inserted between the xDSL router and your Ethernet hub/switch without any IP numbering issues. How to Install Adding bridge functionalities to a FreeBSD system is not difficult. Since 4.5 release it is possible to load such functionalities as modules instead of having to rebuild the kernel, simplifying the procedure a great deal. In the following subsections I will explain both installation ways. Do not follow both instructions: a procedure excludes the other one. Select the best choice according to your needs and abilities. Before going on, be sure to have at least two Ethernet cards that support the promiscuous mode for both reception and transmission, since they must be able to send Ethernet packets with any address, not just their own. Moreover, to have a good throughput, the cards should be PCI bus mastering cards. The best choices are still the Intel ðerexpress; Pro, followed by the &tm.3com; 3c9xx series. To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) in order to distinguish clearly which interface is connected to the router and which to the inner network. Kernel Configuration So you have decided to use the older but well tested installation method. To begin, you have to add the following rows to your kernel configuration file: options BRIDGE options IPFIREWALL options IPFIREWALL_VERBOSE The first line is to compile the bridge support, the second one is the firewall and the third one is the logging functions of the firewall. Now it is necessary to build and install the new kernel. You may find detailed instructions in the Building and Installing a Custom Kernel section of the FreeBSD Handbook. Modules Loading If you have chosen to use the new and simpler installation method, the only thing to do now is add the following row to /boot/loader.conf: bridge_load="YES" In this way, during the system startup, the bridge.ko module will be loaded together with the kernel. It is not required to add a similar row for the ipfw.ko module, since it will be loaded automatically after the execution of the steps in the following section. Final Preparation Before rebooting in order to load the new kernel or the required modules (according to the previously chosen installation method), you have to make some changes to the /etc/rc.conf configuration file. The default rule of the firewall is to reject all IP packets. Initially we will set up an firewall, in order to verify its operation without any issue related to packet filtering (in case you are going to execute this procedure remotely, such configuration will avoid you to remain isolated from the network). Put these lines in /etc/rc.conf: firewall_enable="YES" firewall_type="open" firewall_quiet="YES" firewall_logging="YES" The first row will enable the firewall (and will load the module ipfw.ko if it is not compiled in the kernel), the second one to set up it in mode (as explained in /etc/rc.firewall), the third one to not show rules loading and the fourth one to enable logging support. About the configuration of the network interfaces, the most used way is to assign an IP to only one of the network cards, but the bridge will work equally even if both interfaces or none has a configured IP. In the last case (IP-less) the bridge machine will be still more hidden, as inaccessible from the network: to configure it, you have to login from console or through a third network interface separated from the bridge. Sometimes, during the system startup, some programs require network access, say for domain resolution: in this case it is necessary to assign an IP to the external interface (the one connected to Internet, where DNS server resides), since the bridge will be activated at the end of the startup procedure. It means that the fxp0 interface (in our case) must be mentioned in the ifconfig section of the /etc/rc.conf file, while the xl0 is not. Assigning an IP to both the network cards does not make much sense, unless, during the start procedure, applications should access to services on both Ethernet segments. There is another important thing to know. When running IP over Ethernet, there are actually two Ethernet protocols in use: one is IP, the other is ARP. ARP does the conversion of the IP address of a host into its Ethernet address (MAC layer). In order to allow the communication between two hosts separated by the bridge, it is necessary that the bridge will forward ARP packets. Such protocol is not included in the IP layer, since it exists only with IP over Ethernet. The FreeBSD firewall filters exclusively on the IP layer and therefore all non-IP packets (ARP included) will be forwarded without being filtered, even if the firewall is configured to not permit anything. Now it is time to reboot the system and use it as before: there will be some new messages about the bridge and the firewall, but the bridge will not be activated and the firewall, being in mode, will not avoid any operations. If there are any problems, you should sort them out now before proceeding. Enabling the Bridge At this point, to enable the bridge, you have to execute the following commands (having the shrewdness to replace the names of the two network interfaces fxp0 and xl0 with your own ones): &prompt.root; sysctl net.link.ether.bridge.config=fxp0:0,xl0:0 &prompt.root; sysctl net.link.ether.bridge.ipfw=1 &prompt.root; sysctl net.link.ether.bridge.enable=1 The first row specifies which interfaces should be activated by the bridge, the second one will enable the firewall on the bridge and finally the third one will enable the bridge. If you have &os; 5.1-RELEASE or previous the sysctl variables are spelled differently. See &man.bridge.4; for details. At this point you should be able to insert the machine between two sets of hosts without compromising any communication abilities between them. If so, the next step is to add the net.link.ether.bridge.[blah]=[blah] portions of these rows to the /etc/sysctl.conf file, in order to have them execute at startup. Configuring The Firewall Now it is time to create your own file with custom firewall rules, in order to secure the inside network. There will be some complication in doing this because not all of the firewall functionalities are available on bridged packets. Furthermore, there is a difference between the packets that are in the process of being forwarded and packets that are being received by the local machine. In general, incoming packets are run through the firewall only once, not twice as is normally the case; in fact they are filtered only upon receipt, so rules that use or will never match. Personally, I use which is an older syntax, but one that has a sense when you read it. Another limitation is that you are restricted to use only or commands for packets filtered by a bridge. Sophisticated things like , or are not available. Such options can still be used, but only on traffic to or from the bridge machine itself (if it has an IP address). New in FreeBSD 4.0, is the concept of stateful filtering. This is a big improvement for UDP traffic, which typically is a request going out, followed shortly thereafter by a response with the exact same set of IP addresses and port numbers (but with source and destination reversed, of course). For firewalls that have no statekeeping, there is almost no way to deal with this sort of traffic as a single session. But with a firewall that can remember an outgoing UDP packet and, for the next few minutes, allow a response, handling UDP services is trivial. The following example shows how to do it. It is possible to do the same thing with TCP packets. This allows you to avoid some denial of service attacks and other nasty tricks, but it also typically makes your state table grow quickly in size. Let's look at an example setup. Note first that at the top of /etc/rc.firewall there are already standard rules for the loopback interface lo0, so we should not have to care for them anymore. Custom rules should be put in a separate file (say /etc/rc.firewall.local) and loaded at system startup, by modifying the row of /etc/rc.conf where we defined the firewall: firewall_type="/etc/rc.firewall.local" You have to specify the full path, otherwise it will not be loaded with the risk to remain isolated from the network. For our example imagine to have the fxp0 interface connected towards the outside (Internet) and the xl0 towards the inside (LAN). The bridge machine has the IP 1.2.3.4 (it is not possible that your ISP can give you a class A address like this, but for our example it is good). # Things that we have kept state on before get to go through in a hurry add check-state # Throw away RFC 1918 networks add drop all from 10.0.0.0/8 to any in via fxp0 add drop all from 172.16.0.0/12 to any in via fxp0 add drop all from 192.168.0.0/16 to any in via fxp0 # Allow the bridge machine to say anything it wants # (if the machine is IP-less do not include these rows) add pass tcp from 1.2.3.4 to any setup keep-state add pass udp from 1.2.3.4 to any keep-state add pass ip from 1.2.3.4 to any # Allow the inside hosts to say anything they want add pass tcp from any to any in via xl0 setup keep-state add pass udp from any to any in via xl0 keep-state add pass ip from any to any in via xl0 # TCP section # Allow SSH add pass tcp from any to any 22 in via fxp0 setup keep-state # Allow SMTP only towards the mail server add pass tcp from any to relay 25 in via fxp0 setup keep-state # Allow zone transfers only by the slave name server [dns2.nic.it] add pass tcp from 193.205.245.8 to ns 53 in via fxp0 setup keep-state # Pass ident probes. It is better than waiting for them to timeout add pass tcp from any to any 113 in via fxp0 setup keep-state # Pass the "quarantine" range add pass tcp from any to any 49152-65535 in via fxp0 setup keep-state # UDP section # Allow DNS only towards the name server add pass udp from any to ns 53 in via fxp0 keep-state # Pass the "quarantine" range add pass udp from any to any 49152-65535 in via fxp0 keep-state # ICMP section # Pass 'ping' add pass icmp from any to any icmptypes 8 keep-state # Pass error messages generated by 'traceroute' add pass icmp from any to any icmptypes 3 add pass icmp from any to any icmptypes 11 # Everything else is suspect add drop log all from any to any Those of you who have set up firewalls before may notice some things missing. In particular, there are no anti-spoofing rules, in fact we did not add: add deny all from 1.2.3.4/8 to any in via fxp0 That is, drop packets that are coming in from the outside claiming to be from our network. This is something that you would commonly do to be sure that someone does not try to evade the packet filter, by generating nefarious packets that look like they are from the inside. The problem with that is that there is at least one host on the outside interface that you do not want to ignore: the router. But usually, the ISP anti-spoofs at their router, so we do not need to bother that much. The last rule seems to be an exact duplicate of the default rule, that is, do not let anything pass that is not specifically allowed. But there is a difference: all suspected traffic will be logged. There are two rules for passing SMTP and DNS traffic towards the mail server and the name server, if you have them. Obviously the whole rule set should be flavored to personal taste, this is only a specific example (rule format is described accurately in the &man.ipfw.8; man page). Note that in order for relay and ns to work, name service lookups must work before the bridge is enabled. This is an example of making sure that you set the IP on the correct network card. Alternatively it is possible to specify the IP address instead of the host name (required if the machine is IP-less). People that are used to setting up firewalls are probably also used to either having a or a rule for ident packets (TCP port 113). Unfortunately, this is not an applicable option with the bridge, so the best thing is to simply pass them to their destination. As long as that destination machine is not running an ident daemon, this is relatively harmless. The alternative is dropping connections on port 113, which creates some problems with services like IRC (the ident probe must timeout). The only other thing that is a little weird that you may have noticed is that there is a rule to let the bridge machine speak, and another for internal hosts. Remember that this is because the two sets of traffic will take different paths through the kernel and into the packet filter. The inside net will go through the bridge, while the local machine will use the normal IP stack to speak. Thus the two rules to handle the different cases. The in via fxp0 rules work for both paths. In general, if you use rules throughout the filter, you will need to make an exception for locally generated packets, because they did not come in via any of our interfaces. Contributors Many parts of this article have been taken, updated and adapted from an old text about bridging, edited by Nick Sayer. A pair of inspirations are due to an introduction on bridging by Steve Peterson. A big thanks to Luigi Rizzo for the implementation of the bridge code in FreeBSD and for the time he has dedicated to me answering all of my related questions. A thanks goes out also to Tom Rhodes who looked over my job of translation from Italian (the original language of this article) into English.
diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml index b988270d3a..ae33695464 100644 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ b/en_US.ISO8859-1/articles/fonts/article.sgml @@ -1,985 +1,979 @@ -%freebsd; - -%man; - -%trademarks; - -%urls; + +%articles.ent; ]>
Fonts and FreeBSD A Tutorial Dave Bodenstab
imdave@synet.net
Wed Aug 7, 1996 &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.apple; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.general; This document contains a description of the various font files that may be used with FreeBSD and the syscons driver, X11, Ghostscript and Groff. Cookbook examples are provided for switching the syscons display to 80x60 mode, and for using type 1 fonts with the above application programs. Introduction There are many sources of fonts available, and one might ask how they might be used with FreeBSD. The answer can be found by carefully searching the documentation for the component that one would like to use. This is very time consuming, so this tutorial is an attempt to provide a shortcut for others who might be interested. Basic terminology There are many different font formats and associated font file suffixes. A few that will be addressed here are: .pfa, .pfb &postscript; type 1 fonts. The .pfa is the Ascii form and .pfb the Binary form. .afm The font metrics associated with a type 1 font. .pfm The printer font metrics associated with a type 1 font. .ttf A &truetype; font .fot An indirect reference to a TrueType font (not an actual font) .fon, .fnt Bitmapped screen fonts The .fot file is used by &windows; as sort of a symbolic link to the actual &truetype; font (.ttf) file. The .fon font files are also used by Windows. I know of no way to use this font format with FreeBSD. What font formats can I use? Which font file format is useful depends on the application being used. FreeBSD by itself uses no fonts. Application programs and/or drivers may make use of the font files. Here is a small cross reference of application/driver to the font type suffixes: Driver syscons .fnt Application Ghostscript .pfa, .pfb, .ttf X11 .pfa, .pfb Groff .pfa, .afm Povray .ttf The .fnt suffix is used quite frequently. I suspect that whenever someone wanted to create a specialized font file for their application, more often than not they chose this suffix. Therefore, it is likely that files with this suffix are not all the same format; specifically, the .fnt files used by syscons under FreeBSD may not be the same format as a .fnt file one encounters in the &ms-dos;/&windows; environment. I have not made any attempt at using other .fnt files other than those provided with FreeBSD. Setting a virtual console to 80x60 line mode First, an 8x8 font must be loaded. To do this, /etc/rc.conf should contain the line (change the font name to an appropriate one for your locale): font8x8="iso-8x8" # font 8x8 from /usr/share/syscons/fonts/* (or NO). The command to actually switch the mode is &man.vidcontrol.1;: &prompt.user; vidcontrol VGA_80x60 Various screen-oriented programs, such as &man.vi.1;, must be able to determine the current screen dimensions. As this is achieved this through ioctl calls to the console driver (such as &man.syscons.4;) they will correctly determine the new screen dimensions. To make this more seamless, one can embed these commands in the startup scripts so it takes place when the system boots. To do this is add this line to /etc/rc.conf allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens References: &man.rc.conf.5;, &man.vidcontrol.1;. Using type 1 fonts with X11 X11 can use either the .pfa or the .pfb format fonts. The X11 fonts are located in various subdirectories under /usr/X11R6/lib/X11/fonts. Each font file is cross referenced to its X11 name by the contents of the fonts.dir file in each directory. There is already a directory named Type1. The most straight forward way to add a new font is to put it into this directory. A better way is to keep all new fonts in a separate directory and use a symbolic link to the additional font. This allows one to more easily keep track of ones fonts without confusing them with the fonts that were originally provided. For example: Create a directory to contain the font files &prompt.user; mkdir -p /usr/local/share/fonts/type1 &prompt.user; cd /usr/local/share/fonts/type1 Place the .pfa, .pfb and .afm files here One might want to keep readme files, and other documentation for the fonts here also &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.pfb . &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.afm . Maintain an index to cross reference the fonts &prompt.user; echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX Now, to use a new font with X11, one must make the font file available and update the font name files. The X11 font names look like: -bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 | | | | | | | | | | | | \ \ | | | | | \ \ \ \ \ \ \ +----+- character set | | | | \ \ \ \ \ \ \ +- average width | | | | \ \ \ \ \ \ +- spacing | | | \ \ \ \ \ \ +- vertical res. | | | \ \ \ \ \ +- horizontal res. | | | \ \ \ \ +- points | | | \ \ \ +- pixels | | | \ \ \ foundry family weight slant width additional style A new name needs to be created for each new font. If you have some information from the documentation that accompanied the font, then it could serve as the basis for creating the name. If there is no information, then you can get some idea by using &man.strings.1; on the font file. For example: &prompt.user; strings showboat.pfb | more %!FontType1-1.0: Showboat 001.001 %%CreationDate: 1/15/91 5:16:03 PM %%VMusage: 1024 45747 % Generated by Fontographer 3.1 % Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten. FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup /UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse {save true}{false}ifelse}{false}ifelse 12 dict begin /FontInfo 9 dict dup begin /version (001.001) readonly def /FullName (Showboat) readonly def /FamilyName (Showboat) readonly def /Weight (Medium) readonly def /ItalicAngle 0 def /isFixedPitch false def /UnderlinePosition -106 def /UnderlineThickness 16 def /Notice (Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def end readonly def /FontName /Showboat def --stdin-- Using this information, a possible name might be: -type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 The components of our name are: Foundry Lets just name all the new fonts type1. Family The name of the font. Weight Normal, bold, medium, semibold, etc. From the &man.strings.1; output above, it appears that this font has a weight of medium. Slant roman, italic, oblique, etc. Since the ItalicAngle is zero, roman will be used. Width Normal, wide, condensed, extended, etc. Until it can be examined, the assumption will be normal. Additional style Usually omitted, but this will indicate that the font contains decorative capital letters. Spacing proportional or monospaced. Proportional is used since isFixedPitch is false. All of these names are arbitrary, but one should strive to be compatible with the existing conventions. A font is referenced by name with possible wild cards by an X11 program, so the name chosen should make some sense. One might begin by simply using …-normal-r-normal-…-p-… as the name, and then use &man.xfontsel.1; to examine it and adjust the name based on the appearance of the font. So, to complete our example: Make the font accessible to X11 &prompt.user; cd /usr/X11R6/lib/X11/fonts/Type1 &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . Edit fonts.dir and fonts.scale, adding the line describing the font and incrementing the number of fonts which is found on the first line. &prompt.user; ex fonts.dir :1p 25 :1c 26 . :$a showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 . :wq fonts.scale seems to be identical to fonts.dir… &prompt.user; cp fonts.dir fonts.scale Tell X11 that things have changed &prompt.user; xset fp rehash Examine the new font &prompt.user; xfontsel -pattern -type1-* References: &man.xfontsel.1;, &man.xset.1;, The X Windows System in a Nutshell, O'Reilly & Associates. Using type 1 fonts with Ghostscript Ghostscript references a font via its Fontmap file. This must be modified in a similar way to the X11 fonts.dir file. Ghostscript can use either the .pfa or the .pfb format fonts. Using the font from the previous example, here is how to use it with Ghostscript: Put the font in Ghostscript's font directory &prompt.user; cd /usr/local/share/ghostscript/fonts &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . Edit Fontmap so Ghostscript knows about the font &prompt.user; cd /usr/local/share/ghostscript/4.01 &prompt.user; ex Fontmap :$a /Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat . :wq Use Ghostscript to examine the font &prompt.user; gs prfont.ps Aladdin Ghostscript 4.01 (1996-7-10) Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... /1899520 581354 1300084 13826 0 done. GS>Showboat DoFont Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... 1939688 565415 1300084 16901 0 done. >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< GS>quit References: fonts.txt in the Ghostscript 4.01 distribution Using type 1 fonts with Groff Now that the new font can be used by both X11 and Ghostscript, how can one use the new font with groff? First of all, since we are dealing with type 1 &postscript; fonts, the groff device that is applicable is the ps device. A font file must be created for each font that groff can use. A groff font name is just a file in /usr/share/groff_font/devps. With our example, the font file could be /usr/share/groff_font/devps/SHOWBOAT. The file must be created using tools provided by groff. The first tool is afmtodit. This is not normally installed, so it must be retrieved from the source distribution. I found I had to change the first line of the file, so I did: &prompt.user; cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp &prompt.user; ex /tmp/afmtodit.pl :1c #!/usr/bin/perl -P- . :wq This tool will create the groff font file from the metrics file (.afm suffix.) Continuing with our example: Many .afm files are in Mac format… ^M delimited lines We need to convert them to &unix; style ^J delimited lines &prompt.user; cd /tmp &prompt.user; cat /usr/local/share/fonts/type1/showboat.afm | tr '\015' '\012' >showboat.afm Now create the groff font file &prompt.user; cd /usr/share/groff_font/devps &prompt.user; /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT The font can now be referenced with the name SHOWBOAT. If ghostscript is used to drive the printers on the system, then nothing more needs to be done. However, if true PostScript printers are used, then the font must be down loaded to the printer in order for the font to be used (unless the printer happens to have the showboat font built in or on an accessible font disk.) The final step is to create a down loadable font. The pfbtops tool is used to create the .pfa format of the font, and the download file is modified to reference the new font. The download file must reference the internal name of the font. This can easily be determined from the groff font file as illustrated: Create the .pfa font file &prompt.user; pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa Of course, if the .pfa file is already available, just use a symbolic link to reference it. Get the internal font name &prompt.user; fgrep internalname SHOWBOAT internalname Showboat Tell groff that the font must be down loaded &prompt.user; ex download :$a Showboat showboat.pfa . :wq To test the font: &prompt.user; cd /tmp &prompt.user; cat >example.t <<EOF .sp 5 .ps 16 This is an example of the Showboat font: .br .ps 48 .vs (\n(.s+2)p .sp .ft SHOWBOAT ABCDEFGHI .br JKLMNOPQR .br STUVWXYZ .sp .ps 16 .vs (\n(.s+2)p .fp 5 SHOWBOAT .ft R To use it for the first letter of a paragraph, it will look like: .sp 50p \s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the showboat font as its first letter. Additional vertical space must be used to allow room for the larger letter. EOF &prompt.user; groff -Tps example.t >example.ps To use ghostscript/ghostview &prompt.user; ghostview example.ps To print it &prompt.user; lpr -Ppostscript example.ps References: /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man, &man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;. Converting TrueType fonts to a groff/PostScript format for groff This potentially requires a bit of work, simply because it depends on some utilities that are not installed as part of the base system. They are: ttf2pf TrueType to PostScript conversion utilities. This allows conversion of a TrueType font to an ascii font metric (.afm) file. Currently available at . Note: These files are PostScript programs and must be downloaded to disk by holding down the Shift key when clicking on the link. Otherwise, your browser may try to launch ghostview to view them. The files of interest are: GS_TTF.PS PF2AFM.PS ttf2pf.ps The funny upper/lower case is due to their being intended also for DOS shells. ttf2pf.ps makes use of the others as upper case, so any renaming must be consistent with this. (Actually, GS_TTF.PS and PFS2AFM.PS are supposedly part of the ghostscript distribution, but it is just as easy to use these as an isolated utility. FreeBSD does not seem to include the latter.) You also may want to have these installed to /usr/local/share/groff_font/devps(?). afmtodit Creates font files for use with groff from ascii font metrics file. This usually resides in the directory, /usr/src/contrib/groff/afmtodit, and requires some work to get going. If you are paranoid about working in the /usr/src tree, simply copy the contents of the above directory to a work location. In the work area, you will need to make the utility. Just type: # make -f Makefile.sub afmtodit You may also need to copy /usr/contrib/groff/devps/generate/textmap to /usr/share/groff_font/devps/generate if it does not already exist. Once all these utilities are in place, you are ready to commence: Create the .afm file by typing: % gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name Where, TTF_name is your TrueType font file, PS_font_name is the file name for the .pfa file, AFM_name is the name you wish for the .afm file. If you do not specify output file names for the .pfa or .afm files, then default names will be generated from the TrueType font file name. This also produces a .pfa file, the ascii PostScript font metrics file (.pfb is for the binary form). This will not be needed, but could (I think) be useful for a fontserver. For example, to convert the 30f9 Barcode font using the default file names, use the following command: % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to 3of9.pfa and 3of9.afm. If you want the converted fonts to be stored in A.pfa and B.afm, then use this command: % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to A.pfa and B.afm. Create the groff PostScript file: Change directories to /usr/share/groff_font/devps so as to make the following command easier to execute. You will probably need root privileges for this. (Or, if you are paranoid about working there, make sure you reference the files DESC, text.enc and generate/textmap as being in this directory.) % afmtodit -d DESC -e text.enc file.afm \ generate/textmap PS_font_name Where, file.afm is the AFM_name created by ttf2pf.ps above, and PS_font_name is the font name used from that command, as well as the name that &man.groff.1; will use for references to this font. For example, assuming you used the first tiff2pf.ps command above, then the 3of9 Barcode font can be created using the command: % afmtodit -d DESC -e text.enc 3of9.afm \ generate/textmap 3of9 Ensure that the resulting PS_font_name file (e.g., 3of9 in the example above) is located in the directory /usr/share/groff_font/devps by copying or moving it there. Note that if ttf2pf.ps assigns a font name using the one it finds in the TrueType font file and you want to use a different name, you must edit the .afm file prior to running afmtodit. This name must also match the one used in the Fontmap file if you wish to pipe &man.groff.1; into &man.gs.1;. Can TrueType fonts be used with other programs? The TrueType font format is used by Windows, Windows 95, and Mac's. It is quite popular and there are a great number of fonts available in this format. Unfortunately, there are few applications that I am aware of that can use this format: Ghostscript and Povray come to mind. Ghostscript's support, according to the documentation, is rudimentary and the results are likely to be inferior to type 1 fonts. Povray version 3 also has the ability to use TrueType fonts, but I rather doubt many people will be creating documents as a series of raytraced pages :-). This rather dismal situation may soon change. The FreeType Project is currently developing a useful set of FreeType tools: The freetype module is included with XFree86 4.x. For more information please see the FreeBSD Handbook or the XFree86 4.0.2 Fonts page. The xfsft font server for X11 can serve TrueType fonts in addition to regular fonts. Though currently in beta, it is said to be quite usable. See Juliusz Chroboczek's page for further information. Porting instructions for FreeBSD can be found at Stephen Montgomery's software page. xfstt is another font server for X11, available under . A program called ttf2bdf can produce BDF files suitable for use in an X environment from TrueType files. Linux binaries are said to be available from . For people requiring the use of Asian TrueType fonts, the XTT font server may be worth a look. Information about XTT can be found at URL: . and others … The FreeType Projects page is a good starting point for information on these and other free TrueType projects. Where can additional fonts be obtained? Many fonts are available on the Internet. They are either entirely free, or are share-ware. In addition, there are many inexpensive CDROMs available that contain many fonts. Some Internet locations (as of August 1996) are: (Formerly CICA) Additional questions What use are the .pfm files? Can one generate the .afm file from a .pfa or .pfb? How to generate the groff character mapping files for PostScript fonts with non-standard character names? Can xditview and devX?? devices be set up to access all the new fonts? It would be good to have examples of using TrueType fonts with povray and ghostscript.
diff --git a/en_US.ISO8859-1/articles/formatting-media/article.sgml b/en_US.ISO8859-1/articles/formatting-media/article.sgml index 0cf918caf5..e514e59254 100644 --- a/en_US.ISO8859-1/articles/formatting-media/article.sgml +++ b/en_US.ISO8859-1/articles/formatting-media/article.sgml @@ -1,639 +1,630 @@ -%authors; - - -%freebsd; - - -%trademarks; - - -%man; + +%articles.ent; ]>
Formatting Media For Use With FreeBSD A Tutorial Doug White
dwhite@resnet.uoregon.edu
March 1997 &tm-attrib.freebsd; &tm-attrib.iomega; &tm-attrib.opengroup; &tm-attrib.general; This document describes how to slice, partition, and format hard disk drives and similar media for use with FreeBSD. The examples given have been tested under FreeBSD 2.2 and should work for other releases. The text has been updated for FreeBSD version 4. Introduction & Definitions Overview Successfully adding disks to an existing system is the mark of an experienced system administrator. Slicing, partitioning, and adding disks requires a careful dance of proper command and name syntax. One slipped finger and an entire disk could disappear in seconds. This document is written in an attempt to simplify this process and avoid accidents. Thankfully, enhancements to existing tools (notably sysinstall) have greatly improved this process in recent releases of FreeBSD. There are two possible modes of disk formatting: compatibility mode: Arranging a disk so that it has a slice table for use with other operating systems. dedicated mode, sometimes called dangerously dedicated mode: Formatting a disk with no slice table. This makes the process of adding disks easier, however non-FreeBSD operating systems may not accept the disk. The term dangerously refers to the danger that the system may not recognize a disk formatted in this manner. For most cases, dedicated mode is the easiest to set up and use in existing systems, as a new disk is usually dedicated entirely to FreeBSD. However, compatibility mode insures optimum interoperability with future installations at a cost of increased complexity. In addition to selecting the mode, two methods of slicing the disk are available. One is using the system installation tool /stand/sysinstall. 2.1.7-RELEASE and later versions of sysinstall contain code to ease setup of disks during normal system operation, mainly allowing access to the Label and Partition editors and a Write feature which will update just the selected disk and slice without affecting other disks. The other method is running the tools manually from a root command line. For dedicated mode, only three or four commands are involved while sysinstall requires some manipulation. Definitions &unix; disk management over the centuries has invented many new definitions for old words. The following glossary covers the definitions used in this document and (hopefully) for FreeBSD in general. compatibility mode: Arranging a disk so that it has a slice table for use with other operating systems. Oppose dedicated mode. (dangerously) dedicated mode: Formatting a disk with no slice table. This makes the process of adding disks easier, however non-FreeBSD operating systems may not accept the disk. Oppose compatibility mode. disk: Hard disks, CDROMs, magneto-optical devices and &iomegazip;/&jaz; removable media are example of storage devices commonly used today. The basic principle of the way these work is that one or more spinning disks spin by a motor, while a head, moving on a radial path close to the disks, reads from or writes data to the disk. Writing is done by modifying some physical properties of the disk (magnetic flow, reflectivity, etc.) while reading is done by detecting changes to the same physical properties of the disk. slice: A division of a disk. Up to four slices are permitted on one disk in the PC standard. Slices are composed of contiguous sectors. Slices are recorded in a slice table used by the system BIOS to locate bootable partitions. The slice table is usually called the partition table in DOS parlance. Maintained by the fdisk utility. partition: A division of a slice. Usually used in reference to divisions of the FreeBSD slice of a disk. Each filesystem and swap area on a disk resides in a partition. Maintained using the disklabel utility. sector: Smallest subdivision of a disk. One sector usually represents 512 bytes of data. Warnings & Pitfalls Building disks is not something to take lightly. It is quite possible to destroy the contents of other disks in your system if the proper precautions are not taken. Check your work carefully. It is very simple to destroy the incorrect disk when working with these commands. When in doubt consult the kernel boot output for the proper device. Needless to say, we are not responsible for any damage to any data or hardware that you may experience. You work at your own risk! Zip, Jaz, and Other Removables Removable disks can be formatted in the same way as normal hard disks. It is essential to have the disk drive connected to the system and a disk placed in the drive during startup, so the kernel can determine the drive's geometry. Check the dmesg output and make sure your device and the disk's size is listed. If the kernel reports Can't get the size then the disk was not in the drive. In this case, you will need to restart the machine before attempting to format disks. Formatting Disks in Dedicated Mode Introduction This section details how to make disks that are totally dedicated to FreeBSD. Remember, dedicated mode disks sometimes cannot be booted by the PC architecture. Making Dedicated Mode Disks using Sysinstall /stand/sysinstall, the system installation utility, has been expanded in recent versions to make the process of dividing disks properly a less tiring affair. The fdisk and disklabel editors built into sysinstall are GUI tools that remove much of the confusion from slicing disks. For FreeBSD versions 2.1.7 and later, this is perhaps the simplest way to slice disks. Start sysinstall as root by typing &prompt.root; /stand/sysinstall from the command prompt. Select Index. Select Partition. Select the disk to edit with arrow keys and SPACE. If you are using this entire disk for FreeBSD, select A. When asked: Do you want to do this with a true partition entry so as to remain cooperative with any future possible operating systems on the drive(s)? answer No. When asked if you still want to do this, answer Yes. Select Write. When warned about writing on installed systems, answer Yes. Quitthe FDISK Editor and ESCAPE back to the Index menu. Select Label from the Index menu. Label as desired. For a single partition, enter C to Create a partition, accept the default size, partition type Filesystem, and a mountpoint (which is not used). Enter W when done and confirm to continue. The filesystem will be newfs'd for you, unless you select otherwise (for new partitions you will want to do this!). You will get the error: Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory Ignore. Exit out by repeatedly pressing ESCAPE. Making Dedicated Mode Disks Using the Command Line Execute the following commands, replacing ad2 with the disk name. &prompt.root; dd if=/dev/zero of=/dev/ad2 count=2 &prompt.root; disklabel /dev/ad2 | disklabel -B -R -r ad2 /dev/stdin We only want one partition, so using slice 'c' should be fine: &prompt.root; newfs /dev/ad2c If you need to edit the disklabel to create multiple partitions (such as swap), use the following: &prompt.root; dd if=/dev/zero of=/dev/ad2 count=2 &prompt.root; disklabel /dev/ad2 > /tmp/label Edit disklabel to add partitions: &prompt.root; vi /tmp/label &prompt.root; disklabel -B -R -r ad2 /tmp/label newfs partitions appropriately Your disk is now ready for use. Making Compatibility Mode Disks Introduction The command line is the easiest way to make dedicated disks, and the worst way to make compatibility disks. The command-line fdisk utility requires higher math skills and an in-depth understanding of the slice table, which is more than most people want to deal with. Use sysinstall for compatibility disks, as described below. Making Compatibility Mode Disks Using Sysinstall Start sysinstall as root by typing &prompt.root; /stand/sysinstall from the command prompt. Select Index. Select Partition. Select the disk to edit with arrow keys and SPACE. If you are using this entire disk for FreeBSD, select A. When asked: Do you want to do this with a true partition entry so as to remain cooperative with any future possible operating systems on the drive(s)? answer yes. Select Write. When asked to install the boot manager, select None with SPACE then hit ENTER for OK. Quit the FDISK Editor. You will be asked about the boot manager, select None again. Select Label from the Index menu. Label as desired. For a single partition, accept the default size, type filesystem, and a mountpoint (which is not used). The filesystem will be newfs'd for you, unless you select otherwise (for new partitions you will want to do this!). You will get the error: Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory Ignore. Exit out by repeatedly pressing ESCAPE. Your new disk is now ready for use. Other Disk Operations Adding Swap Space As a system grows, its need for swap space can also grow. Although adding swap space to existing disks is very difficult, a new disk can be partitioned with additional swap space. To add swap space when adding a disk to a system: When partitioning the disk, edit the disklabel and allocate the amount of swap space to add in partition `b' and the remainder in another partition, such as `a' or `e'. The size is given in 512 byte blocks. When newfsing the drive, do NOT newfs the `c' partition. Instead, newfs the partition where the non-swap space lies. Add an entry to /etc/fstab as follows: /dev/ad0b none swap sw 0 0 Change /dev/ad0b to the device of the newly added space. To make the new space immediately available, use the swapon command. &prompt.root; swapon /dev/da0b swapon: added /dev/da0b as swap space Copying the Contents of Disks Submitted By: Renaud Waldura (renaud@softway.com) To move file from your original base disk to the fresh new one, do: &prompt.root; mount /dev/ad2 /mnt &prompt.root; pax -r -w -p e /usr/home /mnt &prompt.root; umount /mnt &prompt.root; rm -rf /usr/home/* &prompt.root; mount /dev/ad2 /usr/home Creating Striped Disks using CCD Commands Submitted By: Stan Brown (stanb@awod.com) The Concatenated Disk Driver, or CCD, allows you to treat several identical disks as a single disk. Striping can result in increased disk performance by distributing reads and writes across the disks. See the &man.ccd.4; and &man.ccdconfig.8; manual pages or the CCD Homepage for further details. You no longer need to build a special kernel to run ccd. When you run ccdconfig, it will load the KLD for you if the kernel does not contain CCD support. You build CCDs on disk partitions of type 4.2BSD. If you want to use the entire disk, you still need to create a new partition. For example, disklabel -e might show: # size offset fstype [fsize bsize bps/cpg] c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) You should not use partition c for the CCD, since it is of type unused. Instead, create a new partition of exactly the same size, but with type 4.2BSD: # size offset fstype [fsize bsize bps/cpg] c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597) To create a new CCD, execute the following commands. This describes how to add three disks together; simply add or remove devices as necessary. Remember that the disks to be striped must be identical. &prompt.root; cd /dev ; sh MAKDEV ccd0 &prompt.root; disklabel -r -w da0 auto &prompt.root; disklabel -r -w da1 auto &prompt.root; disklabel -r -w da2 auto &prompt.root; disklabel -e da0 Add partition e with type 4.2BSD &prompt.root; disklabel -e da1 Add partition e with type 4.2BSD &prompt.root; disklabel -e da2 Add partition e with type 4.2BSD &prompt.root; ccdconfig ccd0 273 0 /dev/da0e /dev/da1e /dev/da2e &prompt.root; newfs /dev/ccd0c The value 273 is the stripe size. This is the number of disk sectors (of 512 bytes each) in each block of data on the CCD. It should be at least 128 kB, and it should not be not be a power of 2. Now you can mount and use your CCD by referencing device /dev/ccd0c. A more powerful and flexible alternative to CCD is Vinum. See the Vinum Project home page for further details. Credits The author would like to thank the following individuals for their contributions to this project: Darryl Okahata (darrylo@hpnmhjw.sr.hp.com) for his simple dedicated mode setup documentation which I have used repeatedly on FreeBSD-questions. &a.jkh; for making sysinstall useful for this type of task. John Fieber (jfieber@indiana.edu) for making information and examples of the DocBook DTD on which this document is based. &a.grog; for checking my work and pointing out inaccuracies, as well as miscellaneous support.
diff --git a/en_US.ISO8859-1/articles/freebsd-questions/article.sgml b/en_US.ISO8859-1/articles/freebsd-questions/article.sgml index e6a1c64c57..931959097c 100644 --- a/en_US.ISO8859-1/articles/freebsd-questions/article.sgml +++ b/en_US.ISO8859-1/articles/freebsd-questions/article.sgml @@ -1,635 +1,627 @@ -%man; - -%mailing-lists; - -%freebsd; - -%trademarks; - -%urls; + +%articles.ent; ]>
How to get best results from the FreeBSD-questions mailing list Greg Lehey
grog@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.microsoft; &tm-attrib.netscape; &tm-attrib.opengroup; &tm-attrib.qualcomm; &tm-attrib.general; This document provides useful information for people looking to prepare an e-mail to the FreeBSD-questions mailing list. Advice and hints are given that will maximize the chance that the reader will receive useful replies. This document is regularly posted to the FreeBSD-questions mailing list. Introduction FreeBSD-questions is a mailing list maintained by the FreeBSD project to help people who have questions about the normal use of FreeBSD. Another group, FreeBSD-hackers, discusses more advanced questions such as future development work. The term hacker has nothing to do with breaking into other people's computers. The correct term for the latter activity is cracker, but the popular press has not found out yet. The FreeBSD hackers disapprove strongly of cracking security, and have nothing to do with it. For a longer description of hackers, see Eric Raymond's How To Become A Hacker This is a regular posting aimed to help both those seeking advice from FreeBSD-questions (the newcomers), and also those who answer the questions (the hackers). Inevitably there is some friction, which stems from the different viewpoints of the two groups. The newcomers accuse the hackers of being arrogant, stuck-up, and unhelpful, while the hackers accuse the newcomers of being stupid, unable to read plain English, and expecting everything to be handed to them on a silver platter. Of course, there is an element of truth in both these claims, but for the most part these viewpoints come from a sense of frustration. In this document, I would like to do something to relieve this frustration and help everybody get better results from FreeBSD-questions. In the following section, I recommend how to submit a question; after that, we will look at how to answer one. How to subscribe to FreeBSD-questions FreeBSD-questions is a mailing list, so you need mail access. Point your WWW browser to FreeBSD-question Info Page. In the section titled Subscribing to freebsd-questions fill in the Your email address field; the other fields are optional. The password fields in the subscription form provide only mild security, but should prevent others from messing with your subscription. Do not use a valuable password as it will occasionally be emailed back to you in cleartext. You will receive a confirmation message from mailman; follow the included instructions to complete your subscription. Finally, when you get the Welcome message from mailman telling you the details of the list and subscription area password, please save it. If you ever should want to leave the list, you will need the information there. See the next section for more details. How to unsubscribe from FreeBSD-questions When you subscribed to FreeBSD-questions, you got a welcome message from mailman. In this message, amongst other things, it told you how to unsubscribe. Here is a typical message: Welcome to the freebsd-questions@freebsd.org mailing list! To post to this list, send your email to: freebsd-questions@freebsd.org General information about the mailing list is at: http://lists.freebsd.org/mailman/listinfo/freebsd-questions If you ever want to unsubscribe or change your options (e.g., switch to or from digest mode, change your password, etc.), visit your subscription page at: http://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de You can also make such adjustments via email by sending a message to: freebsd-questions-request@freebsd.org with the word `help' in the subject or body (don't include the quotes), and you will get back a message with instructions. You must know your password to change your options (including changing the password, itself) or to unsubscribe. It is: 12345 Normally, Mailman will remind you of your freebsd.org mailing list passwords once every month, although you can disable this if you prefer. This reminder will also include instructions on how to unsubscribe or change your account options. There is also a button on your options page that will email your current password to you. From the URL specified in your Welcome message you may visit the Account management page and enter a request to Unsubscribe you from FreeBSD-questions mailing list. A confirmation message will be sent to you from mailman; follow the included instructions to finish unsubscribing. If you have done this, and you still can not figure out what is going on, send a message to freebsd-questions-request@FreeBSD.org, and they will sort things out for you. Do not send a message to FreeBSD-questions: they can not help you. Should I ask <literal>-questions</literal> or <literal>-hackers</literal>? Two mailing lists handle general questions about FreeBSD, FreeBSD-questions and FreeBSD-hackers. In some cases, it is not really clear which group you should ask. The following criteria should help for 99% of all questions, however: If the question is of a general nature, ask FreeBSD-questions. Examples might be questions about installing FreeBSD or the use of a particular &unix; utility. If you think the question relates to a bug, but you are not sure, or you do not know how to look for it, send the message to FreeBSD-questions. If the question relates to a bug, and you are sure that it is a bug (for example, you can pinpoint the place in the code where it happens, and you maybe have a fix), then send the message to FreeBSD-hackers. If the question relates to enhancements to FreeBSD, and you can make suggestions about how to implement them, then send the message to FreeBSD-hackers. There are also a number of other specialized mailing lists, for example FreeBSD-isp, which caters to the interests of ISPs (Internet Service Providers) who run FreeBSD. If you happen to be an ISP, this does not mean you should automatically send your questions to FreeBSD-isp. The criteria above still apply, and it is in your interest to stick to them, since you are more likely to get good results that way. Before submitting a question You can (and should) do some things yourself before asking a question on one of the mailing lists: Try solving the problem on your own. If you post a question which shows that you have tried to solve the problem, your question will generally attract more positive attention from people reading it. Trying to solve the problem yourself will also enhance your understanding of FreeBSD, and will eventually let you use your knowledge to help others by answering questions posted to the mailing lists. Read the manual pages, and the FreeBSD documentation (either installed in /usr/doc or accessible via WWW at ), especially the handbook and the FAQ. Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives at and respectively. This can be done at other WWW sites as well, for example at . Use a search engine such as Google or Yahoo to find answers to your question. Google even has a BSD-specific search interface. How to submit a question When submitting a question to FreeBSD-questions, consider the following points: Remember that nobody gets paid for answering a FreeBSD question. They do it of their own free will. You can influence this free will positively by submitting a well-formulated question supplying as much relevant information as possible. You can influence this free will negatively by submitting an incomplete, illegible, or rude question. It is perfectly possible to send a message to FreeBSD-questions and not get an answer even if you follow these rules. It is much more possible to not get an answer if you do not. In the rest of this document, we will look at how to get the most out of your question to FreeBSD-questions. Not everybody who answers FreeBSD questions reads every message: they look at the subject line and decide whether it interests them. Clearly, it is in your interest to specify a subject. FreeBSD problem or Help are not enough. If you provide no subject at all, many people will not bother reading it. If your subject is not specific enough, the people who can answer it may not read it. Format your message so that it is legible, and PLEASE DO NOT SHOUT!!!!!. We appreciate that a lot of people do not speak English as their first language, and we try to make allowances for that, but it is really painful to try to read a message written full of typos or without any line breaks. Do not underestimate the effect that a poorly formatted mail message has, not just on the FreeBSD-questions mailing list. Your mail message is all people see of you, and if it is poorly formatted, one line per paragraph, badly spelt, or full of errors, it will give people a poor impression of you. A lot of badly formatted messages come from bad mailers or badly configured mailers. The following mailers are known to send out badly formatted messages without you finding out about them: cc:Mail &eudora; exmh µsoft; Exchange µsoft; Internet Mail µsoft; &outlook; &netscape; As you can see, the mailers in the Microsoft world are frequent offenders. If at all possible, use a &unix; mailer. If you must use a mailer under Microsoft environments, make sure it is set up correctly. Try not to use MIME: a lot of people use mailers which do not get on very well with MIME. Make sure your time and time zone are set correctly. This may seem a little silly, since your message still gets there, but many of the people you are trying to reach get several hundred messages a day. They frequently sort the incoming messages by subject and by date, and if your message does not come before the first answer, they may assume they missed it and not bother to look. Do not include unrelated questions in the same message. Firstly, a long message tends to scare people off, and secondly, it is more difficult to get all the people who can answer all the questions to read the message. Specify as much information as possible. This is a difficult area, and we need to expand on what information you need to submit, but here is a start: In nearly every case, it is important to know the version of FreeBSD you are running. This is particularly the case for FreeBSD-CURRENT, where you should also specify the date of the sources, though of course you should not be sending questions about -CURRENT to FreeBSD-questions. With any problem which could be hardware related, tell us about your hardware. In case of doubt, assume it is possible that it is hardware. What kind of CPU are you using? How fast? What motherboard? How much memory? What peripherals? There is a judgement call here, of course, but the output of the &man.dmesg.8; command can frequently be very useful, since it tells not just what hardware you are running, but what version of FreeBSD as well. If you get error messages, do not say I get error messages, say (for example) I get the error message 'No route to host'. If your system panics, do not say My system panicked, say (for example) my system panicked with the message 'free vnode isn't'. If you have difficulty installing FreeBSD, please tell us what hardware you have. In particular, it is important to know the IRQs and I/O addresses of the boards installed in your machine. If you have difficulty getting PPP to run, describe the configuration. Which version of PPP do you use? What kind of authentication do you have? Do you have a static or dynamic IP address? What kind of messages do you get in the log file? A lot of the information you need to supply is the output of programs, such as &man.dmesg.8;, or console messages, which usually appear in /var/log/messages. Do not try to copy this information by typing it in again; it is a real pain, and you are bound to make a mistake. To send log file contents, either make a copy of the file and use an editor to trim the information to what is relevant, or cut and paste into your message. For the output of programs like &man.dmesg.8;, redirect the output to a file and include that. For example, &prompt.user; dmesg > /tmp/dmesg.out This redirects the information to the file /tmp/dmesg.out. If you do all this, and you still do not get an answer, there could be other reasons. For example, the problem is so complicated that nobody knows the answer, or the person who does know the answer was offline. If you do not get an answer after, say, a week, it might help to re-send the message. If you do not get an answer to your second message, though, you are probably not going to get one from this forum. Resending the same message again and again will only make you unpopular. To summarize, let's assume you know the answer to the following question (yes, it is the same one in each case). You choose which of these two questions you would be more prepared to answer: Message 1 Subject: HELP!!?!?? I just can't get hits damn silly FereBSD system to workd, and Im really good at this tsuff, but I have never seen anythign sho difficult to install, it jst wont work whatever I try so why don't you guys tell me what I doing wrong. Message 2 Subject: Problems installing FreeBSD I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot of difficulty installing it. I have a 66 MHz 486 with 16 MB of memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball disk and a Toshiba 3501XA CDROM drive. The installation works just fine, but when I try to reboot the system, I get the message Missing Operating System. How to follow up to a question Often you will want to send in additional information to a question you have already sent. The best way to do this is to reply to your original message. This has three advantages: You include the original message text, so people will know what you are talking about. Do not forget to trim unnecessary text out, though. The text in the subject line stays the same (you did remember to put one in, did you not?). Many mailers will sort messages by subject. This helps group messages together. The message reference numbers in the header will refer to the previous message. Some mailers, such as mutt, can thread messages, showing the exact relationships between the messages. How to answer a question Before you answer a question to FreeBSD-questions, consider: A lot of the points on submitting questions also apply to answering questions. Read them. Has somebody already answered the question? The easiest way to check this is to sort your incoming mail by subject: then (hopefully) you will see the question followed by any answers, all together. If somebody has already answered it, it does not automatically mean that you should not send another answer. But it makes sense to read all the other answers first. Do you have something to contribute beyond what has already been said? In general, Yeah, me too answers do not help much, although there are exceptions, like when somebody is describing a problem he is having, and he does not know whether it is his fault or whether there is something wrong with the hardware or software. If you do send a me too answer, you should also include any further relevant information. Are you sure you understand the question? Very frequently, the person who asks the question is confused or does not express himself very well. Even with the best understanding of the system, it is easy to send a reply which does not answer the question. This does not help: you will leave the person who submitted the question more frustrated or confused than ever. If nobody else answers, and you are not too sure either, you can always ask for more information. Are you sure your answer is correct? If not, wait a day or so. If nobody else comes up with a better answer, you can still reply and say, for example, I do not know if this is correct, but since nobody else has replied, why don't you try replacing your ATAPI CDROM with a frog?. Unless there is a good reason to do otherwise, reply to the sender and to FreeBSD-questions. Many people on the FreeBSD-questions are lurkers: they learn by reading messages sent and replied to by others. If you take a message which is of general interest off the list, you are depriving these people of their information. Be careful with group replies; lots of people send messages with hundreds of CCs. If this is the case, be sure to trim the Cc: lines appropriately. Include relevant text from the original message. Trim it to the minimum, but do not overdo it. It should still be possible for somebody who did not read the original message to understand what you are talking about. Use some technique to identify which text came from the original message, and which text you add. I personally find that prepending > to the original message works best. Leaving white space after the > and leave empty lines between your text and the original text both make the result more readable. Put your response in the correct place (after the text to which it replies). It is very difficult to read a thread of responses where each reply comes before the text to which it replies. Most mailers change the subject line on a reply by prepending a text such as Re: . If your mailer does not do it automatically, you should do it manually. If the submitter did not abide by format conventions (lines too long, inappropriate subject line), please fix it. In the case of an incorrect subject line (such as HELP!!??), change the subject line to (say) Re: Difficulties with sync PPP (was: HELP!!??). That way other people trying to follow the thread will have less difficulty following it. In such cases, it is appropriate to say what you did and why you did it, but try not to be rude. If you find you can not answer without being rude, do not answer. If you just want to reply to a message because of its bad format, just reply to the submitter, not to the list. You can just send him this message in reply, if you like.
diff --git a/en_US.ISO8859-1/articles/hats/article.sgml b/en_US.ISO8859-1/articles/hats/article.sgml index bba1c822cb..1e0b4a7226 100644 --- a/en_US.ISO8859-1/articles/hats/article.sgml +++ b/en_US.ISO8859-1/articles/hats/article.sgml @@ -1,129 +1,117 @@ -%man; - - -%freebsd; - - -%authors; - - -%teams; - - -%mailing-lists; + +%articles.ent; ]>
Working with Hats Warner Losh Contributed by $FreeBSD$ 2002 2003 Warner Losh This is not an official statement from core, but rather one core member's personal interpretation of core's position, both as a sitting member of core and as a former security officer. This is only a guideline, not as a cudgel for grievances. Much like &man.style.9; is a guideline for the source code, this document is not intended as an absolute straight jacket. When core appoints someone to a hat, they expect that person to be responsible for an area of the source code tree. Core expects that person to be the final authority in that area of the tree, or have enough self knowledge to know that they are not and to seek qualified help. Core expects that person to guide development in that area of the tree. Sometimes this means taking an pro-active role in day to day affairs, while other times this means taking a reactive role in reviewing committed code. When people submit patches that potentially impact this area of the tree, core expects the hat or his appointed deputies to review the patches appropriately. Core expects that the hat will work with the patch submitter to correct issues that there may be with the patches. Core expects the hat to offer solutions and work with the submitter to reach a compromise. Core expects the hat to be courteous. It is reasonable for hats to request that normal project rules be followed when reviewing patches (eg, that they generally conform to &man.style.9; or the prevailing style of the file, that style and content changes be separated, etc). When a dispute arises, core expects the hat to make his or her best efforts to compromise or otherwise resolve the dispute. The hat is expected to be courteous to all parties involved. In extreme cases, core recognizes that hats may need to wield a big stick and say no, that is not acceptable and cannot go in (or must be backed out). Core views this last power as one of last resort, and would frown on hats using that either too often or as the first response. Often real life interferes with a hat's ability to perform their duties. A condition that core generally imposes upon the hats of the world is that they have a deputy that can act in their absence. This deputy is expected to be an active participant in the team that the hat puts together and should be conversant with all the issues that surround the part of the tree that the hat is guiding. The deputy is expected to be able to act in the absence of the hat. For example, the security officer deputies send out security advisories when the SO is not around. In extreme cases, the deputy can defer an issue until the hat returns, but that is expected to be the exception rather than the rule, especially if the hat's return is far in the future. Hats are answerable to core. If they are doing good jobs, core will leave them alone. If they are doing a bad job, core has the option to remove them. Hats are expected to work with core if core has issues with their performance of their duties They serve at the pleasure of core. Core sometimes will impose additional, specific requirements for a given hat that does not apply to all hats. These conditions may change over time. Committers and others working with hats are expected to use common sense, and be polite to the hats. They are expected to work with the hat and his team to come to a solution acceptable to everybody. In the event that no compromise can be reached, the committers are expected to accept the decisions of the hat with good grace. In exceptional cases, these decisions can be appealed to core. However, core generally will not override the decisions of the hats that it appoints unless the hat acted in bad faith or arbitrarily. Core is not a technical review board, and has created the hats as mini-TRBs to give dispute resolution a proper framework. If a committer feels that a hat is abusing his or her power, or being regularly rude to contributors, then they should bring the matter to core. This problem can be technical, social, procedural, or some combination or subset of these. Core will hear the case and reach a decision, and expects both sides to abide by their decision. Core appreciates specific complaints rather than general ones as those are easier to resolve. Core expects committers to work together in the appropriate mailing lists to resolve their issues. The hat and his team should be relatively rarely involved in their role as hat, and instead should usually be just another committer. (The one exception to this is the security officer hat, which needs to secretly solve vulnerabilities before they are announced.) The hat should be a first among equals, not a chairman.
diff --git a/en_US.ISO8859-1/articles/hubs/article.sgml b/en_US.ISO8859-1/articles/hubs/article.sgml index 8a76953bd4..eebcbe54a9 100644 --- a/en_US.ISO8859-1/articles/hubs/article.sgml +++ b/en_US.ISO8859-1/articles/hubs/article.sgml @@ -1,1132 +1,1122 @@ -%man; - -%authors; - -%teams; - -%mailing-lists; - -%trademarks; - -%freebsd; + +%articles.ent; ]>
Mirroring FreeBSD $FreeBSD$ Jun Kuriyama
kuriyama@FreeBSD.org
 Valentino Vaschetto
logo@FreeBSD.org
 Daniel Lang
dl@leo.org
 Ken Smith
kensmith@FreeBSD.org
 &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.general; An in-progress article on how to mirror FreeBSD, aimed at hub administrators. Contact Information The Mirror System Coordinators can be reached through email at mirror-admin@FreeBSD.org. There is also a &a.hubs;. Requirements for FreeBSD mirrors Disk Space Disk space is one of the most important requirements. Depending on the set of releases, architectures, and degree of completeness you want to mirror, a huge amount of disk space may be consumed. Also keep in mind that official mirrors are probably required to be complete. The CVS repository and the web pages should always be mirrored completely. Also note that the numbers stated here are reflecting the current state (at &rel2.current;-RELEASE/&rel.current;-RELEASE). Further development and releases will only increase the required amount. Also make sure to keep some (ca. 10-20%) extra space around just to be sure. Here are some approximate figures: Full FTP Distribution: 126 GB CVS repository: 2.7 GB CTM deltas: 1.8 GB Web pages: 300 MB Network Connection/Bandwidth Of course, you need to be connected to the Internet. The required bandwidth depends on your intended use of the mirror. If you just want to mirror some parts of FreeBSD for local use at your site/intranet, the demand may be much smaller than if you want to make the files publicly available. If you intend to become an official mirror, the bandwidth required will be even higher. We can only give rough estimates here: Local site, no public access: basically no minimum, but < 2 Mbps could make syncing too slow. Unofficial public site: 34 Mbps is probably a good start. Official site: > 100 Mbps is recommended, and your host should be connected as close as possible to your border router. System Requirements, CPU, RAM One thing this depends on the expected number of clients, which is determined by the server's policy. It is also affected by the types of services you want to offer. Plain FTP or HTTP services may not require a huge amount of resources. Watch out if you provide CVSup, rsync or even AnonCVS. This can have a huge impact on CPU and memory requirements. Especially rsync is considered a memory hog, and CVSup does indeed consume some CPU. For AnonCVS it might be a nice idea to set up a memory resident file system (MFS) of at least 300 MB, so you need to take this into account for your memory requirements. The following are just examples to give you a very rough hint. For a moderately visited site that offers rsync, you might consider a current CPU with around 800MHz - 1 GHz, and at least 512MB RAM. This is probably the minimum you want for an official site. For a frequently used site you definitely need more RAM (consider 2GB as a good start) and possibly more CPU, which could also mean that you need to go for a SMP system. You also want to consider a fast disk subsystem. Operations on the CVS repository require a fast disk subsystem (RAID is highly advised). A SCSI controller that has a cache of its own can also speed up things since most of these services incur a large number of small modifications to the disk. Services to offer Every mirror site is required to have a set of core services available. In addition to these required services, there are a number of optional services that server administrators may choose to offer. This section explains which services you can provide and how to go about implementing them. FTP (required for FTP fileset) This is one of the most basic services, and it is required for each mirror offering public FTP distributions. FTP access must be anonymous, and no upload/download ratios are allowed (a ridiculous thing anyway). Upload capability is not required (and must never be allowed for the FreeBSD file space). Also the FreeBSD archive should be available under the path /pub/FreeBSD. There is a lot of software available which can be set up to allow anonymous FTP (in alphabetical order). /usr/libexec/ftpd: FreeBSD's own ftpd can be used. Be sure to read &man.ftpd.8;. ftp/ncftpd: A commercial package, free for educational use. ftp/oftpd: An ftpd designed with security as a main focus. ftp/proftpd: A modular and very flexible ftpd. ftp/pure-ftpd: Another ftpd developed with security in mind. ftp/twoftpd: As above. ftp/vsftpd: The very secure ftpd. ftp/wu-ftpd: The ftpd from Washington University. It has become infamous, because of the huge amount of security issues that have been found in it. If you do choose to use this software be sure to keep it up to date. FreeBSD's ftpd, proftpd, wu-ftpd and maybe ncftpd are among the most commonly ones. The others do not have a large userbase among mirror sites. One thing to consider is that you may need flexibility in limiting how many simultaneous connections are allowed, thus limiting how much network bandwidth and system resources are consumed. RSYNC (optional for FTP fileset) rsync is often offered for access to the contents of the FTP area of FreeBSD, so other mirror sites can use your system as their source. The protocol is different from FTP in many ways. It is much more bandwidth friendly, as only differences between files are transferred instead of whole files when they change. rsync does require a significant amount of memory for each instance. The size depends on the size of the synced module in terms of the number of directories and files. rsync can use rsh and ssh (now default) as a transport, or use its own protocol for stand-alone access (this is the preferred method for public rsync servers). Authentication, connection limits, and other restrictions may be applied. There is just one software package available: net/rsync HTTP (required for web pages, optional for FTP fileset) If you want to offer the FreeBSD web pages, you need to install a web server a.k.a. httpd. You may optionally offer the FTP fileset via HTTP. The choice of web server software is left up to the mirror administrator. Some of the most popular choices are: www/apache13: Apache is the most widely deployed web server on the Internet. It is used extensively by the FreeBSD Project. You may also wish to use the next generation of the Apache web server, available in the ports collection as www/apache2. www/thttpd: If you are going to be serving a large amount of static content you may find that using an application such as thttpd is more efficient than Apache. It is optimized for excellent performance on FreeBSD. www/boa: Boa is another alternative to thttpd and Apache. It should provide considerably better performance than Apache for purely static content. It does not, at the time of writing, contain the same set of optimizations for FreeBSD that are found in thttpd. CVSup (desired for CVS repository) CVSup is a very efficient way of distributing files. It works similar to rsync, but was specially designed for use with CVS repositories. If you want to offer the FreeBSD CVS repository, you really want to consider offering it via CVSup. It is possible to offer the CVS repository via AnonCVS, FTP, Rsync or HTTP, but people would benefit much more from CVSup access. CVSup was developed by &a.jdp;. It is a bit tricky to install on non-FreeBSD platforms, since it is written in Modula-3 and therefore requires a Modula-3 environment. John Polstra has built a stripped down version of M3 that is sufficient to run CVSup, and can be installed much easier. See Ezm3 for details. Related ports are: net/cvsup: The native CVSup port (client and server) which requires lang/ezm3 now. net/cvsup-mirror: The CVSup mirror kit, which requires net/cvsup, and configures it mirror-ready. Some site administrators may want a different setup though. There are a few more like net/cvsup-without-gui you might want to have a look at. If you prefer a static binary package, take a look here. This page still refers to the S1G bug that was present in CVSup. Maybe John will set up a generic download-site to get static binaries for various platforms. It is possible to use CVSup to offer any kind of fileset, not just CVS repositories, but configuration can be complex. CVSup is known to eat some CPU on both the server and the client, since it needs to compare lots of files. AnonCVS (optional for CVS repository) If you have the CVS repository, you may want to offer anonymous CVS access. A short warning first: There is not much demand for it, it requires some experience, and you need to know what you are doing. Generally there are two ways to access a CVS repository remotely: via pserver or via ssh (we don't consider rsh). For anonymous access, pserver is very well suited, but some still offer ssh access as well. There is a custom crafted wrapper in the CVS repository, to be used as a login-shell for the anonymous ssh account. It does a chroot, and therefore requires the CVS repository to be available under the anonymous user's home-directory. This may not be possible for all sites. If you just offer pserver this restriction does not apply, but you may run with more security risks. You don't need to install any special software, since &man.cvs.1; comes with FreeBSD. You need to enable access via inetd, so add an entry into your /etc/inetd.conf like this: cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --allow-root=/home/ncvs pserver See the manpage for details of the options. Also see the CVS info page about additional ways to make sure access is read-only. It is advised that you create an unprivileged account, preferably called anoncvs. Also you need to create a file passwd in your /home/ncvs/CVSROOT and assign a CVS password (empty or anoncvs) to that user. The directory /anoncvstmp is a special purpose memory based file system. It is not required but advised since &man.cvs.1; creates a shadow directory structure in your /tmp which is not used after the operation but slows things dramatically if real disk operations are required. Here is an excerpt from /etc/fstab, how to set up such a MFS: /dev/da0s1b /anoncvstmp mfs rw,-s=786432,-b=4096,-f=512,-i=560,-c=3,-m=0,nosuid,nodev 0 0 This is (of course) tuned a lot, and was suggested by &a.jdp;. How to Mirror FreeBSD Ok, now you know the requirements and how to offer the services, but not how to get it. :-) This section explains how to actually mirror the various parts of FreeBSD, what tools to use, and where to mirror from. FTP The FTP area is the largest amount of data that needs to be mirrored. It includes the distribution sets required for network installation, the branches which are actually snapshots of checked-out source trees, the ISO Images to write CD-ROMs with the installation distribution, a live file system, lots of packages, the ports tree, distfiles, and a huge amount of packages. All of course for various FreeBSD versions, and various architectures. With FTP mirror You can use a FTP mirror program to get the files. There are a lot around and widely used, like: ftp/mirror ftp/ftpmirror ftp/emirror ftp/spegla ftp/omi some even use ftp/wget ftp/mirror was very popular, but seemed to have some drawbacks, as it is written in &man.perl.1;, and had real problems with mirroring large directories like a FreeBSD site. There are rumors that the current version has fixed this by allowing a different algorithm for comparing the directory structure to be specified. In general FTP is not really good for mirroring. It transfers the whole file if it has changed, and does not create a single data stream which would benefit from a large TCP congestion window. With RSYNC A better way to mirror the FTP area is rsync. You can install the port net/rsync and then use rsync to sync with your upstream host. rsync is already mentioned in . Since rsync access is not required, your preferred upstream site may not allow it. You may need to hunt around a little bit to find a site that allows rsync access. Since the number of rsync clients will have a significant impact on the server machine, most admins impose limitations on their server. For a mirror, you should ask the site maintainer you are syncing from about their policy, and maybe an exception for your host (since you are a mirror). A command line to mirror FreeBSD could look like that: &prompt.user; rsync -vaz --delete ftp4.de.FreeBSD.org::FreeBSD/ /pub/FreeBSD/ Consult the documentation for rsync, which is also available at http://rsync.samba.org/ about the various options to be used with rsync. If you sync the whole module (unlike subdirectories), be aware that the module-directory (here "FreeBSD") will not be created, so you cannot omit the target directory. Also you might want to set up a script framework that calls such a command via &man.cron.8;. With CVSup A few sites, including the one-and-only ftp-master.FreeBSD.org even offer CVSup to mirror the contents of the FTP space. You need to install a cvsup client, preferably from the port net/cvsup. (Also reread .) A sample supfile suitable for ftp-master.FreeBSD.org looks like this: # # FreeBSD archive supfile from master server # *default host=ftp-master.FreeBSD.org *default base=/usr *default prefix=/pub #*default release=all *default delete use-rel-suffix *default umask=002 # If your network link is a T1 or faster, comment out the following line. #*default compress FreeBSD-archive release=all preserve It seems CVSup would be the best way to mirror the archive in terms of efficiency, but it is only available from few sites. Please have look at the CVSup documentation like &man.cvsup.1; and consider using the option, as it can reduce the amount of work to be done a lot. Mirroring the CVS repository Again you have various possibilities, but the most recommended one is to use CVSup. Using CVSup CVSup was already described to some detail in and . Here we just describe an example to set up the supfile: # # FreeBSD CVS supfile from master server # *default host=cvsup-master.FreeBSD.org *default base=/usr *default prefix=/pub/FreeBSD/development/FreeBSD-CVS *default release=cvs *default delete use-rel-suffix *default umask=002 # If your network link is a T1 or faster, comment out the following line. #*default compress cvs-all You should also have a look at /usr/share/examples/cvsup Please do not forget to consider the hint mentioned in this note above. Using other methods Using other methods than CVSup is generally not recommended. We describe them in short here anyway. Since most sites offer the CVS repository as part of the FTP fileset under the path /pub/FreeBSD/development/FreeBSD-CVS, the following methods could be used. FTP RSYNC maybe even HTTP If you find a site that supports it, you could use net/sup. But it is inferior to CVSup and its deficiencies caused John Polstra to develop CVSup in the first place, so it is clearly not recommended. You can NOT use AnonCVS to mirror the CVS repository since CVS does not allow you to access the repository itself, but only checked out versions of the modules. Mirroring the WWW pages The best way is to check out the www distribution from CVS. If you have a local mirror of the CVS repository, it is probably as easy as: &prompt.user; cvs -d /home/ncvs co www and a cronjob, that calls cvs up -d -P on a regular basis, maybe just after your repository was updated. Of course, the files need to remain in a directory available for public WWW access. The installation and configuration of a web server is not discussed here. For the website to be visible, users must execute the &man.make.1; command in the main www directory. This command will create the standard *.html files for web viewing. For this to work however, the textproc/docproj port must be installed. If you don't have a local repository, you can use CVSup to maintain an up to date copy of the www pages. A sample supfile can be found in /usr/share/examples/cvsup/www-supfile and could look like this: # # WWW module supfile for FreeBSD # *default host=cvsup3.de.FreeBSD.org *default base=/usr *default prefix=/usr/local *default release=cvs tag=. *default delete use-rel-suffix # If your network link is a T1 or faster, comment out the following line. *default compress # This collection retrieves the www/ tree of the FreeBSD repository www Using ftp/wget or other web-mirror tools is probably not recommended. Mirroring the FreeBSD documentation Since the documentation is referenced a lot from the web pages, it is recommended that you mirror the FreeBSD documentation as well. However, this is not as trivial as the www-pages alone. First of all, you should get the doc sources, again preferably via CVSup. Here is a corresponding sample supfile: # # FreeBSD documentation supfile # *default host=cvsup3.de.FreeBSD.org *default base=/usr *default prefix=/usr/share *default release=cvs tag=. *default delete use-rel-suffix # If your network link is a T1 or faster, comment out the following line. #*default compress # This will retrieve the entire doc branch of the FreeBSD repository. # This includes the handbook, FAQ, and translations thereof. doc-all Then you need to install a couple of ports. You are lucky, there is a meta-port: textproc/docproj to do the work for you. You need to set up some environment variables, like SGML_CATALOG_FILES. Also have a look at your /etc/make.conf (copy /etc/defaults/make.conf if you do not have one), and look at the DOC_LANG variable. Now you are probably ready to run make in you doc directory (/usr/share/doc by default) and build the documentation. Again you need to make it accessible for your web server and make sure the links point to the right location. The building of the documentation, as well as lots of side issues, is documented itself in: fdp-primer. Please read this piece of documentation, especially if you have problems building the documentation. XXX MAYBE THIS CAN BE LINKED FROM WITHIN - NOT USING AN ABSOLUTE URL XXX How often should I mirror? Every mirror should be updated on a regular basis. You will certainly need some script framework for it that will be called by &man.cron.8;. Since nearly every admin does this his own way, we cannot give specific instructions. It could work like this: Put the command to run your mirroring application in a script. Use of a plain /bin/sh script is recommended. Add some output redirections so diagnostic messages are logged to a file. Test if your script works. Check the logs. Use &man.crontab.1; to add the script to the appropriate user's &man.crontab.5;. This should be a different user than what your FTP daemon runs as so that if file permissions inside your FTP area are not world-readable those files can not be accessed by anonymous FTP. This is used to stage releases — making sure all of the official mirror sites have all of the necessary release files on release day. Here are some recommended schedules: FTP fileset: daily CVS repository: daily to hourly WWW pages: daily Where to mirror from This is an important issue. So this section will spend some effort to explain the backgrounds. We will say this several times: under no circumstances should you mirror from ftp.FreeBSD.org. A few words about the organization Mirrors are organized by country. All official mirrors have a DNS entry of the form ftpN.CC.FreeBSD.org. CC (i.e. country code) is the top level domain (TLD) of the country where this mirror is located. N is a number, telling that the host would be the Nth mirror in that country. (Same applies to cvsupN.CC.FreeBSD.org, wwwN.CC.FreeBSD.org, etc.) There are mirrors with no CC part. These are the mirror sites that are very well connected and allow a large number of concurrent users. ftp.FreeBSD.org is actually two machines, one currently located in Denmark and the other in the United States. It is NOT a master site and should never be used to mirror from. Lots of online documentation leads interactiveusers to ftp.FreeBSD.org so automated mirroring systems should find a different machine to mirror from. Additionally there exists a hierarchy of mirrors, which is described in terms of tiers. The master sites are not referred to but can be described as Tier-0. Mirrors that mirror from these sites can be considered Tier-1, mirrors of Tier-1-mirrors, are Tier-2, etc. Official sites are encouraged to be of a low tier, but the lower the tier the higher the requirements in terms as described in . Also access to low-tier-mirrors may be restricted, and access to master sites is definitely restricted. The tier-hierarchy is not reflected by DNS and generally not documented anywhere except for the master sites. However, official mirrors with low numbers like 1-4, are usually Tier-1 (this is just a rough hint, and there is no rule). Ok, but where should I get the stuff now? Under no circumstances should you mirror from ftp.FreeBSD.org. The short answer is: from the site that is closest to you in Internet terms, or gives you the fastest access. I just want to mirror from somewhere! If you have no special intentions or requirements, the statement in applies. This means: Look at available mirrors in your country. The FreeBSD Mirror Database can help you with this. Check for those which provide fastest access (number of hops, round-trip-times) and offer the services you intend to use (like rsync or CVSup). Contact the administrators of your chosen site stating your request, and asking about their terms and policies. Set up your mirror as described above. I'm an official mirror, what is the right site for me? In general the description in still applies. Of course you may want to put some weight on the fact that your upstream should be of a low tier. There are some other considerations about official mirrors that are described in . I want to access the master sites! If you have good reasons and good prerequisites, you may want and get access to one of the master sites. Access to these sites is generally restricted, and there are special policies for access. If you are already an official mirror, this certainly helps you getting access. In any other case make sure your country really needs another mirror. If it already has three or more, ask the zone administrator (hostmaster@CC.FreeBSD.org) or &a.hubs; first. Whoever helped you become, an official should have helped you gain access to an appropriate upstream host, either one of the master sites or a suitable Tier-1 site. If not, you can send email to mirror-admin@FreeBSD.org to request help with that. There are three master sites for the FTP fileset and one for the CVS repository (the web pages and docs are obtained from CVS, so there is no need for master). ftp-master.FreeBSD.org This is the master site for the FTP fileset. ftp-master.FreeBSD.org provides rsync and CVSup access, rather in addition to ftp protocol. Refer to and how to access via these protocols. Mirrors should be encouraged to also allow rsync access for the FTP contents, since they are Tier-1-mirrors. cvsup-master.FreeBSD.org This is the master site for the CVS repository. cvsup-master.FreeBSD.org provides CVSup access only. See for details. To get access, you need to contact &a.cvsup-master;. Make sure you read FreeBSD CVSup Access Policy first! Set up the required authentication by following these instructions. Make sure you specify the server as freefall.FreeBSD.org on the cvpasswd command line, as described in this document, even when you are contacting cvsup-master.FreeBSD.org Official Mirrors Official mirrors are mirrors that a) have a FreeBSD.org DNS entry (usually a CNAME). b) are listed as an official mirror in the FreeBSD documentation (like handbook). So far to distinguish official mirrors. Official mirrors are not necessarily Tier-1-mirrors. However you probably won't find a Tier-1-mirror, that is not also official. Special Requirements for official (tier-1) mirrors It is not so easy to state requirements for all official mirrors, since the project is sort of tolerant here. It is more easy to say, what official tier-1 mirrors are required to. All other official mirrors can consider this a big should. The following applies mainly to the FTP fileset, since a CVS repository should always be mirrored completely, and the web pages are a case of its own. Tier-1 mirrors are required to: carry the complete fileset allow access to other mirror sites provide FTP and RSYNC access Furthermore, admins should be subscribed to the &a.hubs;. See this link for details, how to subscribe. It is very important for a hub administrator, especially Tier-1 hub admins, to check the release schedule for the next FreeBSD release. This is important because it will tell you when the next release is scheduled to come out, and thus giving you time to prepare for the big spike of traffic which follows it. It is also important that hub administrators try to keep their mirrors as up-to-date as possible (again, even more crucial for Tier-1 mirrors). If Mirror1 doesn't update for a while, lower tier mirrors will begin to mirror old data from Mirror1 and thus begins a downward spiral... Keep your mirrors up to date! How to become official then? An interesting question, especially, since the state of being official comes with some benefits, like a much higher bill from your ISP as more people will be using your site. Also it may be a key requirement to get access to a master site. Before applying, please consider (again) if another official mirror is really needed for your region. Check first with your zone administrator (hostmaster@CC.FreeBSD.org) or, if that fails, ask on the &a.hubs;. Ok, here is how to do it: Get the mirror running in first place (maybe not using a master site, yet). Subscribe to the &a.hubs;. If everything works so far, contact the DNS administrator responsible for your region/country, and ask for a DNS entry for your site. The admin should able to be contacted via hostmaster@CC.FreeBSD.org, where CC is your country code/TLD. Your DNS entry will be as described in . If there is no subdomain set up for your country yet, you should contact mirror-admin@FreeBSD.org, or you can try the &a.hubs; first. Whoever helps you get an official name should send email to mirror-admin@FreeBSD.org so your site will be added to the mirror list in the FreeBSD Handbook. That is it. Some statistics from mirror sites Here are links to the stat pages of your favorite mirrors (a.k.a. the only ones who feel like providing stats). FTP site statistics ftp2.FreeBSD.org - grisha@ispol.com - (Bandwidth) ftp.is.FreeBSD.org - hostmaster@is.FreeBSD.org - (Bandwidth) (FTP processes) (HTTP processes) ftp.cz.FreeBSD.org - cejkar@fit.vutbr.cz - (Bandwidth) (FTP processes) (Rsync processes) ftp4.de.FreeBSD.org - dl@leo.org - (FTP users) (RSYNC users) CVSup site stats cvsup[23456].jp.FreeBSD.org - kuriyama@FreeBSD.org - (CVSup processes) cvsup.cz.FreeBSD.org - cejkar@fit.vutbr.cz - (CVSup processes) [cvsup3|anoncvs].de.FreeBSD.org - dl@leo.org - (CVSup processes)
diff --git a/en_US.ISO8859-1/articles/ipsec-must/article.sgml b/en_US.ISO8859-1/articles/ipsec-must/article.sgml index 338a83c789..a5562b631e 100644 --- a/en_US.ISO8859-1/articles/ipsec-must/article.sgml +++ b/en_US.ISO8859-1/articles/ipsec-must/article.sgml @@ -1,350 +1,344 @@ -%man; - - -%trademarks; - - -%urls; + +%articles.ent; ]>
Independent Verification of IPsec Functionality in FreeBSD David Honig
honig@sprynet.com
 3 May 1999 &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; You installed IPsec and it seems to be working. How do you know? I describe a method for experimentally verifying that IPsec is working. The Problem First, let's assume you have installed IPsec. How do you know it is working? Sure, your connection will not work if it is misconfigured, and it will work when you finally get it right. &man.netstat.1; will list it. But can you independently confirm it? The Solution First, some crypto-relevant info theory: encrypted data is uniformly distributed, i.e., has maximal entropy per symbol; raw, uncompressed data is typically redundant, i.e., has sub-maximal entropy. Suppose you could measure the entropy of the data to- and from- your network interface. Then you could see the difference between unencrypted data and encrypted data. This would be true even if some of the data in encrypted mode was not encrypted---as the outermost IP header must be, if the packet is to be routable. MUST Ueli Maurer's Universal Statistical Test for Random Bit Generators( MUST) quickly measures the entropy of a sample. It uses a compression-like algorithm. The code is given below for a variant which measures successive (~quarter megabyte) chunks of a file. Tcpdump We also need a way to capture the raw network data. A program called &man.tcpdump.1; lets you do this, if you have enabled the Berkeley Packet Filter interface in your kernel's config file. The command tcpdump -c 4000 -s 10000 -w dumpfile.bin will capture 4000 raw packets to dumpfile.bin. Up to 10,000 bytes per packet will be captured in this example. The Experiment Here is the experiment: Open a window to an IPsec host and another window to an insecure host. Now start capturing packets. In the secure window, run the &unix; command &man.yes.1;, which will stream the y character. After a while, stop this. Switch to the insecure window, and repeat. After a while, stop. Now run MUST on the captured packets. You should see something like the following. The important thing to note is that the secure connection has 93% (6.7) of the expected value (7.18), and the normal connection has 29% (2.1) of the expected value. &prompt.user; tcpdump -c 4000 -s 10000 -w ipsecdemo.bin &prompt.user; uliscan ipsecdemo.bin Uliscan 21 Dec 98 L=8 256 258560 Measuring file ipsecdemo.bin Init done Expected value for L=8 is 7.1836656 6.9396 -------------------------------------------------------- 6.6177 ----------------------------------------------------- 6.4100 --------------------------------------------------- 2.1101 ----------------- 2.0838 ----------------- 2.0983 ----------------- Caveat This experiment shows that IPsec does seem to be distributing the payload data uniformly, as encryption should. However, the experiment described here cannot detect many possible flaws in a system (none of which do I have any evidence for). These include poor key generation or exchange, data or keys being visible to others, use of weak algorithms, kernel subversion, etc. Study the source; know the code. IPsec---Definition Internet Protocol security extensions to IPv4; required for IPv6. A protocol for negotiating encryption and authentication at the IP (host-to-host) level. SSL secures only one application socket; SSH secures only a login; PGP secures only a specified file or message. IPsec encrypts everything between two hosts. Installing IPsec Most of the modern versions of FreeBSD have IPsec support in their base source. So you will probably will need to include option in your kernel config and, after kernel rebuild and reinstall, configure IPsec connections using &man.setkey.8; command. A comprehensive guide on running IPsec on FreeBSD is provided in FreeBSD Handbook. src/sys/i386/conf/KERNELNAME This needs to be present in the kernel config file in order to be able to capture network data with &man.tcpdump.1;. Be sure to run &man.config.8; after adding this, and rebuild and reinstall. device bpf Maurer's Universal Statistical Test (for block size=8 bits) You can find the same code at this link. /* ULISCAN.c ---blocksize of 8 1 Oct 98 1 Dec 98 21 Dec 98 uliscan.c derived from ueli8.c This version has // comments removed for Sun cc This implements Ueli M Maurer's "Universal Statistical Test for Random Bit Generators" using L=8 Accepts a filename on the command line; writes its results, with other info, to stdout. Handles input file exhaustion gracefully. Ref: J. Cryptology v 5 no 2, 1992 pp 89-105 also on the web somewhere, which is where I found it. -David Honig honig@sprynet.com Usage: ULISCAN filename outputs to stdout */ #define L 8 #define V (1<<L) #define Q (10*V) #define K (100 *Q) #define MAXSAMP (Q + K) #include <stdio.h> #include <math.h> int main(argc, argv) int argc; char **argv; { FILE *fptr; int i,j; int b, c; int table[V]; double sum = 0.0; int iproduct = 1; int run; extern double log(/* double x */); printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP); if (argc < 2) { printf("Usage: Uliscan filename\n"); exit(-1); } else { printf("Measuring file %s\n", argv[1]); } fptr = fopen(argv[1],"rb"); if (fptr == NULL) { printf("Can't find %s\n", argv[1]); exit(-1); } for (i = 0; i < V; i++) { table[i] = 0; } for (i = 0; i < Q; i++) { b = fgetc(fptr); table[b] = i; } printf("Init done\n"); printf("Expected value for L=8 is 7.1836656\n"); run = 1; while (run) { sum = 0.0; iproduct = 1; if (run) for (i = Q; run && i < Q + K; i++) { j = i; b = fgetc(fptr); if (b < 0) run = 0; if (run) { if (table[b] > j) j += K; sum += log((double)(j-table[b])); table[b] = i; } } if (!run) printf("Premature end of file; read %d blocks.\n", i - Q); sum = (sum/((double)(i - Q))) / log(2.0); printf("%4.4f ", sum); for (i = 0; i < (int)(sum*8.0 + 0.50); i++) printf("-"); printf("\n"); /* refill initial table */ if (0) { for (i = 0; i < Q; i++) { b = fgetc(fptr); if (b < 0) { run = 0; } else { table[b] = i; } } } } }
diff --git a/en_US.ISO8859-1/articles/java-tomcat/article.sgml b/en_US.ISO8859-1/articles/java-tomcat/article.sgml index 5fce6ed1c3..62b421d349 100644 --- a/en_US.ISO8859-1/articles/java-tomcat/article.sgml +++ b/en_US.ISO8859-1/articles/java-tomcat/article.sgml @@ -1,617 +1,611 @@ -%man; - - -%trademarks; - - -%urls; + +%articles.ent; ]>
&java; and Jakarta Tomcat on FreeBSD Victoria Chan
vkchan@kendryl.net
 Hiten Pandya
hmp@FreeBSD.org
 2002 2003 2004 Victoria Chan Hiten Pandya $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.sun; &tm-attrib.general; This document is presented in hopes of making it easier for anyone that needs to get &java; up and running on FreeBSD, with the least amount of aggravation. Plan on spending a whole day on such a project as it will take time to assemble all the pieces and compile them individually, and then as a whole. It also shows how to install the famous Jakarta Tomcat Servlet and &jsp; container on the FreeBSD operating system. Introduction The &java; programming language was birthed on May 23rd 1995. One would expect that after all this time, &java; applications would be easy to install and ready to run from a single package, or port on FreeBSD, thus making it available for the masses. This is not the case, unfortunately, as the &java; distribution is held very closely by Sun Microsystems, and prohibits re-distribution. All &java; Applets must be compiled from source code, together with the &java; Development Kit from Sun Microsystems. All these ingredients must be blended together in the right order, assembled, and compiled by the end user. With such distribution philosophies at heart, it is my opinion that &java; will always be developer or hacker use only. I certainly found this to be true when I needed to serve up some .jsp pages for a client on my web server, and needed to get www/jakarta-tomcat4 to work with www/apache13 on my FreeBSD system. The Tomcat portion of the install is very straight forward, but the difficulty I had was getting &java; Development Kit up and running for FreeBSD 4.X, as Sun Microsystems only supplies Binaries for Linux, &solaris;, and &windowsnt;. This means that I had to compile my own &jdk; for FreeBSD. I began by searching for documentation on the Internet. I quickly found that there is more source code than I need along with patches to the source code, but very little documentation of what to do after obtaining everything. In this article, you will find how to install the &java; Development Kit for FreeBSD, and how to get up and running with Tomcat. A section is also provided for further reading. The &java; Environment Ensure that you have the current ports collection as make it will fail if it attempts to build older source. You can upgrade your entire ports collection by using CVSup. See Using CVSup section of the Handbook for more information. You can also download the ports you need manually from to get you going. You will need the Linux Emulation (Linux-ABI) enabled in your kernel configuration. Simply add the following option to your kernel configuration file and recompile it. Instructions for building a kernel can be found in the FreeBSD Handbook. options COMPAT_LINUX The above option will add Linux-ABI support to your kernel, when it is recompiled. The list of dependencies below, are required to be installed manually in a certain order. Dependencies that are automatically downloaded are not listed here. java/jdk13 java/linux-jdk13 You will need to get the following: Download bsd-jdk131-patches-9.tar.gz from and place it under /usr/ports/distfiles. Next get out your web browser and head on over to and find SDK downloads. Click on the continue button below GNUZIP Tar Shell Script. Be sure you read every word of the license page before you click on the Accept button! You will be brought to a page titled Download Java(TM) 2 SDK, Standard Edition 1.3.1_10. Scroll to the bottom and click on the HTTP download button. When the File Download box comes up, be sure to click on the Open button rather than the Save button. You will be presented with another File Download box - this time choose Save and you will be able to save j2sdk-1_3_1_10-linux-i386.bin. Place it in /usr/ports/distfiles. Go to . In the table under Produce Description, named Java 2 SDK 1.3.1, go to the right-hand cell and click download. You will be taken to the Sign On page, where you must sign in if you already have an account, or register for access. Once you have signed on, you will be taken to the Legal page, where you must accept the license agreement; scroll down (reading the license) and click on the Continue button. Next page, is the Receipt page. This is where you will save your order number. You will be able to choose the location that is nearest to you. Click on Java 2 SDK, Standard Edition, version 1.3.1. Save the j2sdk-1_3_1-src.tar.gz to the /usr/ports/distfiles/ directory. It is very important for you to read the License Agreement which has been issued by Sun Microsystems Corp. There are several restrictions in place on the use of &java;, which you must address. The FreeBSD Project does not take any responsibilities for your actions. Do not discard any of the downloaded files, as they will be needed for building some of the native ports for FreeBSD, which are discussed later on. Now that you have assembled all the source files and ports, you need to start by building java/linux-jdk13: &prompt.root; cd /usr/ports/java/linux-jdk13 &prompt.root; make all install clean Once you have built java/linux-jdk13, you need to test it, to make sure it works as intended. To do that: &prompt.root; cd /usr/local/linux-jdk1.3.1/bin &prompt.root; ./java -version The output of the above command should be as follows: java version "1.3.1_10" Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_10-b02) Classic VM (build 1.3.1_02-b02, green threads, nojit) If you did not get the correct response, you need to: &prompt.root; cd /usr/ports/java/linux-jdk13 &prompt.root; make deinstall And make sure that /usr/local does not contain a linux-jdk1.3.1 directory. If you find a fragment of the directory, delete it. Repeat the build and install process for java/linux-jdk13. To make the native Java Development Kit 1.3.1 for FreeBSD, do the following: Make sure you have the j2sdk-1_3_1-src.tar.gz file in your /usr/ports/distfiles. This file is needed for applying the patch-set discussed below. You will need to download the patch set for building the port. The patch-set file is called bsd-jdk131-patches-9.tar.gz. You should also make sure the integrity of the files by matching it with the following MD5 checksum. MD5 (bsd-jdk131-patches-9.tar.gz) = 29c83880d3555abcf74fc7df9db1959f The patch-set is available from: The last procedure discussed above (building the native &jdk;) will take some time. Jakarta Tomcat Setup Overview &java; is becoming an even more popular for making diverse and scalable platform independent solutions. One of the most growing needs of &java; is in the ASP (Application Service Provider) market. &java; serves as the perfect solution for these types of markets, with the following advantages: Platform Independence Industry Wide Commitment Scalability Reliable Performance Distributed, Multi-threaded, Secure etc. A very important and growing technology which has emerged from &java; is &jsp; (&javaserver.pages;). &jsp; (&javaserver.pages;) is a server-side technology introduced by Sun Microsystems Corp., which provides a quick simple way to generate dynamic content from within HTML pages. It uses XML tags along with &java; scriptlets to encapsulate and separate the logic from the design and display. When a &jsp; page is invoked, it is dynamically converted into a Servlet and processed by the server to produce the resulting HTML/XML page for the client. When &jsp; is used in conjunction with JavaBeans, it is possible to produce very diverse and scalable applications, which may be combined with the strength and performance of FreeBSD. Tomcat is an open-source implementation of the &java; Servlets and &javaserver.pages; technologies, developed under the Jakarta project at the Apache Software Foundation. Tomcat implements a new Servlet framework (called Catalina) that is based on completely new architecture with the Servlet 2.3 and &jsp; 1.2 specifications. It includes many additional features that make it a useful platform for developing and deploying web applications and web services. In a nutshell, Tomcat is an application server written in 100% Pure &java;. Tomcat is used for many purposes, and is not limited to Application Servers. It provides an open platform to develop extensible web and content management services. When Tomcat is used with an optimized FreeBSD system, it can provide highly reliable and fast pacing services. Please refer to the section for more information on Tomcat and &jsp;. The next section will demonstrate how to build the Tomcat Environment for FreeBSD. The version of Tomcat used in this guide is 4.0.6. This version contains major bug fixes, and the following updates/changes: JSP 1.2 Specification Java Servlet 2.3 Specification Full backward compatibility with the Java Servlet 2.2 and JSP 1.1 Specification The Tomcat environment for FreeBSD It is very simple to install Tomcat on a FreeBSD machine, after setting up the necessary &java; environment, which we have previously completed. In-order to set up Tomcat on FreeBSD, follow the below procedure: Follow the above steps to set up the necessary &java; environment. Set an environment variable JAVA_HOME which, points to the directory where you have installed the &jdk; (the examples below point to a native build of the &jdk;). If you are using &man.sh.1; as your shell, you can set JAVA_HOME with: &prompt.root; export JAVA_HOME="/usr/local/jdk1.3.1" Those who use &man.csh.1; or a compatible shell, must use a slightly different command: &prompt.root; setenv JAVA_HOME /usr/local/jdk1.3.1 This environment variable should be made permanent by adding it into either .profile or .cshrc, depending on the shell you are using. This variable is very crucial for the functioning of all the &java; based programs, including Tomcat itself. Download the Tomcat binary distribution from the Jakarta website, which is located at . The file to download is called jakarta-tomcat-4.0.6.tar.gz. The compressed and archived file we downloaded in the previous step uses special GNU Extensions. In-order to untar and uncompress the file, we will need to install GNU Tar (archivers/gtar), by doing the following: &prompt.root; cd /usr/ports/archivers/gtar && make all install clean Un-tar and Un-compress the jakarta-tomcat-4.0.6.tar.gz file into the /usr/local directory and rename the directory to tomcat-4.0 for ease of reference: &prompt.root; cd /usr/local &prompt.root; gtar zxvf jakarta-tomcat-4.0.6.tar.gz &prompt.root; ls jakarta* jakarta-tomcat-4.0.6 &prompt.root; mv jakarta-tomcat-4.0.6 tomcat-4.0 You can remove the jakarta-tomcat-4.0.6.tar.gz at your preference. Installation by using the source code is currently out of scope for this document. Please refer to the following files for addition information on building from source, available from your Tomcat distribution directory: /usr/local/tomcat-4.0/README.txt /usr/local/tomcat-4.0/BUILDING.txt Operating Tomcat - Basics Now that we have finished installing Tomcat. The following example shows how to start the Tomcat server: &prompt.root; cd /usr/local/tomcat-4.0/bin &prompt.root; ./startup.sh (for starting Tomcat) You can test if your Tomcat server has started by visiting the following URL: http://127.0.0.1:8080 or http://localhost:8080. To stop Tomcat: &prompt.root; cd /usr/local/tomcat-4.0/bin &prompt.root; ./shutdown.sh (for stopping Tomcat) The startup.sh and shutdown.sh are frontends to the catalina.sh executable script in the same directory; if you would like to start Tomcat automatically at boot-time run: &prompt.root; cd /usr/local/etc/rc.d &prompt.root; ln -s /usr/local/tomcat-4.0/bin/catalina.sh Edit the catalina.sh, and add the following at the beginning of the file (after the comment box): JAVA_HOME=/usr/local/jdk1.3.1 If your port 8080 is occupied by some other service, you can change it by editing the server.xml in your Tomcat's conf/ directory. In the example below, the port will be changed to 80, assuming there is no service running on that port. &prompt.root; cd /usr/local/tomcat-4.0/conf &prompt.root; fgrep -n 8080 server.xml ~65: By default, a non-SSL HTTP/1.1 Connector is established on port 8080. ~89: port="8080" minProcessors="5" maxProcessors="75" &prompt.root; cat server.xml | sed s/8080/80/ > server.xml.new &prompt.root; mv server.xml.new server.xml Reference The FreeBSD &java; Project JavaSoft. Home of &java; The Sun Community Source Licensing for &java; Jakarta Tomcat Homepage J2SE Documentation FreeBSD Ports - &java; Section Conclusion Finally, we are at the end of the article and have a working version of Tomcat. We hope that you have learned the basics of installing and building the &java; Development Kit on FreeBSD, along with installation of the Tomcat binary distribution application server released by the Apache Software Foundation. The section contains pointers to additional resources on this topic, some which are in print, some which are on the World Wide Web, or both. The most important thing is drive space. I suggest having 700MB or more free space in /usr. I hope this article has helped you in some small way. For questions, comments, compliments, or rants, please direct them to the authors.
diff --git a/en_US.ISO8859-1/articles/laptop/article.sgml b/en_US.ISO8859-1/articles/laptop/article.sgml index c2b2d7bd96..ea6d649d0a 100644 --- a/en_US.ISO8859-1/articles/laptop/article.sgml +++ b/en_US.ISO8859-1/articles/laptop/article.sgml @@ -1,316 +1,304 @@ -%man; - - -%freebsd; - - -%authors; - - -%mailing-lists; - - -%trademarks; + +%articles.ent; ]>
FreeBSD on Laptops $FreeBSD$ FreeBSD works fine on most laptops, with a few caveats. Some issues specific to running FreeBSD on laptops, relating to different hardware requirements from desktops, are discussed below. &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.xfree86; &tm-attrib.general; FreeBSD is often thought of as a server operating system, but it works just fine on the desktop, and if you want to use it on your laptop you can enjoy all the usual benefits: systematic layout, easy administration and upgrading, the ports/packages system for adding software, and so on. (Its other benefits, such as stability, network performance, and performance under a heavy load, may not be obvious on a laptop, of course.) However, installing it on laptops often involves problems which are not encountered on desktop machines and are not commonly discussed (laptops, even more than desktops, are fine-tuned for µsoft.windows;). This article aims to discuss some of these issues. Several people have also documented their experiences with &os; on specific laptop models on webpages which are not part of the &os; documentation. You might very well find some information if you type the name of your laptop model and the word &os; into a search engine of your choice. Additionally there is a &os;-specific online database which aims to give information on hardware issues with laptops, The &os; Laptop Compatibility List. For communications with other &os; laptop users, check out the &a.mobile.name; list. &xfree86; Recent versions of &xfree86; work with most display adapters available on laptops these days. Acceleration may not be supported, but a generic SVGA configuration should work. Check your laptop documentation for which card you have, and check in the &xfree86; documentation or the Driver Status for &xfree86; page to see whether it is specifically supported. If it is not, use a generic device (do not go for a name which just looks similar). In &xfree86; version 4, you can try your luck with the command XFree86 -configure which auto-detects a lot of configurations. The problem often is configuring the monitor. Common resources for &xfree86; focus on CRT monitors; getting a suitable modeline for an LCD display may be tricky. You may be lucky and not need to specify a modeline, or just need to specify suitable HorizSync and VertRefresh ranges. If that does not work, the best option is to check web resources devoted to configuring X on laptops (these are often Linux oriented sites but it does not matter because both systems use &xfree86;) and copy a modeline posted by someone for similar hardware. Most laptops come with two buttons on their pointing devices, which is rather problematic in X (since the middle button is commonly used to paste text); you can map a simultaneous left-right click in your X configuration to a middle button click with the line Option "Emulate3Buttons" in the XF86Config file in the InputDevice section (for &xfree86; version 4; for version 3, put just the line Emulate3Buttons, without the quotes, in the Pointer section.) Modems Laptops usually come with internal (on-board) modems. Unfortunately, this almost always means they are winmodems whose functionality is implemented in software, for which only &windows; drivers are normally available (though a few drivers are beginning to show up for other operating systems; for example, if your modem has a Lucent LT chipset it might be supported by the comms/ltmdm port). If that is the case, you need to buy an external modem: the most compact option is probably a PC Card (PCMCIA) modem, discussed below, but serial or USB modems may be cheaper. Generally, regular modems (non-winmodems) should work fine. PCMCIA (PC Card) devices Most laptops come with PCMCIA (also called PC Card) slots; these are supported fine under FreeBSD. Look through your boot-up messages (using &man.dmesg.8;) and see whether these were detected correctly (they should appear as pccard0, pccard1 etc on devices like pcic0). &os; 4.X supports 16-bit PCMCIA cards, and &os; 5.X supports both 16-bit and 32-bit (CardBus) cards. A database of supported cards is in the file /etc/defaults/pccard.conf. Look through it, and preferably buy cards listed there. Cards not listed may also work as generic devices: in particular most modems (16-bit) should work fine, provided they are not winmodems (these do exist even as PC Cards, so watch out). If your card is recognised as a generic modem, note that the default pccard.conf file specifies a delay time of 10 seconds (to avoid freezes on certain modems); this may well be over-cautious for your modem, so you may want to play with it, reducing it or removing it totally. Some parts of pccard.conf may need editing. Check the irq line, and be sure to remove any number already being used: in particular, if you have an on board sound card, remove irq 5 (otherwise you may experience hangs when you insert a card). Check also the available memory slots; if your card is not being detected, try changing it to one of the other allowed values (listed in the manual page &man.pccardc.8;). If it is not running already, start the &man.pccardd.8; daemon. (To enable it at boot time, add pccard_enable="YES" to /etc/rc.conf.) Now your cards should be detected when you insert and remove them, and you should get log messages about new devices being enabled. There have been major changes to the pccard code (including ISA routing of interrupts, for machines where &os; is not able to use the PCI BIOS) before the &os; 4.4 release. If you have problems, try upgrading your system. Power management Unfortunately, this is not very reliably supported under FreeBSD. If you are lucky, some functions may work reliably; or they may not work at all. To make things a little more complex, there are two existing standards for power management: APM and ACPI, the latter superseding the former and including more features, but also introducing more problems. Some laptops support both APM and ACPI (to a certain degree), others just support one of them, so chances are that you have to experiment with both of them to have reliable power management on your laptop. You cannot have APM and ACPI enabled at the same time, even if your laptop has support for both of them. APM The APM (Advanced Power Management) BIOS provides support for various power management features like standby, suspend, hibernation, CPU clock slow down etc. and is available under &os; 4.X and &os; 5.X. To enable APM support, you can compile a kernel with power management support (device apm0 on &os; 4.X and device apm on &os; 5.X). A kernel module for APM is available under &os; 5.X, to simply load the APM kernel module at boot add the line apm_load="YES" to /boot/loader.conf. On &os; 5.X, you also have to set hint.apm.0.disabled="0" in /boot/device.hints. You can start APM at boot time by having apm_enable="YES" in /etc/rc.conf. You may also want start the &man.apmd.8; daemon by adding apmd_enable="YES" to /etc/rc.conf, which takes care of various APM events that are posted to the BIOS, so you can have your laptop suspend/resume by pressing some function key on the keyboard or by closing/opening the lid. The APM commands are listed in the &man.apm.8; manual page. For instance, apm -b gives you battery status (or 255 if not supported), apm -Z puts the laptop on standby, apm -z (or zzz) suspends it. To shutdown and power off the machine, use shutdown -p. Again, some or all of these functions may not work very well or at all. You may find that laptop suspension/standby works in console mode but not under X (that is, the screen does not come on again); if you are running &os; 5.X, one solution for this might be to put options SC_NO_SUSPEND_VTYSWITCH in your kernel configuration file and recompile your kernel. Another workaround is to switch to a virtual console (using CtrlAltF1 or another function key) and then execute &man.apm.8;. You can automate this with &man.vidcontrol.1;, if you are running &man.apmd.8;. Simply edit /etc/apmd.conf and change it to this: apm_event SUSPENDREQ { exec "vidcontrol -s 1 < /dev/console"; exec "/etc/rc.suspend"; } apm_event USERSUSPENDREQ { exec "vidcontrol -s 1 < /dev/console"; exec "sync && sync && sync"; exec "sleep 1"; exec "apm -z"; } apm_event NORMRESUME, STANDBYRESUME { exec "/etc/rc.resume"; exec "vidcontrol -s 9 < /dev/console"; } ACPI ACPI (Advanced Configuration and Power Management Interface) provides not only power management but also platform hardware discovery (superseding PnP and PCI BIOS). ACPI is only available under &os; 5.X and is enabled by default, so you do not have to do anything special to get it running. You can control ACPI behaviour with &man.acpiconf.8;. Unfortunately, vendors often ship their laptops with broken ACPI implementations, thus having ACPI enabled sometimes causes more problems than being useful, up to the point that you cannot even boot &os; on some machines with ACPI enabled. If ACPI is causing problems, you might check if your laptop vendor has released a new BIOS version that fixes some bugs. Since the &os; ACPI implementation is still very evolving code, you might also want to upgrade your system; chances are that your problems are fixed. If you want to disable ACPI simply add hint.acpi.0.disabled="1" to /boot/device.hints. You can disable ACPI temporarily at the boot loader prompt by issueing unset acpi_load if you are having problems booting an ACPI enabled machine. &os; 5.1-RELEASE and later come with a boot-time menu that controls how &os; is booted. One of the proposed options is to turn off ACPI. So to disable ACPI just select 2. Boot &os; with ACPI disabled in the menu. Display Power Management The X window system (&xfree86;) also includes display power management (look at the &man.xset.1; manual page, and search for dpms there). You may want to investigate this. However, this, too, works inconsistently on laptops: it often turns off the display but does not turn off the backlight.
diff --git a/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml b/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml index 7570f2cb37..a79cf3a1f4 100644 --- a/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml +++ b/en_US.ISO8859-1/articles/mailing-list-faq/article.sgml @@ -1,557 +1,539 @@ -%man; - - -%freebsd; - - -%authors; - - -%teams; - - -%mailing-lists; - - -%trademarks; - - -%urls; + +%articles.ent; ]>
Frequently Asked Questions About The &os; Mailing Lists The &os; Documentation Project $FreeBSD$ 2004 The &os; Documentation Project This is the FAQ for the &os; mailing lists. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the &os; World Wide Web server. It may also be downloaded as one large HTML file with HTTP or as plain text, PostScript, PDF, etc. from the &os; FTP server. You may also want to Search the FAQ. Introduction As is usual with FAQs, this document aims to cover the most frequently asked questions concerning the &os; mailing lists (and of course answer them!). Although originally intended to reduce bandwidth and avoid the same old questions being asked over and over again, FAQs have become recognized as valuable information resources. This document attempts to represent a community consensus, and as such it can never really be authoritative. However, if you find technical errors within this document, or have suggestions about items that should be added, plase either submit a PR, or email the &a.doc;. Thanks. What is the purpose of the &os; mailing lists? The &os; mailing lists serve as the primary communication channels for the &os; community, covering many different topic areas and communities of interest. Who is the audience for the &os; mailing lists? This depends on charter of each individual list. Some lists are more oriented to developers; some are more oriented towards the &os; community as a whole. Please see this list for the current summary. Are the &os; mailing lists open for anyone to participate? Again, this depends on charter of each individual list. Please read the charter of a mailing list before you post to it, and respect it when you post. This will help everyone to have a better experience with the lists. If after reading the above lists, you still do not know which mailing list to post a question to, you will probably want to post to freebsd-questions (but see below, first). Also note that the mailing lists have traditionally been open to postings from non-subscribers. This has been a deliberate choice, to help make joining the &os; community an easier process, and to encourage open sharing of ideas. However, due to past abuse by some individuals, certain lists now have a policy where postings from non-subscribers must be manually screened to ensure that they are appropriate. How can I subscribe? You can use the Mailman web interface to subscribe to any of the public lists. How can I unsubscribe? You can use the same interface as above; or, you can follow the instructions that are at the bottom of every mailing list message that is sent. Please do not send unsubscribe messages directly to the public lists themselves. First, this will not accomplish your goal, and second, it will irritate the existing subscribers, and you will probably get flamed. This is a classical mistake when using mailing lists; please try to avoid it. Are archives available? Yes. Threaded archives are available here. Are mailing lists available in a digest format? Yes. See the Mailman web interface. Mailing List Etiquette Participation in the mailing lists, like participation in any community, requires a common basis for communication. Please make only appropriate postings, and follow common rules of etiquette. What should I do before I post? You have already taken the most important step by reading this document. However, if you are new to &os;, you may first need to familiarize yourself with the software, and all the social history around it, by reading the numerous books and articles that are available. Items of particular interest include the &os; Frequently Asked Questions (FAQ) document, the &os; Handbook, and the articles How to get best results from the FreeBSD-questions mailing list, Explaining BSD, and &os; First Steps. It is always considered bad form to ask a question that is already answered in the above documents. This is not because the volunteers who work on this project are particularly mean people, but after a certain number of times answering the same questions over and over again, frustration begins to set in. This is particularly true if there is an existing answer to the question that is already available. Always keep in mind that almost all of the work done on &os; is done by volunteers, and that we are only human. What constitutes an inappropriate posting? Postings must be in accordance with the charter of the mailing list. Personal attacks are discouraged. As good net.citizens, we should try to hold ourselves to high standards of behavior. Spam is not allowed, ever. The mailing lists are actively processed to ban offenders to this rule. What is considered proper etiquette when posting to the mailing lists? Please wrap lines at 75 characters, since not everyone uses fancy GUI mail reading programs. Please respect that fact that bandwidth is not infinite. Not everyone reads email through high-speed connections, so if your posting involves something like the content of config.log or an extensive stack trace, please consider putting that information up on a website somewhere and just provide a URL to it. Remember, too, that these postings will be archived indefinitely, so huge postings will simply inflate the size of the archives long after their purpose has expired. Format your message so that it is legible, and PLEASE DO NOT SHOUT!!!!!. Do not underestimate the effect that a poorly formatted mail message has, and not just on the &os; mailing lists. Your mail message is all that people see of you, and if it is poorly formatted, badly spelled, full of errors, and/or has lots of exclamation points, it will give people a poor impression of you. Please use an appropriate human language for a particular mailing list. Many non-English mailing lists are available. For the ones that are not, we do appreciate that many people do not speak English as their first language, and we try to make allowances for that. It is considered particularly poor form to criticize non-native speakers for spelling or grammatical errors. &os; has an excellent track record in this regard; please, help us to uphold that tradition. Please use a standards-compliant Mail User Agent (MUA). A lot of badly formatted messages come from bad mailers or badly configured mailers. The following mailers are known to send out badly formatted messages without you finding out about them: cc:Mail &eudora; (older versions) exmh µsoft; Exchange µsoft; Internet Mail µsoft; &outlook; &netscape; (older versions) As you can see, the mailers in the Microsoft world are frequent offenders. If at all possible, use a &unix; mailer. If you must use a mailer under Microsoft environments, make sure it is set up correctly. Try not to use MIME: a lot of people use mailers which do not get on very well with MIME. Make sure your time and time zone are set correctly. This may seem a little silly, since your message still gets there, but many of the people on these mailing lists get several hundred messages a day. They frequently sort the incoming messages by subject and by date, and if your message does not come before the first answer, they may assume that they missed it and not bother to look. A lot of the information you need to supply is the output of programs, such as &man.dmesg.8;, or console messages, which usually appear in /var/log/messages. Do not try to copy this information by typing it in again; not only it is a real pain, but you are bound to make a mistake. To send log file contents, either make a copy of the file and use an editor to trim the information to what is relevant, or cut and paste into your message. For the output of programs like dmesg, redirect the output to a file and include that. For example, &prompt.user; dmesg > /tmp/dmesg.out This redirects the information to the file /tmp/dmesg.out. When using cut-and-paste, please be aware that some such operations badly mangle their messages. This is of particular concern when posting contents of Makefiles, where tab is a significant character. This is a very common, and very annoying, problem with submissions to the GNATS Problem Reports database. Makefiles with tabs changed to either spaces, or the annoying =3B escape sequence, create a great deal of aggravation for committers. What are the special etiquette consideration when replying to an existing posting on the mailing lists? Please include relevant text from the original message. Trim it to the minimum, but do not overdo it. It should still be possible for somebody who did not read the original message to understand what you are talking about. This is especially important for postings of the type "yes, I see this too", where the initial posting was dozens or hundreds of lines. Use some technique to identify which text came from the original message, and which text you add. A common convention is to prepend > to the original message. Leaving white space after the > and leaving empty lines between your text and the original text both make the result more readable. Please ensure that the attributions of the text you are quoting is correct. People can become offended if you attribute words to them that they themselves did not write. Please do not top post. By this, we mean that if you are replying to a message, please put your replies after the text that you copy in your reply. A: Because it reverses the logical flow of conversation. Q: Why is top posting frowned upon? (Thanks to Randy Bush for the joke.) Recurring Topics On The Mailing Lists Participation in the mailing lists, like participation in any community, requires a common basis for communication. Many of the mailing lists presuppose a knowledge of the Project's history. In particular, there are certain topics that seem to regularly occur to newcomers to the community. It is the responsibility of each poster to ensure that their postings do not fall into one of these categories. By doing so, you will help the mailing lists to stay on-topic, and probably save yourself being flamed in the process. The best method to avoid this is to familiarize yourself with the mailing list archives, to help yourself understand the background of what has gone before. In this, the mailing list search interface is invaluable. (If that method does not yield useful results, please supplement it with a search with your favorite major search engine). By familiarizing yourself with the archives, not only will you learn what topics have been discussed before, but also how discussion tends to proceed on that list, who the participants are, and who the target audience is. These are always good things to know before you post to any mailing list, not just a &os; mailing list. There is no doubt that the archives are quite extensive, and some questions recur more often than others, sometimes as followups where the subject line no longer accurately reflects the new content. Nevertheless, the burden is on you, the poster, to do your homework to help avoid these recurring topics, and especially the dreaded bikesheds. What Is A "Bikeshed"? Literally, a bikeshed is a small outdoor shelter into which one may store one's two-wheeled form of transportation. However, in &os; parlance, the word is a derogatory term that refers to any oft-recurring discussion about a particular subject; in particular, it is most often used to refer to a topic which has never reached a consensus within the &os; community, and instead remains controversial. (The genesis of this term is explained in more detail in this document). You simply must have a working knowledge of this concept before posting to any &os; mailing list. More generally, a bikeshed is a topic that will tend to generate immediate meta-discussions and flames if you have not read up on their past history. Please help us to keep the mailing lists as useful for as many people as possible by avoiding bikesheds whenever you can. Thanks. Acknowledgments &a.grog; Original author of most of the material on mailing list etiquette, taken from the article on How to get best results from the FreeBSD-questions mailing list. &a.linimon; Creation of the rough draft of this FAQ.
diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml index 1bd1b1adba..ddafc966e8 100644 --- a/en_US.ISO8859-1/articles/mh/article.sgml +++ b/en_US.ISO8859-1/articles/mh/article.sgml @@ -1,819 +1,815 @@ -%freebsd; - - -%trademarks; + +%articles.ent; ]>
An <application>MH</application> Primer Matt Midboe
matt@garply.com
v1.0, 16 January 1996 &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; This document contains an introduction to using MH on FreeBSD Introduction MH started back in 1977 at the RAND Corporation, where the initial philosophies behind MH were developed. MH is not so much a monolithic email program but a philosophy about how best to develop tools for reading email. The MH developers have done a great job adhering to the KISS principle: Keep It Simple Stupid. Rather than have one large program for reading, sending and handling email they have written specialized programs for each part of your email life. One might liken MH to the specialization that one finds in insects and nature. Each tool in MH does one thing, and does it very well. Beyond just the various tools that one uses to handle their email MH has done an excellent job keeping the configuration of each of these tools consistent and uniform. In fact, if you are not quite sure how something is supposed to work or what the arguments for some command are supposed to be, then you can generally guess and be right. Each MH command is consistent about how it handles reading the configuration files and how it takes arguments on the command line. One useful thing to remember is that you can always add a to the command to have it display the options for that command. The first thing that you need to do is to make sure that you have installed the MH package on your FreeBSD machine. If you installed from CDROM you should be able to execute the following to load MH: &prompt.root; pkg_add /cdrom/packages/mh-6.8.3.tgz You will notice that it created a /usr/local/lib/mh directory for you as well as adding several binaries to the /usr/local/bin directory. If you would prefer to compile it yourself then you can anonymous ftp it from ftp.ics.uci.edu or louie.udel.edu. This primer is not a full comprehensive explanation of how MH works. This is just intended to get you started on the road to happier, faster mail reading. You should read the manual pages for the various commands. You might also want to read the comp.mail.mh newsgroup. Also you can read the FAQ for MH. The best resource for MH is Jerry Peek's MH & nmh: Email for Users & Programmers. Reading Mail This section covers how to use inc, show, scan, next, prev, rmm, rmf, and msgchk. One of the best things about MH is the consistent interface between programs. One thing to keep in mind when using these commands is how to specify message lists. In the case of inc this does not really make any sense but with commands like show it is useful to know. A message list can consist of something like 23 20 16 which will act on messages 23, 20 and 16. This is fairly simple but you can do more useful things like 23-30 which will act on all the messages between 23 and 30. You can also specify something like cur:10 which will act on the current message and the next 9 messages. The cur, last, and first messages are special messages that refer to the current, last or first message in the folder. <command>inc</command>, <command>msgchk</command>—read in your new email or check it If you just type in inc and hit return you will be well on your way to getting started with MH. The first time you run inc it will set up your account to use all the MH defaults and ask you about creating a Mail directory under your HOME directory. If you have mail waiting to be downloaded you will see something that looks like: 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa This is the same thing you will see from a scan (see ). If you just run inc with no arguments it will look on your computer for email that is supposed to be coming to you. A lot of people like to use POP for grabbing their email. MH can do POP to grab your email. You will need to give inc a few command line arguments. &prompt.user; inc -host mail.pop.org -user username -norpop That tells inc to go to mail.pop.org to download your email, and that your username on their system is username. The option tells inc to use plain POP3 for downloading your email. MH has support for a few different dialects of POP. More than likely you will never ever need to use them though. While you can do more complex things with inc such as audit files and scan format files this will get you going. The msgchk command is used to get information on whether or not you have new email. msgchk takes the same and options that inc takes. <command>show</command>, <command>next</command> and <command>prev</command>—displaying and moving through email show is to show a letter in your current folder. Like inc, show is a fairly straightforward command. If you just type show and hit return then it displays the current message. You can also give specific message numbers to show: &prompt.user; show 32 45 56 This would display message numbers 32, 45 and 56 right after each other. Unless you change the default behavior show basically just does a more on the email message. next is used to move onto the next message and prev will go to the previous message. Both commands have an implied show command so that when you go to the next message it automatically displays it. <command>scan</command>—shows you a scan of your messages scan will display a brief listing of the messages in your current folder. This is an example of what the scan command will give you. 30+ 01/16 Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea 32 01/16 Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa Like just about everything in MH this display is very configurable. This is the typical default display. It gives you the message number, the date on the email, the sender, the subject line, and a sentence fragment from the very beginning of the email if it can fit it. The + means that message is the current message, so if you do a show it will display that message. One useful option for scan is the option. This will list your messages with the highest message number first and lowest message number last. Another useful option with scan is to have it read from a file. If you want to scan your incoming mailbox on FreeBSD without having to inc it you can do scan -file /var/mail/username. This can be used with any file that is in the mbox format. <command>rmm</command> and <command>rmf</command>—remove the current message or folder rmm is used to remove a mail message. The default is typically to not actually remove the message but to rename the file to one that is ignored by the MH commands. You will periodically need to go through and physically delete the removed messages. The rmf command is used to remove folders. This does not just rename the files but actually removes the from the hard drive so you should be careful when you use this command. A typical session of reading with MH The first thing that you will want to do is inc your new mail. So at a shell prompt just type in inc and hit return. &prompt.user; inc Incorporating new mail into inbox... 36+ 01/19 Stephen L. Lange Request...<<Please remove me as contact for pind 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In &prompt.user; This shows you the new email that has been added to your mailbox. So the next thing to do is show the email and move around. &prompt.user; show Received: by sashimi.wwa.com (Smail3.1.29.1 #2) id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) From: "Stephen L. Lange" <stvlange@wwa.com> To: matt@garply.com Subject: Request... Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Please remove me as contact for pindat.com &prompt.user; rmm &prompt.user; next Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 .6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro tocol To: hsu@clinet.fi Cc: hackers@FreeBSD.org Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet boards) In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." <199601182318.AA11772@Sysiphos> X-Mailer: exmh version 1.5omega 10/6/94 Date: Fri, 19 Jan 1996 17:56:40 +0000 From: Matt Thomas <matt@lkg.dec.com> Sender: owner-hackers@FreeBSD.org Precedence: bulk This is due to a typo in pcireg.h (to which I am probably the guilty party). The rmm removed the current message and the next command moved me on to the next message. Now if I wanted to look at ten most recent messages so I could read one of them here is what I would do: &prompt.user; scan last:10 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In &prompt.user; Then if I wanted to read message number 27 I would do a show 27 and it would be displayed. As you can probably tell from this sample session MH is pretty easy to use and looking through emails and displaying them is fairly intuitive and easy. Folders and Mail Searching Anybody who gets lots of email definitely wants to be able to prioritize, stamp, brief, de-brief, and number their emails in a variety of different ways. MH can do this better than just about anything. One thing that we have not really talked about is the concept of folders. You have undoubtedly come across the folders concept using other email programs. MH has folders too. MH can even do sub-folders of a folder. One thing you should keep in mind with MH is that when you ran inc for the first time and it asked you if it could create a Mail directory it began storing everything in that directory. If you look at that directory you will find a directory named inbox. The inbox directory houses all of your incoming mail that has not been thrown anywhere else. Whenever you create a new folder a new directory is going to be created underneath your MH Mail directory, and messages in that folder are going to be stored in that directory. When a new email message comes, it is thrown into your inbox directory with a file name that is equivalent to the message number. So even if you did not have any of the MH tools to read your email you could still use standard &unix; commands to munge around in those directories and just more your files. It is this simplicity that really gives you a lot of power with what you can do with your email. Just as you can use message lists like 23 16 42 with most MH commands there is a folder option you can specify with just about every MH command. If you do a scan +freebsd it will scan your freebsd folder, and your current folder will be changed to freebsd. If you do a show +freebsd 23 16 42, show is going to switch to your freebsd folder and display messages 23, 16 and 42. So remember that syntax. You will need to make sure you use it to make commands process different folders. Remember you default folder for mail is inbox so doing a folder +inbox should always get you back to your mail. Of course, in MH's infinite flexibility this can be changed but most places have probably left it as inbox. <command>pick</command>—search email that matches certain criteria pick is one of the more complex commands in the MH system. So you might want to read the pick1 man page for a more thorough understanding. At its simplest level you can do something like &prompt.user; pick -search pci 15 42 55 56 57 This will tell pick to look through every single line in every message in your current folder and tell you which message numbers it found the word pci in. You can then show those messages and read them if you wish or rmm them. You would have to specify something like show 15 42 55-57 to display them though. A slightly more useful thing to do is this: &prompt.user; pick -search pci -seq pick 5 hits &prompt.user; show pick This will show you the same messages you just did not have to work as hard to do it. The option is really an abbreviation of and pick is just a sequence which contains the message numbers that matched. You can use sequences with just about any MH command. So you could have done an rmm pick and all those messages would be removed instead. You sequence can be named anything. If you run pick again it will overwrite the old sequence if you use the same name. Doing a pick -search can be a bit more time consuming than just searching for message from someone, or to someone. So pick allows you to use the following predefined search criteria: search based upon who the message is to search based on who is in the Cc: list search for who sent the message search for emails with this subject find emails with a matching date search for any other component in the header. (i.e. to find all emails with a certain reply-to in the header) This allows you to do things like &prompt.user; pick -to freebsd-hackers@FreeBSD.org -seq hackers to get a list of all the email send to the FreeBSD hackers mailing list. pick also allows you to group these criteria in different ways using the following options: … … … … … … These commands allow you to do things like &prompt.user; pick -to freebsd-hackers -or -cc freebsd-hackers That will grab all the email in your inbox that was sent to freebsd-hackers or cc'd to that list. The brace options allow you to group search criteria together. This is sometimes very necessary as in the following example &prompt.user; pick -lbrace -to freebsd-hackers -and -not -cc freebsd-questions -rbrace -and -subject pci Basically this says pick (to freebsd-hackers and not cc'd on freebsd-questions) and the subject is pci. It should look through your folder and find all messages sent to the freebsd-hackers list that are not cc'd to the freebsd-questions list and contain pci in the subject line. Ordinarily you might have to worry about something called operator precedence. Remember in math how you evaluate from left to right and you do multiplication and division first and addition and subtraction second? MH has the same type of rules for pick. It is fairly complex so you might want to study the manual page. This document is just to help you get acquainted with MH. <command>folder</command>, <command>folders</command>, <command>refile</command>—three useful programs for folder maintenance There are three programs which are primarily just for manipulating your folders. The folder program is used to switch between folders, pack them, and list them. At its simplest level you can do a folder +newfolder and you will be switched into newfolder. From there on out all your MH commands like comp, repl, scan, and show will act on that newfolder folder. Sometimes when you are reading and deleting messages you will develop holes in your folders. If you do a scan you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do a folder -pack this will renumber all your messages so that there are no holes. It does not actually delete any messages though. So you may need to periodically go through and physically delete rmm'd messages. If you need statistics on your folders you can do a folders or folder -all to list all your folders, how many messages they have, what the current message is in each one and so on. This line of stats it displays for all your folders is the same one you get when you change to a folder with folder +foldername. A folders command looks like this: Folder # of messages ( range ); cur msg (other files) announce has 1 message ( 1- 1). drafts has no messages. f-hackers has 43 messages ( 1- 43). f-questions has 16 messages ( 1- 16). inbox+ has 35 messages ( 1- 38); cur= 37. lists has 8 messages ( 1- 8). netfuture has 1 message ( 1- 1). out has 31 messages ( 1- 31). personal has 6 messages ( 1- 6). todo has 58 messages ( 1- 58); cur= 1. TOTAL= 199 messages in 13 folders. The refile command is what you use to move messages between folders. When you do something like refile 23 +netfuture message number 23 is moved into the netfuture folder. You could also do something like refile 23 +netfuture/latest which would put message number 23 in a subfolder called latest under the netfuture folder. If you want to keep a message in the current folder and link it you can do a refile -link 23 +netfuture which would keep 23 in your current inbox but also list in your netfuture folder. You are probably beginning to realize some of the really powerful things you can do with MH. Sending Mail Email is a two way street for most people so you want to be able to send something back. The way MH handles sending mail can be a bit difficult to follow at first, but it allows for incredible flexibility. The first thing MH does is to copy a components file into your outgoing email. A components file is basically a skeleton email letter with stuff like the To: and Subject: headers already in it. You are then sent into your editor where you fill in the header information and then type the body of your message below the dashed lines in the message. When you leave the editor, the whatnow program is run. When you are at the What now? prompt you can tell it to send, list, edit, push, and quit. Most of these commands are self-explanatory. So the message sending process involves copying a component file, editing your email, and then telling the whatnow program what to do with your email. <command>comp</command>, <command>forw</command>, <command>reply</command>—compose, forward or reply to a message to someone The comp program has a few useful command line options. The most important one to know right now is the option. When MH is installed the default editor is usually a program called prompter which comes with MH. It is not a very exciting editor and basically just gets the job done. So when you go to compose a message to someone you might want to use comp -editor /usr/bin/vi or comp -editor /usr/local/bin/pico instead. Once you have run comp you are in your editor and you see something that looks like this: To: cc: Subject: -------- You need to put the person you are sending the mail to after the To: line. It works the same way for the other headers also, so you would need to put your subject after the Subject: line. Then you would just put the body of your message after the dashed lines. It may seem a bit simplistic since a lot of email programs have special requesters that ask you for this information but there really is no point to that. Plus this really gives you excellent flexibility. To:freebsd-rave@FreeBSD.org cc: Subject:And on the 8th day God created the FreeBSD core team -------- Wow this is an amazing operating system. Thanks! You can now save this message and exit your editor. You will see the What now? prompt and you can type in send or s and hit return. Then the FreeBSD core team will receive their just rewards. As I mentioned earlier, you can also use other commands at the What now? prompt. For example you can use quit, if you do not want to send the message. The forw command is stunningly similar. The big difference being that the message you are forwarding is automatically included in the outgoing message. When you run forw it will forward your current message. You can always tell it to forward something else by doing something like forw 23 and then message number 23 will be put in your outgoing message instead of the current message. Beyond those small differences forw functions exactly the same as comp. You go through the exact same message sending process. The repl command will reply to the current message, unless you give it a different message to reply to. repl will do its best to go ahead and fill in some of the email headers already. So you will notice that the To: header already has the address of the recipient in there. Also the Subject: line will already be filled in. You then go about the normal message composition process and you are done. One useful command line option to know here is the option. You can use all, to, cc, me after the option to have repl automatically add the various addresses to the Cc: list in the message. You have probably noticed that the original message is not included. This is because most MH setups are configured to do this from the start. <filename>components</filename>, and <filename>replcomps</filename>—components files for <command>comp</command> and <command>repl</command> The components file is usually in /usr/local/lib/mh. You can copy that file into your MH Mail directory and edit to contain what you want it to contain. It is a fairly basic file. You have various email headers at the top, a dashed line and then nothing. The comp command just copies this components file and then edits it. You can add any kind of valid RFC822 header you want. For instance you could have something like this in your components file: To: Fcc: out Subject: X-Mailer: MH 6.8.3 X-Home-Page: http://www.FreeBSD.org/ ------- MH would then copy this components file and throw you into your editor. The components file is fairly simple. If you wanted to have a signature on those messages you would just put your signature in that components file. The replcomps file is a bit more complex. The default replcomps looks like this: %(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ %<(nonnull)%(void(width))%(putaddr To: )\n%>\ %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ %<(nonnull)%(void(width))%(putaddr cc: )\n%>\ %<{fcc}Fcc: %{fcc}\n%>\ %<{subject}Subject: Re: %{subject}\n%>\ %<{date}In-reply-to: Your message of "\ %<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} %{message-id}%>\n%>\ -------- It is in the same basic format as the components file but it contains quite a few extra formatting codes. The %(lit) command makes room for the address. The %(formataddr) is a function that returns a proper email address. The next part is %< which means if and the {reply-to} means the reply-to field in the original message. So that might be translated this way: %<if {reply-to} the original message has a reply-to then give that to formataddr, %? else {from} take the from address, %? else {sender} take the sender address, %? else {return-path} take the return-path from the original message, %> endif. As you can tell MH formatting can get rather involved. You can probably decipher what most of the other functions and variables mean. All of the information on writing these format strings is in the MH-Format manual page. The really nice thing is that once you have built your customized replcomps file you will not need to touch it again. No other email program really gives you the power and flexibility that MH gives you.
diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml index 54ffc21f09..ebe8653557 100644 --- a/en_US.ISO8859-1/articles/multi-os/article.sgml +++ b/en_US.ISO8859-1/articles/multi-os/article.sgml @@ -1,755 +1,752 @@ -%authors; - - -%trademarks; + +%articles.ent; ]>
Installing and Using FreeBSD With Other Operating Systems Jay Richmond
jayrich@sysc.com
6 August 1996 &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.powerquest; &tm-attrib.general; This document discusses how to make FreeBSD coexist nicely with other popular operating systems such as Linux, &ms-dos;, &os2;, and &windows; 95. Special thanks to: Annelise Anderson andrsn@stanford.edu, Randall Hopper rhh@ct.picker.com, and &a.jkh;. Overview Most people can not fit these operating systems together comfortably without having a larger hard disk, so special information on large EIDE drives is included. Because there are so many combinations of possible operating systems and hard disk configurations, the section may be of the most use to you. It contains descriptions of specific working computer setups that use multiple operating systems. This document assumes that you have already made room on your hard disk for an additional operating system. Any time you repartition your hard drive, you run the risk of destroying the data on the original partitions. However, if your hard drive is completely occupied by DOS, you might find the FIPS utility (included on the FreeBSD CDROM in the \TOOLS directory or via ftp) useful. It lets you repartition your hard disk without destroying the data already on it. There is also a commercial program available called &partitionmagic;, which lets you size and delete partitions without consequence. Overview of Boot Managers These are just brief descriptions of some of the different boot managers you may encounter. Depending on your computer setup, you may find it useful to use more than one of them on the same system. Boot Easy This is the default boot manager used with FreeBSD. It has the ability to boot most anything, including BSD, &os2; (HPFS), &windows; 95 (FAT and FAT32), and Linux. Partitions are selected with the function keys. &os2; Boot Manager This will boot FAT, FAT32, HPFS, FFS (FreeBSD), and EXT2 (Linux). Partitions are selected using arrow keys. The &os2; Boot Manager is the only one to use its own separate partition, unlike the others which use the master boot record (MBR). Therefore, it must be installed below the 1024th cylinder to avoid booting problems. It can boot Linux using LILO when it is part of the boot sector, not the MBR. Go to Linux HOWTOs on the World Wide Web for more information on booting Linux with the &os2; boot manager. OS-BS This is an alternative to Boot Easy. It gives you more control over the booting process, with the ability to set the default partition to boot and the booting timeout. The beta version of this programs allows you to boot by selecting the OS with your arrow keys. It is included on the FreeBSD CD in the \TOOLS directory, and via ftp. LILO, or LInux LOader This is a limited boot manager. It will boot FreeBSD, though some customization work is required in the LILO configuration file. About FAT32 FAT32 is the replacement to the FAT filesystem included in Microsoft's OEM SR2 Beta release, which started replacing FAT on computers pre-loaded with &windows; 95 towards the end of 1996. It converts the normal FAT filesystem and allows you to use smaller cluster sizes for larger hard drives. FAT32 also modifies the traditional FAT boot sector and allocation table, making it incompatible with some boot managers. A Typical Installation Let's say I have two large EIDE hard drives, and I want to install FreeBSD, Linux, and &windows; 95 on them. Here is how I might do it using these hard disks: /dev/wd0 (first physical hard disk) /dev/wd1 (second hard disk) Both disks have 1416 cylinders. I boot from a &ms-dos; or &windows; 95 boot disk that contains the FDISK.EXE utility and make a small 50 MB primary partition (35-40 for &windows; 95, plus a little breathing room) on the first disk. Also create a larger partition on the second hard disk for my &windows; applications and data. I reboot and install &windows; 95 (easier said than done) on the C: partition. The next thing I do is install Linux. I am not sure about all the distributions of Linux, but Slackware includes LILO (see ). When I am partitioning out my hard disk with Linux fdisk, I would put all of Linux on the first drive (maybe 300 MB for a nice root partition and some swap space). After I install Linux, and are prompted about installing LILO, make sure that I install it on the boot sector of my root Linux partition, not in the MBR (master boot record). The remaining hard disk space can go to FreeBSD. I also make sure that my FreeBSD root slice does not go beyond the 1024th cylinder. (The 1024th cylinder is 528 MB into the disk with our hypothetical 720 MB disks). I will use the rest of the hard drive (about 270 MB) for the /usr and / slices if I wish. The rest of the second hard disk (size depends on the amount of my &windows; application/data partition that I created in step 1) can go to the /usr/src slice and swap space. When viewed with the &windows; 95 fdisk utility, my hard drives should now look something like this: --------------------------------------------------------------------- Display Partition Information Current fixed disk drive: 1 Partition Status Type Volume_Label Mbytes System Usage C: 1 A PRI DOS 50 FAT** 7% 2 A Non-DOS (Linux) 300 43% Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) Press Esc to continue --------------------------------------------------------------------- Display Partition Information Current fixed disk drive: 2 Partition Status Type Volume_Label Mbytes System Usage D: 1 A PRI DOS 420 FAT** 60% Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) Press Esc to continue --------------------------------------------------------------------- ** May say FAT16 or FAT32 if you are using the OEM SR2 update. See . Install FreeBSD. I make sure to boot with my first hard disk set at NORMAL in the BIOS. If it is not, I will have the enter my true disk geometry at boot time (to get this, boot &windows; 95 and consult Microsoft Diagnostics (MSD.EXE), or check your BIOS) with the parameter hd0=1416,16,63 where 1416 is the number of cylinders on my hard disk, 16 is the number of heads per track, and 63 is the number of sectors per track on the drive. When partitioning out the hard disk, I make sure to install Boot Easy on the first disk. I do not worry about the second disk, nothing is booting off of it. When I reboot, Boot Easy should recognize my three bootable partitions as DOS (&windows; 95), Linux, and BSD (FreeBSD). Special Considerations Most operating systems are very picky about where and how they are placed on the hard disk. &windows; 95 and DOS need to be on the first primary partition on the first hard disk. &os2; is the exception. It can be installed on the first or second disk in a primary or extended partition. If you are not sure, keep the beginning of the bootable partitions below the 1024th cylinder. If you install &windows; 95 on an existing BSD system, it will destroy the MBR, and you will have to reinstall your previous boot manager. Boot Easy can be reinstalled by using the BOOTINST.EXE utility included in the \TOOLS directory on the CDROM, and via ftp. You can also re-start the installation process and go to the partition editor. From there, mark the FreeBSD partition as bootable, select Boot Manager, and then type W to (W)rite out the information to the MBR. You can now reboot, and Boot Easy should then recognize &windows; 95 as DOS. Please keep in mind that &os2; can read FAT and HPFS partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, &windows; 95 can only read and write to FAT and FAT32 (see ) partitions. FreeBSD can read most filesystems, but currently cannot read HPFS partitions. Linux can read HPFS partitions, but can not write to them. Recent versions of the Linux kernel (2.x) can read and write to &windows; 95 VFAT partitions (VFAT is what gives &windows; 95 long file names - it is pretty much the same as FAT). Linux can read and write to most filesystems. Got that? I hope so. Examples (section needs work, please send your example to jayrich@sysc.com). FreeBSD + &windows; 95: If you installed FreeBSD after &windows; 95, you should see DOS on the Boot Easy menu. This is &windows; 95. If you installed &windows; 95 after FreeBSD, read above. As long as your hard disk does not have 1024 cylinders you should not have a problem booting. If one of your partitions goes beyond the 1024th cylinder however, and you get messages like invalid system disk under DOS (&windows; 95) and FreeBSD will not boot, try looking for a setting in your BIOS called > 1024 cylinder support or NORMAL/LBA mode. DOS may need LBA (Logical Block Addressing) in order to boot correctly. If the idea of switching BIOS settings every time you boot up does not appeal to you, you can boot FreeBSD through DOS via the FBSDBOOT.EXE utility on the CD (It should find your FreeBSD partition and boot it.) FreeBSD + &os2; + &windows; 95: Nothing new here. The &os2; boot manager can boot all of these operating systems, so that should not be a problem. FreeBSD + Linux: You can also use Boot Easy to boot both operating systems. FreeBSD + Linux + &windows; 95: (see ) Other Sources of Help There are many Linux HOW-TOs that deal with multiple operating systems on the same hard disk. The Linux+DOS+Win95+OS2 mini-HOWTO offers help on configuring the &os2; boot manager, and the Linux+FreeBSD mini-HOWTO might be interesting as well. The Linux-HOWTO is also helpful. The &windowsnt; Loader Hacking Guide provides good information on multibooting &windowsnt;, &windows; 95, and DOS with other operating systems. And Hale Landis's How It Works document pack contains some good info on all sorts of disk geometry and booting related topics. You can find it at . Finally, do not overlook FreeBSD's kernel documentation on the booting procedure, available in the kernel source distribution (it unpacks to /usr/src/sys/i386/boot/biosboot/README.386BSD. Technical Details (Contributed by Randall Hopper, rhh@ct.picker.com) This section attempts to give you enough basic information about your hard disks and the disk booting process so that you can troubleshoot most problems you might encounter when getting set up to boot several operating systems. It starts in pretty basic terms, so you may want to skim down in this section until it begins to look unfamiliar and then start reading. Disk Primer Three fundamental terms are used to describe the location of data on your hard disk: Cylinders, Heads, and Sectors. It is not particularly important to know what these terms relate to except to know that, together, they identify where data is physically on your disk. Your disk has a particular number of cylinders, number of heads, and number of sectors per cylinder-head (a cylinder-head also known now as a track). Collectively this information defines the physical disk geometry for your hard disk. There are typically 512 bytes per sector, and 63 sectors per track, with the number of cylinders and heads varying widely from disk to disk. Thus you can figure the number of bytes of data that will fit on your own disk by calculating: (# of cylinders) × (# heads) × (63 sectors/track) × (512 bytes/sect) For example, on my 1.6 Gig Western Digital AC31600 EIDE hard disk, that is: (3148 cyl) × (16 heads) × (63 sectors/track) × (512 bytes/sect) which is 1,624,670,208 bytes, or around 1.6 Gig. You can find out the physical disk geometry (number of cylinders, heads, and sectors/track counts) for your hard disks using ATAID or other programs off the net. Your hard disk probably came with this information as well. Be careful though: if you are using BIOS LBA (see ), you can not use just any program to get the physical geometry. This is because many programs (e.g. MSD.EXE or FreeBSD fdisk) do not identify the physical disk geometry; they instead report the translated geometry (virtual numbers from using LBA). Stay tuned for what that means. One other useful thing about these terms. Given 3 numbers—a cylinder number, a head number, and a sector-within-track number—you identify a specific absolute sector (a 512 byte block of data) on your disk. Cylinders and Heads are numbered up from 0, and Sectors are numbered up from 1. For those that are interested in more technical details, information on disk geometry, boot sectors, BIOSes, etc. can be found all over the net. Query Lycos, Yahoo, etc. for boot sector or master boot record. Among the useful info you will find are Hale Landis's How It Works document pack. See the section for a few pointers to this pack. Ok, enough terminology. We are talking about booting here. The Booting Process On the first sector of your disk (Cyl 0, Head 0, Sector 1) lives the Master Boot Record (MBR). It contains a map of your disk. It identifies up to 4 partitions, each of which is a contiguous chunk of that disk. FreeBSD calls partitions slices to avoid confusion with its own partitions, but we will not do that here. Each partition can contain its own operating system. Each partition entry in the MBR has a Partition ID, a Start Cylinder/Head/Sector, and an End Cylinder/Head/Sector. The Partition ID tells what type of partition it is (what OS) and the Start/End tells where it is. lists a smattering of some common Partition IDs. Partition IDs ID (hex) Description 01 Primary DOS12 (12-bit FAT) 04 Primary DOS16 (16-bit FAT) 05 Extended DOS 06 Primary big DOS (> 32MB) 0A &os2; 83 Linux (EXT2FS) A5 FreeBSD, NetBSD, 386BSD (UFS)
Note that not all partitions are bootable (e.g. Extended DOS). Some are—some are not. What makes a partition bootable is the configuration of the Partition Boot Sector that exists at the beginning of each partition. When you configure your favorite boot manager, it looks up the entries in the MBR partition tables of all your hard disks and lets you name the entries in that list. Then when you boot, the boot manager is invoked by special code in the Master Boot Sector of the first probed hard disk on your system. It looks at the MBR partition table entry corresponding to the partition choice you made, uses the Start Cylinder/Head/Sector information for that partition, loads up the Partition Boot Sector for that partition, and gives it control. That Boot Sector for the partition itself contains enough information to start loading the operating system on that partition. One thing we just brushed past that is important to know. All of your hard disks have MBRs. However, the one that is important is the one on the disk that is first probed by the BIOS. If you have only IDE hard disks, it is the first IDE disk (e.g. primary disk on first controller). Similarly for SCSI only systems. If you have both IDE and SCSI hard disks though, the IDE disk is typically probed first by the BIOS, so the first IDE disk is the first probed disk. The boot manager you will install will be hooked into the MBR on this first probed hard disk that we have just described. Booting Limitations and Warnings Now the interesting stuff that you need to watch out for. The dreaded 1024 cylinder limit and how BIOS LBA helps The first part of the booting process is all done through the BIOS, (if that is a new term to you, the BIOS is a software chip on your system motherboard which provides startup code for your computer). As such, this first part of the process is subject to the limitations of the BIOS interface. The BIOS interface used to read the hard disk during this period (INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 bits to the Head Number, and 6 bits to the Sector Number. This restricts users of this interface (i.e. boot managers hooked into your disk's MBR as well as OS loaders hooked into the Boot Sectors) to the following limits: 1024 cylinders, max 256 heads, max 64 sectors/track, max (actually 63, 0 is not available) Now big hard disks have lots of cylinders but not a lot of heads, so invariably with big hard disks the number of cylinders is greater than 1024. Given this and the BIOS interface as is, you can not boot off just anywhere on your hard disk. The boot code (the boot manager and the OS loader hooked into all bootable partitions' Boot Sectors) has to reside below cylinder 1024. In fact, if your hard disk is typical and has 16 heads, this equates to: 1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) × 512 bytes/sector which is around the often-mentioned 528MB limit. This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA gives the user of the BIOS API calls access to physical cylinders above 1024 though the BIOS interfaces by redefining a cylinder. That is, it remaps your cylinders and heads, making it appear through the BIOS as though the disk has fewer cylinders and more heads than it actually does. In other words, it takes advantage of the fact that hard disks have relatively few heads and lots of cylinders by shifting the balance between number of cylinders and number of heads so that both numbers lie below the above-mentioned limits (1024 cylinders, 256 heads). With BIOS LBA, the hard disk size limitation is virtually removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA BIOS, you can put FreeBSD or any OS anywhere you want and not hit the 1024 cylinder limit. To use my 1.6 Gig Western Digital as an example again, its physical geometry is: (3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector) However, my BIOS LBA remaps this to: (787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector) giving the same effective size disk, but with cylinder and head counts within the BIOS API's range (Incidentally, I have both Linux and FreeBSD existing on one of my hard disks above the 1024th physical cylinder, and both operating systems boot fine, thanks to BIOS LBA). Boot Managers and Disk Allocation Another gotcha to watch out when installing boot managers is allocating space for your boot manager. It is best to be aware of this issue up front to save yourself from having to reinstall one or more of your OSs. If you followed the discussion in about the Master Boot Sector (where the MBR is), Partition Boot Sectors, and the booting process, you may have been wondering just exactly where on your hard disk that nifty boot manager is going to live. Well, some boot managers are small enough to fit entirely within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with the partition table. Others need a bit more room and actually extend a few sectors past the Master Boot Sector in the Cylinder 0 Head 0 track, since that is typically free…typically. That is the catch. Some operating systems (FreeBSD included) let you start their partitions right after the Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give FreeBSD's sysinstall a disk with an empty chunk up front or the whole disk empty, that is where it will start the FreeBSD partition by default (at least it did when I fell into this trap). Then when you go to install your boot manager, if it is one that occupies a few extra sectors after the MBR, it will overwrite the front of the first partition's data. In the case of FreeBSD, this overwrites the disk label, and renders your FreeBSD partition unbootable. The easy way to avoid this problem (and leave yourself the flexibility to try different boot managers later) is just to always leave the first full track on your disk unallocated when you partition your disk. That is, leave the space from Cylinder 0, Head 0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and start your first partition at Cylinder 0, Head 1, Sector 1. For what it is worth, when you create a DOS partition at the front of your disk, DOS leaves this space open by default (this is why some boot managers assume it is free). So creating a DOS partition up at the front of your disk avoids this problem altogether. I like to do this myself, creating 1 Meg DOS partition up front, because it also avoids my primary DOS drive letters shifting later when I repartition. For reference, the following boot managers use the Master Boot Sector to store their code and data: OS-BS 1.35 Boot Easy LILO These boot managers use a few additional sectors after the Master Boot Sector: OS-BS 2.0 Beta 8 (sectors 2-5) The &os2; boot manager What if your machine will not boot? At some point when installing boot managers, you might leave the MBR in a state such that your machine will not boot. This is unlikely, but possible when re-FDISKing underneath an already-installed boot manager. If you have a bootable DOS partition on your disk, you can boot off a DOS floppy, and run: A:\> FDISK /MBR to put the original, simple DOS boot code back into the system. You can then boot DOS (and DOS only) off the hard drive. Alternatively, just re-run your boot manager installation program off a bootable floppy.
diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml index e790f21940..3264a92b85 100644 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ b/en_US.ISO8859-1/articles/new-users/article.sgml @@ -1,1067 +1,1059 @@ -%man; - -%mailing-lists; - -%freebsd; - -%trademarks; - -%urls; + +%articles.ent; ]>
For People New to Both FreeBSD and &unix; Annelise Anderson
andrsn@andrsn.stanford.edu
 August 15, 1997 &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.microsoft; &tm-attrib.netscape; &tm-attrib.opengroup; &tm-attrib.general; Congratulations on installing FreeBSD! This introduction is for people new to both FreeBSD and &unix;—so it starts with basics. It assumes you are using version 2.0.5 or later of &os; as distributed by &os;.org, your system (for now) has a single user (you)—and you are probably pretty good with DOS/&windows; or &os2;. Logging in and Getting Out Log in (when you see login:) as a user you created during installation or as root. (Your FreeBSD installation will already have an account for root; who can go anywhere and do anything, including deleting essential files, so be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the prompt (yours may be different), with &prompt.user; indicating an ordinary user and &prompt.root; indicating root. To log out (and get a new login: prompt) type &prompt.root; exit as often as necessary. Yes, press enter after commands, and remember that &unix; is case-sensitive—exit, not EXIT. To shut down the machine type &prompt.root; /sbin/shutdown -h now Or to reboot type &prompt.root; /sbin/shutdown -r now or &prompt.root; /sbin/reboot You can also reboot with CtrlAltDelete. Give it a little time to do its work. This is equivalent to /sbin/reboot in recent releases of FreeBSD and is much, much better than hitting the reset button. You do not want to have to reinstall this thing, do you? Adding A User with Root Privileges If you did not create any users when you installed the system and are thus logged in as root, you should probably create a user now with &prompt.root; adduser The first time you use adduser, it might ask for some defaults to save. You might want to make the default shell &man.csh.1; instead of &man.sh.1;, if it suggests sh as the default. Otherwise just press enter to accept each default. These defaults are saved in /etc/adduser.conf, an editable file. Suppose you create a user jack with full name Jack Benimble. Give jack a password if security (even kids around who might pound on the keyboard) is an issue. When it asks you if you want to invite jack into other groups, type wheel Login group is ``jack''. Invite jack into other groups: wheel This will make it possible to log in as jack and use the &man.su.1; command to become root. Then you will not get scolded any more for logging in as root. You can quit adduser any time by typing CtrlC, and at the end you will have a chance to approve your new user or simply type n for no. You might want to create a second new user so that when you edit jack's login files, you will have a hot spare in case something goes wrong. Once you have done this, use exit to get back to a login prompt and log in as jack. In general, it is a good idea to do as much work as possible as an ordinary user who does not have the power—and risk—of root. If you already created a user and you want the user to be able to su to root, you can log in as root and edit the file /etc/group, adding jack to the first line (the group wheel). But first you need to practice &man.vi.1;, the text editor—or use the simpler text editor, &man.ee.1;, installed on recent versions of FreeBSD. To delete a user, use the rmuser command. Looking Around Logged in as an ordinary user, look around and try out some commands that will access the sources of help and information within FreeBSD. Here are some commands and what they do: id Tells you who you are! pwd Shows you where you are—the current working directory. ls Lists the files in the current directory. ls Lists the files in the current directory with a * after executables, a / after directories, and an @ after symbolic links. ls Lists the files in long format—size, date, permissions. ls Lists hidden dot files with the others. If you are root, the dot files show up without the switch. cd Changes directories. cd .. backs up one level; note the space after cd. cd /usr/local goes there. cd ~ goes to the home directory of the person logged in—e.g., /usr/home/jack. Try cd /cdrom, and then ls, to find out if your CDROM is mounted and working. view filename Lets you look at a file (named filename) without changing it. Try view /etc/fstab. Type :q to quit. cat filename Displays filename on screen. If it is too long and you can see only the end of it, press ScrollLock and use the up-arrow to move backward; you can use ScrollLock with manual pages too. Press ScrollLock again to quit scrolling. You might want to try cat on some of the dot files in your home directory—cat .cshrc, cat .login, cat .profile. You will notice aliases in .cshrc for some of the ls commands (they are very convenient). You can create other aliases by editing .cshrc. You can make these aliases available to all users on the system by putting them in the system-wide csh configuration file, /etc/csh.cshrc. Getting Help and Information Here are some useful sources of help. Text stands for something of your choice that you type in—usually a command or filename. apropos text Everything containing string text in the whatis database. man text The manual page for text. The major source of documentation for &unix; systems. man ls will tell you all the ways to use the ls command. Press Enter to move through text, CtrlB to go back a page, CtrlF to go forward, q or CtrlC to quit. which text Tells you where in the user's path the command text is found. locate text All the paths where the string text is found. whatis text Tells you what the command text does and its manual page. Typing whatis * will tell you about all the binaries in the current directory. whereis text Finds the file text, giving its full path. You might want to try using whatis on some common useful commands like cat, more, grep, mv, find, tar, chmod, chown, date, and script. more lets you read a page at a time as it does in DOS, e.g., ls -l | more or more filename. The * works as a wildcard—e.g., ls w* will show you files beginning with w. Are some of these not working very well? Both &man.locate.1; and &man.whatis.1; depend on a database that is rebuilt weekly. If your machine is not going to be left on over the weekend (and running FreeBSD), you might want to run the commands for daily, weekly, and monthly maintenance now and then. Run them as root and, for now, give each one time to finish before you start the next one. &prompt.root; periodic daily output omitted &prompt.root; periodic weekly output omitted &prompt.root; periodic monthly output omitted If you get tired of waiting, press AltF2 to get another virtual console, and log in again. After all, it is a multi-user, multi-tasking system. Nevertheless these commands will probably flash messages on your screen while they are running; you can type clear at the prompt to clear the screen. Once they have run, you might want to look at /var/mail/root and /var/log/messages. Running such commands is part of system administration—and as a single user of a &unix; system, you are your own system administrator. Virtually everything you need to be root to do is system administration. Such responsibilities are not covered very well even in those big fat books on &unix;, which seem to devote a lot of space to pulling down menus in windows managers. You might want to get one of the two leading books on systems administration, either Evi Nemeth et.al.'s UNIX System Administration Handbook (Prentice-Hall, 1995, ISBN 0-13-15051-7)—the second edition with the red cover; or Æleen Frisch's Essential System Administration (O'Reilly & Associates, 2002, ISBN 0-596-00343-9). I used Nemeth. Editing Text To configure your system, you need to edit text files. Most of them will be in the /etc directory; and you will need to su to root to be able to change them. You can use the easy ee, but in the long run the text editor vi is worth learning. There is an excellent tutorial on vi in /usr/src/contrib/nvi/docs/tutorial, if you have the system sources installed. Before you edit a file, you should probably back it up. Suppose you want to edit /etc/rc.conf. You could just use cd /etc to get to the /etc directory and do: &prompt.root; cp rc.conf rc.conf.orig This would copy rc.conf to rc.conf.orig, and you could later copy rc.conf.orig to rc.conf to recover the original. But even better would be moving (renaming) and then copying back: &prompt.root; mv rc.conf rc.conf.orig &prompt.root; cp rc.conf.orig rc.conf because the mv command preserves the original date and owner of the file. You can now edit rc.conf. If you want the original back, you would then mv rc.conf rc.conf.myedit (assuming you want to preserve your edited version) and then &prompt.root; mv rc.conf.orig rc.conf to put things back the way they were. To edit a file, type &prompt.root; vi filename Move through the text with the arrow keys. Esc (the escape key) puts vi in command mode. Here are some commands: x delete letter the cursor is on dd delete the entire line (even if it wraps on the screen) i insert text at the cursor a insert text after the cursor Once you type i or a, you can enter text. Esc puts you back in command mode where you can type :w to write your changes to disk and continue editing :wq to write and quit :q! to quit without saving changes /text to move the cursor to text; /Enter (the enter key) to find the next instance of text. G to go to the end of the file nG to go to line n in the file, where n is a number CtrlL to redraw the screen Ctrlb and Ctrlf go back and forward a screen, as they do with more and view. Practice with vi in your home directory by creating a new file with vi filename and adding and deleting text, saving the file, and calling it up again. vi delivers some surprises because it is really quite complex, and sometimes you will inadvertently issue a command that will do something you do not expect. (Some people actually like vi—it is more powerful than DOS EDIT—find out about the :r command.) Use Esc one or more times to be sure you are in command mode and proceed from there when it gives you trouble, save often with :w, and use :q! to get out and start over (from your last :w) when you need to. Now you can cd to /etc, su to root, use vi to edit the file /etc/group, and add a user to wheel so the user has root privileges. Just add a comma and the user's login name to the end of the first line in the file, press Esc, and use :wq to write the file to disk and quit. Instantly effective. (You did not put a space after the comma, did you?) Printing Files from DOS At this point you probably do not have the printer working, so here is a way to create a file from a manual page, move it to a floppy, and then print it from DOS. Suppose you want to read carefully about changing permissions on files (pretty important). You can use man chmod to read about it. The command &prompt.user; man chmod | col -b > chmod.txt will remove formatting codes and send the manual page to the chmod.txt file instead of showing it on your screen. Now put a dos-formatted diskette in your floppy drive a, su to root, and type &prompt.root; /sbin/mount -t msdos /dev/fd0 /mnt to mount the floppy drive on /mnt. Now (you no longer need to be root, and you can type exit to get back to being user jack) you can go to the directory where you created chmod.txt and copy the file to the floppy with: &prompt.user; cp chmod.txt /mnt and use ls /mnt to get a directory listing of /mnt, which should show the file chmod.txt. You might especially want to make a file from /sbin/dmesg by typing &prompt.user; /sbin/dmesg > dmesg.txt and copying dmesg.txt to the floppy. /sbin/dmesg is the boot log record, and it is useful to understand it because it shows what FreeBSD found when it booted up. If you ask questions on the &a.questions; or on a USENET group—like FreeBSD is not finding my tape drive, what do I do?—people will want to know what dmesg has to say. You can now unmount the floppy drive (as root) to get the disk out with &prompt.root; /sbin/umount /mnt and reboot to go to DOS. Copy these files to a DOS directory, call them up with DOS EDIT, &windows; Notepad or Wordpad, or a word processor, make a minor change so the file has to be saved, and print as you normally would from DOS or Windows. Hope it works! manual pages come out best if printed with the DOS print command. (Copying files from FreeBSD to a mounted DOS partition is in some cases still a little risky.) Getting the printer printing from FreeBSD involves creating an appropriate entry in /etc/printcap and creating a matching spool directory in /var/spool/output. If your printer is on lpt0 (what DOS calls LPT1), you may only need to go to /var/spool/output and (as root) create the directory lpd by typing: mkdir lpd, if it does not already exist. Then the printer should respond if it is turned on when the system is booted, and lp or lpr should send a file to the printer. Whether or not the file actually prints depends on configuring it, which is covered in the FreeBSD handbook. Other Useful Commands df shows file space and mounted systems. ps aux shows processes running. ps ax is a narrower form. rm filename remove filename. rm -R dir removes a directory dir and all subdirectories—careful! ls -R lists files in the current directory and all subdirectories; I used a variant, ls -AFR > where.txt, to get a list of all the files in / and (separately) /usr before I found better ways to find files. passwd to change user's password (or root's password) man hier manual page on the &unix; filesystem Use find to locate filename in /usr or any of its subdirectories with &prompt.user; find /usr -name "filename" You can use * as a wildcard in "filename" (which should be in quotes). If you tell find to search in / instead of /usr it will look for the file(s) on all mounted filesystems, including the CDROM and the DOS partition. An excellent book that explains &unix; commands and utilities is Abrahams & Larson, Unix for the Impatient (2nd ed., Addison-Wesley, 1996). There is also a lot of &unix; information on the Internet. Next Steps You should now have the tools you need to get around and edit files, so you can get everything up and running. There is a great deal of information in the FreeBSD handbook (which is probably on your hard drive) and FreeBSD's web site. A wide variety of packages and ports are on the CDROM as well as the web site. The handbook tells you more about how to use them (get the package if it exists, with pkg_add /cdrom/packages/All/packagename, where packagename is the filename of the package). The CDROM has lists of the packages and ports with brief descriptions in cdrom/packages/index, cdrom/packages/index.txt, and cdrom/ports/index, with fuller descriptions in /cdrom/ports/*/*/pkg/DESCR, where the *s represent subdirectories of kinds of programs and program names respectively. If you find the handbook too sophisticated (what with lndir and all) on installing ports from the CDROM, here is what usually works: Find the port you want, say kermit. There will be a directory for it on the CDROM. Copy the subdirectory to /usr/local (a good place for software you add that should be available to all users) with: &prompt.root; cp -R /cdrom/ports/comm/kermit /usr/local This should result in a /usr/local/kermit subdirectory that has all the files that the kermit subdirectory on the CDROM has. Next, create the directory /usr/ports/distfiles if it does not already exist using mkdir. Now check /cdrom/ports/distfiles for a file with a name that indicates it is the port you want. Copy that file to /usr/ports/distfiles; in recent versions you can skip this step, as FreeBSD will do it for you. In the case of kermit, there is no distfile. Then cd to the subdirectory of /usr/local/kermit that has the file Makefile. Type &prompt.root; make all install During this process the port will FTP to get any compressed files it needs that it did not find on the CDROM or in /usr/ports/distfiles. If you do not have your network running yet and there was no file for the port in /cdrom/ports/distfiles, you will have to get the distfile using another machine and copy it to /usr/ports/distfiles from a floppy or your DOS partition. Read Makefile (with cat or more or view) to find out where to go (the master distribution site) to get the file and what its name is. Its name will be truncated when downloaded to DOS, and after you get it into /usr/ports/distfiles you will have to rename it (with the mv command) to its original name so it can be found. (Use binary file transfers!) Then go back to /usr/local/kermit, find the directory with Makefile, and type make all install. The other thing that happens when installing ports or packages is that some other program is needed. If the installation stops with a message can't find unzip or whatever, you might need to install the package or port for unzip before you continue. Once it is installed type rehash to make FreeBSD reread the files in the path so it knows what is there. (If you get a lot of path not found messages when you use whereis or which, you might want to make additions to the list of directories in the path statement in .cshrc in your home directory. The path statement in &unix; does the same kind of work it does in DOS, except the current directory is not (by default) in the path for security reasons; if the command you want is in the directory you are in, you need to type ./ before the command to make it work; no space after the slash.) You might want to get the most recent version of &netscape; from their FTP site. (&netscape; requires the X Window System.) There is now a FreeBSD version, so look around carefully. Just use gunzip filename and tar xvf filename on it, move the binary to /usr/local/bin or some other place binaries are kept, rehash, and then put the following lines in .cshrc in each user's home directory or (easier) in /etc/csh.cshrc, the system-wide csh start-up file: setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB setenv XNLSPATH /usr/X11R6/lib/X11/nls This assumes that the file XKeysymDB and the directory nls are in /usr/X11R6/lib/X11; if they are not, find them and put them there. If you originally got &netscape; as a port using the CDROM (or FTP), do not replace /usr/local/bin/netscape with the new netscape binary; this is just a shell script that sets up the environment variables for you. Instead rename the new binary to netscape.bin and replace the old binary, which is /usr/local/netscape/netscape. Your Working Environment Your shell is the most important part of your working environment. In DOS, the usual shell is command.com. The shell is what interprets the commands you type on the command line, and thus communicates with the rest of the operating system. You can also write shell scripts, which are like DOS batch files: a series of commands to be run without your intervention. Two shells come installed with FreeBSD: csh and sh. csh is good for command-line work, but scripts should be written with sh (or bash). You can find out what shell you have by typing echo $SHELL. The csh shell is okay, but tcsh does everything csh does and more. It allows you to recall commands with the arrow keys and edit them. It has tab-key completion of filenames (csh uses the Esc key), and it lets you switch to the directory you were last in with cd -. It is also much easier to alter your prompt with tcsh. It makes life a lot easier. Here are the three steps for installing a new shell: Install the shell as a port or a package, just as you would any other port or package. Use rehash and which tcsh (assuming you are installing tcsh) to make sure it got installed. As root, edit /etc/shells, adding a line in the file for the new shell, in this case /usr/local/bin/tcsh, and save the file. (Some ports may do this for you.) Use the chsh command to change your shell to tcsh permanently, or type tcsh at the prompt to change your shell without logging in again. It can be dangerous to change root's shell to something other than sh or csh on early versions of FreeBSD and many other versions of &unix;; you may not have a working shell when the system puts you into single user mode. The solution is to use su -m to become root, which will give you the tcsh as root, because the shell is part of the environment. You can make this permanent by adding it to your .tcshrc file as an alias with: alias su su -m When tcsh starts up, it will read the /etc/csh.cshrc and /etc/csh.login files, as does csh. It will also read the .login file in your home directory and the .cshrc file as well, unless you provide a .tcshrc file. This you can do by simply copying .cshrc to .tcshrc. Now that you have installed tcsh, you can adjust your prompt. You can find the details in the manual page for tcsh, but here is a line to put in your .tcshrc that will tell you how many commands you have typed, what time it is, and what directory you are in. It also produces a > if you are an ordinary user and a # if you are root, but tsch will do that in any case: set prompt = "%h %t %~ %# " This should go in the same place as the existing set prompt line if there is one, or under "if($?prompt) then" if not. Comment out the old line; you can always switch back to it if you prefer it. Do not forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. You can get a listing of other environmental variables that have been set by typing env at the prompt. The result will show you your default editor, pager, and terminal type, among possibly many others. A useful command if you log in from a remote location and can not run a program because the terminal is not capable is setenv TERM vt100. Other As root, you can unmount the CDROM with /sbin/umount /cdrom, take it out of the drive, insert another one, and mount it with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming cd0a is the device name for your CDROM drive. The most recent versions of FreeBSD let you mount the CDROM with just /sbin/mount /cdrom. Using the live filesystem—the second of FreeBSD's CDROM disks—is useful if you have got limited space. What is on the live filesystem varies from release to release. You might try playing games from the CDROM. This involves using lndir, which gets installed with the X Window System, to tell the program(s) where to find the necessary files, because they are in the /cdrom file system instead of in /usr and its subdirectories, which is where they are expected to be. Read man lndir. Comments Welcome If you use this guide I would be interested in knowing where it was unclear and what was left out that you think should be included, and if it was helpful. My thanks to Eugene W. Stark, professor of computer science at SUNY-Stony Brook, and John Fieber for helpful comments. Annelise Anderson, andrsn@andrsn.stanford.edu
diff --git a/en_US.ISO8859-1/articles/pam/article.sgml b/en_US.ISO8859-1/articles/pam/article.sgml index d29469d4ec..f5d4cb58ab 100644 --- a/en_US.ISO8859-1/articles/pam/article.sgml +++ b/en_US.ISO8859-1/articles/pam/article.sgml @@ -1,1368 +1,1362 @@ -%man; - - -%freebsd; - - -%trademarks; + +%articles.ent; ]>
Pluggable Authentication Modules $FreeBSD$ This article describes the underlying principles and mechanisms of the Pluggable Authentication Modules (PAM) library, and explains how to configure PAM, how to integrate PAM into applications, and how to write PAM modules. 2001 2002 2003 Networks Associates Technology, Inc. Dag-Erling Smørgrav Contributed by This article was written for the FreeBSD Project by ThinkSec AS 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. &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.opengroup; &tm-attrib.sun; &tm-attrib.general;
Introduction The Pluggable Authentication Modules (PAM) library is a generalized API for authentication-related services which allows a system administrator to add new authentication methods simply by installing new PAM modules, and to modify authentication policies by editing configuration files. PAM was defined and developed in 1995 by Vipin Samar and Charlie Lai of Sun Microsystems, and has not changed much since. In 1997, the Open Group published the X/Open Single Sign-on (XSSO) preliminary specification, which standardized the PAM API and added extensions for single (or rather integrated) sign-on. At the time of this writing, this specification has not yet been adopted as a standard. Although this article focuses primarily on FreeBSD 5.x, which uses OpenPAM, it should be equally applicable to FreeBSD 4.x, which uses Linux-PAM, and other operating systems such as Linux and &solaris;.
Terms and conventions
Definitions The terminology surrounding PAM is rather confused. Neither Samar and Lai's original paper nor the XSSO specification made any attempt at formally defining terms for the various actors and entities involved in PAM, and the terms that they do use (but do not define) are sometimes misleading and ambiguous. The first attempt at establishing a consistent and unambiguous terminology was a whitepaper written by Andrew G. Morgan (author of Linux-PAM) in 1999. While Morgan's choice of terminology was a huge leap forward, it is in this author's opinion by no means perfect. What follows is an attempt, heavily inspired by Morgan, to define precise and unambiguous terms for all actors and entities involved in PAM. account The set of credentials the applicant is requesting from the arbitrator. applicant The user or entity requesting authentication. arbitrator The user or entity who has the privileges necessary to verify the applicant's credentials and the authority to grant or deny the request. chain A sequence of modules that will be invoked in response to a PAM request. The chain includes information about the order in which to invoke the modules, what arguments to pass to them, and how to interpret the results. client The application responsible for initiating an authentication request on behalf of the applicant and for obtaining the necessary authentication information from him. facility One of the four basic groups of functionality provided by PAM: authentication, account management, session management and authentication token update. module A collection of one or more related functions implementing a particular authentication facility, gathered into a single (normally dynamically loadable) binary file and identified by a single name. policy The complete set of configuration statements describing how to handle PAM requests for a particular service. A policy normally consists of four chains, one for each facility, though some services do not use all four facilities. server The application acting on behalf of the arbitrator to converse with the client, retrieve authentication information, verify the applicant's credentials and grant or deny requests. service A class of servers providing similar or related functionality and requiring similar authentication. PAM policies are defined on a per-service basis, so all servers that claim the same service name will be subject to the same policy. session The context within which service is rendered to the applicant by the server. One of PAM's four facilities, session management, is concerned exclusively with setting up and tearing down this context. token A chunk of information associated with the account, such as a password or passphrase, which the applicant must provide to prove his identity. transaction A sequence of requests from the same applicant to the same instance of the same server, beginning with authentication and session set-up and ending with session tear-down.
Usage examples This section aims to illustrate the meanings of some of the terms defined above by way of a handful of simple examples.
Client and server are one This simple example shows alice &man.su.1;'ing to root. &prompt.user; whoami alice &prompt.user; ls -l `which su` -r-sr-xr-x 1 root wheel 10744 Dec 6 19:06 /usr/bin/su &prompt.user; su - Password: xi3kiune &prompt.root; whoami root The applicant is alice. The account is root. The &man.su.1; process is both client and server. The authentication token is xi3kiune. The arbitrator is root, which is why &man.su.1; is setuid root.
Client and server are separate The example below shows eve try to initiate an &man.ssh.1; connection to login.example.com, ask to log in as bob, and succeed. Bob should have chosen a better password! &prompt.user; whoami eve &prompt.user; ssh bob@login.example.com bob@login.example.com's password: god Last login: Thu Oct 11 09:52:57 2001 from 192.168.0.1 Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 The Regents of the University of California. All rights reserved. FreeBSD 4.4-STABLE (LOGIN) #4: Tue Nov 27 18:10:34 PST 2001 Welcome to FreeBSD! &prompt.user; The applicant is eve. The client is Eve's &man.ssh.1; process. The server is the &man.sshd.8; process on login.example.com The account is bob. The authentication token is god. Although this is not shown in this example, the arbitrator is root.
Sample policy The following is FreeBSD's default policy for sshd: sshd auth required pam_nologin.so no_warn sshd auth required pam_unix.so no_warn try_first_pass sshd account required pam_login_access.so sshd account required pam_unix.so sshd session required pam_lastlog.so no_fail sshd password required pam_permit.so This policy applies to the sshd service (which is not necessarily restricted to the &man.sshd.8; server.) auth, account, session and password are facilities. pam_nologin.so, pam_unix.so, pam_login_access.so, pam_lastlog.so and pam_permit.so are modules. It is clear from this example that pam_unix.so provides at least two facilities (authentication and account management.)
PAM Essentials
Facilities and primitives The PAM API offers six different authentication primitives grouped in four facilities, which are described below. auth Authentication. This facility concerns itself with authenticating the applicant and establishing the account credentials. It provides two primitives: &man.pam.authenticate.3; authenticates the applicant, usually by requesting an authentication token and comparing it with a value stored in a database or obtained from an authentication server. &man.pam.setcred.3; establishes account credentials such as user ID, group membership and resource limits. account Account management. This facility handles non-authentication-related issues of account availability, such as access restrictions based on the time of day or the server's work load. It provides a single primitive: &man.pam.acct.mgmt.3; verifies that the requested account is available. session Session management. This facility handles tasks associated with session set-up and tear-down, such as login accounting. It provides two primitives: &man.pam.open.session.3; performs tasks associated with session set-up: add an entry in the utmp and wtmp databases, start an SSH agent, etc. &man.pam.close.session.3; performs tasks associated with session tear-down: add an entry in the utmp and wtmp databases, stop the SSH agent, etc. password Password management. This facility is used to change the authentication token associated with an account, either because it has expired or because the user wishes to change it. It provides a single primitive: &man.pam.chauthtok.3; changes the authentication token, optionally verifying that it is sufficiently hard to guess, has not been used previously, etc.
Modules Modules are a very central concept in PAM; after all, they are the M in PAM. A PAM module is a self-contained piece of program code that implements the primitives in one or more facilities for one particular mechanism; possible mechanisms for the authentication facility, for instance, include the &unix; password database, NIS, LDAP and Radius.
Module Naming FreeBSD implements each mechanism in a single module, named pam_mechanism.so (for instance, pam_unix.so for the &unix; mechanism.) Other implementations sometimes have separate modules for separate facilities, and include the facility name as well as the mechanism name in the module name. To name one example, &solaris; has a pam_dial_auth.so.1 module which is commonly used to authenticate dialup users.
Module Versioning FreeBSD's original PAM implementation, based on Linux-PAM, did not use version numbers for PAM modules. This would commonly cause problems with legacy applications, which might be linked against older versions of the system libraries, as there was no way to load a matching version of the required modules. OpenPAM, on the other hand, looks for modules that have the same version number as the PAM library (currently 2), and only falls back to an unversioned module if no versioned module could be loaded. Thus legacy modules can be provided for legacy applications, while allowing new (or newly built) applications to take advantage of the most recent modules. Although &solaris; PAM modules commonly have a version number, they're not truly versioned, because the number is a part of the module name and must be included in the configuration.
Chains and policies When a server initiates a PAM transaction, the PAM library tries to load a policy for the service specified in the &man.pam.start.3; call. The policy specifies how authentication requests should be processed, and is defined in a configuration file. This is the other central concept in PAM: the possibility for the admin to tune the system security policy (in the wider sense of the word) simply by editing a text file. A policy consists of four chains, one for each of the four PAM facilities. Each chain is a sequence of configuration statements, each specifying a module to invoke, some (optional) parameters to pass to the module, and a control flag that describes how to interpret the return code from the module. Understanding the control flags is essential to understanding PAM configuration files. There are four different control flags: binding If the module succeeds and no earlier module in the chain has failed, the chain is immediately terminated and the request is granted. If the module fails, the rest of the chain is executed, but the request is ultimately denied. This control flag was introduced by Sun in &solaris; 9 (&sunos; 5.9), and is also supported by OpenPAM. required If the module succeeds, the rest of the chain is executed, and the request is granted unless some other module fails. If the module fails, the rest of the chain is also executed, but the request is ultimately denied. requisite If the module succeeds, the rest of the chain is executed, and the request is granted unless some other module fails. If the module fails, the chain is immediately terminated and the request is denied. sufficient If the module succeeds and no earlier module in the chain has failed, the chain is immediately terminated and the request is granted. If the module fails, the module is ignored and the rest of the chain is executed. As the semantics of this flag may be somewhat confusing, especially when it is used for the last module in a chain, it is recommended that the binding control flag be used instead if the implementation supports it. optional The module is executed, but its result is ignored. If all modules in a chain are marked optional, all requests will always be granted. When a server invokes one of the six PAM primitives, PAM retrieves the chain for the facility the primitive belongs to, and invokes each of the modules listed in the chain, in the order they are listed, until it reaches the end, or determines that no further processing is necessary (either because a binding or sufficient module succeeded, or because a requisite module failed.) The request is granted if and only if at least one module was invoked, and all non-optional modules succeeded. Note that it is possible, though not very common, to have the same module listed several times in the same chain. For instance, a module that looks up user names and passwords in a directory server could be invoked multiple times with different parameters specifying different directory servers to contact. PAM treat different occurrences of the same module in the same chain as different, unrelated modules.
Transactions The lifecycle of a typical PAM transaction is described below. Note that if any of these steps fails, the server should report a suitable error message to the client and abort the transaction. If necessary, the server obtains arbitrator credentials through a mechanism independent of PAM—most commonly by virtue of having been started by root, or of being setuid root. The server calls &man.pam.start.3; to initialize the PAM library and specify its service name and the target account, and register a suitable conversation function. The server obtains various information relating to the transaction (such as the applicant's user name and the name of the host the client runs on) and submits it to PAM using &man.pam.set.item.3;. The server calls &man.pam.authenticate.3; to authenticate the applicant. The server calls &man.pam.acct.mgmt.3; to verify that the requested account is available and valid. If the password is correct but has expired, &man.pam.acct.mgmt.3; will return PAM_NEW_AUTHTOK_REQD instead of PAM_SUCCESS. If the previous step returned PAM_NEW_AUTHTOK_REQD, the server now calls &man.pam.chauthtok.3; to force the client to change the authentication token for the requested account. Now that the applicant has been properly authenticated, the server calls &man.pam.setcred.3; to establish the credentials of the requested account. It is able to do this because it acts on behalf of the arbitrator, and holds the arbitrator's credentials. Once the correct credentials have been established, the server calls &man.pam.open.session.3; to set up the session. The server now performs whatever service the client requested—for instance, provide the applicant with a shell. Once the server is done serving the client, it calls &man.pam.close.session.3; to tear down the session. Finally, the server calls &man.pam.end.3; to notify the PAM library that it is done and that it can release whatever resources it has allocated in the course of the transaction.
PAM Configuration
PAM policy files
The <filename>/etc/pam.conf</filename> file The traditional PAM policy file is /etc/pam.conf. This file contains all the PAM policies for your system. Each line of the file describes one step in a chain, as shown below: login auth required pam_nologin.so no_warn The fields are, in order: service name, facility name, control flag, module name, and module arguments. Any additional fields are interpreted as additional module arguments. A separate chain is constructed for each service / facility pair, so while the order in which lines for the same service and facility appear is significant, the order in which the individual services and facilities are listed is not. The examples in the original PAM paper grouped configuration lines by facility, and the &solaris; stock pam.conf still does that, but FreeBSD's stock configuration groups configuration lines by service. Either way is fine; either way makes equal sense.
The <filename>/etc/pam.d</filename> directory OpenPAM and Linux-PAM support an alternate configuration mechanism, which is the preferred mechanism in FreeBSD. In this scheme, each policy is contained in a separate file bearing the name of the service it applies to. These files are stored in /etc/pam.d/. These per-service policy files have only four fields instead of pam.conf's five: the service name field is omitted. Thus, instead of the sample pam.conf line from the previous section, one would have the following line in /etc/pam.d/login: auth required pam_nologin.so no_warn As a consequence of this simplified syntax, it is possible to use the same policy for multiple services by linking each service name to a same policy file. For instance, to use the same policy for the su and sudo services, one could do as follows: &prompt.root; cd /etc/pam.d &prompt.root; ln -s su sudo This works because the service name is determined from the file name rather than specified in the policy file, so the same file can be used for multiple differently-named services. Since each service's policy is stored in a separate file, the pam.d mechanism also makes it very easy to install additional policies for third-party software packages.
The policy search order As we have seen above, PAM policies can be found in a number of places. What happens if policies for the same service exist in multiple places? It is essential to understand that PAM's configuration system is centered on chains.
Breakdown of a configuration line As explained in the section, each line in /etc/pam.conf consists of four or more fields: the service name, the facility name, the control flag, the module name, and zero or more module arguments. The service name is generally (though not always) the name of the application the statement applies to. If you are unsure, refer to the individual application's documentation to determine what service name it uses. Note that if you use /etc/pam.d/ instead of /etc/pam.conf, the service name is specified by the name of the policy file, and omitted from the actual configuration lines, which then start with the facility name. The facility is one of the four facility keywords described in the section. Likewise, the control flag is one of the four keywords described in the section, describing how to interpret the return code from the module. Linux-PAM supports an alternate syntax that lets you specify the action to associate with each possible return code, but this should be avoided as it is non-standard and closely tied in with the way Linux-PAM dispatches service calls (which differs greatly from the way &solaris; and OpenPAM do it.) Unsurprisingly, OpenPAM does not support this syntax.
Policies To configure PAM correctly, it is essential to understand how policies are interpreted. When an application calls &man.pam.start.3;, the PAM library loads the policy for the specified service and constructs four module chains (one for each facility.) If one or more of these chains are empty, the corresponding chains from the policy for the other service are substituted. When the application later calls one of the six PAM primitives, the PAM library retrieves the chain for the corresponding facility and calls the appropriate service function in each module listed in the chain, in the order in which they were listed in the configuration. After each call to a service function, the module type and the error code returned by the service function are used to determine what happens next. With a few exceptions, which we discuss below, the following table applies: PAM chain execution summary PAM_SUCCESS PAM_IGNORE other binding if (!fail) break; - fail = true; required - - fail = true; requisite - - fail = true; break; sufficient if (!fail) break; - - optional - - -
If fail is true at the end of a chain, or when a break is reached, the dispatcher returns the error code returned by the first module that failed. Otherwise, it returns PAM_SUCCESS. The first exception of note is that the error code PAM_NEW_AUTHTOK_REQD is treated like a success, except that if no module failed, and at least one module returned PAM_NEW_AUTHTOK_REQD, the dispatcher will return PAM_NEW_AUTHTOK_REQD. The second exception is that &man.pam.setcred.3; treats binding and sufficient modules as if they were required. The third and final exception is that &man.pam.chauthtok.3; runs the entire chain twice (once for preliminary checks and once to actually set the password), and in the preliminary phase it treats binding and sufficient modules as if they were required.
FreeBSD PAM Modules
&man.pam.deny.8; The &man.pam.deny.8; module is one of the simplest modules available; it responds to any request with PAM_AUTH_ERR. It is useful for quickly disabling a service (add it to the top of every chain), or for terminating chains of sufficient modules.
&man.pam.echo.8; The &man.pam.echo.8; module simply passes its arguments to the conversation function as a PAM_TEXT_INFO message. It is mostly useful for debugging, but can also serve to display messages such as Unauthorized access will be prosecuted before starting the authentication procedure.
&man.pam.exec.8; The &man.pam.exec.8; module takes its first argument to be the name of a program to execute, and the remaining arguments are passed to that program as command-line arguments. One possible application is to use it to run a program at login time which mounts the user's home directory.
&man.pam.ftpusers.8; The &man.pam.ftpusers.8; module
&man.pam.group.8; The &man.pam.group.8; module accepts or rejects applicants on the basis of their membership in a particular file group (normally wheel for &man.su.1;). It is primarily intended for maintaining the traditional behaviour of BSD &man.su.1;, but has many other uses, such as excluding certain groups of users from a particular service.
&man.pam.guest.8; The &man.pam.guest.8; module allows guest logins using fixed login names. Various requirements can be placed on the password, but the default behaviour is to allow any password as long as the login name is that of a guest account. The &man.pam.guest.8; module can easily be used to implement anonymous FTP logins.
&man.pam.krb5.8; The &man.pam.krb5.8; module
&man.pam.ksu.8; The &man.pam.ksu.8; module
&man.pam.lastlog.8; The &man.pam.lastlog.8; module
&man.pam.login.access.8; The &man.pam.login.access.8; module provides an implementation of the account management primitive which enforces the login restrictions specified in the &man.login.access.5; table.
&man.pam.nologin.8; The &man.pam.nologin.8; module refuses non-root logins when /var/run/nologin exists. This file is normally created by &man.shutdown.8; when less than five minutes remain until the scheduled shutdown time.
&man.pam.opie.8; The &man.pam.opie.8; module implements the &man.opie.4; authentication method. The &man.opie.4; system is a challenge-response mechanism where the response to each challenge is a direct function of the challenge and a passphrase, so the response can be easily computed just in time by anyone possessing the passphrase, eliminating the need for password lists. Moreover, since &man.opie.4; never reuses a challenge that has been correctly answered, it is not vulnerable to replay attacks.
&man.pam.opieaccess.8; The &man.pam.opieaccess.8; module is a companion module to &man.pam.opie.8;. Its purpose is to enforce the restrictions codified in &man.opieaccess.5;, which regulate the conditions under which a user who would normally authenticate herself using &man.opie.4; is allowed to use alternate methods. This is most often used to prohibit the use of password authentication from untrusted hosts. In order to be effective, the &man.pam.opieaccess.8; module must be listed as requisite immediately after a sufficient entry for &man.pam.opie.8;, and before any other modules, in the auth chain.
&man.pam.passwdqc.8; The &man.pam.passwdqc.8; module
&man.pam.permit.8; The &man.pam.permit.8; module is one of the simplest modules available; it responds to any request with PAM_SUCCESS. It is useful as a placeholder for services where one or more chains would otherwise be empty.
&man.pam.radius.8; The &man.pam.radius.8; module
&man.pam.rhosts.8; The &man.pam.rhosts.8; module
&man.pam.rootok.8; The &man.pam.rootok.8; module reports success if and only if the real user id of the process calling it (which is assumed to be run by the applicant) is 0. This is useful for non-networked services such as &man.su.1; or &man.passwd.1;, to which the root should have automatic access.
&man.pam.securetty.8; The &man.pam.securetty.8; module
&man.pam.self.8; The &man.pam.self.8; module reports success if and only if the names of the applicant matches that of the target account. It is most useful for non-networked services such as &man.su.1;, where the identity of the applicant can be easily verified.
&man.pam.ssh.8; The &man.pam.ssh.8; module provides both authentication and session services. The authentication service allows users who have passphrase-protected SSH secret keys in their ~/.ssh directory to authenticate themselves by typing their passphrase. The session service starts &man.ssh-agent.1; and preloads it with the keys that were decrypted in the authentication phase. This feature is particularly useful for local logins, whether in X (using &man.xdm.1; or another PAM-aware X login manager) or at the console.
&man.pam.tacplus.8; The &man.pam.tacplus.8; module
&man.pam.unix.8; The &man.pam.unix.8; module implements traditional &unix; password authentication, using &man.getpwnam.3; to obtain the target account's password and compare it with the one provided by the applicant. It also provides account management services (enforcing account and password expiration times) and password-changing services. This is probably the single most useful module, as the great majority of admins will want to maintain historical behaviour for at least some services.
PAM Application Programming This section has not yet been written.
PAM Module Programming This section has not yet been written.
Sample PAM Application The following is a minimal implementation of &man.su.1; using PAM. Note that it uses the OpenPAM-specific &man.openpam.ttyconv.3; conversation function, which is prototyped in security/openpam.h. If you wish build this application on a system with a different PAM library, you will have to provide your own conversation function. A robust conversation function is surprisingly difficult to implement; the one presented in the appendix is a good starting point, but should not be used in real-world applications. Sample PAM Module The following is a minimal implementation of &man.pam.unix.8;, offering only authentication services. It should build and run with most PAM implementations, but takes advantage of OpenPAM extensions if available: note the use of &man.pam.get.authtok.3;, which enormously simplifies prompting the user for a password. Sample PAM Conversation Function The conversation function presented below is a greatly simplified version of OpenPAM's &man.openpam.ttyconv.3;. It is fully functional, and should give the reader a good idea of how a conversation function should behave, but it is far too simple for real-world use. Even if you're not using OpenPAM, feel free to download the source code and adapt &man.openpam.ttyconv.3; to your uses; we believe it to be as robust as a tty-oriented conversation function can reasonably get. Further Reading This is a list of documents relevant to PAM and related issues. It is by no means complete. Papers <ulink url="http://www.sun.com/software/solaris/pam/pam.external.pdf"> Making Login Services Independent of Authentication Technologies</ulink> Samar Vipin Lai Charlie Sun Microsystems <ulink url="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open Single Sign-on Preliminary Specification</ulink> The Open Group 1-85912-144-6 June 1997 <ulink url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt"> Pluggable Authentication Modules</ulink> Morgan Andrew G. October 6, 1999 User Manuals <ulink url="http://www.sun.com/software/solaris/pam/pam.admin.pdf">PAM Administration</ulink> Sun Microsystems Related Web pages <ulink url="http://openpam.sourceforge.net/">OpenPAM homepage</ulink> Smørgrav Dag-Erling ThinkSec AS <ulink url="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM homepage</ulink> Morgan Andrew G. <ulink url="http://wwws.sun.com/software/solaris/pam/">Solaris PAM homepage</ulink> Sun Microsystems
diff --git a/en_US.ISO8859-1/articles/portbuild/article.sgml b/en_US.ISO8859-1/articles/portbuild/article.sgml index de28ca9deb..b5fcd98093 100644 --- a/en_US.ISO8859-1/articles/portbuild/article.sgml +++ b/en_US.ISO8859-1/articles/portbuild/article.sgml @@ -1,757 +1,747 @@ -%man; - -%freebsd; - -%authors; - -%teams; - -%mailing-lists; - -%trademarks; + +%articles.ent; ]>
Package Building Procedures The &os; Ports Management Team $FreeBSD$ 2003 2004 The &os; Ports Management Team &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.sparc; &tm-attrib.general; Introduction and Conventions In order to provide pre-compiled binaries of third-party applications for &os;, the ports collection is regularly built on one of the Package Building Clusters. Currently, there are two such clusters: pointyhat.FreeBSD.org and dosirak.kr.FreeBSD.org. Most of the package building magic occurs under the /var/portbuild directory. Unless otherwise specified, all paths will be relative to this location. ${arch} will be used to specify one of the package architectures (&i386;, alpha, &sparc64;, ia64, and amd64), and ${branch} will be used to specify the build branch (4, 5, 4-exp). Build Client Management The &i386;, alpha, amd64, and two &sparc64; clients currently netboot from pointyhat; the other sparc64 client and ia64 clients are self-hosted. In all cases they set themselves up at boot-time to prepare to build packages. In the latest round of portbuild updates, disconnected cluster node support has been added. A disconnected node is one that does not mount the cluster master via NFS. It could be a remote node, for example. The cluster master rsync's the interesting data (ports, src, and doc trees, bindist tarballs, scripts, etc.) to disconnected nodes during the node-setup phase. Then, the disconnected portbuild directory is nullfs-mounted for chroot builds. The ports-${arch} user can &man.ssh.1; as root onto each of the ${arch} nodes. The scripts/allgohans script can be used to run a command on all of the ${arch} clients. The scripts/checkmachines script is used to monitor the load on all the nodes of the build cluster, and schedule which nodes build which ports. This script is not very robust, and has a tendency to die. It is best to start up this script on the build master (either pointyhat or dosirak) after boot time using a &man.while.1; loop. Chroot Build Environment Setup Package builds are performed in a chroot populated by the portbuild script using the ${arch}/${branch}/tarballs/bindist.tar file. This tarball is created by the mkbindist script which reads the ${arch}/${branch}/mkbindist.conf file to decide how to create the tarball. The script should be run as root with the following command: /var/portbuild&prompt.root; scripts/mkbindist ${arch} ${branch} If ftp=1 in mkbindist.conf then a pre-built release will be downloaded via FTP from the location specified by ftp://${ftpserver}/${ftpurl}/${rel}. If ftp=0 and buildworld=1 then mkbindist will call makeworld to build a new world [XXX This is currently broken]. If both ftp=0 and buildworld=0 then mkbindist will use the pre-existing contents of ${worlddir} to create bindist.tar. In practice this means that you must have already installed a world in ${worlddir}, which is typically installed with the makeworld script: /var/portbuild&prompt.root; scripts/makeworld ${arch} ${branch} [-nocvs] This command builds a world from the ${arch}/${branch}/src tree and installs it into ${worlddir}. The tree will be updated first unless -nocvs is specified. The bindist.tar file is extracted onto each client at client boot time, and at the start of each pass of the dopackages script. Starting the Build The scripts/dopackages* scripts are used to perform the builds. Most useful are: dopackages.5 - Perform a 5.X build dopackages.4 - Perform a 4.X build dopackages.4-exp - Perform a 4.X build with experimental patches (4-exp branch) These are wrappers around dopackages, and are all symlinked to dopackages.wrapper. New branch wrapper scripts can be created by symlinking dopackages.${branch} to dopackages.wrapper. These scripts take a number of arguments. For example: dopackages.5 ${arch} [-options] [-options] may be zero or more of the following: -nofinish - Do not perform post-processing once the build is complete. Useful if you expect that the build will need to be restarted once it finishes. This option should always be used for normal build operations. -finish - Perform post-processing only. -restart - Restart an interrupted (or non-finished) build from the beginning. Ports that failed on the previous build will be rebuilt. -continue - Restart an interrupted (or non-finished) build. Will not rebuild ports that failed on the previous build. -incremental - Compare the interesting fields of the new INDEX with the previous one, remove packages and log files for the old ports that have changed, and rebuild the rest. This cuts down on build times substantially since unchanged ports do not get rebuilt everytime. [XXX This is a work-in-progress, and does not yet work as advertised.] -cdrom - This package build is intended to end up on a CD-ROM, so NO_CDROM packages and distfiles should be deleted in post-processing. -nobuild - Perform all the preprocessing steps, but do not actually do the package build. -noindex - Do not rebuild INDEX during preprocessing. -noduds - Do not rebuild the duds file (ports that are never built, e.g. those marked IGNORE, NO_PACKAGE, etc.) during preprocessing. -trybroken - Try to build BROKEN ports (off by default because the &i386; cluster is fast enough now that when doing incremental builds, more time was spent rebuilding things that were going to fail anyway. Conversely, the other clusters are slow enough that it would be a waste of time to try and build BROKEN ports. -nocvs - Do not cvs update the src tree during preprocessing. -noportscvs - Do not cvs update the ports tree during preprocessing. -nodoccvs - Do not cvs update the doc tree during preprocessing. -norestr - Do not attempt to build RESTRICTED ports. -plistcheck - Make it fatal for ports to leave behind files after deinstallation. -distfiles - Collect distfiles that pass make checksum for later uploading to ftp-master. Use this sparingly because it takes up a lot of disk space. You should remove the distfiles once they have been transfered to ftp-master. -fetch-original - Fetch the distfile from the original MASTER_SITES rather than ftp-master. Make sure the ${arch} build is run as the ports-${arch} user or it will complain loudly. The actual package build itself occurs in two identical phases. The reason for this is that sometimes transient problems (e.g. NFS failures, FTP sites being unreachable, etc.) may halt the build. Doing things in two phases is a workaround for these types of problems. Be careful that ports/Makefile does not specify any empty subdirectories. This is especially important if you are doing a 4-exp build. If the build process encounters an empty subdirectory, both package build phases will stop short, and an error similar to the following will be written to ${arch}/${branch}/make.[0|1]: don't know how to make dns-all(continuing) To correct this problem, simply comment out or remove the SUBDIR entries that point to empty subdirectories. After doing this, you can restart the build by running the proper dopackages command with the -restart option. Anatomy of a Build A full build without any -no options performs the following operations in the specified order: A CVS checkout of the current ports tree [*] A CVS checkout of the running branch's doc tree [*] A CVS checkout of the running branch's src tree [*] Checks which ports do not have a SUBDIR entry in their respective category's Makefile [*] Creates the duds file, which is a list of ports not to build [*] [+] Generates a fresh INDEX file [*] [+] Sets up the nodes that will be used in the build [*] [+] Builds a list of restricted ports [*] [+] Builds packages (phase 1) [++] Performs another node setup [+] Builds packages (phase 2) [++] [*] Status of these steps can be found in ${arch}/${branch}/build.log as well as on stderr of the tty running the dopackages command. [+] If any of these steps fail, the build will stop cold in its tracks. [++] Status of these steps can be found in ${arch}/${branch}/make.[0|1], where make.0 is the log file used by phase 1 of the package build and make.1 is the log file used by phase 2. Individual ports will write their build logs to ${arch}/${branch}/logs and their error logs to ${arch}/${branch}/errors. Interrupting a Build Sending a HUP signal to the dopackages* shell processes or to any make process invoked by those scripts is usually sufficient to interrupt the build. The package builds dispatched by make to the client machines will clean themselves up after a few minutes (check with ps x until they all go away). The following command usually does the trick: &prompt.user; killall -HUP sh ssh make Remove the ${arch}/lock file before trying to restart the build. Monitoring the Build The scripts/stats ${branch} command counts the number of packages currently built. Running cat /var/portbuild/*/loads/* shows the client loads and number of concurrent builds in progress. Running tail -f ${arch}/${branch}/build.log shows the overall build progress. If a build is failing, and it is not immediately obvious from the port build log as to why, you can preserve the WRKDIR for further analysis. To do this, touch a file called .keep in the port's directory. The next time the cluster tries to build this port, it will tar, compress, and copy the WRKDIR to ${arch}/${branch}/wrkdirs. Keep an eye on &man.df.1; output. If the /var/portbuild file system becomes full then Bad Things happen. Release Builds When building packages for a release, it may be necessary to manually update the ports and src trees to the release tag and use -nocvs and -noportscvs. To build package sets intended for use on a CD-ROM, use the -cdrom option to dopackages. Assuming disk space is available on the cluster, use -distfiles to collect distfiles. You must run the initial build with -distfiles to collect all the fetched distfiles. After the initial build completes, restart the build with -restart -distfiles -fetch-original to collect updated distfiles as well. Then, once the build is post-processed, take an inventory of the list of files fetched: &prompt.user; cd ${arch}/${branch} &prompt.user; find distfiles > distfiles-${release} This inventory file typically lives in i386/${branch} on the cluster master. This is useful to aid in periodically cleaning out the distfiles from ftp-master. When space gets tight, distfiles from recent releases can be kept while others can be thrown away. Once the distfiles have been uploaded (see below), the final release package set must be created. Just to be on the safe side, run the ${arch}/${branch}/cdrom.sh script by hand to make sure all the CD-ROM restricted packages and distfiles have been pruned. Then, copy the ${arch}/${branch}/packages directory to ${arch}/${branch}/packages-${release}. Once the packages are safely moved off, contact the &a.re; and inform them of the release package location. Remember to coordinate with the &a.re; about the timing and status of the release builds. Uploading Packages Once a build has completed, packages and/or distfiles can be transferred to ftp-master for propagation to the FTP mirror network. If the build was run with -nofinish, then make sure to follow up with dopackages -finish to post-process the packages (removes RESTRICTED and NO_CDROM packages where appropriate, prunes packages not listed in INDEX, removes from INDEX references to packages not built, and generates a CHECKSUM.MD5 summary); and distfiles (moves them from the temporary distfiles/.pbtmp directory into distfiles/ and removes RESTRICTED and NO_CDROM distfiles). It is usually a good idea to run the restricted.sh and/or cdrom.sh scripts by hand after dopackages finishes just to be safe. Run the restricted.sh script before uploading to ftp-master, then run cdrom.sh before preparing the final package set for a release. Packages can be copied to the staging area on ftp-master with something like the following: &prompt.root; cd /var/portbuild/${arch}/${branch} &prompt.root; tar cfv - packages/ | ssh portmgr@ftp-master tar xfC - w/ports/${arch}/tmp/${branch} Then log into ftp-master, verify that the package set was transferred successfully, remove the package set that the new package set is to replace (in ~/w/ports/${arch}), and move the new set into place. Some of the directories on ftp-master are, in fact, symlinks. Be sure you move the new packages directory over the real destination directory, and not one of the symlinks that points to it. Distfiles can be transferred via rsync: &prompt.root; cd /var/portbuild/${arch}/${branch} &prompt.root; rsync -r -v -l -p -c -n distfiles/ portmgr@ftp-master:w/ports/distfiles/ | tee log ALWAYS use -n first with rsync and check the output to make sure it is sane. If it looks good, re-run the rsync without the -n option. Experimental Patches Builds Experimental patches builds are run from time to time to new features or bugfixes to the ports infrastructure (i.e. bsd.port.mk), or to test large sweeping upgrades. The current experimental patches branch is 4-exp on the &i386; architecture. In general, an experimental patches build is run the same way as any other build. However, before running the dopackages script, you must apply the required patches to the ports tree. It is always a good idea to save original copies of all changed files, as well as a list of what you are changing. You can then look back on this list when doing the final commit. In order to have a good control case with which to compare failures, you should first do a package build of the branch on which the experimental patches branch is based for the &i386; architecture (currently this is 4). Then, when preparing for the experimental patches build, checkout a ports tree and a src tree with the same date as was used for the control build. This will ensure an apples-to-apples comparison later. One build cluster can do the control build while the other does the experimental patches build. This can be a great time-saver. Once the build finishes, compare the control build failures to those of the experimental patches build. Use the following commands to facilitate this (this assumes the 4 branch is the control branch, and the 4-exp branch is the experimental patches branch): &prompt.user; cd /var/portbuild/i386/4-exp/errors &prompt.user; find . -name \*.log\* | sort > /tmp/4-exp-errs &prompt.user; cd /var/portbuild/i386/4/errors &prompt.user; find . -name \*.log\* | sort > /tmp/4-errs If it has been a long time since one of the builds finished, the logs may have been automatically compressed with bzip2. In that case, you must use sort | sed 's,\.bz2,,g' instead. &prompt.user; comm -3 /tmp/4-errs /tmp/4-exp-errs | less This last command will produce a two-column report. The first column is ports that failed on the control build but not in the experimental patches build; the second column is vice versa. Reasons that the port might be in the first column include: Port was fixed since the control build was run, or was upgraded to a newer version that is also broken (thus the newer version should appear in the second column) Port is fixed by the patches in the experimental patches build Port did not build under the experimental patches build due to a dependency failure Reasons for a port appearing in the second column include: Port was broken by the experimental patches [1] Port was upgraded since the control build and has become broken [2] Port was broken due to a transient error (e.g. FTP site down, package client error, etc.) Both columns should be investigated and the reason for the errors understood before committing the experimental patches set. To differentiate between [1] and [2] above, you can do a rebuild of the affected packages under the control branch: &prompt.user; cd /var/portbuild/i386/4/ports Be sure to cvs update this tree to the same date as the experimental patches tree. The following command will set up the control branch for the partial build: &prompt.user; /var/portbuild/scripts/dopackages.4 -noportscvs -nobuild -nocvs -nofinish The builds must be performed from the packages/All directory. This directory should initially be empty except for the Makefile symlink. If this symlink does not exist, it must be created: &prompt.user; cd /var/portbuild/i386/4/packages/All &prompt.user; ln -sf ../../Makefile . &prompt.user; make -k -j<#> <list of packages to build> <#> is the concurrency of the build to attempt. It is usually the sum of the weights listed in /var/portbuild/i386/mlist unless you have a reason to run a heavier or lighter build. The list of packages to build should be a list of package names (including versions) as they appear in INDEX. The PKGSUFFIX (i.e. .tgz or .tbz) is optional. This will build only those packages listed as well as all of their dependencies. You can check the progress of this partial build the same way you would a regular build. Once all the errors have been resolved, you can commit the package set. After committing, it is customary to send a HEADS UP email to ports@FreeBSD.org and copy ports-developers@FreeBSD.org informing people of the changes. A summary of all changes should also be committed to /usr/ports/CHANGES.
diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml index 60f2565edb..4e5b78a033 100644 --- a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml +++ b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml @@ -1,538 +1,530 @@ -%man; - -%mailing-lists; - -%freebsd; - -%trademarks; - -%urls; + +%articles.ent; ]>
Problem Report Handling Guidelines $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs). Whilst developed for the FreeBSD PR Database Maintenance Team freebsd-bugbusters@FreeBSD.org, these guidelines should be followed by anyone working with FreeBSD PRs. Dag-Erling Smørgrav Hiten Pandya
Introduction GNATS is a defect management (bug reporting) system used by the FreeBSD Project. As accurate tracking of outstanding software defects is important to FreeBSD's quality, the correct use of GNATS is essential to the forward progress of the Project. Access to GNATS is available to FreeBSD developers, as well as to the wider community. In order to maintain consistency within the database and provide a consistent user experience, guidelines have been established covering common aspects of bug management such as presenting followup, handling close requests, and so forth.
Problem Report Life-cycle The Reporter submits a PR with &man.send-pr.1; and receives a confirmation message. Joe Random Committer takes interest in the PR and assigns it to himself, or Jane Random BugBuster decides that Joe is best suited to handle it and assigns it to him. Joe has a brief exchange with the originator (making sure it all goes into the audit trail) and determines the cause of the problem. He then makes sure the cause is documented in the audit trail, and sets the PRs state to analyzed. Joe pulls an all-nighter and whips up a patch that he thinks fixes the problem, and submits it in a follow-up, asking the originator to test it. He then sets the PRs state to feedback. A couple of iterations later, both Joe and the originator are satisfied with the patch, and Joe commits it to -CURRENT (or directly to -STABLE if the problem does not exist in -CURRENT), making sure to reference the Problem Report in his commit log (and credit the originator if he submitted all or part of the patch) and, if appropriate, start an MFC countdown. If the patch does not need MFCing, Joe then closes the PR. If the patch needs MFCing, Joe leaves the Problem Report in patched state until the patch has been MFCed, then closes it. Many PRs are submitted with very little information about the problem, and some are either very complex to solve, or just scratch the surface of a larger problem; in these cases, it is very important to obtain all the necessary information needed to solve the problem. If the problem contained within cannot be solved, or has occurred again, it is necessary to re-open the PR. The email address used on the PR might not be able to receive mail. In this case, followup to the PR as usual and ask the originator (in the followup) to provide a working email address. This is normally the case when &man.send-pr.1; is used from a system with the mail system disabled or not installed.
Problem Report State It is important to update the state of a PR when certain actions are taken. The state should accurately reflect the current state of work on the PR. A small example on when to change PR state When a PR has been worked on and the developer(s) responsible feel comfortable about the fix, they will submit a followup to the PR and change its state to feedback. At this point, the originator should evaluate the fix in their context and respond indicating whether the defect has indeed been remedied. A Problem Report may be in one of the following states: open Initial state; the problem has been pointed out and it needs reviewing. analyzed The problem has been reviewed and a solution is being sought. feedback Further work requires additional information from the originator or the community; possibly information regarding the proposed solution. patched A patch has been committed, but something (MFC, or maybe confirmation from originator) is still pending. suspended The problem is not being worked on, due to lack of information or resources. This is a prime candidate for somebody who is looking for a project to take on. If the problem cannot be solved at all, it will be closed, rather than suspended. The documentation project uses suspended for wish-list items that entail a significant amount of work which no one currently has time for. closed A problem report is closed when any changes have been integrated, documented, and tested, or when fixing the problem is abandoned. The patched state is directly related to feedback, so you may go directly to closed state if the originator cannot test the patch, and it works in your own testing.
Types of Problem Reports While handling problem reports, either as a developer who has direct access to the GNATS database or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of PRs. PRs already assigned to someone. Duplicates of existing PRs. Stale PRs Misfiled PRs The following sections describe what each different type of PRs is used for, when a PR belongs to one of these types, and what treatment each different type receives.
Assigned PRs If a PR has the responsible field set to the username of a FreeBSD developer, it means that the PR has been handed over to that particular person for further work. Assigned PRs should not be touched by anyone but the assignee. If you have comments, submit a followup. If for some reason you think the PR should change state or be reassigned, send a message to the assignee. If the assignee does not respond within two weeks, unassign the PR and do as you please.
Duplicate PRs If you find more than one PR that describe the same issue, choose the one that contains the largest amount of useful information and close the others, stating clearly the number of the superseding PR. If several PRs contain non-overlapping useful information, submit all the missing information to one in a followup, including references to the others; then close the other PRs (which are now completely superseded).
Stale PRs A PR is considered stale if it has not been modified in more than six months. Apply the following procedure to deal with stale PRs: If the PR contains sufficient detail, try to reproduce the problem in -CURRENT and -STABLE. If you succeed, submit a followup detailing your findings and try to find someone to assign it to. Set the state to analyzed if appropriate. If the PR describes an issue which you know is the result of a usage error (incorrect configuration or otherwise), submit a followup explaining what the originator did wrong, then close the PR with the reason User error or Configuration error. If the PR describes an error which you know has been corrected in both -CURRENT and -STABLE, close it with a message stating when it was fixed in each branch. If the PR describes an error which you know has been corrected in -CURRENT, but not in -STABLE, try to find out when the person who corrected it is planning to MFC it, or try to find someone else (maybe yourself?) to do it. Set the state to feedback and assign it to whomever will do the MFC. In other cases, ask the originator to confirm if the problem still exists in newer versions. If the originator does not reply within a month, close the PR with the notation Feedback timeout.
Misfiled PRs GNATS is picky about the format of a submitted bug report. This is why a lot of PRs end up being misfiled if the submitter forgets to fill in a field or puts the wrong sort of data in some of the PR fields. This section aims to provide most of the necessary details for FreeBSD developers that can help them to close or refile these PRs. When GNATS cannot deduce what to do with a problem report that reaches the database, it sets the responsible of the PR to gnats-admin and files it under the pending category. This is now a misfiled PR and will not appear in bug report listings, unless someone explicitly asks for a list of all the misfiled PRs. If you have access to the FreeBSD cluster machines, you can use query-pr to view a listing of PRs that have been misfiled: &prompt.user; query-pr -x -q -r gnats-admin 52458 gnats-ad open serious medium Re: declaration clash f 52510 gnats-ad open serious medium Re: lots of sockets in 52557 gnats-ad open serious medium 52570 gnats-ad open serious medium Jigdo maintainer update Commonly PRs like the ones shown above are misfiled for one of the following reasons: A followup to an existing PR, sent through email, has the wrong format on its Subject: header. When completing the &man.send-pr.1; template, the submitter forgot to set the category or class of the PR to a proper value. It is not a real PR, but some random message sent to bug-followup@FreeBSD.org or freebsd-gnats-submit@FreeBSD.org.
Followups misfiled as new PRs The first category of misfiled PRs, the one with the wrong subject header, is actually the one that requires the greatest amount of work from developers. These are not real PRs, describing separate problem reports. When a reply is received for an existing PR at one of the addresses that GNATS listens to for incoming messages, the subject of the reply should always be of the form: Subject: Re: category/number: old synopsis text Most mailers will add the Re:  part when you reply to the original mail message of a PR. The category/number:  part is a GNATS-specific convention that you have to manually insert to the subject of your followup reports. Any FreeBSD developer, who has direct access to the GNATS database, can periodically check for PRs of this sort and move interesting bits of the misfiled PR into the audit trail of the original PR (by posting a proper followup to a bug report to the address bug-followup@FreeBSD.org). Then the misfiled PR can be closed with a message similar to: Your problem report was misfiled. Please use the format "Subject: category/number: original text" when following up to older, existing PRs. I've added the relevant bits from the body of this PR to kern/12345 Searching with query-pr for the original PR, of which a misfiled followup is a reply, is as easy as running: &prompt.user; query-pr -q -y "some text" After you locate the original PR and the misfiled followups, use the option of query-pr to save the full text of all the relevant PRs in a &unix; mailbox file, i.e.: &prompt.user; query-pr -F 52458 52474 > mbox Now you can use any mail user agent to view all the PRs you saved in mbox. Copy the text of all the misfiled PRs in a followup to the original PR and make sure you include the proper Subject: header. Then close the misfiled PRs. When you close the misfiled PRs remember that the submitter receives a mail notification that his PR changed state to closed. Make sure you provide enough details in the log about the reason of this state change. Typically something like the following is ok: Followup to ports/45364 misfiled as a new PR. This was misfiled because the subject didn't have the format: Re: ports/45364: ... This way the submitter of the misfiled PR will know what to avoid the next time a followup to an existing PR is sent.
PRs misfiled because of missing fields The second type of misfiled PRs is usually the result of a submitter forgetting to fill all the necessary fields when writing the original PR. Missing or bogus category or class fields can result in a misfiled report. Developers can use &man.edit-pr.1; to change the category or class of these misfiled PRs to a more appropriate value and save the PR. Another common cause of misfiled PRs because of formatting issues is quoting, changes or removal of the send-pr template, either by the user who edits the template or by mailers which do strange things to plain text messages. This doesn't happen a lot of the time, but it can be fixed with edit-pr too; it does require a bit of work from the developer who refiles the PR, but it is relatively easy to do most of the time.
Misfiled PRs that are not really problem reports Sometimes a user wants to submit a report for a problem and sends a simple email message to GNATS. The GNATS scripts will recognize bug reports that are formatted using the &man.send-pr.1; template. They cannot parse any sort of email though. This is why submissions of bug reports that are sent to freebsd-gnats-submit@FreeBSD.org have to follow the template of send-pr, but email reports can be sent to &a.bugs;. Developers that come across PRs that look like they should have been posted to &a.bugs.name; or some other list should close the PR, informing the submitter in their state-change log why this is not really a PR and where the message should be posted. The email addresses that GNATS listens to for incoming PRs have been published as part of the FreeBSD documentation, have been announced and listed on the web-site. This means that spammers found them. Every day several messages with advertisements would reach GNATS which promptly files them all under the pending category until someone looks at them. Closing one of these with &man.edit-pr.1; is very annoying though, because GNATS replies to the submitter and the sender's address of spam mail is never valid these days. Bounces will come back for each PR that is closed. Currently, with the installation of some antispam filters that check all submissions to the GNATS database, the amount of spam that reaches the pending state is very small. All developers who have access to the FreeBSD.org cluster machines are encouraged to check for misfiled PRs and immediately close those that are spam mail. Whenever you close one of these PRs it is also a good idea to set its category to junk. Junk PRs are not backed up, so filing spam mail under this category makes it obvious that we do not care to keep it around or waste disk space for it.
Further Reading This is a list of resources relevant to the proper writing and processing of problem reports. It is by no means complete. How to Write FreeBSD Problem Reports—guidelines for PR originators.
diff --git a/en_US.ISO8859-1/articles/problem-reports/article.sgml b/en_US.ISO8859-1/articles/problem-reports/article.sgml index d52827bc7d..f65c18cdea 100644 --- a/en_US.ISO8859-1/articles/problem-reports/article.sgml +++ b/en_US.ISO8859-1/articles/problem-reports/article.sgml @@ -1,887 +1,879 @@ -%man; - -%mailing-lists; - -%trademarks; - -%freebsd; - -%urls; + +%articles.ent; ]>
Writing &os; Problem Reports $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.ibm; &tm-attrib.intel; &tm-attrib.sparc; &tm-attrib.sun; &tm-attrib.general; This article describes how to best formulate and submit a problem report to the &os; Project. Dag-Erling Smørgrav Contributed by problem reports
Introduction One of the most frustrating experiences one can have as a software user is to submit a problem report only to have it summarily closed with a terse and unhelpful explanation like not a bug or bogus PR. Similarly, one of the most frustrating experiences as a software developer is to be flooded with problem reports that are not really problem reports but requests for support, or that contain little or no information about what the problem is and how to reproduce it. This document attempts to describe how to write good problem reports. What, you ask, is a good problem report? Well, to go straight to the bottom line, a good problem report is one that can be analyzed and dealt with swiftly, to the mutual satisfaction of both user and developer. Although the primary focus of this article is on &os; problem reports, most of it should apply quite well to other software projects. Note that this article is organized thematically, not chronologically, so you should read through the entire document before submitting a problem report, rather than treat it as a step-by-step tutorial.
When to submit a problem report There are many types of problems, and not all of them should engender a problem report. Of course, nobody is perfect, and there will be times when you are convinced you have found a bug in a program when in fact you have misunderstood the syntax for a command or made a typographical error in a configuration file (though that in itself may sometimes be indicative of poor documentation or poor error handling in the application). There are still many cases where submitting a problem report is clearly not the right course of action, and will only serve to frustrate you and the developers. Conversely, there are cases where it might be appropriate to submit a problem report about something else than a bug—an enhancement or a feature request, for instance. So how do you determine what is a bug and what is not? As a simple rule of thumb your problem is not a bug if it can be expressed as a question (usually of the form How do I do X? or Where can I find Y?). It is not always quite so black and white, but the question rule covers a large majority of cases. If you are looking for an answer, consider posing your question to the &a.questions;. Some cases where it may be appropriate to submit a problem report about something that is not a bug are: Requests for feature enhancements. It is generally a good idea to air these on the mailing lists before submitting a problem report. Notification of updates to externally maintained software (mainly ports, but also externally maintained base system components such as BIND or various GNU utilities). Another thing is that if the system on which you experienced the bug is not fairly up-to-date, you should seriously consider upgrading and trying to reproduce the problem on an up-to-date system before submitting a problem report. There are few things that will annoy a developer more than receiving a problem report about a bug she has already fixed. Finally, a bug that can not be reproduced can rarely be fixed. If the bug only occurred once and you can not reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong. That does not mean it did not happen, but it does mean that the chances of your problem report ever leading to a bug fix are very slim. To make matters worse, often these kinds of bugs are actually caused by failing hard drives or overheating processors — you should always try to rule out these causes, whenever possible, before submitting a PR.
Preparations A good rule to follow is to always do a background search before submitting a problem report. Maybe your problem has already been reported; maybe it is being discussed on the mailing lists, or recently was; it may even already be fixed in a newer version than what you are running. You should therefore check all the obvious places before submitting your problem report. For &os;, this means: The &os; Frequently Asked Questions (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning hardware compatibility, user applications, and kernel configuration. The mailing lists—if you are not subscribed, use the searchable archives on the &os; web site. If your problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something you have overlooked. Optionally, the entire web—use your favorite search engine to locate any references to your problem. You may even get hits from archived mailing lists or newsgroups you did not know of or had not thought to search through. Next, the searchable &os; PR database (GNATS). Unless your problem is recent or obscure, there is a fair chance it has already been reported. Most importantly, you should attempt to see if existing documentation in the source base addresses your problem. For the base &os; code, you should carefully study the contents of the /usr/src/UPDATING file on your system or its latest version at . (This is vital information if you are upgrading from one version to another—especially if you are upgrading to the &os.current; branch). However, if the problem is in something that was installed as a part of the &os; Ports Collection, you should refer to /usr/ports/UPDATING (for individual ports) or /usr/ports/CHANGES (for changes that affect the entire Ports Collection). and are also available via CVSweb. Next, you need to make sure your problem report goes to the right people. The first catch here is that if the problem is a bug in third-party software (a port or a package you have installed), you should report the bug to the original author, not to the &os; Project. There are two exceptions to this rule: the first is if the bug does not occur on other platforms, in which case the problem may lie in how the software was ported to &os;; the second is if the original author has already fixed the bug and released a patch or a new version of his software, and the &os; port has not been updated yet. The second catch is that &os;'s bug tracking system sorts problem reports according to the category the originator selected. Therefore, if you select the wrong category when you submit your problem report, there is a good chance that it will go unnoticed for a while, until someone re-categorizes it.
Writing the problem report Now that you have decided that your issue merits a problem report, and that it is a &os; problem, it is time to write the actual problem report. Before we get into the mechanics of the program used to generate and submit PRs, here are some tips and tricks to help make sure that your PR will be most effective.
Tips and tricks for writing a good problem report Do not leave the Synopsis line empty. The PRs go both onto a mailing list that goes all over the world (where the Synopsis is used for the Subject: line), but also into a database. Anyone who comes along later and browses the database by synopsis, and finds a PR with a blank subject line, tends just to skip over it. Remember that PRs stay in this database until they are closed by someone; an anonymous one will usually just disappear in the noise. Avoid using a weak Synopsis line. You should not assume that anyone reading your PR has any context for your submission, so the more you provide, the better. For instance, what part of the system does the problem apply to? Do you only see the problem while installing, or while running? To illustrate, instead of Synopsis: portupgrade is broken, see how much more informative this seems: Synopsis: port sysutils/portupgrade coredumps on -current. (In the case of ports, it is especially helpful to have both the category and portname in the Synopsis line.) If you have a patch, say so. A PR with a patch included is much more likely to be looked at than one without. If you are including one, put the string [patch] at the beginning of the Synopsis. (Although it is not mandatory to use that exact string, by convention, that is the one that is used.) If you are a maintainer, say so. If you are maintaining a part of the source code (for instance, a port), you might consider adding the string [maintainer update] at the beginning of your synopsis line, and you definitely should set the Class of your PR to maintainer-update. This way any committer that handles your PR will not have to check. Be specific. The more information you supply about what problem you are having, the better your chance of getting a response. Include the version of &os; you are running (there is a place to put that, see below) and on which architecture. You should include whether you are running from a release (e.g. from a CDROM or download), or from a system maintained by &man.cvsup.1; (and, if so, how recently you updated). If you are tracking the &os.current; branch, that is the very first thing someone will ask, because fixes (especially for high-profile problems) tend to get committed very quickly, and &os.current; users are expected to keep up. Include which global options you have specified in your make.conf. Note: specifying -O2 and above to &man.gcc.1; is known to be buggy in many situations. While the &os; developers will accept patches, they are generally unwilling to investigate such issues due to simple lack of time and volunteers, and may instead respond that this just is not supported. If this is a kernel problem, then be prepared to supply the following information. (You do not have to include these by default, which only tends to fill up the database, but you should include excerpts that you think might be relevant): your kernel configuration (including which hardware devices you have installed) whether or not you have debugging options enabled (such as WITNESS), and if so, whether the problem persists when you change the sense of that option a backtrace, if one was generated the fact that you have read src/UPDATING and that your problem is not listed there (someone is guaranteed to ask) whether or not you can run any other kernel as a fallback (this is to rule out hardware-related issues such as failing disks and overheating CPUs, which can masquerade as kernel problems) If this is a ports problem, then be prepared to supply the following information. (You do not have to include these by default, which only tends to fill up the database, but you should include excerpts that you think might be relevant): which ports you have installed any environment variables that override the defaults in bsd.port.mk, such as PORTSDIR the fact that you have read ports/UPDATING and that your problem is not listed there (someone is guaranteed to ask) Avoid vague requests for features. PRs of the form someone should really implement something that does so-and-so are less likely to get results than very specific requests. Remember, the source is available to everyone, so if you want a feature, the best way to ensure it being included is to get to work! Also consider the fact that many things like this would make a better topic for discussion on freebsd-questions than an entry in the PR database, as discussed above. Make sure no one else has already submitted a similar PR. Although this has already been mentioned above, it bears repeating here. It only take a minute or two to use the web-based search engine at . (Of course, everyone is guilty of forgetting to do this now and then.) Avoid controversial requests. If your PR addresses an area that has been controversial in the past, you should probably be prepared to not only offer patches, but also justification for why the patches are The Right Thing To Do. As noted above, a careful search of the mailing lists using the archives at is always good preparation. Be polite. Almost anyone who would potentially work on your PR is a volunteer. No one likes to be told that they have to do something when they are already doing it for some motivation other than monetary gain. This is a good thing to keep in mind at all times on Open Source projects.
Before you begin Before running the &man.send-pr.1; program, make sure your VISUAL (or EDITOR if VISUAL is not set) environment variable is set to something sensible. You should also make sure that mail delivery works fine. &man.send-pr.1; uses mail messages for the submission and tracking of problem reports. If you cannot post mail messages from the machine you're running &man.send-pr.1; on, your problem report will not reach the GNATS database. For details on the setup of mail on &os;, see the Electronic Mail chapter of the &os; Handbook at .
Attaching patches or files The &man.send-pr.1; program has provisions for attaching files to a problem report. You can attach as many files as you want provided that each has a unique base name (i.e. the name of the file proper, without the path). Just use the command-line option to specify the names of the files you wish to attach: &prompt.user; send-pr -a /var/run/dmesg -a /tmp/errors Do not worry about binary files, they will be automatically encoded so as not to upset your mail agent. If you attach a patch, make sure you use the or option to &man.diff.1; to create a context or unified diff (unified is preferred), and make sure to specify the exact CVS revision numbers of the files you modified so the developers who read your report will be able to apply them easily. For problems with the kernel or the base utilities, a patch against &os.current; (the HEAD CVS branch) is preferred since all new code should be applied and tested there first. After appropriate or substantial testing has been done, the code will be merged/migrated to the &os.stable; branch. If you attach a patch inline, instead of as an attachment, note that the most common problem by far is the tendency of some email programs to render tabs as spaces, which will completely ruin anything intended to be part of a Makefile. Also note that while including small patches in a PR is generally all right—particularly when they fix the problem described in the PR—large patches and especially new code which may require substantial review before committing should be placed on a web or ftp server, and the URL should be included in the PR instead of the patch. Patches in email tend to get mangled, especially when GNATS is involved, and the larger the patch, the harder it will be for interested parties to unmangle it. Also, posting a patch on the web allows you to modify it without having to resubmit the entire patch in a followup to the original PR. You should also take note that unless you explicitly specify otherwise in your PR or in the patch itself, any patches you submit will be assumed to be licensed under the same terms as the original file you modified.
Filling out the template When you run &man.send-pr.1;, you are presented with a template. The template consists of a list of fields, some of which are pre-filled, and some of which have comments explaining their purpose or listing acceptable values. Do not worry about the comments; they will be removed automatically if you do not modify them or remove them yourself. At the top of the template, below the SEND-PR: lines, are the email headers. You do not normally need to modify these, unless you are sending the problem report from a machine or account that can send but not receive mail, in which case you will want to set the From: and Reply-To: to your real email address. You may also want to send yourself (or someone else) a carbon copy of the problem report by adding one or more email addresses to the Cc: header. Next comes a series of single-line fields: Submitter-Id: Do not change this. The default value of current-users is correct, even if you run &os.stable;. Originator: This is normally prefilled with the gecos field of the currently logged-in user. Please specify your real name, optionally followed by your email address in angle brackets. Organization: Whatever you feel like. This field is not used for anything significant. Confidential: This is prefilled to no. Changing it makes no sense as there is no such thing as a confidential &os; problem report—the PR database is distributed worldwide by CVSup. Synopsis: Fill this out with a short and accurate description of the problem. The synopsis is used as the subject of the problem report email, and is used in problem report listings and summaries; problem reports with obscure synopses tend to get ignored. As noted above, if your problem report includes a patch, please have the synopsis start with [patch]; if you are a maintainer, you may consider adding [maintainer update] and set the Class of your PR to maintainer-update. Severity: One of non-critical, serious or critical. Do not overreact; refrain from labeling your problem critical unless it really is (e.g. root exploit, easily reproducible panic) or serious unless it is something that will affect many users (problems with particular device drivers or system utilities). &os; developers will not neccesarily work on your problem faster if you inflate its importance since there are so many other people who have done exactly that — in fact, some developers pay little attention to this field, and the next, because of this. Priority: One of low, medium or high. high should be reserved for problems that will affect practically every user of &os; and medium for something that will affect many users. Category: Choose one of the following (taken from /usr/gnats/gnats-adm/categories): advocacy: problems relating to &os;'s public image. Rarely used. alpha: problems specific to the Alpha platform. amd64: problems specific to the AMD64 platform. bin: problems with userland programs in the base system. conf: problems with configuration files, default values etc. docs: problems with manual pages or on-line documentation. gnu: problems with GNU software such as &man.gcc.1; or &man.grep.1;. i386: problems specific to the &i386; platform. ia64: problems specific to the ia64 platform. java: problems related to &java;. kern: problems with the kernel or (non-platform-specific) device drivers. misc: anything that does not fit in any of the other categories. (Note that it is easy for things to get lost in this category). ports: problems relating to the ports tree. powerpc: problems specific to the &powerpc; platform. sparc64: problems specific to the &sparc64; platform. standards: Standards conformance issues. threads: problems related to the &os; threads implementation (especially on &os.current;). www: Changes or enhancements to the &os; website. Class: Choose one of the following: sw-bug: software bugs. doc-bug: errors in documentation. change-request: requests for additional features or changes in existing features. update: updates to ports or other contributed software. maintainer-update: updates to ports for which you are the maintainer. Release: The version of &os; that you are running. This is filled out automatically by &man.send-pr.1; and need only be changed if you are sending a problem report from a different system than the one that exhibits the problem. Finally, there is a series of multi-line fields: Environment: This should describe, as accurately as possible, the environment in which the problem has been observed. This includes the operating system version, the version of the specific program or file that contains the problem, and any other relevant items such as system configuration, other installed software that influences the problem, etc.—quite simply everything a developer needs to know to reconstruct the environment in which the problem occurs. Description: A complete and accurate description of the problem you are experiencing. Try to avoid speculating about the causes of the problem unless you are certain that you are on the right track, as it may mislead a developer into making incorrect assumptions about the problem. How-To-Repeat: A summary of the actions you need to take to reproduce the problem. Fix: Preferably a patch, or at least a workaround (which not only helps other people with the same problem work around it, but may also help a developer understand the cause for the problem), but if you do not have any firm ideas for either, it is better to leave this field blank than to speculate.
Sending off the problem report Once you are done filling out the template, have saved it, and exit your editor, &man.send-pr.1; will prompt you with s)end, e)dit or a)bort?. You can then hit s to go ahead and submit the problem report, e to restart the editor and make further modifications, or a to abort. If you choose the latter, your problem report will remain on disk (&man.send-pr.1; will tell you the filename before it terminates), so you can edit it at your leisure, or maybe transfer it to a system with better net connectivity, before sending it with the to &man.send-pr.1;: &prompt.user; send-pr -f ~/my-problem-report This will read the specified file, validate the contents, strip comments and send it off.
Follow-up Once your problem report has been filed, you will receive a confirmation by email which will include the tracking number that was assigned to your problem report and a URL you can use to check its status. With a little luck, someone will take an interest in your problem and try to address it, or, as the case may be, explain why it is not a problem. You will be automatically notified of any change of status, and you will receive copies of any comments or patches someone may attach to your problem report's audit trail. If someone requests additional information from you, or you remember or discover something you did not mention in the initial report, please use one of two methods to submit your followup: The easiest way is to use the followup link on the individual PR's web page, which you can reach from the PR search page. Clicking on this link will bring up an an email window with the correct To: and Subject: lines filled in (if your browser is configured to do this). Alternatively, you can just mail it to bug-followup@FreeBSD.org, making sure that the tracking number is included in the subject so the bug tracking system will know what problem report to attach it to. If you do not include the tracking number, GNATS will become confused and create an entirely new PR which it then assigns to the GNATS administrator, and then your followup will become lost until someone comes in to clean up the mess, which could be days or weeks afterwards. Wrong way: Subject: that PR I sent Right way: Subject: Re: ports/12345: compilation problem with foo/bar If the problem report remains open after the problem has gone away, just send a follow-up (in the manner prescribed above) saying that the problem report can be closed, and, if possible, explaining how or when the problem was fixed.
Further Reading This is a list of resources relevant to the proper writing and processing of problem reports. It is by no means complete. How to Report Bugs Effectively—an excellent essay by Simon G. Tatham on composing useful (non-&os;-specific) problem reports. Problem Report Handling Guidelines—valuable insight into how problem reports are handled by the &os; developers.
diff --git a/en_US.ISO8859-1/articles/pxe/article.sgml b/en_US.ISO8859-1/articles/pxe/article.sgml index 2db25484a1..efc50a8ecc 100644 --- a/en_US.ISO8859-1/articles/pxe/article.sgml +++ b/en_US.ISO8859-1/articles/pxe/article.sgml @@ -1,294 +1,285 @@ -%man - - -%authors; - - -%misc; - - -%trademarks; + +%articles.ent; ]>
FreeBSD Jumpstart Guide Alfred Perlstein
alfred@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.general; This article details the method used to allow machines to install FreeBSD using the &intel; PXE method of booting a machine over a network. Introduction This procedure will make the Server both insecure and dangerous, it is best to just keep the Server on its own hub and not in any way accessible by any machines other than the Clients. Terminology: Server The machine offering netboot and install options. Client The machine that will have FreeBSD installed on it. Requires: Clients supporting the &intel; PXE netboot option, an Ethernet connection. Please let me know if you come across anything you have problems with or suggestions for additional documentation. If you would like someone to train/implement a specific netinstall system for you, please send email so that we can discuss terms. I would also like to thank &a.ps; and &a.jhb; for doing most of the programming work on pxeboot, the interface to the &intel; PXE (netboot) system. Server Configuration Install DHCP: Install net/isc-dhcp3-server you can use this config file dhcpd.conf, stick it in /usr/local/etc/. Enable tftp: Make a directory /usr/tftpboot Add this line to your /etc/inetd.conf: tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /usr/tftpboot Enable NFS: Add this to /etc/rc.conf: nfs_server_enable="YES" Add this to /etc/exports: /usr -alldirs -ro Reboot to enable the new services or start them manually. Bootstrap Setup Download bootfiles: Download the kern.flp and mfsroot.flp floppy images. Set up tftp/pxe-boot directory: Put pxeboot in the boot directory: &prompt.root; rm -rf /usr/obj/* &prompt.root; cd /usr/src/sys/boot &prompt.root; make &prompt.root; cp /usr/src/sys/boot/i386/pxeldr/pxeboot /usr/tftpboot Using the vndevice mount the kern.flp file and copy its contents to /usr/tftpboot: &prompt.root; vnconfig vn0 kern.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp -R /mnt /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file Compile a custom kernel for the clients (particularly to avoid the device config screen at boot) and stick it in /usr/tftpboot. Make a special loader.rc to and install it in /usr/tftpboot/boot/loader.rc so that it does not prompt for the second disk, here is mine. Extract the installer and helper utilities from the mfsroot disk and uncompress them, put them in /usr/tftpboot as well: &prompt.root; vnconfig vn0 mfsroot.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp /mnt/mfsroot.gz /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file &prompt.root; cd /usr/tftpboot # get into the pxeboot directory &prompt.root; gunzip mfsroot.gz # uncompress the mfsroot Make your sysinstall script install.cfg, you can use mine as a template, but you must edit it. Copy the sysinstall script into the extracted and uncompressed mfsroot image: &prompt.root; cd /usr/tftpboot &prompt.root; vnconfig vn0 mfsroot &prompt.root; mount /dev/vn0 /mnt &prompt.root; cp install.cfg /mnt &prompt.root; umount /mnt &prompt.root; vnconfig -u vn0 Install Setup Put the install files in an NFS accessible location on the Server. Make a directory corresponding the 'nfs' directive in the install.cfg file and mirror the FreeBSD install files there, you will want it to look somewhat like this: ABOUT.TXT TROUBLE.TXT compat20 floppies ports ERRATA.TXT UPGRADE.TXT compat21 games proflibs HARDWARE.TXT XF86336 compat22 info src INSTALL.TXT bin compat3x kern.flp LAYOUT.TXT catpages crypto manpages README.TXT cdrom.inf dict mfsroot.flp RELNOTES.TXT compat1x doc packages Copy the compressed packages into the packages/All directory under nfs. Make sure you have an INDEX file prepared in the packages directory. You can make your own INDEX entries like so: alfred-1.0||/|Alfred install bootstrap||alfred@FreeBSD.org|||| Then you can install custom packages, particularly your own custom post-install package. Custom Post-Install Package You can use the script pkgmaker.sh to create a custom package for post install, the idea is to have it install and configure any special things you may need done. pkgmaker is run in the directory above the package you wish to create with the single argument of the package (ie mypkg) which will then create a mypkg.tgz for you to include in your sysinstall package. Inside your custom package dir you will want a file called PLIST which contains all the files that you wish to install and be incorporated into your package. You will also want files called pre and post in the directory, these are shell scripts that you want to execute before and after your package is installed. Since this package is in your install.cfg file it should be run and do the final configuration for you.
diff --git a/en_US.ISO8859-1/articles/relaydelay/article.sgml b/en_US.ISO8859-1/articles/relaydelay/article.sgml index c9ac279d56..3ed75ec5f6 100644 --- a/en_US.ISO8859-1/articles/relaydelay/article.sgml +++ b/en_US.ISO8859-1/articles/relaydelay/article.sgml @@ -1,297 +1,288 @@ -%man; - - - -%freebsd; - - -%trademarks; - - + +%articles.ent; ]>
Using Greylist with &os; Tom Rhodes
trhodes@FreeBSD.org
 2004 The &os; Documentation Project An article written for the sole purpose of explaining the relaydelay system on a &os; mail server. A relaydelay or greylisting server cuts down on spam simply by issuing a TEMPFAIL error message to every incoming email. The purpose behind this idea is that most spammers use their personal computers with software to do their spamming. A real mail server should queue the message and try to send it later. Thus the spammer most likely moves on to the next host in place of trying to send the email again. This is an excellent idea; at least until the spammers begin to use software that offers to try again. But how does this work exactly? Well, when an email is received the message ID is stored in a database and the TEMPFAIL is returned along with the email. If the email is resent, the message ID will be checked against the message IDs currently stored in the database. If it exists in the database then the email is permitted to reach its intended recipient. Otherwise, the ID will be stored and a TEMPFAIL will be issued. This cycle will repeat with every email which comes into the server. From my personal experience, this really does cut out 90% of the spam. Basic Configuration &os; 4.X includes perl in the base system, but we need the threaded perl. Users of &os; 5.X may start the process after reading the forthcoming note. Remove the base perl and all traces of perl from the system with the following command: &prompt.root find / -name '*perl*' | xargs rm -rf This will require all ports which require perl to be rebuilt and reinstalled; sysutils/portupgrade is perfect for this. At least it will point out which ports have been removed and which will need to be reinstalled. Install lang/perl5.8 with the USE_THREADS=yes variable set. The current version of perl may need to be removed first; errors will be reported by the install process if this is necessary. &os; 4.X users will need to run the use.perl command in the work work directory. The permissions may need to be altered to make the file executable first, I just set it to 755 with chmod. From this point on, all users of &os; 4.X should uncomment the NOPERL option in their local make.conf file. Otherwise the base perl will be reinstalled during the next upgrade. Now for the database server; MySQL is perfect for this sort of work. Install the databases/mysql40-server along with databases/p5-DBD-mysql40. The previous port should imply the installation of databases/p5-DBI-137 so that knocks off another step. Install the perl based portable server plugin, net/p5-Net-Daemon port. Most of these port installations should have been straight forward. The next step will be more involved. Now install the mail/p5-Sendmail-Milter port. As of this writing the Makefile contains a line beginning with BROKEN, just remove it or comment it out. It is only marked this way because &os; neither has nor installs a threaded perl package by default. Once that line is removed it should build and install perfectly fine. Create a directory to hold temporary configuration files: &prompt.root; mkdir /tmp/relaydelay &prompt.root; cd /tmp/relaydelay Now that we have a temporary directory to work in, the following URLs should be sent to the fetch command: &prompt.root; fetch http://projects.puremagic.com/greylisting/releases/relaydelay-0.04.tgz &prompt.root; fetch http://lists.puremagic.com/pipermail/greylist-users/attachments/20030904/b8dafed9/relaydelay-0.04.bin The source code should now be unpacked: &prompt.root; gunzip -c relaydelay-0.04.tgz | tar xvf - There should now be several files into the temporary directory by this point. The appropriate information can now be passed to the database server by importing it from the mysql.sql file: &prompt.root; mysql < relaydelay-0.04/mysql.sql And patch the other files with the relaydelay.bin by running: &prompt.root; patch -d /tmp/relaydelay/relaydelay-0.04 < relaydelay.bin Edit the relaydelay.conf and the db_maintenance.pl file to append the correct username and password for the MySQL database. If the database was built and installed like the above then no users or passwords exist. This should be altered before putting this into production, that is covered in the database documentation and is beyond the scope of this document. Change the working directory to the relaydelay-0.04 directory: &prompt.root; cd relaydelay-0.04 Copy or move the configuration files to their respective directories: &prompt.root; mv db_maintenance.pl relaydelay.pl /usr/local/sbin &prompt.root; mv relaydelay.conf /etc/mail &prompt.root; mv relaydelay.sh /usr/local/etc/rc.d/ Test the current configuration by running: &prompt.root; sh /usr/local/etc/rc.d/relaydelay.sh start This file will not exist if the previous &man.mv.1; commands were neglected. If everything worked correctly a new file, relaydelay.log, should exist in /var/log. It should contain something similar to the following text: Loaded Config File: /etc/mail/relaydelay.conf Using connection 'local:/var/run/relaydelay.sock' for filter relaydelay DBI Connecting to DBI:mysql:database=relaydelay:host=localhost:port=3306 Spawned relaydelay daemon process 38277. Starting Sendmail::Milter 0.18 engine. If this does not appear then something went wrong, review the screen output or look for anything new in the messages log file. Glue everything together by adding the following line to /etc/mail/sendmail.mc or the customized site specific mc file: INPUT_MAIL_FILTER(`relaydelay', `S=local:/var/run/relaydelay.sock, T=S:1m;R:2m;E:3m')dnl Rebuild and reinstall the files in the /etc/mail directory and restart sendmail. A quick make restart should do the trick. Obtain the perl script located at http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html and save it in the relaydelay-0.04 directory. In the following examples this script is referred to as addlist.pl. Edit the whitelist_ip.txt file and modify it to include IP addresses of servers which should have the explicit abilities to bypass the relaydelay filters. i.e., domains from which email will not be issued a TEMPFAIL when received. Some examples could include: 192.168. # My internal network. 66.218.66 # Yahoo groups has unique senders. The blacklist_ip.txt file should be treated similarly but with reversed rules. List within this file IPs which should be denied without being issued a TEMPFAIL. This list of domains will never have the opportunity to prove that they are legitimate email servers. These files should now be imported into the database with the addlist.pl script obtained a few lines ago: &prompt.root; perl addlist.pl -whitelist 9999-12-31 23:59:59 < whitelist_ip.txt &prompt.root; perl addlist.pl -blacklist 9999-12-31 23:59:59 < blacklist_ip.txt To have relaydelay start with every system boot, add the to the /etc/rc.conf file. The /var/log/relaydelay.log log file should slowly fill up with success stories. Lines like the following should appear after a short time, depending on how busy the mail server is. === 2004-05-24 21:03:22 === Stored Sender: <someasshole@flawed-example.com> Passed Recipient: <local_user@pittgoth.com> Relay: example.net [XXX.XX.XXX.XX] - If_Addr: MY_IP_ADDRESS RelayIP: XX.XX.XX.XX - RelayName: example.net - RelayIdent: - PossiblyForged: 0 From: someasshole@flawed-example.com - To: local_user InMailer: esmtp - OutMailer: local - QueueID: i4P13Lo6000701111 Email is known but block has not expired. Issuing a tempfail. rowid: 51 IN ABORT CALLBACK - PrivData: 0<someasshole@flawed-example.com> The following line may now be added to /etc/newsyslog.conf to cause for relaydelay.log rotation at every 100 Kb: /var/log/relaydelay.log 644 3 100 * Z At some point there was an error about improper perl variables in the /etc/mail/relaydelay.conf. If those two variables are commented out then configuration may proceed as normal. Just remember to uncomment them before starting the relaydelay process.
diff --git a/en_US.ISO8859-1/articles/releng-packages/article.sgml b/en_US.ISO8859-1/articles/releng-packages/article.sgml index 9e7ec3070e..0648814b6d 100644 --- a/en_US.ISO8859-1/articles/releng-packages/article.sgml +++ b/en_US.ISO8859-1/articles/releng-packages/article.sgml @@ -1,375 +1,367 @@ -%man; - -%teams; - -%freebsd; - -%authors; - -%trademarks; + +%articles.ent; ]>
FreeBSD Release Engineering for Third Party Software Packages Steve Price
steve@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.xfree86; &tm-attrib.general; 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 set up 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. 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 ./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/articles/releng/article.sgml b/en_US.ISO8859-1/articles/releng/article.sgml index cad8f5f9c6..75183f532f 100644 --- a/en_US.ISO8859-1/articles/releng/article.sgml +++ b/en_US.ISO8859-1/articles/releng/article.sgml @@ -1,1058 +1,1046 @@ -%authors; - -%teams; - -%mailing-lists; - -%man; - -%freebsd; - -%trademarks; - -%urls; + +%articles.ent; The Release Engineering of Third Party Packages'> ]>
FreeBSD Release Engineering November 2001 BSDCon Europe Murray Stokely I've been involved in the development of FreeBSD based products since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems. FreeBSD 4.4 was the first official release of FreeBSD that I played a significant part in.
murray@FreeBSD.org
$FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.intel; &tm-attrib.xfree86; &tm-attrib.general; This paper describes the approach used by the FreeBSD release engineering team to make production quality releases of the FreeBSD Operating System. It details the methodology used for the official FreeBSD releases and describes the tools available for those interested in producing customized FreeBSD releases for corporate rollouts or commercial productization. Introduction The development of FreeBSD is a very open process. FreeBSD is comprised of contributions from thousands of people around the world. The FreeBSD Project provides anonymous CVS[1] access to the general public so that others can have access to log messages, diffs (patches) between development branches, and other productivity enhancements that formal source code management provides. This has been a huge help in attracting more talented developers to FreeBSD. However, I think everyone would agree that chaos would soon manifest if write access was opened up to everyone on the Internet. Therefore only a select group of nearly 300 people are given write access to the CVS repository. These committers[6] are responsible for the bulk of FreeBSD development. An elected core-team[7] of very senior developers provides some level of direction over the project. The rapid pace of FreeBSD development leaves little time for polishing the development system into a production quality release. To solve this dilemma, development continues on two parallel tracks. The main development branch is the HEAD or trunk of our CVS tree, known as FreeBSD-CURRENT or -CURRENT for short. A more stable branch is maintained, known as FreeBSD-STABLE or -STABLE for short. Both branches live in a master CVS repository in California and are replicated via CVSup[2] to mirrors all over the world. FreeBSD-CURRENT[8] is the bleeding-edge of FreeBSD development where all new changes first enter the system. FreeBSD-STABLE is the development branch from which major releases are made. Changes go into this branch at a different pace, and with general assumption that they have first gone into FreeBSD-CURRENT and have been thoroughly tested by our user community. In the interim period between releases, nightly snapshots are built automatically by the FreeBSD Project build machines and made available for download from ftp://stable.FreeBSD.org/. The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with CVSup and make world[8] helps to keep FreeBSD-STABLE in a very reliable condition even before the quality assurance activities ramp up pending a major release. Bug reports and feature requests are continuously submitted by users throughout the release cycle. Problems reports are entered into our GNATS[9] database through email, the &man.send-pr.1; application, or via the web interface provided at . In addition to the multitude of different technical mailing lists about FreeBSD, the &a.qa; provides a forum for discussing the finer points of release-polishing. To service our most conservative users, individual release branches were introduced with FreeBSD 4.3. These release branches are created shortly before a final release is made. After the release goes out, only the most critical security fixes and additions are merged onto the release branch. In addition to source updates via CVS, binary patchkits are available to keep systems on the RELENG_X_Y branches updated. discusses the different phases of the release engineering process leading up to the actual system build and describes the actual build process. describes how the base release may be extended by third parties and details some of the lessons learned through the release of FreeBSD 4.4. Finally, presents future directions of development. Release Process New releases of FreeBSD are released from the -STABLE branch at approximately four month intervals. The FreeBSD release process begins to ramp up 45 days before the anticipated release date when the release engineer sends an email to the development mailing lists to remind developers that they only have 15 days to integrate new changes before the code freeze. During this time, many developers perform what have become known as MFC sweeps. MFC stands for Merge From CURRENT and it describes the process of merging a tested change from our -CURRENT development branch to our -STABLE branch. Code Review Thirty days before the anticipated release, the source repository enters a code slush. During this time, all commits to the -STABLE branch must be approved by the &a.re;. The kinds of changes that are allowed during this 15 day period include: Bug fixes. Documentation updates. Security-related fixes of any kind. Minor changes to device drivers, such as adding new Device IDs. Any additional change that the release engineering team feels is justified, given the potential risk. After the first 15 days of the code slush, a release candidate is released for widespread testing and the code enters a code freeze where it becomes much harder to justify new changes to the system unless a serious bug-fix or security issue is involved. During the code freeze, at least one release candidate is released per week, until the final release is ready. During the days leading to the final release, the release engineering team is in constant communication with the security-officer team, the documentation maintainers, and the port maintainers, to ensure that all of the different components required for a successful release are available. Final Release Checklist When several release candidates have been made available for widespread testing and all major issues have been resolved, the final release polishing can begin. Creating the Release Branch As described in the introduction, the RELENG_X_Y release branch is a relatively new addition to our release engineering methodology. The first step in creating this branch is to ensure that you are working with the newest version of the RELENG_X sources that you want to branch from. /usr/src&prompt.root; cvs update -rRELENG_4 -P -d The next step is to create a branch point tag, so that diffs against the start of the branch are easier with CVS: /usr/src&prompt.root; cvs rtag -rRELENG_4 RELENG_4_8_BP src And then a new branch tag is created with: /usr/src&prompt.root; cvs rtag -b -rRELENG_4_8_BP RELENG_4_8 src The RELENG_* tags are restricted for use by the CVS-meisters and release engineers. A tag is CVS vernacular for a label that identifies the source at a specific point in time. By tagging the tree, we ensure that future release builders will always be able to use the same source we used to create the official FreeBSD Project releases. FreeBSD Development Branch FreeBSD 3.x STABLE Branch FreeBSD 4.x STABLE Branch Bumping up the Version Number Before the final release can be tagged, built, and released, the following files need to be modified to reflect the correct version of FreeBSD: doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml doc/en_US.ISO8859-1/books/porters-handbook/book.sgml doc/share/sgml/freebsd.ent src/Makefile.inc1 src/UPDATING src/gnu/usr.bin/groff/tmac/mdoc.local src/release/Makefile src/release/doc/en_US.ISO8859-1/share/sgml/release.dsl src/release/doc/share/examples/Makefile.relnotesng src/release/doc/share/sgml/release.ent src/share/examples/cvsup/standard-supfile src/sys/conf/newvers.sh src/sys/sys/param.h src/usr.sbin/pkg_install/add/main.c www/en/docs.sgml www/en/cgi/ports.cgi ports/Tools/scripts/release/config The release notes and errata files also need to be adjusted for the new release (on the release branch) and truncated appropriately (on the stable/current branch): src/release/doc/en_US.ISO8859-1/relnotes/common/new.sgml src/release/doc/en_US.ISO8859-1/errata/article.sgml Sysinstall should be updated to note the number of available ports and the amount of disk space required for the Ports Collection. This information is currently kept in src/release/sysinstall/dist.c. After the release has been built, a number of file should be updated to announce the release to the world. www/share/sgml/includes.release.sgml www/share/sgml/includes.release.xsl www/en/releases/* www/en/releng/index.sgml www/en/news/news.xml src/share/misc/bsd-family-tree Creating Release Tags When the final release is ready, the following command will create the RELENG_4_8_0_RELEASE tag. /usr/src&prompt.root; cvs rtag -rRELENG_4_8 RELENG_4_8_0_RELEASE src The Documentation and Ports managers are responsible for tagging the respective trees with the RELEASE_4_8_0 tag. Occasionally, a last minute fix may be required after the final tags have been created. In practice this isn't a problem, since CVS allows tags to be manipulated with cvs tag -d tagname filename. It is very important that any last minute changes be tagged appropriately as part of the release. FreeBSD releases must always be reproduceable. Local hacks in the release engineer's environment are not acceptable. Release Building FreeBSD releases can be built by anyone with a fast machine and access to a source repository. (That should be everyone, since we offer anonymous CVS! See The Handbook for details.) The only special requirement is that the &man.vn.4; device must be available. (On -CURRENT, this device has been replaced by the new &man.md.4; memory disk driver.) If the device is not loaded into your kernel, then the kernel module should be automatically loaded when &man.vnconfig.8; is executed during the boot media creation phase. All of the tools necessary to build a release are available from the CVS repository in src/release. These tools aim to provide a consistent way to build FreeBSD releases. A complete release can actually be built with only a single command, including the creation of ISO images suitable for burning to CDROM, installation floppies, and an FTP install directory. This command is aptly named make release. <command>make release</command> To successfully build a release, you must first populate /usr/obj by running make world or simply make buildworld. The release target requires several variables be set properly to build a release: CHROOTDIR - The directory to be used as the chroot environment for the entire release build. BUILDNAME - The name of the release to be built. CVSROOT - The location of a CVS Repository. RELEASETAG - The CVS tag corresponding to the release you would like to build. If you do not already have access to a local CVS repository, then you may mirror one with CVSup. The supplied supfile, /usr/share/examples/cvsup/cvs-supfile, is a useful starting point for mirroring the CVS repository. If RELEASETAG is omitted, then the release will be built from the HEAD (a.k.a. -CURRENT) branch. Releases built from this branch are normally referred to as -CURRENT snapshots. There are many other variables available to customize the release build. Most of these variables are documented at the top of src/release/Makefile. The exact command used to build the official FreeBSD 4.7 (x86) release was: make release CHROOTDIR=/local3/release \ BUILDNAME=4.7-RELEASE \ CVSROOT=/host/cvs/usr/home/ncvs \ RELEASETAG=RELENG_4_7_0_RELEASE The release Makefile can be broken down into several distinct steps. Creation of a sanitized system environment in a separate directory hierarchy with make installworld. Checkout from CVS of a clean version of the system source, documentation, and ports into the release build hierarchy. Population of /etc and /dev in the chrooted environment. chroot into the release build hierarchy, to make it harder for the outside environment to taint this build. make world in the chrooted environment. Build of Kerberos-related binaries. Build GENERIC kernel. Creation of a staging directory tree where the binary distributions will be built and packaged. Build and installation of the documentation toolchain needed to convert the documentation source (SGML) into HTML and text documents that will accompany the release. Build and installation of the actual documentation (user manuals, tutorials, release notes, hardware compatibility lists, and so on.) Build of the crunched binaries used for installation floppies. Package up distribution tarballs of the binaries and sources. Create the boot media and a fixit floppy. Create FTP installation hierarchy. (optionally) Create ISO images for CDROM/DVD media. For more information about the release build infrastructure, please see &man.release.7;. Building <application>&xfree86;</application> &xfree86; is an important component for many desktop users. Prior to FreeBSD 4.6-RELEASE, releases used &xfree86; 3.X by default. The easiest way to build these versions is to use the src/release/scripts/X11/build_x.sh script. This script requires that &xfree86; and Tcl/Tk already be installed on the build host. After compiling the necessary X servers, the script will package all of the files into tarballs that &man.sysinstall.8; expects to find in the XF86336 directory of the installation media. Beginning with FreeBSD 4.6-RELEASE, &man.sysinstall.8; installs &xfree86; 4.X by default, as a set of normal packages. These can either be the packages generated by the package-building cluster or packages built from an appropriately tagged ports tree. It is important to remove any site-specific settings from /etc/make.conf. For example, it would be unwise to distribute binaries that were built on a system with CPUTYPE set to a specific processor. Contributed Software (<quote>ports</quote>) 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 official FreeBSD releases. The release engineering activities for our collection of third-party packages is beyond the scope of this document. A separate article, &art.re.pkgs;, covers this topic in depth. Release ISOs Starting with FreeBSD 4.4, the FreeBSD Project decided to release all four ISO images that were previously sold on the BSDi/Wind River Systems/FreeBSD Mall official CDROM distributions. Each of the four discs must contain a README.TXT file that explains the contents of the disc, a CDROM.INF file that provides meta-data for the disc so that &man.sysinstall.8; can validate and use the contents, and a filename.txt file that provides a manifest for the disc. This manifest can be created with a simple command: /stage/cdrom&prompt.root; find . -type f | sed -e 's/^\.\///' | sort > filename.txt The specific requirements of each CD are outlined below. Disc 1 The first disc is almost completely created by make release. The only changes that should be made to the disc1 directory are the addition of a tools directory, &xfree86;, and as many popular third party software packages as will fit on the disc. The tools directory contains software that allow users to create installation floppies from other operating systems. This disc should be made bootable so that users of modern PCs do not need to create installation floppy disks. If an alternate version of &xfree86; is to be provided, then &man.sysinstall.8; must be updated to reflect the new location and installation instructions. The relevant code is contained in src/release/sysinstall on -STABLE or src/usr.sbin/sysinstall on -CURRENT. Specifically, the files dist.c, menus.c, and config.c will need to be updated. Disc 2 The second disc is also largely created by make release. This disc contains a live filesystem that can be used from &man.sysinstall.8; to troubleshoot a FreeBSD installation. This disc should be bootable and should also contain a compressed copy of the CVS repository in the CVSROOT directory and commercial software demos in the commerce directory. Discs 3 and 4 The remaining two discs contain additional software packages for FreeBSD. The packages should be clustered so that a package and all of its dependencies are included on the same disc. More information about the creation of these discs is provided in the &art.re.pkgs; article. Distribution FTP Sites When the release has been thoroughly tested and packaged for distribution, the master FTP site must be updated. The official FreeBSD public FTP sites are all mirrors of a master server that is open only to other FTP sites. This site is known as ftp-master. When the release is ready, the following files must be modified on ftp-master: /pub/FreeBSD/releases/arch/X.Y-RELEASE/ The installable FTP directory as output from make release. /pub/FreeBSD/ports/arch/packages-X.Y-release/ The complete package build for this release. /pub/FreeBSD/releases/arch/X.Y-RELEASE/tools A symlink to ../../../tools. /pub/FreeBSD/releases/arch/X.Y-RELEASE/packages A symlink to ../../../ports/arch/packages-X.Y-release. /pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso The ISO images. The * is disc1, disc2, etc. Only if there is a disc1 and there is an alternative first installation CD (for example a stripped-down install with no windowing system) there may be a mini as well. For more information about the distribution mirror architecture of the FreeBSD FTP sites, please see the Mirroring FreeBSD article. It may take many hours to two days after updating ftp-master before a majority of the Tier-1 FTP sites have the new software depending on whether or not a package set got loaded at the same time. It is imperative that the release engineers coordinate with the &a.mirror-announce; before announcing the general availability of new software on the FTP sites. Ideally the release package set should be loaded at least four days prior to release day. The release bits should be loaded between 24 and 48 hours before the planned release time with other file permissions turned off. This will allow the mirror sites to download it but the general public will not be able to download it from the mirror sites. Mail should be sent to &a.mirror-announce; at the time the release bits get posted saying the release has been staged and giving the time that the mirror sites should begin allowing access. Be sure to include a time zone with the time, for example make it relative to GMT. CD-ROM Replication Coming soon: Tips for sending FreeBSD ISOs to a replicator and quality assurance measures to be taken. Extensibility Although FreeBSD forms a complete operating system, there is nothing that forces you to use the system exactly as we have packaged it up for distribution. We have tried to design the system to be as extensible as possible so that it can serve as a platform that other commercial products can be built on top of. The only rule we have about this is that if you are going to distribute FreeBSD with non-trivial changes, we encourage you to document your enhancements! The FreeBSD community can only help support users of the software we provide. We certainly encourage innovation in the form of advanced installation and administration tools, for example, but we can't be expected to answer questions about it. Creating Customized Boot floppies Many sites have complex requirements that may require additional kernel modules or userland tools be added to the installation floppies. The quick and dirty way to accomplish this would be to modify the staging directory of an existing make release build hierarchy: Apply patches or add additional files inside the chroot release build directory. rm ${CHROOTDIR}/usr/obj/usr/src/release/release.[59] rebuild &man.sysinstall.8;, the kernel, or whatever parts of the system your change affected. chroot ${CHROOTDIR} ./mk floppies New release floppies will be located in ${CHROOTDIR}/R/stage/floppies. Alternatively, the boot.flp make target can be called, or the filesystem creating script, src/release/scripts/doFS.sh, may be invoked directly. Local patches may also be supplied to the release build by defining the LOCAL_PATCH variable in make release. Scripting <command>sysinstall</command> The FreeBSD system installation and configuration tool, &man.sysinstall.8;, can be scripted to provide automated installs for large sites. This functionality can be used in conjunction with &intel; PXE[13] to bootstrap systems from the network, or via custom boot floppies with a sysinstall script. An example sysinstall script is available in the CVS tree as src/release/sysinstall/install.cfg. Lessons Learned from FreeBSD 4.4 The release engineering process for 4.4 formally began on August 1st, 2001. After that date all commits to the RELENG_4 branch of FreeBSD had to be explicitly approved by the &a.re;. The first release candidate for the x86 architecture was released on August 16, followed by 4 more release candidates leading up to the final release on September 18th. The security officer was very involved in the last week of the process as several security issues were found in the earlier release candidates. A total of over 500 emails were sent to the &a.re; in little over a month. Our user community has made it very clear that the security and stability of a FreeBSD release should not be sacrificed for any self-imposed deadlines or target release dates. The FreeBSD Project has grown tremendously over its lifetime and the need for standardized release engineering procedures has never been more apparent. This will become even more important as FreeBSD is ported to new platforms. Future Directions It is imperative for our release engineering activities to scale with our growing userbase. Along these lines we are working very hard to document the procedures involved in producing FreeBSD releases. Parallelism - Certain portions of the release build are actually embarrassingly parallel. Most of the tasks are very I/O intensive, so having multiple high-speed disk drives is actually more important than using multiple processors in speeding up the make release process. If multiple disks are used for different hierarchies in the &man.chroot.2; environment, then the CVS checkout of the ports and doc trees can be happening simultaneously as the make world on another disk. Using a RAID solution (hardware or software) can significantly decrease the overall build time. Cross-building releases - Building IA-64 or Alpha release on x86 hardware? make TARGET=ia64 release. Regression Testing - We need better automated correctness testing for FreeBSD. Installation Tools - Our installation program has long since outlived its intended life span. Several projects are under development to provide a more advanced installation mechanism. One of the most promising is the libh project[5] which aims to provide an intelligent new package framework and GUI installation program. Acknowledgements I would like to thank Jordan Hubbard for giving me the opportunity to take on some of the release engineering responsibilities for FreeBSD 4.4 and also for all of his work throughout the years making FreeBSD what it is today. Of course the release wouldn't have been possible without all of the release-related work done by &a.asami;, &a.steve;, &a.bmah;, &a.nik;, &a.obrien;, &a.kris;, &a.jhb; and the rest of the FreeBSD development community. I would also like to thank &a.rgrimes;, &a.phk;, and others who worked on the release engineering tools in the very early days of FreeBSD. This article was influenced by release engineering documents from the CSRG[14], the NetBSD Project[11], and John Baldwin's proposed release engineering process notes[12]. References [1] CVS - Concurrent Versions System [2] CVSup - The CVS-Optimized General Purpose Network File Distribution System [3] [4] FreeBSD Ports Collection [5] The libh Project [6] FreeBSD Committers [7] FreeBSD Core-Team [8] FreeBSD Handbook [9] GNATS: The GNU Bug Tracking System [10] FreeBSD PR Statistics [11] NetBSD Developer Documentation: Release Engineering [12] John Baldwin's FreeBSD Release Engineering Proposal [13] PXE Jumpstart Guide [14] Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: The Release Engineering of 4.3BSD
diff --git a/en_US.ISO8859-1/articles/serial-uart/article.sgml b/en_US.ISO8859-1/articles/serial-uart/article.sgml index c63bd54548..c0de19c776 100644 --- a/en_US.ISO8859-1/articles/serial-uart/article.sgml +++ b/en_US.ISO8859-1/articles/serial-uart/article.sgml @@ -1,2445 +1,2439 @@ -%man; - -%authors; - -%trademarks; - -%urls; + +%articles.ent; ]>
Serial and UART Tutorial Frank Durda
uhclem@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.microsoft; &tm-attrib.general; This article talks about using serial hardware with FreeBSD. The UART: What it is and how it works Copyright © 1996 &a.uhclem;, All Rights Reserved. 13 January 1996. The Universal Asynchronous Receiver/Transmitter (UART) controller is the key component of the serial communications subsystem of a computer. The UART takes bytes of data and transmits the individual bits in a sequential fashion. At the destination, a second UART re-assembles the bits into complete bytes. Serial transmission is commonly used with modems and for non-networked communication between computers, terminals and other devices. There are two primary forms of serial transmission: Synchronous and Asynchronous. Depending on the modes that are supported by the hardware, the name of the communication sub-system will usually include a A if it supports Asynchronous communications, and a S if it supports Synchronous communications. Both forms are described below. Some common acronyms are:
UART Universal Asynchronous Receiver/Transmitter
USART Universal Synchronous-Asynchronous Receiver/Transmitter
Synchronous Serial Transmission Synchronous serial transmission requires that the sender and receiver share a clock with one another, or that the sender provide a strobe or other timing signal so that the receiver knows when to read the next bit of the data. In most forms of serial Synchronous communication, if there is no data available at a given instant to transmit, a fill character must be sent instead so that data is always being transmitted. Synchronous communication is usually more efficient because only data bits are transmitted between sender and receiver, and synchronous communication can be more costly if extra wiring and circuits are required to share a clock signal between the sender and receiver. A form of Synchronous transmission is used with printers and fixed disk devices in that the data is sent on one set of wires while a clock or strobe is sent on a different wire. Printers and fixed disk devices are not normally serial devices because most fixed disk interface standards send an entire word of data for each clock or strobe signal by using a separate wire for each bit of the word. In the PC industry, these are known as Parallel devices. The standard serial communications hardware in the PC does not support Synchronous operations. This mode is described here for comparison purposes only. Asynchronous Serial Transmission Asynchronous transmission allows data to be transmitted without the sender having to send a clock signal to the receiver. Instead, the sender and receiver must agree on timing parameters in advance and special bits are added to each word which are used to synchronize the sending and receiving units. When a word is given to the UART for Asynchronous transmissions, a bit called the "Start Bit" is added to the beginning of each word that is to be transmitted. The Start Bit is used to alert the receiver that a word of data is about to be sent, and to force the clock in the receiver into synchronization with the clock in the transmitter. These two clocks must be accurate enough to not have the frequency drift by more than 10% during the transmission of the remaining bits in the word. (This requirement was set in the days of mechanical teleprinters and is easily met by modern electronic equipment.) After the Start Bit, the individual bits of the word of data are sent, with the Least Significant Bit (LSB) being sent first. Each bit in the transmission is transmitted for exactly the same amount of time as all of the other bits, and the receiver looks at the wire at approximately halfway through the period assigned to each bit to determine if the bit is a 1 or a 0. For example, if it takes two seconds to send each bit, the receiver will examine the signal to determine if it is a 1 or a 0 after one second has passed, then it will wait two seconds and then examine the value of the next bit, and so on. The sender does not know when the receiver has looked at the value of the bit. The sender only knows when the clock says to begin transmitting the next bit of the word. When the entire data word has been sent, the transmitter may add a Parity Bit that the transmitter generates. The Parity Bit may be used by the receiver to perform simple error checking. Then at least one Stop Bit is sent by the transmitter. When the receiver has received all of the bits in the data word, it may check for the Parity Bits (both sender and receiver must agree on whether a Parity Bit is to be used), and then the receiver looks for a Stop Bit. If the Stop Bit does not appear when it is supposed to, the UART considers the entire word to be garbled and will report a Framing Error to the host processor when the data word is read. The usual cause of a Framing Error is that the sender and receiver clocks were not running at the same speed, or that the signal was interrupted. Regardless of whether the data was received correctly or not, the UART automatically discards the Start, Parity and Stop bits. If the sender and receiver are configured identically, these bits are not passed to the host. If another word is ready for transmission, the Start Bit for the new word can be sent as soon as the Stop Bit for the previous word has been sent. Because asynchronous data is self synchronizing, if there is no data to transmit, the transmission line can be idle. Other UART Functions In addition to the basic job of converting data from parallel to serial for transmission and from serial to parallel on reception, a UART will usually provide additional circuits for signals that can be used to indicate the state of the transmission media, and to regulate the flow of data in the event that the remote device is not prepared to accept more data. For example, when the device connected to the UART is a modem, the modem may report the presence of a carrier on the phone line while the computer may be able to instruct the modem to reset itself or to not take calls by raising or lowering one more of these extra signals. The function of each of these additional signals is defined in the EIA RS232-C standard. The RS232-C and V.24 Standards In most computer systems, the UART is connected to circuitry that generates signals that comply with the EIA RS232-C specification. There is also a CCITT standard named V.24 that mirrors the specifications included in RS232-C. RS232-C Bit Assignments (Marks and Spaces) In RS232-C, a value of 1 is called a Mark and a value of 0 is called a Space. When a communication line is idle, the line is said to be Marking, or transmitting continuous 1 values. The Start bit always has a value of 0 (a Space). The Stop Bit always has a value of 1 (a Mark). This means that there will always be a Mark (1) to Space (0) transition on the line at the start of every word, even when multiple word are transmitted back to back. This guarantees that sender and receiver can resynchronize their clocks regardless of the content of the data bits that are being transmitted. The idle time between Stop and Start bits does not have to be an exact multiple (including zero) of the bit rate of the communication link, but most UARTs are designed this way for simplicity. In RS232-C, the "Marking" signal (a 1) is represented by a voltage between -2 VDC and -12 VDC, and a "Spacing" signal (a 0) is represented by a voltage between 0 and +12 VDC. The transmitter is supposed to send +12 VDC or -12 VDC, and the receiver is supposed to allow for some voltage loss in long cables. Some transmitters in low power devices (like portable computers) sometimes use only +5 VDC and -5 VDC, but these values are still acceptable to a RS232-C receiver, provided that the cable lengths are short. RS232-C Break Signal RS232-C also specifies a signal called a Break, which is caused by sending continuous Spacing values (no Start or Stop bits). When there is no electricity present on the data circuit, the line is considered to be sending Break. The Break signal must be of a duration longer than the time it takes to send a complete byte plus Start, Stop and Parity bits. Most UARTs can distinguish between a Framing Error and a Break, but if the UART cannot do this, the Framing Error detection can be used to identify Breaks. In the days of teleprinters, when numerous printers around the country were wired in series (such as news services), any unit could cause a Break by temporarily opening the entire circuit so that no current flowed. This was used to allow a location with urgent news to interrupt some other location that was currently sending information. In modern systems there are two types of Break signals. If the Break is longer than 1.6 seconds, it is considered a "Modem Break", and some modems can be programmed to terminate the conversation and go on-hook or enter the modems' command mode when the modem detects this signal. If the Break is smaller than 1.6 seconds, it signifies a Data Break and it is up to the remote computer to respond to this signal. Sometimes this form of Break is used as an Attention or Interrupt signal and sometimes is accepted as a substitute for the ASCII CONTROL-C character. Marks and Spaces are also equivalent to Holes and No Holes in paper tape systems. Breaks cannot be generated from paper tape or from any other byte value, since bytes are always sent with Start and Stop bit. The UART is usually capable of generating the continuous Spacing signal in response to a special command from the host processor. RS232-C DTE and DCE Devices The RS232-C specification defines two types of equipment: the Data Terminal Equipment (DTE) and the Data Carrier Equipment (DCE). Usually, the DTE device is the terminal (or computer), and the DCE is a modem. Across the phone line at the other end of a conversation, the receiving modem is also a DCE device and the computer that is connected to that modem is a DTE device. The DCE device receives signals on the pins that the DTE device transmits on, and vice versa. When two devices that are both DTE or both DCE must be connected together without a modem or a similar media translater between them, a NULL modem must be used. The NULL modem electrically re-arranges the cabling so that the transmitter output is connected to the receiver input on the other device, and vice versa. Similar translations are performed on all of the control signals so that each device will see what it thinks are DCE (or DTE) signals from the other device. The number of signals generated by the DTE and DCE devices are not symmetrical. The DTE device generates fewer signals for the DCE device than the DTE device receives from the DCE. RS232-C Pin Assignments The EIA RS232-C specification (and the ITU equivalent, V.24) calls for a twenty-five pin connector (usually a DB25) and defines the purpose of most of the pins in that connector. In the IBM Personal Computer and similar systems, a subset of RS232-C signals are provided via nine pin connectors (DB9). The signals that are not included on the PC connector deal mainly with synchronous operation, and this transmission mode is not supported by the UART that IBM selected for use in the IBM PC. Depending on the computer manufacturer, a DB25, a DB9, or both types of connector may be used for RS232-C communications. (The IBM PC also uses a DB25 connector for the parallel printer interface which causes some confusion.) Below is a table of the RS232-C signal assignments in the DB25 and DB9 connectors. DB25 RS232-C Pin DB9 IBM PC Pin EIA Circuit Symbol CCITT Circuit Symbol Common Name Signal Source Description 1 - AA 101 PG/FG - Frame/Protective Ground 2 3 BA 103 TD DTE Transmit Data 3 2 BB 104 RD DCE Receive Data 4 7 CA 105 RTS DTE Request to Send 5 8 CB 106 CTS DCE Clear to Send 6 6 CC 107 DSR DCE Data Set Ready 7 5 AV 102 SG/GND - Signal Ground 8 1 CF 109 DCD/CD DCE Data Carrier Detect 9 - - - - - Reserved for Test 10 - - - - - Reserved for Test 11 - - - - - Reserved for Test 12 - CI 122 SRLSD DCE Sec. Recv. Line Signal Detector 13 - SCB 121 SCTS DCE Secondary Clear to Send 14 - SBA 118 STD DTE Secondary Transmit Data 15 - DB 114 TSET DCE Trans. Sig. Element Timing 16 - SBB 119 SRD DCE Secondary Received Data 17 - DD 115 RSET DCE Receiver Signal Element Timing 18 - - 141 LOOP DTE Local Loopback 19 - SCA 120 SRS DTE Secondary Request to Send 20 4 CD 108.2 DTR DTE Data Terminal Ready 21 - - - RDL DTE Remote Digital Loopback 22 9 CE 125 RI DCE Ring Indicator 23 - CH 111 DSRS DTE Data Signal Rate Selector 24 - DA 113 TSET DTE Trans. Sig. Element Timing 25 - - 142 - DCE Test Mode Bits, Baud and Symbols Baud is a measurement of transmission speed in asynchronous communication. Because of advances in modem communication technology, this term is frequently misused when describing the data rates in newer devices. Traditionally, a Baud Rate represents the number of bits that are actually being sent over the media, not the amount of data that is actually moved from one DTE device to the other. The Baud count includes the overhead bits Start, Stop and Parity that are generated by the sending UART and removed by the receiving UART. This means that seven-bit words of data actually take 10 bits to be completely transmitted. Therefore, a modem capable of moving 300 bits per second from one place to another can normally only move 30 7-bit words if Parity is used and one Start and Stop bit are present. If 8-bit data words are used and Parity bits are also used, the data rate falls to 27.27 words per second, because it now takes 11 bits to send the eight-bit words, and the modem still only sends 300 bits per second. The formula for converting bytes per second into a baud rate and vice versa was simple until error-correcting modems came along. These modems receive the serial stream of bits from the UART in the host computer (even when internal modems are used the data is still frequently serialized) and converts the bits back into bytes. These bytes are then combined into packets and sent over the phone line using a Synchronous transmission method. This means that the Stop, Start, and Parity bits added by the UART in the DTE (the computer) were removed by the modem before transmission by the sending modem. When these bytes are received by the remote modem, the remote modem adds Start, Stop and Parity bits to the words, converts them to a serial format and then sends them to the receiving UART in the remote computer, who then strips the Start, Stop and Parity bits. The reason all these extra conversions are done is so that the two modems can perform error correction, which means that the receiving modem is able to ask the sending modem to resend a block of data that was not received with the correct checksum. This checking is handled by the modems, and the DTE devices are usually unaware that the process is occurring. By striping the Start, Stop and Parity bits, the additional bits of data that the two modems must share between themselves to perform error-correction are mostly concealed from the effective transmission rate seen by the sending and receiving DTE equipment. For example, if a modem sends ten 7-bit words to another modem without including the Start, Stop and Parity bits, the sending modem will be able to add 30 bits of its own information that the receiving modem can use to do error-correction without impacting the transmission speed of the real data. The use of the term Baud is further confused by modems that perform compression. A single 8-bit word passed over the telephone line might represent a dozen words that were transmitted to the sending modem. The receiving modem will expand the data back to its original content and pass that data to the receiving DTE. Modern modems also include buffers that allow the rate that bits move across the phone line (DCE to DCE) to be a different speed than the speed that the bits move between the DTE and DCE on both ends of the conversation. Normally the speed between the DTE and DCE is higher than the DCE to DCE speed because of the use of compression by the modems. Because the number of bits needed to describe a byte varied during the trip between the two machines plus the differing bits-per-seconds speeds that are used present on the DTE-DCE and DCE-DCE links, the usage of the term Baud to describe the overall communication speed causes problems and can misrepresent the true transmission speed. So Bits Per Second (bps) is the correct term to use to describe the transmission rate seen at the DCE to DCE interface and Baud or Bits Per Second are acceptable terms to use when a connection is made between two systems with a wired connection, or if a modem is in use that is not performing error-correction or compression. Modern high speed modems (2400, 9600, 14,400, and 19,200bps) in reality still operate at or below 2400 baud, or more accurately, 2400 Symbols per second. High speed modem are able to encode more bits of data into each Symbol using a technique called Constellation Stuffing, which is why the effective bits per second rate of the modem is higher, but the modem continues to operate within the limited audio bandwidth that the telephone system provides. Modems operating at 28,800 and higher speeds have variable Symbol rates, but the technique is the same. The IBM Personal Computer UART Starting with the original IBM Personal Computer, IBM selected the National Semiconductor INS8250 UART for use in the IBM PC Parallel/Serial Adapter. Subsequent generations of compatible computers from IBM and other vendors continued to use the INS8250 or improved versions of the National Semiconductor UART family. National Semiconductor UART Family Tree There have been several versions and subsequent generations of the INS8250 UART. Each major version is described below. INS8250 -> INS8250B \ \ \-> INS8250A -> INS82C50A \ \ \-> NS16450 -> NS16C450 \ \ \-> NS16550 -> NS16550A -> PC16550D INS8250 This part was used in the original IBM PC and IBM PC/XT. The original name for this part was the INS8250 ACE (Asynchronous Communications Element) and it is made from NMOS technology. The 8250 uses eight I/O ports and has a one-byte send and a one-byte receive buffer. This original UART has several race conditions and other flaws. The original IBM BIOS includes code to work around these flaws, but this made the BIOS dependent on the flaws being present, so subsequent parts like the 8250A, 16450 or 16550 could not be used in the original IBM PC or IBM PC/XT. INS8250-B This is the slower speed of the INS8250 made from NMOS technology. It contains the same problems as the original INS8250. INS8250A An improved version of the INS8250 using XMOS technology with various functional flaws corrected. The INS8250A was used initially in PC clone computers by vendors who used clean BIOS designs. Because of the corrections in the chip, this part could not be used with a BIOS compatible with the INS8250 or INS8250B. INS82C50A This is a CMOS version (low power consumption) of the INS8250A and has similar functional characteristics. NS16450 Same as NS8250A with improvements so it can be used with faster CPU bus designs. IBM used this part in the IBM AT and updated the IBM BIOS to no longer rely on the bugs in the INS8250. NS16C450 This is a CMOS version (low power consumption) of the NS16450. NS16550 Same as NS16450 with a 16-byte send and receive buffer but the buffer design was flawed and could not be reliably be used. NS16550A Same as NS16550 with the buffer flaws corrected. The 16550A and its successors have become the most popular UART design in the PC industry, mainly due to its ability to reliably handle higher data rates on operating systems with sluggish interrupt response times. NS16C552 This component consists of two NS16C550A CMOS UARTs in a single package. PC16550D Same as NS16550A with subtle flaws corrected. This is revision D of the 16550 family and is the latest design available from National Semiconductor. The NS16550AF and the PC16550D are the same thing National reorganized their part numbering system a few years ago, and the NS16550AFN no longer exists by that name. (If you have a NS16550AFN, look at the date code on the part, which is a four digit number that usually starts with a nine. The first two digits of the number are the year, and the last two digits are the week in that year when the part was packaged. If you have a NS16550AFN, it is probably a few years old.) The new numbers are like PC16550DV, with minor differences in the suffix letters depending on the package material and its shape. (A description of the numbering system can be found below.) It is important to understand that in some stores, you may pay $15(US) for a NS16550AFN made in 1990 and in the next bin are the new PC16550DN parts with minor fixes that National has made since the AFN part was in production, the PC16550DN was probably made in the past six months and it costs half (as low as $5(US) in volume) as much as the NS16550AFN because they are readily available. As the supply of NS16550AFN chips continues to shrink, the price will probably continue to increase until more people discover and accept that the PC16550DN really has the same function as the old part number. National Semiconductor Part Numbering System The older NSnnnnnrqp part numbers are now of the format PCnnnnnrgp. The r is the revision field. The current revision of the 16550 from National Semiconductor is D. The p is the package-type field. The types are: "F" QFP (quad flat pack) L lead type "N" DIP (dual inline package) through hole straight lead type "V" LPCC (lead plastic chip carrier) J lead type The g is the product grade field. If an I precedes the package-type letter, it indicates an industrial grade part, which has higher specs than a standard part but not as high as Military Specification (Milspec) component. This is an optional field. So what we used to call a NS16550AFN (DIP Package) is now called a PC16550DN or PC16550DIN. Other Vendors and Similar UARTs Over the years, the 8250, 8250A, 16450 and 16550 have been licensed or copied by other chip vendors. In the case of the 8250, 8250A and 16450, the exact circuit (the megacell) was licensed to many vendors, including Western Digital and Intel. Other vendors reverse-engineered the part or produced emulations that had similar behavior. In internal modems, the modem designer will frequently emulate the 8250A/16450 with the modem microprocessor, and the emulated UART will frequently have a hidden buffer consisting of several hundred bytes. Because of the size of the buffer, these emulations can be as reliable as a 16550A in their ability to handle high speed data. However, most operating systems will still report that the UART is only a 8250A or 16450, and may not make effective use of the extra buffering present in the emulated UART unless special drivers are used. Some modem makers are driven by market forces to abandon a design that has hundreds of bytes of buffer and instead use a 16550A UART so that the product will compare favorably in market comparisons even though the effective performance may be lowered by this action. A common misconception is that all parts with 16550A written on them are identical in performance. There are differences, and in some cases, outright flaws in most of these 16550A clones. When the NS16550 was developed, the National Semiconductor obtained several patents on the design and they also limited licensing, making it harder for other vendors to provide a chip with similar features. Because of the patents, reverse-engineered designs and emulations had to avoid infringing the claims covered by the patents. Subsequently, these copies almost never perform exactly the same as the NS16550A or PC16550D, which are the parts most computer and modem makers want to buy but are sometimes unwilling to pay the price required to get the genuine part. Some of the differences in the clone 16550A parts are unimportant, while others can prevent the device from being used at all with a given operating system or driver. These differences may show up when using other drivers, or when particular combinations of events occur that were not well tested or considered in the &windows; driver. This is because most modem vendors and 16550-clone makers use the Microsoft drivers from &windows; for Workgroups 3.11 and the µsoft; &ms-dos; utility as the primary tests for compatibility with the NS16550A. This over-simplistic criteria means that if a different operating system is used, problems could appear due to subtle differences between the clones and genuine components. National Semiconductor has made available a program named COMTEST that performs compatibility tests independent of any OS drivers. It should be remembered that the purpose of this type of program is to demonstrate the flaws in the products of the competition, so the program will report major as well as extremely subtle differences in behavior in the part being tested. In a series of tests performed by the author of this document in 1994, components made by National Semiconductor, TI, StarTech, and CMD as well as megacells and emulations embedded in internal modems were tested with COMTEST. A difference count for some of these components is listed below. Because these tests were performed in 1994, they may not reflect the current performance of the given product from a vendor. It should be noted that COMTEST normally aborts when an excessive number or certain types of problems have been detected. As part of this testing, COMTEST was modified so that it would not abort no matter how many differences were encountered. Vendor Part Number Errors (aka "differences" reported) National (PC16550DV) 0 National (NS16550AFN) 0 National (NS16C552V) 0 TI (TL16550AFN) 3 CMD (16C550PE) 19 StarTech (ST16C550J) 23 Rockwell Reference modem with internal 16550 or an emulation (RC144DPi/C3000-25) 117 Sierra Modem with an internal 16550 (SC11951/SC11351) 91 To date, the author of this document has not found any non-National parts that report zero differences using the COMTEST program. It should also be noted that National has had five versions of the 16550 over the years and the newest parts behave a bit differently than the classic NS16550AFN that is considered the benchmark for functionality. COMTEST appears to turn a blind eye to the differences within the National product line and reports no errors on the National parts (except for the original 16550) even when there are official erratas that describe bugs in the A, B and C revisions of the parts, so this bias in COMTEST must be taken into account. It is important to understand that a simple count of differences from COMTEST does not reveal a lot about what differences are important and which are not. For example, about half of the differences reported in the two modems listed above that have internal UARTs were caused by the clone UARTs not supporting five- and six-bit character modes. The real 16550, 16450, and 8250 UARTs all support these modes and COMTEST checks the functionality of these modes so over fifty differences are reported. However, almost no modern modem supports five- or six-bit characters, particularly those with error-correction and compression capabilities. This means that the differences related to five- and six-bit character modes can be discounted. Many of the differences COMTEST reports have to do with timing. In many of the clone designs, when the host reads from one port, the status bits in some other port may not update in the same amount of time (some faster, some slower) as a real NS16550AFN and COMTEST looks for these differences. This means that the number of differences can be misleading in that one device may only have one or two differences but they are extremely serious, and some other device that updates the status registers faster or slower than the reference part (that would probably never affect the operation of a properly written driver) could have dozens of differences reported. COMTEST can be used as a screening tool to alert the administrator to the presence of potentially incompatible components that might cause problems or have to be handled as a special case. If you run COMTEST on a 16550 that is in a modem or a modem is attached to the serial port, you need to first issue a ATE0&W command to the modem so that the modem will not echo any of the test characters. If you forget to do this, COMTEST will report at least this one difference: Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61 8250/16450/16550 Registers The 8250/16450/16550 UART occupies eight contiguous I/O port addresses. In the IBM PC, there are two defined locations for these eight ports and they are known collectively as COM1 and COM2. The makers of PC-clones and add-on cards have created two additional areas known as COM3 and COM4, but these extra COM ports conflict with other hardware on some systems. The most common conflict is with video adapters that provide IBM 8514 emulation. COM1 is located from 0x3f8 to 0x3ff and normally uses IRQ 4. COM2 is located from 0x2f8 to 0x2ff and normally uses IRQ 3. COM3 is located from 0x3e8 to 0x3ef and has no standardized IRQ. COM4 is located from 0x2e8 to 0x2ef and has no standardized IRQ. A description of the I/O ports of the 8250/16450/16550 UART is provided below. I/O Port Access Allowed Description +0x00 write (DLAB==0) Transmit Holding Register (THR).Information written to this port are treated as data words and will be transmitted by the UART. +0x00 read (DLAB==0) Receive Buffer Register (RBR).Any data words received by the UART form the serial link are accessed by the host by reading this port. +0x00 write/read (DLAB==1) Divisor Latch LSB (DLL)This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 0 thru 7 of the divisor. +0x01 write/read (DLAB==1) Divisor Latch MSB (DLH)This value will be divided from the master input clock (in the IBM PC, the master clock is 1.8432MHz) and the resulting clock will determine the baud rate of the UART. This register holds bits 8 thru 15 of the divisor. +0x01 write/read (DLAB==0) Interrupt Enable Register (IER)The 8250/16450/16550 UART classifies events into one of four categories. Each category can be configured to generate an interrupt when any of the events occurs. The 8250/16450/16550 UART generates a single external interrupt signal regardless of how many events in the enabled categories have occurred. It is up to the host processor to respond to the interrupt and then poll the enabled interrupt categories (usually all categories have interrupts enabled) to determine the true cause(s) of the interrupt. Bit 7 Reserved, always 0. Bit 6 Reserved, always 0. Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 Enable Modem Status Interrupt (EDSSI). Setting this bit to "1" allows the UART to generate an interrupt when a change occurs on one or more of the status lines. Bit 2 Enable Receiver Line Status Interrupt (ELSI) Setting this bit to "1" causes the UART to generate an interrupt when the an error (or a BREAK signal) has been detected in the incoming data. Bit 1 Enable Transmitter Holding Register Empty Interrupt (ETBEI) Setting this bit to "1" causes the UART to generate an interrupt when the UART has room for one or more additional characters that are to be transmitted. Bit 0 Enable Received Data Available Interrupt (ERBFI) Setting this bit to "1" causes the UART to generate an interrupt when the UART has received enough characters to exceed the trigger level of the FIFO, or the FIFO timer has expired (stale data), or a single character has been received when the FIFO is disabled. +0x02 write FIFO Control Register (FCR) (This port does not exist on the 8250 and 16450 UART.) Bit 7 Receiver Trigger Bit #1 Bit 6 Receiver Trigger Bit #0These two bits control at what point the receiver is to generate an interrupt when the FIFO is active. 7 6 How many words are received before an interrupt is generated 0 0 1 0 1 4 1 0 8 1 1 14 Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 DMA Mode Select. If Bit 0 is set to "1" (FIFOs enabled), setting this bit changes the operation of the -RXRDY and -TXRDY signals from Mode 0 to Mode 1. Bit 2 Transmit FIFO Reset. When a "1" is written to this bit, the contents of the FIFO are discarded. Any word currently being transmitted will be sent intact. This function is useful in aborting transfers. Bit 1 Receiver FIFO Reset. When a "1" is written to this bit, the contents of the FIFO are discarded. Any word currently being assembled in the shift register will be received intact. Bit 0 16550 FIFO Enable. When set, both the transmit and receive FIFOs are enabled. Any contents in the holding register, shift registers or FIFOs are lost when FIFOs are enabled or disabled. +0x02 read Interrupt Identification Register Bit 7 FIFOs enabled. On the 8250/16450 UART, this bit is zero. Bit 6 FIFOs enabled. On the 8250/16450 UART, this bit is zero. Bit 5 Reserved, always 0. Bit 4 Reserved, always 0. Bit 3 Interrupt ID Bit #2. On the 8250/16450 UART, this bit is zero. Bit 2 Interrupt ID Bit #1 Bit 1 Interrupt ID Bit #0.These three bits combine to report the category of event that caused the interrupt that is in progress. These categories have priorities, so if multiple categories of events occur at the same time, the UART will report the more important events first and the host must resolve the events in the order they are reported. All events that caused the current interrupt must be resolved before any new interrupts will be generated. (This is a limitation of the PC architecture.) 2 1 0 Priority Description 0 1 1 First Received Error (OE, PE, BI, or FE) 0 1 0 Second Received Data Available 1 1 0 Second Trigger level identification (Stale data in receive buffer) 0 0 1 Third Transmitter has room for more words (THRE) 0 0 0 Fourth Modem Status Change (-CTS, -DSR, -RI, or -DCD) Bit 0 Interrupt Pending Bit. If this bit is set to "0", then at least one interrupt is pending. +0x03 write/read Line Control Register (LCR) Bit 7 Divisor Latch Access Bit (DLAB). When set, access to the data transmit/receive register (THR/RBR) and the Interrupt Enable Register (IER) is disabled. Any access to these ports is now redirected to the Divisor Latch Registers. Setting this bit, loading the Divisor Registers, and clearing DLAB should be done with interrupts disabled. Bit 6 Set Break. When set to "1", the transmitter begins to transmit continuous Spacing until this bit is set to "0". This overrides any bits of characters that are being transmitted. Bit 5 Stick Parity. When parity is enabled, setting this bit causes parity to always be "1" or "0", based on the value of Bit 4. Bit 4 Even Parity Select (EPS). When parity is enabled and Bit 5 is "0", setting this bit causes even parity to be transmitted and expected. Otherwise, odd parity is used. Bit 3 Parity Enable (PEN). When set to "1", a parity bit is inserted between the last bit of the data and the Stop Bit. The UART will also expect parity to be present in the received data. Bit 2 Number of Stop Bits (STB). If set to "1" and using 5-bit data words, 1.5 Stop Bits are transmitted and expected in each data word. For 6, 7 and 8-bit data words, 2 Stop Bits are transmitted and expected. When this bit is set to "0", one Stop Bit is used on each data word. Bit 1 Word Length Select Bit #1 (WLSB1) Bit 0 Word Length Select Bit #0 (WLSB0) Together these bits specify the number of bits in each data word. 1 0 Word Length 0 0 5 Data Bits 0 1 6 Data Bits 1 0 7 Data Bits 1 1 8 Data Bits +0x04 write/read Modem Control Register (MCR) Bit 7 Reserved, always 0. Bit 6 Reserved, always 0. Bit 5 Reserved, always 0. Bit 4 Loop-Back Enable. When set to "1", the UART transmitter and receiver are internally connected together to allow diagnostic operations. In addition, the UART modem control outputs are connected to the UART modem control inputs. CTS is connected to RTS, DTR is connected to DSR, OUT1 is connected to RI, and OUT 2 is connected to DCD. Bit 3 OUT 2. An auxiliary output that the host processor may set high or low. In the IBM PC serial adapter (and most clones), OUT 2 is used to tri-state (disable) the interrupt signal from the 8250/16450/16550 UART. Bit 2 OUT 1. An auxiliary output that the host processor may set high or low. This output is not used on the IBM PC serial adapter. Bit 1 Request to Send (RTS). When set to "1", the output of the UART -RTS line is Low (Active). Bit 0 Data Terminal Ready (DTR). When set to "1", the output of the UART -DTR line is Low (Active). +0x05 write/read Line Status Register (LSR) Bit 7 Error in Receiver FIFO. On the 8250/16450 UART, this bit is zero. This bit is set to "1" when any of the bytes in the FIFO have one or more of the following error conditions: PE, FE, or BI. Bit 6 Transmitter Empty (TEMT). When set to "1", there are no words remaining in the transmit FIFO or the transmit shift register. The transmitter is completely idle. Bit 5 Transmitter Holding Register Empty (THRE). When set to "1", the FIFO (or holding register) now has room for at least one additional word to transmit. The transmitter may still be transmitting when this bit is set to "1". Bit 4 Break Interrupt (BI). The receiver has detected a Break signal. Bit 3 Framing Error (FE). A Start Bit was detected but the Stop Bit did not appear at the expected time. The received word is probably garbled. Bit 2 Parity Error (PE). The parity bit was incorrect for the word received. Bit 1 Overrun Error (OE). A new word was received and there was no room in the receive buffer. The newly-arrived word in the shift register is discarded. On 8250/16450 UARTs, the word in the holding register is discarded and the newly- arrived word is put in the holding register. Bit 0 Data Ready (DR) One or more words are in the receive FIFO that the host may read. A word must be completely received and moved from the shift register into the FIFO (or holding register for 8250/16450 designs) before this bit is set. +0x06 write/read Modem Status Register (MSR) Bit 7 Data Carrier Detect (DCD). Reflects the state of the DCD line on the UART. Bit 6 Ring Indicator (RI). Reflects the state of the RI line on the UART. Bit 5 Data Set Ready (DSR). Reflects the state of the DSR line on the UART. Bit 4 Clear To Send (CTS). Reflects the state of the CTS line on the UART. Bit 3 Delta Data Carrier Detect (DDCD). Set to "1" if the -DCD line has changed state one more time since the last time the MSR was read by the host. Bit 2 Trailing Edge Ring Indicator (TERI). Set to "1" if the -RI line has had a low to high transition since the last time the MSR was read by the host. Bit 1 Delta Data Set Ready (DDSR). Set to "1" if the -DSR line has changed state one more time since the last time the MSR was read by the host. Bit 0 Delta Clear To Send (DCTS). Set to "1" if the -CTS line has changed state one more time since the last time the MSR was read by the host. +0x07 write/read Scratch Register (SCR). This register performs no function in the UART. Any value can be written by the host to this location and read by the host later on. Beyond the 16550A UART Although National Semiconductor has not offered any components compatible with the 16550 that provide additional features, various other vendors have. Some of these components are described below. It should be understood that to effectively utilize these improvements, drivers may have to be provided by the chip vendor since most of the popular operating systems do not support features beyond those provided by the 16550. ST16650 By default this part is similar to the NS16550A, but an extended 32-byte send and receive buffer can be optionally enabled. Made by StarTech. TIL16660 By default this part behaves similar to the NS16550A, but an extended 64-byte send and receive buffer can be optionally enabled. Made by Texas Instruments. Hayes ESP This proprietary plug-in card contains a 2048-byte send and receive buffer, and supports data rates to 230.4Kbit/sec. Made by Hayes. In addition to these dumb UARTs, many vendors produce intelligent serial communication boards. This type of design usually provides a microprocessor that interfaces with several UARTs, processes and buffers the data, and then alerts the main PC processor when necessary. Because the UARTs are not directly accessed by the PC processor in this type of communication system, it is not necessary for the vendor to use UARTs that are compatible with the 8250, 16450, or the 16550 UART. This leaves the designer free to components that may have better performance characteristics. Configuring the <devicename>sio</devicename> driver The sio driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. Several multiport cards are supported as well. See the &man.sio.4; manual page for detailed technical documentation. Digi International (DigiBoard) PC/8 Contributed by &a.awebster;. 26 August 1995. Here is a config snippet from a machine with a Digi International PC/8 with 16550. It has 8 modems connected to these 8 lines, and they work just great. Do not forget to add options COM_MULTIPORT or it will not work very well! device sio4 at isa? port 0x100 flags 0xb05 device sio5 at isa? port 0x108 flags 0xb05 device sio6 at isa? port 0x110 flags 0xb05 device sio7 at isa? port 0x118 flags 0xb05 device sio8 at isa? port 0x120 flags 0xb05 device sio9 at isa? port 0x128 flags 0xb05 device sio10 at isa? port 0x130 flags 0xb05 device sio11 at isa? port 0x138 flags 0xb05 irq 9 The trick in setting this up is that the MSB of the flags represent the last SIO port, in this case 11 so flags are 0xb05. Boca 16 Contributed by &a.whiteside;. 26 August 1995. The procedures to make a Boca 16 port board with FreeBSD are pretty straightforward, but you will need a couple things to make it work: You either need the kernel sources installed so you can recompile the necessary options or you will need someone else to compile it for you. The 2.0.5 default kernel does not come with multiport support enabled and you will need to add a device entry for each port anyways. Two, you will need to know the interrupt and IO setting for your Boca Board so you can set these options properly in the kernel. One important note — the actual UART chips for the Boca 16 are in the connector box, not on the internal board itself. So if you have it unplugged, probes of those ports will fail. I have never tested booting with the box unplugged and plugging it back in, and I suggest you do not either. If you do not already have a custom kernel configuration file set up, refer to Kernel Configuration chapter of the FreeBSD Handbook for general procedures. The following are the specifics for the Boca 16 board and assume you are using the kernel name MYKERNEL and editing with vi. Add the line options COM_MULTIPORT to the config file. Where the current device sion lines are, you will need to add 16 more devices. The following example is for a Boca Board with an interrupt of 3, and a base IO address 100h. The IO address for Each port is +8 hexadecimal from the previous port, thus the 100h, 108h, 110h... addresses. device sio1 at isa? port 0x100 flags 0x1005 device sio2 at isa? port 0x108 flags 0x1005 device sio3 at isa? port 0x110 flags 0x1005 device sio4 at isa? port 0x118 flags 0x1005 … device sio15 at isa? port 0x170 flags 0x1005 device sio16 at isa? port 0x178 flags 0x1005 irq 3 The flags entry must be changed from this example unless you are using the exact same sio assignments. Flags are set according to 0xMYY where M indicates the minor number of the master port (the last port on a Boca 16) and YY indicates if FIFO is enabled or disabled(enabled), IRQ sharing is used(yes) and if there is an AST/4 compatible IRQ control register(no). In this example, flags 0x1005 indicates that the master port is sio16. If I added another board and assigned sio17 through sio28, the flags for all 16 ports on that board would be 0x1C05, where 1C indicates the minor number of the master port. Do not change the 05 setting. Save and complete the kernel configuration, recompile, install and reboot. Presuming you have successfully installed the recompiled kernel and have it set to the correct address and IRQ, your boot message should indicate the successful probe of the Boca ports as follows: (obviously the sio numbers, IO and IRQ could be different) sio1 at 0x100-0x107 flags 0x1005 on isa sio1: type 16550A (multiport) sio2 at 0x108-0x10f flags 0x1005 on isa sio2: type 16550A (multiport) sio3 at 0x110-0x117 flags 0x1005 on isa sio3: type 16550A (multiport) sio4 at 0x118-0x11f flags 0x1005 on isa sio4: type 16550A (multiport) sio5 at 0x120-0x127 flags 0x1005 on isa sio5: type 16550A (multiport) sio6 at 0x128-0x12f flags 0x1005 on isa sio6: type 16550A (multiport) sio7 at 0x130-0x137 flags 0x1005 on isa sio7: type 16550A (multiport) sio8 at 0x138-0x13f flags 0x1005 on isa sio8: type 16550A (multiport) sio9 at 0x140-0x147 flags 0x1005 on isa sio9: type 16550A (multiport) sio10 at 0x148-0x14f flags 0x1005 on isa sio10: type 16550A (multiport) sio11 at 0x150-0x157 flags 0x1005 on isa sio11: type 16550A (multiport) sio12 at 0x158-0x15f flags 0x1005 on isa sio12: type 16550A (multiport) sio13 at 0x160-0x167 flags 0x1005 on isa sio13: type 16550A (multiport) sio14 at 0x168-0x16f flags 0x1005 on isa sio14: type 16550A (multiport) sio15 at 0x170-0x177 flags 0x1005 on isa sio15: type 16550A (multiport) sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa sio16: type 16550A (multiport master) If the messages go by too fast to see, &prompt.root; dmesg | more will show you the boot messages. Next, appropriate entries in /dev for the devices must be made using the /dev/MAKEDEV script. This step can be omitted if you are running FreeBSD 5.X with a kernel that has &man.devfs.5; support compiled in. If you do need to create the /dev entries, run the following as root: &prompt.root; cd /dev &prompt.root; ./MAKEDEV tty1 &prompt.root; ./MAKEDEV cua1 (everything in between) &prompt.root; ./MAKEDEV ttyg &prompt.root; ./MAKEDEV cuag If you do not want or need call-out devices for some reason, you can dispense with making the cua* devices. If you want a quick and sloppy way to make sure the devices are working, you can simply plug a modem into each port and (as root) &prompt.root; echo at > ttyd* for each device you have made. You should see the RX lights flash for each working port. Support for Cheap Multi-UART Cards Contributed by Helge Oldach hmo@sep.hamburg.com, September 1999 Ever wondered about FreeBSD support for your 20$ multi-I/O card with two (or more) COM ports, sharing IRQs? Here is how: Usually the only option to support these kind of boards is to use a distinct IRQ for each port. For example, if your CPU board has an on-board COM1 port (aka sio0–I/O address 0x3F8 and IRQ 4) and you have an extension board with two UARTs, you will commonly need to configure them as COM2 (aka sio1–I/O address 0x2F8 and IRQ 3), and the third port (aka sio2) as I/O 0x3E8 and IRQ 5. Obviously this is a waste of IRQ resources, as it should be basically possible to run both extension board ports using a single IRQ with the COM_MULTIPORT configuration described in the previous sections. Such cheap I/O boards commonly have a 4 by 3 jumper matrix for the COM ports, similar to the following: o o o * Port A | o * o * Port B | o * o o IRQ 2 3 4 5 Shown here is port A wired for IRQ 5 and port B wired for IRQ 3. The IRQ columns on your specific board may vary—other boards may supply jumpers for IRQs 3, 4, 5, and 7 instead. One could conclude that wiring both ports for IRQ 3 using a handcrafted wire-made jumper covering all three connection points in the IRQ 3 column would solve the issue, but no. You cannot duplicate IRQ 3 because the output drivers of each UART are wired in a totem pole fashion, so if one of the UARTs drives IRQ 3, the output signal will not be what you would expect. Depending on the implementation of the extension board or your motherboard, the IRQ 3 line will continuously stay up, or always stay low. You need to decouple the IRQ drivers for the two UARTs, so that the IRQ line of the board only goes up if (and only if) one of the UARTs asserts a IRQ, and stays low otherwise. The solution was proposed by Joerg Wunsch j@ida.interface-business.de: To solder up a wired-or consisting of two diodes (Germanium or Schottky-types strongly preferred) and a 1 kOhm resistor. Here is the schematic, starting from the 4 by 3 jumper field above: Diode +---------->|-------+ / | o * o o | 1 kOhm Port A +----|######|-------+ o * o o | | Port B `-------------------+ ==+== o * o o | Ground \ | +--------->|-------+ IRQ 2 3 4 5 Diode The cathodes of the diodes are connected to a common point, together with a 1 kOhm pull-down resistor. It is essential to connect the resistor to ground to avoid floating of the IRQ line on the bus. Now we are ready to configure a kernel. Staying with this example, we would configure: # standard on-board COM1 port device sio0 at isa? port "IO_COM1" flags 0x10 # patched-up multi-I/O extension board options COM_MULTIPORT device sio1 at isa? port "IO_COM2" flags 0x205 device sio2 at isa? port "IO_COM3" flags 0x205 irq 3 Note that the flags setting for sio1 and sio2 is truly essential; refer to &man.sio.4; for details. (Generally, the 2 in the "flags" attribute refers to sio2 which holds the IRQ, and you surely want a 5 low nibble.) With kernel verbose mode turned on this should yield something similar to this: sio0: irq maps: 0x1 0x11 0x1 0x1 sio0 at 0x3f8-0x3ff irq 4 flags 0x10 on isa sio0: type 16550A sio1: irq maps: 0x1 0x9 0x1 0x1 sio1 at 0x2f8-0x2ff flags 0x205 on isa sio1: type 16550A (multiport) sio2: irq maps: 0x1 0x9 0x1 0x1 sio2 at 0x3e8-0x3ef irq 3 flags 0x205 on isa sio2: type 16550A (multiport master) Though /sys/i386/isa/sio.c is somewhat cryptic with its use of the irq maps array above, the basic idea is that you observe 0x1 in the first, third, and fourth place. This means that the corresponding IRQ was set upon output and cleared after, which is just what we would expect. If your kernel does not display this behavior, most likely there is something wrong with your wiring. Configuring the <devicename>cy</devicename> driver Contributed by Alex Nash. 6 June 1996. The Cyclades multiport cards are based on the cy driver instead of the usual sio driver used by other multiport cards. Configuration is a simple matter of: Add the cy device to your kernel configuration (note that your irq and iomem settings may differ). device cy0 at isa? irq 10 iomem 0xd4000 iosiz 0x2000 Rebuild and install the new kernel. Make the device nodes by typing (the following example assumes an 8-port board) You can omit this part if you are running FreeBSD 5.X with &man.devfs.5;. : &prompt.root; cd /dev &prompt.root; for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done If appropriate, add dialup entries to /etc/ttys by duplicating serial device (ttyd) entries and using ttyc in place of ttyd. For example: ttyc0 "/usr/libexec/getty std.38400" unknown on insecure ttyc1 "/usr/libexec/getty std.38400" unknown on insecure ttyc2 "/usr/libexec/getty std.38400" unknown on insecure … ttyc7 "/usr/libexec/getty std.38400" unknown on insecure Reboot with the new kernel. Configuring the <devicename>si</devicename> driver Contributed by &a.nsayer;. 25 March 1998. The Specialix SI/XIO and SX multiport cards use the si driver. A single machine can have up to 4 host cards. The following host cards are supported: ISA SI/XIO host card (2 versions) EISA SI/XIO host card PCI SI/XIO host card ISA SX host card PCI SX host card Although the SX and SI/XIO host cards look markedly different, their functionality are basically the same. The host cards do not use I/O locations, but instead require a 32K chunk of memory. The factory configuration for ISA cards places this at 0xd0000-0xd7fff. They also require an IRQ. PCI cards will, of course, auto-configure themselves. You can attach up to 4 external modules to each host card. The external modules contain either 4 or 8 serial ports. They come in the following varieties: SI 4 or 8 port modules. Up to 57600 bps on each port supported. XIO 8 port modules. Up to 115200 bps on each port supported. One type of XIO module has 7 serial and 1 parallel port. SXDC 8 port modules. Up to 921600 bps on each port supported. Like XIO, a module is available with one parallel port as well. To configure an ISA host card, add the following line to your kernel configuration file, changing the numbers as appropriate: device si0 at isa? iomem 0xd0000 irq 11 Valid IRQ numbers are 9, 10, 11, 12 and 15 for SX ISA host cards and 11, 12 and 15 for SI/XIO ISA host cards. To configure an EISA or PCI host card, use this line: device si0 After adding the configuration entry, rebuild and install your new kernel. The following step, is not necessary if you are using &man.devfs.5; in FreeBSD 5.X. After rebooting with the new kernel, you need to make the device nodes in /dev. The MAKEDEV script will take care of this for you. Count how many total ports you have and type: &prompt.root; cd /dev &prompt.root; ./MAKEDEV ttyAnn cuaAnn (where nn is the number of ports) If you want login prompts to appear on these ports, you will need to add lines like this to /etc/ttys: ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure Change the terminal type as appropriate. For modems, dialup or unknown is fine.
diff --git a/en_US.ISO8859-1/articles/solid-state/article.sgml b/en_US.ISO8859-1/articles/solid-state/article.sgml index dc2bfe6db6..cff6136296 100644 --- a/en_US.ISO8859-1/articles/solid-state/article.sgml +++ b/en_US.ISO8859-1/articles/solid-state/article.sgml @@ -1,638 +1,635 @@ -%man; + +%articles.ent; - - -%trademarks; ]>
FreeBSD and Solid State Devices John Kozubik
john@kozubik.com
 $FreeBSD$ 2001 The FreeBSD Documentation Project &tm-attrib.freebsd; &tm-attrib.m-systems; &tm-attrib.general; &legalnotice; This article covers the use of solid state disk devices in FreeBSD to create embedded systems. Embedded systems have the advantage of increased stability due to the lack of integral moving parts (hard drives). Account must be taken, however, for the generally low disk space available in the system and the durability of the storage medium. Specific topics to be covered include the types and attributes of solid state media suitable for disk use in FreeBSD, kernel options that are of interest in such an environment, the rc.diskless mechanisms that automate the initialization of such systems and the need for read-only filesystems, and building filesystems from scratch. The article will conclude with some general strategies for small and read-only FreeBSD environments. Solid State Disk Devices The scope of this article will be limited to solid state disk devices made from flash memory. Flash memory is a solid state memory (no moving parts) that is non-volatile (the memory maintains data even after all power sources have been disconnected). Flash memory can withstand tremendous physical shock and is reasonably fast (the flash memory solutions covered in this article are slightly slower than a EIDE hard disk for write operations, and much faster for read operations). One very important aspect of flash memory, the ramifications of which will be discussed later in this article, is that each sector has a limited rewrite capacity. You can only write, erase, and write again to a sector of flash memory a certain number of times before the sector becomes permanently unusable. Although many flash memory products automatically map bad blocks, and although some even distribute write operations evenly throughout the unit, the fact remains that there exists a limit to the amount of writing that can be done to the device. Competitive units have between 1,000,000 and 10,000,000 writes per sector in their specification. This figure varies due to the temperature of the environment. Specifically, we will be discussing ATA compatible compact-flash units and the M-Systems &diskonchip; flash memory unit. ATA compatible compact-flash cards are quite popular as storage media for digital cameras. Of particular interest is the fact that they pin out directly to the IDE bus and are compatible with the ATA command set. Therefore, with a very simple and low-cost adaptor, these devices can be attached directly to an IDE bus in a computer. Once implemented in this manner, operating systems such as FreeBSD see the device as a normal hard disk (albeit small). The M-Systems &diskonchip; product is based on the same underlying flash memory technology as ATA compatible compact-flash cards, but resides in a DIP form factor and is not ATA compatible. To use such a device, not only must you install it on a motherboard that has a &diskonchip; socket, you must also build the `fla` driver into any FreeBSD kernel you wish to use it with. Further, there is critical, manufacturer-specific data residing in the boot sector of this device, so you must take care not to install the FreeBSD (or any other) boot loader when using this. Other solid state disk solutions do exist, but their expense, obscurity, and relative unease of use places them beyond the scope of this article. Kernel Options A few kernel options are of specific interest to those creating an embedded FreeBSD system. First, all embedded FreeBSD systems that use flash memory as system disk will be interested in memory disks and memory filesystems. Because of the limited number of writes that can be done to flash memory, the disk and the filesystems on the disk will most likely be mounted read-only. In this environment, filesystems such as /tmp and /var are mounted as memory filesystems to allow the system to create logs and update counters and temporary files. Memory filesystems are a critical component to a successful solid state FreeBSD implementation. You should make sure the following lines exist in your kernel configuration file: options MFS # Memory Filesystem options MD_ROOT # md device usable as a potential root device pseudo-device md # memory disk Second, if you will be using the M-Systems &diskonchip; product, you must also include this line: device fla0 at isa? <filename>rc.diskless</filename> and Read-Only Filesystems The post-boot initialization of an embedded FreeBSD system is controlled by /etc/rc.diskless2 (/etc/rc.diskless1 is for BOOTP diskless boot). This initialization script is invoked by placing a line in /etc/rc.conf as follows: diskless_mount=/etc/rc.diskless2 rc.diskless2 mounts /var as a memory filesystem, makes a configurable list of directories in /var with the &man.mkdir.1; command, changes modes on some of those directories, and extracts a list of device entries to copy to a writable (again, a memory filesystem) /dev partition. In the execution of /etc/rc.diskless2, one other rc.conf variable comes into play - varsize. The /etc/rc.diskless2 file creates a /var partition based on the value of this variable in rc.conf: varsize=8192 Remember that this value is in sectors. The creation of the /dev partition by /etc/rc.diskless2, however, is governed by a hard-coded value of 4096 sectors. It is trivial to change this entry in the /etc/rc.diskless2 file itself, although you should not need more space than that for /dev. It is important to remember that the /etc/rc.diskless2 script assumes that you have already removed your conventional /tmp partition and replaced it with a symbolic link to /var/tmp. Because tmp is one of the directories created in /var by the /etc/rc.diskless2 script, and because /var is a memory filesystem (which is mounted read-write), /tmp will now be a directory that is read-write as well. The fact that /var and /dev are read-write filesystems is an important distinction, as the / partition (and any other partitions you may have on your flash media) should be mounted read-only. Remember that in we detailed the limitations of flash memory - specifically the limited write capability. The importance of not mounting filesystems on flash media read-write, and the importance of not using a swap file, cannot be overstated. A swap file on a busy system can burn through a piece of flash media in less than one year. Heavy logging or temporary file creation and destruction can do the same. Therefore, in addition to removing the swap and /proc entries from your /etc/fstab file, you should also change the Options field for each filesystem to ro as follows: # Device Mountpoint FStype Options Dump Pass# /dev/ad0s1a / ufs ro 1 1 A few applications in the average system will immediately begin to fail as a result of this change. For instance, ports will not install from the ports tree because the /var/db/port.mkversion file does not exist. cron will not run properly as a result of missing cron tabs in the /var created by /etc/rc.diskless2, and syslog and dhcp will encounter problems as well as a result of the read-only filesystem and missing items in the /var that /etc/rc.diskless2 has created. These are only temporary problems though, and are addressed, along with solutions to the execution of other common software packages in . An important thing to remember is that a filesystem that was mounted read-only with /etc/fstab can be made read-write at any time by issuing the command: &prompt.root; /sbin/mount -uw partition and can be toggled back to read-only with the command: &prompt.root; /sbin/mount -ur partition Building a File System From Scratch Because ATA compatible compact-flash cards are seen by FreeBSD as normal IDE hard drives, as is a M-Systems &diskonchip; product (when you are running a kernel with the fla driver built in) you could theoretically install FreeBSD from the network using the kern and mfsroot floppies or from a CD. Other than the fact that you should not write a boot-loader of any kind to the M-Systems device, no special instructions are needed. However, even a small installation of FreeBSD using normal installation procedures can produce a system in size of greater than 200 megabytes. Because most people will be using smaller flash memory devices (128 megabytes is considered fairly large - 32 or even 16 megabytes is common) an installation using normal mechanisms is not possible—there is simply not enough disk space for even the smallest of conventional installations. The easiest way to overcome this space limitation is to install FreeBSD using conventional means to a normal hard disk. After the installation is complete, pare down the operating system to a size that will fit onto your flash media, then tar the entire filesystem. The following steps will guide you through the process of preparing a piece of flash memory for your tarred filesystem. Remember, because a normal installation is not being performed, operations such as partitioning, labeling, file-system creation, etc. need to be performed by hand. In addition to the kern and mfsroot floppy disks, you will also need to use the fixit floppy. If you are using a M-Systems &diskonchip;, the kernel on your kern floppy must have the fla option detailed in compiled into it. Please see for instructions on creating a new kernel for kern.flp. Partitioning your flash media device After booting with the kern and mfsroot floppies, choose custom from the installation menu. In the custom installation menu, choose partition. In the partition menu, you should delete all existing partitions using the d key. After deleting all existing partitions, create a partition using the c key and accept the default value for the size of the partition. When asked for the type of the partition, make sure the value is set to 165. Now write this partition table to the disk by pressing the w key (this is a hidden option on this screen). When presented with a menu to choose a boot manager, take care to select None if you are using an M-Systems &diskonchip;. If you are using an ATA compatible compact flash card, you should choose the FreeBSD Boot Manager. Now press the q key to quit the partition menu. You will be shown the boot manager menu once more - repeat the choice you made earlier. Creating filesystems on your flash memory device Exit the custom installation menu, and from the main installation menu choose the fixit option. After entering the fixit environment, enter the following commands: ATA compatible &diskonchip; &prompt.root; mknod /dev/ad0a c 116 0 &prompt.root; mknod /dev/ad0c c 116 2 &prompt.root; disklabel -e /dev/ad0c &prompt.root; mknod /dev/fla0a c 102 0 &prompt.root; mknod /dev/fla0c c 102 2 &prompt.root; disklabel -e /dev/fla0c At this point you will have entered the vi editor under the auspices of the disklabel command. If you are using &diskonchip;, the first step will be to change the type value near the beginning of the file from ESDI to DOC2K. Next, regardless of whether you are using &diskonchip; or ATA compatible compact flash media, you need to add an a: line at the end of the file. This a: line should look like: a: 123456 0 4.2BSD 0 0 Where 123456 is a number that is exactly the same as the number in the existing c: entry for size. Basically you are duplicating the existing c: line as an a: line, making sure that fstype is 4.2BSD. Save the file and exit. ATA compatible &diskonchip; &prompt.root; disklabel -B -r /dev/ad0c &prompt.root; newfs /dev/ad0a &prompt.root; disklabel -B -r /dev/fla0c &prompt.root; newfs /dev/fla0a Placing your filesystem on the flash media Mount the newly prepared flash media: ATA compatible &diskonchip; &prompt.root; mount /dev/ad0a /flash &prompt.root; mount /dev/fla0a /flash Bring this machine up on the network so we may transfer our tar file and explode it onto our flash media filesystem. One example of how to do this is: &prompt.root; ifconfig xl0 192.168.0.10 netmask 255.255.255.0 &prompt.root; route add default 192.168.0.1 Now that the machine is on the network, transfer your tar file. You may be faced with a bit of a dilemma at this point - if your flash memory part is 128 megabytes, for instance, and your tar file is larger than 64 megabytes, you cannot have your tar file on the flash media at the same time as you explode it - you will run out of space. One solution to this problem, if you are using FTP, is to untar the file while it is transferred over FTP. If you perform your transfer in this manner, you will never have the tar file and the tar contents on your disk at the same time: ftp> get tarfile.tar "| tar xvf -" If your tarfile is gzipped, you can accomplish this as well: ftp> get tarfile.tar "| zcat | tar xvf -" After the contents of your tarred filesystem are on your flash memory filesystem, you can unmount the flash memory and reboot: &prompt.root; cd / &prompt.root; umount /flash &prompt.root; exit Assuming that you configured your filesystem correctly when it was built on the normal hard disk (with your filesystems mounted read-only, and with the necessary options compiled into the kernel) you should now be successfully booting your FreeBSD embedded system. Building a <filename>kern.flp</filename> Installation Floppy with the fla Driver This section of the article is relevant only to those using M-Systems &diskonchip; flash media. It is possible that your kern.flp boot floppy does not have a kernel with the fla driver compiled into it necessary for the system to recognize the &diskonchip;. If you have booted off of the installation floppies and are told that no disks are present, then you are probably lacking the fla driver in your kernel. After you have built a kernel with fla support that is smaller than 1.4 megabytes, you can create a custom kern.flp floppy image with it by following these instructions: Obtain an existing kern.flp image file &prompt.root; vnconfig vn0c kern.flp &prompt.root; mount /dev/vn0c /mnt Place your kernel file into /mnt, replacing the existing one &prompt.root; vnconfig -d vn0c Your kern.flp file now has your new kernel on it. System Strategies for Small and Read Only Environments In , it was pointed out that the /var filesystem constructed by /etc/rc.diskless2 and the presence of a read-only root filesystem causes problems with many common software packages used with FreeBSD. In this article, suggestions for successfully running cron, syslog, ports installations, and the Apache web server will be provided. cron In /etc/rc.diskless2 there is a variable named var_dirs. This variable consists of a space-delimited list of directories that will be created inside of /var after it is mounted as a memory filesystem. cron and cron/tabs are not in that list, and without those directories, cron will complain. By inserting cron, cron/tabs, and perhaps even at, and at/jobs as elements of that variable, you will facilitate the running of the &man.cron.8; and &man.at.1; daemons. However, this still does not solve the problem of maintaining cron tabs across reboots. When the system reboots, the /var filesystem that is in memory will disappear and any cron tabs you may have had in it will also disappear. Therefore, one solution would be to create cron tabs for the users that need them, mount your / filesystem as read-write and copy those cron tabs to somewhere safe, like /etc/tabs, then add a line to the end of /etc/rc.diskless2 that copies those crontabs into /var/cron/tabs after that directory has been created during system initialization. You may also need to add a line that changes modes and permissions on the directories you create and the files you copy with /etc/rc.diskless2. syslog syslog.conf specifies the locations of certain log files that exist in /var/log. These files are not created by /etc/rc.diskless2 upon system initialization. Therefore, somewhere in /etc/rc.diskless2, after the section that creates the directories in /var, you will need to add something like this: &prompt.root; touch /var/log/security /var/log/maillog /var/log/cron /var/log/messages &prompt.root; chmod 0644 /var/log/* You will also need to add the log directory to the list of directories that /etc/rc.diskless2 creates. ports installation Before discussing the changes necessary to successfully use the ports tree, a reminder is necessary regarding the read-only nature of your filesystems on the flash media. Since they are read-only, you will need to temporarily mount them read-write using the mount syntax shown in . You should always remount those filesystems read-only when you are done with any maintenance - unnecessary writes to the flash media could considerably shorten its lifespan. To make it possible to enter a ports directory and successfully run make install, it is necessary for the file /var/db/port.mkversion to exist, and that it has a correct date in it. Further, we must create a packages directory on a non-memory filesystem that will keep track of our packages across reboots. Because it is necessary to mount your filesystems as read-write for the installation of a package anyway, it is sensible to assume that an area on the flash media can also be used for package information to be written to. First, create a package database directory. This is normally in /var/db/pkg, but we cannot place it there as it will disappear every time the system is booted. &prompt.root; mkdir /etc/pkg Now, add a line to /etc/rc.diskless2 that links the /etc/pkg directory to /var/db/pkg. An example: &prompt.root; ln -s /etc/pkg /var/db/pkg Add another line in /etc/rc.diskless2 that creates and populates /var/db/port.mkversion &prompt.root; touch /var/db/port.mkversion &prompt.root; chmod 0644 /var/db/port.mkversion &prompt.root; echo 20010412 >> /var/db/port.mkversion where 20010412 is a date that is appropriate for your particular release of FreeBSD Now, any time that you mount your filesystems as read-write and install a package, the make install will work because it finds a suitable /var/db/port.mkversion, and package information will be written successfully to /etc/pkg (because the filesystem will, at that time, be mounted read-write) which will always be available to the operating system as /var/db/pkg. Apache Web Server Apache keeps pid files and logs in apache_install/logs. Since this directory doubtless exists on a read-only filesystem, this will not work. It is necessary to add a new directory to the /etc/rc.diskless2 list of directories to create in /var, to link apache_install/logs to /var/log/apache. It is also necessary to set permissions and ownership on this new directory. First, add the directory log/apache to the list of directories to be created in /etc/rc.diskless2. Second, add these commands to /etc/rc.diskless2 after the directory creation section: &prompt.root; chmod 0774 /var/log/apache &prompt.root; chown nobody:nobody /var/log/apache Finally, remove the existing apache_install/logs directory, and replace it with a link: &prompt.root; rm -rf (apache_install)/logs &prompt.root; ln -s /var/log/apache (apache_install)/logs
diff --git a/en_US.ISO8859-1/articles/storage-devices/article.sgml b/en_US.ISO8859-1/articles/storage-devices/article.sgml index cc7fd0cafa..8f8577925f 100644 --- a/en_US.ISO8859-1/articles/storage-devices/article.sgml +++ b/en_US.ISO8859-1/articles/storage-devices/article.sgml @@ -1,2647 +1,2643 @@ -%man; - -%authors; - -%trademarks; + +%articles.ent; ]>
Storage Devices Wilko Bulte
wilko@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; This article talks about storage devices with FreeBSD. Using ESDI hard disks Copyright © 1995, &a.wilko;. 24 September 1995. ESDI is an acronym that means Enhanced Small Device Interface. It is loosely based on the good old ST506/412 interface originally devised by Seagate Technology, the makers of the first affordable 5.25" winchester disk. The acronym says Enhanced, and rightly so. In the first place the speed of the interface is higher, 10 or 15 Mbits/second instead of the 5 Mbits/second of ST412 interfaced drives. Secondly some higher level commands are added, making the ESDI interface somewhat smarter to the operating system driver writers. It is by no means as smart as SCSI by the way. ESDI is standardized by ANSI. Capacities of the drives are boosted by putting more sectors on each track. Typical is 35 sectors per track, high capacity drives I have seen were up to 54 sectors/track. Although ESDI has been largely obsoleted by IDE and SCSI interfaces, the availability of free or cheap surplus drives makes them ideal for low (or now) budget systems. Concepts of ESDI Physical connections The ESDI interface uses two cables connected to each drive. One cable is a 34 pin flat cable edge connector that carries the command and status signals from the controller to the drive and vice-versa. The command cable is daisy chained between all the drives. So, it forms a bus onto which all drives are connected. The second cable is a 20 pin flat cable edge connector that carries the data to and from the drive. This cable is radially connected, so each drive has its own direct connection to the controller. To the best of my knowledge PC ESDI controllers are limited to using a maximum of 2 drives per controller. This is compatibility feature(?) left over from the WD1003 standard that reserves only a single bit for device addressing. Device addressing On each command cable a maximum of 7 devices and 1 controller can be present. To enable the controller to uniquely identify which drive it addresses, each ESDI device is equipped with jumpers or switches to select the devices address. On PC type controllers the first drive is set to address 0, the second disk to address 1. Always make sure you set each disk to an unique address! So, on a PC with its two drives/controller maximum the first drive is drive 0, the second is drive 1. Termination The daisy chained command cable (the 34 pin cable remember?) needs to be terminated at the last drive on the chain. For this purpose ESDI drives come with a termination resistor network that can be removed or disabled by a jumper when it is not used. So, one and only one drive, the one at the farthest end of the command cable has its terminator installed/enabled. The controller automatically terminates the other end of the cable. Please note that this implies that the controller must be at one end of the cable and not in the middle. Using ESDI disks with FreeBSD Why is ESDI such a pain to get working in the first place? People who tried ESDI disks with FreeBSD are known to have developed a profound sense of frustration. A combination of factors works against you to produce effects that are hard to understand when you have never seen them before. This has also led to the popular legend ESDI and FreeBSD is a plain NO-GO. The following sections try to list all the pitfalls and solutions. ESDI speed variants As briefly mentioned before, ESDI comes in two speed flavors. The older drives and controllers use a 10 Mbits/second data transfer rate. Newer stuff uses 15 Mbits/second. It is not hard to imagine that 15 Mbits/second drive cause problems on controllers laid out for 10 Mbits/second. As always, consult your controller and drive documentation to see if things match. Stay on track Mainstream ESDI drives use 34 to 36 sectors per track. Most (older) controllers cannot handle more than this number of sectors. Newer, higher capacity, drives use higher numbers of sectors per track. For instance, I own a 670 MB drive that has 54 sectors per track. In my case, the controller could not handle this number of sectors. It proved to work well except that it only used 35 sectors on each track. This meant losing a lot of disk space. Once again, check the documentation of your hardware for more info. Going out-of-spec like in the example might or might not work. Give it a try or get another more capable controller. Hard or soft sectoring Most ESDI drives allow hard or soft sectoring to be selected using a jumper. Hard sectoring means that the drive will produce a sector pulse on the start of each new sector. The controller uses this pulse to tell when it should start to write or read. Hard sectoring allows a selection of sector size (normally 256, 512 or 1024 bytes per formatted sector). FreeBSD uses 512 byte sectors. The number of sectors per track also varies while still using the same number of bytes per formatted sector. The number of unformatted bytes per sector varies, dependent on your controller it needs more or less overhead bytes to work correctly. Pushing more sectors on a track of course gives you more usable space, but might give problems if your controller needs more bytes than the drive offers. In case of soft sectoring, the controller itself determines where to start/stop reading or writing. For ESDI hard sectoring is the default (at least on everything I came across). I never felt the urge to try soft sectoring. In general, experiment with sector settings before you install FreeBSD because you need to re-run the low-level format after each change. Low level formatting ESDI drives need to be low level formatted before they are usable. A reformat is needed whenever you figgle with the number of sectors/track jumpers or the physical orientation of the drive (horizontal, vertical). So, first think, then format. The format time must not be underestimated, for big disks it can take hours. After a low level format, a surface scan is done to find and flag bad sectors. Most disks have a manufacturer bad block list listed on a piece of paper or adhesive sticker. In addition, on most disks the list is also written onto the disk. Please use the manufacturer's list. It is much easier to remap a defect now than after FreeBSD is installed. Stay away from low-level formatters that mark all sectors of a track as bad as soon as they find one bad sector. Not only does this waste space, it also and more importantly causes you grief with bad144 (see the section on bad144). Translations Translations, although not exclusively a ESDI-only problem, might give you real trouble. Translations come in multiple flavors. Most of them have in common that they attempt to work around the limitations posed upon disk geometries by the original IBM PC/AT design (thanks IBM!). First of all there is the (in)famous 1024 cylinder limit. For a system to be able to boot, the stuff (whatever operating system) must be in the first 1024 cylinders of a disk. Only 10 bits are available to encode the cylinder number. For the number of sectors the limit is 64 (0-63). When you combine the 1024 cylinder limit with the 16 head limit (also a design feature) you max out at fairly limited disk sizes. To work around this problem, the manufacturers of ESDI PC controllers added a BIOS prom extension on their boards. This BIOS extension handles disk I/O for booting (and for some operating systems all disk I/O) by using translation. For instance, a big drive might be presented to the system as having 32 heads and 64 sectors/track. The result is that the number of cylinders is reduced to something below 1024 and is therefore usable by the system without problems. It is noteworthy to know that FreeBSD does not use the BIOS after its kernel has started. More on this later. A second reason for translations is the fact that most older system BIOSes could only handle drives with 17 sectors per track (the old ST412 standard). Newer system BIOSes usually have a user-defined drive type (in most cases this is drive type 47). Whatever you do to translations after reading this document, keep in mind that if you have multiple operating systems on the same disk, all must use the same translation While on the subject of translations, I have seen one controller type (but there are probably more like this) offer the option to logically split a drive in multiple partitions as a BIOS option. I had select 1 drive == 1 partition because this controller wrote this info onto the disk. On power-up it read the info and presented itself to the system based on the info from the disk. Spare sectoring Most ESDI controllers offer the possibility to remap bad sectors. During/after the low-level format of the disk bad sectors are marked as such, and a replacement sector is put in place (logically of course) of the bad one. In most cases the remapping is done by using N-1 sectors on each track for actual data storage, and sector N itself is the spare sector. N is the total number of sectors physically available on the track. The idea behind this is that the operating system sees a perfect disk without bad sectors. In the case of FreeBSD this concept is not usable. The problem is that the translation from bad to good is performed by the BIOS of the ESDI controller. FreeBSD, being a true 32 bit operating system, does not use the BIOS after it has been booted. Instead, it has device drivers that talk directly to the hardware. So: do not use spare sectoring, bad block remapping or whatever it may be called by the controller manufacturer when you want to use the disk for FreeBSD. Bad block handling The preceding section leaves us with a problem. The controller's bad block handling is not usable and still FreeBSD's filesystems assume perfect media without any flaws. To solve this problem, FreeBSD use the bad144 tool. Bad144 (named after a Digital Equipment standard for bad block handling) scans a FreeBSD slice for bad blocks. Having found these bad blocks, it writes a table with the offending block numbers to the end of the FreeBSD slice. When the disk is in operation, the disk accesses are checked against the table read from the disk. Whenever a block number is requested that is in the bad144 list, a replacement block (also from the end of the FreeBSD slice) is used. In this way, the bad144 replacement scheme presents perfect media to the FreeBSD filesystems. There are a number of potential pitfalls associated with the use of bad144. First of all, the slice cannot have more than 126 bad sectors. If your drive has a high number of bad sectors, you might need to divide it into multiple FreeBSD slices each containing less than 126 bad sectors. Stay away from low-level format programs that mark every sector of a track as bad when they find a flaw on the track. As you can imagine, the 126 limit is quickly reached when the low-level format is done this way. Second, if the slice contains the root filesystem, the slice should be within the 1024 cylinder BIOS limit. During the boot process the bad144 list is read using the BIOS and this only succeeds when the list is within the 1024 cylinder limit. The restriction is not that only the root filesystem must be within the 1024 cylinder limit, but rather the entire slice that contains the root filesystem. Kernel configuration ESDI disks are handled by the same wddriver as IDE and ST412 MFM disks. The wd driver should work for all WD1003 compatible interfaces. Most hardware is jumperable for one of two different I/O address ranges and IRQ lines. This allows you to have two wd type controllers in one system. When your hardware allows non-standard strappings, you can use these with FreeBSD as long as you enter the correct info into the kernel config file. An example from the kernel config file (they live in /sys/i386/conf BTW). # First WD compatible controller controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr disk wd0 at wdc0 drive 0 disk wd1 at wdc0 drive 1 # Second WD compatible controller controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr disk wd2 at wdc1 drive 0 disk wd3 at wdc1 drive 1 Particulars on ESDI hardware Adaptec 2320 controllers I successfully installed FreeBSD onto a ESDI disk controlled by a ACB-2320. No other operating system was present on the disk. To do so I low level formatted the disk using NEFMT.EXE (ftpable from www.adaptec.com) and answered NO to the question whether the disk should be formatted with a spare sector on each track. The BIOS on the ACD-2320 was disabled. I used the free configurable option in the system BIOS to allow the BIOS to boot it. Before using NEFMT.EXE I tried to format the disk using the ACB-2320 BIOS built-in formatter. This proved to be a show stopper, because it did not give me an option to disable spare sectoring. With spare sectoring enabled the FreeBSD installation process broke down on the bad144 run. Please check carefully which ACB-232xy variant you have. The x is either 0 or 2, indicating a controller without or with a floppy controller on board. The y is more interesting. It can either be a blank, a A-8 or a D. A blank indicates a plain 10 Mbits/second controller. An A-8 indicates a 15 Mbits/second controller capable of handling 52 sectors/track. A D means a 15 Mbits/second controller that can also handle drives with > 36 sectors/track (also 52?). All variations should be capable of using 1:1 interleaving. Use 1:1, FreeBSD is fast enough to handle it. Western Digital WD1007 controllers I successfully installed FreeBSD onto a ESDI disk controlled by a WD1007 controller. To be precise, it was a WD1007-WA2. Other variations of the WD1007 do exist. To get it to work, I had to disable the sector translation and the WD1007's onboard BIOS. This implied I could not use the low-level formatter built into this BIOS. Instead, I grabbed WDFMT.EXE from www.wdc.com Running this formatted my drive just fine. Ultrastor U14F controllers According to multiple reports from the net, Ultrastor ESDI boards work OK with FreeBSD. I lack any further info on particular settings. Further reading If you intend to do some serious ESDI hacking, you might want to have the official standard at hand: The latest ANSI X3T10 committee document is: Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] [X3T10/792D Rev 11] On Usenet the newsgroup comp.periphs is a noteworthy place to look for more info. The World Wide Web (WWW) also proves to be a very handy info source: For info on Adaptec ESDI controllers see . For info on Western Digital controllers see . Thanks to... Andrew Gordon for sending me an Adaptec 2320 controller and ESDI disk for testing. What is SCSI? Copyright © 1995, &a.wilko;. July 6, 1996. SCSI is an acronym for Small Computer Systems Interface. It is an ANSI standard that has become one of the leading I/O buses in the computer industry. The foundation of the SCSI standard was laid by Shugart Associates (the same guys that gave the world the first mini floppy disks) when they introduced the SASI bus (Shugart Associates Standard Interface). After some time an industry effort was started to come to a more strict standard allowing devices from different vendors to work together. This effort was recognized in the ANSI SCSI-1 standard. The SCSI-1 standard (approximately 1985) is rapidly becoming obsolete. The current standard is SCSI-2 (see Further reading), with SCSI-3 on the drawing boards. In addition to a physical interconnection standard, SCSI defines a logical (command set) standard to which disk devices must adhere. This standard is called the Common Command Set (CCS) and was developed more or less in parallel with ANSI SCSI-1. SCSI-2 includes the (revised) CCS as part of the standard itself. The commands are dependent on the type of device at hand. It does not make much sense of course to define a Write command for a scanner. The SCSI bus is a parallel bus, which comes in a number of variants. The oldest and most used is an 8 bit wide bus, with single-ended signals, carried on 50 wires. (If you do not know what single-ended means, do not worry, that is what this document is all about.) Modern designs also use 16 bit wide buses, with differential signals. This allows transfer speeds of 20Mbytes/second, on cables lengths of up to 25 meters. SCSI-2 allows a maximum bus width of 32 bits, using an additional cable. Quickly emerging are Ultra SCSI (also called Fast-20) and Ultra2 (also called Fast-40). Fast-20 is 20 million transfers per second (20 Mbytes/sec on a 8 bit bus), Fast-40 is 40 million transfers per second (40 Mbytes/sec on a 8 bit bus). Most hard drives sold today are single-ended Ultra SCSI (8 or 16 bits). Of course the SCSI bus not only has data lines, but also a number of control signals. A very elaborate protocol is part of the standard to allow multiple devices to share the bus in an efficient manner. In SCSI-2, the data is always checked using a separate parity line. In pre-SCSI-2 designs parity was optional. In SCSI-3 even faster bus types are introduced, along with a serial SCSI busses that reduces the cabling overhead and allows a higher maximum bus length. You might see names like SSA and fibre channel in this context. None of the serial buses are currently in widespread use (especially not in the typical FreeBSD environment). For this reason the serial bus types are not discussed any further. As you could have guessed from the description above, SCSI devices are intelligent. They have to be to adhere to the SCSI standard (which is over 2 inches thick BTW). So, for a hard disk drive for instance you do not specify a head/cylinder/sector to address a particular block, but simply the number of the block you want. Elaborate caching schemes, automatic bad block replacement etc are all made possible by this intelligent device approach. On a SCSI bus, each possible pair of devices can communicate. Whether their function allows this is another matter, but the standard does not restrict it. To avoid signal contention, the 2 devices have to arbitrate for the bus before using it. The philosophy of SCSI is to have a standard that allows older-standard devices to work with newer-standard ones. So, an old SCSI-1 device should normally work on a SCSI-2 bus. I say Normally, because it is not absolutely sure that the implementation of an old device follows the (old) standard closely enough to be acceptable on a new bus. Modern devices are usually more well-behaved, because the standardization has become more strict and is better adhered to by the device manufacturers. Generally speaking, the chances of getting a working set of devices on a single bus is better when all the devices are SCSI-2 or newer. This implies that you do not have to dump all your old stuff when you get that shiny 80GB disk: I own a system on which a pre-SCSI-1 disk, a SCSI-2 QIC tape unit, a SCSI-1 helical scan tape unit and 2 SCSI-1 disks work together quite happily. From a performance standpoint you might want to separate your older and newer (=faster) devices however. This is especially advantageous if you have an Ultra160 host adapter where you should separate your U160 devices from the Fast and Wide SCSI-2 devices. Components of SCSI As said before, SCSI devices are smart. The idea is to put the knowledge about intimate hardware details onto the SCSI device itself. In this way, the host system does not have to worry about things like how many heads a hard disks has, or how many tracks there are on a specific tape device. If you are curious, the standard specifies commands with which you can query your devices on their hardware particulars. FreeBSD uses this capability during boot to check out what devices are connected and whether they need any special treatment. The advantage of intelligent devices is obvious: the device drivers on the host can be made in a much more generic fashion, there is no longer a need to change (and qualify!) drivers for every odd new device that is introduced. For cabling and connectors there is a golden rule: get good stuff. With bus speeds going up all the time you will save yourself a lot of grief by using good material. So, gold plated connectors, shielded cabling, sturdy connector hoods with strain reliefs etc are the way to go. Second golden rule: do no use cables longer than necessary. I once spent 3 days hunting down a problem with a flaky machine only to discover that shortening the SCSI bus by 1 meter solved the problem. And the original bus length was well within the SCSI specification. SCSI bus types From an electrical point of view, there are two incompatible bus types: single-ended and differential. This means that there are two different main groups of SCSI devices and controllers, which cannot be mixed on the same bus. It is possible however to use special converter hardware to transform a single-ended bus into a differential one (and vice versa). The differences between the bus types are explained in the next sections. In lots of SCSI related documentation there is a sort of jargon in use to abbreviate the different bus types. A small list: FWD: Fast Wide Differential FND: Fast Narrow Differential SE: Single Ended FN: Fast Narrow etc. With a minor amount of imagination one can usually imagine what is meant. Wide is a bit ambiguous, it can indicate 16 or 32 bit buses. As far as I know, the 32 bit variant is not (yet) in use, so wide normally means 16 bit. Fast means that the timing on the bus is somewhat different, so that on a narrow (8 bit) bus 10 Mbytes/sec are possible instead of 5 Mbytes/sec for slow SCSI. As discussed before, bus speeds of 20 and 40 million transfers/second are also emerging (Fast-20 == Ultra SCSI and Fast-40 == Ultra2 SCSI). The data lines > 8 are only used for data transfers and device addressing. The transfers of commands and status messages etc are only performed on the lowest 8 data lines. The standard allows narrow devices to operate on a wide bus. The usable bus width is negotiated between the devices. You have to watch your device addressing closely when mixing wide and narrow. Single ended buses A single-ended SCSI bus uses signals that are either 5 Volts or 0 Volts (indeed, TTL levels) and are relative to a COMMON ground reference. A singled ended 8 bit SCSI bus has approximately 25 ground lines, who are all tied to a single rail on all devices. A standard single ended bus has a maximum length of 6 meters. If the same bus is used with fast-SCSI devices, the maximum length allowed drops to 3 meters. Fast-SCSI means that instead of 5Mbytes/sec the bus allows 10Mbytes/sec transfers. Fast-20 (Ultra SCSI) and Fast-40 allow for 20 and 40 million transfers/second respectively. So, F20 is 20 Mbytes/second on a 8 bit bus, 40 Mbytes/second on a 16 bit bus etc. For F20 the max bus length is 1.5 meters, for F40 it becomes 0.75 meters. Be aware that F20 is pushing the limits quite a bit, so you will quickly find out if your SCSI bus is electrically sound. If some devices on your bus use fast to communicate your bus must adhere to the length restrictions for fast buses! It is obvious that with the newer fast-SCSI devices the bus length can become a real bottleneck. This is why the differential SCSI bus was introduced in the SCSI-2 standard. For connector pinning and connector types please refer to the SCSI-2 standard (see Further reading) itself, connectors etc are listed there in painstaking detail. Beware of devices using non-standard cabling. For instance Apple uses a 25pin D-type connecter (like the one on serial ports and parallel printers). Considering that the official SCSI bus needs 50 pins you can imagine the use of this connector needs some creative cabling. The reduction of the number of ground wires they used is a bad idea, you better stick to 50 pins cabling in accordance with the SCSI standard. For Fast-20 and 40 do not even think about buses like this. Differential buses A differential SCSI bus has a maximum length of 25 meters. Quite a difference from the 3 meters for a single-ended fast-SCSI bus. The idea behind differential signals is that each bus signal has its own return wire. So, each signal is carried on a (preferably twisted) pair of wires. The voltage difference between these two wires determines whether the signal is asserted or de-asserted. To a certain extent the voltage difference between ground and the signal wire pair is not relevant (do not try 10 kVolts though). It is beyond the scope of this document to explain why this differential idea is so much better. Just accept that electrically seen the use of differential signals gives a much better noise margin. You will normally find differential buses in use for inter-cabinet connections. Because of the lower cost single ended is mostly used for shorter buses like inside cabinets. There is nothing that stops you from using differential stuff with FreeBSD, as long as you use a controller that has device driver support in FreeBSD. As an example, Adaptec marketed the AHA1740 as a single ended board, whereas the AHA1744 was differential. The software interface to the host is identical for both. Terminators Terminators in SCSI terminology are resistor networks that are used to get a correct impedance matching. Impedance matching is important to get clean signals on the bus, without reflections or ringing. If you once made a long distance telephone call on a bad line you probably know what reflections are. With 20Mbytes/sec traveling over your SCSI bus, you do not want signals echoing back. Terminators come in various incarnations, with more or less sophisticated designs. Of course, there are internal and external variants. Many SCSI devices come with a number of sockets in which a number of resistor networks can (must be!) installed. If you remove terminators from a device, carefully store them. You will need them when you ever decide to reconfigure your SCSI bus. There is enough variation in even these simple tiny things to make finding the exact replacement a frustrating business. There are also SCSI devices that have a single jumper to enable or disable a built-in terminator. There are special terminators you can stick onto a flat cable bus. Others look like external connectors, or a connector hood without a cable. So, lots of choice as you can see. There is much debate going on if and when you should switch from simple resistor (passive) terminators to active terminators. Active terminators contain slightly more elaborate circuit to give cleaner bus signals. The general consensus seems to be that the usefulness of active termination increases when you have long buses and/or fast devices. If you ever have problems with your SCSI buses you might consider trying an active terminator. Try to borrow one first, they reputedly are quite expensive. Please keep in mind that terminators for differential and single-ended buses are not identical. You should not mix the two variants. OK, and now where should you install your terminators? This is by far the most misunderstood part of SCSI. And it is by far the simplest. The rule is: every single line on the SCSI bus has 2 (two) terminators, one at each end of the bus. So, two and not one or three or whatever. Do yourself a favor and stick to this rule. It will save you endless grief, because wrong termination has the potential to introduce highly mysterious bugs. (Note the potential here; the nastiest part is that it may or may not work.) A common pitfall is to have an internal (flat) cable in a machine and also an external cable attached to the controller. It seems almost everybody forgets to remove the terminators from the controller. The terminator must now be on the last external device, and not on the controller! In general, every reconfiguration of a SCSI bus must pay attention to this. Termination is to be done on a per-line basis. This means if you have both narrow and wide buses connected to the same host adapter, you need to enable termination on the higher 8 bits of the bus on the adapter (as well as the last devices on each bus, of course). What I did myself is remove all terminators from my SCSI devices and controllers. I own a couple of external terminators, for both the Centronics-type external cabling and for the internal flat cable connectors. This makes reconfiguration much easier. On modern devices, sometimes integrated terminators are used. These things are special purpose integrated circuits that can be enabled or disabled with a control pin. It is not necessary to physically remove them from a device. You may find them on newer host adapters, sometimes they are software configurable, using some sort of setup tool. Some will even auto-detect the cables attached to the connectors and automatically set up the termination as necessary. At any rate, consult your documentation! Terminator power The terminators discussed in the previous chapter need power to operate properly. On the SCSI bus, a line is dedicated to this purpose. So, simple huh? Not so. Each device can provide its own terminator power to the terminator sockets it has on-device. But if you have external terminators, or when the device supplying the terminator power to the SCSI bus line is switched off you are in trouble. The idea is that initiators (these are devices that initiate actions on the bus, a discussion follows) must supply terminator power. All SCSI devices are allowed (but not required) to supply terminator power. To allow for un-powered devices on a bus, the terminator power must be supplied to the bus via a diode. This prevents the backflow of current to un-powered devices. To prevent all kinds of nastiness, the terminator power is usually fused. As you can imagine, fuses might blow. This can, but does not have to, lead to a non functional bus. If multiple devices supply terminator power, a single blown fuse will not put you out of business. A single supplier with a blown fuse certainly will. Clever external terminators sometimes have a LED indication that shows whether terminator power is present. In newer designs auto-restoring fuses that reset themselves after some time are sometimes used. Device addressing Because the SCSI bus is, ehh, a bus there must be a way to distinguish or address the different devices connected to it. This is done by means of the SCSI or target ID. Each device has a unique target ID. You can select the ID to which a device must respond using a set of jumpers, or a dip switch, or something similar. Some SCSI host adapters let you change the target ID from the boot menu. (Yet some others will not let you change the ID from 7.) Consult the documentation of your device for more information. Beware of multiple devices configured to use the same ID. Chaos normally reigns in this case. A pitfall is that one of the devices sharing the same ID sometimes even manages to answer to I/O requests! For an 8 bit bus, a maximum of 8 targets is possible. The maximum is 8 because the selection is done bitwise using the 8 data lines on the bus. For wide buses this increases to the number of data lines (usually 16). A narrow SCSI device can not communicate with a SCSI device with a target ID larger than 7. This means it is generally not a good idea to move your SCSI host adapter's target ID to something higher than 7 (or your CDROM will stop working). The higher the SCSI target ID, the higher the priority the devices has. When it comes to arbitration between devices that want to use the bus at the same time, the device that has the highest SCSI ID will win. This also means that the SCSI host adapter usually uses target ID 7. Note however that the lower 8 IDs have higher priorities than the higher 8 IDs on a wide-SCSI bus. Thus, the order of target IDs is: [7 6 .. 1 0 15 14 .. 9 8] on a wide-SCSI system. (If you are wondering why the lower 8 have higher priority, read the previous paragraph for a hint.) For a further subdivision, the standard allows for Logical Units or LUNs for short. A single target ID may have multiple LUNs. For example, a tape device including a tape changer may have LUN 0 for the tape device itself, and LUN 1 for the tape changer. In this way, the host system can address each of the functional units of the tape changer as desired. Bus layout SCSI buses are linear. So, not shaped like Y-junctions, star topologies, rings, cobwebs or whatever else people might want to invent. One of the most common mistakes is for people with wide-SCSI host adapters to connect devices on all three connecters (external connector, internal wide connector, internal narrow connector). Do not do that. It may appear to work if you are really lucky, but I can almost guarantee that your system will stop functioning at the most unfortunate moment (this is also known as Murphy's law). You might notice that the terminator issue discussed earlier becomes rather hairy if your bus is not linear. Also, if you have more connectors than devices on your internal SCSI cable, make sure you attach devices on connectors on both ends instead of using the connectors in the middle and let one or both ends dangle. This will screw up the termination of the bus. The electrical characteristics, its noise margins and ultimately the reliability of it all are tightly related to linear bus rule. Stick to the linear bus rule! Using SCSI with FreeBSD About translations, BIOSes and magic... As stated before, you should first make sure that you have a electrically sound bus. When you want to use a SCSI disk on your PC as boot disk, you must aware of some quirks related to PC BIOSes. The PC BIOS in its first incarnation used a low level physical interface to the hard disk. So, you had to tell the BIOS (using a setup tool or a BIOS built-in setup) how your disk physically looked like. This involved stating number of heads, number of cylinders, number of sectors per track, obscure things like precompensation and reduced write current cylinder etc. One might be inclined to think that since SCSI disks are smart you can forget about this. Alas, the arcane setup issue is still present today. The system BIOS needs to know how to access your SCSI disk with the head/cyl/sector method in order to load the FreeBSD kernel during boot. The SCSI host adapter or SCSI controller you have put in your AT/EISA/PCI/whatever bus to connect your disk therefore has its own on-board BIOS. During system startup, the SCSI BIOS takes over the hard disk interface routines from the system BIOS. To fool the system BIOS, the system setup is normally set to No hard disk present. Obvious, is it not? The SCSI BIOS itself presents to the system a so called translated drive. This means that a fake drive table is constructed that allows the PC to boot the drive. This translation is often (but not always) done using a pseudo drive with 64 heads and 32 sectors per track. By varying the number of cylinders, the SCSI BIOS adapts to the actual drive size. It is useful to note that 32 * 64 / 2 = the size of your drive in megabytes. The division by 2 is to get from disk blocks that are normally 512 bytes in size to Kbytes. Right. All is well now?! No, it is not. The system BIOS has another quirk you might run into. The number of cylinders of a bootable hard disk cannot be greater than 1024. Using the translation above, this is a show-stopper for disks greater than 1 GB. With disk capacities going up all the time this is causing problems. Fortunately, the solution is simple: just use another translation, e.g. with 128 heads instead of 32. In most cases new SCSI BIOS versions are available to upgrade older SCSI host adapters. Some newer adapters have an option, in the form of a jumper or software setup selection, to switch the translation the SCSI BIOS uses. It is very important that all operating systems on the disk use the same translation to get the right idea about where to find the relevant partitions. So, when installing FreeBSD you must answer any questions about heads/cylinders etc using the translated values your host adapter uses. Failing to observe the translation issue might lead to un-bootable systems or operating systems overwriting each others partitions. Using fdisk you should be able to see all partitions. You might have heard some talk of lying devices? Older FreeBSD kernels used to report the geometry of SCSI disks when booting. An example from one of my systems: aha0 targ 0 lun 0: <MICROP 1588-15MB1057404HSP4> da0: 636MB (1303250 total sec), 1632 cyl, 15 head, 53 sec, bytes/sec 512 Newer kernels usually do not report this information. e.g. (bt0:0:0): "SEAGATE ST41651 7574" type 0 fixed SCSI 2 da0(bt0:0:0): Direct-Access 1350MB (2766300 512 byte sectors) Why has this changed? This info is retrieved from the SCSI disk itself. Newer disks often use a technique called zone bit recording. The idea is that on the outer cylinders of the drive there is more space so more sectors per track can be put on them. This results in disks that have more tracks on outer cylinders than on the inner cylinders and, last but not least, have more capacity. You can imagine that the value reported by the drive when inquiring about the geometry now becomes suspect at best, and nearly always misleading. When asked for a geometry, it is nearly always better to supply the geometry used by the BIOS, or if the BIOS is never going to know about this disk, (e.g. it is not a booting disk) to supply a fictitious geometry that is convenient. SCSI subsystem design FreeBSD uses a layered SCSI subsystem. For each different controller card a device driver is written. This driver knows all the intimate details about the hardware it controls. The driver has a interface to the upper layers of the SCSI subsystem through which it receives its commands and reports back any status. On top of the card drivers there are a number of more generic drivers for a class of devices. More specific: a driver for tape devices (abbreviation: sa, for serial access), magnetic disks (da, for direct access), CDROMs (cd) etc. In case you are wondering where you can find this stuff, it all lives in /sys/cam/scsi. See the man pages in section 4 for more details. The multi level design allows a decoupling of low-level bit banging and more high level stuff. Adding support for another piece of hardware is a much more manageable problem. Kernel configuration Dependent on your hardware, the kernel configuration file must contain one or more lines describing your host adapter(s). This includes I/O addresses, interrupts etc. Consult the manual page for your adapter driver to get more info. Apart from that, check out /sys/i386/conf/LINT for an overview of a kernel config file. LINT contains every possible option you can dream of. It does not imply LINT will actually get you to a working kernel at all. Although it is probably stating the obvious: the kernel config file should reflect your actual hardware setup. So, interrupts, I/O addresses etc must match the kernel config file. During system boot messages will be displayed to indicate whether the configured hardware was actually found. Note that most of the EISA/PCI drivers (namely ahb, ahc, ncr and amd will automatically obtain the correct parameters from the host adapters themselves at boot time; thus, you just need to write, for instance, controller ahc0. An example loosely based on the FreeBSD 2.2.5-Release kernel config file LINT with some added comments (between []): # SCSI host adapters: `aha', `ahb', `aic', `bt', `nca' # # aha: Adaptec 154x # ahb: Adaptec 174x # ahc: Adaptec 274x/284x/294x # aic: Adaptec 152x and sound cards using the Adaptec AIC-6360 (slow!) # amd: AMD 53c974 based SCSI cards (e.g., Tekram DC-390 and 390T) # bt: Most Buslogic controllers # nca: ProAudioSpectrum cards using the NCR 5380 or Trantor T130 # ncr: NCR/Symbios 53c810/815/825/875 etc based SCSI cards # uha: UltraStore 14F and 34F # sea: Seagate ST01/02 8 bit controller (slow!) # wds: Western Digital WD7000 controller (no scatter/gather!). # [For an Adaptec AHA274x/284x/294x/394x etc controller] controller ahc0 [For an NCR/Symbios 53c875 based controller] controller ncr0 [For an Ultrastor adapter] controller uha0 at isa? port "IO_UHA0" bio irq ? drq 5 vector uhaintr # Map SCSI buses to specific SCSI adapters controller scbus0 at ahc0 controller scbus2 at ncr0 controller scbus1 at uha0 # The actual SCSI devices disk da0 at scbus0 target 0 unit 0 [SCSI disk 0 is at scbus 0, LUN 0] disk da1 at scbus0 target 1 [implicit LUN 0 if omitted] disk da2 at scbus1 target 3 [SCSI disk on the uha0] disk da3 at scbus2 target 4 [SCSI disk on the ncr0] tape sa1 at scbus0 target 6 [SCSI tape at target 6] device cd0 at scbus? [the first ever CDROM found, no wiring] The example above tells the kernel to look for a ahc (Adaptec 274x) controller, then for an NCR/Symbios board, and so on. The lines following the controller specifications tell the kernel to configure specific devices but only attach them when they match the target ID and LUN specified on the corresponding bus. Wired down devices get first shot at the unit numbers so the first non wired down device, is allocated the unit number one greater than the highest wired down unit number for that kind of device. So, if you had a SCSI tape at target ID 2 it would be configured as sa2, as the tape at target ID 6 is wired down to unit number 1. Wired down devices need not be found to get their unit number. The unit number for a wired down device is reserved for that device, even if it is turned off at boot time. This allows the device to be turned on and brought on-line at a later time, without rebooting. Notice that a device's unit number has no relationship with its target ID on the SCSI bus. Below is another example of a kernel config file as used by FreeBSD version < 2.0.5. The difference with the first example is that devices are not wired down. Wired down means that you specify which SCSI target belongs to which device. A kernel built to the config file below will attach the first SCSI disk it finds to da0, the second disk to da1 etc. If you ever removed or added a disk, all other devices of the same type (disk in this case) would move around. This implies you have to change /etc/fstab each time. Although the old style still works, you are strongly recommended to use this new feature. It will save you a lot of grief whenever you shift your hardware around on the SCSI buses. So, when you re-use your old trusty config file after upgrading from a pre-FreeBSD2.0.5.R system check this out. [driver for Adaptec 174x] controller ahb0 at isa? bio irq 11 vector ahbintr [for Adaptec 154x] controller aha0 at isa? port "IO_AHA0" bio irq 11 drq 5 vector ahaintr [for Seagate ST01/02] controller sea0 at isa? bio irq 5 iomem 0xc8000 iosiz 0x2000 vector seaintr controller scbus0 device da0 [support for 4 SCSI harddisks, da0 up da3] device sa0 [support for 2 SCSI tapes] [for the CDROM] device cd0 #Only need one of these, the code dynamically grows Both examples support SCSI disks. If during boot more devices of a specific type (e.g. da disks) are found than are configured in the booting kernel, the system will simply allocate more devices, incrementing the unit number starting at the last number wired down. If there are no wired down devices then counting starts at unit 0. Use man 4 scsi to check for the latest info on the SCSI subsystem. For more detailed info on host adapter drivers use e.g., man 4 ahc for info on the Adaptec 294x driver. Tuning your SCSI kernel setup Experience has shown that some devices are slow to respond to INQUIRY commands after a SCSI bus reset (which happens at boot time). An INQUIRY command is sent by the kernel on boot to see what kind of device (disk, tape, CDROM etc.) is connected to a specific target ID. This process is called device probing by the way. To work around the slow response problem, FreeBSD allows a tunable delay time before the SCSI devices are probed following a SCSI bus reset. You can set this delay time in your kernel configuration file using a line like: options SCSI_DELAY=15 #Be pessimistic about Joe SCSI device This line sets the delay time to 15 seconds. On my own system I had to use 3 seconds minimum to get my trusty old CDROM drive to be recognized. Start with a high value (say 30 seconds or so) when you have problems with device recognition. If this helps, tune it back until it just stays working. Rogue SCSI devices Although the SCSI standard tries to be complete and concise, it is a complex standard and implementing things correctly is no easy task. Some vendors do a better job then others. This is exactly where the rogue devices come into view. Rogues are devices that are recognized by the FreeBSD kernel as behaving slightly (...) non-standard. Rogue devices are reported by the kernel when booting. An example for two of my cartridge tape units: Feb 25 21:03:34 yedi /kernel: ahb0 targ 5 lun 0: <TANDBERG TDC 3600 -06:> Feb 25 21:03:34 yedi /kernel: sa0: Tandberg tdc3600 is a known rogue Mar 29 21:16:37 yedi /kernel: aha0 targ 5 lun 0: <ARCHIVE VIPER 150 21247-005> Mar 29 21:16:37 yedi /kernel: sa1: Archive Viper 150 is a known rogue For instance, there are devices that respond to all LUNs on a certain target ID, even if they are actually only one device. It is easy to see that the kernel might be fooled into believing that there are 8 LUNs at that particular target ID. The confusion this causes is left as an exercise to the reader. The SCSI subsystem of FreeBSD recognizes devices with bad habits by looking at the INQUIRY response they send when probed. Because the INQUIRY response also includes the version number of the device firmware, it is even possible that for different firmware versions different workarounds are used. See e.g. /sys/cam/scsi/scsi_sa.c and /sys/cam/scsi/scsi_all.c for more info on how this is done. This scheme works fine, but keep in mind that it of course only works for devices that are known to be weird. If you are the first to connect your bogus Mumbletech SCSI CDROM you might be the one that has to define which workaround is needed. After you got your Mumbletech working, please send the required workaround to the FreeBSD development team for inclusion in the next release of FreeBSD. Other Mumbletech owners will be grateful to you. Multiple LUN devices In some cases you come across devices that use multiple logical units (LUNs) on a single SCSI ID. In most cases FreeBSD only probes devices for LUN 0. An example are so called bridge boards that connect 2 non-SCSI hard disks to a SCSI bus (e.g. an Emulex MD21 found in old Sun systems). This means that any devices with LUNs != 0 are not normally found during device probe on system boot. To work around this problem you must add an appropriate entry in /sys/cam/scsi and rebuild your kernel. Look for a struct that is initialized like below: (FIXME: which file? Do these entries still exist in this form now that we use CAM?) { T_DIRECT, T_FIXED, "MAXTOR", "XT-4170S", "B5A", "mx1", SC_ONE_LU } For your Mumbletech BRIDGE2000 that has more than one LUN, acts as a SCSI disk and has firmware revision 123 you would add something like: { T_DIRECT, T_FIXED, "MUMBLETECH", "BRIDGE2000", "123", "da", SC_MORE_LUS } The kernel on boot scans the inquiry data it receives against the table and acts accordingly. See the source for more info. Tagged command queuing Modern SCSI devices, particularly magnetic disks, support what is called tagged command queuing (TCQ). In a nutshell, TCQ allows the device to have multiple I/O requests outstanding at the same time. Because the device is intelligent, it can optimize its operations (like head positioning) based on its own request queue. On SCSI devices like RAID (Redundant Array of Independent Disks) arrays the TCQ function is indispensable to take advantage of the device's inherent parallelism. Each I/O request is uniquely identified by a tag (hence the name tagged command queuing) and this tag is used by FreeBSD to see which I/O in the device drivers queue is reported as complete by the device. It should be noted however that TCQ requires device driver support and that some devices implemented it not quite right in their firmware. This problem bit me once, and it leads to highly mysterious problems. In such cases, try to disable TCQ. Bus-master host adapters Most, but not all, SCSI host adapters are bus mastering controllers. This means that they can do I/O on their own without putting load onto the host CPU for data movement. This is of course an advantage for a multitasking operating system like FreeBSD. It must be noted however that there might be some rough edges. For instance an Adaptec 1542 controller can be set to use different transfer speeds on the host bus (ISA or AT in this case). The controller is settable to different rates because not all motherboards can handle the higher speeds. Problems like hang-ups, bad data etc might be the result of using a higher data transfer rate then your motherboard can stomach. The solution is of course obvious: switch to a lower data transfer rate and try if that works better. In the case of a Adaptec 1542, there is an option that can be put into the kernel config file to allow dynamic determination of the right, read: fastest feasible, transfer rate. This option is disabled by default: options "TUNE_1542" #dynamic tune of bus DMA speed Check the manual pages for the host adapter that you use. Or better still, use the ultimate documentation (read: driver source). Tracking down problems The following list is an attempt to give a guideline for the most common SCSI problems and their solutions. It is by no means complete. Check for loose connectors and cables. Check and double check the location and number of your terminators. Check if your bus has at least one supplier of terminator power (especially with external terminators. Check if no double target IDs are used. Check if all devices to be used are powered up. Make a minimal bus config with as little devices as possible. If possible, configure your host adapter to use slow bus speeds. Disable tagged command queuing to make things as simple as possible (for a NCR host adapter based system see man ncrcontrol) If you can compile a kernel, make one with the SCSIDEBUG option, and try accessing the device with debugging turned on for that device. If your device does not even probe at startup, you may have to define the address of the device that is failing, and the desired debug level in /sys/cam/cam_debug.h. If it probes but just does not work, you can use the &man.camcontrol.8; command to dynamically set a debug level to it in a running kernel (if CAMDEBUG is defined). This will give you copious debugging output with which to confuse the gurus. See man camcontrol for more exact information. Also look at man 4 pass. Further reading If you intend to do some serious SCSI hacking, you might want to have the official standard at hand: Approved American National Standards can be purchased from ANSI at
13th Floor 11 West 42nd Street New York NY 10036 Sales Dept: (212) 642-4900
You can also buy many ANSI standards and most committee draft documents from Global Engineering Documents,
15 Inverness Way East Englewood CO, 80112-5704 Phone: (800) 854-7179 Outside USA and Canada: (303) 792-2181 Fax: (303) 792- 2192
Many X3T10 draft documents are available electronically on the SCSI BBS (719-574-0424) and on the ncrinfo.ncr.com anonymous FTP site. Latest X3T10 committee documents are: AT Attachment (ATA or IDE) [X3.221-1994] (Approved) ATA Extensions (ATA-2) [X3T10/948D Rev 2i] Enhanced Small Device Interface (ESDI) [X3.170-1990/X3.170a-1991] (Approved) Small Computer System Interface — 2 (SCSI-2) [X3.131-1994] (Approved) SCSI-2 Common Access Method Transport and SCSI Interface Module (CAM) [X3T10/792D Rev 11] Other publications that might provide you with additional information are: SCSI: Understanding the Small Computer System Interface, written by NCR Corporation. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 ISBN 0-13-796855-8 Basics of SCSI, a SCSI tutorial written by Ancot Corporation Contact Ancot for availability information at: Phone: (415) 322-5322 Fax: (415) 322-0455 SCSI Interconnection Guide Book, an AMP publication (dated 4/93, Catalog 65237) that lists the various SCSI connectors and suggests cabling schemes. Available from AMP at (800) 522-6752 or (717) 564-0100 Fast Track to SCSI, A Product Guide written by Fujitsu. Available from: Prentice Hall, Englewood Cliffs, NJ, 07632 Phone: (201) 767-5937 ISBN 0-13-307000-X The SCSI Bench Reference, The SCSI Encyclopedia, and the SCSI Tutor, ENDL Publications, 14426 Black Walnut Court, Saratoga CA, 95070 Phone: (408) 867-6642 Zadian SCSI Navigator (quick ref. book) and Discover the Power of SCSI (First book along with a one-hour video and tutorial book), Zadian Software, Suite 214, 1210 S. Bascom Ave., San Jose, CA 92128, (408) 293-0800 On Usenet the newsgroups comp.periphs.scsi and comp.periphs are noteworthy places to look for more info. You can also find the SCSI-FAQ there, which is posted periodically. Most major SCSI device and host adapter suppliers operate FTP sites and/or BBS systems. They may be valuable sources of information about the devices you own. * Disk/tape controllers * SCSI * IDE * Floppy Hard drives SCSI hard drives Contributed by &a.asami;. 17 February 1998. As mentioned in the SCSI section, virtually all SCSI hard drives sold today are SCSI-2 compliant and thus will work fine as long as you connect them to a supported SCSI host adapter. Most problems people encounter are either due to badly designed cabling (cable too long, star topology, etc.), insufficient termination, or defective parts. Please refer to the SCSI section first if your SCSI hard drive is not working. However, there are a couple of things you may want to take into account before you purchase SCSI hard drives for your system. Rotational speed Rotational speeds of SCSI drives sold today range from around 4,500RPM to 15,000RPM. Most of them are either 7,200RPM or 10,000RPM, with 15,000RPM becoming affordable (June 2002). Even though the 10,000RPM drives can generally transfer data faster, they run considerably hotter than their 7,200RPM counterparts. A large fraction of today's disk drive malfunctions are heat-related. If you do not have very good cooling in your PC case, you may want to stick with 7,200RPM or slower drives. Note that newer drives, with higher areal recording densities, can deliver much more bits per rotation than older ones. Today's top-of-line 7,200RPM drives can sustain a throughput comparable to 10,000RPM drives of one or two model generations ago. The number to find on the spec sheet for bandwidth is internal data (or transfer) rate. It is usually in megabits/sec so divide it by 8 and you will get the rough approximation of how much megabytes/sec you can get out of the drive. (If you are a speed maniac and want a 15,000RPM drive for your cute little PC, be my guest; however, those drives become extremely hot. Do not even think about it if you do not have a fan blowing air directly at the drive or a properly ventilated disk enclosure.) Obviously, the latest 15,000RPM drives and 10,000RPM drives can deliver more data than the latest 7,200RPM drives, so if absolute bandwidth is the necessity for your applications, you have little choice but to get the faster drives. Also, if you need low latency, faster drives are better; not only do they usually have lower average seek times, but also the rotational delay is one place where slow-spinning drives can never beat a faster one. (The average rotational latency is half the time it takes to rotate the drive once; thus, it is 2 milliseconds for 15,000RPM, 3ms for 10,000RPM drives, 4.2ms for 7,200RPM drives and 5.6ms for 5,400RPM drives.) Latency is seek time plus rotational delay. Make sure you understand whether you need low latency or more accesses per second, though; in the latter case (e.g., news servers), it may not be optimal to purchase one big fast drive. You can achieve similar or even better results by using the ccd (concatenated disk) driver to create a striped disk array out of multiple slower drives for comparable overall cost. Make sure you have adequate air flow around the drive, especially if you are going to use a fast-spinning drive. You generally need at least 1/2” (1.25cm) of spacing above and below a drive. Understand how the air flows through your PC case. Most cases have the power supply suck the air out of the back. See where the air flows in, and put the drive where it will have the largest volume of cool air flowing around it. You may need to seal some unwanted holes or add a new fan for effective cooling. Another consideration is noise. Many 10,000 or faster drives generate a high-pitched whine which is quite unpleasant to most people. That, plus the extra fans often required for cooling, may make 10,000 or faster drives unsuitable for some office and home environments. Form factor Most SCSI drives sold today are of 3.5” form factor. They come in two different heights; 1.6” (half-height) or 1” (low-profile). The half-height drive is the same height as a CDROM drive. However, do not forget the spacing rule mentioned in the previous section. If you have three standard 3.5” drive bays, you will not be able to put three half-height drives in there (without frying them, that is). Interface The majority of SCSI hard drives sold today are Ultra, Ultra-wide, or Ultra160 SCSI. As of this writing (June 2002), the first Ultra320 host adapters and devices become available. The maximum bandwidth of Ultra SCSI is 20MB/sec, and Ultra-wide SCSI is 40MB/sec. Ultra160 can transfer 160MB/sec and Ultra320 can transfer 320MB/sec. There is no difference in max cable length between Ultra and Ultra-wide; however, the more devices you have on the same bus, the sooner you will start having bus integrity problems. Unless you have a well-designed disk enclosure, it is not easy to make more than 5 or 6 Ultra SCSI drives work on a single bus. On the other hand, if you need to connect many drives, going for Fast-wide SCSI may not be a bad idea. That will have the same max bandwidth as Ultra (narrow) SCSI, while electronically it is much easier to get it right. My advice would be: if you want to connect many disks, get wide or Ultra160 SCSI drives; they usually cost a little more but it may save you down the road. (Besides, if you can not afford the cost difference, you should not be building a disk array.) There are two variant of wide SCSI drives; 68-pin and 80-pin SCA (Single Connector Attach). The SCA drives do not have a separate 4-pin power connector, and also read the SCSI ID settings through the 80-pin connector. If you are really serious about building a large storage system, get SCA drives and a good SCA enclosure (dual power supply with at least one extra fan). They are more electronically sound than 68-pin counterparts because there is no stub of the SCSI bus inside the disk canister as in arrays built from 68-pin drives. They are easier to install too (you just need to screw the drive in the canister, instead of trying to squeeze in your fingers in a tight place to hook up all the little cables (like the SCSI ID and disk activity LED lines). * IDE hard drives Tape drives Contributed by &a.jmb;. 2 July 1996. General tape access commands &man.mt.1; provides generic access to the tape drives. Some of the more common commands are rewind, erase, and status. See the &man.mt.1; manual page for a detailed description. Controller Interfaces There are several different interfaces that support tape drives. The interfaces are SCSI, IDE, Floppy and Parallel Port. A wide variety of tape drives are available for these interfaces. Controllers are discussed in Disk/tape controllers. SCSI drives The &man.st.4; driver provides support for 8mm (Exabyte), 4mm (DAT: Digital Audio Tape), QIC (Quarter-Inch Cartridge), DLT (Digital Linear Tape), QIC Mini cartridge and 9-track (remember the big reels that you see spinning in Hollywood computer rooms) tape drives. See the &man.st.4; manual page for a detailed description. The drives listed below are currently being used by members of the FreeBSD community. They are not the only drives that will work with FreeBSD. They just happen to be the ones that we use. 4mm (DAT: Digital Audio Tape) Archive Python 28454 Archive Python 04687 HP C1533A HP C1534A HP 35450A HP 35470A HP 35480A SDT-5000 Wangtek 6200 8mm (Exabyte) EXB-8200 EXB-8500 EXB-8505 QIC (Quarter-Inch Cartridge) Archive Anaconda 2750 Archive Viper 60 Archive Viper 150 Archive Viper 2525 Tandberg TDC 3600 Tandberg TDC 3620 Tandberg TDC 3800 Tandberg TDC 4222 Wangtek 5525ES DLT (Digital Linear Tape) Digital TZ87 Mini-Cartridge Conner CTMS 3200 Exabyte 2501 Autoloaders/Changers Hewlett-Packard HP C1553A Autoloading DDS2 * IDE drives Floppy drives Conner 420R * Parallel port drives Detailed Information Archive Anaconda 2750 The boot message identifier for this drive is ARCHIVE ANCDA 2750 28077 -003 type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 1.35GB when using QIC-1350 tapes. This drive will read and write QIC-150 (DC6150), QIC-250 (DC6250), and QIC-525 (DC6525) tapes as well. Data transfer rate is 350kB/s using &man.dump.8;. Rates of 530kB/s have been reported when using Amanda Production of this drive has been discontinued. The SCSI bus connector on this tape drive is reversed from that on most other SCSI devices. Make sure that you have enough SCSI cable to twist the cable one-half turn before and after the Archive Anaconda tape drive, or turn your other SCSI devices upside-down. Two kernel code changes are required to use this drive. This drive will not work as delivered. If you have a SCSI-2 controller, short jumper 6. Otherwise, the drive behaves are a SCSI-1 device. When operating as a SCSI-1 device, this drive, locks the SCSI bus during some tape operations, including: fsf, rewind, and rewoffl. If you are using the NCR SCSI controllers, patch the file /usr/src/sys/pci/ncr.c (as shown below). Build and install a new kernel. *** 4831,4835 **** }; ! if (np->latetime>4) { /* ** Although we tried to wake it up, --- 4831,4836 ---- }; ! if (np->latetime>1200) { /* ** Although we tried to wake it up, Reported by: &a.jmb; Archive Python 28454 The boot message identifier for this drive is ARCHIVE Python 28454-XXX4ASB type 1 removable SCSI 2 density code 0x8c, 512-byte blocks This is a DDS-1 tape drive. Native capacity is 2.5GB on 90m tapes. Data transfer rate is XXX. This drive was repackaged by Sun Microsystems as model 595-3067. Reported by: Bob Bishop rb@gid.co.uk Throughput is in the 1.5 MByte/sec range, however this will drop if the disks and tape drive are on the same SCSI controller. Reported by: Robert E. Seastrom rs@seastrom.com Archive Python 04687 The boot message identifier for this drive is ARCHIVE Python 04687-XXX 6580 Removable Sequential Access SCSI-2 device This is a DAT-DDS-2 drive. Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Switch 4 controls MRS (Media Recognition System). MRS tapes have stripes on the transparent leader. Switch 4 off enables MRS, on disables MRS. Parity is controlled by switch 5. Switch 5 on to enable parity control. Compression is enabled with Switch 6 off. It is possible to override compression with the SCSI MODE SELECT command (see &man.mt.1;). Data transfer rate is 800kB/s. Archive Viper 60 The boot message identifier for this drive is ARCHIVE VIPER 60 21116 -007 type 1 removable SCSI 1 This is a QIC tape drive. Native capacity is 60MB. Data transfer rate is XXX. Production of this drive has been discontinued. Reported by: Philippe Regnauld regnauld@hsc.fr Archive Viper 150 The boot message identifier for this drive is ARCHIVE VIPER 150 21531 -004 Archive Viper 150 is a known rogue type 1 removable SCSI 1. A multitude of firmware revisions exist for this drive. Your drive may report different numbers (e.g 21247 -005. This is a QIC tape drive. Native capacity is 150/250MB. Both 150MB (DC6150) and 250MB (DC6250) tapes have the recording format. The 250MB tapes are approximately 67% longer than the 150MB tapes. This drive can read 120MB tapes as well. It can not write 120MB tapes. Data transfer rate is 100kB/s This drive reads and writes DC6150 (150MB) and DC6250 (250MB) tapes. This drives quirks are known and pre-compiled into the SCSI tape device driver (&man.st.4;). Under FreeBSD 2.2-CURRENT, use mt blocksize 512 to set the blocksize. (The particular drive had firmware revision 21247 -005. Other firmware revisions may behave differently) Previous versions of FreeBSD did not have this problem. Production of this drive has been discontinued. Reported by: Pedro A M Vazquez vazquez@IQM.Unicamp.BR &a.msmith; Archive Viper 2525 The boot message identifier for this drive is ARCHIVE VIPER 2525 25462 -011 type 1 removable SCSI 1 This is a QIC tape drive. Native capacity is 525MB. Data transfer rate is 180kB/s at 90 inches/sec. The drive reads QIC-525, QIC-150, QIC-120 and QIC-24 tapes. Writes QIC-525, QIC-150, and QIC-120. Firmware revisions prior to 25462 -011 are bug ridden and will not function properly. Production of this drive has been discontinued. Conner 420R The boot message identifier for this drive is Conner tape. This is a floppy controller, mini cartridge tape drive. Native capacity is XXXX Data transfer rate is XXX The drive uses QIC-80 tape cartridges. Reported by: Mark Hannon mark@seeware.DIALix.oz.au Conner CTMS 3200 The boot message identifier for this drive is CONNER CTMS 3200 7.00 type 1 removable SCSI 2. This is a mini cartridge tape drive. Native capacity is XXXX Data transfer rate is XXX The drive uses QIC-3080 tape cartridges. Reported by: Thomas S. Traylor tst@titan.cs.mci.com <ulink url="http://www.digital.com/info/Customer-Update/931206004.txt.html">DEC TZ87</ulink> The boot message identifier for this drive is DEC TZ87 (C) DEC 9206 type 1 removable SCSI 2 density code 0x19 This is a DLT tape drive. Native capacity is 10GB. This drive supports hardware data compression. Data transfer rate is 1.2MB/s. This drive is identical to the Quantum DLT2000. The drive firmware can be set to emulate several well-known drives, including an Exabyte 8mm drive. Reported by: &a.wilko; <ulink url="http://www.Exabyte.COM:80/Products/Minicartridge/2501/Rfeatures.html">Exabyte EXB-2501</ulink> The boot message identifier for this drive is EXABYTE EXB-2501 This is a mini-cartridge tape drive. Native capacity is 1GB when using MC3000XL mini cartridges. Data transfer rate is XXX This drive can read and write DC2300 (550MB), DC2750 (750MB), MC3000 (750MB), and MC3000XL (1GB) mini cartridges. WARNING: This drive does not meet the SCSI-2 specifications. The drive locks up completely in response to a SCSI MODE_SELECT command unless there is a formatted tape in the drive. Before using this drive, set the tape blocksize with &prompt.root; mt -f /dev/st0ctl.0 blocksize 1024 Before using a mini cartridge for the first time, the mini cartridge must be formated. FreeBSD 2.1.0-RELEASE and earlier: &prompt.root; /sbin/scsi -f /dev/rst0.ctl -s 600 -c "4 0 0 0 0 0" (Alternatively, fetch a copy of the scsiformat shell script from FreeBSD 2.1.5/2.2.) FreeBSD 2.1.5 and later: &prompt.root; /sbin/scsiformat -q -w /dev/rst0.ctl Right now, this drive cannot really be recommended for FreeBSD. Reported by: Bob Beaulieu ez@eztravel.com Exabyte EXB-8200 The boot message identifier for this drive is EXABYTE EXB-8200 252X type 1 removable SCSI 1 This is an 8mm tape drive. Native capacity is 2.3GB. Data transfer rate is 270kB/s. This drive is fairly slow in responding to the SCSI bus during boot. A custom kernel may be required (set SCSI_DELAY to 10 seconds). There are a large number of firmware configurations for this drive, some have been customized to a particular vendor's hardware. The firmware can be changed via EPROM replacement. Production of this drive has been discontinued. Reported by: &a.msmith; Exabyte EXB-8500 The boot message identifier for this drive is EXABYTE EXB-8500-85Qanx0 0415 type 1 removable SCSI 2 This is an 8mm tape drive. Native capacity is 5GB. Data transfer rate is 300kB/s. Reported by: Greg Lehey grog@lemis.de <ulink url="http://www.Exabyte.COM:80/Products/8mm/8505XL/Rfeatures.html">Exabyte EXB-8505</ulink> The boot message identifier for this drive is EXABYTE EXB-85058SQANXR1 05B0 type 1 removable SCSI 2 This is an 8mm tape drive which supports compression, and is upward compatible with the EXB-5200 and EXB-8500. Native capacity is 5GB. The drive supports hardware data compression. Data transfer rate is 300kB/s. Reported by: Glen Foster gfoster@gfoster.com Hewlett-Packard HP C1533A The boot message identifier for this drive is HP C1533A 9503 type 1 removable SCSI 2. This is a DDS-2 tape drive. DDS-2 means hardware data compression and narrower tracks for increased data capacity. Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is 510kB/s. This drive is used in Hewlett-Packard's SureStore 6000eU and 6000i tape drives and C1533A DDS-2 DAT drive. The drive has a block of 8 dip switches. The proper settings for FreeBSD are: 1 ON; 2 ON; 3 OFF; 4 ON; 5 ON; 6 ON; 7 ON; 8 ON. switch 1 switch 2 Result On On Compression enabled at power-on, with host control On Off Compression enabled at power-on, no host control Off On Compression disabled at power-on, with host control Off Off Compression disabled at power-on, no host control Switch 3 controls MRS (Media Recognition System). MRS tapes have stripes on the transparent leader. These identify the tape as DDS (Digital Data Storage) grade media. Tapes that do not have the stripes will be treated as write-protected. Switch 3 OFF enables MRS. Switch 3 ON disables MRS. See HP SureStore Tape Products and Hewlett-Packard Disk and Tape Technical Information for more information on configuring this drive. Warning: Quality control on these drives varies greatly. One FreeBSD core-team member has returned 2 of these drives. Neither lasted more than 5 months. Reported by: &a.se; Hewlett-Packard HP 1534A The boot message identifier for this drive is HP HP35470A T503 type 1 removable SCSI 2 Sequential-Access density code 0x13, variable blocks. This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. Data transfer rate is 183kB/s. The same mechanism is used in Hewlett-Packard's SureStore 2000i tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT drive and HP C1536A DDS format DAT drive. The HP C1534A DDS format DAT drive has two indicator lights, one green and one amber. The green one indicates tape action: slow flash during load, steady when loaded, fast flash during read/write operations. The amber one indicates warnings: slow flash when cleaning is required or tape is nearing the end of its useful life, steady indicates an hard fault. (factory service required?) Reported by Gary Crutcher gcrutchr@nightflight.com Hewlett-Packard HP C1553A Autoloading DDS2 The boot message identifier for this drive is "". This is a DDS-2 tape drive with a tape changer. DDS-2 means hardware data compression and narrower tracks for increased data capacity. Native capacity is 24GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is 510kB/s (native). This drive is used in Hewlett-Packard's SureStore 12000e tape drive. The drive has two selectors on the rear panel. The selector closer to the fan is SCSI id. The other selector should be set to 7. There are four internal switches. These should be set: 1 ON; 2 ON; 3 ON; 4 OFF. At present the kernel drivers do not automatically change tapes at the end of a volume. This shell script can be used to change tapes: #!/bin/sh PATH="/sbin:/usr/sbin:/bin:/usr/bin"; export PATH usage() { echo "Usage: dds_changer [123456ne] raw-device-name echo "1..6 = Select cartridge" echo "next cartridge" echo "eject magazine" exit 2 } if [ $# -ne 2 ] ; then usage fi cdb3=0 cdb4=0 cdb5=0 case $1 in [123456]) cdb3=$1 cdb4=1 ;; n) ;; e) cdb5=0x80 ;; ?) usage ;; esac scsi -f $2 -s 100 -c "1b 0 0 $cdb3 $cdb4 $cdb5" Hewlett-Packard HP 35450A The boot message identifier for this drive is HP HP35450A -A C620 type 1 removable SCSI 2 Sequential-Access density code 0x13 This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 1.2GB. Data transfer rate is 160kB/s. Reported by: Mark Thompson mark.a.thompson@pobox.com Hewlett-Packard HP 35470A The boot message identifier for this drive is HP HP35470A 9 09 type 1 removable SCSI 2 This is a DDS-1 tape drive. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. Data transfer rate is 183kB/s. The same mechanism is used in Hewlett-Packard's SureStore 2000i tape drive, C35470A DDS format DAT drive, C1534A DDS format DAT drive, and HP C1536A DDS format DAT drive. Warning: Quality control on these drives varies greatly. One FreeBSD core-team member has returned 5 of these drives. None lasted more than 9 months. Reported by: David Dawes dawes@rf900.physics.usyd.edu.au (9 09) Hewlett-Packard HP 35480A The boot message identifier for this drive is HP HP35480A 1009 type 1 removable SCSI 2 Sequential-Access density code 0x13. This is a DDS-DC tape drive. DDS-DC is DDS-1 with hardware data compression. DDS-1 is the original DAT tape format. Native capacity is 2GB when using 90m tapes. It cannot handle 120m tapes. This drive supports hardware data compression. Please refer to the section on HP C1533A for the proper switch settings. Data transfer rate is 183kB/s. This drive is used in Hewlett-Packard's SureStore 5000eU and 5000i tape drives and C35480A DDS format DAT drive.. This drive will occasionally hang during a tape eject operation (mt offline). Pressing the front panel button will eject the tape and bring the tape drive back to life. WARNING: HP 35480-03110 only. On at least two occasions this tape drive when used with FreeBSD 2.1.0, an IBM Server 320 and an 2940W SCSI controller resulted in all SCSI disk partitions being lost. The problem has not be analyzed or resolved at this time. <ulink url="http://www.sel.sony.com/SEL/ccpg/storage/tape/t5000.html">Sony SDT-5000</ulink> There are at least two significantly different models: one is a DDS-1 and the other DDS-2. The DDS-1 version is SDT-5000 3.02. The DDS-2 version is SONY SDT-5000 327M. The DDS-2 version has a 1MB cache. This cache is able to keep the tape streaming in almost any circumstances. The boot message identifier for this drive is SONY SDT-5000 3.02 type 1 removable SCSI 2 Sequential-Access density code 0x13 Native capacity is 4GB when using 120m tapes. This drive supports hardware data compression. Data transfer rate is depends upon the model or the drive. The rate is 630kB/s for the SONY SDT-5000 327M while compressing the data. For the SONY SDT-5000 3.02, the data transfer rate is 225kB/s. In order to get this drive to stream, set the blocksize to 512 bytes (mt blocksize 512) reported by Kenneth Merry ken@ulc199.residence.gatech.edu. SONY SDT-5000 327M information reported by Charles Henrich henrich@msu.edu. Reported by: &a.jmz; Tandberg TDC 3600 The boot message identifier for this drive is TANDBERG TDC 3600 =08: type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 150/250MB. This drive has quirks which are known and work around code is present in the SCSI tape device driver (&man.st.4;). Upgrading the firmware to XXX version will fix the quirks and provide SCSI 2 capabilities. Data transfer rate is 80kB/s. IBM and Emerald units will not work. Replacing the firmware EPROM of these units will solve the problem. Reported by: &a.msmith; Tandberg TDC 3620 This is very similar to the Tandberg TDC 3600 drive. Reported by: &a.joerg; Tandberg TDC 3800 The boot message identifier for this drive is TANDBERG TDC 3800 =04Y Removable Sequential Access SCSI-2 device This is a QIC tape drive. Native capacity is 525MB. Reported by: &a.jhs; Tandberg TDC 4222 The boot message identifier for this drive is TANDBERG TDC 4222 =07 type 1 removable SCSI 2 This is a QIC tape drive. Native capacity is 2.5GB. The drive will read all cartridges from the 60 MB (DC600A) upwards, and write 150 MB (DC6150) upwards. Hardware compression is optionally supported for the 2.5 GB cartridges. This drives quirks are known and pre-compiled into the SCSI tape device driver (&man.st.4;) beginning with FreeBSD 2.2-CURRENT. For previous versions of FreeBSD, use mt to read one block from the tape, rewind the tape, and then execute the backup program (mt fsr 1; mt rewind; dump ...) Data transfer rate is 600kB/s (vendor claim with compression), 350 KB/s can even be reached in start/stop mode. The rate decreases for smaller cartridges. Reported by: &a.joerg; Wangtek 5525ES The boot message identifier for this drive is WANGTEK 5525ES SCSI REV7 3R1 type 1 removable SCSI 1 density code 0x11, 1024-byte blocks This is a QIC tape drive. Native capacity is 525MB. Data transfer rate is 180kB/s. The drive reads 60, 120, 150, and 525MB tapes. The drive will not write 60MB (DC600 cartridge) tapes. In order to overwrite 120 and 150 tapes reliably, first erase (mt erase) the tape. 120 and 150 tapes used a wider track (fewer tracks per tape) than 525MB tapes. The extra width of the previous tracks is not overwritten, as a result the new data lies in a band surrounded on both sides by the previous data unless the tape have been erased. This drives quirks are known and pre-compiled into the SCSI tape device driver (&man.st.4;). Other firmware revisions that are known to work are: M75D Reported by: Marc van Kempen marc@bowtie.nl REV73R1 Andrew Gordon Andrew.Gordon@net-tel.co.uk M75D Wangtek 6200 The boot message identifier for this drive is WANGTEK 6200-HS 4B18 type 1 removable SCSI 2 Sequential-Access density code 0x13 This is a DDS-1 tape drive. Native capacity is 2GB using 90m tapes. Data transfer rate is 150kB/s. Reported by: Tony Kimball alk@Think.COM * Problem drives CDROM drives Contributed by &a.obrien;. 23 November 1997. Generally speaking those in The FreeBSD Project prefer SCSI CDROM drives over IDE CDROM drives. However not all SCSI CDROM drives are equal. Some feel the quality of some SCSI CDROM drives have been deteriorating to that of IDE CDROM drives. Toshiba used to be the favored stand-by, but many on the SCSI mailing list have found displeasure with the 12x speed XM-5701TA as its volume (when playing audio CDROMs) is not controllable by the various audio player software. Another area where SCSI CDROM manufacturers are cutting corners is adherence to the SCSI specification. Many SCSI CDROMs will respond to multiple LUNs for its target address. Known violators include the 6x Teac CD-56S 1.0D.
diff --git a/en_US.ISO8859-1/articles/vinum/article.sgml b/en_US.ISO8859-1/articles/vinum/article.sgml index a3d2098834..730605d2cc 100644 --- a/en_US.ISO8859-1/articles/vinum/article.sgml +++ b/en_US.ISO8859-1/articles/vinum/article.sgml @@ -1,2550 +1,2547 @@ - - -%trademarks; + +%articles.ent; Vinum"> -%man; ]>
Bootstrapping Vinum: A Foundation for Reliable Servers Robert A. Van Valzah 2001 Robert A. Van Valzah - $Date: 2003-10-18 10:39:16 $ GMT - $Id: article.sgml,v 1.14 2003-10-18 10:39:16 simon Exp $ + $Date: 2004-08-08 13:43:56 $ GMT + $Id: article.sgml,v 1.15 2004-08-08 13:43:56 hrs Exp $ &tm-attrib.freebsd; &tm-attrib.general; In the most abstract sense, these instructions show how to build a pair of disk drives where either one is adequate to keep your server running if the other fails. Life is better if they are both working, but your server will never die unless both disk drives die at once. If you choose ATAPI drives and use a fairly generic kernel, you can be confident that either of these drives can be plugged into most any main board to produce a working server in a pinch. The drives need not be identical. These techniques work equally well with SCSI drives as they do with ATAPI, but I will focus on ATAPI here because main boards with this interface are ubiquitous. After building the foundation of a reliable server as shown here, you can expand to as many disk drives as necessary to build the failure-resilient server of your dreams.
Introduction Any machine that is going to provide reliable service needs to have either redundant components on-line or a pool of off-line spares that can be promptly swapped in. Commodity PC hardware makes it affordable for even small organizations to have some spare parts available that could be pressed into service following the failure of production equipment. In many organizations, a failed power supply, NIC, memory, or main board could easily be swapped with a standby in a matter of minutes and be ready to return to production work. If a disk drive fails, however, it often has to be restored from a tape backup. This may take many hours. With disk drive capacities rising faster than tape drive capacities, the time needed to restore a failed disk drive seems to increase as technology progresses. &vinum.ap; is a volume manager for FreeBSD that provides a standard block I/O layer interface to the filesystem code just as any hardware device driver would. It works by managing partitions of type vinum and allows you to subdivide and group the space in such partitions into logical devices called volumes that can be used in the same way as disk partitions. Volumes can be configured for resilience, performance, or both. Experienced system administrators will immediately recognize the benefits of being able to configure each filesystem to match the way it is most often used. In some ways, Vinum is similar to &man.ccd.4;, but it is far more flexible and robust in the face of failures. It is only slightly more difficult to set up than &man.ccd.4;. &man.ccd.4; may meet your needs if you are only interested in concatenation.
Terminology Discussion of storage management can get very tricky simply because of the terminology involved. As we will see below, the terms disk, slice, partition, subdisk, and volume each refer to different things that present the same interface to a kernel function like swapping. The potential for confusion is compounded because the objects that these terms represent can be nested inside each other. I will refer to a physical disk drive as a spindle. A partition here means a BSD partition as maintained by disklabel. It does not refer to slices or BIOS partitions as maintained by fdisk.
Vinum Objects Vinum defines a hierarchy of four objects that it uses to manage storage (see ). Different combinations of these objects are used to achieve failure resilience, performance, and/or extra capacity. I will give a whirlwind tour of the objects here--see the Vinum web site for a more thorough description.
Vinum Objects and Architecture +-----+------+------+ | UFS | swap | Etc. | +---+-+------+----+ + | volume | | + V +-------------+ + | i plex | | + n +-------------+ + | u subdisk | | + m +-------------+ + | drive | | +-----------------+ + | Block I/O devices | +-------------------+ Vinum Objects and Architecture
The top object, a vinum volume, implements a virtual disk that provides a standard block I/O layer interface to other parts of the kernel. The bottom object, a vinum drive, uses this same interface to request I/O from physical devices below it. In between these two (from top to bottom) we have objects called a vinum plex and a vinum subdisk. As you can probably guess from the name, a vinum subdisk is a contiguous subset of the space available on a vinum drive. It lets you subdivide a vinum drive in much the same way that a disk BSD partition lets you subdivide a BIOS slice. A plex allows subdisks to be grouped together making the space of all subdisks available as a single object. A plex can be organized with its constituent subdisks concatenated or striped. Both organizations are useful for spreading I/O requests across spindles since plexes reside on distinct spindles. A striped plex will switch spindles each time a multiple of the stripe size is reached. A concatenated plex will switch spindles only when the end of a subdisk is reached. An important characteristic of a Vinum volume is that it can be made up of more than one plex. In this case, writes go to all plexes and a read may be satisfied by any plex. Configuring two or more plexes on distinct spindles yields a volume that is resilient to failure. Vinum maintains a configuration that defines instances of the above objects and the way they are related to each other. This configuration is automatically written to all spindles under Vinum management whenever it changes.
Vinum Volume/Plex Organization Although Vinum can manage any number of spindles, I will only cover scenarios with two spindles here for simplification. See to see how two spindles organized with Vinum compare to two spindles without Vinum. Characteristics of Two Spindles Organized with Vinum Organization Total Capacity Failure Resilient Peak Read Performance Peak Write Performance Concatenated Plexes Unchanged, but appears as a single drive No Unchanged Unchanged Striped Plexes (RAID-0) Unchanged, but appears as a single drive No 2x 2x Mirrored Volumes (RAID-1) 1/2, appearing as a single drive Yes 2x Unchanged
shows that striping yields the same capacity and lack of failure resilience as concatenation, but it has better peak read and write performance. Hence we will not be using concatenation in any of the examples here. Mirrored volumes provide the benefits of improved peak read performance and failure resilience--but this comes at a loss in capacity. Both concatenation and striping bring their benefits over a single spindle at the cost of increased likelihood of failure since more than one spindle is now involved. When three or more spindles are present, Vinum also supports rotated, block-interleaved parity (also called RAID-5) that provides better capacity than mirroring (but not quite as good as striping), better read performance than both mirroring and striping, and good failure resilience. There is, however, a substantial decrease in write performance with RAID-5. Most of the benefits become more pronounced with five or more spindles. The organizations described above may be combined to provide benefits that no single organization can match. For example, mirroring and striping can be combined to provide failure-resilience with very fast read performance.
Vinum History Vinum is a standard part of even a "minimum" FreeBSD distribution and it has been standard since 3.0-RELEASE. The official pronunciation of the name is VEE-noom. &vinum.ap; was inspired by the Veritas Volume Manager, but was not derived from it. The name is a play on that history and the Latin adage In Vino Veritas (Vino is the ablative form of Vinum). Literally translated, that is Truth lies in wine hinting that drunkards have a hard time lying. I have been using it in production on six different servers for over two years with no data loss. Like the rest of FreeBSD, Vinum provides rock-stable performance. (On a personal note, I have seen Vinum panic when I misconfigured something, but I have never had any trouble in normal operation.) Greg Lehey wrote Vinum for FreeBSD, but he is seeking help in porting it to NetBSD and OpenBSD. Just like the rest of FreeBSD, Vinum is undergoing continuous development. Several subtle, but significant bugs have been fixed in recent releases. It is always best to use the most recent code base that meets your stability requirements.
Vinum Deployment Strategy Vinum, coupled with prudent partition management, lets you keep warm-spare spindles on-line so that failures are transparent to users. Failed spindles can be replaced during regular maintenance periods or whenever it is convenient. When all spindles are working, the server benefits from increased performance and capacity. Having redundant copies of your home directory does not help you if the spindle holding root, /usr, or swap fails on your server. Hence I focus here on building a simple foundation for a failure-resilient server covering the root, /usr, /home, and swap partitions. Vinum mirroring does not remove the need for making backups! Mirroring cannot help you recover from site disasters or the dreaded rm -r -f / command.
Why Bootstrap Vinum? It is possible to add Vinum to a server configuration after it is already in production use, but this is much harder than designing for it from the start. Ironically, Vinum is not supported by /stand/sysinstall and hence you cannot install /usr right onto a Vinum volume. Vinum currently does not support the root filesystem (this feature is in development). Hence it is a bit tricky to get started using Vinum, but these instructions take you though the process of planning for Vinum, installing FreeBSD without it, and then beginning to use it. I have come to call this whole process bootstrapping Vinum. That is, the process of getting Vinum initially installed and operating to the point where you have met your resilience or performance goals. My purpose here is to document a Vinum bootstrapping method that I have found that works well for me.
Vinum Benefits The server foundation scenario I have chosen here allows me to show you examples of configuring for resilience on /usr and /home. Yet Vinum provides benefits other than resilience--namely performance, capacity, and manageability. It can significantly improve disk performance (especially under multi-user loads). Vinum can easily concatenate many smaller disks to produce the illusion of a single larger disk (but my server foundation scenario does not allow me to illustrate these benefits here). For servers with many spindles, Vinum provides substantial benefits in volume management, particularly when coupled with hot-pluggable hardware. Data can be moved from spindle to spindle while the system is running without loss of production time. Again, details of this will not be given here, but once you get your feet wet with Vinum, other documentation will help you do things like this. See "The Vinum Volume Manager" for a technical introduction to Vinum, &man.vinum.8; for a description of the vinum command, and &man.vinum.4; for a description of the vinum device driver and the way Vinum objects are named. Breaking up your disk space into smaller and smaller partitions has the benefit of allowing you to tune for the most common type of access and tends to keep disk hogs within their pens. However it also causes some loss in total available disk space due to fragmentation.
Server Operation in Degraded Mode Some disk failures in this two-spindle scenario will result in Vinum automatically routing all disk I/O to the remaining good spindle. Others will require brief manual intervention on the console to configure the server for degraded mode operation and a quick reboot. Other than actual hardware repairs, most recovery work can be done while the server is running in multi-user degraded mode so there is as little production impact from failures as possible. I give the instructions in needed to configure the server for degraded mode operation in those cases where Vinum cannot do it automatically. I also give the instructions needed to return to normal operation once the failed hardware is repaired. You might call these instructions Vinum failure recovery techniques. I recommend practicing using these instructions by recovering from simulated failures. For each failure scenario, I also give tips below for simulating a failure even when your hardware is working well. Even a minimum Vinum system as described in below can be a good place to experiment with recovery techniques without impacting production equipment.
Hardware RAID vs. Vinum (Software RAID) Manual intervention is sometimes required to configure a server for degraded mode because Vinum is implemented in software that runs after the FreeBSD kernel is loaded. One disadvantage of such software RAID solutions is that there is nothing that can be done to hide spindle failures from the BIOS or the FreeBSD boot sequence. Hence the manual reconfiguration of the server for degraded operation mentioned above just informs the BIOS and boot sequence of failed spindles. Hardware RAID solutions generally have an advantage in that they require no such reconfiguration since spindle failures are hidden from the BIOS and boot sequence. Hardware RAID, however, may have some disadvantages that can be significant in some cases: The hardware RAID controller itself may become a single point of failure for the system. The data is usually kept in a proprietary format so that a disk drive cannot be simply plugged into another main board and booted. You often cannot mix and match drives with different sizes and interfaces. You are often limited to the number of drives supported by the hardware RAID controller (often only four or eight). In other words, &vinum.ap; may offer advantages in that there is no single point of failure, the drives can boot on most any main board, and you are free to mix and match as many drives using whatever interface you choose. Keep your kernel fairly generic (or at least keep /kernel.GENERIC around). This will improve the chances that you can come back up on foreign hardware more quickly. The pros and cons discussed above suggest that the root filesystem and swap partition are good candidates for hardware RAID if available. This is especially true for servers where it is difficult for administrators to get console access (recall that this is sometimes required to configure a server for degraded mode operation). A server with only software RAID is well suited to office and home environments where an administrator can be close at hand. A common myth is that hardware RAID is always faster than software RAID. Since it runs on the host CPU, Vinum often has more CPU power and memory available than a dedicated RAID controller would have. If performance is a prime concern, it is best to benchmark your application running on your CPU with your spindles using both hardware and software RAID systems before making a decision.
Hardware for Vinum These instructions may be timely since commodity PC hardware can now easily host several hundred gigabytes of reasonably high-performance disk space at a low price. Many disk drive manufactures now sell 7,200 RPM disk drives with quite low seek times and high transfer rates through ATA-100 interfaces, all at very attractive prices. Four such drives, attached to a suitable main board and configured with Vinum and prudent partitioning, yields a failure-resilient, high performance disk server at a very reasonable cost. However, you can indeed get started with Vinum very simply. A minimum system can be as simple as an old CPU (even a 486 is fine) and a pair of drives that are 500 MB or more. They need not be the same size or even use the same interface (i.e., it is fine to mix ATAPI and SCSI). So get busy and give this a try today! You will have the foundation of a failure-resilient server running in an hour or so!
Bootstrapping Phases Greg Lehey suggested this bootstrapping method. It uses knowledge of how Vinum internally allocates disk space to avoid copying data. Instead, Vinum objects are configured so that they occupy the same disk space where /stand/sysinstall built filesystems. The filesystems are thus embedded within Vinum objects without copying. There are several distinct phases to the Vinum bootstrapping procedure. Each of these phases is presented in a separate section below. The section starts with a general overview of the phase and its goals. It then gives example steps for the two-spindle scenario presented here and advice on how to adapt them for your server. (If you are reading for a general understanding of Vinum bootstrapping, the example sections for each phase can safely be skipped.) The remainder of this section gives an overview of the entire bootstrapping process. Phase 1 involves planning and preparation. We will balance requirements for the server against available resources and make design tradeoffs. We will plan the transition from no Vinum to Vinum on just one spindle, to Vinum on two spindles. In phase 2, we will install a minimum FreeBSD system on a single spindle using partitions of type 4.2BSD (regular UFS filesystems). Phase 3 will embed the non-root filesystems from phase 2 in Vinum objects. Note that Vinum will be up and running at this point, but it cannot yet provide any resilience since it only has one spindle on which to store data. Finally in phase 4, we configure Vinum on a second spindle and make a backup copy of the root filesystem. This will give us resilience on all filesystems.
Bootstrapping Phase 1: Planning and Preparation Our goal in this phase is to define the different partitions we will need and examine their requirements. We will also look at available disk drives and controllers and allocate partitions to them. Finally, we will determine the size of each partition and its use during the bootstrapping process. After this planning is complete, we can optionally prepare to use some tools that will make bootstrapping Vinum easier. Several key questions must be answered in this planning phase: What filesystem and partitions will be needed? How will they be used? How will we name each spindle? How will the partitions be ordered for each spindle? How will partitions be assigned to the spindles? How will partitions be configured? Resilience or performance? What technique will be used to achieve resilience? What spindles will be used? How will they be configured on the available controllers? How much space is required for each partition?
Phase 1 Example In this example, I will assume a scenario where we are building a minimal foundation for a failure-resilient server. Hence we will need at least root, /usr, /home, and swap partitions. The root, /usr, and /home filesystems all need resilience since the server will not be much good without them. The swap partition needs performance first and generally does not need resilience since nothing it holds needs to be retained across a reboot.
Spindle Naming The kernel would refer to the master spindle on the primary and secondary ATA controllers as /dev/ad0 and /dev/ad2 respectively. This assumes that you have not removed the line options ATA_STATIC_ID from your kernel configuration. But Vinum also needs to have a name for each spindle that will stay the same name regardless of how it is attached to the CPU (i.e., if the drive moves, the Vinum name moves with the drive). Some recovery techniques documented below suggest moving a spindle from the secondary ATA controller to the primary ATA controller. (Indeed, the flexibility of making such moves is a key benefit of Vinum especially if you are managing a large number of spindles.) After such a drive/controller swap, the kernel will see what used to be /dev/ad2 as /dev/ad0 but Vinum will still call it by whatever name it had when it was attached to /dev/ad2 (i.e., when it was created or first made known to Vinum). Since connections can change, it is best to give each spindle a unique, abstract name that gives no hint of how it is attached. Avoid names that suggest a manufacturer, model number, physical location, or membership in a sequence (e.g. avoid names like upper, lower, etc., alpha, beta, etc., SCSI1, SCSI2, etc., or Seagate1, Seagate2 etc.). Such names are likely to lose their uniqueness or get out of sequence someday even if they seem like great names today. Once you have picked names for your spindles, label them with a permanent marker. If you have hot-swappable hardware, write the names on the sleds in which the spindles are mounted. This will significantly reduce the likelihood of error when you are moving spindles around later as part of failure recovery or routine system management procedures. In the instructions that follow, Vinum will name the root spindle YouCrazy and the rootback spindle UpWindow. I will only use /dev/ad0 when I want to refer to whichever of the two spindles is currently attached as /dev/ad0.
Partition Ordering Modern disk drives operate with fairly uniform areal density across the surface of the disk. That implies that more data is available under the heads without seeking on the outer cylinders than on the inner cylinders. We will allocate partitions most critical to system performance from these outer cylinders as /stand/sysinstall generally does. The root filesystem is traditionally the outermost, even though it generally is not as critical to system performance as others. (However root can have a larger impact on performance if it contains /tmp and /var as it does in this example.) The FreeBSD boot loaders assume that the root filesystem lives in the a partition. There is no requirement that the a partition start on the outermost cylinders, but this convention makes it easier to manage disk labels. Swap performance is critical so it comes next on our way toward the center. I/O operations here tend to be large and contiguous. Having as much data under the heads as possible avoids seeking while swapping. With all the smaller partitions out of the way, we finish up the disk with /home and /usr. Access patterns here tend not to be as intense as for other filesystems (especially if there is an abundant supply of RAM and read cache hit rates are high). If the pair of spindles you have are large enough to allow for more than /home and /usr, it is fine to plan for additional filesystems here.
Assigning Partitions to Spindles We will want to assign partitions to these spindles so that either can fail without loss of data on filesystems configured for resilience. Reliability on /usr and /home is best achieved using Vinum mirroring. Resilience will have to come differently, however, for the root filesystem since Vinum is not a part of the FreeBSD boot sequence. Here we will have to settle for two identical partitions with a periodic copy from the primary to the backup secondary. The kernel already has support for interleaved swap across all available partitions so there is no need for help from Vinum here. /stand/sysinstall will automatically configure /etc/fstab for all swap partitions given. The &vinum.ap; bootstrapping method given below requires a pair of spindles that I will call the root spindle and the rootback spindle. The rootback spindle must be the same size or larger than the root spindle. These instructions first allocate all space on the root spindle and then allocate exactly that amount of space on a rootback spindle. (After &vinum.ap; is bootstrapped, there is nothing special about either of these spindles--they are interchangeable.) You can later use the remaining space on the rootback spindle for other filesystems. If you have more than two spindles, the bootvinum Perl script and the procedure below will help you initialize them for use with &vinum.ap;. However you will have to figure out how to assign partitions to them on your own.
Assigning Space to Partitions For this example, I will use two spindles: one with 4,124,673 blocks (about 2 GB) on /dev/ad0 and one with 8,420,769 blocks (about 4 GB) on /dev/ad2. It is best to configure your two spindles on separate controllers so that both can operate in parallel and so that you will have failure resilience in case a controller dies. Note that mirrored volume write performance will be halved in cases where both spindles share a controller that requires they operate serially (as is often the case with ATA controllers). One spindle will be the master on the primary ATA controller and the other will be the master on the secondary ATA controller. Recall that we will be allocating space on the smaller spindle first and the larger spindle second.
Assigning Partitions on the Root Spindle We will allocate 200,000 blocks (about 93 MB) for a root filesystem on each spindle (/dev/ad0s1a and /dev/ad2s1a). We will initially allocate 200,265 blocks for a swap partition on each spindle, giving a total of about 186 MB of swap space (/dev/ad0s1b and /dev/ad2s1b). We will lose 265 blocks from each swap partition as part of the bootstrapping process. This is the size of the space used by Vinum to store configuration information. The space will be taken from swap and given to a vinum partition but will be unavailable for Vinum subdisks. I have done the partition allocation in nice round numbers of blocks just to emphasize where the 265 blocks go. There is nothing wrong with allocating space in MB if that is more convenient for you. This leaves 4,124,673 - 200,000 - 200,265 = 3,724,408 blocks (about 1,818 MB) on the root spindle for Vinum partitions (/dev/ad0s1e and /dev/ad2s1f). From this, allocate the 265 blocks for Vinum configuration information, 1,000,000 blocks (about 488 MB) for /home, and the remaining 2,724,408 blocks (about 1,330 MB) for /usr. See below to see this graphically. The left-hand side of below shows what spindle ad0 will look like at the end of phase 2. The right-hand side shows what it will look like at the end of phase 3.
Spindle ad0 Before and After Vinum ad0 Before Vinum Offset (blocks) ad0 After Vinum +----------------------+ <-- 0--> +----------------------+ | root | | root | | /dev/ad0s1a | | /dev/ad0s1a | +----------------------+ <-- 200000--> +----------------------+ | swap | | swap | | /dev/ad0s1b | | /dev/ad0s1b | | | 400000--> +----------------------+ | | | Vinum drive YouCrazy | | | | /dev/ad0s1h | +----------------------+ <-- 400265--> +-----------------+ | | /home | | Vinum sd | | | /dev/ad0s1e | | home.p0.s0 | | +----------------------+ <--1400265--> +-----------------+ | | /usr | | Vinum sd | | | /dev/ad0s1f | | usr.p0.s0 | | +----------------------+ <--4124673--> +-----------------+----+ Not to scale Spindle /dev/ad0 Before and After Vinum
Assigning Partitions on the Rootback Spindle The /rootback and swap partition sizes on the rootback spindle must match the root and swap partition sizes on the root spindle. That leaves 8,420,769 - 200,000 - 200,265 = 8,020,504 blocks for the Vinum partition. Mirrors of /home and /usr receive the same allocation as on the root spindle. That will leave an extra 2 GB or so that we can deal with later. See below to see this graphically. The left-hand side of below shows what spindle ad2 will look like at the beginning of phase 4. The right-hand side shows what it will look like at the end.
Spindle ad2 Before and After Vinum ad2 Before Vinum Offset (blocks) ad2 After Vinum +----------------------+ <-- 0--> +----------------------+ | /rootback | | /rootback | | /dev/ad2s1e | | /dev/ad2s1a | +----------------------+ <-- 200000--> +----------------------+ | swap | | swap | | /dev/ad2s1b | | /dev/ad2s1b | | | 400000--> +----------------------+ | | | Vinum drive UpWindow | | | | /dev/ad2s1h | +----------------------+ <-- 400265--> +-----------------+ | | /NOFUTURE | | Vinum sd | | | /dev/ad2s1f | | home.p1.s0 | | | | 1400265--> +-----------------+ | | | | Vinum sd | | | | | usr.p1.s0 | | | | 4124673--> +-----------------+ | | | | Vinum sd | | | | | hope.p0.s0 | | +----------------------+ <--8420769--> +-----------------+----+ Not to scale Spindle ad2 Before and After Vinum
Preparation of Tools The bootvinum Perl script given below in will make the Vinum bootstrapping process much easier if you can run it on the machine being bootstrapped. It is over 200 lines and you would not want to type it in. At this point, I recommend that you copy it to a floppy or arrange some alternative method of making it readily available so that it can be available later when needed. For example: &prompt.root; fdformat -f 1440 /dev/fd0 &prompt.root; newfs_msdos -f 1440 /dev/fd0 &prompt.root; mount_msdos /dev/fd0 /mnt &prompt.root; cp /usr/share/examples/vinum/bootvinum /mnt XXX Someday, I would like this script to live in /usr/share/examples/vinum. Till then, please use this link to get a copy.
Bootstrapping Phase 2: Minimal OS Installation Our goal in this phase is to complete the smallest possible FreeBSD installation in such a way that we can later install Vinum. We will use only partitions of type 4.2BSD (i.e., regular UFS file systems) since that is the only type supported by /stand/sysinstall.
Phase 2 Example Start up the FreeBSD installation process by running /stand/sysinstall from installation media as you normally would. Fdisk partition all spindles as needed. Make sure to select BootMgr for all spindles. Partition the root spindle with appropriate block allocations as described above in . For this example on a 2 GB spindle, I will use 200,000 blocks for root, 200,265 blocks for swap, 1,000,000 blocks for /home, and the rest of the spindle (2,724,408 blocks) for /usr. (/stand/sysinstall should automatically assign these to /dev/ad0s1a, /dev/ad0s1b, /dev/ad0s1e, and /dev/ad0s1f by default.) If you prefer Soft Updates as I do and you are using 4.4-RELEASE or better, this is a good time to enable them. Partition the rootback spindle with the appropriate block allocations as described above in . For this example on a 4 GB spindle, I will use 200,000 blocks for /rootback, 200,265 blocks for swap, and the rest of the spindle (8,020,504 blocks) for /NOFUTURE. (/stand/sysinstall should automatically assign these to /dev/ad2s1e, /dev/ad2s1b, and /dev/ad2s1f by default.) We do not really want to have a /NOFUTURE UFS filesystem (we want a vinum partition instead), but that is the best choice we have for the space given the limitations of /stand/sysinstall. Mount point names beginning with NOFUTURE and rootback serve as sentinels to the bootstrapping script presented in below. Partition any other spindles with swap if desired and a single /NOFUTURExx filesystem. Select a minimum system install for now even if you want to end up with more distributions loaded later. Do not worry about system configuration options at this point--get Vinum set up and get the partitions in the right places first. Exit /stand/sysinstall and reboot. Do a quick test to verify that the minimum installation was successful. The left-hand side of above and the left-hand side of above show how the disks will look at this point.
Bootstrapping Phase 3: Root Spindle Setup Our goal in this phase is get Vinum set up and running on the root spindle. We will embed the existing /usr and /home filesystems in a Vinum partition. Note that the Vinum volumes created will not yet be failure-resilient since we have only one underlying Vinum drive to hold them. The resulting system will automatically start Vinum as it boots to multi-user mode.
Phase 3 Example Login as root. We will need a directory in the root filesystem in which to keep a few files that will be used in the Vinum bootstrapping process. &prompt.root; mkdir /bootvinum &prompt.root; cd /bootvinum Several files need to be prepared for use in bootstrapping. I have written a Perl script that makes all the required files for you. Copy this script to /bootvinum by floppy disk, tape, network, or any convenient means and then run it. (If you cannot get this script copied onto the machine being bootstrapped, then see below for a manual alternative.) &prompt.root; cp /mnt/bootvinum . &prompt.root; ./bootvinum bootvinum produces no output when run successfully. If you get any errors, something may have gone wrong when you were creating partitions with /stand/sysinstall above. Running bootvinum will: Create /etc/fstab.vinum based on what it finds in your existing /etc/fstab Create new disk labels for each spindle mentioned in /etc/fstab and keep copies of the current disk labels Create files needed as input to vinum for building Vinum objects on each spindle Create many alternates to /etc/fstab.vinum that might come in handy should a spindle fail You may want to take a look at these files to learn more about the disk partitioning required for Vinum or to learn more about the commands needed to create Vinum objects. We now need to install new spindle partitioning for /dev/ad0. This requires that /dev/ad0s1b not be in use for swapping so we have to reboot in single-user mode. First, reboot the system. &prompt.root; reboot Next, enter single-user mode. Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 8 seconds... Type '?' for a list of commands, 'help' for more detailed help. ok boot -s In single-user mode, install the new partitioning created above. &prompt.root; cd /bootvinum &prompt.root; disklabel -R ad0s1 disklabel.ad0s1 &prompt.root; disklabel -R ad2s1 disklabel.ad2s1 If you have additional spindles, repeat the above commands as appropriate for them. We are about to start Vinum for the first time. It is going to want to create several device nodes under /dev/vinum so we will need to mount the root filesystem for read/write access. &prompt.root; fsck -p / &prompt.root; mount / Now it is time to create the Vinum objects that will embed the existing non-root filesystems on the root spindle in a Vinum partition. This will load the Vinum kernel module and start Vinum as a side effect. &prompt.root; vinum create create.YouCrazy You should see a list of Vinum objects created that looks like the following: 1 drives: D YouCrazy State: up Device /dev/ad0s1h Avail: 0/1818 MB (0%) 2 volumes: V home State: up Plexes: 1 Size: 488 MB V usr State: up Plexes: 1 Size: 1330 MB 2 plexes: P home.p0 C State: up Subdisks: 1 Size: 488 MB P usr.p0 C State: up Subdisks: 1 Size: 1330 MB 2 subdisks: S home.p0.s0 State: up PO: 0 B Size: 488 MB S usr.p0.s0 State: up PO: 0 B Size: 1330 MB You should also see several kernel messages which state that the Vinum objects you have created are now up. Our non-root filesystems should now be embedded in a Vinum partition and hence available through Vinum volumes. It is important to test that this embedding worked. &prompt.root; fsck -n /dev/vinum/home &prompt.root; fsck -n /dev/vinum/usr This should produce no errors. If it does produce errors do not fix them. Instead, go back and examine the root spindle partition tables before and after Vinum to see if you can spot the error. You can back out the partition table changes by using disklabel -R with the disklabel.*.b4vinum files. While we have the root filesystem mounted read/write, this is a good time to install /etc/fstab. &prompt.root; mv /etc/fstab /etc/fstab.b4vinum &prompt.root; cp /etc/fstab.vinum /etc/fstab We are now done with tasks requiring single-user mode, so it is safe to go multi-user from here on. &prompt.root; ^D Login as root. Edit /etc/rc.conf and add this line: start_vinum="YES"
Bootstrapping Phase 4: Rootback Spindle Setup Our goal in this phase is to get redundant copies of all data from the root spindle to the rootback spindle. We will first create the necessary Vinum objects on the rootback spindle. Then we will ask Vinum to copy the data from the root spindle to the rootback spindle. Finally, we use dump and restore to copy the root filesystem.
Phase 4 Example Now that Vinum is running on the root spindle, we can bring it up on the rootback spindle so that our Vinum volumes can become failure-resilient. &prompt.root; cd /bootvinum &prompt.root; vinum create create.UpWindow You should see a list of Vinum objects created that looks like the following: 2 drives: D YouCrazy State: up Device /dev/ad0s1h Avail: 0/1818 MB (0%) D UpWindow State: up Device /dev/ad2s1h Avail: 2096/3915 MB (53%) 2 volumes: V home State: up Plexes: 2 Size: 488 MB V usr State: up Plexes: 2 Size: 1330 MB 4 plexes: P home.p0 C State: up Subdisks: 1 Size: 488 MB P usr.p0 C State: up Subdisks: 1 Size: 1330 MB P home.p1 C State: faulty Subdisks: 1 Size: 488 MB P usr.p1 C State: faulty Subdisks: 1 Size: 1330 MB 4 subdisks: S home.p0.s0 State: up PO: 0 B Size: 488 MB S usr.p0.s0 State: up PO: 0 B Size: 1330 MB S home.p1.s0 State: stale PO: 0 B Size: 488 MB S usr.p1.s0 State: stale PO: 0 B Size: 1330 MB You should also see several kernel messages which state that some of the Vinum objects you have created are now up while others are faulty or stale. Now we ask Vinum to copy each of the subdisks on drive YouCrazy to drive UpWindow. This will change the state of the newly created Vinum subdisks from stale to up. It will also change the state of the newly created Vinum plexes from faulty to up. First, we do the new subdisk we added to /home. &prompt.root; vinum start -w home.p1.s0 reviving home.p1.s0 (time passes . . . ) home.p1.s0 is up by force home.p1 is up home.p1.s0 is up My 5,400 RPM EIDE spindles copied at about 3.5 MBytes/sec. Your mileage may vary. Next we do the new subdisk we added to /usr. &prompt.root; vinum start -w usr.p1.s0 reviving usr.p1.s0 (time passes . . . ) usr.p1.s0 is up by force usr.p1 is up usr.p1.s0 is up All Vinum objects should be in state up at this point. The output of vinum list should look like the following: 2 drives: D YouCrazy State: up Device /dev/ad0s1h Avail: 0/1818 MB (0%) D UpWindow State: up Device /dev/ad2s1h Avail: 2096/3915 MB (53%) 2 volumes: V home State: up Plexes: 2 Size: 488 MB V usr State: up Plexes: 2 Size: 1330 MB 4 plexes: P home.p0 C State: up Subdisks: 1 Size: 488 MB P usr.p0 C State: up Subdisks: 1 Size: 1330 MB P home.p1 C State: up Subdisks: 1 Size: 488 MB P usr.p1 C State: up Subdisks: 1 Size: 1330 MB 4 subdisks: S home.p0.s0 State: up PO: 0 B Size: 488 MB S usr.p0.s0 State: up PO: 0 B Size: 1330 MB S home.p1.s0 State: up PO: 0 B Size: 488 MB S usr.p1.s0 State: up PO: 0 B Size: 1330 MB Copy the root filesystem so that you will have a backup. &prompt.root; cd /rootback &prompt.root; dump 0f - / | restore rf - &prompt.root; rm restoresymtable &prompt.root; cd / You may see errors like this: ./tmp/rstdir1001216411: (inode 558) not found on tape cannot find directory inode 265 abort? [yn] n expected next file 492, got 491 They seem to cause no harm. I suspect they are a consequence of dumping the filesystem containing /tmp and/or the pipe connecting dump and restore. Make a directory on which we can mount a damaged root filesystem during the recovery process. &prompt.root; mkdir /rootbad Remove sentinel mount points that are now unused. &prompt.root; rmdir /NOFUTURE* Create empty &vinum.ap; drives on remaining spindles. &prompt.root; vinum create create.ThruBank &prompt.root; ... At this point, the reliable server foundation is complete. The right-hand side of above and the right-hand side of above show how the disks will look. You may want to do a quick reboot to multi-user and give it a quick test drive. This is also a good point to complete installation of other distributions beyond the minimal install. Add packages, ports, and users as required. Configure /etc/rc.conf as required. After you have completed your server configuration, remember to do one more copy of root to /rootback as shown above before placing the server into production. Make a schedule to refresh /rootback periodically. It may be a good idea to mount /rootback read-only for normal operation of the server. This does, however, complicate the periodic refresh a bit. Do not forget to watch /var/log/messages carefully for errors. Vinum may automatically avoid failed hardware in a way that users do not notice. You must watch for such failures and get them repaired before a second failure results in data loss. You may see Vinum noting damaged objects at server boot time.
Where to Go from Here? Now that you have established the foundation of a reliable server, there are several things you might want to try next.
Make a Vinum Volume with Remaining Space Following are the steps to create another Vinum volume with space remaining on the rootback spindle. This volume will not be resilient to spindle failure since it has only one plex on a single spindle. Create a file with the following contents: volume hope plex name hope.p0 org concat volume hope sd name hope.p0.s0 drive UpWindow plex hope.p0 len 0 Specifying a length of 0 for the hope.p0.s0 subdisk asks Vinum to use whatever space is left available on the underlying drive. Feed these commands into vinum . &prompt.root; vinum create filename Now we newfs the volume and mount it. &prompt.root; newfs -v /dev/vinum/hope &prompt.root; mkdir /hope &prompt.root; mount /dev/vinum/hope /hope Edit /etc/fstab if you want /hope mounted at boot time.
Try Out More Vinum Commands You might already be familiar with vinum to get a list of all Vinum objects. Try following it to see more detail. If you have more spindles and you want to bring them up as concatenated, mirrored, or striped volumes, then give vinum drivelist, vinum drivelist, or vinum drivelist a try. See &man.vinum.8; for sample configurations and important performance considerations before settling on a final organization for your additional spindles. The failure recovery instructions below will also give you some experience using more Vinum commands.
Failure Scenarios This section contains descriptions of various failure scenarios. For each scenario, there is a subsection on how to configure your server for degraded mode operation, how to recover from the failure, how to exit degraded mode, and how to simulate the failure. Make a hard copy of these instructions and leave them inside the CPU case, being careful not to interfere with ventilation.
Root filesystem on ad0 unusable, rest of drive ok We assume here that the boot blocks and disk label on /dev/ad0 are ok. If your BIOS can boot from a drive other than C:, you may be able to get around this limitation.
Configure Server for Degraded Mode Use BootMgr to load kernel from /dev/ad2s1a. Hit F5 in BootMgr to select Drive 1. Hit F1 to select FreeBSD. After the kernel is loaded, hit any key but enter to interrupt the boot sequence. Boot into single-user mode and allow explicit entry of a root filesystem. Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 8 seconds... Type '?' for a list of commands, 'help' for more detailed help. ok boot -as Select /rootback as your root filesystem. Manual root filesystem specification: <fstype>:<device> Mount <device> using filesystem <fstype> e.g. ufs:/dev/da0s1a ? List valid disk boot devices <empty line> Abort manual input mountroot> ufs:/dev/ad2s1a Now that you are in single-user mode, change /etc/fstab to avoid the bad root filesystem. If you used the bootvinum Perl script from below, then these commands should configure your server for degraded mode. &prompt.root; fsck -p / &prompt.root; mount / &prompt.root; cd /etc &prompt.root; mv fstab fstab.bak &prompt.root; cp fstab_ad0s1_root_bad fstab &prompt.root; cd / &prompt.root; mount -o ro / &prompt.root; vinum start &prompt.root; fsck -p &prompt.root; ^D
Recovery Restore /dev/ad0s1a from backups or copy /rootback to it with these commands: &prompt.root; umount /rootbad &prompt.root; newfs /dev/ad0s1a &prompt.root; tunefs -n enable /dev/ad0s1a &prompt.root; mount /rootbad &prompt.root; cd /rootbad &prompt.root; dump 0f - / | restore rf - &prompt.root; rm restoresymtable
Exiting Degraded Mode Enter single-user mode. &prompt.root; shutdown now Put /etc/fstab back to normal and reboot. &prompt.root; cd /rootbad/etc &prompt.root; rm fstab &prompt.root; mv fstab.bak fstab &prompt.root; reboot Reboot and hit F1 to boot from /dev/ad0 when prompted by BootMgr.
Simulation This kind of failure can be simulated by shutting down to single-user mode and then booting as shown above in .
Drive ad2 Fails This section deals with the total failure of /dev/ad2.
Configure Server for Degraded Mode After the kernel is loaded, hit any key but Enter to interrupt the boot sequence. Boot into single-user mode. Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 8 seconds... Type '?' for a list of commands, 'help' for more detailed help. ok boot -s Change /etc/fstab to avoid the bad drive. If you used the bootvinum Perl script from below, then these commands should configure your server for degraded mode. &prompt.root; fsck -p / &prompt.root; mount / &prompt.root; cd /etc &prompt.root; mv fstab fstab.bak &prompt.root; cp fstab_only_have_ad0s1 fstab &prompt.root; cd / &prompt.root; mount -o ro / &prompt.root; vinum start &prompt.root; fsck -p &prompt.root; ^D If you do not have modified versions of /etc/fstab that are ready for use, then you can use ed to make one. Alternatively, you can fsck and mount /usr and then use your favorite editor.
Recovery We assume here that your server is up and running multi-user in degraded mode on just /dev/ad0 and that you have a new spindle now on /dev/ad2 ready to go. You will need a new spindle with enough room to hold root and swap partitions plus a Vinum partition large enough to hold /home and /usr. Create a BIOS partition (slice) on the new spindle. &prompt.root; /stand/sysinstall Select Custom. Select Partition. Select ad2. Create a FreeBSD (type 165) slice large enough to hold everything mentioned above. Write changes. Yes, you are absolutely sure. Select BootMgr. Quit Partitioning. Exit /stand/sysinstall. Create disk label partitioning based on current /dev/ad0 partitioning. &prompt.root; disklabel ad0 > /tmp/ad0 &prompt.root; disklabel -e ad2 This will drop you into your favorite editor. Copy the lines for the a and b partitions from /tmp/ad0 to the ad2 disklabel. Add the size of the a and b partitions to find the proper offset for the h partition. Subtract this offset from the size of the c partition to find the proper size for the h partition. Define an h partition with the size and offset calculated above. Set the fstype column to vinum. Save the file and quit your editor. Tell Vinum about the new drive. Ask Vinum to start an editor with a copy of the current configuration. &prompt.root; vinum create Uncomment the drive line referring to drive UpWindow and set device to /dev/ad2s1h. Save the file and quit your editor. Now that Vinum has two spindles again, revive the mirrors. &prompt.root; vinum start -w usr.p1.s0 &prompt.root; vinum start -w home.p1.s0 Now we need to restore /rootback to a current copy of the root filesystem. These commands will accomplish this. &prompt.root; newfs /dev/ad2s1a &prompt.root; tunefs -n enable /dev/ad2s1a &prompt.root; mount /dev/ad2s1a /mnt &prompt.root; cd /mnt &prompt.root; dump 0f - / | restore rf - &prompt.root; rm restoresymtable &prompt.root; cd / &prompt.root; umount /mnt
Exiting Degraded Mode Enter single-user mode. &prompt.root; shutdown now Return /etc/fstab to its normal state and reboot. &prompt.root; cd /etc &prompt.root; rm fstab &prompt.root; mv fstab.bak fstab &prompt.root; reboot
Simulation You can simulate this kind of failure by unplugging /dev/ad2, write-protecting it, or by this procedure: Shutdown to single-user mode. Unmount all non-root filesystems. Clobber any existing Vinum configuration and partitioning on /dev/ad2. &prompt.root; vinum stop &prompt.root; dd if=/dev/zero of=/dev/ad2s1h count=512 &prompt.root; dd if=/dev/zero of=/dev/ad2 count=512
Drive ad0 Fails Some BIOSes can boot from drive 1 or drive 2 (often called C: or D:), while others can boot only from drive 1. If your BIOS can boot from either, the fastest road to recovery might be to boot directly from /dev/ad2 in single-user mode and install /etc/fstab_only_have_ad2s1 as /etc/fstab. You would then have to adapt the /dev/ad2 failure recovery instructions from above. If your BIOS can only boot from drive one, then you will have to unplug drive YouCrazy from the controller for /dev/ad2 and plug it into the controller for /dev/ad0. Then continue with the instructions for /dev/ad2 failure recovery in above.
bootvinum Perl Script The bootvinum Perl script below reads /etc/fstab and current drive partitioning. It then writes several files in the current directory and several variants of /etc/fstab in /etc. These files significantly simplify the installation of Vinum and recovery from spindle failures. #!/usr/bin/perl -w use strict; use FileHandle; -my $config_tag1 = '$Id: article.sgml,v 1.14 2003-10-18 10:39:16 simon Exp $'; +my $config_tag1 = '$Id: article.sgml,v 1.15 2004-08-08 13:43:56 hrs Exp $'; # Copyright (C) 2001 Robert A. Van Valzah # # Bootstrap Vinum # # Read /etc/fstab and current partitioning for all spindles mentioned there. # Generate files needed to mirror all filesystems on root spindle. # A new partition table for each spindle # Input for the vinum create command to create Vinum objects on each spindle # A copy of fstab mounting Vinum volumes instead of BSD partitions # Copies of fstab altered for server's degraded modes of operation # See handbook for instructions on how to use the the files generated. # N.B. This bootstrapping method shrinks size of swap partition by the size # of Vinum's on-disk configuration (265 sectors). It embeds existing file # systems on the root spindle in Vinum objects without having to copy them. # Thanks to Greg Lehey for suggesting this bootstrapping method. # Expectations: # The root spindle must contain at least root, swap, and /usr partitions # The rootback spindle must have matching /rootback and swap partitions # Other spindles should only have a /NOFUTURE* filesystem and maybe swap # File systems named /NOFUTURE* will be replaced with Vinum drives # Change configuration variables below to suit your taste my $vip = 'h'; # VInum Partition my @drv = ('YouCrazy', 'UpWindow', 'ThruBank', # Vinum DRiVe names 'OutSnakes', 'MeWild', 'InMovie', 'HomeJames', 'DownPrices', 'WhileBlind'); # No configuration variables beyond this point my %vols; # One entry per Vinum volume to be created my @spndl; # One entry per SPiNDLe my $rsp; # Root SPindle (as in /dev/$rsp) my $rbsp; # RootBack SPindle (as in /dev/$rbsp) my $cfgsiz = 265; # Size of Vinum on-disk configuration info in sectors my $nxtpas = 2; # Next fsck pass number for non-root filesystems # Parse fstab, generating the version we'll need for Vinum and noting # spindles in use. my $fsin = "/etc/fstab"; #my $fsin = "simu/fstab"; open(FSIN, "$fsin") || die("Couldn't open $fsin: $!\n"); my $fsout = "/etc/fstab.vinum"; open(FSOUT, ">$fsout") || die("Couldn't open $fsout for writing: $!\n"); while (<FSIN>) { my ($dev, $mnt, $fstyp, $opt, $dump, $pass) = split; next if $dev =~ /^#/; if ($mnt eq '/' || $mnt eq '/rootback' || $mnt =~ /^\/NOFUTURE/) { my $dn = substr($dev, 5, length($dev)-6); # Device Name without /dev/ push(@spndl, $dn) unless grep($_ eq $dn, @spndl); $rsp = $dn if $mnt eq '/'; next if $mnt =~ /^\/NOFUTURE/; } # Move /rootback from partition e to a if ($mnt =~ /^\/rootback/) { $dev =~ s/e$/a/; $pass = 1; $rbsp = substr($dev, 5, length($dev)-6); print FSOUT "$dev\t\t$mnt\t$fstyp\t$opt\t\t$dump\t$pass\n"; next; } # Move non-root filesystems on smallest spindle into Vinum if (defined($rsp) && $dev =~ /^\/dev\/$rsp/ && $dev =~ /[d-h]$/) { $pass = $nxtpas++; print FSOUT "/dev/vinum$mnt\t\t$mnt\t\t$fstyp\t$opt\t\t$dump\t$pass\n"; $vols{$dev}->{mnt} = substr($mnt, 1); next; } print FSOUT $_; } close(FSOUT); die("Found more spindles than we have abstract names\n") if $#spndl > $#drv; die("Didn't find a root partition!\n") if !defined($rsp); die("Didn't find a /rootback partition!\n") if !defined($rbsp); # Table of server's Degraded Modes # One row per mode with hash keys # fn FileName # xpr eXPRession needed to convert fstab lines for this mode # cm1 CoMment 1 describing this mode # cm2 CoMment 2 describing this mode # FH FileHandle (dynamically initialized below) my @DM = ( { cm1 => "When we only have $rsp, comment out lines using $rbsp", fn => "/etc/fstab_only_have_$rsp", xpr => "s:^/dev/$rbsp:#\$&:", }, { cm1 => "When we only have $rbsp, comment out lines using $rsp and", cm2 => "rootback becomes root", fn => "/etc/fstab_only_have_$rbsp", xpr => "s:^/dev/$rsp:#\$&: || s:/rootback:/\t:", }, { cm1 => "When only $rsp root is bad, /rootback becomes root and", cm2 => "root becomes /rootbad", fn => "/etc/fstab_${rsp}_root_bad", xpr => "s:\t/\t:\t/rootbad: || s:/rootback:/\t:", }, ); # Initialize output FileHandles and write comments foreach my $dm (@DM) { my $fh = new FileHandle; $fh->open(">$dm->{fn}") || die("Can't write $dm->{fn}: $!\n"); print $fh "# $dm->{cm1}\n" if $dm->{cm1}; print $fh "# $dm->{cm2}\n" if $dm->{cm2}; $dm->{FH} = $fh; } # Parse the Vinum version of fstab written above and write versions needed # for server's degraded modes. open(FSOUT, "$fsout") || die("Couldn't open $fsout: $!\n"); while (<FSOUT>) { my $line = $_; foreach my $dm (@DM) { $_ = $line; eval $dm->{xpr}; print {$dm->{FH}} $_; } } # Parse partition table for each spindle and write versions needed for Vinum my $rootsiz; # ROOT partition SIZe my $swapsiz; # SWAP partition SIZe my $rspminoff; # Root SPindle MINimum OFFset of non-root, non-swap, non-c parts my $rspsiz; # Root SPindle SIZe my $rbspsiz; # RootBack SPindle SIZe foreach my $i (0..$#spndl) { my $dlin = "disklabel $spndl[$i] |"; # my $dlin = "simu/disklabel.$spndl[$i]"; open(DLIN, "$dlin") || die("Couldn't open $dlin: $!\n"); my $dlout = "disklabel.$spndl[$i]"; open(DLOUT, ">$dlout") || die("Couldn't open $dlout for writing: $!\n"); my $dlb4 = "$dlout.b4vinum"; open(DLB4, ">$dlb4") || die("Couldn't open $dlb4 for writing: $!\n"); my $minoff; # MINimum OFFset of non-root, non-swap, non-c partitions my $totsiz = 0; # TOTal SIZe of all non-root, non-swap, non-c partitions my $swapspndl = 0; # True if SWAP partition on this SPiNDLe while (<DLIN>) { print DLB4 $_; my ($part, $siz, $off, $fstyp, $fsiz, $bsiz, $bps) = split; if ($part && $part eq 'a:' && $spndl[$i] eq $rsp) { $rootsiz = $siz; } if ($part && $part eq 'e:' && $spndl[$i] eq $rbsp) { if ($rootsiz != $siz) { die("Rootback size ($siz) != root size ($rootsiz)\n"); } } if ($part && $part eq 'c:') { $rspsiz = $siz if $spndl[$i] eq $rsp; $rbspsiz = $siz if $spndl[$i] eq $rbsp; } # Make swap partition $cfgsiz sectors smaller if ($part && $part eq 'b:') { if ($spndl[$i] eq $rsp) { $swapsiz = $siz; } else { if ($swapsiz != $siz) { die("Swap partition sizes unequal across spindles\n"); } } printf DLOUT "%4s%9d%9d%10s\n", $part, $siz-$cfgsiz, $off, $fstyp; $swapspndl = 1; next; } # Move rootback spindle e partitions to a if ($part && $part eq 'e:' && $spndl[$i] eq $rbsp) { printf DLOUT "%4s%9d%9d%10s%9d%6d%6d\n", 'a:', $siz, $off, $fstyp, $fsiz, $bsiz, $bps; next; } # Delete non-root, non-swap, non-c partitions but note their minimum # offset and total size that're needed below. if ($part && $part =~ /^[d-h]:$/) { $minoff = $off unless $minoff; $minoff = $off if $off < $minoff; $totsiz += $siz; if ($spndl[$i] eq $rsp) { # If doing spindle containing root my $dev = "/dev/$spndl[$i]" . substr($part, 0, 1); $vols{$dev}->{siz} = $siz; $vols{$dev}->{off} = $off; $rspminoff = $minoff; } next; } print DLOUT $_; } if ($swapspndl) { # If there was a swap partition on this spindle # Make a Vinum partition the size of all non-root, non-swap, # non-c partitions + the size of Vinum's on-disk configuration. # Set its offset so that the start of the first subdisk it contains # coincides with the first filesystem we're embedding in Vinum. printf DLOUT "%4s%9d%9d%10s\n", "$vip:", $totsiz+$cfgsiz, $minoff-$cfgsiz, 'vinum'; } else { # No need to mess with size size and offset if there was no swap printf DLOUT "%4s%9d%9d%10s\n", "$vip:", $totsiz, $minoff, 'vinum'; } } die("Swap partition not found\n") unless $swapsiz; die("Swap partition not larger than $cfgsiz blocks\n") unless $swapsiz>$cfgsiz; die("Rootback spindle size not >= root spindle size\n") unless $rbspsiz>=$rspsiz; # Generate input to vinum create command needed for each spindle. foreach my $i (0..$#spndl) { my $cfn = "create.$drv[$i]"; # Create File Name open(CF, ">$cfn") || die("Can't open $cfn for writing: $!\n"); print CF "drive $drv[$i] device /dev/$spndl[$i]$vip\n"; next unless $spndl[$i] eq $rsp || $spndl[$i] eq $rbsp; foreach my $dev (keys(%vols)) { my $mnt = $vols{$dev}->{mnt}; my $siz = $vols{$dev}->{siz}; my $off = $vols{$dev}->{off}-$rspminoff+$cfgsiz; print CF "volume $mnt\n" if $spndl[$i] eq $rsp; print CF <<EOF; plex name $mnt.p$i org concat volume $mnt sd name $mnt.p$i.s0 drive $drv[$i] plex $mnt.p$i len ${siz}s driveoffset ${off}s EOF } } Manual Vinum Bootstrapping The bootvinum Perl script in makes life easier, but it may be necessary to manually perform some or all of the steps that it automates. This appendix describes how you would manually mimic the script. Make a copy of /etc/fstab to be customized. &prompt.root; cp /etc/fstab /etc/fstab.vinum Edit /etc/fstab.vinum. Change the device column of non-root partitions on the root spindle to /dev/vinum/mnt. Change the pass column of non-root partitions on the root spindle to 2, 3, etc. Delete any lines with mountpoint matching /NOFUTURE*. Change the device column of /rootback from e to a. Change the pass column of /rootback to 1. Prepare disklabels for editing: &prompt.root; cd /bootvinum &prompt.root; disklabel ad0s1 > disklabel.ad0s1 &prompt.root; cp disklabel.ad0s1 disklabel.ad0s1.b4vinum &prompt.root; disklabel ad2s1 > disklabel.ad2s1 &prompt.root; cp disklabel.ad2s1 disklabel.ad2s1.b4vinum Edit /etc/disklabel.ad?s1. On the root spindle: Decrease the size of the b partition by 265 blocks. Note the size and offset of the a and b partitions. Note the smallest offset for partitions d-h. Note the size and offset for all non-root, non-swap partitions (/home was probably on e and /usr was probably on f). Delete partitions d-h. Create a new h partition with offset 265 blocks less than the smallest offset for partitions d-h noted above. Set its size to the size of the c partition less the smallest offset for partitions d-h noted above + 265 blocks. Vinum can use any partition other than c. It is not strictly necessary to use h for all your Vinum partitions, but it is good practice to be consistent across all spindles. Set the fstype of this new partition to vinum. On the rootback spindle: Move the e partition to a. Verify that the size of the a and b partitions matches the root spindle. Note the smallest offset for partitions d-h. Delete partitions d-h. Create a new h partition with offset 265 blocks less than the smallest offset noted above for partitions d-h. Set its size to the size of the c partition less the smallest offset for partitions d-h noted above + 265 blocks. Set the fstype of this new partition to vinum. Create a file named create.YouCrazy that contains: drive YouCrazy device /dev/ad0s1h volume home plex name home.p0 org concat volume home sd name home.p0.s0 drive YouCrazy plex home.p0 len $hl driveoffset $ho volume usr plex name usr.p0 org concat volume usr sd name usr.p0.s0 drive YouCrazy plex usr.p0 len $ul driveoffset $uo Where: $hl is the length noted above for /home. $ho is the offset noted above for /home less the smallest offset noted above + 265 blocks. $ul is the length noted above for /usr. $uo is the offset noted above for /usr less the smallest offset noted above + 265 blocks. Create a file named create.UpWindow containing: drive UpWindow device /dev/ad2s1h plex name home.p1 org concat volume home sd name home.p1.s0 drive UpWindow plex home.p1 len $hl driveoffset $ho plex name usr.p1 org concat volume usr sd name usr.p1.s0 drive UpWindow plex usr.p1 len $ul driveoffset $uo Where $hl, $ho, $ul, and $uo are set as above. Acknowledgements I would like to thank Greg Lehey for writing &vinum.ap; and for providing very helpful comments on early drafts. Several others made helpful suggestions after reviewing later drafts including Dag-Erling Smørgrav, Michael Splendoria, Chern Lee, Stefan Aeschbacher, Fleming Froekjaer, Bernd Walter, Aleksey Baranov, and Doug Swarin.
diff --git a/en_US.ISO8859-1/articles/vm-design/article.sgml b/en_US.ISO8859-1/articles/vm-design/article.sgml index c77ab30396..b022a1203d 100644 --- a/en_US.ISO8859-1/articles/vm-design/article.sgml +++ b/en_US.ISO8859-1/articles/vm-design/article.sgml @@ -1,851 +1,846 @@ -%man; - -%freebsd; - - -%trademarks; + +%articles.ent; ]>
Design elements of the FreeBSD VM system Matthew Dillon
dillon@apollo.backplane.com
&tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.general; The title is really just a fancy way of saying that I am going to attempt to describe the whole VM enchilada, hopefully in a way that everyone can follow. For the last year I have concentrated on a number of major kernel subsystems within FreeBSD, with the VM and Swap subsystems being the most interesting and NFS being a necessary chore. I rewrote only small portions of the code. In the VM arena the only major rewrite I have done is to the swap subsystem. Most of my work was cleanup and maintenance, with only moderate code rewriting and no major algorithmic adjustments within the VM subsystem. The bulk of the VM subsystem's theoretical base remains unchanged and a lot of the credit for the modernization effort in the last few years belongs to John Dyson and David Greenman. Not being a historian like Kirk I will not attempt to tag all the various features with peoples names, since I will invariably get it wrong. This article was originally published in the January 2000 issue of DaemonNews. This version of the article may include updates from Matt and other authors to reflect changes in FreeBSD's VM implementation. Introduction Before moving along to the actual design let's spend a little time on the necessity of maintaining and modernizing any long-living codebase. In the programming world, algorithms tend to be more important than code and it is precisely due to BSD's academic roots that a great deal of attention was paid to algorithm design from the beginning. More attention paid to the design generally leads to a clean and flexible codebase that can be fairly easily modified, extended, or replaced over time. While BSD is considered an old operating system by some people, those of us who work on it tend to view it more as a mature codebase which has various components modified, extended, or replaced with modern code. It has evolved, and FreeBSD is at the bleeding edge no matter how old some of the code might be. This is an important distinction to make and one that is unfortunately lost to many people. The biggest error a programmer can make is to not learn from history, and this is precisely the error that many other modern operating systems have made. &windowsnt; is the best example of this, and the consequences have been dire. Linux also makes this mistake to some degree—enough that we BSD folk can make small jokes about it every once in a while, anyway. Linux's problem is simply one of a lack of experience and history to compare ideas against, a problem that is easily and rapidly being addressed by the Linux community in the same way it has been addressed in the BSD community—by continuous code development. The &windowsnt; folk, on the other hand, repeatedly make the same mistakes solved by &unix; decades ago and then spend years fixing them. Over and over again. They have a severe case of not designed here and we are always right because our marketing department says so. I have little tolerance for anyone who cannot learn from history. Much of the apparent complexity of the FreeBSD design, especially in the VM/Swap subsystem, is a direct result of having to solve serious performance issues that occur under various conditions. These issues are not due to bad algorithmic design but instead rise from environmental factors. In any direct comparison between platforms, these issues become most apparent when system resources begin to get stressed. As I describe FreeBSD's VM/Swap subsystem the reader should always keep two points in mind. First, the most important aspect of performance design is what is known as Optimizing the Critical Path. It is often the case that performance optimizations add a little bloat to the code in order to make the critical path perform better. Second, a solid, generalized design outperforms a heavily-optimized design over the long run. While a generalized design may end up being slower than an heavily-optimized design when they are first implemented, the generalized design tends to be easier to adapt to changing conditions and the heavily-optimized design winds up having to be thrown away. Any codebase that will survive and be maintainable for years must therefore be designed properly from the beginning even if it costs some performance. Twenty years ago people were still arguing that programming in assembly was better than programming in a high-level language because it produced code that was ten times as fast. Today, the fallibility of that argument is obvious—as are the parallels to algorithmic design and code generalization. VM Objects The best way to begin describing the FreeBSD VM system is to look at it from the perspective of a user-level process. Each user process sees a single, private, contiguous VM address space containing several types of memory objects. These objects have various characteristics. Program code and program data are effectively a single memory-mapped file (the binary file being run), but program code is read-only while program data is copy-on-write. Program BSS is just memory allocated and filled with zeros on demand, called demand zero page fill. Arbitrary files can be memory-mapped into the address space as well, which is how the shared library mechanism works. Such mappings can require modifications to remain private to the process making them. The fork system call adds an entirely new dimension to the VM management problem on top of the complexity already given. A program binary data page (which is a basic copy-on-write page) illustrates the complexity. A program binary contains a preinitialized data section which is initially mapped directly from the program file. When a program is loaded into a process's VM space, this area is initially memory-mapped and backed by the program binary itself, allowing the VM system to free/reuse the page and later load it back in from the binary. The moment a process modifies this data, however, the VM system must make a private copy of the page for that process. Since the private copy has been modified, the VM system may no longer free it, because there is no longer any way to restore it later on. You will notice immediately that what was originally a simple file mapping has become much more complex. Data may be modified on a page-by-page basis whereas the file mapping encompasses many pages at once. The complexity further increases when a process forks. When a process forks, the result is two processes—each with their own private address spaces, including any modifications made by the original process prior to the call to fork(). It would be silly for the VM system to make a complete copy of the data at the time of the fork() because it is quite possible that at least one of the two processes will only need to read from that page from then on, allowing the original page to continue to be used. What was a private page is made copy-on-write again, since each process (parent and child) expects their own personal post-fork modifications to remain private to themselves and not effect the other. FreeBSD manages all of this with a layered VM Object model. The original binary program file winds up being the lowest VM Object layer. A copy-on-write layer is pushed on top of that to hold those pages which had to be copied from the original file. If the program modifies a data page belonging to the original file the VM system takes a fault and makes a copy of the page in the higher layer. When a process forks, additional VM Object layers are pushed on. This might make a little more sense with a fairly basic example. A fork() is a common operation for any *BSD system, so this example will consider a program that starts up, and forks. When the process starts, the VM system creates an object layer, let's call this A: +---------------+ | A | +---------------+ A picture A represents the file—pages may be paged in and out of the file's physical media as necessary. Paging in from the disk is reasonable for a program, but we really do not want to page back out and overwrite the executable. The VM system therefore creates a second layer, B, that will be physically backed by swap space: +---------------+ | B | +---------------+ | A | +---------------+ On the first write to a page after this, a new page is created in B, and its contents are initialized from A. All pages in B can be paged in or out to a swap device. When the program forks, the VM system creates two new object layers—C1 for the parent, and C2 for the child—that rest on top of B: +-------+-------+ | C1 | C2 | +-------+-------+ | B | +---------------+ | A | +---------------+ In this case, let's say a page in B is modified by the original parent process. The process will take a copy-on-write fault and duplicate the page in C1, leaving the original page in B untouched. Now, let's say the same page in B is modified by the child process. The process will take a copy-on-write fault and duplicate the page in C2. The original page in B is now completely hidden since both C1 and C2 have a copy and B could theoretically be destroyed if it does not represent a real file). However, this sort of optimization is not trivial to make because it is so fine-grained. FreeBSD does not make this optimization. Now, suppose (as is often the case) that the child process does an exec(). Its current address space is usually replaced by a new address space representing a new file. In this case, the C2 layer is destroyed: +-------+ | C1 | +-------+-------+ | B | +---------------+ | A | +---------------+ In this case, the number of children of B drops to one, and all accesses to B now go through C1. This means that B and C1 can be collapsed together. Any pages in B that also exist in C1 are deleted from B during the collapse. Thus, even though the optimization in the previous step could not be made, we can recover the dead pages when either of the processes exit or exec(). This model creates a number of potential problems. The first is that you can wind up with a relatively deep stack of layered VM Objects which can cost scanning time and memory when you take a fault. Deep layering can occur when processes fork and then fork again (either parent or child). The second problem is that you can wind up with dead, inaccessible pages deep in the stack of VM Objects. In our last example if both the parent and child processes modify the same page, they both get their own private copies of the page and the original page in B is no longer accessible by anyone. That page in B can be freed. FreeBSD solves the deep layering problem with a special optimization called the All Shadowed Case. This case occurs if either C1 or C2 take sufficient COW faults to completely shadow all pages in B. Lets say that C1 achieves this. C1 can now bypass B entirely, so rather then have C1->B->A and C2->B->A we now have C1->A and C2->B->A. But look what also happened—now B has only one reference (C2), so we can collapse B and C2 together. The end result is that B is deleted entirely and we have C1->A and C2->A. It is often the case that B will contain a large number of pages and neither C1 nor C2 will be able to completely overshadow it. If we fork again and create a set of D layers, however, it is much more likely that one of the D layers will eventually be able to completely overshadow the much smaller dataset represented by C1 or C2. The same optimization will work at any point in the graph and the grand result of this is that even on a heavily forked machine VM Object stacks tend to not get much deeper then 4. This is true of both the parent and the children and true whether the parent is doing the forking or whether the children cascade forks. The dead page problem still exists in the case where C1 or C2 do not completely overshadow B. Due to our other optimizations this case does not represent much of a problem and we simply allow the pages to be dead. If the system runs low on memory it will swap them out, eating a little swap, but that is it. The advantage to the VM Object model is that fork() is extremely fast, since no real data copying need take place. The disadvantage is that you can build a relatively complex VM Object layering that slows page fault handling down a little, and you spend memory managing the VM Object structures. The optimizations FreeBSD makes proves to reduce the problems enough that they can be ignored, leaving no real disadvantage. SWAP Layers Private data pages are initially either copy-on-write or zero-fill pages. When a change, and therefore a copy, is made, the original backing object (usually a file) can no longer be used to save a copy of the page when the VM system needs to reuse it for other purposes. This is where SWAP comes in. SWAP is allocated to create backing store for memory that does not otherwise have it. FreeBSD allocates the swap management structure for a VM Object only when it is actually needed. However, the swap management structure has had problems historically. Under FreeBSD 3.X the swap management structure preallocates an array that encompasses the entire object requiring swap backing store—even if only a few pages of that object are swap-backed. This creates a kernel memory fragmentation problem when large objects are mapped, or processes with large runsizes (RSS) fork. Also, in order to keep track of swap space, a list of holes is kept in kernel memory, and this tends to get severely fragmented as well. Since the list of holes is a linear list, the swap allocation and freeing performance is a non-optimal O(n)-per-page. It also requires kernel memory allocations to take place during the swap freeing process, and that creates low memory deadlock problems. The problem is further exacerbated by holes created due to the interleaving algorithm. Also, the swap block map can become fragmented fairly easily resulting in non-contiguous allocations. Kernel memory must also be allocated on the fly for additional swap management structures when a swapout occurs. It is evident that there was plenty of room for improvement. For FreeBSD 4.X, I completely rewrote the swap subsystem. With this rewrite, swap management structures are allocated through a hash table rather than a linear array giving them a fixed allocation size and much finer granularity. Rather then using a linearly linked list to keep track of swap space reservations, it now uses a bitmap of swap blocks arranged in a radix tree structure with free-space hinting in the radix node structures. This effectively makes swap allocation and freeing an O(1) operation. The entire radix tree bitmap is also preallocated in order to avoid having to allocate kernel memory during critical low memory swapping operations. After all, the system tends to swap when it is low on memory so we should avoid allocating kernel memory at such times in order to avoid potential deadlocks. Finally, to reduce fragmentation the radix tree is capable of allocating large contiguous chunks at once, skipping over smaller fragmented chunks. I did not take the final step of having an allocating hint pointer that would trundle through a portion of swap as allocations were made in order to further guarantee contiguous allocations or at least locality of reference, but I ensured that such an addition could be made. When to free a page Since the VM system uses all available memory for disk caching, there are usually very few truly-free pages. The VM system depends on being able to properly choose pages which are not in use to reuse for new allocations. Selecting the optimal pages to free is possibly the single-most important function any VM system can perform because if it makes a poor selection, the VM system may be forced to unnecessarily retrieve pages from disk, seriously degrading system performance. How much overhead are we willing to suffer in the critical path to avoid freeing the wrong page? Each wrong choice we make will cost us hundreds of thousands of CPU cycles and a noticeable stall of the affected processes, so we are willing to endure a significant amount of overhead in order to be sure that the right page is chosen. This is why FreeBSD tends to outperform other systems when memory resources become stressed. The free page determination algorithm is built upon a history of the use of memory pages. To acquire this history, the system takes advantage of a page-used bit feature that most hardware page tables have. In any case, the page-used bit is cleared and at some later point the VM system comes across the page again and sees that the page-used bit has been set. This indicates that the page is still being actively used. If the bit is still clear it is an indication that the page is not being actively used. By testing this bit periodically, a use history (in the form of a counter) for the physical page is developed. When the VM system later needs to free up some pages, checking this history becomes the cornerstone of determining the best candidate page to reuse. What if the hardware has no page-used bit? For those platforms that do not have this feature, the system actually emulates a page-used bit. It unmaps or protects a page, forcing a page fault if the page is accessed again. When the page fault is taken, the system simply marks the page as having been used and unprotects the page so that it may be used. While taking such page faults just to determine if a page is being used appears to be an expensive proposition, it is much less expensive than reusing the page for some other purpose only to find that a process needs it back and then have to go to disk. FreeBSD makes use of several page queues to further refine the selection of pages to reuse as well as to determine when dirty pages must be flushed to their backing store. Since page tables are dynamic entities under FreeBSD, it costs virtually nothing to unmap a page from the address space of any processes using it. When a page candidate has been chosen based on the page-use counter, this is precisely what is done. The system must make a distinction between clean pages which can theoretically be freed up at any time, and dirty pages which must first be written to their backing store before being reusable. When a page candidate has been found it is moved to the inactive queue if it is dirty, or the cache queue if it is clean. A separate algorithm based on the dirty-to-clean page ratio determines when dirty pages in the inactive queue must be flushed to disk. Once this is accomplished, the flushed pages are moved from the inactive queue to the cache queue. At this point, pages in the cache queue can still be reactivated by a VM fault at relatively low cost. However, pages in the cache queue are considered to be immediately freeable and will be reused in an LRU (least-recently used) fashion when the system needs to allocate new memory. It is important to note that the FreeBSD VM system attempts to separate clean and dirty pages for the express reason of avoiding unnecessary flushes of dirty pages (which eats I/O bandwidth), nor does it move pages between the various page queues gratuitously when the memory subsystem is not being stressed. This is why you will see some systems with very low cache queue counts and high active queue counts when doing a systat -vm command. As the VM system becomes more stressed, it makes a greater effort to maintain the various page queues at the levels determined to be the most effective. An urban myth has circulated for years that Linux did a better job avoiding swapouts than FreeBSD, but this in fact is not true. What was actually occurring was that FreeBSD was proactively paging out unused pages in order to make room for more disk cache while Linux was keeping unused pages in core and leaving less memory available for cache and process pages. I do not know whether this is still true today. Pre-Faulting and Zeroing Optimizations Taking a VM fault is not expensive if the underlying page is already in core and can simply be mapped into the process, but it can become expensive if you take a whole lot of them on a regular basis. A good example of this is running a program such as &man.ls.1; or &man.ps.1; over and over again. If the program binary is mapped into memory but not mapped into the page table, then all the pages that will be accessed by the program will have to be faulted in every time the program is run. This is unnecessary when the pages in question are already in the VM Cache, so FreeBSD will attempt to pre-populate a process's page tables with those pages that are already in the VM Cache. One thing that FreeBSD does not yet do is pre-copy-on-write certain pages on exec. For example, if you run the &man.ls.1; program while running vmstat 1 you will notice that it always takes a certain number of page faults, even when you run it over and over again. These are zero-fill faults, not program code faults (which were pre-faulted in already). Pre-copying pages on exec or fork is an area that could use more study. A large percentage of page faults that occur are zero-fill faults. You can usually see this by observing the vmstat -s output. These occur when a process accesses pages in its BSS area. The BSS area is expected to be initially zero but the VM system does not bother to allocate any memory at all until the process actually accesses it. When a fault occurs the VM system must not only allocate a new page, it must zero it as well. To optimize the zeroing operation the VM system has the ability to pre-zero pages and mark them as such, and to request pre-zeroed pages when zero-fill faults occur. The pre-zeroing occurs whenever the CPU is idle but the number of pages the system pre-zeros is limited in order to avoid blowing away the memory caches. This is an excellent example of adding complexity to the VM system in order to optimize the critical path. Page Table Optimizations The page table optimizations make up the most contentious part of the FreeBSD VM design and they have shown some strain with the advent of serious use of mmap(). I think this is actually a feature of most BSDs though I am not sure when it was first introduced. There are two major optimizations. The first is that hardware page tables do not contain persistent state but instead can be thrown away at any time with only a minor amount of management overhead. The second is that every active page table entry in the system has a governing pv_entry structure which is tied into the vm_page structure. FreeBSD can simply iterate through those mappings that are known to exist while Linux must check all page tables that might contain a specific mapping to see if it does, which can achieve O(n^2) overhead in certain situations. It is because of this that FreeBSD tends to make better choices on which pages to reuse or swap when memory is stressed, giving it better performance under load. However, FreeBSD requires kernel tuning to accommodate large-shared-address-space situations such as those that can occur in a news system because it may run out of pv_entry structures. Both Linux and FreeBSD need work in this area. FreeBSD is trying to maximize the advantage of a potentially sparse active-mapping model (not all processes need to map all pages of a shared library, for example), whereas Linux is trying to simplify its algorithms. FreeBSD generally has the performance advantage here at the cost of wasting a little extra memory, but FreeBSD breaks down in the case where a large file is massively shared across hundreds of processes. Linux, on the other hand, breaks down in the case where many processes are sparsely-mapping the same shared library and also runs non-optimally when trying to determine whether a page can be reused or not. Page Coloring We will end with the page coloring optimizations. Page coloring is a performance optimization designed to ensure that accesses to contiguous pages in virtual memory make the best use of the processor cache. In ancient times (i.e. 10+ years ago) processor caches tended to map virtual memory rather than physical memory. This led to a huge number of problems including having to clear the cache on every context switch in some cases, and problems with data aliasing in the cache. Modern processor caches map physical memory precisely to solve those problems. This means that two side-by-side pages in a processes address space may not correspond to two side-by-side pages in the cache. In fact, if you are not careful side-by-side pages in virtual memory could wind up using the same page in the processor cache—leading to cacheable data being thrown away prematurely and reducing CPU performance. This is true even with multi-way set-associative caches (though the effect is mitigated somewhat). FreeBSD's memory allocation code implements page coloring optimizations, which means that the memory allocation code will attempt to locate free pages that are contiguous from the point of view of the cache. For example, if page 16 of physical memory is assigned to page 0 of a process's virtual memory and the cache can hold 4 pages, the page coloring code will not assign page 20 of physical memory to page 1 of a process's virtual memory. It would, instead, assign page 21 of physical memory. The page coloring code attempts to avoid assigning page 20 because this maps over the same cache memory as page 16 and would result in non-optimal caching. This code adds a significant amount of complexity to the VM memory allocation subsystem as you can well imagine, but the result is well worth the effort. Page Coloring makes VM memory as deterministic as physical memory in regards to cache performance. Conclusion Virtual memory in modern operating systems must address a number of different issues efficiently and for many different usage patterns. The modular and algorithmic approach that BSD has historically taken allows us to study and understand the current implementation as well as relatively cleanly replace large sections of the code. There have been a number of improvements to the FreeBSD VM system in the last several years, and work is ongoing. Bonus QA session by Allen Briggs <email>briggs@ninthwonder.com</email> What is the interleaving algorithm that you refer to in your listing of the ills of the FreeBSD 3.X swap arrangements? FreeBSD uses a fixed swap interleave which defaults to 4. This means that FreeBSD reserves space for four swap areas even if you only have one, two, or three. Since swap is interleaved the linear address space representing the four swap areas will be fragmented if you do not actually have four swap areas. For example, if you have two swap areas A and B FreeBSD's address space representation for that swap area will be interleaved in blocks of 16 pages: A B C D A B C D A B C D A B C D FreeBSD 3.X uses a sequential list of free regions approach to accounting for the free swap areas. The idea is that large blocks of free linear space can be represented with a single list node (kern/subr_rlist.c). But due to the fragmentation the sequential list winds up being insanely fragmented. In the above example, completely unused swap will have A and B shown as free and C and D shown as all allocated. Each A-B sequence requires a list node to account for because C and D are holes, so the list node cannot be combined with the next A-B sequence. Why do we interleave our swap space instead of just tack swap areas onto the end and do something fancier? Because it is a whole lot easier to allocate linear swaths of an address space and have the result automatically be interleaved across multiple disks than it is to try to put that sophistication elsewhere. The fragmentation causes other problems. Being a linear list under 3.X, and having such a huge amount of inherent fragmentation, allocating and freeing swap winds up being an O(N) algorithm instead of an O(1) algorithm. Combined with other factors (heavy swapping) and you start getting into O(N^2) and O(N^3) levels of overhead, which is bad. The 3.X system may also need to allocate KVM during a swap operation to create a new list node which can lead to a deadlock if the system is trying to pageout pages in a low-memory situation. Under 4.X we do not use a sequential list. Instead we use a radix tree and bitmaps of swap blocks rather than ranged list nodes. We take the hit of preallocating all the bitmaps required for the entire swap area up front but it winds up wasting less memory due to the use of a bitmap (one bit per block) instead of a linked list of nodes. The use of a radix tree instead of a sequential list gives us nearly O(1) performance no matter how fragmented the tree becomes. I do not get the following:
It is important to note that the FreeBSD VM system attempts to separate clean and dirty pages for the express reason of avoiding unnecessary flushes of dirty pages (which eats I/O bandwidth), nor does it move pages between the various page queues gratuitously when the memory subsystem is not being stressed. This is why you will see some systems with very low cache queue counts and high active queue counts when doing a systat -vm command.
How is the separation of clean and dirty (inactive) pages related to the situation where you see low cache queue counts and high active queue counts in systat -vm? Do the systat stats roll the active and dirty pages together for the active queue count? Yes, that is confusing. The relationship is goal verses reality. Our goal is to separate the pages but the reality is that if we are not in a memory crunch, we do not really have to. What this means is that FreeBSD will not try very hard to separate out dirty pages (inactive queue) from clean pages (cache queue) when the system is not being stressed, nor will it try to deactivate pages (active queue -> inactive queue) when the system is not being stressed, even if they are not being used. In the &man.ls.1; / vmstat 1 example, would not some of the page faults be data page faults (COW from executable file to private page)? I.e., I would expect the page faults to be some zero-fill and some program data. Or are you implying that FreeBSD does do pre-COW for the program data? A COW fault can be either zero-fill or program-data. The mechanism is the same either way because the backing program-data is almost certainly already in the cache. I am indeed lumping the two together. FreeBSD does not pre-COW program data or zero-fill, but it does pre-map pages that exist in its cache. In your section on page table optimizations, can you give a little more detail about pv_entry and vm_page (or should vm_page be vm_pmap—as in 4.4, cf. pp. 180-181 of McKusick, Bostic, Karel, Quarterman)? Specifically, what kind of operation/reaction would require scanning the mappings? How does Linux do in the case where FreeBSD breaks down (sharing a large file mapping over many processes)? A vm_page represents an (object,index#) tuple. A pv_entry represents a hardware page table entry (pte). If you have five processes sharing the same physical page, and three of those processes's page tables actually map the page, that page will be represented by a single vm_page structure and three pv_entry structures. pv_entry structures only represent pages mapped by the MMU (one pv_entry represents one pte). This means that when we need to remove all hardware references to a vm_page (in order to reuse the page for something else, page it out, clear it, dirty it, and so forth) we can simply scan the linked list of pv_entry's associated with that vm_page to remove or modify the pte's from their page tables. Under Linux there is no such linked list. In order to remove all the hardware page table mappings for a vm_page linux must index into every VM object that might have mapped the page. For example, if you have 50 processes all mapping the same shared library and want to get rid of page X in that library, you need to index into the page table for each of those 50 processes even if only 10 of them have actually mapped the page. So Linux is trading off the simplicity of its design against performance. Many VM algorithms which are O(1) or (small N) under FreeBSD wind up being O(N), O(N^2), or worse under Linux. Since the pte's representing a particular page in an object tend to be at the same offset in all the page tables they are mapped in, reducing the number of accesses into the page tables at the same pte offset will often avoid blowing away the L1 cache line for that offset, which can lead to better performance. FreeBSD has added complexity (the pv_entry scheme) in order to increase performance (to limit page table accesses to only those pte's that need to be modified). But FreeBSD has a scaling problem that Linux does not in that there are a limited number of pv_entry structures and this causes problems when you have massive sharing of data. In this case you may run out of pv_entry structures even though there is plenty of free memory available. This can be fixed easily enough by bumping up the number of pv_entry structures in the kernel config, but we really need to find a better way to do it. In regards to the memory overhead of a page table verses the pv_entry scheme: Linux uses permanent page tables that are not throw away, but does not need a pv_entry for each potentially mapped pte. FreeBSD uses throw away page tables but adds in a pv_entry structure for each actually-mapped pte. I think memory utilization winds up being about the same, giving FreeBSD an algorithmic advantage with its ability to throw away page tables at will with very low overhead. Finally, in the page coloring section, it might help to have a little more description of what you mean here. I did not quite follow it. Do you know how an L1 hardware memory cache works? I will explain: Consider a machine with 16MB of main memory but only 128K of L1 cache. Generally the way this cache works is that each 128K block of main memory uses the same 128K of cache. If you access offset 0 in main memory and then offset offset 128K in main memory you can wind up throwing away the cached data you read from offset 0! Now, I am simplifying things greatly. What I just described is what is called a direct mapped hardware memory cache. Most modern caches are what are called 2-way-set-associative or 4-way-set-associative caches. The set-associatively allows you to access up to N different memory regions that overlap the same cache memory without destroying the previously cached data. But only N. So if I have a 4-way set associative cache I can access offset 0, offset 128K, 256K and offset 384K and still be able to access offset 0 again and have it come from the L1 cache. If I then access offset 512K, however, one of the four previously cached data objects will be thrown away by the cache. It is extremely important… extremely important for most of a processor's memory accesses to be able to come from the L1 cache, because the L1 cache operates at the processor frequency. The moment you have an L1 cache miss and have to go to the L2 cache or to main memory, the processor will stall and potentially sit twiddling its fingers for hundreds of instructions worth of time waiting for a read from main memory to complete. Main memory (the dynamic ram you stuff into a computer) is slow, when compared to the speed of a modern processor core. Ok, so now onto page coloring: All modern memory caches are what are known as physical caches. They cache physical memory addresses, not virtual memory addresses. This allows the cache to be left alone across a process context switch, which is very important. But in the &unix; world you are dealing with virtual address spaces, not physical address spaces. Any program you write will see the virtual address space given to it. The actual physical pages underlying that virtual address space are not necessarily physically contiguous! In fact, you might have two pages that are side by side in a processes address space which wind up being at offset 0 and offset 128K in physical memory. A program normally assumes that two side-by-side pages will be optimally cached. That is, that you can access data objects in both pages without having them blow away each other's cache entry. But this is only true if the physical pages underlying the virtual address space are contiguous (insofar as the cache is concerned). This is what Page coloring does. Instead of assigning random physical pages to virtual addresses, which may result in non-optimal cache performance, Page coloring assigns reasonably-contiguous physical pages to virtual addresses. Thus programs can be written under the assumption that the characteristics of the underlying hardware cache are the same for their virtual address space as they would be if the program had been run directly in a physical address space. Note that I say reasonably contiguous rather than simply contiguous. From the point of view of a 128K direct mapped cache, the physical address 0 is the same as the physical address 128K. So two side-by-side pages in your virtual address space may wind up being offset 128K and offset 132K in physical memory, but could also easily be offset 128K and offset 4K in physical memory and still retain the same cache performance characteristics. So page-coloring does not have to assign truly contiguous pages of physical memory to contiguous pages of virtual memory, it just needs to make sure it assigns contiguous pages from the point of view of cache performance and operation.
diff --git a/en_US.ISO8859-1/articles/zip-drive/article.sgml b/en_US.ISO8859-1/articles/zip-drive/article.sgml index eba18e15d6..63f239b80e 100644 --- a/en_US.ISO8859-1/articles/zip-drive/article.sgml +++ b/en_US.ISO8859-1/articles/zip-drive/article.sgml @@ -1,287 +1,282 @@ -%man; - -%freebsd; - -%trademarks; - + +%articles.ent; ]>
&iomegazip; Drives Jason Bacon
acadix@execpc.com
 &tm-attrib.freebsd; &tm-attrib.adaptec; &tm-attrib.iomega; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.general; &iomegazip; Drive Basics &iomegazip; disks are high capacity, removable, magnetic disks, which can be read or written by ZIP drives from IOMEGA corporation. ZIP disks are similar to floppy disks, except that they are much faster, and have a much greater capacity. While floppy disks typically hold 1.44 megabytes, ZIP disks are available in two sizes, namely 100 megabytes and 250 megabytes. ZIP drives should not be confused with the super-floppy, a 120 megabyte floppy drive which also handles traditional 1.44 megabyte floppies. IOMEGA also sells a higher capacity, higher performance drive called the &jaz;/JAZZ drive. Jaz drives come in 1 gigabyte and 2 gigabyte sizes. ZIP drives are available as internal or external units, using one of three interfaces: The SCSI (Small Computer Standard Interface) interface is the fastest, most sophisticated, most expandable, and most expensive interface. The SCSI interface is used by all types of computers from PC's to RISC workstations to minicomputers, to connect all types of peripherals such as disk drives, tape drives, scanners, and so on. SCSI ZIP drives may be internal or external, assuming your host adapter has an external connector. If you are using an external SCSI device, it is important never to connect or disconnect it from the SCSI bus while the computer is running. Doing so may cause file-system damage on the disks that remain connected. If you want maximum performance and easy setup, the SCSI interface is the best choice. This will probably require adding a SCSI host adapter, since most PC's (except for high-performance servers) do not have built-in SCSI support. Each SCSI host adapter can support either 7 or 15 SCSI devices, depending on the model. Each SCSI device has its own controller, and these controllers are fairly intelligent and well standardized, (the second `S' in SCSI is for Standard) so from the operating system's point of view, all SCSI disk drives look about the same, as do all SCSI tape drives, etc. To support SCSI devices, the operating system need only have a driver for the particular host adapter, and a generic driver for each type of device, i.e. a SCSI disk driver, SCSI tape driver, and so on. There are some SCSI devices that can be better utilized with specialized drivers (e.g. DAT tape drives), but they tend to work OK with the generic driver, too. It is just that the generic drivers may not support some of the special features. Using a SCSI zip drive is simply a matter of determining which device file in the /dev directory represents the ZIP drive. This can be determined by looking at the boot messages while FreeBSD is booting (or in /var/log/messages after booting), where you will see a line something like this: da1: <IOMEGA ZIP 100 D.13> Removable Direct Access SCSI-2 Device This means that the ZIP drive is represented by the file /dev/da1. The IDE (Integrated Drive Electronics) interface is a low-cost disk drive interface used by many desktop PC's. Most IDE devices are strictly internal. Performance of IDE ZIP drives is comparable to SCSI ZIP drives. (The IDE interface is not as fast as SCSI, but ZIP drives performance is limited mainly by the mechanics of the drive, not by the bus interface.) The drawback of the IDE interface is the limitations it imposes. Most IDE adapters can only support 2 devices, and IDE interfaces are not typically designed for the long term. For example, the original IDE interface would not support hard disks with more than 1024 cylinders, which forced a lot of people to upgrade their hardware prematurely. If you have plans to expand your PC by adding another disk, a tape drive, or scanner, you may want to invest in a SCSI host adapter and a SCSI ZIP drive to avoid problems in the future. IDE devices in FreeBSD are prefixed with a a. For example, an IDE hard disk might be /dev/ad0, an IDE (ATAPI) CDROM might be /dev/acd1, and so on. The parallel port interface is popular for portable external devices such as external ZIP drives and scanners, because virtually every computer has a standard parallel port (usually used for printers). This makes things easy for people to transfer data between multiple computers by toting around their ZIP drive. Performance will generally be slower than a SCSI or IDE ZIP drive, since it is limited by the speed of the parallel port. Parallel port speed varies considerably between various computers, and can often be configured in the system BIOS. Some machines will also require BIOS configuration to operate the parallel port in bidirectional mode. (Parallel ports were originally designed only for output to printers) Parallel ZIP: The <devicename>vpo</devicename> Driver To use a parallel-port ZIP drive under FreeBSD, the vpo driver must be configured into the kernel. Parallel port ZIP drives also have a built-in SCSI controller. The vpo driver allows the FreeBSD kernel to communicate with the ZIP drive's SCSI controller through the parallel port. Since the vpo driver is not a standard part of the kernel (as of FreeBSD 3.2), you will need to rebuild the kernel to enable this device. The process of building a kernel is outlined in detail in another section. The following steps outline the process in brief for the purpose of enabling the vpo driver: Run /stand/sysinstall, and install the kernel source code on your system. Create a custom kernel configuration, that includes the driver for the vpo driver: &prompt.root; cd /sys/i386/conf &prompt.root; cp GENERIC MYKERNEL Edit MYKERNEL, change the ident line to MYKERNEL, and uncomment the line describing the vpo driver. If you have a second parallel port, you may need to copy the section for ppc0 to create a ppc1 device. The second parallel port usually uses IRQ 5 and address 378. Only the IRQ is required in the config file. If your root hard disk is a SCSI disk, you might run into a problem with probing order, which will cause the system to attempt to use the ZIP drive as the root device. This will cause a boot failure, unless you happen to have a FreeBSD root file-system on your ZIP disk! In this case, you will need to wire down the root disk, i.e. force the kernel to bind a specific device to /dev/da0, the root SCSI disk. It will then assign the ZIP disk to the next available SCSI disk, e.g. /dev/da1. To wire down your SCSI hard drive as da0, change the line device da0 to disk da0 at scbus0 target 0 unit 0 You may need to change the target above to match the SCSI ID of your disk drive. You should also wire down the scbus0 entry to your controller. For example, if you have an &adaptec; 15xx controller, you would change controller scbus0 to controller scbus0 at aha0 Finally, since you are creating a custom kernel configuration, you can take the opportunity to remove all the unnecessary drivers. This should be done with a great deal of caution, and only if you feel confident about making modifications to your kernel configuration. Removing unnecessary drivers will reduce the kernel size, leaving more memory available for your applications. To determine which drivers are not needed, go to the end of the file /var/log/messages, and look for lines reading "not found". Then, comment out these devices in your config file. You can also change other options to reduce the size and increase the speed of your kernel. Read the section on rebuilding your kernel for more complete information. Now it is time to compile the kernel: &prompt.root; /usr/sbin/config MYKERNEL &prompt.root; cd ../../compile/MYKERNEL &prompt.root; make clean depend && make all install After the kernel is rebuilt, you will need to reboot. Make sure the ZIP drive is connected to the parallel port before the boot begins. You should see the ZIP drive show up in the boot messages as device vpo0 or vpo1, depending on which parallel port the drive is attached to. It should also show which device file the ZIP drive has been bound to. This will be /dev/da0 if you have no other SCSI disks in the system, or /dev/da1 if you have a SCSI hard disk wired down as the root device. Mounting ZIP disks To access the ZIP disk, you simply mount it like any other disk device. The file-system is represented as slice 4 on the device, so for SCSI or parallel ZIP disks, you would use: &prompt.root; mount_msdos /dev/da1s4 /mnt For IDE ZIP drives, use: &prompt.root; mount_msdos /dev/ad1s4 /mnt It will also be helpful to update /etc/fstab to make mounting easier. Add a line like the following, edited to suit your system: /dev/da1s4 /zip msdos rw,noauto 0 0 and create the directory /zip. Then, you can mount simply by typing &prompt.root; mount /zip and unmount by typing &prompt.root; umount /zip For more information on the format of /etc/fstab, see &man.fstab.5;. You can also create a FreeBSD file-system on the ZIP disk using &man.newfs.8;. However, the disk will only be usable on a FreeBSD system, or perhaps a few other &unix; clones that recognize FreeBSD file-systems. (Definitely not DOS or &windows;.)
diff --git a/en_US.ISO8859-1/books/arch-handbook/book.sgml b/en_US.ISO8859-1/books/arch-handbook/book.sgml index 3401257fce..06a645e210 100644 --- a/en_US.ISO8859-1/books/arch-handbook/book.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/book.sgml @@ -1,215 +1,210 @@ -%bookinfo; - -%man; - -%freebsd; - %chapters; - %mac-entities; - %authors - %mailing-lists; - -%urls; + +%books.ent; + +%chapters; + +%mac-entities; + ]> &os; Architecture Handbook The FreeBSD Documentation Project August 2000 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.trademarks; &bookinfo.legalnotice; Welcome to the &os; Architecture Handbook. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD World Wide Web server. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. Kernel &chap.boot; &chap.locking; &chap.kobj; &chap.jail; &chap.sysinit; &chap.mac; &chap.vm; &chap.smp; * UFS UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling, locking, metadata, soft-updates, LFS, portalfs, procfs, vnodes, memory sharing, memory objects, TLBs, caching * AFS AFS, NFS, SANs, etc. * Syscons Syscons, tty, PCVT, serial console, screen savers, etc. * Compatibility Layers * Linux Linux, SVR4, etc. Device Drivers &chap.driverbasics; &chap.isa; &chap.pci; &chap.scsi; &chap.usb; &chap.newbus; &chap.snd; &chap.pccard; Appendices Marshall Kirk McKusick Keith Bostic Michael J Karels John S Quarterman 1996Addison-Wesley Publishing Company, Inc. 0-201-54979-4 Addison-Wesley Publishing Company, Inc. The Design and Implementation of the 4.4 BSD Operating System 1-2 diff --git a/en_US.ISO8859-1/books/bibliography/book.sgml b/en_US.ISO8859-1/books/bibliography/book.sgml index 0e4df7e775..61ed0f7ef2 100644 --- a/en_US.ISO8859-1/books/bibliography/book.sgml +++ b/en_US.ISO8859-1/books/bibliography/book.sgml @@ -1,36 +1,39 @@ +%books.ent; + ]> FreeBSD Bibliography The FreeBSD Documentation Project February 1999 2001 The FreeBSD Documentation Project &bibliography; diff --git a/en_US.ISO8859-1/books/corp-net-guide/book.sgml b/en_US.ISO8859-1/books/corp-net-guide/book.sgml index d1ef4ecbe9..bda8f553d7 100644 --- a/en_US.ISO8859-1/books/corp-net-guide/book.sgml +++ b/en_US.ISO8859-1/books/corp-net-guide/book.sgml @@ -1,3219 +1,3222 @@ - + +%books.ent; +]> The FreeBSD Corporate Networker's Guide Ted Mittelstaedt 2001 Addison-Wesley Longman, Inc (Original English language edition) 2001 Pearson Educational Japan (Japanese language translation) ENGLISH LANGUAGE EDITION ISBN: 0-201-70481-1 JAPANESE LANGUAGE EDITION ISBN: 4-89471-464-7 The eighth chapter of the book, The FreeBSD Corporate Networker's Guide is excerpted here with the permission of the publisher. No part of it may be further reproduced or distributed without the publisher's express written Chanda.Leary-Coutu@awl.com. The other chapters of the book covers topics such as system administration, fileserving, and e-mail delivery. More information about this book is available from the publisher, with whom you can also sign up to receive news of related titles. The author's web site for the book includes sample code, working examples, errata and a Q&A forum, and is available at . Printserving Printserving is a complicated topic. There are many different software interfaces to printers, as well as a wide variety of printer hardware interfaces. This chapter covers the basics of setting up a print queue, using Samba to print, and administering print queues and connections. PC printing history In the early days of the personal computer, printing was simple. The PC owner bought a cheap printer, usually a dot matrix that barely supported ASCII, and plugged it into the computer with a parallel cable. Applications would either work with the printer or not, and most did because all they could do was output DOS or ASCII text. The few software applications that supported graphics generally could only output on specific makes and models of printers. Shared network printing, if it existed, was usually done by some type of serial port switchbox. This was the general state of affairs with the PC until the Windows operating system was released. All at once, application programmers were finally free of the restrictions of worrying about how some printer manufacturer would change printer control codes. Graphics printing, in the form of fonts and images, was added to most applications, and demand for it rapidly increased across the corporation. Large, high-capacity laser printers designed for office printing appeared on the scene. Printing went from 150 to 300 to 600 dpi for the common desktop laser printer. Today organizational network printing is complex, and printers themselves are more complicated. Most organizations find that sharing a few high-quality laser printers is much more cost effective than buying many cheaper dot matrix units. Good network print serving is a necessity, and it can be very well provided by the FreeBSD UNIX system. Printer communication protocols and hardware Printers that don't use proprietary vendor codes communicate with computers using one or more of three major printing protocols. The communication is done over a hardware cable that can be a parallel connection (printer port) or a serial connection (COM port). ASCII Printing Protocol The ASCII protocol is the simplest protocol used, as well as the oldest. ASCII is also used to represent text files internally in the DOS, UNIX, and Windows operating systems. Therefore, data taken from a text file or a directory listing generally requires little preparation before being sent to the printer, other than a newline-to-carriage return/linefeed conversion for UNIX. Printers usually follow the DOS text file convention of the print head requiring an explicit carriage return character followed by a linefeed character at the end of a line of text. Since UNIX uses only the linefeed character to terminate text, an additional carriage return character must be added to the end of each line in raw text print output; otherwise, text prints in a stairstep output. (Some printers have hardware or software switches to do the conversion.) PostScript Printing Protocol Adobe introduced the PostScript language in 1985; it is used to enable the printout of high quality graphics and styled font text. PostScript is now the de-facto print standard in the UNIX community, and the only print standard in the Macintosh community. Numerous UNIX utilities exist to beautify and enhance text printing with PostScript. PostScript can be used to download font files into a printer as well as the data to be printed. PostScript commands can be sent to instruct the printer CPU to image, rotate, and scale complex graphics and images, thus freeing the host CPU. Scaling is particularly important with fonts since the document with the font has been produced on a computer screen with far lower resolution than the printer. For example, a 1024x768 computer screen on a 17-inch monitor allows for a resolution of approximately 82dpi, a modern desktop printer prints at a resolution of 600dpi. Therefore, a font must be scaled at least seven times larger for WYSIWYG output! PostScript printers generally come with a number of resident fonts. For example, the NEC Silentwriter 95 contains Courier, Helvetica, ITC Avant Garde Gothic Book, ITC Bookman Light, New Century Schoolbook Roman, Palatino Roman, Times Roman, and several symbol fonts. These are stored in Read Only Memory (ROM) in the printer. When a page is printed from a Windows client that contains a font not in the printer, a font substitution table is used. If no substitute can be made, Courier is usually used. The user should be conscious of this when creating documents - documents with fonts not listed in the substitution table may cause other users problems when printing. Avoid use of strange fonts for documents that will be widely distributed. The user program can choose to download different fonts as outline fonts to the PostScript printer if desired. Fonts that are commonly used by the user are often downloaded to PostScript printers that are connected directly to the user's computer, the fonts are then available to successive print jobs until the printer is turned off. When PostScript printers are networked, the clients must download any fonts desired with each print job. Since jobs come from different clients, the clients cannot assume that downloaded fonts will still be in the printer. PostScript print jobs also contain a header that is sent describing the page layout, among other things. On a shared network printer, this header must also be downloaded with each print job. Although some PostScript drivers allow downloading of the header only once, this usually requires a bi-directional serial connection to the printer, instead of a unidirectional parallel connection. PostScript print jobs can be sent either as binary data or as ASCII. The main advantage of binary data transmission is that it is faster. However, not all PostScript printers support it. Also, fonts can generally not be downloaded in binary. When FreeBSD is used as a printserver, ASCII PostScript printing should be selected on the clients, this is generally the default with most PostScript drivers. The Adobe company licenses PostScript interpreters as well as resident fonts to printer manufacturers, and extracts a hefty license fee from any printer manufacturer who wants to use them in its printer. This presents both a benefit and a problem to the end user. Although a single company holding control over a standard can guarantee compliance, it does significantly raise the cost of the printer. As a result, PostScript has not met with much success in the lower-end laser and inkjet Windows printing market, despite the fact that Adobe distributes PostScript software operating system drivers for free. One issue that is a concern when networking PostScript printers is the selection of banner page, (also known as header page, or burst page) printing. UNIX shared printing began with ASCII line printers, and since UNIX is a multiuser system, often many different user print jobs piled up in the printer output hopper. To separate these jobs the UNIX printing system programs support banner page printing if the client program that submits jobs asks for them. These pages print at the beginning or end of every print job and contain the username, submittal date, and so on.. By default, most clients, whether remote (e.g., a Windows LPR client) or local (e.g., the /usr/bin/lpr program) trigger a banner page to be printed. One problem is that some PostScript printers abort the entire job if they get unformatted ASCII text instead of PostScript. (In general, PostScript printers compatible with Hewlett-Packard Printer Control Language [HPPCL] handle banners without problems) Banner printing should be disabled for any printers with this problem, unless PostScript banner page printing is set up on the server. HPPCL Printing Protocol The Hewlett Packard company currently holds the largest market share of desktop inkjet and office laser printers. Back when Windows was released, HP decided to expand into the desktop laser jet market with the first LaserJet series of printers. At the time there was much pressure on Microsoft to use Adobe Type Manager for scaleable fonts within Windows, and to print PostScript to higher-end printers. Microsoft decided against doing this and used a technically inferior font standard, Truetype. They thought that it would be unlikely that the user would download fonts to the printer, since desktop Publishing was not being done on PC's at the time. Instead users would rasterize the entire page to the printer using whatever proprietary graphics printer codes the selected printer needed. HP devised HPPCL for their LaserJets, and make PostScript an add-on. The current revision of HPPCL now allows for many of the same scaling and font download commands that PostScript does. HP laser jet printers that support PostScript can be distinguished by the letter "M" in their model number. (M is for Macintosh, since Macintosh requires PostScript to print) For example, the HP 6MP has PostScript, the 6P doesn't. HPPCL has almost no support in the UNIX applications market, and it is very unlikely that any will appear soon. One big reason is the development of the free Ghostscript PostScript interpreter. Ghostscript can take a PostScript input stream and print it on a PCL printer under UNIX. Another reason is the UNIX community's dislike of reinventing the wheel. HPPCL has no advantage over PostScript, and in many ways there are fewer problems with PostScript. Considering that PostScript can be added to a printer, either by hardware or use of Ghostscript, what is the point of exchanging an existing working solution for a slightly technically inferior one? Over the life of the printer, taking into account the costs of toner, paper, and maintenance, the initial higher cost of PostScript support is infinitesimal. Network Printing Basics The most common network printing implementation is a printserver accepting print jobs from clients tied to the server via a network cable. Printservers The term "printserver" is one of those networking terms, like packet, that has been carelessly tossed around until its meaning has become somewhat confusing and blurred. To be specific, a printserver is simply a program that arbitrates print data from multiple clients for a single printer. Printservers can be implemented in one of the four methods described in the following sections. Printserver on the fileserver The printer can be physically cabled to the PC running the Network OS. Print jobs are submitted by clients to the printserver software on the fileserver, which sends them down the parallel or serial cable to the printer. The printer must be physically close to the fileserver. This kind of printserving is popular in smaller workgroup networks, in smaller offices.
Printserver on the fileserver ,---------. | ======= | Server | ======= | +---------------------+ ,-----. +-----------+ | +---------------+ | | | | Printer [ ]------------[ ] | Printserver | | |_____| +-----------+ Parallel | | Software | [ ]------_________ Cable | +---------------+ | / ::::::: \ +---------------------+ `---------' Network PC Printer, connected to a network server running printserver software, with one or more network PCs printing through it.
Printserver on a separate PC It is possible to run a print server program on a cheap PC that is located next to the printer and plugged into it via parallel cable. This program simply acts as a pass-through program, taking network packets from the network interface and passing them to the printer. This kind of server doesn't allow any manipulation of print jobs, jobs usually come from a central fileserver, where jobs are controlled.
Printserver on a separate PC Fileserver ,----------------. ,---------. .---| | === | | ======= | ,-----. | `----------======' | ======= | | | | +-----------+ |_____| | | Printer [ ]------------_________---------| Ethernet +-----------+ Parallel / ::::::: \ | Cable `---------' | Printserver | ,-----. | | | | |_____| `---------_________ / ::::::: \ `---------' Network PC Printer connected to a printserver (typically running FreeBSD), with network files hosted on a separate machine, and a network PC, able to access both resources.
Printserver on a separate hardware box A printserver on a separate hardware box is exemplified by network devices such as the Intel Netport, the HP JetDirect Ex, the Osicom/DPI NETPrint, and the Lexmark MarkNet. Basically, these are plastic boxes with an Ethernet connection on one side and a parallel port on the other. Like a printserver on a PC, these devices don't allow remote job manipulation, and merely pass packets from the network down the parallel port to the printer.
Printserver on a separate hardware box Fileserver ,----------------. ,---------. .---| | === | | ======= | | `----------======' | ======= | Printserver | +-----------+ ,--------. | | Printer [ ]-----------[ ] ooo [ ]-------| Ethernet +-----------+ Parallel `--------' | Cable | | ,-----. | | | | |_____| `---------_________ / ::::::: \ `---------' Network PC Printer connected to a dedicated print server appliance.
Printserver in the Printer The HP JetDirect Internal is the best known printserver of this type. It is inserted into a slot in the printer case, and it works identically to the external JetDirect units.
Printserver in the printer Fileserver ,----------------. ,---------. .---| | === | | ======= | | `----------======' | ======= | | +-----------+ | | Printer [ ]------------------------------| Ethernet +-----------+ | | | ,-----. | | | | |_____| `---------_________ / ::::::: \ `---------' Network PC Printer with an embedded print server, connecting directly to the local network.
Printspools Printspooling is an integral part of network printing. Since the PC can spit out data much faster than the printer can accept it, the data must be buffered in a spool at some location. In addition, because many clients share printers, when clients send print jobs at the same time, jobs must be placed on a queue so that one can be printed after the other. Logical location of the print spool Printspooling can be implemented at one of three locations The client. Clients can be required to spool their own print jobs on their own disks. For example, when a Windows client application generates a print job the job must be placed on the local client's hard drive. Once the remote print server is free to accept the job it signals the client to start sending the job a bit at a time. Client spooling is popular in peer-to-peer networks with no defined central fileserver. However, it is impossible for a central administrator to perform advanced print job management tasks such as moving a particular print job ahead of another, or deleting jobs. The printserver. If each printer on the network is allocated their own combination print spooler-printserver, jobs can stack at the printer. Many of the larger printers with internal printservers have internal hard disks for this purpose. Although this enables basic job management, it still restricts the ability to move jobs from one printer to another. A central print spooler on a fileserver. Print jobs are received from all clients on the network in the spool and then dispatched to the appropriate printer. This scheme is the best for locations with several busy printers and many clients. Administration is extremely simple because all print jobs are spooled on a central server, which is particularly important in bigger organizations. Many large organizations have standardized on PostScript printing for all printing; in the event that a particular printer fails and is offline, incoming PostScript print jobs can be rerouted automatically to another printer. Since all printers and clients are using PostScript, clients don't need to be reconfigured when this happens. Print jobs appear the same whether printed on a 4 page-per-minute NEC Silentwriter 95, or a 24 page-per-minute HP LaserJet 5SiMX if both printers are defined in the client as PostScript printers.
Print spool locations Client ,---------. PC | ======= | ,-----. | ======= | | | +-----------+ |_____| | Printer [ ]---------------------------------------------------_________ +-----------+ / ::::::: \ `---------' Spool Printserver ,---------. PC | ======= | ,-----. | ======= | | | +-----------+ ,----------------. |_____| | Printer [ ]--------------| | === |-------------------_________ +-----------+ `----------======' / ::::::: \ Spool `---------' Fileserver ,---------. PC | ======= | ,-----. | ======= | Printserver Fileserver | | +-----------+ ,----------------. ,----------------. |_____| | Printer [ ]----| | === |-----| | === |------_________ +-----------+ `----------======' `----------======' / ::::::: \ Spool `---------' Possible locations for the print spool
FreeBSD is an excellent platform to implement centralized printserving and print spooling. The rest of this chapter concentrates on the centralized print spooler model. Note that PostScript printing is not a requirement for this model--the HPPCL protocol can be the standard print protocol as well. For transparent printing between printers with HPPCL, however, the printer models must be similar. Physical location of the print spool In some companies, the central fileserver is often placed in a closet, locked away. Printers, on the other hand, are best located in high traffic areas for ease of use. Network printing works best when the printers are evenly distributed throughout the organization. Attempting to place all the major printers in one location, as technically advantageous as it may seem, merely provokes users to requisition smaller printers that are more convenient for that quick print job. The administrator may end up with a datacenter full of nice, expensive printers that are never used, while the smaller personal laser printers scattered throughout the plant bear most of the printing load. The big problem with this is that scattering printers through the organization makes it difficult to utilize the 3 possible parallel ports on the fileserver due to parallel port distance limitations. Although high-speed serial ports may extend the distance, not many printers have good serial ports on them. This is where the hardware network print server devices can come into play. I prefer using these devices because they are much cheaper and more reliable than a standalone PC running printserver software. For example, Castelle sells the LANpress 1P/10BT printserver for about $170.00. Using these devices a FreeBSD UNIX server can have dozens of print spools accepting print jobs and then route them back out over the network to these remote printserver boxes. If these hardware servers are used, they must support the Line Printer Daemon (LPD) print protocol. With a scheme like this it is important to have enough disk space on the spool to handle the print jobs. A single large PowerPoint presentation PostScript print job containing many graphics may be over 100MB. When many such jobs stack up in the print spool waiting to print, the print spooler should have several gigabytes of free disk space available. Network Printing to Remote Spools Although several proprietary network printing protocols such as Banyan Vines and NetWare, are tied to proprietary network protocols, FreeBSD UNIX can use two TCP/IP network printing protocols to print to remote print spools. The two print protocols available on TCP/IP with FreeBSD are the open LPD protocol and the NetBIOS-over-TCP/IP Server Messaging Block (SMB) print protocol first defined by Intel and Microsoft and later used by IBM and Microsoft. The LPD protocol is defined in RFC1179. This network protocol is the standard print protocol used on all UNIX systems. LPD client implementations exist for all Windows operating systems and DOS. Microsoft has written LPD for the Windows NT versions, the other Windows operating system implementations are provided by third parties. The Microsoft Networking network protocol that runs on top of SMB can use NetBIOS over TCP/IP as defined in RFC1001 and RFC1002. This protocol has a specification for printing that is the same print protocol used to send print jobs to NT Server by Microsoft clients. To implement this protocol on FreeBSD requires the installation of the Samba client suite of programs discussed in Chapter 7. Setting up LPR on Windows clients The program clients use to print via LPD is the Line Printer Remote, or LPR program. The following instructions cover enabling this program on Windows clients. Windows 3.1/Windows for Workgroups 3.11 Several commercial TCP/IP stacks are available for Win31, that provide LPR client programs, in addition to the basic TCP/IP protocol to Win31. WfW has TCP/IP networking available for free from Microsoft, but it doesn't include an LPR client. Unfortunately, I have not come across a freeware implementation of a 16-bit Windows LPR client, so with the following instructions I use the Shareware program WLPRSPL available from . This program must be active during client printing, and is usually placed in the Startup group. Organizations that want to use UNIX as a printserver to a group of Win31 clients without using a commercial or shareware LPR program have another option. The Microsoft Networking client for DOS used underneath Win31 contains SMB-based printing which is covered later in the chapter. DOS networking client setup and use are covered in Chapter 2 and Chapter 7. If LPR-based client printing is desired and the organization doesn't want to upgrade to Win95, (which has several LPR clients available) the following instructions can be used. WLPRSPL needs a Winsock under Windows 3.1, so for the example I explain the setup of the Novell 16-bit TCP/IP client. The stack can be FTPed from Novell, and is easy to integrate into sites that already use the 16-bit NetWare networking client, usually NW 3.11 and 3.12. In most cases, however, sites that use NetWare + Win31 are probably best off printing through the NetWare server, then loading an LPR spooler as an Netware Loadable Module (NLM) to send the job over to FreeBSD. As an alternate, the Microsoft Networking DOS 16-bit TCP/IP client under Win31 contains a Winsock, as does Microsoft TCP/IP for WfW. The target machine used here is a Compaq Deskpro 386/33 with 12MB of ram with an operating version of Windows 3.1, and a 3com 3C579 EISA network card. The instructions assume an LPR printserver on the network, named mainprinter.my.domain.com with a print queue named RAW. Use the installation instructions in Exhibit 8.1 for a quick and dirty TCP/IP Winsock for Win31 systems. Administrators who already have the Novell IPX client installed should skip those steps. Installation of the Novell TCP/IP Winsock client Make sure that the machine has enough environment space (2048 bytes or more) by adding the following line to the config.sys file and rebooting: SHELL=C:\COMMAND.COM /E:2048 /P Obtain the TCP16.EXE file from . Obtain the Network Adapter support diskette for the network card in your machine. This should be supplied with the card, or available via FTP from the network adapter manufacturer's FTP site. Now you need the file LSL.COM. This is available on some Network Adapter Driver diskettes, it used to be available from the VLM121_2.EXE file from Novell but unfortunately this file is no longer publicly accessible from Novell. If you have vlm121_2.exe in a temporary directory, run it. This will extract a number of files. One of the files extracted is LSL.CO_ extract this file with the command nwunpack lsl.co_. Create the directory c:\nwclient. Then, copy lsl.com from the temporary directory into the directory. Obtain and install the printer driver for the model of printer that you will be spooling to and point it to LPT1:. Win31 and WfW 3.11 have an incomplete printer driver list, so if you need a driver Microsoft has many Win16 printer drivers on their FTP site. A list is available at . In addition, if you are installing a PostScript printer driver for a printer supplied in Win31, it may be necessary to patch the driver. The Microsoft PostScript driver supplied in Win31 is version 3.5. (The patch named PSCRIP.EXE which brought the PostScript driver to version 3.58 is no longer publicly available.) WfW already uses the more recent PostScript driver, as does Win31 version A. Installing the Adobe PostScript driver for Win31 is also an option. (see for the version 3.1.2 Win31 PostScript driver). Look on the network adapter driver disk for the subdirectory nwclient/ and then look for the ODI driver for the adapter card. For example, on the 3com 3C509/3C579 adapter driver disk, the driver and location are \NWCLIENT\3C5X9.COM. Copy this driver to the c:\nwclient directory. Create a file called NET.CFG in the c:\nwclient directory. Often, the network card adapter driver diskette has a template for this file in the same location as the ODI driver. This can be modified, as can the following example: LINK SUPPORT BUFFERS 4 1600 MEMPOOL 8192 LINK DRIVER 3C5X9 ; PORT 300 (these are optional, if needed by card uncomment) ; INT 10 (optional, uncomment and modify if needed) Attempt to load the network card driver. First load lsl, then the ODI driver. With the 3com card the commands are: lsl 3c5x9 If the driver properly loads it will list the hardware port and interrupt settings for the network adapter. If it has loaded properly, unload the drivers in reverse order with the command: 3c5x9 /u lsl /u Go to the temporary directory that contains the tcp16.exe file and extract it by running the program. Run the install batch file by typing installr. It should list New Installation detected. It will then copy a number of files into nwclient, add some commented-out sections to net.cfg, and call edit on net.cfg. Read the editing instructions and make the appropriate entries. The sample net.cfg file from above would look like this. LINK SUPPORT BUFFERS 4 1600 MEMPOOL 8192 LINK DRIVER 3C5X9 FRAME ETHERNET_II Protocol TCPIP PATH TCP_CFG c:\nwclient ip_address 192.168.1.54 LAN_NET ip_netmask 255.255.255.0 LAN_NET ip_router 192.168.1.1 LAN_NET Bind 3C5X9 #1 Ethernet_II LAN_NET Save and exit, the Installer should list TCP16 installation completed. Reload the client with the commands: lsl 3c5x9 tcpip The TCP/IP driver should list the IP numbers and other information. Optionally, create either a HOSTS file, or a RESOLV.CFG file (pointing to a nameserver) in c:\nwclient. Check to see this is operating properly by pinging a hostname. Add the c:\nwclient directory to the PATH, as well as the 3 startup commands in step 15 in autoexec.bat Installation of the LPR client on 16-bit Windows with a Winsock installed The following assumes a running Win31 installation with a Winsock or a running WfW installation with the 32-bit Microsoft TCP/IP protocol installed. Install the printer driver desired. See step 8 of the previous set of instructions. Obtain and extract into a temporary directory the wlprs41.zip file from the location mentioned above. Run setup.exe from the temporary directory containing the wlprs files. In setup, accept default directory, and check Yes to add to its own group. Click Continue when asked for group name, and check whatever choice you want when asked to copy the doc files. Click No when asked to add the program to Startup. On the UNIX FreeBSD print spooler, make sure that there is an entry in /etc/hosts.lpd or /etc/hosts.equiv for the client workstation, thereby allowing it to submit jobs. Double-click the Windows LPR Spooler icon in the Windows LPR Spooler group that is opened. When it asks for a valid spool directory, just select the c:\wlprspl directory that the program installed its files into. When asked for a valid Queue Definition File, just click OK to use the default filename. The program automatically creates a queue definition file. The program opens up with its menu. Click Setup in the top menu, then select Define New Queue. For a local spool filename, just use the name of the remote queue (RAW) to which the client prints. For the remote printer name, use the same name as the remote queue (RAW) to which the client prints. For the remote hostname, use the machine name of the FreeBSD print spooler. mainprinter.ayedomain.com. For the Description, enter a description such as 3rd floor Marketing printer. For the protocol, leave the default of BSD LPR/LPD selected. Click on the Queue Properties, and make sure that the Print unfiltered is selected. If you're printing PostScript, then also click the Advanced options button. Make sure that Remove trailing Ctrl-D is unchecked, and that Remove Leading Ctrl-D is checked. Also with PostScript, if the printer cannot print ASCII, uncheck the Send header page box. (PostScript header/banner pages are discussed later in this chapter) Click OK. At the main menu of the program, click File, then Control Panel/Printers to bring up the Printers control panel of Windows. Make sure that the Use Print Manager button is checked, then highlight the printer driver and click the Connect button. Scroll down to the C:\WLPRSPL\RAW entry for the spool that was built and highlight this. Click OK. Minimize the Windows LPR Spooler. Copy the Windows LPR Spooler icon to the Startup group. Click File/Properties with the Windows LPR Spooler icon highlighted in the Startup group. Check the Run Minimized button. Exit Windows, and when the Save queue changes? button comes up, click Yes. Restart windows and make sure that the spooler starts up. Open the Control Panel and look for a new yellow icon named Set Username If you are running the Novell or other Winsock under Win31, click on this icon and put the username of the person using this computer into the space provided. If you are running WfW, this isn't necessary because Windows will supply the username. If the spooler is not started properly in some installations, there may be a bug. If placing the icon in the Startup group doesn't actually start the spooler, the program name can be placed in the run= line of win.ini. Try printing a print job from an application such as Notepad. If everything goes properly, clicking on the Queues/Show remote printer status" in the Windows LPR menu should show the print job spooled and printing on the remote printserver. Installation of LPR client on Windows 95/98 The wlprspl program also can be used under Windows 95, but as a 16-bit program, it is far from an optimal implementation on a 32-bit operating system. In addition, Win95 and its derivatives fundamentally changed from Windows 3.1 in the printing subsystem. For these reasons I use a different LPR client program for Win95/98 LPR printing instructions. It is a full 32-bit print program, and it installs as a Windows 32-bit printer port monitor. The program is called ACITS LPR Remote Printing for Windows 95 and it is located at . ACITS stands for Academic Computing and Instructional Technologies Services. The ACITS LPR client includes software developed by the University of Texas at Austin and its contributors, it was written by Glenn K. Smith, a systems analyst with the Networking Services group at the university. The filename of the archive in the original program was ACITSLPR95.EXE and as of version 1.4 it was free for individuals or organizations to use for their internal printing needs. Since that time, it has gotten so popular that the university has taken over the program, incremented the version number (to get out from under the free license) and is now charging a $35 per copy fee for commercial use for the newer versions. The older free version can still be found on overseas FTP servers, such as . It is likely that the cost of a shareware/commercial LPR program for Win95 plus the cost of Win95 itself will meet or exceed that of Win2K. As such, users wishing to print via LPR to FreeBSD UNIX systems will probably find it cheaper to simply upgrade to Windows NT Workstation or Win2K. ACITS LPR and Win95 have a few printing idosyncracies. Most Win95 programs, such as Microsoft Word, expect print output to be spooled on the local hard drive and then metered out to a printer that is plugged into the parallel port. Network printing, on the other hand, assumes that print output will go directly from the application to the remote print server. Under Win95, local ports have a setting under Properties, Details, Spool Settings labeled "Print directly to the printer". If this is checked, the application running on the desktop (such as Microsoft Word) will not create a little Printer icon with pages coming out of it or use other means of showing the progress of the job as it is built. This can be very disconcerting to the user of a network printer, so this option should be checked only with printers plugged directly into the parallel port. Worse, if this is checked with ACITS, it can cause the job to abort if the remote print spooler momentarily goes offline. Another local setting also should be changed. Generally, with local ports, Win95 builds the first page in the spooler and then starts printing it while the rest of the pages spool. If ACITS starts printing the first page while the rest of the pages are building, timeouts at the network layer can sometimes cause very large jobs to abort. The entire job should be set to completely spool before the LPR client passes it to the UNIX spooler. The problem is partly the result of program design: because ACITS is implemented as a local printer port instead of being embedded into Win95 networking (and available in Network Neighborhood) the program acts like a local printer port in some ways. The LPR program can be set to deselect banner/burst page printing if a PostScript printer that cannot support ASCII is used. The burst pages referred to here are NOT generated by the Windows machine. Use the instructions in Exhibit 8.3 to install ACITS. LPR client on Win95/98 installation instructions Obtain the ACITSLPR95.EXE file and place it in a temporary directory such as c:\temp1. Close all running programs on the desktop. The computer must be rebooted at completion of installation or the program will not work. Click Start, Run and type in c:\temp1\acitslpr95 then click Yes at the InstallShield prompt. Click Next, then Yes. The program will run through some installation and then presents a Help screen that explains how to configure an LPR port. After the help screen closes, the program asks to reboot the system. Ensure that Yes is checked and click Finish to reboot. After the machine comes back up, install a Printer icon in the Start, Settings, Printers folder if one hasn't been created for the correct model of destination printer. With the Printers folder open, right-click over the printer icon that needs to use the LPR program and click on the Properties tab. Under the Details tab, click the Add Port tab, then click Other. Highlight the ACITS LPR Remote Printing line and click OK. The Add ACITS LPR screen opens. Type in the hostname of the UNIX system that the client spools through— mainprinter.ayedomain.com. Type in the Printer/Queue name and click OK. (Some versions have a "Verify Printer Information" button.) The LPR program then contacts the UNIX host and makes sure that the selected printer is available. If this fails the client machine name is probably not in the /etc/hosts.equiv or etc/hosts.lpd on the FreeBSD printserver. Most sites may simply decide to put a wildcard in hosts.equiv to allow printing, especially if DHCP is used, but many security-conscious sites may stick with individual entries in hosts.lpd. If the printer is PostScript and cannot print ASCII, make sure that the "No banner page control flag" is checked to turn off banner pages. Accessible under Port settings, this flag is overridden if the /etc/printcap file specifies no banner pages. Review how the "send plain text control flag" is set. With this flag unchecked, the LPR code sent is L, (i.e., print unfiltered) meaning that the if filter gets called with the option. This is equivalent to the local invocation of /usr/bin/lpr -l. With the flag checked, the code is F, (formatted) meaning that the if filter gets called without the option. This is equivalent to the default invocation /usr/bin/lpr. (This is also an issue under Windows NT, which retypes the print job to text if this flag is checked. Some filters understand the flag, which is used to preserve control characters, so it should generally remain unchecked. Leave the "Send data file before control file" box unchecked. This option is used only in rare mainframe spooling circumstances. Click OK, then click the Spool Settings button at the properties page. Make sure that the "Spool print jobs so program finishes printing faster" box is checked. Make sure that "Start printing after last page is spooled" box is checked. Make sure that "Disable bi-directional support for this printer" is checked, or greyed out. Make sure that the "Spool data format" is set to RAW. Some printer drivers present a choice of EMF or RAW, such as the Generic Text driver, in this case select RAW. Click OK, then OK again to close the Printer Properties. The printer icon now spools through FreeBSD. Installation of LPR client on Windows NT Unlike WfW and Win95 TCP/IP, Windows NT—both server and workstation—includes an LPR client as well as an LPD program that allows incoming print jobs to be printed from LPR clients, such as UNIX systems. To install the LPR client and daemon program under Windows NT 3.51, use the following instructions. The TCP/IP protocol should be installed beforehand and you must be logged in to the NT system as Administrator. This can be done at any time after the NT system is installed, or during OS installation: Double-click on Main, Control Panel, then Network Settings. In the Installed Network Software window, "Microsoft TCP/IP Printing" should be listed as well as "TCP/IP Protocol". If it is, stop here; otherwise continue. Click the Add Software button to get the Add Network Software dialog box Click the down arrow and select TCP/IP Protocol and related components. Click Continue. Check the "TCP/IP Network Printing Support" box and click Continue. LPR printing is now installed. Follow the instructions to reboot to save changes. To install the LPR client and daemon program under Windows NT 4, use the following instructions. The TCP/IP protocol should be installed beforehand and you must be logged in to the NT system as Administrator. This can be done at any time after the NT system is installed, or during OS installation: Click on Start, Settings, Control Panel, and double-click on Network to open it up. Click on the Services tab. Microsoft TCP/IP Printing should be listed. If not, continue steps 3 - 4. Click Add, then select Microsoft TCP/IP Printing and click OK. Click Close. Follow instructions to reboot to save changes. Any NT Service Packs that were previously installed must be reapplied after these operations. Once LPR printing has been installed, the Printer icon or icons must be created on the NT system so that applications can print. Since this printer driver does all job formatting before passing the printing to the FreeBSD printserver, the print queues specified should be raw queues on the FreeBSD system, which don't do any job formatting. To install the printer icon in Print Manager and set it to send print jobs to the FreeBSD UNIX system, use the following instructions under NT 3.51. You must be logged in to the NT system as Administrator. This can be done at any time after the NT system is installed, or during OS installation. Click on Main, and open it. Then click on Print Manager to open it. Click on Printer, Create Printer. Select the appropriate printer driver. Click the down arrow under Print To and select Other. In the Available Print Monitors window select LPR port and click OK. Enter the hostname of the FreeBSD printserver, and the name of the printer queue and click OK Click OK to close the Create Printer window. The Printer icon is created. To install the printer icon in Print Manager and set it to send print jobs to the FreeBSD UNIX system, use the following instructions under NT 4. You must be logged in to the NT system as Administrator. This can be done at any time after the NT system is installed, or during OS installation: Click Start, Settings, Printers to open the printer folder. Double-click Add Printer to start the wizard. Select the My Computer radio button, not the Network Print Server button and click Next. (The printer is a networked printer, it is managed on the local NT system. Microsoft used confusing terminology here. Click Add Port and select LPR Port, then click New Port. Enter the hostname and print queue for the FreeBSD printserver and click OK. Click Next and select the correct printer driver. Continue until the printer is set up. The LPR client in Windows NT allows DOS print jobs originating in DOS boxes to be routed to the central UNIX print spooler. This is an advantage over the Win95 and WfW LPR programs. Windows NT Registry Changes Using the LPR daemon program under Windows NT presents one problem. If the NT server is used as an LPR/LPD "relay", for example, to pass jobs from clients to LPR print queues on a UNIX system, to pass jobs from LPR programs on UNIX terminating at NT print queues, or to pass jobs from Appletalk clients to LPR printers, NT retypes the job if the type code is set to P (text). This can wreak havoc on PostScript files printed through HP LaserJet printers with internal MIO cards in them, if the job originates from the /usr/bin/lpr program under UNIX, which assigns a P type code. The printserver card treats PostScript jobs as text, and instead of the print job, the raw PostScript codes print. This problem often manifests in the following way: /usr/bin/lpr is used to print a PostScript file from UNIX directly to the remote printer printserver, which works fine, but spooling it through NT causes problems. A registry change that can override the NT Server formatting behavior is detailed in Microsoft Knowledge Base article ID Q150930. With Windows NT 3.51, and 4.0 up to service pack 1 the change is global. Starting with NT 4.0 Service pack 2 the change can be applied to specific print queues, (see Knowledge Base article ID Q168457). This registry change also works for Windows 2000. Under Windows NT 4.0, the change is: Run Registry Editor (REGEDT32.EXE) From the HKEY_LOCAL_MACHINE subtree, go to the following key: \SYSTEM\CurrentControlSet\Services\LPDSVC\Parameters On the Edit menu, click Add Value. Add the following: Value Name: SimulatePassThrough Data Type: REG_DWORD Data 1 The default value is 0, which informs LPD to assign datatypes according to the control commands. Under Windows NT 3.51, the change is: Run Registry Editor (REGEDT32.EXE) From the HKEY_LOCAL_MACHINE subtree, go to the following key: \SYSTEM\CurrentControlSet\Services\LPDSVC\Parameters On the Edit menu, click Add Value. Add the following: Value Name: SimulatePassThrough Data Type: REG_DWORD Data 1 The default value is 0, which informs LPD to assign datatypes according to the control commands. Create an LPD key at the same level as the LPDSVC key. Click the LPDSVC Key, click Save Key from the Registry menu, and then save the file as LPDSVC.KEY Click the LPD key created in step 5. Click Restore on the Registry menu, click the file created in step 6, and then click OK. A warning message appears. Click OK and then quit the Registry Editor. At a command prompt window, type: net stop lpdsvc net start lpdsvc Printing PostScript and DOS command files One problem with printing under Win31 and Win95 with the LPR methods discussed is the lack of a raw LPT1: device. This is annoying to the administrator who wants to print an occasional text file, such as a file full of printer control codes, without their being intercepted by the Windows printer driver. Of course this is also an issue with DOS programs, but a commercial site that runs significant DOS software and wants to print directly to UNIX with LPR really only has one option—to use a commercial TCP/IP stack containing a DOS LPR program. Normally, under Windows printing, virtually all graphical programs print through the Windows printer driver. This is true even of basic programs such as Notepad. For example, an administrator may have a DOS batch file named filename.txt containing the following line: echo \033&k2G > lpt1: This batch file switches a HP LaserJet from CR-LF, MS-DOS textfile printing into Newline termination UNIX textfile printing. Otherwise, raw text printed from UNIX on the HP prints with a stairstep effect. If the administrator opens this file with Notepad and prints it using a regular printer driver, such as an Epson LQ, the Windows printer driver encapsulates this print output into a series of printer-specific control codes that do things such as initialize the printer, install fonts, and so on. The printer won't interpret this output as control code input. Usually, if the printer is locally attached, the user can force a "raw text print" of the file by opening a DOS window and running: copy filename.txt lpt1: /b Since the LPR client program doesn't provide a DOS driver, it cannot reroute input from the LPT1: device ports. The solution is to use the Generic / Text Only printer driver in conjunction with Wordpad (under Win95); under Win31 use a different text editor. The Notepad editor supplied with Windows is unsuitable for this - it "helpfully" inserts a 1 inch margin of spaces around all printed output, as well as the filename title. Wordpad supplied with Win95, can be set to use margins of zero, and inserts no additions into the printed output. Also, make sure that banner pages are turned off, and the print type is set to raw. Checking PostScript Printer capabilities Following is a PostScript command file that can be used to get a PostScript printer to output a number of useful pieces of information that are needed to set up a printer icon under Windows properly. It was printed from Wordpad, in Win95, through the Generic / Text Only printer driver with the following instructions: Start, Run, type in Wordpad and press Enter. File, Open testps.txt File, Page Setup, Printer, select Generic / Text Only, click Properties Click Device Options, select TTY custom, click OK. Click OK, then set all four margins to 0; click OK. Click File, Print, OK. This could also have been printed with /usr/bin/lpr on a UNIX command prompt. The file prints Test Page and some printer statistics below that, as follows. % filename: testps.txt % purpose: to verify proper host connection and function of PostScript % printers. /buf 10 string def /CM { save statusdict/product get (PostScript) anchorsearch exch pop {length 0 eq {1}{2}ifelse } {2}ifelse exch restore }bind def /isCM { CM 1 ge }bind def /Times-BoldItalic findfont 75 scalefont setfont 150 500 moveto (Test Page) false charpath isCM{gsave 0.0 1.0 1.0 0.0 setcmykcolor fill grestore}if 2 setlinewidth stroke /Times-Roman findfont 10 scalefont setfont 150 400 moveto (Your PostScript printer is properly connected and operational.)show 150 380 moveto (The border around the page indicates your printer's printable region.)show { vmreclaim } stopped pop vmstatus exch sub exch pop 150 360 moveto (Max Available Printer Virtual Memory (KB):)show 150 340 moveto dup 1024 div truncate buf cvs show 150 320 moveto (Calculated memory size used for PostScript printer icon properties:) show 150 300 moveto 0.85 mul 1024 div truncate buf cvs show 150 280 moveto (Printer Model: )show statusdict begin product show end 150 260 moveto (PostScript Level: )show /languagelevel where { languagelevel 3 string cvs show pop } {(1) show } ifelse 150 240 moveto (PostScript Version: )show statusdict begin version show (.)show revision 40 string cvs show end clippath stroke showpage Setting up LPR/LPD on FreeBSD When a FreeBSD system is booted, it starts the LPD spooler control daemon program if the /etc/rc.conf file has lpd_enable="YES" set. If this is not set, attempts to print through and from the FreeBSD system will fail with an lpr: connect: No such file or directory error message. The LPD program manages all incoming print jobs, whether they come in from the network, or from local users on the UNIX system. It transfers print jobs to all locally attached parallel or serial printers, as well as defined remote printers. Several programs also are used to manipulate jobs in the print spools that LPD manages, as well as the user programs to submit them from the UNIX command prompt. All of these programs use the /etc/printcap file, which is the master control file for the printing system. Back when printing was mostly text, it was common to place printers on a serial connection that stretched for long distances. Often, 9600bps was used because it could work reliably up to a block away, which allowed printers to be located almost anywhere on an office high-rise floor. Modern office print jobs, on the other hand, are generally graphics-laden and tend to be rather large. These jobs would take hours to transfer over a slower 9600bps serial printer connection. Today, most printers that are not connected to a remote hardware print server box are directly connected to the server using parallel cables. All of the examples shown here are direct connections that are parallel connections. The printcap configuration file, like most UNIX configuration files, indicates comment lines starting with a hash character. Lines without a hash character are meant to be part of a printer queue description line. Each printer queue description line starts with a symbolic name, and ends with a newline. Since the description lines are often quite long, they are often written to span multiple lines by escaping intermediate newlines with the backslash (\) character. The /etc/printcap file, as supplied, defines a single printer queue, lp. The lp queue is the default queue. Most UNIX-supplied printing utilities send print output to this queue if no printer is specified by the user. It should be set to point to the most popular print queue with local UNIX print users, (i.e., users that have shell accounts). The layout of /etc/printcap is covered in the manual page, which is reached by running the man printcap command. The stock /etc/printcap file at the line defining the spool lp shows: # lp|local line printer:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: # In this example the first line defines the names by which the printer is known, and ends with an escaped newline. The next line defines the physical device, the PC parallel port, by /dev/lpt0, and the directory in which the spool files are stored at /var/spool/output/lpd, and the error log file. Note that this particular error log file will not show all LPD errors, such as bad job submittals, it usually shows only the errors that originate within the printing system itself. In general, the administrator creates two print queues for every printer that is connected to the FreeBSD machine. The first queue entry contains whatever additional capabilities UNIX shell users on the server require. The second is a raw queue that performs no print processing on the incoming print job. This queue is used by remote clients, such as Windows clients, that format their own jobs. If the administrator is setting up the printer to allow incoming LPR jobs from network clients, such as other Windows or UNIX systems, those systems must be listed in /etc/hosts.lpd. Creating the spools Building new print spools is merely a matter of making an entry in the /etc/printcap file, creating the spool directories, and setting the correct permissions on them. For example, the following additional line defines a PostScript printer named NEC (in addition to the lp definition): # lp|local line printer:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: NEC|NEC Silentwriter 95 PostScript printer:\ :lp=/dev/lpt0:sd=/var/spool/output/NEC:lf=/var/log/lpd-errs: # Because UNIX is case sensitive, NEC is different from nec in both the name of the printer and the name of the Spool directory. With the print spooler LPD, the Spool directories must be different from each other, or the spooler gets confused and doesen't print. After the /etc/printcap is modified, the root user must create the /var/spool/output/NEC directory and assign ownership of it to the bin user, assign group ownership to daemon, and set permissions with the following commands: &prompt.user; su root &prompt.root; cd /var/spool/output &prompt.root; mkdir NEC &prompt.root; chown bin NEC &prompt.root; chgrp daemon NEC &prompt.root; chmod 755 NEC Additional spool capabilities Because modern print jobs (especially PostScript) can sometimes reach hundreds of megabytes, the sd capability entry in the /etc/printcap file should always point to a Spool directory on a filesystem that has enough space. The /var directory on a default FreeBSD installation is generally set to a fairly small amount, which can easily overflow the spool. There are four ways to handle this problem: During FreeBSD installation, if the administrator knows a lot of print jobs are going to go through the spooler, /var should be set to a large amount of free space. Modify the sd capability in the /etc/printcap file to point to a spool directory in a different, larger filesystem, such as /usr/spool. Use soft links to point the /var/spool/output directory to directories on a larger filesystem. Don't define a /var directory at all during FreeBSD installation; this would make the installer link /var to /usr/var. In addition to spools, the following other capabilities are usually placed in a production /etc/printcap file. The entry fo prints a form feed when the printer is opened. It is handy for HPPCL (HP LaserJets) or other non-PostScript printers that are located behind electronic print sharing devices. It can also be used for printers that accept input from multiple connections, such as a parallel port, serial port, and localtalk port. An example is an HP LaserJet with an MIO card in it plugged into both Ethernet and LocalTalk networks. It will clear any garbage out of the printer before the job is processed. The entry mx defines the maximum size of a print job, which is a must for modern print jobs that frequently grow far past the default print size of a megabyte. The original intent of this capability was to prevent errant programs from stuffing the spool with jobs so large that they would use up all paper in a printer. Graphics-heavy print jobs have made it impossible to depend on this kind of space limitation, so mx is usually set to zero, which turns it off. The entry sh suppresses printing of banner pages in case the printer cannot handle ASCII and the client mistakenly requests them. The entry ct denotes a TCP Connection timeout. This is useful if the remote print server doesn't close the connection properly. FreeBSD 2.2.5 contains a bug in the LPD system - as a workaround the ct capability needs to be set very large, such as 3600, or the appropriate patch installed and LPD recompiled. More recent versions of FreeBSD do not have this bug. Printing to hardware print server boxes or remote print servers. Hardware print server boxes, such as the HP JetDirect internal and external cards, need some additional capabilities defined in the /etc/printcap entry; rp, for remote print spool, and rm for remote machine name. The rm capability is simply the DNS or /etc/hosts name of the IP number associated with the remote printserver device. Obviously, print server devices, such as the HP JetDirect, must not use a dynamic TCP/IP network numbering assignment. If they get their numbering via DHCP, the IP number should be assigned from the static pool; it should always be the same IP number. Determining the name used for rp, on the other hand, can be rather difficult. Here are some common names: Windows NT Server: Printer name of the printer icon created in Print Manager FreeBSD: Print queue name defined in /etc/printcap HP JetDirect: Either the name TEXT or the name RAW. TEXT automatically converts incoming UNIX newline text to DOS-like CR/LF text that the printer can print. RAW should be used for PostScript, and HPPCL printing. HP JetDirect EX +3: External, 3 port version of the JetDirect. Use RAW1, RAW2, RAW3, TEXT1, TEXT2, or TEXT3 depending on the port desired. Intel NetPort: Either use TEXT for UNIX text conversion printing or use PASSTHRU for normal printing. DPI: Use PORT1 or PORT2 depending on which port the printer is plugged into. For other manufacturer's print servers refer to the manuals supplied with those devices. The following is an example printcap that redefines the default lp print queue to send print jobs to the first parallel port on a remote HP LaserJet plugged into a JetDirect EX +3 named floor2hp4.biggy.com. # lp|local line printer:\ :rm=floor2hp4.biggy.com:rp=RAW1:\ :sd=/var/spool/output/lpd:\ :lf=/var/log/lpd-errs: # The rp capability must be defined or the job goes to the default print queue on the remote host. If the remote device does not have a single print queue, such as another UNIX system, this causes problems. For example, if the remote device was a JetDirect EX + 3 and rp was omitted, all queues defined would print out of the first parallel port. Filters The last two important printcap capabilities concern print filters, if (input filter) and of (output filter). If defined, incoming print jobs are run through the filters that these entries point to for further processing. Filters are the reason that the UNIX print spooling system is so much more powerful than any other commercial server operating system. Under FreeBSD, incoming print jobs are acted on by any filters specified in the /etc/printcap no matter where they originate. Incoming print jobs from remote Windows, Mac, NT, OS/2 or other clients can be intercepted and manipulated by any program specified as a filter. Want a PostScript Printer? There's a filter that adds PostScript capability to a non-PostScript printer. Want to make a cheap Epson MX 80 dot-matrix emulate an expensive Okidata Microline dot-matrix for some archaic mainframe application? Write a filter that will rewrite the print codes to do it. Want custom-built banner pages? Use a filter. Many UNIX /etc/printcap filters on many Internet sites can do a variety of interesting and unique things. Someone may have already written a filter that does what you want! Types of Filters Three types of filters can be defined in the /etc/printcap file. In this book all filter examples are for Input filters. Input Filters Input filters are specified by the if capability. Every job that comes into the spool is acted on by any filter specified in the if entry for that spool. Virtually all filters that an administrator would use are specified here. These filters can be either shell scripts, or compiled programs. Fixed Filters Fixed filters are specified by separate capabilities, such as cf, df, and gf. Mostly, these exist for historical reasons. Originally, the idea of LPD was that incoming jobs would be submitted with the type fields set to trigger whatever filter was desired. However, type codes are confusing and annoying to the user, who has to remember which option is needed to trigger which type. It is much easier to set up multiple queues with different names, and this is what most sites do these days. For example, originally a DVI fixed filter might be specified in a spool for lp, triggered by the option passed to lpr. Jobs without this option aren't acted on by the DVI filter. However, the same thing can be done by creating a queue named lp that doesn't have a DVI filter, and a queue named lpdvi which has the DVI filter specified in the if capability. Users just need to remember which queue to print to, instead of what option needed for this or that program. Output Filters These are specified by the of capability. Output filters are much more complicated than input filters and are hardly ever used in normal circumstances. They also generally require a compiled program somewhere, either directly specified or wrapped in a shell script, since they have to do their own signal-handling. Printing Raw UNIX Text with a Filter One of the first things that a new UNIX user will discover when plugging a standard LaserJet or impact printer into a UNIX system is the stairstep problem. The symptom is that the user dumps text to the printer, either through LPR or redirection (by catting it to the parallel device) and instead of receiving the expected Courier 10-point printout, gets a page with a single line of text, or two lines of text "stairstepped", text and nothing else. The problem is rooted in how printers and UNIX handle textfiles internally. Printers by and large follow the "MS-DOS Textfile" convention of requiring a carriage return, then a linefeed, at the end of every text line. This is a holdover from the early days when printers were mechanical devices, and the print head needed to return and the platen to advance to start a new line. UNIX uses only the linefeed character to terminate a text line. So, simply dumping raw text out the parallel port works on MS-DOS, but not on UNIX. If the printer is a PostScript printer, and doesn't support standard ASCII, then dumping UNIX text to it doesn't work. But then, neither would dumping MS-DOS text to it. (Raw text printing on PostScript printers is discussed later in this chapter.) Note also that if the printer is connected over the network to an HP JetDirect hardware print server, internal or external, the TEXT queue on the hardware print automatically adds the extra Carriage Return character to the end of a text line. If the printer is the garden-variety HP LaserJet, DeskJet, or an impact printer, and under DOS the administrator is used to printing raw text from the command line for directory listings, there are two ways to fix stairstep. The first is to send a command to the printer to make it print in "unix textfile" mode, which makes the printer supply its own carriage return. This solution is ugly in a printer environment with UNIX and Windows machines attempting to share use of the same printer. Switching the printer to work with UNIX disrupts DOS/Windows raw text printouts. The better solution is to use a simple filter that converts incoming text from UNIX style to DOS style. The following filter posted on questions@FreeBSD.org and the sample /etc/printcap entry can be used to do this: #!/bin/sh # /usr/local/libexec/crlfilter # # simple parlor trick to add CR to LF for printer # Every line of standard input is printed with CRLF # attached. # awk '{printf "%s\r\n", $0}' - An alternative filter posted using sed could be written as: #!/bin/sh # /usr/local/libexec/crlfilter # # Add CR to LF for printer # Every line of standard input is printed with CRLF # attached. # # Note, the ^M is a *real* ^M (^V^M if your typing in vi) # sed 's/$/^M/' - Here is an example of a filter that triggers the printers automatic LF-to-CR/LF converter (this option is only useful on HP LaserJets that support this command): #!/bin/sh # Simply copies stdin to stdout. Ignores all filter # arguments. # Tells printer to treat LF as CR+LF. Writes a form feed # character after printing job. printf "\033&k2G" && cat && printf "\f" && exit 0 exit 2 The printcap file used to trigger the filter is: #/etc/printcap # The trailer (tr) is used when the queue empties. I found that the # form feed (\f) was basically required for the HP to print properly. # Banners also need to be shut off. # lp|local line printer:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: :if=/usr/local/libexec/crlfilter:sh:tr=\f:mx#0: # The <literal>pr</literal> filter Although most filters are built by scripts or programs and are added to the UNIX machine by the administrator, there is one filter that is supplied with the FreeBSD operating system is very useful for raw text files: the pr filter. It is most commonly used when printing from the UNIX command shell. The pr filter paginates and applies headers and footers to ASCII text files. It is automatically invoked with the option used with the lpr program at the UNIX command prompt. The pr filter is special - it runs in addition to any input filters specified for the print queue in /etc/printcap, if the user sets the option for a print job. This allows headers and pagination to be applied in addition to any special conversion, such as CR to CR/LF that a specified input filter may apply. Printing PostScript Banner Pages with a Filter. Unfortunately, the canned banner page supplied in the LPD program prints only on a text-compatible printer. If the attached printer understands only PostScript and the administrator wants to print banner pages, it is possible to install a filter into the /etc/printcap file to do this. The following filter is taken from the FreeBSD Handbook. I've slightly changed its invocation for a couple of reasons. First, some PostScript printers have difficulty when two print files are sent within the same print job or they lack the trailing Control-D. Second is that the handbook invocation uses the LPRPS program, which requires a serial connection to the printer. The following filter shows another trick: calling LPR from within a filter program to spin off another print job. Unfortunately, the problem with using this trick is that the banner page always gets printed after the job. This is because the incoming job spools first, and then FreeBSD runs the filter against it, so the banner page generated by the filter always spools behind the existing job. There are two scripts, both should be put in the /usr/local/libexec directory, and the modes set to executable. The printcap also must be modified to create the nonbanner and banner versions of the print queue. Following the scripts is the /etc/printcap file showing how they are called. Notice that the sh parameter is turned on since the actual printed banner is being generated on the fly by the filter: #!/bin/sh # Filename /usr/local/libexec/psbanner # parameter spacing comes from if= filter call template of: # if -c -w -l -i -n login -h host # parsing trickiness is to allow for the presence or absence of -c # sleep is in there for ickiness of some PostScript printers for dummy do case "$1" in -n) alogname="$2" ;; -h) ahostname="$2" ;; esac shift done /usr/local/libexec/make-ps-header $alogname $ahostname "PostScript" | \ lpr -P lpnobanner sleep 10 cat && exit 0 Here is the make-ps-header listing. #!/bin/sh # Filename /usr/local/libexec/make-ps-header # # These are PostScript units (72 to the inch). Modify for A4 or # whatever size paper you are using: # page_width=612 page_height=792 border=72 # # Save these, mostly for readability in the PostScript, below. # user=$1 host=$2 job=$3 date=`date` # # Send the PostScript code to stdout. # exec cat <<EOF %!PS % % Make sure we do not interfere with user's job that will follow % % % Make a thick, unpleasant border around the edge of the paper. % $border $border moveto $page_width $border 2 mul sub 0 rlineto 0 $page_height $border 2 mul sub rlineto currentscreen 3 -1 roll pop 100 3 1 roll setscreen $border 2 mul $page_width sub 0 rlineto closepath 0.8 setgray 10 setlinewidth stroke 0 setgray % % Display user's login name, nice and large and prominent % /Helvetica-Bold findfont 64 scalefont setfont $page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto ($user) show % % Now show the boring particulars % /Helvetica findfont 14 scalefont setfont /y 200 def [ (Job:) (Host:) (Date:) ] { 200 y moveto show /y y 18 sub def } forall /Helvetica-Bold findfont 14 scalefont setfont /y 200 def [ ($job) ($host) ($date) ] { 270 y moveto show /y y 18 sub def } forall % % That is it % showpage Here is the /etc/printcap file. # lp|local line printer, PostScript, banner:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:\ :if=/usr/local/libexec/psbanner:sh:mx#0: lpnobanner|local line printer, PostScript, no banner:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd-noban:\ :lf=/var/log/lpd-errs:sh:mx#0: # Printer Accounting The FreeBSD print spooler can manage accounting statistics for printer usage. The spooler counts each page printed and generates totals for each user. In this manner departments or individuals can be charged money for their use of the printer. In the academic world, such as student computer labs, accounting is very political. Many schemes have been developed to attempt to gather statistics to charge people (generally students) for printing. Administrators in this environment who deal with printers can have almost as many accounting problems as printer problems. In the corporate environment, on the other hand, accounting is not as important. I strongly recommend against any corporation attempting to implement printer accounting on shared printers for a number of reasons: The entire UNIX accounting system is based on ASCII printouts. It is easy to count the number of ASCII pages, form feeds, or text lines in a print job. In corporations, however, PostScript and HPPCL are generally the order of the day. It is almost impossible to figure out by examining the datastream how many pages it will occupy, and even if this could be done accurately, it wastes significant computational resources. It is possible to get some PostScript printers to count pages, but doing so requires a bidirectional connection to the printer and additional programming on the UNIX system. This task is beyond the scope of this book. Banner pages aren't included in UNIX printer accounting counts. Therefore, someone submitting 20 two-page jobs uses much more paper than does someone submitting one 40 page job, yet both are charged the same amount. The username of the submitter can be easily forged, if the job is remotely submitted over the network from a client (practically all jobs in a Windows client printing environment are remotely submitted). Although some LPR clients can be set to authenticate, and the rs capability can be set to enforce authentication, not all can, especially Windows LPR clients. It is more difficult for a submitter to hide the IP number or machine name of the remote client, but in a Windows environment there is no guarantee that someone was sitting at a particular desktop machine when the job was submitted. A business generates no revenue by monitoring printer usage. In the academic community, however, when a student lab charges for printouts the lab is actually extracting money from an entity (the student) that is separate from the lab. Within a corporation, the concept of department A getting revenue from user B is pointless and doesn't generate a net gain for the corporation as a whole. For my printer administration, I have found that I can save more money on printing costs by purchasing supplies wisely than by attempting to discourage printing through "chargebacks". What is the sense of being miserly with printing while spending double on toner cartridges because no one is willing to comparison shop, or signing a "lease" agreement that isn't beneficial for the printer? When you get down to it, corporate users don't care much for print sharing anyway, and they generally only agree to it because the administrator can buy a far bigger, faster, and fancier printer than they can requisition. Worse yet, if usage on a shared printer is charged, it encourages employees to look for other places to print. Inevitably, people run out buy cheap inkjet printers for their own use, and the business ends up spending more on paper and supplies for many poor-quality small printers, than it would for a few decent big ones. Moreover, the inferior output of these printers makes the organization as a whole look bad. The corporate spirit should be one of teamwork, not bickering. The surest way to kill a network in a corporation is to set up a situation that puts the administrator into the policeman position or pits one department against another. The only justification I've ever seen for running accounting on corporate printers is using the accounting system to automate reminders to the administrator to replace paper, or toner. Aside from this use, a corporation that implements accounting as a way of encouraging employees not to waste paper ends up defeating the purpose of turning on accounting. Microsoft Networking Client printing with Samba Although LPR is a time-tested and truly cross-platform printing solution, sites with a majority of Windows clients running Microsoft Networking have an alternate printing mechanism—Samba. Samba can provide print services to clients running SMB-compatible network clients. With a running Samba installation, the administrator may "share out" printers as well as filesystem directories from the FreeBSD system. Printers accessed with Samba must be defined both in the /etc/printcap file and the /usr/local/etc/smb.conf file. If the individual printers are defined in the smb.conf file with the printer driver= statement set to the exact model name of the printer, the "Auto printer driver install" feature of Windows NT and Win95/98 is activated. This automatically loads the correct printer driver if the user clicks on the print queue in Network Neighborhood under Windows 95 or NT 4.0. The restriction, of course, is that the printer model must be in the Windows client driver database. The smb.conf file also defines the print command used to pass jobs to the UNIX print spool. It is a good idea to redefine this via the print command option to lpr -s -P %p %s; rm %s. This turns on soft linking, so that large print jobs don't get truncated. In operation, the SMB-networking client builds the print job on itself and then transfers the entire job over the network to the Samba server. On the server, Samba has its own temporary print spool directory to which the job is copied. Once the job has been completely received, it is then passed to the UNIX print spooler.
Microsoft Networking Client printing with Samba ,---------. | ======= | FreeBSD Server | ======= | +---------------------+ ,-----. +-----------+ | +---------------+ | | | | Printer [ ]------------[ ] | Samba | | |_____| +-----------+ Parallel | | Software | [ ]------_________ Cable | +---------------+ | / ::::::: \ | | `---------' | +---------------+ | Network PC | | Print | | | | Software | | | +---------------+ | +---------------------+ The Samba software and the print software run on the same host. Samba receives the print job, then hands it to the print spooler.
Client access issues Because a Windows client formats print jobs before sending them to the server, the administrator may want to hide some of the specialty print queues on the server. For example, the queue that converts LF to CRLF for UNIX text printouts would probably not be shared out. To make such queues invisible, the browseable=no option can be turned on in the smb.conf file. Also, the load printers option must be set to no to allow individual printer definitions. In general, the only print queues that should be visible through Samba are the "raw" print queues that are set up by the administrator to allow incoming preformatted print jobs. Windows clients that print to Samba print queues on the UNIX system can view and cancel print jobs in the print queue. They cannot pause them, however, which is a difference between Novell and Windows NT Server print queues. They also cannot prioritize print jobs from the print queue window, although the administrator can reprioritize print jobs that are in the queue from a command shell on the FreeBSD server. Printer entries in configuration files Following are listings of sample /etc/printcap and smb.conf files used on the system to provide print services. An explanation of the interaction of these files follows. <filename>/etc/printcap</filename> # # # The printer in lpt0 is a PostScript printer. The nec-crlf entry # is for testing the printer when it is switched into HP LaserJet III # mode. # lp|local line printer:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:\ :lf=/var/log/lpd-errs:sh:mx#0: # nec-crlf|NEC Silentwriter 95 in ASCII mode with UNIX text filter:\ :lp=/dev/lpt0:sd=/usr/lpdspool/nec-crlf:\ :lf=/var/log/lpd-errs:sh:mx#0:\ :if=/usr/local/libexec/crlfilter:tr=\f: # nec-raw|NEC Silentwriter 95 used for PostScript passthrough printing:\ :lp=/dev/lpt0:sd=/usr/lpdspool/nec-raw:\ :lf=/var/log/lpd-errs:sh:mx#0: # nec-ps-banner|NEC Silentwriter 95 with PostScript banner page created:\ :lp=/dev/lpt0:sd=/usr/lpdspool/nec-ps-banner:\ :lf=/var/log/lpd-errs:sh:mx#0:if=/usr/local/libexec/psbanner: # # <filename>/usr/local/etc/smb.conf</filename> [global] comment = FreeBSD - Samba %v log file = /var/log/samba.log dont descend = /dev,/proc,/root,/stand print command = lpr -s -P %p %s; rm %s interfaces = X.X.X.X (the system IP number goes here) printing = bsd map archive = no status = yes public = yes read only = no preserve case = yes strip dot = yes security = share guest ok = no password level = 1 dead time = 15 domain master = yes workgroup = WORKGROUP [homes] browseable = no comment = User Home Directory create mode = 0775 public = no [printers] path = /var/spool comment = Printers create mode = 0700 browseable = no read only = yes public = no [lp] printable = yes browseable = no [nec-raw] comment = Main PostScript printer driver for Windows clients printer driver = NEC SilentWriter 95 printable = yes browseable = yes [wwwroot] path = /usr/local/www read only = no create mode = 0775 comment = Internal Web Server Browsing output Following is the output of a net view command executed at a DOS prompt under Windows 95: Shared resources at \\SERVER Sharename Type Comment -------------------------------------------------------------------- nec-crlf Print NEC Silentwriter 95 in ASCII mode nec-raw Print Main PostScript printer driver tedm Disk User Home Directory wwwroot Disk Internal Web Server The command was completed successfully. In the /etc/printcap file four print queues are defined, all tied to the printer plugged into the parallel port on the FreeBSD server. The first is lp, the generic local line printer. Since this print queue generally has a filter placed on it to format jobs from the UNIX print queue properly, it should not be visible on the SMB network (i.e., visible in Network Neighborhood). The second queue, nec-crlf, has a filter that converts UNIX text to text that prints without stairstepping, so it also should be hidden from the SMB network. The third, nec-raw, should be visible on the network because this is the spool that the Windows clients use. The last queue, nec-ps-banner, is another specialty queue for UNIX local printing and thus should not be visible. When the smb.conf file is parsed, the default entry [printers] is first read and used as a set of defaults for printers that are going to be shared out. Next, the /etc/printcap file is read to get a list of all printers on the server. Last, each printer is checked for a service name in the smb.conf file that contains settings that override the set of defaults. In the listing of what resources are visible on the network, both nec-crlf and nec-raw print queues are visible, and lp and nec-ps-banner is not. lp is not visible because there is a specific entry, [lp] in the smb.conf file that blocks it. nec-ps-banner doesn't have such an entry, but because the print queue name is not a legal length for a SMB name, it isn't shared out either. The nec-crlf printer is visible so as to illustrate another point - comments. If a print queue has no entry in the smb.conf file and is built by scanning the /etc/printcap file and using the [printers] defaults, the comment is taken from the /etc/printcap file next to the queue definition name. Otherwise, if an entry is made for the printer in the smb.conf file the comment is taken from the entry in smb.conf. Printing between NT Server/NetWare and FreeBSD. Up to this point in the chapter, our main concern has been FreeBSD and Windows NT printing interoperability with NT as a print client passing jobs to the FreeBSD system. What happens if the situation is reversed and the FreeBSD system is itself a printing client of another LPD server? This situation can arise in a mixed UNIX/NetWare or UNIX/NT environment. The administrator may elect to forgo the use of Samba, and use an NT server to provide print services. Alternatively, the administrator may have existing DOS Novell IPX clients that they don't want to change, printing to an existing IPX Novell NetWare server. Many of the earlier hardware print servers, such as the Intel NetPort 1 and NetPort 2 were IPX only. A site with a large number of these hardware servers may wish to move the clients to TCP/IP, but leave the existing IPX-based printing network intact. With NetWare it is possible to load an LPD NetWare loadable module (NLM) on the NetWare server that takes incoming LPR print jobs and prints them on IPX print queues. Later versions of NetWare may include this NLM, it was an extra cost add-on with NetWare 3.X With Windows NT Server, loading the TCP/IP LPR printing support also loads the LPD print server on NT. By using LPR client programs on UNIX, it is possible to submit, view status, and remove jobs remotely from an NT server that has LPR installed as a port for its printers. Following is a sample /etc/printcap file entry that defines a print queue named tank on the FreeBSD system pointed to an NT LPD server queue named sherman on a NT Server named big.army.mil in the DNS. This uses the rm printcap capability. Unlike the earlier examples, the output print jobs are sent out not by the PC parallel port but over the network to the NT server. # tank|sample remote printer:\ :rm=big.army.mil:rp=sherman:sd=/var/spool/output/lphost:\ :lf=/var/log/lpd-errs: # When using an NT server as an LPD server it may be necessary to make the NT registry changes mentioned under Windows NT Registry Changes, earlier in the chapter. Printing from UNIX Two commands used at the FreeBSD command prompt are intended as general-purpose print commands: lp and lpr. <command>lp</command> The lp command is simply a front end command that calls the lpr command with appropriate options. Its main use is to allow the running of precompiled binary programs and scripts that assume that the lp command is the official printing command. <command>lpr</command> The lpr command is the main command that is used to print files from the command prompts under the FreeBSD operating system. It is frequently spawned off as a child program, or used in pipes. For example, when the Netscape web browser's Print button is clicked, Netscape may create the PostScript output, but the output goes through the lpr command. The lpr command, like many UNIX command-line printing programs, assumes that the default print queue name is lp. When the FreeBSD machine is set up, the administrator usually sets the lp queue to print through a filter that allows raw UNIX text sent to it to print properly. For example, if an HP LaserJet printer that doesn't have PostScript is connected to the server, the lp queue specifies in the /etc/printcap file the CRLF filter listed earlier. On the other hand, if an Apple Laserwriter that doesn't support ASCII is connected to the server, the a2psfilter would be specified in the /etc/printcap for the lp queue. When printing raw text files usually the option is specified to lpr. When printing preformatted files, such as PostScript files, the option is used, which selects whatever queue is used to handle these job types. Managing the UNIX Print Queue Once the print jobs coming in from clients are received on the FreeBSD system and placed in the print spool, they are metered out at a slower rate to the various printers. If traffic activity is light, and few print jobs get sent through, the administrator can probably ignore the print queue as long as it continues to work. However, a busy network printer running at an optimal rate of speed usually has a backlog of unprinted jobs in the queue waiting for print time. To keep all users happy and to provide for the occasional rush print job, the UNIX LPD/LPR printing system has several administration commands which are described here. Viewing the queue On busy printers, and to troubleshoot stopped printers, users sometimes need to view the print jobs in the queue. Administrators also need to view the queue to see what jobs may need to be expedited. This can be done from the workstation that remotely submitted the job if the LPR client has the ability to do this. The Windows 3.1 LPR client discussed earlier has this capability. Unfortunately, many LPR clients don't, which means that the administrator must Telnet into the UNIX machine that the print queues are on and view them there. The UNIX shell command used to view the queue is the lpq command. It is frequently run as lpq -a which shows jobs in all queues. The following is a sample output of the command: &prompt.root; lpq -a nec-raw: Rank Owner Job Files Total Size 1st tedm 19 C:/WLPRSPL/SPOOL/~LP00018.TMP 105221 bytes 2nd tedm 20 C:/WLPRSPL/SPOOL/~LP00019.TMP 13488 bytes 3rd root 3 hosts 1220 bytes 4th tedm 1 Printer Test Page 765 bytes 5th tedm 2 Microsoft Word - CHAPTE10.DOC 15411 bytes The first two jobs and the last two jobs came from remote clients, the third came from the command prompt. Removing print jobs Deleting unwanted print jobs that haven't yet printed from the queue can be done by the remote workstations that submitted the job if their LPR implementations have the necessary commands. The Windows 3.1 LPR client I detailed earlier has this capability. Many LPR clients don't, however, which means that the administrator must Telnet into the UNIX machine that the print queues are on and delete the jobs there. The administrator can delete any print jobs from any queues by running the lprm command followed by the specified print queue and the job number. Below is a sample output of the command: &prompt.root; lprm -P nec-raw 19 dfA019tedmitte dequeued cfA019dostest dequeued &prompt.root; lprm -P nec-raw 3 dfA003toybox.placo.com dequeued cfA003toybox.placo.com dequeued The lprm command is also used under UNIX to delete remote print jobs. Advanced management The administrator logged into the FreeBSD system as the root user can also perform several other operations that ordinary users cannot. These include turning the queues on and off, and moving print jobs within the print queues. The command used to do this is the lpc command. lpc has two modes of operation. In the first mode, the command is run by itself, which puts the administrator into an lpc prompt. Some general help is available for the commands, such as the following sample output: &prompt.root; lpc lpc> help Commands may be abbreviated. Commands are: abort enable disable help restart status topq ? clean exit down quit start stop up lpc> help disable disable turn a spooling queue off lpc> help status status show status of daemon and queue lpc> exit In the second mode of operation the lpc command is just run by itself, followed by the command and the print queue name. Following is a sample output: &prompt.root; lpc disable lp lp: queuing disabled Under FreeBSD, there is no command that specifically allows the administrator to move jobs from one queue to another. This can be done, however, by changing into the raw queue directory then rerunning the lpr command. Following is a sample run showing three print jobs moved from a dysfunctional queue to a good one: &prompt.root; lpq -a lp: Warning: lp is down: printing disabled printing disabled Rank Owner Job Files Total Size 1st root 51 hosts 1220 bytes 2nd root 52 services 60767 bytes 3rd root 53 printcap 2383 bytes &prompt.root; cd /var/spool/output/lpd &prompt.root; ls .seq cfA053toybox.placo.com dfA053toybox.placo.com cfA051toybox.placo.com dfA051toybox.placo.com lock cfA052toybox.placo.com dfA052toybox.placo.com status &prompt.root; lpr -P nec-raw dfA051toybox.placo.com &prompt.root; lpr -P nec-raw dfA052toybox.placo.com &prompt.root; lpr -P nec-raw dfA053toybox.placo.com &prompt.root; lprm -P lp - &prompt.root; lpq -a nec-raw: Warning: nec-raw is down: printing disabled Warning: no daemon present Rank Owner Job Files Total Size 1st root 5 dfA051toybox.placo.com 1220 bytes 2nd root 6 dfA052toybox.placo.com 60767 bytes 3rd root 7 dfA053toybox.placo.com 2383 bytes Moving jobs from queue to queue is feasible only when all printers are similar, as when all printers support PostScript. Remote Management Just as the root user can manipulate remotely submitted jobs in the print queue, print jobs can be remotely managed by regular users with the LPR clients that created them. Unfortunately, some LPR clients, such as the ACITS LPR client for Win95, don't have enough programming to be able to do this. Others, like the Win31 client, can manipulate the print jobs remotely. FreeBSD offers some level of protection against inadvertent deletion of print jobs from remote hosts by restricting manipulation of a job to the same host that originated it. Even if the owner of the job matches a local user account on the server, for an ordinary user to delete remotely submitted print jobs, the request still must come from the remote host. Advanced Printing Topics The FreeBSD UNIX LPR/LPD printing system is very flexible, and, with the addition of filters, can be adapted to very unusual printing environments. To enhance this flexibility, several useful printing utilities are supplied on the FreeBSD CDROM which the administrator might wish to install. Ghostscript The Ghostscript program, invoked as /usr/local/bin/gs, is one of the most useful printing utilities that have been developed for the free software community. Ghostscript reads incoming PostScript data, (or Adobe PDF files) interprets it, and outputs it as a raster image. This can be displayed on screen, for example, with the GhostView program under the X Window system, or printed on most graphics printers, such as Epson dot-matrix, HP DeskJet, or HP LaserJet. In effect, it is a way of adding PostScript printing capability to a printer that doesn't have PostScript firmware code. Ghostscript has been ported to numerous operating systems including Windows. The Ghostscript home page is located at and contains the most current version of the program. A prebuilt FreeBSD binary of Ghostscript is located in the Packages section of the FreeBSD CDROM. This can be installed on the FreeBSD system by selecting the package from the prepackaged software list that is accessed through the /stand/sysinstall installation program. Many packaged programs on the CD depend on GhostScript, and so it may already be installed. Installation of the packaged version of GhostScript is recommended in the FreeBSD ports Section because it has been tested with the other packages that require it. The package creates a directory containing some documentation files in /usr/local/share/ghostscript/X.XX/doc. Unfortunately, because of the packaging process on the FreeBSD CDROM not all the useful installation files are copied into this location. So, if the package was version 5.03 (for example) the administrator will also want to get the file , and unzip and untar it into a temporary directory. Extracting the archive file creates a directory structure under the gs5.03 subdirectory. To install ghostscript in the /etc/printcap file, read the gs5.03/devs.mak file to determine which printer driver definition works with your printer and then use the following instructions: Change to the root user with su. In the gs5.03 directory, copy the lprsetup.sh, unix-lpr.txt, and unix-lpr.sh files to /usr/local/share/ghostscript/5.03. Change to the /usr/local/share/ghostscript/5.03 directory. Edit lprsetup.sh with a text editor such as vi. Modify the DEVICES= entries to list your selected printer driver definitions per the instructions in unix-lpr.txt. Modify the PRINTERDEV= to /dev/lpt0, and the GSDIR= to /usr/local/share/ghostscript, and the SPOOLDIR= to /var/spool/output. Save the file. Edit the unix-lpr.sh file and change the PSFILTERPATH= to /usr/local/share/ghostscript. If the printer that you defined in the lprsetup.sh file is a monochrome printer, remove the "-dBitsPerPixel=${bpp}" and "$colorspec" entries on the gs invocation line and save the file. Otherwise, if it is a color definition leave them in. For example, the following line is for a monochrome LaserJet: ") | gs -q -dNOPAUSE -sDEVICE=${device} \" Don't remove anything else. Exit the editor, and save the unix-lpr.sh file. Copy the unix-lpr.sh file to the parent directory, /usr/local/share/ghostscript and set the execute bit on it. Set the execute bit on lprsetup.sh with chmod and run the file by typing ./lprsetup.sh. Follow the instructions on creating the Spool directories. If you will be using accounting and a separate log file, run the touch command to create the empty files per directions in script output. The sample /etc/printcap is located in the current directory; the filename is printcap.insert. Use this as a template to modify the /etc/printcap file. A sample /etc/printcap file for a LaserJet 3 is below: # # ljet3.raw|Raw output device ljet3 for Ghostscript:\ :rm=big.army.mil:rp=sherman:sd=/var/spool/output/ljet3/raw:\ :mx#0:sf:sh:rs: # ljet3|Ghostscript device ljet3 (output to ljet3.raw):\ :lp=/dev/null:sd=/var/spool/output/ljet3:\ :lf=/var/log/lpd-errs:mx#0:sf:sh:rs:\ :if=/usr/local/share/ghostscript/filt/indirect/ljet3/gsif:\ :af=/var/spool/output/ljet3/acct: # a2ps filter Another handy utility is the a2ps filter, short for ASCII-to-PostScript. This program takes an incoming ASCII datastream and converts it into PostScript. It can also print multiple pages on a single sheet of paper by shrinking them down. It is a useful tool for a printer that cannot interpret ASCII, such as a PostScript-only printer. A2ps is not installed in the FreeBSD system by default; it is located in the ports section /usr/ports/print/a2ps43. A prepackaged binary can be installed with /stand/sysinstall but I have had problems with that port. It is best to install it by running make in the a2ps43 ports directory. A printcap entry and filter using this follow: <filename>/etc/printcap</filename> # lp|local line printer with output dumped through a2ps for raw listings:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:sh:mx#0:\ :if=/usr/local/libexec/ascii2postscript: # <filename>/usr/local/libexec/ascii2postscript</filename> #!/bin/sh # # Simple filter that converts ASCII to PostScript for basic stuff like # directory listings. # /usr/local/bin/a2ps && exit 0 exit 2 Read the system manual page for a2ps to see the options available with this program, and remember to set the filter script ascii2postscript all-executable. Miscellaneous The large number of other printing utilities cannot be covered here. Some add features such as automatic job type sensing, others handle bidirectional communication between the server and the printer. There are also a few other experimental LPR printing replacement systems. Commands such as ghostscript and a2ps can also be used in pipes that create pretty output on an ordinary impact printer. One last hint - the system manual pages can be printed with the option which turns their ordinary ASCII output to beautifully formatted PostScript. Try the command man -t man and send the output through GhostScript or a PostScript printer for easier to read manual pages. diff --git a/en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl b/en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl index ba9b0d542f..59efdeff4e 100644 --- a/en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl +++ b/en_US.ISO8859-1/books/corp-net-guide/freebsd.dsl @@ -1,18 +1,18 @@ - + + ]> ;; Keep the legalnotice together with the rest of the text (define %generate-legalnotice-link% #f) diff --git a/en_US.ISO8859-1/books/design-44bsd/book.sgml b/en_US.ISO8859-1/books/design-44bsd/book.sgml index 2c7159a021..3f263bef8c 100644 --- a/en_US.ISO8859-1/books/design-44bsd/book.sgml +++ b/en_US.ISO8859-1/books/design-44bsd/book.sgml @@ -1,2858 +1,2858 @@ -%man; + +%books.ent; ]> The Design and Implementation of the 4.4BSD Operating System Marshall Kirk McKusick Keith Bostic Michael J. Karels John S. Quarterman 1996 Addison-Wesley Longman, Inc The second chapter of the book, The Design and Implementation of the 4.4BSD Operating System is excerpted here with the permission of the publisher. No part of it may be further reproduced or distributed without the publisher's express written permission. The rest of the book explores the concepts introduced in this chapter in incredible detail and is an excellent reference for anyone with an interest in BSD UNIX. More information about this book is available from the publisher, with whom you can also sign up to receive news of related titles. Information about BSD courses is available from Kirk McKusick. Design Overview of 4.4BSD 4.4BSD Facilities and the Kernel The 4.4BSD kernel provides four basic facilities: processes, a filesystem, communications, and system startup. This section outlines where each of these four basic services is described in this book. Processes constitute a thread of control in an address space. Mechanisms for creating, terminating, and otherwise controlling processes are described in Chapter 4. The system multiplexes separate virtual-address spaces for each process; this memory management is discussed in Chapter 5. The user interface to the filesystem and devices is similar; common aspects are discussed in Chapter 6. The filesystem is a set of named files, organized in a tree-structured hierarchy of directories, and of operations to manipulate them, as presented in Chapter 7. Files reside on physical media such as disks. 4.4BSD supports several organizations of data on the disk, as set forth in Chapter 8. Access to files on remote machines is the subject of Chapter 9. Terminals are used to access the system; their operation is the subject of Chapter 10. Communication mechanisms provided by traditional UNIX systems include simplex reliable byte streams between related processes (see pipes, Section 11.1), and notification of exceptional events (see signals, Section 4.7). 4.4BSD also has a general interprocess-communication facility. This facility, described in Chapter 11, uses access mechanisms distinct from those of the filesystem, but, once a connection is set up, a process can access it as though it were a pipe. There is a general networking framework, discussed in Chapter 12, that is normally used as a layer underlying the IPC facility. Chapter 13 describes a particular networking implementation in detail. Any real operating system has operational issues, such as how to start it running. Startup and operational issues are described in Chapter 14. Sections 2.3 through 2.14 present introductory material related to Chapters 3 through 14. We shall define terms, mention basic system calls, and explore historical developments. Finally, we shall give the reasons for many major design decisions. The Kernel The kernel is the part of the system that runs in protected mode and mediates access by all user programs to the underlying hardware (e.g., CPU, disks, terminals, network links) and software constructs (e.g., filesystem, network protocols). The kernel provides the basic system facilities; it creates and manages processes, and provides functions to access the filesystem and communication facilities. These functions, called system calls appear to user processes as library subroutines. These system calls are the only interface that processes have to these facilities. Details of the system-call mechanism are given in Chapter 3, as are descriptions of several kernel mechanisms that do not execute as the direct result of a process doing a system call. A kernel in traditional operating-system terminology, is a small nucleus of software that provides only the minimal facilities necessary for implementing additional operating-system services. In contemporary research operating systems -- such as Chorus , Mach , Tunis , and the V Kernel -- this division of functionality is more than just a logical one. Services such as filesystems and networking protocols are implemented as client application processes of the nucleus or kernel. The 4.4BSD kernel is not partitioned into multiple processes. This basic design decision was made in the earliest versions of UNIX. The first two implementations by Ken Thompson had no memory mapping, and thus made no hardware-enforced distinction between user and kernel space . A message-passing system could have been implemented as readily as the actually implemented model of kernel and user processes. The monolithic kernel was chosen for simplicity and performance. And the early kernels were small; the inclusion of facilities such as networking into the kernel has increased its size. The current trend in operating-systems research is to reduce the kernel size by placing such services in user space. Users ordinarily interact with the system through a command-language interpreter, called a shell, and perhaps through additional user application programs. Such programs and the shell are implemented with processes. Details of such programs are beyond the scope of this book, which instead concentrates almost exclusively on the kernel. Sections 2.3 and 2.4 describe the services provided by the 4.4BSD kernel, and give an overview of the latter's design. Later chapters describe the detailed design and implementation of these services as they appear in 4.4BSD. Kernel Organization In this section, we view the organization of the 4.4BSD kernel in two ways: As a static body of software, categorized by the functionality offered by the modules that make up the kernel By its dynamic operation, categorized according to the services provided to users The largest part of the kernel implements the system services that applications access through system calls. In 4.4BSD, this software has been organized according to the following: Basic kernel facilities: timer and system-clock handling, descriptor management, and process management Memory-management support: paging and swapping Generic system interfaces: the I/O, control, and multiplexing operations performed on descriptors The filesystem: files, directories, pathname translation, file locking, and I/O buffer management Terminal-handling support: the terminal-interface driver and terminal line disciplines Interprocess-communication facilities: sockets Support for network communication: communication protocols and generic network facilities, such as routing Machine-independent software in the 4.4BSD kernel Category Lines of code Percentage of kernel total machine independent 162,617 80.4 headers 9,393 4.6 initialization 1,107 0.6 kernel facilities 8,793 4.4 generic interfaces 4,782 2.4 interprocess communication 4,540 2.2 terminal handling 3,911 1.9 virtual memory 11,813 5.8 vnode management 7,954 3.9 filesystem naming 6,550 3.2 fast filestore 4,365 2.2 log-structure filestore 4,337 2.1 memory-based filestore 645 0.3 cd9660 filesystem 4,177 2.1 miscellaneous filesystems (10) 12,695 6.3 network filesystem 17,199 8.5 network communication 8,630 4.3 internet protocols 11,984 5.9 ISO protocols 23,924 11.8 X.25 protocols 10,626 5.3 XNS protocols 5,192 2.6
Most of the software in these categories is machine independent and is portable across different hardware architectures. The machine-dependent aspects of the kernel are isolated from the mainstream code. In particular, none of the machine-independent code contains conditional code for specific architecture. When an architecture-dependent action is needed, the machine-independent code calls an architecture-dependent function that is located in the machine-dependent code. The software that is machine dependent includes Low-level system-startup actions Trap and fault handling Low-level manipulation of the run-time context of a process Configuration and initialization of hardware devices Run-time support for I/O devices Machine-dependent software for the HP300 in the 4.4BSD kernel Category Lines of code Percentage of kernel total machine dependent 39,634 19.6 machine dependent headers 1,562 0.8 device driver headers 3,495 1.7 device driver source 17,506 8.7 virtual memory 3,087 1.5 other machine dependent 6,287 3.1 routines in assembly language 3,014 1.5 HP/UX compatibility 4,683 2.3
summarizes the machine-independent software that constitutes the 4.4BSD kernel for the HP300. The numbers in column 2 are for lines of C source code, header files, and assembly language. Virtually all the software in the kernel is written in the C programming language; less than 2 percent is written in assembly language. As the statistics in show, the machine-dependent software, excluding HP/UX and device support, accounts for a minuscule 6.9 percent of the kernel. Only a small part of the kernel is devoted to initializing the system. This code is used when the system is bootstrapped into operation and is responsible for setting up the kernel hardware and software environment (see Chapter 14). Some operating systems (especially those with limited physical memory) discard or overlay the software that performs these functions after that software has been executed. The 4.4BSD kernel does not reclaim the memory used by the startup code because that memory space is barely 0.5 percent of the kernel resources used on a typical machine. Also, the startup code does not appear in one place in the kernel -- it is scattered throughout, and it usually appears in places logically associated with what is being initialized. Kernel Services The boundary between the kernel- and user-level code is enforced by hardware-protection facilities provided by the underlying hardware. The kernel operates in a separate address space that is inaccessible to user processes. Privileged operations -- such as starting I/O and halting the central processing unit (CPU) -- are available to only the kernel. Applications request services from the kernel with system calls. System calls are used to cause the kernel to execute complicated operations, such as writing data to secondary storage, and simple operations, such as returning the current time of day. All system calls appear synchronous to applications: The application does not run while the kernel does the actions associated with a system call. The kernel may finish some operations associated with a system call after it has returned. For example, a write system call will copy the data to be written from the user process to a kernel buffer while the process waits, but will usually return from the system call before the kernel buffer is written to the disk. A system call usually is implemented as a hardware trap that changes the CPU's execution mode and the current address-space mapping. Parameters supplied by users in system calls are validated by the kernel before being used. Such checking ensures the integrity of the system. All parameters passed into the kernel are copied into the kernel's address space, to ensure that validated parameters are not changed as a side effect of the system call. System-call results are returned by the kernel, either in hardware registers or by their values being copied to user-specified memory addresses. Like parameters passed into the kernel, addresses used for the return of results must be validated to ensure that they are part of an application's address space. If the kernel encounters an error while processing a system call, it returns an error code to the user. For the C programming language, this error code is stored in the global variable errno, and the function that executed the system call returns the value -1. User applications and the kernel operate independently of each other. 4.4BSD does not store I/O control blocks or other operating-system-related data structures in the application's address space. Each user-level application is provided an independent address space in which it executes. The kernel makes most state changes, such as suspending a process while another is running, invisible to the processes involved. Process Management 4.4BSD supports a multitasking environment. Each task or thread of execution is termed a process. The context of a 4.4BSD process consists of user-level state, including the contents of its address space and the run-time environment, and kernel-level state, which includes scheduling parameters, resource controls, and identification information. The context includes everything used by the kernel in providing services for the process. Users can create processes, control the processes' execution, and receive notification when the processes' execution status changes. Every process is assigned a unique value, termed a process identifier (PID). This value is used by the kernel to identify a process when reporting status changes to a user, and by a user when referencing a process in a system call. The kernel creates a process by duplicating the context of another process. The new process is termed a child process of the original parent process The context duplicated in process creation includes both the user-level execution state of the process and the process's system state managed by the kernel. Important components of the kernel state are described in Chapter 4.
Process lifecycle +----------------+ wait +----------------+ | parent process |--------------------------------->| parent process |---> +----------------+ +----------------+ | ^ | fork | V | +----------------+ execve +----------------+ wait +----------------+ | child process |------->| child process |------->| zombie process | +----------------+ +----------------+ +----------------+ Process-management system calls
The process lifecycle is depicted in . A process may create a new process that is a copy of the original by using the fork system call. The fork call returns twice: once in the parent process, where the return value is the process identifier of the child, and once in the child process, where the return value is 0. The parent-child relationship induces a hierarchical structure on the set of processes in the system. The new process shares all its parent's resources, such as file descriptors, signal-handling status, and memory layout. Although there are occasions when the new process is intended to be a copy of the parent, the loading and execution of a different program is a more useful and typical action. A process can overlay itself with the memory image of another program, passing to the newly created image a set of parameters, using the system call execve. One parameter is the name of a file whose contents are in a format recognized by the system -- either a binary-executable file or a file that causes the execution of a specified interpreter program to process its contents. A process may terminate by executing an exit system call, sending 8 bits of exit status to its parent. If a process wants to communicate more than a single byte of information with its parent, it must either set up an interprocess-communication channel using pipes or sockets, or use an intermediate file. Interprocess communication is discussed extensively in Chapter 11. A process can suspend execution until any of its child processes terminate using the wait system call, which returns the PID and exit status of the terminated child process. A parent process can arrange to be notified by a signal when a child process exits or terminates abnormally. Using the wait4 system call, the parent can retrieve information about the event that caused termination of the child process and about resources consumed by the process during its lifetime. If a process is orphaned because its parent exits before it is finished, then the kernel arranges for the child's exit status to be passed back to a special system process init: see Sections 3.1 and 14.6). The details of how the kernel creates and destroys processes are given in Chapter 5. Processes are scheduled for execution according to a process-priority parameter. This priority is managed by a kernel-based scheduling algorithm. Users can influence the scheduling of a process by specifying a parameter (nice) that weights the overall scheduling priority, but are still obligated to share the underlying CPU resources according to the kernel's scheduling policy. Signals The system defines a set of signals that may be delivered to a process. Signals in 4.4BSD are modeled after hardware interrupts. A process may specify a user-level subroutine to be a handler to which a signal should be delivered. When a signal is generated, it is blocked from further occurrence while it is being caught by the handler. Catching a signal involves saving the current process context and building a new one in which to run the handler. The signal is then delivered to the handler, which can either abort the process or return to the executing process (perhaps after setting a global variable). If the handler returns, the signal is unblocked and can be generated (and caught) again. Alternatively, a process may specify that a signal is to be ignored, or that a default action, as determined by the kernel, is to be taken. The default action of certain signals is to terminate the process. This termination may be accompanied by creation of a core file that contains the current memory image of the process for use in postmortem debugging. Some signals cannot be caught or ignored. These signals include SIGKILL, which kills runaway processes, and the job-control signal SIGSTOP. A process may choose to have signals delivered on a special stack so that sophisticated software stack manipulations are possible. For example, a language supporting coroutines needs to provide a stack for each coroutine. The language run-time system can allocate these stacks by dividing up the single stack provided by 4.4BSD. If the kernel does not support a separate signal stack, the space allocated for each coroutine must be expanded by the amount of space required to catch a signal. All signals have the same priority. If multiple signals are pending simultaneously, the order in which signals are delivered to a process is implementation specific. Signal handlers execute with the signal that caused their invocation to be blocked, but other signals may yet occur. Mechanisms are provided so that processes can protect critical sections of code against the occurrence of specified signals. The detailed design and implementation of signals is described in Section 4.7. Process Groups and Sessions Processes are organized into process groups. Process groups are used to control access to terminals and to provide a means of distributing signals to collections of related processes. A process inherits its process group from its parent process. Mechanisms are provided by the kernel to allow a process to alter its process group or the process group of its descendents. Creating a new process group is easy; the value of a new process group is ordinarily the process identifier of the creating process. The group of processes in a process group is sometimes referred to as a job and is manipulated by high-level system software, such as the shell. A common kind of job created by a shell is a pipeline of several processes connected by pipes, such that the output of the first process is the input of the second, the output of the second is the input of the third, and so forth. The shell creates such a job by forking a process for each stage of the pipeline, then putting all those processes into a separate process group. A user process can send a signal to each process in a process group, as well as to a single process. A process in a specific process group may receive software interrupts affecting the group, causing the group to suspend or resume execution, or to be interrupted or terminated. A terminal has a process-group identifier assigned to it. This identifier is normally set to the identifier of a process group associated with the terminal. A job-control shell may create a number of process groups associated with the same terminal; the terminal is the controlling terminal for each process in these groups. A process may read from a descriptor for its controlling terminal only if the terminal's process-group identifier matches that of the process. If the identifiers do not match, the process will be blocked if it attempts to read from the terminal. By changing the process-group identifier of the terminal, a shell can arbitrate a terminal among several different jobs. This arbitration is called job control and is described, with process groups, in Section 4.8. Just as a set of related processes can be collected into a process group, a set of process groups can be collected into a session. The main uses for sessions are to create an isolated environment for a daemon process and its children, and to collect together a user's login shell and the jobs that that shell spawns. Memory Management Each process has its own private address space. The address space is initially divided into three logical segments: text, data, and stack. The text segment is read-only and contains the machine instructions of a program. The data and stack segments are both readable and writable. The data segment contains the initialized and uninitialized data portions of a program, whereas the stack segment holds the application's run-time stack. On most machines, the stack segment is extended automatically by the kernel as the process executes. A process can expand or contract its data segment by making a system call, whereas a process can change the size of its text segment only when the segment's contents are overlaid with data from the filesystem, or when debugging takes place. The initial contents of the segments of a child process are duplicates of the segments of a parent process. The entire contents of a process address space do not need to be resident for a process to execute. If a process references a part of its address space that is not resident in main memory, the system pages the necessary information into memory. When system resources are scarce, the system uses a two-level approach to maintain available resources. If a modest amount of memory is available, the system will take memory resources away from processes if these resources have not been used recently. Should there be a severe resource shortage, the system will resort to swapping the entire context of a process to secondary storage. The demand paging and swapping done by the system are effectively transparent to processes. A process may, however, advise the system about expected future memory utilization as a performance aid. BSD Memory-Management Design Decisions The support of large sparse address spaces, mapped files, and shared memory was a requirement for 4.2BSD. An interface was specified, called mmap, that allowed unrelated processes to request a shared mapping of a file into their address spaces. If multiple processes mapped the same file into their address spaces, changes to the file's portion of an address space by one process would be reflected in the area mapped by the other processes, as well as in the file itself. Ultimately, 4.2BSD was shipped without the mmap interface, because of pressure to make other features, such as networking, available. Further development of the mmap interface continued during the work on 4.3BSD. Over 40 companies and research groups participated in the discussions leading to the revised architecture that was described in the Berkeley Software Architecture Manual . Several of the companies have implemented the revised interface . Once again, time pressure prevented 4.3BSD from providing an implementation of the interface. Although the latter could have been built into the existing 4.3BSD virtual-memory system, the developers decided not to put it in because that implementation was nearly 10 years old. Furthermore, the original virtual-memory design was based on the assumption that computer memories were small and expensive, whereas disks were locally connected, fast, large, and inexpensive. Thus, the virtual-memory system was designed to be frugal with its use of memory at the expense of generating extra disk traffic. In addition, the 4.3BSD implementation was riddled with VAX memory-management hardware dependencies that impeded its portability to other computer architectures. Finally, the virtual-memory system was not designed to support the tightly coupled multiprocessors that are becoming increasingly common and important today. Attempts to improve the old implementation incrementally seemed doomed to failure. A completely new design, on the other hand, could take advantage of large memories, conserve disk transfers, and have the potential to run on multiprocessors. Consequently, the virtual-memory system was completely replaced in 4.4BSD. The 4.4BSD virtual-memory system is based on the Mach 2.0 VM system . with updates from Mach 2.5 and Mach 3.0. It features efficient support for sharing, a clean separation of machine-independent and machine-dependent features, as well as (currently unused) multiprocessor support. Processes can map files anywhere in their address space. They can share parts of their address space by doing a shared mapping of the same file. Changes made by one process are visible in the address space of the other process, and also are written back to the file itself. Processes can also request private mappings of a file, which prevents any changes that they make from being visible to other processes mapping the file or being written back to the file itself. Another issue with the virtual-memory system is the way that information is passed into the kernel when a system call is made. 4.4BSD always copies data from the process address space into a buffer in the kernel. For read or write operations that are transferring large quantities of data, doing the copy can be time consuming. An alternative to doing the copying is to remap the process memory into the kernel. The 4.4BSD kernel always copies the data for several reasons: Often, the user data are not page aligned and are not a multiple of the hardware page length. If the page is taken away from the process, it will no longer be able to reference that page. Some programs depend on the data remaining in the buffer even after those data have been written. If the process is allowed to keep a copy of the page (as it is in current 4.4BSD semantics), the page must be made copy-on-write. A copy-on-write page is one that is protected against being written by being made read-only. If the process attempts to modify the page, the kernel gets a write fault. The kernel then makes a copy of the page that the process can modify. Unfortunately, the typical process will immediately try to write new data to its output buffer, forcing the data to be copied anyway. When pages are remapped to new virtual-memory addresses, most memory-management hardware requires that the hardware address-translation cache be purged selectively. The cache purges are often slow. The net effect is that remapping is slower than copying for blocks of data less than 4 to 8 Kbyte. The biggest incentives for memory mapping are the needs for accessing big files and for passing large quantities of data between processes. The mmap interface provides a way for both of these tasks to be done without copying. Memory Management Inside the Kernel The kernel often does allocations of memory that are needed for only the duration of a single system call. In a user process, such short-term memory would be allocated on the run-time stack. Because the kernel has a limited run-time stack, it is not feasible to allocate even moderate-sized blocks of memory on it. Consequently, such memory must be allocated through a more dynamic mechanism. For example, when the system must translate a pathname, it must allocate a 1-Kbyte buffer to hold the name. Other blocks of memory must be more persistent than a single system call, and thus could not be allocated on the stack even if there was space. An example is protocol-control blocks that remain throughout the duration of a network connection. Demands for dynamic memory allocation in the kernel have increased as more services have been added. A generalized memory allocator reduces the complexity of writing code inside the kernel. Thus, the 4.4BSD kernel has a single memory allocator that can be used by any part of the system. It has an interface similar to the C library routines malloc and free that provide memory allocation to application programs . Like the C library interface, the allocation routine takes a parameter specifying the size of memory that is needed. The range of sizes for memory requests is not constrained; however, physical memory is allocated and is not paged. The free routine takes a pointer to the storage being freed, but does not require the size of the piece of memory being freed. I/O System The basic model of the UNIX I/O system is a sequence of bytes that can be accessed either randomly or sequentially. There are no access methods and no control blocks in a typical UNIX user process. Different programs expect various levels of structure, but the kernel does not impose structure on I/O. For instance, the convention for text files is lines of ASCII characters separated by a single newline character (the ASCII line-feed character), but the kernel knows nothing about this convention. For the purposes of most programs, the model is further simplified to being a stream of data bytes, or an I/O stream. It is this single common data form that makes the characteristic UNIX tool-based approach work . An I/O stream from one program can be fed as input to almost any other program. (This kind of traditional UNIX I/O stream should not be confused with the Eighth Edition stream I/O system or with the System V, Release 3 STREAMS, both of which can be accessed as traditional I/O streams.) Descriptors and I/O UNIX processes use descriptors to reference I/O streams. Descriptors are small unsigned integers obtained from the open and socket system calls. The open system call takes as arguments the name of a file and a permission mode to specify whether the file should be open for reading or for writing, or for both. This system call also can be used to create a new, empty file. A read or write system call can be applied to a descriptor to transfer data. The close system call can be used to deallocate any descriptor. Descriptors represent underlying objects supported by the kernel, and are created by system calls specific to the type of object. In 4.4BSD, three kinds of objects can be represented by descriptors: files, pipes, and sockets. A file is a linear array of bytes with at least one name. A file exists until all its names are deleted explicitly and no process holds a descriptor for it. A process acquires a descriptor for a file by opening that file's name with the open system call. I/O devices are accessed as files. A pipe is a linear array of bytes, as is a file, but it is used solely as an I/O stream, and it is unidirectional. It also has no name, and thus cannot be opened with open. Instead, it is created by the pipe system call, which returns two descriptors, one of which accepts input that is sent to the other descriptor reliably, without duplication, and in order. The system also supports a named pipe or FIFO. A FIFO has properties identical to a pipe, except that it appears in the filesystem; thus, it can be opened using the open system call. Two processes that wish to communicate each open the FIFO: One opens it for reading, the other for writing. A socket is a transient object that is used for interprocess communication; it exists only as long as some process holds a descriptor referring to it. A socket is created by the socket system call, which returns a descriptor for it. There are different kinds of sockets that support various communication semantics, such as reliable delivery of data, preservation of message ordering, and preservation of message boundaries. In systems before 4.2BSD, pipes were implemented using the filesystem; when sockets were introduced in 4.2BSD, pipes were reimplemented as sockets. The kernel keeps for each process a descriptor table, which is a table that the kernel uses to translate the external representation of a descriptor into an internal representation. (The descriptor is merely an index into this table.) The descriptor table of a process is inherited from that process's parent, and thus access to the objects to which the descriptors refer also is inherited. The main ways that a process can obtain a descriptor are by opening or creation of an object, and by inheritance from the parent process. In addition, socket IPC allows passing of descriptors in messages between unrelated processes on the same machine. Every valid descriptor has an associated file offset in bytes from the beginning of the object. Read and write operations start at this offset, which is updated after each data transfer. For objects that permit random access, the file offset also may be set with the lseek system call. Ordinary files permit random access, and some devices do, as well. Pipes and sockets do not. When a process terminates, the kernel reclaims all the descriptors that were in use by that process. If the process was holding the final reference to an object, the object's manager is notified so that it can do any necessary cleanup actions, such as final deletion of a file or deallocation of a socket. Descriptor Management Most processes expect three descriptors to be open already when they start running. These descriptors are 0, 1, 2, more commonly known as standard input, standard output, and standard error, respectively. Usually, all three are associated with the user's terminal by the login process (see Section 14.6) and are inherited through fork and exec by processes run by the user. Thus, a program can read what the user types by reading standard input, and the program can send output to the user's screen by writing to standard output. The standard error descriptor also is open for writing and is used for error output, whereas standard output is used for ordinary output. These (and other) descriptors can be mapped to objects other than the terminal; such mapping is called I/O redirection, and all the standard shells permit users to do it. The shell can direct the output of a program to a file by closing descriptor 1 (standard output) and opening the desired output file to produce a new descriptor 1. It can similarly redirect standard input to come from a file by closing descriptor 0 and opening the file. Pipes allow the output of one program to be input to another program without rewriting or even relinking of either program. Instead of descriptor 1 (standard output) of the source program being set up to write to the terminal, it is set up to be the input descriptor of a pipe. Similarly, descriptor 0 (standard input) of the sink program is set up to reference the output of the pipe, instead of the terminal keyboard. The resulting set of two processes and the connecting pipe is known as a pipeline. Pipelines can be arbitrarily long series of processes connected by pipes. The open, pipe, and socket system calls produce new descriptors with the lowest unused number usable for a descriptor. For pipelines to work, some mechanism must be provided to map such descriptors into 0 and 1. The dup system call creates a copy of a descriptor that points to the same file-table entry. The new descriptor is also the lowest unused one, but if the desired descriptor is closed first, dup can be used to do the desired mapping. Care is required, however: If descriptor 1 is desired, and descriptor 0 happens also to have been closed, descriptor 0 will be the result. To avoid this problem, the system provides the dup2 system call; it is like dup, but it takes an additional argument specifying the number of the desired descriptor (if the desired descriptor was already open, dup2 closes it before reusing it). Devices Hardware devices have filenames, and may be accessed by the user via the same system calls used for regular files. The kernel can distinguish a device special file or special file, and can determine to what device it refers, but most processes do not need to make this determination. Terminals, printers, and tape drives are all accessed as though they were streams of bytes, like 4.4BSD disk files. Thus, device dependencies and peculiarities are kept in the kernel as much as possible, and even in the kernel most of them are segregated in the device drivers. Hardware devices can be categorized as either structured or unstructured; they are known as block or character devices, respectively. Processes typically access devices through special files in the filesystem. I/O operations to these files are handled by kernel-resident software modules termed device drivers. Most network-communication hardware devices are accessible through only the interprocess-communication facilities, and do not have special files in the filesystem name space, because the raw-socket interface provides a more natural interface than does a special file. Structured or block devices are typified by disks and magnetic tapes, and include most random-access devices. The kernel supports read-modify-write-type buffering actions on block-oriented structured devices to allow the latter to be read and written in a totally random byte-addressed fashion, like regular files. Filesystems are created on block devices. Unstructured devices are those devices that do not support a block structure. Familiar unstructured devices are communication lines, raster plotters, and unbuffered magnetic tapes and disks. Unstructured devices typically support large block I/O transfers. Unstructured files are called character devices because the first of these to be implemented were terminal device drivers. The kernel interface to the driver for these devices proved convenient for other devices that were not block structured. Device special files are created by the mknod system call. There is an additional system call, ioctl, for manipulating the underlying device parameters of special files. The operations that can be done differ for each device. This system call allows the special characteristics of devices to be accessed, rather than overloading the semantics of other system calls. For example, there is an ioctl on a tape drive to write an end-of-tape mark, instead of there being a special or modified version of write. Socket IPC The 4.2BSD kernel introduced an IPC mechanism more flexible than pipes, based on sockets. A socket is an endpoint of communication referred to by a descriptor, just like a file or a pipe. Two processes can each create a socket, and then connect those two endpoints to produce a reliable byte stream. Once connected, the descriptors for the sockets can be read or written by processes, just as the latter would do with a pipe. The transparency of sockets allows the kernel to redirect the output of one process to the input of another process residing on another machine. A major difference between pipes and sockets is that pipes require a common parent process to set up the communications channel. A connection between sockets can be set up by two unrelated processes, possibly residing on different machines. System V provides local interprocess communication through FIFOs (also known as named pipes). FIFOs appear as an object in the filesystem that unrelated processes can open and send data through in the same way as they would communicate through a pipe. Thus, FIFOs do not require a common parent to set them up; they can be connected after a pair of processes are up and running. Unlike sockets, FIFOs can be used on only a local machine; they cannot be used to communicate between processes on different machines. FIFOs are implemented in 4.4BSD only because they are required by the POSIX.1 standard. Their functionality is a subset of the socket interface. The socket mechanism requires extensions to the traditional UNIX I/O system calls to provide the associated naming and connection semantics. Rather than overloading the existing interface, the developers used the existing interfaces to the extent that the latter worked without being changed, and designed new interfaces to handle the added semantics. The read and write system calls were used for byte-stream type connections, but six new system calls were added to allow sending and receiving addressed messages such as network datagrams. The system calls for writing messages include send, sendto, and sendmsg. The system calls for reading messages include recv, recvfrom, and recvmsg. In retrospect, the first two in each class are special cases of the others; recvfrom and sendto probably should have been added as library interfaces to recvmsg and sendmsg, respectively. Scatter/Gather I/O In addition to the traditional read and write system calls, 4.2BSD introduced the ability to do scatter/gather I/O. Scatter input uses the readv system call to allow a single read to be placed in several different buffers. Conversely, the writev system call allows several different buffers to be written in a single atomic write. Instead of passing a single buffer and length parameter, as is done with read and write, the process passes in a pointer to an array of buffers and lengths, along with a count describing the size of the array. This facility allows buffers in different parts of a process address space to be written atomically, without the need to copy them to a single contiguous buffer. Atomic writes are necessary in the case where the underlying abstraction is record based, such as tape drives that output a tape block on each write request. It is also convenient to be able to read a single request into several different buffers (such as a record header into one place and the data into another). Although an application can simulate the ability to scatter data by reading the data into a large buffer and then copying the pieces to their intended destinations, the cost of memory-to-memory copying in such cases often would more than double the running time of the affected application. Just as send and recv could have been implemented as library interfaces to sendto and recvfrom, it also would have been possible to simulate read with readv and write with writev. However, read and write are used so much more frequently that the added cost of simulating them would not have been worthwhile. Multiple Filesystem Support With the expansion of network computing, it became desirable to support both local and remote filesystems. To simplify the support of multiple filesystems, the developers added a new virtual node or vnode interface to the kernel. The set of operations exported from the vnode interface appear much like the filesystem operations previously supported by the local filesystem. However, they may be supported by a wide range of filesystem types: Local disk-based filesystems Files imported using a variety of remote filesystem protocols Read-only CD-ROM filesystems Filesystems providing special-purpose interfaces -- for example, the /proc filesystem A few variants of 4.4BSD, such as FreeBSD, allow filesystems to be loaded dynamically when the filesystems are first referenced by the mount system call. The vnode interface is described in Section 6.5; its ancillary support routines are described in Section 6.6; several of the special-purpose filesystems are described in Section 6.7. Filesystems A regular file is a linear array of bytes, and can be read and written starting at any byte in the file. The kernel distinguishes no record boundaries in regular files, although many programs recognize line-feed characters as distinguishing the ends of lines, and other programs may impose other structure. No system-related information about a file is kept in the file itself, but the filesystem stores a small amount of ownership, protection, and usage information with each file. A filename component is a string of up to 255 characters. These filenames are stored in a type of file called a directory. The information in a directory about a file is called a directory entry and includes, in addition to the filename, a pointer to the file itself. Directory entries may refer to other directories, as well as to plain files. A hierarchy of directories and files is thus formed, and is called a filesystem;
A small filesystem +-------+ | | +-------+ / \ usr / \ vmunix |/ \| +-------+ +-------+ | | | | +-------+ +-------+ / | \ staff / | \ bin |/ | tmp \| +-------+ V +-------+ | | +-------+ | | +-------+ | | +-------+ / | \ +-------+ / | \ mckusick / | \| |/ | \ ls |/ | karels | vi \| +-------+ V V +-------+ | | +-------+ +-------+ | | +-------+ | | | | +-------+ +-------+ +-------+ A small filesystem tree
a small one is shown in . Directories may contain subdirectories, and there is no inherent limitation to the depth with which directory nesting may occur. To protect the consistency of the filesystem, the kernel does not permit processes to write directly into directories. A filesystem may include not only plain files and directories, but also references to other objects, such as devices and sockets. The filesystem forms a tree, the beginning of which is the root directory, sometimes referred to by the name slash, spelled with a single solidus character (/). The root directory contains files; in our example in Fig 2.2, it contains vmunix, a copy of the kernel-executable object file. It also contains directories; in this example, it contains the usr directory. Within the usr directory is the bin directory, which mostly contains executable object code of programs, such as the files ls and vi. A process identifies a file by specifying that file's pathname, which is a string composed of zero or more filenames separated by slash (/) characters. The kernel associates two directories with each process for use in interpreting pathnames. A process's root directory is the topmost point in the filesystem that the process can access; it is ordinarily set to the root directory of the entire filesystem. A pathname beginning with a slash is called an absolute pathname, and is interpreted by the kernel starting with the process's root directory. A pathname that does not begin with a slash is called a relative pathname, and is interpreted relative to the current working directory of the process. (This directory also is known by the shorter names current directory or working directory.) The current directory itself may be referred to directly by the name dot, spelled with a single period (.). The filename dot-dot (..) refers to a directory's parent directory. The root directory is its own parent. A process may set its root directory with the chroot system call, and its current directory with the chdir system call. Any process may do chdir at any time, but chroot is permitted only a process with superuser privileges. Chroot is normally used to set up restricted access to the system. Using the filesystem shown in Fig. 2.2, if a process has the root of the filesystem as its root directory, and has /usr as its current directory, it can refer to the file vi either from the root with the absolute pathname /usr/bin/vi, or from its current directory with the relative pathname bin/vi. System utilities and databases are kept in certain well-known directories. Part of the well-defined hierarchy includes a directory that contains the home directory for each user -- for example, /usr/staff/mckusick and /usr/staff/karels in Fig. 2.2. When users log in, the current working directory of their shell is set to the home directory. Within their home directories, users can create directories as easily as they can regular files. Thus, a user can build arbitrarily complex subhierarchies. The user usually knows of only one filesystem, but the system may know that this one virtual filesystem is really composed of several physical filesystems, each on a different device. A physical filesystem may not span multiple hardware devices. Since most physical disk devices are divided into several logical devices, there may be more than one filesystem per physical device, but there will be no more than one per logical device. One filesystem -- the filesystem that anchors all absolute pathnames -- is called the root filesystem, and is always available. Others may be mounted; that is, they may be integrated into the directory hierarchy of the root filesystem. References to a directory that has a filesystem mounted on it are converted transparently by the kernel into references to the root directory of the mounted filesystem. The link system call takes the name of an existing file and another name to create for that file. After a successful link, the file can be accessed by either filename. A filename can be removed with the unlink system call. When the final name for a file is removed (and the final process that has the file open closes it), the file is deleted. Files are organized hierarchically in directories. A directory is a type of file, but, in contrast to regular files, a directory has a structure imposed on it by the system. A process can read a directory as it would an ordinary file, but only the kernel is permitted to modify a directory. Directories are created by the mkdir system call and are removed by the rmdir system call. Before 4.2BSD, the mkdir and rmdir system calls were implemented by a series of link and unlink system calls being done. There were three reasons for adding systems calls explicitly to create and delete directories: The operation could be made atomic. If the system crashed, the directory would not be left half-constructed, as could happen when a series of link operations were used. When a networked filesystem is being run, the creation and deletion of files and directories need to be specified atomically so that they can be serialized. When supporting non-UNIX filesystems, such as an MS-DOS filesystem, on another partition of the disk, the other filesystem may not support link operations. Although other filesystems might support the concept of directories, they probably would not create and delete the directories with links, as the UNIX filesystem does. Consequently, they could create and delete directories only if explicit directory create and delete requests were presented. The chown system call sets the owner and group of a file, and chmod changes protection attributes. Stat applied to a filename can be used to read back such properties of a file. The fchown, fchmod, and fstat system calls are applied to a descriptor, instead of to a filename, to do the same set of operations. The rename system call can be used to give a file a new name in the filesystem, replacing one of the file's old names. Like the directory-creation and directory-deletion operations, the rename system call was added to 4.2BSD to provide atomicity to name changes in the local filesystem. Later, it proved useful explicitly to export renaming operations to foreign filesystems and over the network. The truncate system call was added to 4.2BSD to allow files to be shortened to an arbitrary offset. The call was added primarily in support of the Fortran run-time library, which has the semantics such that the end of a random-access file is set to be wherever the program most recently accessed that file. Without the truncate system call, the only way to shorten a file was to copy the part that was desired to a new file, to delete the old file, then to rename the copy to the original name. As well as this algorithm being slow, the library could potentially fail on a full filesystem. Once the filesystem had the ability to shorten files, the kernel took advantage of that ability to shorten large empty directories. The advantage of shortening empty directories is that it reduces the time spent in the kernel searching them when names are being created or deleted. Newly created files are assigned the user identifier of the process that created them and the group identifier of the directory in which they were created. A three-level access-control mechanism is provided for the protection of files. These three levels specify the accessibility of a file to The user who owns the file The group that owns the file Everyone else Each level of access has separate indicators for read permission, write permission, and execute permission. Files are created with zero length, and may grow when they are written. While a file is open, the system maintains a pointer into the file indicating the current location in the file associated with the descriptor. This pointer can be moved about in the file in a random-access fashion. Processes sharing a file descriptor through a fork or dup system call share the current location pointer. Descriptors created by separate open system calls have separate current location pointers. Files may have holes in them. Holes are void areas in the linear extent of the file where data have never been written. A process can create these holes by positioning the pointer past the current end-of-file and writing. When read, holes are treated by the system as zero-valued bytes. Earlier UNIX systems had a limit of 14 characters per filename component. This limitation was often a problem. For example, in addition to the natural desire of users to give files long descriptive names, a common way of forming filenames is as basename.extension, where the extension (indicating the kind of file, such as .c for C source or .o for intermediate binary object) is one to three characters, leaving 10 to 12 characters for the basename. Source-code-control systems and editors usually take up another two characters, either as a prefix or a suffix, for their purposes, leaving eight to 10 characters. It is easy to use 10 or 12 characters in a single English word as a basename (e.g., ``multiplexer''). It is possible to keep within these limits, but it is inconvenient or even dangerous, because other UNIX systems accept strings longer than the limit when creating files, but then truncate to the limit. A C language source file named multiplexer.c (already 13 characters) might have a source-code-control file with s. prepended, producing a filename s.multiplexer that is indistinguishable from the source-code-control file for multiplexer.ms, a file containing troff source for documentation for the C program. The contents of the two original files could easily get confused with no warning from the source-code-control system. Careful coding can detect this problem, but the long filenames first introduced in 4.2BSD practically eliminate it. Filestores The operations defined for local filesystems are divided into two parts. Common to all local filesystems are hierarchical naming, locking, quotas, attribute management, and protection. These features are independent of how the data will be stored. 4.4BSD has a single implementation to provide these semantics. The other part of the local filesystem is the organization and management of the data on the storage media. Laying out the contents of files on the storage media is the responsibility of the filestore. 4.4BSD supports three different filestore layouts: The traditional Berkeley Fast Filesystem The log-structured filesystem, based on the Sprite operating-system design A memory-based filesystem Although the organizations of these filestores are completely different, these differences are indistinguishable to the processes using the filestores. The Fast Filesystem organizes data into cylinder groups. Files that are likely to be accessed together, based on their locations in the filesystem hierarchy, are stored in the same cylinder group. Files that are not expected to accessed together are moved into different cylinder groups. Thus, files written at the same time may be placed far apart on the disk. The log-structured filesystem organizes data as a log. All data being written at any point in time are gathered together, and are written at the same disk location. Data are never overwritten; instead, a new copy of the file is written that replaces the old one. The old files are reclaimed by a garbage-collection process that runs when the filesystem becomes full and additional free space is needed. The memory-based filesystem is designed to store data in virtual memory. It is used for filesystems that need to support fast but temporary data, such as /tmp. The goal of the memory-based filesystem is to keep the storage packed as compactly as possible to minimize the usage of virtual-memory resources. Network Filesystem Initially, networking was used to transfer data from one machine to another. Later, it evolved to allowing users to log in remotely to another machine. The next logical step was to bring the data to the user, instead of having the user go to the data -- and network filesystems were born. Users working locally do not experience the network delays on each keystroke, so they have a more responsive environment. Bringing the filesystem to a local machine was among the first of the major client-server applications. The server is the remote machine that exports one or more of its filesystems. The client is the local machine that imports those filesystems. From the local client's point of view, a remotely mounted filesystem appears in the file-tree name space just like any other locally mounted filesystem. Local clients can change into directories on the remote filesystem, and can read, write, and execute binaries within that remote filesystem identically to the way that they can do these operations on a local filesystem. When the local client does an operation on a remote filesystem, the request is packaged and is sent to the server. The server does the requested operation and returns either the requested information or an error indicating why the request was denied. To get reasonable performance, the client must cache frequently accessed data. The complexity of remote filesystems lies in maintaining cache consistency between the server and its many clients. Although many remote-filesystem protocols have been developed over the years, the most pervasive one in use among UNIX systems is the Network Filesystem (NFS), whose protocol and most widely used implementation were done by Sun Microsystems. The 4.4BSD kernel supports the NFS protocol, although the implementation was done independently from the protocol specification . The NFS protocol is described in Chapter 9. Terminals Terminals support the standard system I/O operations, as well as a collection of terminal-specific operations to control input-character editing and output delays. At the lowest level are the terminal device drivers that control the hardware terminal ports. Terminal input is handled according to the underlying communication characteristics, such as baud rate, and according to a set of software-controllable parameters, such as parity checking. Layered above the terminal device drivers are line disciplines that provide various degrees of character processing. The default line discipline is selected when a port is being used for an interactive login. The line discipline is run in canonical mode; input is processed to provide standard line-oriented editing functions, and input is presented to a process on a line-by-line basis. Screen editors and programs that communicate with other computers generally run in noncanonical mode (also commonly referred to as raw mode or character-at-a-time mode). In this mode, input is passed through to the reading process immediately and without interpretation. All special-character input processing is disabled, no erase or other line editing processing is done, and all characters are passed to the program that is reading from the terminal. It is possible to configure the terminal in thousands of combinations between these two extremes. For example, a screen editor that wanted to receive user interrupts asynchronously might enable the special characters that generate signals and enable output flow control, but otherwise run in noncanonical mode; all other characters would be passed through to the process uninterpreted. On output, the terminal handler provides simple formatting services, including Converting the line-feed character to the two-character carriage-return-line-feed sequence Inserting delays after certain standard control characters Expanding tabs Displaying echoed nongraphic ASCII characters as a two-character sequence of the form ``^C'' (i.e., the ASCII caret character followed by the ASCII character that is the character's value offset from the ASCII ``@'' character). Each of these formatting services can be disabled individually by a process through control requests. Interprocess Communication Interprocess communication in 4.4BSD is organized in communication domains. Domains currently supported include the local domain, for communication between processes executing on the same machine; the internet domain, for communication between processes using the TCP/IP protocol suite (perhaps within the Internet); the ISO/OSI protocol family for communication between sites required to run them; and the XNS domain, for communication between processes using the XEROX Network Systems (XNS) protocols. Within a domain, communication takes place between communication endpoints known as sockets. As mentioned in Section 2.6, the socket system call creates a socket and returns a descriptor; other IPC system calls are described in Chapter 11. Each socket has a type that defines its communications semantics; these semantics include properties such as reliability, ordering, and prevention of duplication of messages. Each socket has associated with it a communication protocol. This protocol provides the semantics required by the socket according to the latter's type. Applications may request a specific protocol when creating a socket, or may allow the system to select a protocol that is appropriate for the type of socket being created. Sockets may have addresses bound to them. The form and meaning of socket addresses are dependent on the communication domain in which the socket is created. Binding a name to a socket in the local domain causes a file to be created in the filesystem. Normal data transmitted and received through sockets are untyped. Data-representation issues are the responsibility of libraries built on top of the interprocess-communication facilities. In addition to transporting normal data, communication domains may support the transmission and reception of specially typed data, termed access rights. The local domain, for example, uses this facility to pass descriptors between processes. Networking implementations on UNIX before 4.2BSD usually worked by overloading the character-device interfaces. One goal of the socket interface was for naive programs to be able to work without change on stream-style connections. Such programs can work only if the read and write systems calls are unchanged. Consequently, the original interfaces were left intact, and were made to work on stream-type sockets. A new interface was added for more complicated sockets, such as those used to send datagrams, with which a destination address must be presented with each send call. Another benefit is that the new interface is highly portable. Shortly after a test release was available from Berkeley, the socket interface had been ported to System III by a UNIX vendor (although AT&T did not support the socket interface until the release of System V Release 4, deciding instead to use the Eighth Edition stream mechanism). The socket interface was also ported to run in many Ethernet boards by vendors, such as Excelan and Interlan, that were selling into the PC market, where the machines were too small to run networking in the main processor. More recently, the socket interface was used as the basis for Microsoft's Winsock networking interface for Windows. Network Communication Some of the communication domains supported by the socket IPC mechanism provide access to network protocols. These protocols are implemented as a separate software layer logically below the socket software in the kernel. The kernel provides many ancillary services, such as buffer management, message routing, standardized interfaces to the protocols, and interfaces to the network interface drivers for the use of the various network protocols. At the time that 4.2BSD was being implemented, there were many networking protocols in use or under development, each with its own strengths and weaknesses. There was no clearly superior protocol or protocol suite. By supporting multiple protocols, 4.2BSD could provide interoperability and resource sharing among the diverse set of machines that was available in the Berkeley environment. Multiple-protocol support also provides for future changes. Today's protocols designed for 10- to 100-Mbit-per-second Ethernets are likely to be inadequate for tomorrow's 1- to 10-Gbit-per-second fiber-optic networks. Consequently, the network-communication layer is designed to support multiple protocols. New protocols are added to the kernel without the support for older protocols being affected. Older applications can continue to operate using the old protocol over the same physical network as is used by newer applications running with a newer network protocol. Network Implementation The first protocol suite implemented in 4.2BSD was DARPA's Transmission Control Protocol/Internet Protocol (TCP/IP). The CSRG chose TCP/IP as the first network to incorporate into the socket IPC framework, because a 4.1BSD-based implementation was publicly available from a DARPA-sponsored project at Bolt, Beranek, and Newman (BBN). That was an influential choice: The 4.2BSD implementation is the main reason for the extremely widespread use of this protocol suite. Later performance and capability improvements to the TCP/IP implementation have also been widely adopted. The TCP/IP implementation is described in detail in Chapter 13. The release of 4.3BSD added the Xerox Network Systems (XNS) protocol suite, partly building on work done at the University of Maryland and at Cornell University. This suite was needed to connect isolated machines that could not communicate using TCP/IP. The release of 4.4BSD added the ISO protocol suite because of the latter's increasing visibility both within and outside the United States. Because of the somewhat different semantics defined for the ISO protocols, some minor changes were required in the socket interface to accommodate these semantics. The changes were made such that they were invisible to clients of other existing protocols. The ISO protocols also required extensive addition to the two-level routing tables provided by the kernel in 4.3BSD. The greatly expanded routing capabilities of 4.4BSD include arbitrary levels of routing with variable-length addresses and network masks. System Operation Bootstrapping mechanisms are used to start the system running. First, the 4.4BSD kernel must be loaded into the main memory of the processor. Once loaded, it must go through an initialization phase to set the hardware into a known state. Next, the kernel must do autoconfiguration, a process that finds and configures the peripherals that are attached to the processor. The system begins running in single-user mode while a start-up script does disk checks and starts the accounting and quota checking. Finally, the start-up script starts the general system services and brings up the system to full multiuser operation. During multiuser operation, processes wait for login requests on the terminal lines and network ports that have been configured for user access. When a login request is detected, a login process is spawned and user validation is done. When the login validation is successful, a login shell is created from which the user can run additional processes. References Accetta et al, 1986 Mach: A New Kernel Foundation for UNIX Development" M. Accetta R. Baron W. Bolosky D. Golub R. Rashid A. Tevanian M. Young 93-113 USENIX Association Conference Proceedings USENIX Association June 1986 Cheriton, 1988 The V Distributed System D. R. Cheriton 314-333 Comm ACM, 31, 3 March 1988 Ewens et al, 1985 Tunis: A Distributed Multiprocessor Operating System P. Ewens D. R. Blythe M. Funkenhauser R. C. Holt 247-254 USENIX Assocation Conference Proceedings USENIX Association June 1985 Gingell et al, 1987 Virtual Memory Architecture in SunOS R. Gingell J. Moran W. Shannon 81-94 USENIX Association Conference Proceedings USENIX Association June 1987 Kernighan & Pike, 1984 The UNIX Programming Environment B. W. Kernighan R. Pike Prentice-Hall
Englewood Cliffs NJ
1984 Macklem, 1994 The 4.4BSD NFS Implementation R. Macklem 6:1-14 4.4BSD System Manager's Manual O'Reilly & Associates, Inc.
Sebastopol CA
1994 McKusick & Karels, 1988 Design of a General Purpose Memory Allocator for the 4.3BSD UNIX Kernel M. K. McKusick M. J. Karels 295-304 USENIX Assocation Conference Proceedings USENIX Assocation June 1998 McKusick et al, 1994 Berkeley Software Architecture Manual, 4.4BSD Edition M. K. McKusick M. J. Karels S. J. Leffler W. N. Joy R. S. Faber 5:1-42 4.4BSD Programmer's Supplementary Documents O'Reilly & Associates, Inc.
Sebastopol CA
1994 Ritchie, 1988 Early Kernel Design private communication D. M. Ritchie March 1988 Rosenblum & Ousterhout, 1992 The Design and Implementation of a Log-Structured File System M. Rosenblum K. Ousterhout 26-52 ACM Transactions on Computer Systems, 10, 1 Association for Computing Machinery February 1992 Rozier et al, 1988 Chorus Distributed Operating Systems M. Rozier V. Abrossimov F. Armand I. Boule M. Gien M. Guillemont F. Herrmann C. Kaiser S. Langlois P. Leonard W. Neuhauser 305-370 USENIX Computing Systems, 1, 4 Fall 1988 Tevanian, 1987 Architecture-Independent Virtual Memory Management for Parallel and Distributed Environments: The Mach Approach Technical Report CMU-CS-88-106, A. Tevanian Department of Computer Science, Carnegie-Mellon University
Pittsburgh PA
December 1987 diff --git a/en_US.ISO8859-1/books/design-44bsd/freebsd.dsl b/en_US.ISO8859-1/books/design-44bsd/freebsd.dsl index ba9b0d542f..59efdeff4e 100644 --- a/en_US.ISO8859-1/books/design-44bsd/freebsd.dsl +++ b/en_US.ISO8859-1/books/design-44bsd/freebsd.dsl @@ -1,18 +1,18 @@ - + + ]> ;; Keep the legalnotice together with the rest of the text (define %generate-legalnotice-link% #f) diff --git a/en_US.ISO8859-1/books/dev-model/book.sgml b/en_US.ISO8859-1/books/dev-model/book.sgml index 0f78a2c652..262e1babf0 100644 --- a/en_US.ISO8859-1/books/dev-model/book.sgml +++ b/en_US.ISO8859-1/books/dev-model/book.sgml @@ -1,2688 +1,2684 @@ -%bookinfo; - -%man; - -%freebsd; + +%books.ent; %chapters; ]> A project model for the FreeBSD Project Niklas Saers 2002, 2003 Niklas Saers 1.0 December 4th, 2003 Ready for commit to FreeBSD Documentation 0.7 April 7th, 2003 Release for review by the Documentation team 0.6 March 1st, 2003 Incorporated corrections noted by interviewees and reviewers 0.5 February 1st, 2003 Initial review by interviewees Foreword Up until now, the FreeBSD project has released a number of described techniques to do different parts of work. However, a project model summarising how the project is structured is needed because of the increasing amount of project members. This goes hand-in-hand with Brooks' law that adding another person to a late project will make it later since it will increase the communication needs . A project model is a tool to reduce the communication needs. This paper will provide such a project model and is donated to the FreeBSD Documentation project where it can evolve together with the project so that it can at any point in time reflect the way the project works. It is based on . I would like to thank the following people for taking the time to explain things that were unclear to me and for proofreading the document. Andrey A. Chernov ache@freebsd.org Bruce A. Mah bmah@freebsd.org Dag-Erling Smørgrav des@freebsd.org Giorgos Keramidaskeramida@freebsd.org Ingvil Hovig ingvil.hovig@skatteetaten.no Jesper Holckjeh.inf@cbs.dk John Baldwin jhb@freebsd.org John Polstra jdp@freebsd.org Kirk McKusick mckusick@freebsd.org Mark Linimon linimon@freebsd.org Marleen Devos Niels Jørgenssennielsj@ruc.dk Nik Clayton nik@freebsd.org Poul-Henning Kamp phk@freebsd.org Simon L. Nielsen simon@freebsd.org Overview A project model is a means to reduce the communications overhead in a project. As shown by , increasing the number of project participants increases the communication in the project exponentionally. FreeBSD has during the past few year increased both its mass of active users and committers, and the communication in the project has risen accordingly. This project model will serve to reduce this overhead by providing an up-to-date description of the project. During the Core elections in 2002, Mark Murray stated I am opposed to a long rule-book, as that satisfies lawyer-tendencies, and is counter to the technocentricity that the project so badly needs. . This project model is not meant to be a tool to justify creating impositions for developers, but as a tool to facilitate coordination. It is meant as a description of the project, with an overview of how the different processes are executed. It is an introduction to how the FreeBSD project works. The FreeBSD project model will be described as of April 1st, 2003. It is based on the Niels Jørgensen's paper , FreeBSD's official documents, discussions on FreeBSD mailing lists and interviews with developers. After providing definitions of terms used, this document will outline the organisational structure (including role descriptions and communication lines), discuss the methodology model and after presenting the tools used for process control, it will present the defined processes. Finally it will outline major sub-projects of the FreeBSD project. , Section 1.2 and 1.3 give the vision and the architectural guidelines for the project. The vision is To produce the best UNIX-like operating system package possible, with due respect to the original software tools ideology as well as usability, performance and stability. The architectural guidelines help determine whether a problem that someone wants to be solved is within the scope of the project Definitions
Activity An activity is an element of work performed during the course of a project . It has an output and leads towards an outcome. Such an output can either be an input to another activity or a part of the process' delivery.
Process A process is a series of activities that lead towards a particular outcome. A process can consist of one or more sub-processes. An example of a process is software design.
Hat A hat is synonymous with role. A hat has certain responsibilities in a process and for the process outcome. The hat executes activities. It is well defined what issues the hat should be contacted about by the project members and people outside the project.
Outcome An outcome is the final output of the process. This is synonymous with deliverable, that is defined as any measurable, tangible, verifiable outcome, result or item that must be produced to complete a project or part of a project. Often used more narrowly in reference to an external deliverable, which is a deliverable that is subject to approval by the project sponsor or customer by . Examples of outcomes are a piece of software, a decision made or a report written.
FreeBSD When saying FreeBSD we will mean the BSD derivative UNIX-like operating system FreeBSD, whereas when saying the FreeBSD Project we will mean the project organisation.
Organisational structure While no-one takes ownership of FreeBSD, the FreeBSD organisation is divided into core, committers and contributors and is part of the FreeBSD community that lives around it.
The FreeBSD Project's structure
Number of committers has been determined by going through CVS logs from December 1st, 2001 to December 1st, 2002 and contributors by going through the list of contributions and problem reports. The main resource in the FreeBSD community is its developers: the committers and contributors. It is with their contributions that the project can move forward. Regular developers are referred to as contributors. As by January 1st, 2003, there are an estimated 5500 contributors on the project. Committers are developers with the privilege of being able to commit changes. These are usually the most active developers who are willing to spend their time not only integrating their own code but integrating code submitted by the developers who do not have this privilege. They are also the developers who elect the core team, and they have access to closed discussions. The project can be grouped into four distinct separate parts, and most developers will during their involvement in the FreeBSD project only be involved with one of these parts. The four parts are kernel development, userland development, ports and documentation. When referring to the base system, both kernel and userland is meant. This split changes our triangle to look like this:
The FreeBSD Project's structure with committers in categories
Number of committers per area has been determined by going through CVS logs from December 1st, 2001 to December 1st, 2002. Note that many committers work in multiple areas, making the total number higher than the real number of committers. The total number of committers at that time was 275. Committers fall into three groups: committers who are only concerned with one area of the project (for instance file systems), committers who are involved only with one sub-project and committers who commit to different parts of the code, including sub-projects. Because some committers work on different parts, the total number in the committers section of the triangle is higher than in the above triangle. The kernel is the main building block of FreeBSD. While the userland applications are protected against faults in other userland applications, the entire system is vulnerable to errors in the kernel. This, combined with the vast amount of dependencies in the kernel and that it is not easy to see all the consequences of a kernel change, demands developers with a relative full understanding of the kernel. Multiple development efforts in the kernel also requires a closer coordination than userland applications do. The core utilities, known as userland, provide the interface that identifies FreeBSD, both user interface, shared libraries and external interfaces to connecting clients. Currently, 99 people are involved in userland development and maintenance, many being maintainers for their own part of the code. Maintainership will be discussed in the section. Documentation is handled by and includes all documents surrounding the FreeBSD project, including the web pages. There are currently 41 people involved in the FreeBSD Documentation Project. Ports is the collection of meta-data that is needed to make software packages build correctly on FreeBSD. An example of a port is the port for the web-browser Mozilla. It contains information about where to fetch the source, what patches to apply and how, and how the package should be installed on the system. This allows automated tools to fetch, build and install the package. As of this writing, there are more than 7800 ports available. Statistics are generated by counting the number of entries in the file ports/INDEX by January 1st, 2003. , ranging from web servers to games, programming languages and most of the application types that are in use on modern computers. Ports will be discussed further in the section . Methodology model
Development model There is no defined model for how people write code in FreeBSD. However, Niels Jørgenssen has suggested a model of how written code is integrated into the project.
Jørgenssen's model for change integration
The development release is the FreeBSD-CURRENT ("-CURRENT") branch and the production release is the FreeBSD-STABLE branch ("-STABLE") . This is a model for one change, and shows that after coding, developers seek community review and try integrating it with their own systems. After integrating the change into the development release, called FreeBSD-CURRENT, it is tested by many users and developers in the FreeBSD community. After it has gone through enough testing, it is merged into the production release, called FreeBSD-STABLE. Unless each stage is finished successfully, the developer needs to go back and make modifications in the code and restart the process. To integrate a change with either -CURRENT or -STABLE is called making a commit. Jørgensen found that most FreeBSD developers work individually, meaning that this model is used in parallel by many developers on the different ongoing development efforts. A developer can also be working on multiple changes, so that while he is waiting for review or people to test one or more of his changes, he may be writing another change. As each commit represents an increment, this is a massively incremental model. The commits are in fact so frequent that during one year The period from December 1st, 2001 to December 3rd, 2002 was examined to find this number. , 132148 commits were made, making a daily average of 360 commits. Within the code bracket in Jørgensen's figure, each programmer has his own working style and follows his own development models. The bracket could very well have been called development as it includes requirements gathering and analysis, system and detailed design, implementation and verification. However, the only output from these stages is the source code or system documentation. From a stepwise model's perspective (such as the waterfall model), the other brackets can be seen as further verification and system integration. This system integration is also important to see if a change is accepted by the community. Up until the code is committed, the developer is free to choose how much to communicate about it to the rest of the project. In order for -CURRENT to work as a buffer (so that bright ideas that had some undiscovered drawbacks can be backed out) the minimum time a commit should be in -CURRENT before merging it to -STABLE is 3 days. Such a merge is referred to as an MFC (Merge From Current). It is important to notice the word change. Most commits do not contain radical new features, but are maintenance updates. The only exceptions from this model are security fixes and changes to features that are deprecated in the -CURRENT branch. In these cases, changes can be committed directly to the -STABLE branch. In addition to many people working on the project, there are many related projects to the FreeBSD Project. These are either projects developing brand new features, sub-projects or projects whose outcome is incorporated into FreeBSD For instance, the development of the Bluetooth stack started as a sub-project until it was deemed stable enough to be merged into the -CURRENT branch. Now it is a part of the core FreeBSD system. . These projects fit into the FreeBSD Project just like regular development efforts: they produce code that is integrated with the FreeBSD Project. However, some of them (like Ports and Documentation) have the privilege of being applicable to both branches or commit directly to both -CURRENT and -STABLE. There is no standards to how design should be done, nor is design collected in a centralised repository. The main design is that of 4.4BSD. According to Kirk McKusick, after 20 years of developing UNIX operating systems, the interfaces are for the most part figured out. There is therefore no need for much design. However, new applications of the system and new hardware leads to some implementations being more beneficial than those that used to be preferred. One example is the introduction of web browsing that made the normal TCP/IP connection a short burst of data rather than a steady stream over a longer period of time. As design is a part of the Code bracket in Jørgenssen's model, it is up to every developer or sub-project how this should be done. Even if the design should be stored in a central repository, the output from the design stages would be of limited use as the differences of methodologies would make them poorly if at all interoperable. For the overall design of the project, the project relies on the sub-projects to negotiate fit interfaces between each other rather than to dictate interfacing.
Release branches The releases of FreeBSD is best illustrated by a tree with many branches where each major branch represents a major version. Minor versions are represented by branches of the major branches. In the following release tree, arrows that follow one-another in a particular direction represent a branch. Boxes with full lines and diamonds represent official releases. Boxes with dotted lines represent the development branch at that time. Security branches are represented by ovals. Diamonds differ from boxes in that they represent a fork, meaning a place where a branch splits into two branches where one of the branches becomes a sub-branch. For example, at 4.0-RELEASE the 4.0-CURRENT branch split into 4-STABLE and 5.0-CURRENT. At 4.5-RELEASE, the branch forked off a security release called RELENG_4_5.
The FreeBSD release tree
The latest -CURRENT version is always referred to as -CURRENT, while the latest -STABLE release is always referred to as -STABLE. In this figure, -STABLE refers to 4-STABLE while -CURRENT refers to 5.0-CURRENT following 5.0-RELEASE. A major release is always made from the -CURRENT branch. However, the -CURRENT branch does not need to fork at that point in time, but can focus on stabilising. An example of this is that following 3.0-RELEASE, 3.1-RELEASE was also a continuation of the -CURRENT-branch, and -CURRENT did not become a true development branch until this version was released and the 3-STABLE branch was forked. When -CURRENT returns to becoming a development branch, it can only be followed by a major release. 5-STABLE is predicted to be forked off 5.0-CURRENT at around 5.1-RELEASE or 5.2-RELEASE. It is not until 5-STABLE is forked that the development branch will be branded 6.0-CURRENT. A minor release is made from the -CURRENT branch following a major release, or from the -STABLE branch. Following and including, 4.3-RELEASE The first release this actually happened for was 4.5-RELEASE, but security branches were at the same time created for 4.3-RELEASE and 4.4-RELEASE. , when a minor release has been made, it becomes a security branch. This is meant for organisations that do not want to follow the -STABLE branch and the potential new/changed features it offers, but instead require an absolutely stable environment, only updating to implement security updates. There is a terminology overlap with respect to the word "stable", which leads to some confusion. The -STABLE branch is still a development branch, whose goal is to be useful for most people. If it is never acceptable for a system to get changes that are not announced at the time it is deployed, that system should run a security branch. Each update to a security branch is called a patchlevel. For every security enhancement that is done, the patchlevel number is increased, making it easy for people tracking the branch to see what security enhancements they have implemented. In cases where there have been especially serious security flaws, an entire new release can be made from a security branch. An example of this is 4.6.2-RELEASE.
Model summary To summarise, the development model of FreeBSD can be seen as the following tree:
The overall development model
The tree of the FreeBSD development with ongoing development efforts and continuous integration. The tree symbolises the release versions with major versions spawning new main branches and minor versions being versions of the main branch. The top branch is the -CURRENT branch where all new development is integrated, and the -STABLE branch is the branch directly below it. Clouds of development efforts hang over the project where developers use the development models they see fit. The product of their work is then integrated into -CURRENT where it undergoes parallel debugging and is finally merged from -CURRENT into -STABLE. Security fixes are merged from -STABLE to the security branches.
Hats Many committers have a special area of responsibility. These roles are called hats . These hats can be either project roles, such as public relations officer, or maintainer for a certain area of the code. Because this is a project where people give voluntarily of their spare time, people with assigned hats are not always available. They must therefore appoint a deputy that can perform the hat's role in his or her absence. The other option is to have the role held by a group. Many of these hats are not formalised. Formalised hats have a charter stating the exact purpose of the hat along with its privileges and responsibilities. The writing of such charters is a new part of the project, and has thus yet to be completed for all hats. These hat descriptions are not such a formalisation, rather a summary of the role with links to the charter where available and contact addresses,
General Hats
Contributor A Contributor contributes to the FreeBSD project either as a developer, as an author, by sending problem reports, or in other ways contributing to the progress of the project. A contributor has no special privileges in the FreeBSD project.
Committer A person who has the required privileges to add his code or documentation to the repository. A committer has made a commit within the past 12 months. An active committer is a committer who has made an average of one commit per month during that time. It is worth noting that there are no technical barriers to prevent someone, once having gained commit privileges, to make commits in parts of the source the committer did not specifically get permission to modify. However, when wanting to make modifications to parts a committer has not been involved in before, he/she should read the logs to see what has happened in this area before, and also read the MAINTAINER file to see if the maintainer of this part has any special requests on how changes in the code should be made Also, since is allowed to give commit privileges without approval from core, a committer who has gained his privileges through contributing to the ports sub-project should be careful and have his changes approved before committing anything outside the ports tree.
Core Team The core team is elected by the committers from the pool of committers and serves as the board of directors of the FreeBSD project. It promotes active contributors to committers, assigns people to well-defined hats, and is the final arbiter of decisions involving which way the project should be heading. As by January 1st, 2003, core consisted of 9 members. Elections are held every two years.
Maintainership Maintainership means that that person is responsible for what is allowed to go into that area of the code and has the final say should disagreements over the code occur. This involves involves proactive work aimed at stimulating contributions and reactive work in reviewing commits. With the FreeBSD source comes the MAINTAINERS file that contains a one-line summary of how each maintainer would like contributions to be made. Having this notice and contact information enables developers to focus on the development effort rather than being stuck in a slow correspondence should the maintainer be unavailable for some time. If the maintainer is unavailable for an unreasonably long period of time, and other people do a significant amount of work, maintainership may be switched without the maintainer's approval. This is based on the stance that maintainership should be demonstrated, not declared. Maintainership of a particular piece of code is a hat that is not held as a group.
Official Hats The official hats in the FreeBSD Project are hats that are more or less formalised and mainly administrative roles. They have the authority and responsibility for their area. The following illustration shows the responsibility lines. After this follows a description of each hat, including who it is held by.
Overview of official hats
All boxes consist of groups of committers, except for the dotted boxes where the holders are not necessarily committers. The flattened circles are sub-projects and consist of both committers and non-committers of the main project.
Documentation project manager architect is responsible for defining and following up documentation goals for the committers in the Documentation project. Hat held by: The DocEng team doceng@FreeBSD.org. The DocEng Charter.
CVSup Mirror Site Coordinator The CVSup Mirror Site Coordinator coordinates all the s to ensure that they are distributing current versions of the software, that they have the capacity to update themselves when major updates are in progress, and making it easy for the general public to find their closest CVSup mirror. Hat currently held by: John Polstra jdp@FreeBSD.org.
Internationalisation The Internationalisation hat is responsible for coordinating the localisation efforts of the FreeBSD kernel and userland utilities. The translation effort are coordinated by . The Internationalisation hat should suggest and promote standards and guidelines for writing and maintaining the software in a fashion that makes it easier to translate. Hat currently available.
Postmaster The Postmaster is responsible for mail being correctly delivered to the committers' email address. He is also responsible for ensuring that the mailing lists work and should take measures against possible disruptions of mail such as having troll-, spam- and virus-filters. Hat currently held by: Jonathan M. Bresler jmb@FreeBSD.org.
Release Coordination The responsibilities of the Release Engineering Team are Setting, publishing and following a release schedule for official releases Documenting and formalising release engineering procedures Creation and maintenance of code branches Coordinating with the Ports and Documentation teams to have an updated set of packages and documentation released with the new releases Coordinating with the Security team so that pending releases are not affected by recently disclosed vulnerabilities. Further information about the development process is available in the section. Hat held by: the Release Engineering team re@FreeBSD.org, currently headed by Murray Stokely murray@FreeBSD.org. The Release Engineering Charter.
Public Relations & Corporate Liaison The Public Relations & Corporate Liaison's responsibilities are: Making press statements when happenings that are important to the FreeBSD Project happen. Being the official contact person for corporations that are working close with the FreeBSD Project. Take steps to promote FreeBSD within both the Open Source community and the corporate world. Handle the freebsd-advocacy mailing list. This hat is currently not occupied.
Security Officer The Security Officer's main responsibility is to coordinate information exchange with others in the security community and in the FreeBSD project. The Security Officer is also responsible for taking action when security problems are reported and promoting proactive development behaviour when it comes to security. Because of the fear that information about vulnerabilities may leak out to people with malicious intent before a patch is available, only the Security Officer, consisting of an officer, a deputy and two members, receive sensitive information about security issues. However, to create or implement a patch, the Security Officer has the Security Officer Team security-team@FreeBSD.org to help do the work. Hat held by: the Security Officer security-officer@FreeBSD.org, currently headed by Jacques Vidrine nectar@FreeBSD.org. The Security Officer and The Security Officer Team's charter.
Source Repository Manager The Source Repository Manager is the only one who is allowed to directly modify the repository without using the tool. It is his/her responsibility to ensure that technical problems that arise in the repository are resolved quickly. The source repository manager has the authority to back out commits if this is necessary to resolve a CVS technical problem. Hat held by: the Source Repository Manager cvs@FreeBSD.org, currently headed by Peter Wemm peter@FreeBSD.org.
Election Manager The Election Manager is responsible for the process. The manager is responsible for running and maintaining the election system, and is the final authority should minor unforseen events happen in the election process. Major unforseen events have to be discussed with the Hat held only during elections.
Web site Management The Web site Management hat is responsible for coordinating the rollout of updated web pages on mirrors around the world, for the overall structure of the primary web site and the system it is running upon. The management needs to coordinate the content with and acts as maintainer for the www tree. Hat held by: the FreeBSD Webmasters www@FreeBSD.org.
Ports Manager The Ports Manager acts as a liaison between and the core project, and all requests from the project should go to the ports manager. Hat held by: the Ports Management Team portmgr@FreeBSD.org.
Standards The Standards hat is responsible for ensuring that FreeBSD complies with the standards it is committed to , keeping up to date on the development of these standards and notifying FreeBSD developers of important changes that allows them to take a proactive role and decrease the time between a standards update and FreeBSD's compliancy. Hat currently held by: Garrett Wollman wollman@FreeBSD.org.
Core Secretary The Core Secretary's main responsibility is to write drafts to and publish the final Core Reports. The secretary also keeps the core agenda, thus ensuring that no balls are dropped unresolved. Hat currently held by: Wilko Bulte wilko@FreeBSD.org.
XFree86 Project, Inc. Liaison The XFree86 Project liaison relays information from the XFree86 Project to the right people in the FreeBSD Project and visa versa. This enables the projects to be alligned without everyone in both projects staying up-to-date on the other project. Hat currently held by: Rich Murphey rich@FreeBSD.org.
GNATS Administrator The GNATS Administrator is responsible for ensuring that the maintenance database is in working order, that the entries are correctly categorised and that there are no invalid entries. Hat currently held by: Steve Price steve@FreeBSD.org.
Bugmeister The Bugmeister is person in charge of the problem report group. Hat currently held by: Giorgos Keramidas keramida@FreeBSD.org.
Donations Liaison Officer The task of the donations liason officer is to match the developers with needs with people or organisations willing to make a donation. The Donations Liason Charter is available here Hat held by: the Donations Liaison Office donations@FreeBSD.org, currently headed by Michael W. Lucas mwlucas@FreeBSD.org.
Admin (Also called FreeBSD Cluster Admin) The admin team consists are the people responsible for administrating the computers that the project relies on for its distributed work and communication to be synchronised. It consists mainly of those people who have physical access to the servers. Hat held by: the Admin team admin@FreeBSD.org, currently headed by Mark Murray markm@FreeBSD.org
Process dependent hats
Report originator The person originally responsible for filing a Problem Report.
Bugbuster A person who will either find the right person to solve the problem, or close the PR if it is a duplicate or otherwise not an interesting one.
Mentor A mentor is a committer who takes it upon him/her to initialise a new committer to the project, both in terms of ensuring the new committers setup is valid, that the new committer knows the available tools required in his/her work and that the new committer knows what is expected of him/her in terms of behaviour.
Vendor The person(s) or organisation whom external code comes from and whom patches are sent to.
Reviewers People on the mailing list where the request for review is posted.
CVSup Mirror Site Admin A CVSup Mirror Site Admin has accesses to a server that he/she uses to mirror the CVS repository. The admin works with the to ensure the site remains up-to-date and is following the general policy of official mirror sites.
Processes The following section will describe the defined project processes. Issues that are not handled by these processes happen on an ad-hoc basis based on what has been customary to do in similar cases.
Adding new and removing old committers The Core team has the responsibility of giving and removing commit privileges to contributors. This can only be done through a vote on the core mailing list. The ports and documentation sub-projects can give commit privileges to people working on these projects, but have to date not removed such privileges. Normally a contributor is recommended to core by a committer. For contributors or outsiders to contact core asking to be a committer is not well thought of and is usually rejected. If the area of particular interest for the developer potentially overlaps with other committers' area of maintainership, the opinion of those maintainers is sought. However, it is frequently this committer that recommends the developer. When a contributor is given committer status, he is assigned a mentor. The committer who recommended the new committer will, in the general case, take it upon himself to be the new committers mentor. When a contributor is given his commit bit, a -signed email is sent from either , or nik@freebsd.org to both admins@freebsd.org, the assigned mentor, the new committer and core confirming the approval of a new account. The mentor then gathers a password line, public key and PGP key from the new committer and sends them to . When the new account is created, the mentor activates the commit bit and guides the new committer through the rest of the initial process.
Process summary: adding a new committer
When a contributor sends a piece of code, the receiving committer may choose to recommend that the contributor is given commit privileges. If he recommends this to core, they will vote on this recommendation. If they vote in favour, a mentor is assigned the new committer and the new committer has to email his details to the administrators for an account to be created. After this, the new committer is all set to make his first commit. By tradition, this is by adding his name to the committers list. Recall that a committer is considered to be someone who has committed code during the past 12 months. However, it is not until after 18 months of inactivity have passed that commit privileges are eligible to be revoked. There are, however, no automatic procedures for doing this. For reactions concerning commit privileges not triggered by time, see section 8.5.8.
Process summary: removing a committer
When Core decides to clean up the committers list, they check who has not made a commit for the past 18 months. Committers who have not done so have their commit bits revoked. It is also possible for committers to request that their commit bit be retired if for some reason they are no longer going to be actively committing to the project. In this case, it can also be restored at a later time by core, should the committer ask. Roles in this process:
Adding/Removing an official CVSup Mirror A mirror is a replica of the official CVSup master that contains all the up-to-date source code for all the branches in the FreeBSD project, ports and documentation. Adding an official CVSup mirror starts with the potential installing the cvsup-mirror package. Having done this and updated the source code with a mirror site, he now runs a fairly recent unofficial CVSup mirror. Deciding he has a stable environment, the processing power, the network capacity and the storage capacity to run an official mirror, he mails the who decides whether the mirror should become an official mirror or not. In making this decision, the has to determine whether that geographical area needs another mirror site, if the mirror administrator has the skills to run it reliably, if the network bandwidth is adequate and if the master server has the capacity to server another mirror. If decides that the mirror should become an official mirror, he obtains an authentication key from the mirror admin that he installs so the mirror admin can update the mirror from the master server.
Process summary: adding a CVSup mirror
When a CVSup mirror administrator of an unofficial mirror offers to become an official mirror site, the CVSup coordinator decides if another mirror is needed and if there is sufficient capacity to accommodate it. If so, an authorisation key is requested and the mirror is given access to the main distribution site and added to the list of official mirrors. Roles involved in this process: Tools used in this process:
Committing code The committing of new or modified code is one of the most frequent processes in the FreeBSD project and will usually happen many times a day. Committing of code can only be done by a committer. Committers commit either code written by themselves, code submitted to them or code submitted through a problem report. When code is written by the developer that is non-trivial, he should seek a code review from the community. This is done by sending mail to the relevant list asking for review. Before submitting the code for review, he should ensure it compiles correctly with the entire tree and that all relevant tests run. This is called pre-commit test. When contributed code is received, it should be reviewed by the committer and tested the same way. When a change is committed to a part of the source that has been contributed from an outside , the maintainer should ensure that the patch is contributed back to the vendor. This is in line with the open source philosophy and makes it easier to stay in sync with outside projects as the patches do not have to be reapplied every time a new release is made. After the code has been available for review and no further changes are necessary, the code is committed into the development branch, -CURRENT. If the change applies for the -STABLE branch or the other branches as well, a Merge From Current ("MFC") countdown is set by the committer. After the number of days the committer chose when setting the MFC have passed, an email will automatically be sent to the committer reminding him to commit it to the -STABLE branch (and possibly security branches as well). Only security critical changes should be merged to security branches. Delaying the commit to -STABLE and other branches allows for parallel debugging where the committed code is tested on a wide range of configurations. This makes changes to -STABLE to contain fewer faults and thus giving the branch its name.
Process summary: A committer commits code
When a committer has written a piece of code and wants to commit it, he first needs to determine if it is trivial enough to go in without prior review or if it should first be reviewed by the developer community. If the code is trivial or has been reviewed and the committer is not the maintainer, he should consult the maintainer before proceeding. If the code is contributed by an outside vendor, the maintainer should create a patch that is sent back to the vendor. The code is then committed and the deployed by the users. Should they find problems with the code, this will be reported and the committer can go back to writing a patch. If a vendor is affected, he can choose to implement or ignore the patch.
Process summary: A contributor commits code
The difference when a contributor makes a code contribution is that he submits the code through the send-pr program. This report is picked up by the maintainer who reviews the code and commits it. Hats included in this process are:
Core election Core elections are held at least every two years. The first Core election was held September 2000 Nine core members are elected. New elections are held if the number of core members drops below seven. New elections can also be held should at least 1/3 of the active committers demand this. When an election is to take place, core announces this at least 6 weeks in advance, and appoints an election manager to run the elections. Only committers can be elected into core. The candidates need to submit their candidacy at least one week before the election starts, but can refine their statements until the voting starts. They are presented in the candidates list. When writing their election statements, the candidates must answer a few standard questions submitted by the election manager. During elections, the rule that a committer must have committed during the 12 past months is followed strictly. Only these committers are eligible to vote. When voting, the committer may vote once in support of up to nine nominees. The voting is done over a period of four weeks with reminders being posted on developers mailing list that is available to all committers. The election results are released one week after the election ends, and the new core team takes office one week after the results have been posted. Should there be a voting tie, this will be resolved by the new, unambiguously elected core members. Votes and candidate statements are archived, but the archives are not publicly available.
Process summary: Core elections
Core announces the election and selects an election manager. He prepares the elections, and when ready, candidates can announce their candidacies through submitting their statements. The committers then vote. After the vote is over, the election results are announced and the new core team takes office. Hats in core elections are:
Development of new features Within the project there are sub-projects that are working on new features. These projects are generally done by one person . Every project is free to organise development as it sees fit. However, when the project is merged to the -CURRENT branch it must follow the project guidelines. When the code has been well tested in the -CURRENT branch and deemed stable enough and relevant to the -STABLE branch, it is merged to the -STABLE branch. The requirements of the project are given by developer wishes, requests from the community in terms of direct requests by mail, Problem Reports, commercial funding for the development of features, or contributions by the scientific community. The wishes that come within the responsibility of a developer are given to that developer who prioritises his time between the request and his wishes. A common way to do this is maintain a TODO-list maintained by the project. Items that do not come within someone's responsibility are collected on TODO-lists unless someone volunteers to take the responsibility. All requests, their distribution and follow-up are handled by the tool. Requirements analysis happens in two ways. The requests that come in are discussed on mailing lists, both within the main project and in the sub-project that the request belongs to or is spawned by the request. Furthermore, individual developers on the sub-project will evaluate the feasibility of the requests and determine the prioritisation between them. Other than archives of the discussions that have taken place, no outcome is created by this phase that is merged into the main project. As the requests are prioritised by the individual developers on the basis of doing what they find interesting, necessary or are funded to do, there is no overall strategy or priorisation of what requests to regard as requirements and following up their correct implementation. However, most developers have some shared vision of what issues are more important, and they can ask for guidelines from the release engineering team and technical review board. The verification phase of the project is two-fold. Before committing code to the current-branch, developers request their code to be reviewed by their peers. This review is for the most part done by functional testing, but also code review is important. When the code is committed to the branch, a broader functional testing will happen, that may trigger further code review and debugging should the code not behave as expected. This second verification form may be regarded as structural verification. Although the sub-projects themselves may write formal tests such as unit tests, these are usually not collected by the main project and are usually removed before the code is committed to the current branch. More and more tests are however performed when building the system (make world). These tests are however a very new addition and no systematic framework for these tests have yet been created.
Maintenance It is an advantage to the project to for each area of the source have at least one person that knows this area well. Some parts of the code have designated maintainers. Others have de-facto maintainers, and some parts of the system do not have maintainers. The maintainer is usually a person from the sub-project that wrote and integrated the code, or someone who has ported it from the platform it was written for. sendmail and named are examples of code that has been merged from other platforms. The maintainer's job is to make sure the code is in sync with the project the code comes from if it is contributed code, and apply patches submitted by the community or write fixes to issues that are discovered. The main bulk of work that is put into the FreeBSD project is maintenance. has made a figure showing the life cycle of changes.
Jørgenssen's model for change integration
Here development release refers to the -CURRENT branch while production release refers to the -STABLE branch. The pre-commit test is the functional testing by peer developers when asked to do so or trying out the code to determine the status of the sub-project. Parallel debugging is the functional testing that can trigger more review, and debugging when the code is included in the -CURRENT branch. As of this writing, there were 275 committers in the project. When they commit a change to a branch, that constitutes a new release. It is very common for users in the community to track a particular branch. The immediate existence of a new release makes the changes widely available right away and allows for rapid feedback from the community. This also gives the community the response time they expect on issues that are of importance to them. This makes the community more engaged, and thus allows for more and better feedback that again spurs more maintenance and ultimately should create a better product. Before making changes to code in parts of the tree that has a history unknown to the committer, the committer is required to read the commit logs to see why certain features are implemented the way they are in order not to make mistakes that have previously either been thought through or resolved.
Problem reporting FreeBSD comes with a problem reporting tool called send-pr that is a part of the GNATS package. All users and developers are encouraged to use this tool for reporting problems in software they do not maintain. Problems include bug reports, feature requests, features that should be enhanced and notices of new versions of external software that is included in the project. Problem reports are sent to an email address where it is inserted into the GNATS maintenance database. A classifies the problem and sends it to the correct group or maintainer within the project. After someone has taken responsibility for the report, the report is being analysed. This analysis includes verifying the problem and thinking out a solution for the problem. Often feedback is required from the report originator or even from the FreeBSD community. Once a patch for the problem is made, the originator may be asked to try it out. Finally, the working patch is integrated into the project, and documented if applicable. It there goes through the regular maintenance cycle as described in section . These are the states a problem report can be in: open, analyzed, feedback, patched, suspended and closed. The suspended state is for when further progress is not possible due to the lack of information or for when the task would require so much work that nobody is working on it at the moment.
Process summary: problem reporting
A problem is reported by the report originator. It is then classified by a bugbuster and handed to the correct maintainer. He verifies the problem and discusses the problem with the originator until he has enough information to create a working patch. This patch is then committed and the problem report is closed. The roles included in this process are: .
Reacting to misbehaviour has a number of rules that committers should follow. However, it happens that these rules are broken. The following rules exist in order to be able to react to misbehaviour. They specify what actions will result in how long a suspension the committer's commit privileges. Committing during code freezes without the approval of the Release Engineering team - 2 days Committing to a security branch without approval - 2 days Commit wars - 5 days to all participating parties Impolite or inappropriate behaviour - 5 days For the suspensions to be efficient, any single core member can implement a suspension before discussing it on the core mailing list. Repeat offenders can, with a 2/3 vote by core, receive harsher penalties, including permanent removal of commit privileges. (However, the latter is always viewed as a last resort, due to its inherent tendency to create controversy). All suspensions are posted to the developers mailing list, a list available to committers only. It is important that you cannot be suspended for making technical errors. All penalties come from breaking social etiquette. Hats involved in this process:
Release engineering The FreeBSD project has a Release Engineering team with a principal release engineer that is responsible for creating releases of FreeBSD that can be brought out to the user community via the net or sold in retail outlets. Since FreeBSD is available on multiple platforms and releases for the different architectures are made available at the same time, the team has one person in charge of each architecture. Also, there are roles in the team responsible for coordinating quality assurance efforts, building a package set and for having an updated set of documents. When referring to the release engineer, a representative for the release engineering team is meant. When a release is coming, the FreeBSD project changes shape somewhat. A release schedule is made containing feature- and code-freezes, release of interim releases and the final release. A feature-freeze means no new features are allowed to be committed to the branch without the release engineers' explicit consent. Code-freeze means no changes to the code (like bugs-fixes) are allowed to be committed without the release engineers explicit consent. This feature- and code-freeze is known as stabilising. During the release process, the release engineer has the full authority to revert to older versions of code and thus "back out" changes should he find that the changes are not suitable to be included in the release. There are three different kinds of releases: .0 releases are the first release of a major version. These are branched of the -CURRENT branch and have a significantly longer release engineering cycle due to the unstable nature of the -CURRENT branch .X releases are releases of the -STABLE branch. They are scheduled to come out every 4 months. .X.Y releases are security releases that follow the .X branch. These come out only when sufficient security fixes have been merged since the last release on that branch. New features are rarely included, and the security team is far more involved in these than in regular releases. For releases of the -STABLE-branch, the release process starts 45 days before the anticipated release date. During the first phase, the first 15 days, the developers merge what changes they have had in -CURRENT that they want to have in the release to the release branch. When this period is over, the code enters a 15 day code freeze in which only bug fixes, documentation updates, security-related fixes and minor device driver changes are allowed. These changes must be approved by the release engineer in advance. At the beginning of the last 15 day period a release candidate is created for widespread testing. Updates are less likely to be allowed during this period, except for important bug fixes and security updates. In this final period, all releases are considered release candidates. At the end of the release process, a release is created with the new version number, including binary distributions on web sites and the creation of a CD-ROM images. However, the release isn't considered "really released" until a -signed message stating exactly that, is sent to the mailing list freebsd-announce; anything labelled as a "release" before that may well be in-process and subject to change before the PGP-signed message is sent. Many commercial vendors use these images to create CD-ROMs that are sold in retail outlets. . The releases of the -CURRENT-branch (that is, all releases that end with .0) are very similar, but with twice as long timeframe. It starts 8 weeks prior to the release with announcement of the release time line. Two weeks into the release process, the feature freeze is initiated and performance tweaks should be kept to a minimum. Four weeks prior to the release, an official beta version is made available. Two weeks prior to release, the code is officially branched into a new version. This version is given release candidate status, and as with the release engineering of -STABLE, the code freeze of the release candidate is hardened. However, development on the main development branch can continue. Other than these differences, the release engineering processes are alike. .0 releases go into their own branch and are aimed mainly at early adopters. It is not until .1 versions are released that the branch becomes -STABLE and -CURRENT targets the next major version. Most releases are made when a given date that has been deemed a long enough time since the previous release comes. A target is set for having major releases every 18 months and minor releases every 4 months. The user community has made it very clear that security and stability cannot be sacrificed by self-imposed deadlines and target release dates. For slips of time not to become to long with regards to security and stability issues, extra dicipline is required when committing changes to -STABLE.
Process summary: release engineering
These are the stages in the release engineering process. Multiple release candidates may be created until the release is deemed stable enough to be released.
Tools The major support tools for supporting the development process are CVS, CVSup, Perforce, GNATS, Mailman and OpenSSH. Except for CVSup, these are externally developed tools. These tools are commonly used in the open source world.
Concurrent Versions System (CVS) Concurrent Versions System or simply CVS is a system to handle multiple versions of text files and tracking who committed what changes and why. A project lives within a repository and different versions are considered different branches.
CVSup CVSup is a software package for distributing and updating collections of files across a network. It is consists of a client program, cvsup, and a server program, cvsupd. The package is tailored specifically for distributing CVS repositories, and by taking advantage of CVS' properties, it performs updates much faster than traditional systems.
GNATS GNATS is a maintenance database consisting of a set of tools to track bugs at a central site. It supports the bug tracking process for sending and handling bugs as well as querying and updating the database and editing bug reports. The project uses one of its many client interfaces, send-pr, to send Problem Reports by email to the projects central GNATS server. The committers have also web and command-line clients available.
Mailman Mailman is a program that automates the management of mailing lists. The FreeBSD Project uses it to run 17 general lists, 45 technical lists and 6 limited lists. It is also used for many mailing lists set up and used by other people and projects in the FreeBSD community. General lists are lists for the general public, technical lists are mainly for the development of specific areas of interest, and closed lists are for internal communication not intended for the general public. The majority of all the communication in the project goes through these 68 lists , Appendix C.
Perforce Perforce is a commercial software configuration management system developed by Perforce Systems that is available on over 50 operating systems. It is a collection of clients built around the Perforce server that contains the central file repository and tracks the operations done upon it. The clients are both clients for accessing the repository and administration of its configuration.
Pretty Good Privacy Pretty Good Privacy, better known as PGP, is a cryptosystem using a public key architecture to allow people to digitally sign and/or encrypt information in order to ensure secure communication between two parties. A signature is used when sending information out many recipients, enabling them to verify that the information has not been tampered with before they received it. In the FreeBSD Project this is the primary means of ensuring that information has been written by the person who claims to have written it, and not altered in transit.
Secure Shell Secure Shell is a standard for securely logging into a remote system and for executing commands on the remote system. It allows other connections, called tunnels, to be established and protected between the two involved systems. This standard exists in two primary versions, and only version two is used for the FreeBSD Project. The most common implementation of the standard is OpenSSH that is a part of the project's main distribution. Since its source is updated more often than FreeBSD releases, the latest version is also available in the ports tree.
Sub-projects Sub-projects are formed to reduce the amount of communication needed to coordinate the group of developers. When a problem area is sufficiently isolated, most communication would be within the group focusing on the problem, requiring less communication with the groups they communicate with than were the group not isolated.
The Ports Subproject A port is a set of meta-data and patches that are needed to fetch, compile and install correctly an external piece of software on a FreeBSD system. The amount of ports have grown at a tremendous rate, as shown by the following figure.
Number of ports added between 1996 and 2003
is taken from the FreeBSD web site. It shows the number of ports available to FreeBSD in the period 1995 to 2003. It looks like the curve has first grown exponentionally, and then since the middle of 2001 grown linerly. As the external software described by the port often is under continued development, the amount of work required to maintain the ports is already large, and increasing. This has led to the ports part of the FreeBSD project gaining a more empowered structure, and is more and more becoming a sub-project of the FreeBSD project. Ports has its own core team with the as its leader, and this team can appoint committers without FreeBSD Core's approval. Unlike in the FreeBSD Project, where a lot of maintenance frequently is rewarded with a commit bit, the ports sub-project contains many active maintainers that are not committers. Unlike the main project, the ports tree is not branched. Every release of FreeBSD follows the current ports collection and has thus available updated information on where to find programs and how to build them. This, however, means that a port that makes dependencies on the system may need to have variations depending on what version of FreeBSD it runs on. With an unbranched ports repository it is not possible to guarantee that any port will run on anything other than -CURRENT and -STABLE, in particular older, minor releases. There is neither the infrastructure nor volunteer time needed to guarantee this. For efficiency of communication, teams depending on Ports, such as the release engineering team, have their own ports liaisons.
The FreeBSD Documentation Project The FreeBSD Documentation project was started January 1995. From the initial group of a project leader, four team leaders and 16 members, they are now a total of 44 committers. The documentation mailing list has just under 300 members, indicating that there is quite a large community around it. The goal of the Documentation project is to provide good and useful documentation of the FreeBSD project, thus making it easier for new users to get familiar with the system and detailing advanced features for the users. The main tasks in the Documentation project are to work on current projects in the FreeBSD Documentation Set, and translate the documentation to other languages. Like the FreeBSD Project, documentation is split in the same branches. This is done so that there is always an updated version of the documentation for each version. Only documentation errors are corrected in the security branches. Like the ports sub-project, the Documentation project can appoint documentation committers without FreeBSD Core's approval. . The Documentation project has a primer. This is used both to introduce new project members to the standard tools and syntaxes and acts as a reference when working on the project.
References Frederick P.Brooks 19751995 Pearson Education Limited 0201835959 Addison-Wesley Pub Co The Mythical Man-Month Essays on Software Engineering, Anniversary Edition (2nd Edition) NiklasSaers 2003 A project model for the FreeBSD Project Candidatus Scientiarum thesis NielsJørgensen 2001 Putting it All in the Trunk Incremental Software Development in the FreeBSD Open Source Project Project Management Institute 19962000 Project Management Institute 1-880410-23-0 Project Management Institute
Newtown Square Pennsylvania USA
PMBOK Guide A Guide to the Project Management Body of Knowledge, 2000 Edition 2002 The FreeBSD Project Core Bylaws 2002 The FreeBSD Documentation Project FreeBSD Developer's Handbook 2002 The FreeBSD Project Core team election 2002 WarnerLosh 2002 The FreeBSD Documentation Project Working with Hats Dag-ErlingSmørgrav HitenPandya 2002 The FreeBSD Documentation Project The FreeBSD Documentation Project Problem Report Handling Guidelines Dag-ErlingSmørgrav 2002 The FreeBSD Documentation Project The FreeBSD Documentation Project Writing FreeBSD Problem Reports 2001 The FreeBSD Documentation Project The FreeBSD Documentation Project Committers Guide MurrayStokely 2002 The FreeBSD Documentation Project The FreeBSD Documentation Project FreeBSD Release Engineering The FreeBSD Documentation Project FreeBSD Handbook 2002 The FreeBSD Documentation Project The FreeBSD Documentation Project Contributors to FreeBSD 2002 The FreeBSD Project The FreeBSD Project Core team elections 2002 2002 The FreeBSD Project The FreeBSD Project Commit Bit Expiration Policy 2002/04/06 15:35:30 2002 The FreeBSD Project The FreeBSD Project New Account Creation Procedure 2002/08/19 17:11:27 2002 The FreeBSD Documentation Project The FreeBSD Documentation Project FreeBSD DocEng Team Charter 2003/03/16 12:17 GregLehey 2002 Greg Lehey Greg Lehey Two years in the trenches The evolution of a software project diff --git a/en_US.ISO8859-1/books/developers-handbook/book.sgml b/en_US.ISO8859-1/books/developers-handbook/book.sgml index 3b0acaeca6..8d8ecff6e7 100644 --- a/en_US.ISO8859-1/books/developers-handbook/book.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/book.sgml @@ -1,286 +1,276 @@ -%bookinfo; - -%man; - -%freebsd; + +%books.ent; %chapters; - %authors - %mailing-lists; - -%trademarks; - -%urls; ]> FreeBSD Developers' Handbook The FreeBSD Documentation Project August 2000 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.legalnotice; &tm-attrib.freebsd; &tm-attrib.apple; &tm-attrib.ibm; &tm-attrib.ieee; &tm-attrib.intel; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.sun; &tm-attrib.general; Welcome to the Developers' Handbook. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD World Wide Web server. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. Basics &chap.introduction; &chap.tools; &chap.secure; &chap.l10n; &chap.policies; &chap.testing; Interprocess Communication * Signals Signals, pipes, semaphores, message queues, shared memory, ports, sockets, doors &chap.sockets; &chap.ipv6; Kernel &chap.dma; &chap.kerneldebug; * UFS UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling, locking, metadata, soft-updates, LFS, portalfs, procfs, vnodes, memory sharing, memory objects, TLBs, caching * AFS AFS, NFS, SANs, etc. * Syscons Syscons, tty, PCVT, serial console, screen savers, etc. * Compatibility Layers * Linux Linux, SVR4, etc. Architectures &chap.x86; * Alpha Explanation of alignment errors, how to fix, how to ignore. Example assembly language code for FreeBSD/alpha. Appendices Dave A Patterson John L Hennessy 1998Morgan Kaufmann Publishers, Inc. 1-55860-428-6 Morgan Kaufmann Publishers, Inc. Computer Organization and Design The Hardware / Software Interface 1-2 W. Richard Stevens 1993Addison Wesley Longman, Inc. 0-201-56317-7 Addison Wesley Longman, Inc. Advanced Programming in the Unix Environment 1-2 Marshall Kirk McKusick Keith Bostic Michael J Karels John S Quarterman 1996Addison-Wesley Publishing Company, Inc. 0-201-54979-4 Addison-Wesley Publishing Company, Inc. The Design and Implementation of the 4.4 BSD Operating System 1-2 Aleph One Phrack 49; "Smashing the Stack for Fun and Profit" Chrispin Cowan Calton Pu Dave Maier StackGuard; Automatic Adaptive Detection and Prevention of Buffer-Overflow Attacks Todd Miller Theo de Raadt strlcpy and strlcat -- consistent, safe string copy and concatenation. diff --git a/en_US.ISO8859-1/books/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml index cdca438fc1..411ab9d474 100644 --- a/en_US.ISO8859-1/books/faq/book.sgml +++ b/en_US.ISO8859-1/books/faq/book.sgml @@ -1,12492 +1,12472 @@ - -%man; - -%freebsd; - -%authors; - -%teams; - - -%bookinfo; - - -%mailing-lists; - - -%urls; - - -%trademarks; - + +%books.ent; - ]> Frequently Asked Questions for FreeBSD 2.X, 3.X, 4.X and 5.X The FreeBSD Documentation Project $FreeBSD$ 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.legalnotice; &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.adobe; &tm-attrib.creative; &tm-attrib.cvsup; &tm-attrib.ibm; &tm-attrib.ieee; &tm-attrib.intel; &tm-attrib.iomega; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.mips; &tm-attrib.netscape; &tm-attrib.opengroup; &tm-attrib.oracle; &tm-attrib.sgi; &tm-attrib.sparc; &tm-attrib.sun; &tm-attrib.usrobotics; &tm-attrib.xfree86; &tm-attrib.general; This is the FAQ for FreeBSD versions 2.X, 3.X, 4.X and 5.X. All entries are assumed to be relevant to FreeBSD 2.0.5 and later, unless otherwise noted. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD World Wide Web server. It may also be downloaded as one large HTML file with HTTP or as plain text, &postscript;, PDF, etc. from the FreeBSD FTP server. You may also want to Search the FAQ. Introduction Welcome to the FreeBSD 2.X-5.X FAQ! As is usual with Usenet FAQs, this document aims to cover the most frequently asked questions concerning the FreeBSD operating system (and of course answer them!). Although originally intended to reduce bandwidth and avoid the same old questions being asked over and over again, FAQs have become recognized as valuable information resources. Every effort has been made to make this FAQ as informative as possible; if you have any suggestions as to how it may be improved, please feel free to mail them to the &a.doc;. What is FreeBSD? Briefly, FreeBSD is a &unix; like operating system for the &i386;, IA-64, PC-98, Alpha/AXP, and &ultrasparc; platforms based on U.C. Berkeley's 4.4BSD-Lite release, with some 4.4BSD-Lite2 enhancements. It is also based indirectly on William Jolitz's port of U.C. Berkeley's Net/2 to the &i386;, known as 386BSD, though very little of the 386BSD code remains. A fuller description of what FreeBSD is and how it can work for you may be found on the FreeBSD home page. FreeBSD is used by companies, Internet Service Providers, researchers, computer professionals, students and home users all over the world in their work, education and recreation. For more detailed information on FreeBSD, please see the FreeBSD Handbook. What is the goal of the FreeBSD Project? The goal of the FreeBSD Project is to provide software that may be used for any purpose and without strings attached. Many of us have a significant investment in the code (and project) and would certainly not mind a little financial compensation now and then, but we definitely do not insist on it. We believe that our first and foremost mission is to provide code to any and all comers, and for whatever purpose, so that the code gets the widest possible use and provides the widest possible benefit. This is, we believe, one of the most fundamental goals of Free Software and one that we enthusiastically support. That code in our source tree which falls under the GNU General Public License (GPL) or GNU Library General Public License (LGPL) comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software, we do, however, endeavor to replace such software with submissions under the more relaxed FreeBSD license whenever possible. Does the FreeBSD license have any restrictions? Yes. Those restrictions do not control how you use the code, merely how you treat the FreeBSD Project itself. If you have serious license concerns, read the actual license. For the simply curious, the license can be summarized like this. Do not claim that you wrote this. Do not sue us if it breaks. Can FreeBSD replace my current operating system? For most people, yes. But this question is not quite that cut-and-dried. Most people do not actually use an operating system. They use applications. The applications are what really use the operating system. FreeBSD is designed to provide a robust and full-featured environment for applications. It supports a wide variety of web browsers, office suites, email readers, graphics programs, programming environments, network servers, and just about everything else you might want. Most of these applications can be managed through the Ports Collection. If you need to use an application that is only available on one operating system, you simply cannot replace that operating system. Chances are there is a very similar application on FreeBSD, however. If you want a solid office or Internet server, a reliable workstation, or just the ability to do your job without interruptions, FreeBSD will almost certainly do everything you need. Many computer users across the world, including both novices and experienced &unix; administrators, use FreeBSD as their only desktop operating system. If you are migrating to FreeBSD from some other &unix; environment, you already know most of what you need to. If your background is in graphic-driven operating systems such as &windows; and older versions of &macos;, expect to invest additional time learning the &unix; way of doing things. This FAQ and the FreeBSD Handbook are excellent places to start. Why is it called FreeBSD? It may be used free of charge, even by commercial users. Full source for the operating system is freely available, and the minimum possible restrictions have been placed upon its use, distribution and incorporation into other work (commercial or non-commercial). Anyone who has an improvement or bug fix is free to submit their code and have it added to the source tree (subject to one or two obvious provisions). It is worth pointing out that the word free is being used in two ways here, one meaning at no cost, the other meaning you can do whatever you like. Apart from one or two things you cannot do with the FreeBSD code, for example pretending you wrote it, you can really do whatever you like with it. What are the differences between FreeBSD and NetBSD, OpenBSD, and other open source BSD operating systems? James Howard wrote a good explanation of the history and differences between the various projects for DaemonNews, called The BSD Family Tree which goes a fair way to answering this question. What is the latest version of FreeBSD? At this point in FreeBSD's development, there are two parallel development branches; releases are being made from both branches. The 4.X series of releases is being made from the -STABLE branch and the 5.X series of releases is being made from -CURRENT. Version &rel.current; is the latest release from the -CURRENT branch; it was released in &rel.current.date;. Version &rel2.current; is the latest release from the -STABLE branch; it was released in &rel2.current.date;. Briefly, -STABLE is aimed at the ISP, corporate user, or any user who wants stability and a minimal number of changes compared to the new (and possibly unstable) features of the latest -CURRENT snapshot. Releases can come from either branch, but -CURRENT should only be used if you are prepared for its increased volatility (relative to -STABLE, that is). Releases are made every few months. While many people stay more up-to-date with the FreeBSD sources (see the questions on FreeBSD-CURRENT and FreeBSD-STABLE) than that, doing so is more of a commitment, as the sources are a moving target. More information on FreeBSD releases can be found on the Release Engineering page on the FreeBSD Web site. What is FreeBSD-CURRENT? FreeBSD-CURRENT is the development version of the operating system, which will in due course become the new &os.stable; branch. This is expected to happen around 5.3-RELEASE. As such, it is really only of interest to developers working on the system and die-hard hobbyists. See the relevant section in the handbook for details on running -CURRENT. If you are not familiar with the operating system or are not capable of identifying the difference between a real problem and a temporary problem, you should not use FreeBSD-CURRENT. This branch sometimes evolves quite quickly and can be un-buildable for a number of days at a time. People that use FreeBSD-CURRENT are expected to be able to analyze any problems and only report them if they are deemed to be mistakes rather than glitches. Questions such as make world produces some error about groups on the -CURRENT mailing list may be treated with contempt. Every day, snapshot releases are made based on the current state of the -CURRENT and -STABLE branches. Distributions of the occasional snapshot are made available. The goals behind each snapshot release are: To test the latest version of the installation software. To give people who would like to run -CURRENT or -STABLE but who do not have the time or bandwidth to follow it on a day-to-day basis an easy way of bootstrapping it onto their systems. To preserve a fixed reference point for the code in question, just in case we break something really badly later. (Although CVS normally prevents anything horrible like this happening :) To ensure that all new features and fixes in need of testing have the greatest possible number of potential testers. No claims are made that any -CURRENT snapshot can be considered production quality for any purpose. If you want to run a stable and fully tested system, you will have to stick to full releases, or use the -STABLE snapshots. Snapshot releases are directly available from ftp://current.FreeBSD.org/pub/FreeBSD/snapshots/. 3-STABLE snapshots are no longer being produced. Snapshots are generated, on the average, daily for all actively developed branches. What is the FreeBSD-STABLE concept? Back when FreeBSD 2.0.5 was released, FreeBSD development branched in two. One branch was named -STABLE, one -CURRENT. FreeBSD-STABLE is intended for Internet Service Providers and other commercial enterprises for whom sudden shifts or experimental features are quite undesirable. It receives only well-tested bug fixes and other small incremental enhancements. FreeBSD-CURRENT, on the other hand, has been one unbroken line since 2.0 was released, leading towards 5.2.1-RELEASE (and beyond). At 5.3-RELEASE, the 5-STABLE branch is expected to be created, and &os.current; will become 6-CURRENT. If a little ASCII art would help, this is how it looks: 2.0 | | | [2.1-STABLE] *BRANCH* 2.0.5 -> 2.1 -> 2.1.5 -> 2.1.6 -> 2.1.7.1 [2.1-STABLE ends] | (Mar 1997) | | | [2.2-STABLE] *BRANCH* 2.2.1 -> 2.2.2-RELEASE -> 2.2.5 -> 2.2.6 -> 2.2.7 -> 2.2.8 [end] | (Mar 1997) (Oct 97) (Apr 98) (Jul 98) (Dec 98) | | 3.0-SNAPs (started Q1 1997) | | 3.0-RELEASE (Oct 1998) | | [3.0-STABLE] *BRANCH* 3.1-RELEASE (Feb 1999) -> 3.2 -> 3.3 -> 3.4 -> 3.5 -> 3.5.1 | (May 1999) (Sep 1999) (Dec 1999) (June 2000) (July 2000) | | [4.0-STABLE] *BRANCH* 4.0 (Mar 2000) -> 4.1 -> 4.1.1 -> 4.2 -> 4.3 -> 4.4 -> ... later 4.X releases ... | | (July 2000) (Sep 2000) (Nov 2000) 5.0-RELEASE (Jan 2003) | | 5.1-RELEASE (Jun 2003) | | 5.2-RELEASE (Jan 2004) | | 5.2.1-RELEASE (Feb 2004) | \|/ + [5-CURRENT continues] The 2.2-STABLE branch was retired with the release of 2.2.8. The 3-STABLE branch has ended with the release of 3.5.1, the final 3.X release. The only changes made to either of these branches will be, for the most part, security-related bug fixes. 4-STABLE is the actively developed -STABLE branch. The latest release on the 4-STABLE branch is &rel2.current;-RELEASE, which was released in &rel2.current.date;. The 5-CURRENT branch is slowly progressing toward the creation of a 5-STABLE branch. See What is FreeBSD-CURRENT? for more information on this branch. When are FreeBSD releases made? The &a.re; releases a new version of FreeBSD about every four months, on average. Release dates are announced well in advance, so that the people working on the system know when their projects need to be finished and tested. A testing period precedes each release, in order to ensure that the addition of new features does not compromise the stability of the release. Many users regard this caution as one of the best things about FreeBSD, even though waiting for all the latest goodies to reach -STABLE can be a little frustrating. More information on the release engineering process (including a schedule of upcoming releases) can be found on the release engineering pages on the FreeBSD Web site. For people who need or want a little more excitement, binary snapshots are made daily as discussed above. Who is responsible for FreeBSD? The key decisions concerning the FreeBSD project, such as the overall direction of the project and who is allowed to add code to the source tree, are made by a core team of 9 people. There is a much larger team of more than 300 committers who are authorized to make changes directly to the FreeBSD source tree. However, most non-trivial changes are discussed in advance in the mailing lists, and there are no restrictions on who may take part in the discussion. Where can I get FreeBSD? Every significant release of FreeBSD is available via anonymous FTP from the FreeBSD FTP site: For the current 3.X-STABLE release, 3.5.1-RELEASE, see the 3.5.1-RELEASE directory. The latest 5.X release, &rel.current;-RELEASE can be found in the &rel.current;-RELEASE directory. The latest 4-STABLE release, &rel2.current;-RELEASE can be found in the &rel2.current;-RELEASE directory. 4.X snapshots are usually made daily. 5.X Snapshot releases are made daily for the -CURRENT branch, these being of service purely to bleeding-edge testers and developers. Information about obtaining FreeBSD on CD, DVD, and other media can be found in the Handbook. How do I set up a FreeBSD mirror? Information on setting up a FreeBSD mirror can be found in the Mirroring FreeBSD article. How do I access the Problem Report database? The Problem Report database of all user change requests may be queried by using our web-based PR query interface. The &man.send-pr.1; command can be used to submit problem reports and change requests via electronic mail. The web-based problem report submission interface is currently disabled due to persistent abuse. Before submitting a problem report, please read Writing FreeBSD Problem Reports, an article on how to write good problem reports. How do I become a FreeBSD Web mirror? There are multiple ways to mirror the Web pages. You can retrieve the formatted files from a FreeBSD CVSup server using the application net/cvsup. The file /usr/share/examples/cvsup/www-supfile contains an example CVSup configuration file for web mirrors. You can download the web site source code from any FreeBSD FTP server using your favorite ftp mirror tool. Keep in mind that you have to build these sources before publishing them. Start mirroring at . What other sources of information are there? Please check the Documentation list on the main FreeBSD web site. Documentation and Support What good books are there about FreeBSD? The project produces a wide range of documentation, available online from this link: . The same documents are available as packages, that you can easily install on your FreeBSD system. More details on documentation packages can be found in the next paragraphs. In addition, the Bibliography at the end of this FAQ, and the one in the Handbook reference other recommended books. Is the documentation available in other formats, such as plain text (ASCII), or &postscript;? Yes. The documentation is available in a number of different formats and compression schemes on the FreeBSD FTP site, in the /pub/FreeBSD/doc/ directory. The documentation is categorized in a number of different ways. These include: The document's name, such as faq, or handbook. The document's language and encoding. These are based on the locale names you will find under /usr/share/locale on your FreeBSD system. The current languages and encodings that we have for documentation are as follows: Name Meaning en_US.ISO8859-1 US English de_DE.ISO8859-1 German es_ES.ISO8859-1 Spanish fr_FR.ISO8859-1 French ja_JP.eucJP Japanese (EUC encoding) ru_RU.KOI8-R Russian (KOI8-R encoding) zh_TW.Big5 Chinese (Big5 encoding) Some documents may not be available in all languages. The document's format. We produce the documentation in a number of different output formats. Each format has its own advantages and disadvantages. Some formats are better suited for online reading, while others are meant to be aesthetically pleasing when printed on paper. Having the documentation available in any of these formats ensures that our readers will be able to read the parts they are interested in, either on their monitor, or on paper after printing the documents. The currently available formats are: Format Meaning html-split A collection of small, linked, HTML files. html One large HTML file containing the entire document pdb Palm Pilot database format, for use with the iSilo reader. pdf Adobe's Portable Document Format ps &postscript; rtf Microsoft's Rich Text Format Page numbers are not automatically updated when loading this format into Word. Press CTRLA, CTRLEND, F9 after loading the document, to update the page numbers. txt Plain text The compression and packaging scheme. There are three of these currently in use. Where the format is html-split, the files are bundled up using &man.tar.1;. The resulting .tar file is then compressed using the compression schemes detailed in the next point. All the other formats generate one file, called book.format (i.e., book.pdb, book.html, and so on). These files are then compressed using two compression schemes. Scheme Description zip The Zip format. If you want to uncompress this on FreeBSD you will need to install the archivers/unzip port first. bz2 The BZip2 format. Less widespread than Zip, but generally gives smaller files. Install the archivers/bzip2 port to uncompress these files. So the &postscript; version of the Handbook, compressed using BZip2 will be stored in a file called book.ps.bz2 in the handbook/ directory. After choosing the format and compression mechanism that you want to download, you must then decide whether or not you want to download the document as a FreeBSD package. The advantage of downloading and installing the package is that the documentation can then be managed using the normal FreeBSD package management comments, such as &man.pkg.add.1; and &man.pkg.delete.1;. If you decide to download and install the package then you must know the filename to download. The documentation-as-packages files are stored in a directory called packages. Each package file looks like document-name.lang.encoding.format.tgz. For example, the FAQ, in English, formatted as PDF, is in the package called faq.en_US.ISO8859-1.pdf.tgz. Knowing this, you can use the following command to install the English PDF FAQ package. &prompt.root; pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO8859-1.pdf.tgz Having done that, you can use &man.pkg.info.1; to determine where the file has been installed. &prompt.root; pkg_info -f faq.en_US.ISO8859-1.pdf Information for faq.en_US.ISO8859-1.pdf: Packing list: Package name: faq.en_US.ISO8859-1.pdf CWD to /usr/share/doc/en_US.ISO8859-1/books/faq File: book.pdf CWD to . File: +COMMENT (ignored) File: +DESC (ignored) As you can see, book.pdf will have been installed into /usr/share/doc/en_US.ISO8859-1/books/faq. If you do not want to use the packages then you will have to download the compressed files yourself, uncompress them, and then copy the appropriate documents into place. For example, the split HTML version of the FAQ, compressed using &man.bzip2.1;, can be found in the doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2 file. To download and uncompress that file you would have to do this. &prompt.root; fetch ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2 &prompt.root; bzip2 -d book.html-split.tar.bz2 &prompt.root; tar xvf book.html-split.tar You will be left with a collection of .html files. The main one is called index.html, which will contain the table of contents, introductory material, and links to the other parts of the document. You can then copy or move these to their final location as necessary. Where do I find info on the FreeBSD mailing lists? You can find full information in the Handbook entry on mailing-lists. Where do I find the FreeBSD Y2K info? You can find full information in the FreeBSD Y2K page. What FreeBSD news groups are available? You can find full information in the Handbook entry on newsgroups. Are there FreeBSD IRC (Internet Relay Chat) channels? Yes, most major IRC networks host a FreeBSD chat channel: Channel #FreeBSD on EFNet is a FreeBSD forum, but do not go there for tech support or try to get folks there to help you avoid the pain of reading manual pages or doing your own research. It is a chat channel, first and foremost, and topics there are just as likely to involve sex, sports or nuclear weapons as they are FreeBSD. You Have Been Warned! Available at server irc.chat.org. Channel #FreeBSDhelp on EFNet is a channel dedicated to helping FreeBSD users. They are much more sympathetic to questions than #FreeBSD is. Channel #FreeBSD on DALNET is available at irc.dal.net in the US and irc.eu.dal.net in Europe. Channel #FreeBSD on UNDERNET is available at us.undernet.org in the US and eu.undernet.org in Europe. Since it is a help channel, be prepared to read the documents you are referred to. Channel #FreeBSD on HybNet. This channel is a help channel. A list of servers can be found on the HybNet web site. Each of these channels are distinct and are not connected to each other. Their chat styles also differ, so you may need to try each to find one suited to your chat style. As with all types of IRC traffic, if you are easily offended or cannot deal with lots of young people (and more than a few older ones) doing the verbal equivalent of jello wrestling, do not even bother with it. Where can I get commercial FreeBSD training and support? DaemonNews provides commercial training and support for FreeBSD. More information can be found at their BSD Mall site. FreeBSD Services Ltd provide commercial support for FreeBSD in the UK (as well as selling FreeBSD on DVD). See their web site for more information. The FreeBSD Mall provides commercial FreeBSD support. You can get more information at their web site. Any other organizations providing training and support should contact the project in order to be listed here. Nik Clayton
nik@FreeBSD.org
 Installation Which file do I download to get FreeBSD? Prior to release 3.1, you only needed one floppy image to install FreeBSD, namely floppies/boot.flp. However, since release 3.1 the Project has added out-of-the-box support for a wide variety of hardware, which takes up more space. For 3.X and later you need two floppy images: floppies/kernel.flp and floppies/mfsroot.flp. These images need to be copied onto floppies by tools like fdimage or &man.dd.1;. If you need to download the distributions yourself (for a DOS filesystem install, for instance), below are some recommendations for distributions to grab: bin/ manpages/ compat*/ doc/ src/ssys.* Full instructions on this procedure and a little bit more about installation issues in general can be found in the Handbook entry on installing FreeBSD. What do I do if the floppy images does not fit on a single floppy? A 3.5 inch (1.44MB) floppy can accommodate 1474560 bytes of data. The boot image is exactly 1474560 bytes in size. Common mistakes when preparing the boot floppy are: Not downloading the floppy image in binary mode when using FTP. Some FTP clients default their transfer mode to ascii and attempt to change any end-of-line characters received to match the conventions used by the client's system. This will almost invariably corrupt the boot image. Check the size of the downloaded boot image: if it is not exactly that on the server, then the download process is suspect. To workaround: type binary at the FTP command prompt after getting connected to the server and before starting the download of the image. Using the DOS copy command (or equivalent GUI tool) to transfer the boot image to floppy. Programs like copy will not work as the boot image has been created to be booted into directly. The image has the complete content of the floppy, track for track, and is not meant to be placed on the floppy as a regular file. You have to transfer it to the floppy raw, using the low-level tools (e.g. fdimage or rawrite) described in the installation guide to FreeBSD. Where are the instructions for installing FreeBSD? Installation instructions can be found in the Handbook entry on installing FreeBSD. What do I need in order to run FreeBSD? You will need a 386 or better PC, with 5 MB or more of RAM and at least 60 MB of hard disk space. It can run with a low end MDA graphics card but to run X11R6, a VGA or better video card is needed. See also . I have only 4 MB of RAM. Can I install FreeBSD? FreeBSD 2.1.7 was the last version of FreeBSD that could be installed on a 4MB system. FreeBSD 2.2 and later needs at least 5MB to install on a new system. All versions of FreeBSD will run in 4MB of RAM, they just cannot run the installation program in 4MB. You can add extra memory for the install process, if you like, and then after the system is up and running, go back to 4MB. Or you could swap your disk into a system which has >4MB, install onto the disk and then swap it back. After the installation, if you build a custom kernel, it will run in 4 MB. Someone has even successfully booted with 2 MB, although the system was almost unusable. How can I make my own custom install floppy? Currently there is no way to just make a custom install floppy. You have to cut a whole new release, which will include your install floppy. To make a custom release, follow the instructions in the Release Engineering article. Can I have more than one operating system on my PC? Have a look at the multi-OS page. Can &windows; 95/98 co-exist with FreeBSD? Install &windows; 95/98 first, after that FreeBSD. FreeBSD's boot manager will then manage to boot Win95/98 and FreeBSD. If you install &windows; 95/98 second, it will boorishly overwrite your boot manager without even asking. If that happens, see the next section. &windows; 95/98 killed my boot manager! How do I get it back? You can reinstall the boot manager FreeBSD comes with in one of three ways: Running DOS, go into the tools/ directory of your FreeBSD distribution and look for bootinst.exe. You run it like so: ...\TOOLS> bootinst.exe boot.bin and the boot manager will be reinstalled. Boot the FreeBSD boot floppy again and go to the Custom installation menu item. Choose Partition. Select the drive which used to contain your boot manager (likely the first one) and when you come to the partition editor for it, as the very first thing (e.g. do not make any changes) select (W)rite. This will ask for confirmation, say yes, and when you get the Boot Manager selection prompt, be sure to select Boot Manager. This will re-write the boot manager to disk. Now quit out of the installation menu and reboot off the hard disk as normal. Boot the FreeBSD boot floppy (or CDROM) and choose the Fixit menu item. Select either the Fixit floppy or CDROM #2 (the live filesystem option) as appropriate and enter the fixit shell. Then execute the following command: Fixit# fdisk -B -b /boot/boot0 bootdevice substituting bootdevice for your real boot device such as ad0 (first IDE disk), ad4 (first IDE disk on auxiliary controller), da0 (first SCSI disk), etc. My A, T, or X series IBM Thinkpad locks up when I first booted up my FreeBSD installation. How can I solve this? A bug in early revisions of IBM's BIOS on these machines mistakenly identifies the FreeBSD partition as a potential FAT suspend-to-disk partition. When the BIOS tries to parse the FreeBSD partition it hangs. According to IBMIn an e-mail from Keith Frechette kfrechet@us.ibm.com., the following model/BIOS release numbers incorporate the fix. Model BIOS revision T20 IYET49WW or later T21 KZET22WW or later A20p IVET62WW or later A20m IWET54WW or later A21p KYET27WW or later A21m KXET24WW or later A21e KUET30WW It has been reported that later IBM BIOS revisions may have reintroduced the bug. This message from Jacques Vidrine to the &a.mobile; describes a procedure which may work if your newer IBM laptop does not boot FreeBSD properly, and you can upgrade or downgrade the BIOS. If you have an earlier BIOS, and upgrading is not an option a workaround is to install FreeBSD, change the partition ID FreeBSD uses, and install new boot blocks that can handle the different partition ID. First, you will need to restore the machine to a state where it can get through its self-test screen. Doing this requires powering up the machine without letting it find a FreeBSD partition on its primary disk. One way is to remove the hard disk and temporarily move it to an older ThinkPad (such as a ThinkPad 600) or a desktop PC with an appropriate conversion cable. Once it is there, you can delete the FreeBSD partition and move the hard disk back. The ThinkPad should now be in a bootable state again. With the machine functional again, you can use the workaround procedure described here to get a working FreeBSD installation. Download boot1 and boot2 from . Put these files somewhere you will be able to retrieve them later. Install FreeBSD as normal on to the ThinkPad. Do not use Dangerously Dedicated mode. Do not reboot when the install has finished. Either switch to the Emergency Holographic Shell (ALT F4) or start a fixit shell. Use &man.fdisk.8; to change the FreeBSD partition ID from 165 to 166 (this is the type used by OpenBSD). Bring the boot1 and boot2 files to the local filesystem. Use &man.disklabel.8; to write boot1 and boot2 to your FreeBSD slice. &prompt.root; disklabel -B -b boot1 -s boot2 ad0sn n is the number of the slice where you installed FreeBSD. Reboot. At the boot prompt you will be given the option of booting OpenBSD. This will actually boot FreeBSD. Getting this to work in the case where you want to dual boot OpenBSD and FreeBSD on the same laptop is left as an exercise for the reader. Can I install on a disk with bad blocks? Prior to 3.0, FreeBSD included a utility known as bad144, which automatically remapped bad blocks. Because modern IDE drives perform this function themselves, bad144 has been removed from the FreeBSD source tree. If you wish to install FreeBSD 3.0 or later, we strongly suggest you purchase a newer disk drive. If you do not wish to do this, you must run FreeBSD 2.X. If you are seeing bad block errors with a modern IDE drive, chances are the drive is going to die very soon (the drive's internal remapping functions are no longer sufficient to fix the bad blocks, which means the disk is heavily corrupted); we suggest you buy a new hard drive. If you have a SCSI drive with bad blocks, see this answer. I have just upgraded from 3.X to 4.X, and my first boot failed with bad sector table not supported FreeBSD 3.X and earlier supported bad144, which automatically remapped bad blocks. FreeBSD 4.X and later do not support this, as modern IDE drives include this functionality. See this question for more information. To fix this after an upgrade, you need to physically place the drive in a working system and use &man.disklabel.8; as discussed in the following questions. How do I tell if a drive has bad144 information on it before I try to upgrade to FreeBSD 4.0 and it fails? Use &man.disklabel.8; for this. disklabel -r drive device will give you the contents of your disk label. Look for a flags field. If you see flags: badsect, this drive is using bad144. For example, the following drive has bad144 enabled.: &prompt.root; disklabel -r wd0 # /dev/rwd0c: type: ESDI disk: wd0s1 label: flags: badsect bytes/sector: 512 sectors/track: 63 How do I remove bad144 from my pre-4.X system so I can upgrade safely? Use disklabel -e -rwd0 to edit the disklabel in place. Just remove the word badsect from the flags field, save, and exit. The bad144 file will still take up some space on your drive, but the disk itself will be usable. We still recommend you purchase a new disk if you have a large number of bad blocks. Strange things happen when I boot the install floppy! What is happening? If you are seeing things like the machine grinding to a halt or spontaneously rebooting when you try to boot the install floppy, here are three questions to ask yourself:- Did you use a new, freshly-formatted, error-free floppy (preferably a brand-new one straight out of the box, as opposed to the magazine cover disk that has been lying under the bed for the last three years)? Did you download the floppy image in binary (or image) mode? (do not be embarrassed, even the best of us have accidentally downloaded a binary file in ASCII mode at least once!) If you are using &windows; 95 or 98 did you run fdimage or rawrite in pure DOS mode? These operating systems can interfere with programs that write directly to hardware, which the disk creation program does; even running it inside a DOS shell in the GUI can cause this problem. There have also been reports of &netscape; causing problems when downloading the boot floppy, so it is probably best to use a different FTP client if you can. I booted from my ATAPI CDROM, but the install program says no CDROM is found. Where did it go? The usual cause of this problem is a mis-configured CDROM drive. Many PCs now ship with the CDROM as the slave device on the secondary IDE controller, with no master device on that controller. This is illegal according to the ATAPI specification, but &windows; plays fast and loose with the specification, and the BIOS ignores it when booting. This is why the BIOS was able to see the CDROM to boot from it, but why FreeBSD cannot see it to complete the install. Reconfigure your system so that the CDROM is either the master device on the IDE controller it is attached to, or make sure that it is the slave on an IDE controller that also has a master device. Can I install on my laptop over PLIP (Parallel Line IP)? Yes. Use a standard Laplink cable. If necessary, you can check out the PLIP section of the Handbook for details on parallel port networking. If you are running FreeBSD 3.X or earlier, also look at the Mobile Computing page. Which geometry should I use for a disk drive? By the geometry of a disk, we mean the number of cylinders, heads and sectors/track on a disk. We will refer to this as C/H/S for convenience. This is how the PC's BIOS works out which area on a disk to read/write from. This causes a lot of confusion among new system administrators. First of all, the physical geometry of a SCSI drive is totally irrelevant, as FreeBSD works in term of disk blocks. In fact, there is no such thing as the physical geometry, as the sector density varies across the disk. What manufacturers claim is the physical geometry is usually the geometry that they have determined wastes the least space. For IDE disks, FreeBSD does work in terms of C/H/S, but all modern drives internally convert this into block references. All that matters is the logical geometry. This is the answer that the BIOS gets when it asks the drive what is your geometry? It then uses this geometry to access the disk. As FreeBSD uses the BIOS when booting, it is very important to get this right. In particular, if you have more than one operating system on a disk, they must all agree on the geometry. Otherwise you will have serious problems booting! For SCSI disks, the geometry to use depends on whether extended translation support is turned on in your controller (this is often referred to as support for DOS disks >1GB or something similar). If it is turned off, then use N cylinders, 64 heads and 32 sectors/track, where N is the capacity of the disk in MB. For example, a 2GB disk should pretend to have 2048 cylinders, 64 heads and 32 sectors/track. If it is turned on (it is often supplied this way to get around certain limitations in &ms-dos;) and the disk capacity is more than 1GB, use M cylinders, 63 sectors per track (not 64), and 255 heads, where 'M' is the disk capacity in MB divided by 7.844238 (!). So our example 2GB drive would have 261 cylinders, 63 sectors per track and 255 heads. If you are not sure about this, or FreeBSD fails to detect the geometry correctly during installation, the simplest way around this is usually to create a small DOS partition on the disk. The BIOS should then detect the correct geometry, and you can always remove the DOS partition in the partition editor if you do not want to keep it. You might want to leave it around for programming network cards and the like, however. Alternatively, there is a freely available utility distributed with FreeBSD called pfdisk.exe. You can find it in the tools subdirectory on the FreeBSD CDROM or on the various FreeBSD FTP sites. This program can be used to work out what geometry the other operating systems on the disk are using. You can then enter this geometry in the partition editor. Are there any restrictions on how I divide the disk up? Yes. You must make sure that your root partition is below 1024 cylinders so the BIOS can boot the kernel from it. (Note that this is a limitation in the PC's BIOS, not FreeBSD). For a SCSI drive, this will normally imply that the root partition will be in the first 1024MB (or in the first 4096MB if extended translation is turned on - see previous question). For IDE, the corresponding figure is 504MB. Is FreeBSD compatible with any disk managers? FreeBSD recognizes the Ontrack Disk Manager and makes allowances for it. Other disk managers are not supported. If you just want to use the disk with FreeBSD you do not need a disk manager. Just configure the disk for as much space as the BIOS can deal with (usually 504 megabytes), and FreeBSD should figure out how much space you really have. If you are using an old disk with an MFM controller, you may need to explicitly tell FreeBSD how many cylinders to use. If you want to use the disk with FreeBSD and another operating system, you may be able to do without a disk manager: just make sure the FreeBSD boot partition and the slice for the other operating system are in the first 1024 cylinders. If you are reasonably careful, a 20 megabyte boot partition should be plenty. When I boot FreeBSD I get Missing Operating System. What is happening? This is classically a case of FreeBSD and DOS or some other OS conflicting over their ideas of disk geometry. You will have to reinstall FreeBSD, but obeying the instructions given above will almost always get you going. Why can I not get past the boot manager's F? prompt? This is another symptom of the problem described in the preceding question. Your BIOS geometry and FreeBSD geometry settings do not agree! If your controller or BIOS supports cylinder translation (often marked as >1GB drive support), try toggling its setting and reinstalling FreeBSD. Do I need to install the complete sources? In general, no. However, we would strongly recommend that you install, at a minimum, the base source kit, which includes several of the files mentioned here, and the sys (kernel) source kit, which includes sources for the kernel. There is nothing in the system which requires the presence of the sources to operate, however, except for the kernel-configuration program &man.config.8;. With the exception of the kernel sources, our build structure is set up so that you can read-only mount the sources from elsewhere via NFS and still be able to make new binaries (due to the kernel-source restriction, we recommend that you not mount this on /usr/src directly, but rather in some other location with appropriate symbolic links to duplicate the top-level structure of the source tree). Having the sources on-line and knowing how to build a system with them will make it much easier for you to upgrade to future releases of FreeBSD. To actually select a subset of the sources, use the Custom menu item when you are in the Distributions menu of the system installation tool. Do I need to build a kernel? Building a new kernel was originally pretty much a required step in a FreeBSD installation, but more recent releases have benefited from the introduction of a much friendlier kernel configuration tool. When at the FreeBSD boot prompt (boot:), use the flag and you will be dropped into a visual configuration screen which allows you to configure the kernel's settings for most common ISA cards. It is still recommended that you eventually build a new kernel containing just the drivers that you need, just to save a bit of RAM, but it is no longer a strict requirement for most systems. Should I use DES, Blowfish, or MD5 passwords and how do I specify which form my users receive? The default password format on FreeBSD is to use MD5-based passwords. These are believed to be more secure than the traditional &unix; password format, which used a scheme based on the DES algorithm. DES passwords are still available if you need to share your password file with legacy operating systems which still use the less secure password format (they are available if you choose to install the crypto distribution in sysinstall, or by installing the crypto sources if building from source). Installing the crypto libraries will also allow you to use the Blowfish password format, which is more secure. Which password format to use for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of des, blf (if these are available) or md5. See the &man.login.conf.5; manual page for more information about login capabilities. Why does the boot floppy start, but hang at the Probing Devices... screen? If you have a IDE &iomegazip; or &jaz; drive installed, remove it and try again. The boot floppy can get confused by the drives. After the system is installed you can reconnect the drive. Hopefully this will be fixed in a later release. Why do I get a panic: can't mount root error when rebooting the system after installation? This error comes from confusion between the boot block's and the kernel's understanding of the disk devices. The error usually manifests on two-disk IDE systems, with the hard disks arranged as the master or single device on separate IDE controllers, with FreeBSD installed on the secondary IDE controller. The boot blocks think the system is installed on wd1 (the second BIOS disk) while the kernel assigns the first disk on the secondary controller device wd2. After the device probing, the kernel tries to mount what the boot blocks think is the boot disk, wd1, while it is really wd2, and fails. To fix the problem, do one of the following: For FreeBSD 3.3 and later, reboot the system and hit Enter at the Booting kernel in 10 seconds; hit [Enter] to interrupt prompt. This will drop you into the boot loader. Then type set root_disk_unit="disk_number" . disk_number will be 0 if FreeBSD is installed on the master drive on the first IDE controller, 1 if it is installed on the slave on the first IDE controller, 2 if it is installed on the master of the second IDE controller, and 3 if it is installed on the slave of the second IDE controller. Then type boot, and your system should boot correctly. To make this change permanent (ie so you do not have to do this every time you reboot or turn on your FreeBSD machine), put the line root_disk_unit="disk_number" in /boot/loader.conf.local . If using FreeBSD 3.2 or earlier, at the Boot: prompt, enter 1:wd(2,a)kernel and press Enter. If the system starts, then run the command echo "1:wd(2,a)kernel" > /boot.config to make it the default boot string. Move the FreeBSD disk onto the primary IDE controller, so the hard disks are consecutive. Rebuild your kernel, modify the wd configuration lines to read: controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr disk wd0 at wdc0 drive 0 # disk wd1 at wdc0 drive 1 # comment out this line controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr disk wd1 at wdc1 drive 0 # change from wd2 to wd1 disk wd2 at wdc1 drive 1 # change from wd3 to wd2 Install the new kernel. If you moved your disks and wish to restore the previous configuration, replace the disks in the desired configuration and reboot. Your system should boot successfully. What are the limits for memory? For memory, the limit is 4 gigabytes. If you plan to install this much memory into a machine, you need to be careful. You will probably want to use ECC memory and to reduce capacitive loading use 9 chip memory modules versus 18 chip memory modules. What are the limits for ffs filesystems? For ffs filesystems, the maximum theoretical limit is 8 terabytes (2G blocks), or 16TB for the default block size of 8K. In practice, there is a soft limit of 1 terabyte, but with modifications filesystems with 4 terabytes are possible (and exist). The maximum size of a single ffs file is approximately 1G blocks, or 4TB with a block size of 4K. Maximum file sizes fs block size 2.2.7-stable 3.0-current works should work 4K 4T-1 4T-1 4T-1 >4T 8K >32G 8T-1 >32G 32T-1 16K >128G 16T-1 >128G 32T-1 32K >512G 32T-1 >512G 64T-1 64K >2048G 64T-1 >2048G 128T-1
When the fs block size is 4K, triple indirect blocks work and everything should be limited by the maximum fs block number that can be represented using triple indirect blocks (approx. 1K^3 + 1K^2 + 1K), but everything is limited by a (wrong) limit of 1G-1 on fs block numbers. The limit on fs block numbers should be 2G-1. There are some bugs for fs block numbers near 2G-1, but such block numbers are unreachable when the fs block size is 4K. For block sizes of 8K and larger, everything should be limited by the 2G-1 limit on fs block numbers, but is actually limited by the 1G-1 limit on fs block numbers, except under -STABLE triple indirect blocks are unreachable, so the limit is the maximum fs block number that can be represented using double indirect blocks (approx. (blocksize/4)^2 + (blocksize/4)), and under -CURRENT exceeding this limit may cause problems. Using the correct limit of 2G-1 blocks does cause problems. Why do I get an error message, archsw.readin.failed after compiling and booting a new kernel? You can boot by specifying the kernel directly at the second stage, pressing any key when the | shows up before loader is started. More specifically, you have upgraded the source for your kernel, and installed a new kernel builtin from them without making world. This is not supported. Make world. What are these security profiles? A security profile is a set of configuration options that attempts to achieve the desired ratio of security to convenience by enabling and disabling certain programs and other settings. For full details, see the Security Profile section of the Handbook's post-install chapter. Hardware compatibility General I want to get a piece of hardware for my FreeBSD system. Which model/brand/type is best? This is discussed continually on the FreeBSD mailing lists. Since hardware changes so quickly, however, we expect this. We still strongly recommend that you read through the Hardware notes for &os; &rel.current; or &rel2.current; and search the mailing list archives before asking about the latest and greatest hardware. Chances are a discussion about the type of hardware you are looking for took place just last week. If you are looking for a laptop, check the FreeBSD-mobile mailing list archives. Otherwise, you probably want the archives for FreeBSD-questions, or possibly a specific mailing list for a particular hardware type. Architectures and processors Does FreeBSD support architectures other than the x86? Yes. FreeBSD currently runs on the Intel x86 and DEC (now Compaq) Alpha architectures. As of FreeBSD 5.0, the IA-64, AMD-64 and &sparc64; architectures are also supported. Upcoming platforms are &mips; and &powerpc;, join the &a.ppc; or the &a.mips; respectively for more information about ongoing work on these platforms. For general discussion on new architectures, join the &a.platforms;. If your machine has a different architecture and you need something right now, we suggest you look at NetBSD or OpenBSD. Does FreeBSD support Symmetric Multiprocessing (SMP)? Yes. SMP is not enabled in the GENERIC kernel, so you must recompile your kernel to enable SMP. Take a look at /sys/i386/conf/LINT to learn what options to put in your kernel config file. I do not have a math co-processor - is that bad? This will only affect 386/486SX/486SLC owners - other machines will have one built into the CPU. In general this will not cause any problems, but there are circumstances where you will take a hit, either in performance or accuracy of the math emulation code (see the section on FP emulation). In particular, drawing arcs in X will be VERY slow. It is highly recommended that you buy a math co-processor; it is well worth it. Some math co-processors are better than others. It pains us to say it, but nobody ever got fired for buying Intel. Unless you are sure it works with FreeBSD, beware of clones. Hard drives, tape drives, and CD and DVD drives What kind of hard drives does FreeBSD support? FreeBSD supports EIDE and SCSI drives (with a compatible controller; see the next section), and all drives using the original Western Digital interface (MFM, RLL, ESDI, and of course IDE). A few ESDI controllers that use proprietary interfaces may not work: stick to WD1002/3/6/7 interfaces and clones. Which SCSI controllers are supported? See the complete list in the Hardware Notes for &os; &rel.current; or &rel2.current;. What types of tape drives are supported? FreeBSD supports SCSI and QIC-36 (with a QIC-02 interface). This includes 8-mm (aka Exabyte) and DAT drives. Some of the early 8-mm drives are not quite compatible with SCSI-2, and may not work well with FreeBSD. Does FreeBSD support tape changers? FreeBSD supports SCSI changers using the &man.ch.4; device and the &man.chio.1; command. The details of how you actually control the changer can be found in the &man.chio.1; manual page. If you are not using AMANDA or some other product that already understands changers, remember that they only know how to move a tape from one point to another, so you need to keep track of which slot a tape is in, and which slot the tape currently in the drive needs to go back to. Which CDROM drives are supported by FreeBSD? Any SCSI drive connected to a supported controller is supported. The following proprietary CDROM interfaces are also supported: Mitsumi LU002 (8bit), LU005 (16bit) and FX001D (16bit 2x Speed). Sony CDU 31/33A Sound Blaster Non-SCSI CDROM Matsushita/Panasonic CDROM ATAPI compatible IDE CDROMs All non-SCSI cards are known to be extremely slow compared to SCSI drives, and some ATAPI CDROMs may not work. The official FreeBSD CDROM ISO, and CDROMs from Daemon News and FreeBSD Mall, support booting directly from the CD. Which CD-RW drives are supported by FreeBSD? FreeBSD supports any ATAPI-compatible IDE CD-R or CD-RW drive. For FreeBSD versions 4.0 and later, see the manual page for &man.burncd.8;. For earlier FreeBSD versions, see the examples in /usr/share/examples/atapi. FreeBSD also supports any SCSI CD-R or CD-RW drives. Install and use the cdrecord command from the ports or packages system, and make sure that you have the pass device compiled in your kernel. Does FreeBSD support &iomegazip; drives? FreeBSD supports SCSI and ATAPI (IDE) &iomegazip; drives out of the box, of course. SCSI ZIP drives can only be set to run at SCSI target IDs 5 or 6, but if your SCSI host adapter's BIOS supports it you can even boot from it. It is not clear which host adapters support booting from targets other than 0 or 1, so you will have to consult your adapter's documentation if you would like to use this feature. FreeBSD also supports Parallel Port Zip Drives. Check that your kernel contains the scbus0, da0, ppbus0, and vp0 drivers (the GENERIC kernel contains everything except vp0). With all these drivers present, the Parallel Port drive should be available as /dev/da0s4. Disks can be mounted using mount /dev/da0s4 /mnt OR (for dos disks) mount_msdos /dev/da0s4 /mnt as appropriate. Also check out the FAQ on removable drives later in this chapter, and the note on formattingin the Administration chapter. Does FreeBSD support &jaz;, EZ and other removable drives? Apart from the IDE version of the EZ drive, these are all SCSI devices, so they should all look like SCSI disks to FreeBSD, and the IDE EZ should look like an IDE drive. I am not sure how well FreeBSD supports changing the media out while running. You will of course need to dismount the drive before swapping media, and make sure that any external units are powered on when you boot the system so FreeBSD can see them. See this note on formatting. Keyboards and mice Does FreeBSD support my USB keyboard? FreeBSD 4.X and later supports USB keyboards out-of-the-box. Preliminary USB device support appeared in FreeBSD 3.1, but might not always work as of version 3.2. If you want to experiment with the USB keyboard support in FreeBSD 3.X, follow the procedure described below. Use a version of FreeBSD 3.X later than 3.2. Add the following lines to your kernel configuration file, and rebuild the kernel. controller uhci0 controller ohci0 controller usb0 controller ukbd0 options KBD_INSTALL_CDEV Go to the /dev directory and create device nodes as follows: &prompt.root; cd /dev &prompt.root; ./MAKEDEV kbd0 kbd1 Edit /etc/rc.conf and add the following lines: usbd_enable="YES" usbd_flags="" If you want to use a USB keyboard in FreeBSD 4.X or later, you just need to enable USB support in /etc/rc.conf. Once you have USB keyboard support enabled on your system, the AT keyboard becomes /dev/kbd0 and the USB keyboard becomes /dev/kbd1, if both are connected to the system. If there is the USB keyboard only, it will be /dev/ukbd0. If you want to use the USB keyboard in the console, you have to explicitly tell the console driver to use the existing USB keyboard. This can be done by running the following command as a part of system initialization. &prompt.root; kbdcontrol -k /dev/kbd1 < /dev/ttyv0 > /dev/null Note that if the USB keyboard is the only keyboard, it is accessed as /dev/kbd0, thus, the command should look like: &prompt.root; kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null /etc/rc.i386 is a good place to add the above command. Once this is done, the USB keyboard should work in the X environment as well without any special settings. Hot-plugging and unplugging of the USB keyboard may not work quite right yet. We recommend connecting the keyboard before starting the system and leaving it connected until the system is shutdown to avoid troubles. See the &man.ukbd.4; manual page for more information. I have an unusual bus mouse. How do I set it up? FreeBSD supports the bus mouse and the InPort bus mouse from such manufactures as Microsoft, Logitech and ATI. The bus device driver is compiled in the GENERIC kernel by default in FreeBSD versions 2.X, but not included in version 3.0 or later. If you are building a custom kernel with the bus mouse driver, make sure to add the following line to the kernel config file In FreeBSD 3.0 or before, add: device mse0 at isa? port 0x23c tty irq5 vector mseintr In FreeBSD 3.X, the line should be: device mse0 at isa? port 0x23c tty irq5 And in FreeBSD 4.X and later, the line should read: device mse0 at isa? port 0x23c irq5 Bus mice usually comes with dedicated interface cards. These cards may allow you to set the port address and the IRQ number other than shown above. Refer to the manual of your mouse and the &man.mse.4; manual page for more information. How do I use my PS/2 (mouse port or keyboard) mouse? The PS/2 mouse is supported out-of-the-box in all recent versions of FreeBSD. The necessary device driver, psm, is included in the GENERIC kernel. If your custom kernel does not have this, add the appropriate following line to your kernel configuration file and compile a new kernel. In FreeBSD 3.0 or earlier, the line should be: device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr In FreeBSD 3.1 or later, the line should be: device psm0 at isa? tty irq 12 In FreeBSD 4.0 or later, the line should be: device psm0 at atkbdc? irq 12 Once the kernel detects psm0 correctly at boot time, make sure that an entry for psm0 exists in /dev. You can do this by typing: &prompt.root; cd /dev; sh MAKEDEV psm0 when logged in as root. You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled, since the proper device nodes will be created automatically under /dev. Is it possible to use a mouse in any way outside the X Window system? If you are using the default console driver, &man.syscons.4;, you can use a mouse pointer in text consoles to cut & paste text. Run the mouse daemon, &man.moused.8;, and turn on the mouse pointer in the virtual console: &prompt.root; moused -p /dev/xxxx -t yyyy &prompt.root; vidcontrol -m on Where xxxx is the mouse device name and yyyy is a protocol type for the mouse. The mouse daemon can automatically determine the protocol type of most mice, except old serial mice. Specify the auto protocol to invoke automatic detection. If automatic detection does not work, see the &man.moused.8; manual page for a list of supported protocol types. If you have a PS/2 mouse, just add moused_enable="YES" to /etc/rc.conf to start the mouse daemon at boot-time. Additionally, if you would like to use the mouse daemon on all virtual terminals instead of just the console, add allscreens_flags="-m on" to /etc/rc.conf. When the mouse daemon is running, access to the mouse must be coordinated between the mouse daemon and other programs such as X Windows. Refer to the FAQ Why does my mouse not work with X? for more details on this issue. How do I cut and paste text with a mouse in the text console? Once you get the mouse daemon running (see the previous section), hold down the button 1 (left button) and move the mouse to select a region of text. Then, press the button 2 (middle button) to paste it at the text cursor. Pressing button 3 (right button) will extend the selected region of text. If your mouse does not have a middle button, you may wish to emulate one or remap buttons using mouse daemon options. See the &man.moused.8; manual page for details. Does FreeBSD support any USB mice? Preliminary USB device support was added to FreeBSD 3.1. It did not always work through early versions of 3.X. As of FreeBSD 4.0, USB devices should work out of the box. If you want to experiment with the USB mouse support under FreeBSD 3.X, follow the procedure described below. Use FreeBSD 3.2 or later. Add the following lines to your kernel configuration file, and rebuild the kernel. device uhci device ohci device usb device ums In versions of FreeBSD before 4.0, use this instead: controller uhci0 controller ohci0 controller usb0 device ums0 Go to the /dev directory and create a device node as follows: &prompt.root; cd /dev &prompt.root; ./MAKEDEV ums0 You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled, since the proper device nodes will be created automatically under /dev. Edit /etc/rc.conf and add the following lines: moused_enable="YES" moused_type="auto" moused_port="/dev/ums0" moused_flags="" usbd_enable="YES" usbd_flags="" See the previous section for more detailed discussion on moused. In order to use the USB mouse in the X session, edit XF86Config. If you are using &xfree86; 3.3.2 or later, be sure to have the following lines in the Pointer section: Device "/dev/sysmouse" Protocol "Auto" If you are using earlier versions of &xfree86;, be sure to have the following lines in the Pointer section: Device "/dev/sysmouse" Protocol "SysMouse" Refer to another section on the mouse support in the X environment. Hot-plugging and unplugging of the USB mouse may not work quite right yet. It is a good idea connect the mouse before you start the system and leave it connected until the system is shutdown to avoid trouble. My mouse has a fancy wheel and buttons. Can I use them in FreeBSD? The answer is, unfortunately, It depends. These mice with additional features require specialized driver in most cases. Unless the mouse device driver or the user program has specific support for the mouse, it will act just like a standard two, or three button mouse. For the possible usage of wheels in the X Window environment, refer to that section. How do I use the mouse/trackball/touchpad on my laptop? Please refer to the answer to the previous question. Also check out the Mobile Computing page. Networking and serial devices Which network cards does FreeBSD support? See the Hardware Notes supplied with each release of FreeBSD for a more complete list. Why is FreeBSD not finding my internal Plug & Play modem? You will need to add the modem's PnP ID to the PnP ID list in the serial driver. To enable Plug & Play support, compile a new kernel with controller pnp0 in the configuration file, then reboot the system. The kernel will print the PnP IDs of all the devices it finds. Copy the PnP ID from the modem to the table in /sys/i386/isa/sio.c, at about line 2777. Look for the string SUP1310 in the structure siopnp_ids[] to find the table. Build the kernel again, install, reboot, and your modem should be found. You may have to manually configure the PnP devices using the pnp command in the boot-time configuration with a command like pnp 1 0 enable os irq0 3 drq0 0 port0 0x2f8 to make the modem show. Does FreeBSD support software modems, such as Winmodems? FreeBSD supports many software modems via add-on software. The comms/ltmdm port adds support for modems based on the very popular Lucent LT chipset. The comms/mwavem port supports the modem in IBM Thinkpad 600 and 700 laptops. You cannot install FreeBSD via a software modem; this software must be installed after the OS is installed. Is there a native driver for the Broadcom 43xx cards? No, and there is not likely to be. Broadcom refuses to publically release programming information for their wireless chipsets, most likely because they use software controlled radios. In order to get FCC type acceptance for their parts, they have to ensure that users cannot arbitrarily set things like operating frequencies, modulation parameters and power output. But without knowing how to program the chipsets, it is nearly impossible to write a driver. Which multi-port serial cards are supported by FreeBSD? There is a list of these in the Miscellaneous devices section of the handbook. Some unnamed clone cards have also been known to work, especially those that claim to be AST compatible. Check the &man.sio.4; manual page to get more information on configuring such cards. How do I get the boot: prompt to show on the serial console? Build a kernel with options COMCONSOLE. Create /boot.config and place as the only text in the file. Unplug the keyboard from the system. See /usr/src/sys/i386/boot/biosboot/README.serial for information. Sound devices Which sound cards are supported by FreeBSD? FreeBSD supports the &soundblaster;, &soundblaster; Pro, &soundblaster; 16, Pro Audio Spectrum 16, AdLib and Gravis UltraSound sound cards. There is also limited support for MPU-401 and compatible MIDI cards. Cards conforming to the µsoft; Sound System specification are also supported through the pcm driver. This is only for sound! This driver does not support CDROMs, SCSI or joysticks on these cards, except for the &soundblaster;. The &soundblaster; SCSI interface and some non-SCSI CDROMs are supported, but you cannot boot off this device. Workarounds for no sound from es1370 with pcm driver? You can run the following command every time the machine booted up: &prompt.root; mixer pcm 100 vol 100 cd 100 Other hardware What other devices does FreeBSD support? See the Handbook for the list of other devices supported. Does FreeBSD support power management on my laptop? FreeBSD supports APM on certain machines. Please look in the LINT kernel config file, searching for the APM keyword. Further information can be found in &man.apm.4;. Why does my Micron system hang at boot time? Certain Micron motherboards have a non-conforming PCI BIOS implementation that causes grief when FreeBSD boots because PCI devices do not get configured at their reported addresses. Disable the Plug and Play Operating System flag in the BIOS to work around this problem. More information can be found at http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron The boot floppy hangs on a system with an ASUS K7V motherboard. How do I fix this? Go into the BIOS setup and disable the boot virus protection. Why does my &tm.3com; PCI network card not work with my Micron computer? Certain Micron motherboards have a non-conforming PCI BIOS implementation that does not configure PCI devices at the addresses reported. This causes grief when FreeBSD boots. To work around this problem, disable the Plug and Play Operating System flag in the BIOS. More information on this problem is available at URL: Troubleshooting What do I do when I have bad blocks on my hard drive? With SCSI drives, the drive should be capable of re-mapping these automatically. However, many drives are shipped with this feature disabled, for some mysterious reason... To enable this, you will need to edit the first device page mode, which can be done on FreeBSD by giving the command (as root) &prompt.root; camcontrol modepage sd0 -m 1 -e -P 3 and changing the values of AWRE and ARRE from 0 to 1:- AWRE (Auto Write Reallocation Enbld): 1 ARRE (Auto Read Reallocation Enbld): 1 The following paragraphs were submitted by Ted Mittelstaedt tedm@toybox.placo.com: For IDE drives, any bad block is usually a sign of potential trouble. All modern IDE drives come with internal bad-block remapping turned on. All IDE hard drive manufacturers today offer extensive warranties and will replace drives with bad blocks on them. If you still want to attempt to rescue an IDE drive with bad blocks, you can attempt to download the IDE drive manufacturer's IDE diagnostic program, and run this against the drive. Sometimes these programs can be set to force the drive electronics to rescan the drive for bad blocks and lock them out. For ESDI, RLL and MFM drives, bad blocks are a normal part of the drive and are no sign of trouble, generally. With a PC, the disk drive controller card and BIOS handle the task of locking out bad sectors. This is fine for operating systems like DOS that use BIOS code to access the disk. However, FreeBSD's disk driver does not go through BIOS, therefore a mechanism, bad144, exists that replaces this functionality. bad144 only works with the wd driver (which means it is not supported in FreeBSD 4.0), it is NOT able to be used with SCSI. bad144 works by entering all bad sectors found into a special file. One caveat with bad144 - the bad block special file is placed on the last track of the disk. As this file may possibly contain a listing for a bad sector that would occur near the beginning of the disk, where the /kernel file might be located, it therefore must be accessible to the bootstrap program that uses BIOS calls to read the kernel file. This means that the disk with bad144 used on it must not exceed 1024 cylinders, 16 heads, and 63 sectors. This places an effective limit of 500MB on a disk that is mapped with bad144. To use bad144, simply set the Bad Block scanning to ON in the FreeBSD fdisk screen during the initial install. This works up through FreeBSD 2.2.7. The disk must have less than 1024 cylinders. It is generally recommended that the disk drive has been in operation for at least 4 hours prior to this to allow for thermal expansion and track wandering. If the disk has more than 1024 cylinders (such as a large ESDI drive) the ESDI controller uses a special translation mode to make it work under DOS. The wd driver understands about these translation modes, IF you enter the translated geometry with the set geometry command in fdisk. You must also NOT use the dangerously dedicated mode of creating the FreeBSD partition, as this ignores the geometry. Also, even though fdisk will use your overridden geometry, it still knows the true size of the disk, and will attempt to create a too large FreeBSD partition. If the disk geometry is changed to the translated geometry, the partition MUST be manually created with the number of blocks. A quick trick to use is to set up the large ESDI disk with the ESDI controller, boot it with a DOS disk and format it with a DOS partition. Then, boot the FreeBSD install and in the fdisk screen, read off and write down the blocksize and block numbers for the DOS partition. Then, reset the geometry to the same that DOS uses, delete the DOS partition, and create a cooperative FreeBSD partition using the blocksize you recorded earlier. Then, set the partition bootable and turn on bad block scanning. During the actual install, bad144 will run first, before any filesystems are created (you can view this with an AltF2). If it has any trouble creating the badsector file, you have set too large a disk geometry - reboot the system and start all over again (including repartitioning and reformatting with DOS). If remapping is enabled and you are seeing bad blocks, consider replacing the drive. The bad blocks will only get worse as time goes on. Why does FreeBSD not recognize my Bustek 742a EISA SCSI controller? This info is specific to the 742a but may also cover other Buslogic cards. (Bustek = Buslogic) There are 2 general versions of the 742a card. They are hardware revisions A-G, and revisions H - onwards. The revision letter is located after the Assembly number on the edge of the card. The 742a has 2 ROM chips on it, one is the BIOS chip and the other is the Firmware chip. FreeBSD does not care what version of BIOS chip you have but it does care about what version of firmware chip. Buslogic will send upgrade ROMs out if you call their tech support dept. The BIOS and Firmware chips are shipped as a matched pair. You must have the most current Firmware ROM in your adapter card for your hardware revision. The REV A-G cards can only accept BIOS/Firmware sets up to 2.41/2.21. The REV H- up cards can accept the most current BIOS/Firmware sets of 4.70/3.37. The difference between the firmware sets is that the 3.37 firmware supports round robin. The Buslogic cards also have a serial number on them. If you have an old hardware revision card you can call the Buslogic RMA department and give them the serial number and attempt to exchange the card for a newer hardware revision. If the card is young enough they will do so. FreeBSD 2.1 only supports Firmware revisions 2.21 onward. If you have a Firmware revision older than this your card will not be recognized as a Buslogic card. It may be recognized as an &adaptec; 1540, however. The early Buslogic firmware contains an AHA1540 emulation mode. This is not a good thing for an EISA card, however. If you have an old hardware revision card and you obtain the 2.21 firmware for it, you will need to check the position of jumper W1 to B-C, the default is A-B. Why does FreeBSD not detect my HP Netserver's SCSI controller? This is basically a known problem. The EISA on-board SCSI controller in the HP Netserver machines occupies EISA slot number 11, so all the true EISA slots are in front of it. Alas, the address space for EISA slots >= 10 collides with the address space assigned to PCI, and FreeBSD's auto-configuration currently cannot handle this situation very well. So now, the best you can do is to pretend there is no address range clash :), by bumping the kernel option EISA_SLOTS to a value of 12. Configure and compile a kernel, as described in the Handbook entry on configuring the kernel. Of course, this does present you with a chicken-and-egg problem when installing on such a machine. In order to work around this problem, a special hack is available inside UserConfig. Do not use the visual interface, but the plain command-line interface there. Simply type eisa 12 quit at the prompt, and install your system as usual. While it is recommended you compile and install a custom kernel anyway. Hopefully, future versions will have a proper fix for this problem. You cannot use a dangerously dedicated disk with an HP Netserver. See this note for more info. I keep seeing messages like ed1: timeout. What do these messages mean? This is usually caused by an interrupt conflict (e.g., two boards using the same IRQ). FreeBSD prior to 2.0.5R used to be tolerant of this, and the network driver would still function in the presence of IRQ conflicts. However, with 2.0.5R and later, IRQ conflicts are no longer tolerated. Boot with the -c option and change the ed0/de0/... entry to match your board. If you are using the BNC connector on your network card, you may also see device timeouts because of bad termination. To check this, attach a terminator directly to the NIC (with no cable) and see if the error messages go away. Some NE2000 compatible cards will give this error if there is no link on the UTP port or if the cable is disconnected. Why did my &tm.3com; 3C509 card stop working for no apparent reason? This card has a bad habit of losing its configuration information. Refresh your card's settings with the DOS utility 3c5x9.exe. My parallel printer is ridiculously slow. What can I do? If the only problem is that the printer is terribly slow, try changing your printer port mode as discussed in the Printer Setup section of the Handbook. Why do my programs occasionally die with Signal 11 errors? Signal 11 errors are caused when your process has attempted to access memory which the operating system has not granted it access to. If something like this is happening at seemingly random intervals then you need to start investigating things very carefully. These problems can usually be attributed to either: If the problem is occurring only in a specific application that you are developing yourself it is probably a bug in your code. If it is a problem with part of the base FreeBSD system, it may also be buggy code, but more often than not these problems are found and fixed long before us general FAQ readers get to use these bits of code (that is what -current is for). In particular, a dead giveaway that this is not a FreeBSD bug is if you see the problem when you are compiling a program, but the activity that the compiler is carrying out changes each time. For example, suppose you are running make buildworld, and the compile fails while trying to compile ls.c into ls.o. If you then run make buildworld again, and the compile fails in the same place then this is a broken build -- try updating your sources and try again. If the compile fails elsewhere then this is almost certainly hardware. What you should do: In the first case you can use a debugger e.g. gdb to find the point in the program which is attempting to access a bogus address and then fix it. In the second case you need to verify that it is not your hardware at fault. Common causes of this include: Your hard disks might be overheating: Check the fans in your case are still working, as your disk (and perhaps other hardware might be overheating). The processor running is overheating: This might be because the processor has been overclocked, or the fan on the processor might have died. In either case you need to ensure that you have hardware running at what it is specified to run at, at least while trying to solve this problem. i.e. Clock it back to the default settings. If you are overclocking then note that it is far cheaper to have a slow system than a fried system that needs replacing! Also the wider community is not often sympathetic to problems on overclocked systems, whether you believe it is safe or not. Dodgy memory: If you have multiple memory SIMMS/DIMMS installed then pull them all out and try running the machine with each SIMM or DIMM individually and narrow the problem down to either the problematic DIMM/SIMM or perhaps even a combination. Over-optimistic Motherboard settings: In your BIOS settings, and some motherboard jumpers you have options to set various timings, mostly the defaults will be sufficient, but sometimes, setting the wait states on RAM too low, or setting the RAM Speed: Turbo option, or similar in the BIOS will cause strange behavior. A possible idea is to set to BIOS defaults, but it might be worth noting down your settings first! Unclean or insufficient power to the motherboard. If you have any unused I/O boards, hard disks, or CDROMs in your system, try temporarily removing them or disconnecting the power cable from them, to see if your power supply can manage a smaller load. Or try another power supply, preferably one with a little more power (for instance, if your current power supply is rated at 250 Watts try one rated at 300 Watts). You should also read the SIG11 FAQ (listed below) which has excellent explanations of all these problems, albeit from a &linux; viewpoint. It also discusses how memory testing software or hardware can still pass faulty memory. Finally, if none of this has helped it is possible that you have just found a bug in FreeBSD, and you should follow the instructions to send a problem report. There is an extensive FAQ on this at the SIG11 problem FAQ My system crashes with either Fatal trap 12: page fault in kernel mode, or panic:, and spits out a bunch of information. What should I do? The FreeBSD developers are very interested in these errors, but need some more information than just the error you see. Copy your full crash message. Then consult the FAQ section on kernel panics, build a debugging kernel, and get a backtrace. This might sound difficult, but you do not need any programming skills; you just have to follow the instructions. Why does the screen go black and lose sync when I boot? This is a known problem with the ATI Mach 64 video card. The problem is that this card uses address 2e8, and the fourth serial port does too. Due to a bug (feature?) in the &man.sio.4; driver it will touch this port even if you do not have the fourth serial port, and even if you disable sio3 (the fourth port) which normally uses this address. Until the bug has been fixed, you can use this workaround: Enter at the boot prompt. (This will put the kernel into configuration mode). Disable sio0, sio1, sio2 and sio3 (all of them). This way the sio driver does not get activated -> no problems. Type exit to continue booting. If you want to be able to use your serial ports, you will have to build a new kernel with the following modification: in /usr/src/sys/i386/isa/sio.c find the one occurrence of the string 0x2e8 and remove that string and the preceding comma (keep the trailing comma). Now follow the normal procedure of building a new kernel. Even after applying these workarounds, you may still find that the X Window System does not work properly. If this is the case, make sure that the &xfree86; version you are using is at least &xfree86; 3.3.3 or higher. This version and upwards has built-in support for the Mach64 cards and even a dedicated X server for those cards. Why does FreeBSD only use 64 MB of RAM when my system has 128 MB of RAM installed? Due to the manner in which FreeBSD gets the memory size from the BIOS, it can only detect 16 bits worth of Kbytes in size (65535 Kbytes = 64MB) (or less... some BIOSes peg the memory size to 16M). If you have more than 64MB, FreeBSD will attempt to detect it; however, the attempt may fail. To work around this problem, you need to use the kernel option specified below. There is a way to get complete memory information from the BIOS, but we do not have room in the bootblocks to do it. Someday when lack of room in the bootblocks is fixed, we will use the extended BIOS functions to get the full memory information...but for now we are stuck with the kernel option. options "MAXMEM=n" Where n is your memory in Kilobytes. For a 128 MB machine, you would want to use 131072. Why does FreeBSD 2.0 panic with kmem_map too small!? The message may also be mb_map too small! The panic indicates that the system ran out of virtual memory for network buffers (specifically, mbuf clusters). You can increase the amount of VM available for mbuf clusters by adding: options "NMBCLUSTERS=n" to your kernel config file, where n is a number in the range 512-4096, depending on the number of concurrent TCP connections you need to support. I would recommend trying 2048 - this should get rid of the panic completely. You can monitor the number of mbuf clusters allocated/in use on the system with netstat -m (see &man.netstat.1;). The default value for NMBCLUSTERS is 512 + MAXUSERS * 16. Why do I get the error /kernel: proc: table is full? The FreeBSD kernel will only allow a certain number of processes to exist at one time. The number is based on the MAXUSERS option in the kernel configuration. MAXUSERS also affects various other in-kernel limits, such as network buffers (see this earlier question). If your machine is heavily loaded, you probably want to increase MAXUSERS. This will increase these other system limits in addition to the maximum number of processes. After FreeBSD 4.4, MAXUSERS became a tunable value that could be set with kern.maxusers in /boot/loader.conf. In earlier versions of FreeBSD, you need to adjust MAXUSERS in your kernel configuration. If your machine is lightly loaded, and you are simply running a very large number of processes, you can adjust this with the kern.maxproc sysctl. If these processes are being run by a single user, you will also need to adjust kern.maxprocperuid to be one less than your new kern.maxproc value. (It must be at least one less because one system program, &man.init.8;, must always be running.) To make a sysctl permanent across reboots, set this in /etc/sysctl.conf in recent versions of FreeBSD, or /etc/rc.local in older versions. Why do I get an error reading CMAP busy when rebooting with a new kernel? The logic that attempts to detect an out of date /var/db/kvm_*.db files sometimes fails and using a mismatched file can sometimes lead to panics. If this happens, reboot single-user and do: &prompt.root; rm /var/db/kvm_*.db What does the message ahc0: brkadrint, Illegal Host Access at seqaddr 0x0 mean? This is a conflict with an Ultrastor SCSI Host Adapter. During the boot process enter the kernel configuration menu and disable uha0, which is causing the problem. When I boot my system, I get the error ahc0: illegal cable configuration. My cabling is correct. What is going on? Your motherboard lacks the external logic to support automatic termination. Switch your SCSI BIOS to specify the correct termination for your configuration rather than automatic termination. The AIC7XXX driver cannot determine if the external logic for cable detection (and thus auto-termination) is available. The driver simply assumes that this support must exist if the configuration contained in the serial EEPROM is set to "automatic termination". Without the external cable detection logic the driver will often configure termination incorrectly, which can compromise the reliability of the SCSI bus. Why does Sendmail give me an error reading mail loops back to myself? This is answered in the sendmail FAQ as follows:- * I'm getting "Local configuration error" messages, such as: 553 relay.domain.net config error: mail loops back to myself 554 <user@domain.net>... Local configuration error How can I solve this problem? You have asked mail to the domain (e.g., domain.net) to be forwarded to a specific host (in this case, relay.domain.net) by using an MX record, but the relay machine does not recognize itself as domain.net. Add domain.net to /etc/mail/local-host-names (if you are using FEATURE(use_cw_file)) or add "Cw domain.net" to /etc/mail/sendmail.cf. The current version of the sendmail FAQ is no longer maintained with the sendmail release. It is however regularly posted to comp.mail.sendmail, comp.mail.misc, comp.mail.smail, comp.answers, and news.answers. You can also receive a copy via email by sending a message to mail-server@rtfm.mit.edu with the command send usenet/news.answers/mail/sendmail-faq as the body of the message. Why do full screen applications on remote machines misbehave? The remote machine may be setting your terminal type to something other than the cons25 terminal type required by the FreeBSD console. There are a number of possible work-arounds for this problem: After logging on to the remote machine, set your TERM shell variable to ansi or sco if the remote machine knows about these terminal types. Use a VT100 emulator like screen at the FreeBSD console. screen offers you the ability to run multiple concurrent sessions from one terminal, and is a neat program in its own right. Each screen window behaves like a VT100 terminal, so the TERM variable at the remote end should be set to vt100. Install the cons25 terminal database entry on the remote machine. The way to do this depends on the operating system on the remote machine. The system administration manuals for the remote system should be able to help you here. Fire up an X server at the FreeBSD end and login to the remote machine using an X based terminal emulator such as xterm or rxvt. The TERM variable at the remote host should be set to xterm or vt100. Why does my machine print calcru: negative time...? This can be caused by various hardware or software ailments relating to interrupts. It may be due to bugs but can also happen by nature of certain devices. Running TCP/IP over the parallel port using a large MTU is one good way to provoke this problem. Graphics accelerators can also get you here, in which case you should check the interrupt setting of the card first. A side effect of this problem are dying processes with the message SIGXCPU exceeded cpu time limit. For FreeBSD 3.0 and later from Nov 29, 1998 forward: If the problem cannot be fixed otherwise the solution is to set this sysctl variable: &prompt.root; sysctl -w kern.timecounter.method=1 The option of &man.sysctl.8; is deprecated and silently ignored in &os; 4.4-RELEASE and all newer versions. You can safely ommit it when setting options with sysctl as shown above. This means a performance impact, but considering the cause of this problem, you probably will not notice. If the problem persists, keep the sysctl set to one and set the NTIMECOUNTER option in your kernel to increasingly large values. If by the time you have reached NTIMECOUNTER=20 the problem is not solved, interrupts are too hosed on your machine for reliable time keeping. I see pcm0 not found or my sound card is found as pcm1 but I have device pcm0 in my kernel config file. What is going on? This occurs in FreeBSD 3.X with PCI sound cards. The pcm0 device is reserved exclusively for ISA-based cards so, if you have a PCI card, then you will see this error, and your card will appear as pcm1. You cannot remove the warning by simply changing the line in the kernel config file to device pcm1 as this will result in pcm1 being reserved for ISA cards and your PCI card being found as pcm2 (along with the warning pcm1 not found). If you have a PCI sound card you will also have to make the snd1 device rather than snd0: &prompt.root; cd /dev &prompt.root; ./MAKEDEV snd1 You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled, since the proper device nodes will be created automatically under /dev. This situation does not arise in FreeBSD 4.X as a lot of work has been done to make it more PnP-centric and the pcm0 device is no longer reserved exclusively for ISA cards Why is my PnP card no longer found (or found as unknown) since upgrading to FreeBSD 4.X? FreeBSD 4.X is now much more PnP-centric and this has had the side effect of some PnP devices (e.g. sound cards and internal modems) not working even though they worked under FreeBSD 3.X. The reasons for this behavior are explained by the following e-mail, posted to the freebsd-questions mailing list by Peter Wemm, in answer to a question about an internal modem that was no longer found after an upgrade to FreeBSD 4.X (the comments in [] have been added to clarify the context. The contents of this quotation has been updated from its original text.
The PNP bios preconfigured it [the modem] and left it laying around in port space, so [in 3.X] the old-style ISA probes found it there. Under 4.0, the ISA code is much more PnP-centric. It was possible [in 3.X] for an ISA probe to find a stray device and then for the PNP device id to match and then fail due to resource conflicts. So, it disables the programmable cards first so this double probing cannot happen. It also means that it needs to know the PnP id's for supported PnP hardware. Making this more user tweakable is on the TODO list.
To get the device working again requires finding its PnP id and adding it to the list that the ISA probes use to identify PnP devices. This is obtained using &man.pnpinfo.8; to probe the device, for example this is the output from &man.pnpinfo.8; for an internal modem: &prompt.root; pnpinfo Checking for Plug-n-Play devices... Card assigned CSN #1 Vendor ID PMC2430 (0x3024a341), Serial Number 0xffffffff PnP Version 1.0, Vendor Version 0 Device Description: Pace 56 Voice Internal Plug & Play Modem Logical Device ID: PMC2430 0x3024a341 #0 Device supports I/O Range Check TAG Start DF I/O Range 0x3f8 .. 0x3f8, alignment 0x8, len 0x8 [16-bit addr] IRQ: 4 - only one type (true/edge) [more TAG lines elided] TAG End DF End Tag Successfully got 31 resources, 1 logical fdevs -- card select # 0x0001 CSN PMC2430 (0x3024a341), Serial Number 0xffffffff Logical device #0 IO: 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 IRQ 5 0 DMA 4 0 IO range check 0x00 activate 0x01 The information you require is in the Vendor ID line at the start of the output. The hexadecimal number in parentheses (0x3024a341 in this example) is the PnP id and the string immediately before this (PMC2430) is a unique ASCII id. Alternatively, if &man.pnpinfo.8; does not list the card in question, &man.pciconf.8; can be used instead. This is part of the output from pciconf -vl for an onboard sound chip: &prompt.root; pciconf -vl chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02 hdr=0x00 vendor = 'Intel Corporation' device = '82801AA 8xx Chipset AC'97 Audio Controller' class = multimedia subclass = audio Here, you would use the chip value, 0x24158086. This information (Vendor ID or chip value) needs adding to the file /usr/src/sys/isa/sio.c. You should first make a backup of sio.c just in case things go wrong. You will also need it to make the patch to submit with your PR (you are going to submit a PR, are you not?) then edit sio.c and search for the line static struct isa_pnp_id sio_ids[] = { then scroll down to find the correct place to add the entry for your device. The entries look like this, and are sorted on the ASCII Vendor ID string which should be included in the comment to the right of the line of code along with all (if it will fit) or part of the Device Description from the output of &man.pnpinfo.8;: {0x0f804f3f, NULL}, /* OZO800f - Zoom 2812 (56k Modem) */ {0x39804f3f, NULL}, /* OZO8039 - Zoom 56k flex */ {0x3024a341, NULL}, /* PMC2430 - Pace 56 Voice Internal Modem */ {0x1000eb49, NULL}, /* ROK0010 - Rockwell ? */ {0x5002734a, NULL}, /* RSS0250 - 5614Jx3(G) Internal Modem */ Add the hexadecimal Vendor ID for your device in the correct place, save the file, rebuild your kernel, and reboot. Your device should now be found as an sio device as it was under FreeBSD 3.X Why do I get the error nlist failed when running, for example, top or systat? The problem is that the application you are trying to run is looking for a specific kernel symbol, but, for whatever reason, cannot find it; this error stems from one of two problems: Your kernel and userland are not synchronized (i.e., you built a new kernel but did not do an installworld, or vice versa), and thus the symbol table is different from what the user application thinks it is. If this is the case, simply complete the upgrade process (see /usr/src/UPDATING for the correct sequence). You are not using /boot/loader to load your kernel, but doing it directly from boot2 (see &man.boot.8;). While there is nothing wrong with bypassing /boot/loader, it generally does a better job of making the kernel symbols available to user applications. Why does it take so long to connect to my computer via ssh or telnet? The symptom: there is a long delay between the time the TCP connection is established and the time when the client software asks for a password (or, in &man.telnet.1;'s case, when a login prompt appears). The problem: more likely than not, the delay is caused by the server software trying to resolve the client's IP address into a hostname. Many servers, including the Telnet and SSH servers that come with FreeBSD, do this in order to, among other things, store the hostname in a log file for future reference by the administrator. The remedy: if the problem occurs whenever you connect from your computer (the client) to any server, the problem is with the client; likewise, if the problem only occurs when someone connects to your computer (the server) the problem is with the server. If the problem is with the client, the only remedy is to fix the DNS so the server can resolve it. If this is on a local network, consider it a server problem and keep reading; conversely, if this is on the global Internet, you will most likely need to contact your ISP and ask them to fix it for you. If the problem is with the server, and this is on a local network, you need to configure the server to be able to resolve address-to-hostname queries for your local address range. See the &man.hosts.5; and &man.named.8; manual pages for more information. If this is on the global Internet, the problem may be that your server's resolver is not functioning correctly. To check, try to look up another host--say, www.yahoo.com. If it does not work, that is your problem. What does stray IRQ mean? Stray IRQs are indications of hardware IRQ glitches, mostly from hardware that removes its interrupt request in the middle of the interrupt request acknowledge cycle. One has three options for dealing with this: Live with the warnings. All except the first 5 per irq are suppressed anyway. Break the warnings by changing 5 to 0 in isa_strayintr() so that all the warnings are suppressed. Break the warnings by installing parallel port hardware that uses irq 7 and the PPP driver for it (this happens on most systems), and install an ide drive or other hardware that uses irq 15 and a suitable driver for it. Why does file: table is full show up repeatedly in dmesg? This error message indicates you have exhausted the number of available file descriptors on your system. Please see the kern.maxfiles section of the Tuning Kernel Limits section of the Handbook for a discussion and solution. Why does the clock on my laptop keep incorrect time? Your laptop has two or more clocks, and FreeBSD has chosen to use the wrong one. Run &man.dmesg.8;, and check for lines that contain Timecounter. The last line printed is the one that FreeBSD chose, and will almost certainly be TSC. &prompt.root; dmesg | grep Timecounter Timecounter "i8254" frequency 1193182 Hz Timecounter "TSC" frequency 595573479 Hz You can confirm this by checking the kern.timecounter.hardware &man.sysctl.3;. &prompt.root; sysctl kern.timecounter.hardware kern.timecounter.hardware: TSC The BIOS may modify the TSC clock—perhaps to change the speed of the processor when running from batteries, or going into a power saving mode, but FreeBSD is unaware of these adjustments, and appears to gain or lose time. In this example, the i8254 clock is also available, and can be selected by writing its name to the kern.timecounter.hardware &man.sysctl.3;. &prompt.root; sysctl -w kern.timecounter.hardware=i8254 kern.timecounter.hardware: TSC -> i8254 Your laptop should now start keeping more accurate time. To have this change automatically run at boot time, add the following line to /etc/sysctl.conf. kern.timecounter.hardware=i8254 Why did my laptop fail to correctly probe PC cards? This problem is common on laptops that boot more than one operating system. Some non-BSD operating systems leave PC card hardware in an inconsistent state. pccardd will detect the card as "(null)""(null)" instead of its actual model. You must remove all power from the PC card slot to fully reset the hardware. Completely power off the laptop. (Don't suspend it, don't let it go into standby; the power needs to be completely off.) Wait a few moments, and reboot. Your PC card should work now. Some laptop hardware lies when it claims to be off. If the above does not work shut down, remove the battery, wait a moment, replace the battery, and reboot. Why does FreeBSD's boot loader display Read error and stop after the BIOS screen? FreeBSD's boot loader is incorrectly recognizing the hard drive's geometry. This must be manually set within fdisk when creating or modifying FreeBSD's slice. The correct drive geometry values can be found within the machine's BIOS. Look for the number of cylinders, heads and sectors for the particular drive. Within &man.sysinstall.8;'s fdisk, hit G to set the drive geometry. A dialog will pop up requesting the number of cylinders, heads and sectors. Type the numbers found from the BIOS separates by forward slashes. 5000 cylinders, 250 sectors and 60 sectors would be entered as 5000/250/60 Press enter to set the values, and hit W to write the new partition table to the drive. Another operating system destroyed my Boot Manager. How do I get it back? Enter &man.sysinstall.8; and choose Configure, then Fdisk. Select the disk the Boot Manager resided on with the space key. Press W to write changes to the drive. A prompt will appear asking which boot loader to install. Select this, and it will be restored. What does the error swap_pager: indefinite wait buffer: mean? This means that a process is trying to page memory to disk, and the page attempt has hung trying to access the disk for more than 20 seconds. It might be caused by bad blocks on the disk drive, disk wiring, cables, or any other disk I/O-related hardware. If the drive itself is actually bad, you will also see disk errors in /var/log/messages and in the output of dmesg. Otherwise, check your cables and connections. What are UDMA ICRC errors, and how do I fix them? The &man.ata.4; driver reports UDMA ICRC errors when a DMA transfer to or from a drive is corrupted. The driver will retry the operation a few times. Should the retries fail, it will switch from DMA to the slower PIO mode of communication with the device. The problem can be caused by many factors, although perhaps the most common cause is faulty or incorrect cabling. Check that the ATA cables are undamaged and rated for the Ultra DMA mode in use. If you're using removable drive trays, they must also be compatible. Be sure that all connections are making good contact. Problems have also been noticed when an old drive is installed on the same ATA channel as an Ultra DMA 66 (or faster) drive. Lastly, these errors can indicate that the drive is failing. Most drive vendors provide testing software for their drives, so test your drive, and, if necessary, back up your data and replace it. The &man.atacontrol.8; utility can be used to show and select the DMA or PIO modes used for each ATA device. In particular, atacontrol mode channel will show the modes in use on a particular ATA channel, where the primary channel is numbered 0, and so on. What is a lock order reversal? &a.rwatson; answered this question very succinctly on the freebsd-current list in a thread entitled lock order reversals - what do they mean?
&a.rwatson; on freebsd-current, December 14, 2003 These warnings are generated by Witness, a run-time lock diagnostic system found in FreeBSD 5-CURRENT kernels (but removed in releases). You can read more about Witness in the &man.witness.4; man page, which talks about its capabilities. Among other things, Witness performs run-time lock order verification using a combination of hard coded lock orders, and run-time detected lock orders, and generates console warnings when lock orders are violated. The intent of this is to detect the potential for deadlocks due to lock order violations; it's worth observing that Witness is actually slightly conservative, and so it's possible to get false positives. In the event that Witness is accurately reporting a lock order problem, it's basically saying "If you were unlucky, a deadlock would have happened here". There are a couple of "well known" false positives, which we need to do a better job of documenting to prevent spurious reports. The non-well-known ones typically correspond to bugs in newly added locking, as lock order reversals usually get fixed pretty quickly because Witness is busy generating warnings :-).
See Bjoern Zeeb's lock order reversal page for the status of known lock order reversals. Commercial Applications This section is still very sparse, though we are hoping, of course, that companies will add to it! :) The FreeBSD group has no financial interest in any of the companies listed here but simply lists them as a public service (and feels that commercial interest in FreeBSD can have very positive effects on FreeBSD's long-term viability). We encourage commercial software vendors to send their entries here for inclusion. See the Vendors page for a longer list. Where can I get an Office Suite for FreeBSD? The FreeBSD Mall offers a FreeBSD native version of VistaSource ApplixWare 5. ApplixWare is a rich full-featured, commercial Office Suite for FreeBSD containing a word processor, spreadsheet, presentation program, vector drawing package, and other applications. ApplixWare is offered as part of the FreeBSD Mall's BSD Desktop Edition. The &linux; version of StarOffice works flawlessly on FreeBSD. The easiest way to install the &linux; version of StarOffice is through the FreeBSD Ports collection. Future versions of the open-source OpenOffice suite should work as well. Where can I get &motif; for FreeBSD? The Open Group has released the source code to &motif; 2.1.30. You can install the open-motif package, or compile it from ports. Refer to the ports section of the Handbook for more information on how to do this. The Open &motif; distribution only allows redistribution if it is running on an open source operating system. In addition, there are commercial distributions of the &motif; software available. These, however, are not for free, but their license allows them to be used in closed-source software. Contact Apps2go for the least expensive ELF &motif; 2.1.20 distribution for FreeBSD (either &i386; or Alpha). There are two distributions, the development edition and the runtime edition (for much less). These distributions includes: OSF/&motif; manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic ELF libraries (for use with FreeBSD 3.0 and above). Demonstration applets. Be sure to specify that you want the FreeBSD version of &motif; when ordering (do not forget to mention the architecture you want too)! Versions for NetBSD and OpenBSD are also sold by Apps2go. This is currently a FTP only download. More info Apps2go WWW page or sales@apps2go.com or support@apps2go.com or phone (817) 431 8775 or +1 817 431-8775 Contact Metro Link for an either ELF or a.out &motif; 2.1 distribution for FreeBSD. This distribution includes: OSF/&motif; manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic libraries (specify ELF for use with FreeBSD 3.0 and later; or a.out for use with FreeBSD 2.2.8 and earlier). Demonstration applets. Preformatted manual pages. Be sure to specify that you want the FreeBSD version of &motif; when ordering! Versions for &linux; are also sold by Metro Link. This is available on either a CDROM or for FTP download. Contact Xi Graphics for an a.out &motif; 2.0 distribution for FreeBSD. This distribution includes: OSF/&motif; manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic libraries (for use with FreeBSD 2.2.8 and earlier). Demonstration applets. Preformatted manual pages. Be sure to specify that you want the FreeBSD version of &motif; when ordering! Versions for BSDI and &linux; are also sold by Xi Graphics. This is currently a 4 diskette set... in the future this will change to a unified CD distribution like their CDE. Where can I get CDE for FreeBSD? Xi Graphics used to sell CDE for FreeBSD, but no longer do. KDE is an open source X11 desktop which is similar to CDE in many respects. You might also like the look and feel of xfce. KDE and xfce are both in the ports system. Are there any commercial high-performance X servers? Yes, Xi Graphics and Metro Link sell Accelerated-X product for FreeBSD and other Intel based systems. The Metro Link offering is a high performance X Server that offers easy configuration using the FreeBSD Package suite of tools, support for multiple concurrent video boards and is distributed in binary form only, in a convenient FTP download. Not to mention the Metro Link offering is available at the very reasonable price of $39. Metro Link also sells both ELF and a.out &motif; for FreeBSD (see above). More info Metro Link WWW page or sales@metrolink.com or tech@metrolink.com or phone (954) 938-0283 or +1 954 938-0283 The Xi Graphics offering is a high performance X Server that offers easy configuration, support for multiple concurrent video boards and is distributed in binary form only, in a unified diskette distribution for FreeBSD and &linux;. Xi Graphics also offers a high performance X Server tailored for laptop support. There is a free compatibility demo of version 5.0 available. Xi Graphics also sells &motif; and CDE for FreeBSD (see above). More info Xi Graphics WWW page or sales@xig.com or support@xig.com or phone (800) 946 7433 or +1 303 298-7478. Are there any Database systems for FreeBSD? Yes! See the Commercial Vendors section of FreeBSD's Web site. Also see the Databases section of the Ports collection. Can I run &oracle; on FreeBSD? Yes. The following pages tell you exactly how to set up &linux;-&oracle; on FreeBSD: http://www.scc.nl/~marcel/howto-oracle.html http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd User Applications So, where are all the user applications? Please take a look at the ports page for info on software packages ported to FreeBSD. The list currently tops &os.numports; and is growing daily, so come back to check often or subscribe to the freebsd-announce mailing list for periodic updates on new entries. Most ports should work on the 4.X and 5.X branches. Each time a FreeBSD release is made, a snapshot of the ports tree at the time of release in also included in the ports/ directory. We also support the concept of a package, essentially no more than a gzipped binary distribution with a little extra intelligence embedded in it for doing whatever custom installation work is required. A package can be installed and uninstalled again easily without having to know the gory details of which files it includes. Use the package installation menu in /stand/sysinstall (under the post-configuration menu item) or invoke the &man.pkg.add.1; command on the specific package files you are interested in installing. Package files can usually be identified by their .tgz suffix and CDROM distribution people will have a packages/All directory on their CD which contains such files. They can also be downloaded over the net for various versions of FreeBSD at the following locations: for 4.X-RELEASE/4-STABLE ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/ for 5.X-CURRENT ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current or your nearest local mirror site. Note that all ports may not be available as packages since new ones are constantly being added. It is always a good idea to check back periodically to see which packages are available at the ftp.FreeBSD.org master site. Why does ghostscript give lots of errors with my 386/486SX? You do not have a math co-processor, right? You will need to add the alternative math emulator to your kernel; you do this by adding the following to your kernel config file and it will be compiled in. options GPL_MATH_EMULATE You will need to remove the MATH_EMULATE option when you do this. How do I configure INN (Internet News) for my machine? After installing the news/inn package or port, an excellent place to start is Dave Barr's INN Page where you will find the INN FAQ. What version of µsoft; FrontPage should I get? Use the Port, Luke! A pre-patched version of Apache, www/apache13-fp, is available in the ports tree. Does FreeBSD support &java;? Yes. Please see http://www.FreeBSD.org/java/. Why can I not build this port on my 3.X-STABLE machine? If you are running a FreeBSD version that lags significantly behind -CURRENT or -STABLE, you may need a ports upgrade kit from http://www.FreeBSD.org/ports/. If you are up to date, then someone might have committed a change to the port which works for -CURRENT but which broke the port for -STABLE. Please submit a bug report on this with the &man.send-pr.1; command, since the ports collection is supposed to work for both the -CURRENT and -STABLE branches. I just tried to build INDEX using make index, and it failed. Why? First, always make sure that you have a completely up-to-date Ports Collection. Errors that affect building INDEX from an up-to-date copy of the Ports Collection are high-visibility and are thus almost always fixed immediately. However, if you are up-to-date, perhaps you are seeing another problem. make index has a known bug in dealing with incomplete copies of the Ports Collection. It assumes that you have a local copy of every single port that every other port that you have a local copy of depends on. To explain, if you have a copy of foo/bar on your disk, and foo/bar depends on baz/quux, then you must also have a copy of baz/quux on your disk, and the ports baz/quux depends on, and so on. Otherwise, make index has insufficient information to create its dependency tree. This is particularly a problem for &os; users who utilize &man.cvsup.1; to track the Ports Collection but choose not to install certain categories by specifying them in refuse. In theory, one should be able to refuse categories, but in practice there are too many ports that depend on ports in other categories. Until someone comes up with a solution for this problem, the general rule is is that if you want to build INDEX, you must have a complete copy of the Ports Collection. There are rare cases where INDEX will not build due to odd cases involving WITH_* or WITHOUT_* variables being set in make.conf. If you suspect that this is the case, please try to make INDEX with those Makevars turned off before reporting it to &a.ports;. Where do I find ld.so? a.out applications like &netscape.navigator; require a.out libraries. A version of FreeBSD built with ELF libraries does not install them by default. You will get complaints about not having /usr/libexec/ld.so if this is the case on your system. These libraries are available as an add-on in the compat22 distribution. Use &man.sysinstall.8; to install them. You can also install them from the FreeBSD source code: &prompt.root; cd /usr/src/lib/compat/compat22 &prompt.root; make install clean If you want to install the latest compat22 libraries whenever you run make world, edit /etc/make.conf to include COMPAT22=YES. Old compatibility libraries change rarely, if ever, so this is not generally needed. Also see the ERRATAs for 3.1-RELEASE and 3.2-RELEASE. I updated the sources, now how do I update my installed ports? FreeBSD does not include a port upgrading tool, but it does have some tools to make the upgrade process somewhat easier. You can also install additional tools to simplify port handling. The &man.pkg.version.1; command can generate a script that will update installed ports to the latest version in the ports tree. &prompt.root; pkg_version -c > /tmp/myscript The output script must be edited by hand before you use it. Recent versions of &man.pkg.version.1; force this by inserting an &man.exit.1; at the beginning of the script. You should save the output of the script, as it will note packages that depend on the one that has been updated. These may or may not need to be updated as well. The usual case where they need to be updated is that a shared library has changed version numbers, so the ports that used that library need to be rebuilt to use the new version. Beginning with FreeBSD 5.0 (and higher revisions), &man.pkg.version.1; no longer supports the option. If you have the disk space, you can use the portupgrade tool to automate all of this. portupgrade includes various tools to simplify package handling. It is available under sysutils/portupgrade. Since it is written in Ruby, portupgrade is an unlikely candidate for integration with the main FreeBSD tree. That should not stop anyone from using it, however. If your system is up full time, the &man.periodic.8; system can be used to generate a weekly list of ports that might need updating by setting weekly_status_pkg_enable="YES" in /etc/periodic.conf. Why is /bin/sh so minimal? Why does FreeBSD not use bash or another shell? Because &posix; says that there shall be such a shell. The more complicated answer: many people need to write shell scripts which will be portable across many systems. That is why &posix; specifies the shell and utility commands in great detail. Most scripts are written in Bourne shell, and because several important programming interfaces (&man.make.1;, &man.system.3;, &man.popen.3;, and analogues in higher-level scripting languages like Perl and Tcl) are specified to use the Bourne shell to interpret commands. Because the Bourne shell is so often and widely used, it is important for it to be quick to start, be deterministic in its behavior, and have a small memory footprint. The existing implementation is our best effort at meeting as many of these requirements simultaneously as we can. In order to keep /bin/sh small, we have not provided many of the convenience features that other shells have. That is why the Ports Collection includes more featureful shells like bash, scsh, tcsh, and zsh. (You can compare for yourself the memory utilization of all these shells by looking at the VSZ and RSS columns in a ps -u listing.) Why do &netscape; and Opera take so long to start? The usual answer is that DNS on your system is misconfigured. Both &netscape; and Opera perform DNS checks when starting up. The browser will not appear on your desktop until the program either gets a response or determines that the system has no network connection. I updated parts of the Ports Collection using CVSup, and now many ports fail to build with mysterious error messages! What happened? Is the Ports Collection broken in some major way? If you only update parts of the Ports Collection, using one of its CVSup subcollections and not the ports-all CVSup collection, you should always update the ports-base subcollection too! The reasons are described in the Handbook. How do I create audio CDs from my MIDI files? To create audio CDs from MIDI files, first install audio/timidity++ from ports then install manually the GUS patches set by Eric A. Welsh, available at . After timidity++ has been installed properly, midi files may be converted to wav's with the following command line: &prompt.user; timidity -Ow -s 44100 -o /tmp/juke/01.wav 01.mid The wav files can then be converted to other formats or burned onto audio CDs, as described in the FreeBSD Handbook. Kernel Configuration I would like to customize my kernel. Is it difficult? Not at all! Check out the kernel config section of the Handbook. We recommend that you make a dated snapshot of your new /kernel called /kernel.YYMMDD after you get it working properly. Also back up your new /modules directory to /modules.YYMMDD. That way, if you make a mistake the next time you play with your configuration you can boot the backup kernel instead of having to fall back to kernel.GENERIC. This is particularly important if you are now booting from a controller that GENERIC does not support. My kernel compiles fail because _hw_float is missing. How do I solve this problem? Let me guess. You removed npx0 (see &man.npx.4;) from your kernel configuration file because you do not have a math co-processor, right? Wrong! :-) The npx0 is MANDATORY. Even if you do not have a mathematic co-processor, you must include the npx0 device. Why is my kernel so big (over 10MB)? Chances are, you compiled your kernel in debug mode. Kernels built in debug mode contain many symbols that are used for debugging, thus greatly increasing the size of the kernel. Note that if you running a FreeBSD 3.0 or later system, there will be little or no performance decrease from running a debug kernel, and it is useful to keep one around in case of a system panic. However, if you are running low on disk space, or you simply do not want to run a debug kernel, make sure that both of the following are true: You do not have a line in your kernel configuration file that reads: makeoptions DEBUG=-g You are not running &man.config.8; with the option. Both of the above situations will cause your kernel to be built in debug mode. As long as you make sure you follow the steps above, you can build your kernel normally, and you should notice a fairly large size decrease; most kernels tend to be around 1.5MB to 2MB. Why do I get interrupt conflicts with multi-port serial code? When I compile a kernel with multi-port serial code, it tells me that only the first port is probed and the rest skipped due to interrupt conflicts. How do I fix this? The problem here is that FreeBSD has code built-in to keep the kernel from getting trashed due to hardware or software conflicts. The way to fix this is to leave out the IRQ settings on all but one port. Here is an example: # # Multiport high-speed serial line - 16550 UARTS # device sio2 at isa? port 0x2a0 tty irq 5 flags 0x501 vector siointr device sio3 at isa? port 0x2a8 tty flags 0x501 vector siointr device sio4 at isa? port 0x2b0 tty flags 0x501 vector siointr device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr Why does every kernel I try to build fail to compile, even GENERIC? There are a number of possible causes for this problem. They are, in no particular order: You are not using the new make buildkernel and make installkernel targets, and your source tree is different from the one used to build the currently running system (e.g., you are compiling 4.3-RELEASE on a 4.0-RELEASE system). If you are attempting an upgrade, please read the /usr/src/UPDATING file, paying particular attention to the COMMON ITEMS section at the end. You are using the new make buildkernel and make installkernel targets, but you failed to assert the completion of the make buildworld target. The make buildkernel target relies on files generated by the make buildworld target to complete its job correctly. Even if you are trying to build FreeBSD-STABLE, it is possible that you fetched the source tree at a time when it was either being modified, or broken for other reasons; only releases are absolutely guaranteed to be buildable, although FreeBSD-STABLE builds fine the majority of the time. If you have not already done so, try re-fetching the source tree and see if the problem goes away. Try using a different server in case the one you are using is having problems. How can I verify which scheduler is in use on a running system? Just type: &prompt.root; sysctl kern.quantum If you see unknown oid 'kern.quantum' it means that the current scheduler is SCHED_ULE, however, if you see kern.quantum: 100000 then the original scheduler SCHED_4BSD is the current selection. What is 'kern.quantum'? kern.quantum is the maximum number of ticks a process can run without being preempted. It is specific to the 4BSD scheduler, so you can use its presence or absence to determine which scheduler is in use. Disks, Filesystems, and Boot Loaders How can I add my new hard disk to my FreeBSD system? See the Disk Formatting Tutorial at www.FreeBSD.org. How do I move my system over to my huge new disk? The best way is to reinstall the OS on the new disk, then move the user data over. This is highly recommended if you have been tracking -STABLE for more than one release, or have updated a release instead of installing a new one. You can install booteasy on both disks with &man.boot0cfg.8;, and dual boot them until you are happy with the new configuration. Skip the next paragraph to find out how to move the data after doing this. Should you decide not to do a fresh install, you need to partition and label the new disk with either /stand/sysinstall, or &man.fdisk.8; and &man.disklabel.8;. You should also install booteasy on both disks with &man.boot0cfg.8;, so that you can dual boot to the old or new system after the copying is done. See the formatting-media article for details on this process. Now you have the new disk set up, and are ready to move the data. Unfortunately, you cannot just blindly copy the data. Things like device files (in /dev), flags, and links tend to screw that up. You need to use tools that understand these things, which means &man.dump.8;. Although it is suggested that you move the data in single user mode, it is not required. You should never use anything but &man.dump.8; and &man.restore.8; to move the root filesystem. The &man.tar.1; command may work - then again, it may not. You should also use &man.dump.8; and &man.restore.8; if you are moving a single partition to another empty partition. The sequence of steps to use dump to move a partitions data to a new partition is: newfs the new partition. mount it on a temporary mount point. cd to that directory. dump the old partition, piping output to the new one. For example, if you are going to move root to /dev/ad1s1a, with /mnt as the temporary mount point, it is: &prompt.root; newfs /dev/ad1s1a &prompt.root; mount /dev/ad1s1a /mnt &prompt.root; cd /mnt &prompt.root; dump 0af - / | restore xf - Rearranging your partitions with dump takes a bit more work. To merge a partition like /var into its parent, create the new partition large enough for both, move the parent partition as described above, then move the child partition into the empty directory that the first move created: &prompt.root; newfs /dev/ad1s1a &prompt.root; mount /dev/ad1s1a /mnt &prompt.root; cd /mnt &prompt.root; dump 0af - / | restore xf - &prompt.root; cd var &prompt.root; dump 0af - /var | restore xf - To split a directory from its parent, say putting /var on its own partition when it was not before, create both partitions, then mount the child partition on the appropriate directory in the temporary mount point, then move the old single partition: &prompt.root; newfs /dev/ad1s1a &prompt.root; newfs /dev/ad1s1d &prompt.root; mount /dev/ad1s1a /mnt &prompt.root; mkdir /mnt/var &prompt.root; mount /dev/ad1s1d /mnt/var &prompt.root; cd /mnt &prompt.root; dump 0af - / | restore xf - You might prefer &man.cpio.1;, &man.pax.1;, &man.tar.1; to &man.dump.8; for user data. At the time of this writing, these are known to lose file flag information, so use them with caution. Will a dangerously dedicated disk endanger my health? The installation procedure allows you to chose two different methods in partitioning your hard disk(s). The default way makes it compatible with other operating systems on the same machine, by using fdisk table entries (called slices in FreeBSD), with a FreeBSD slice that employs partitions of its own. Optionally, one can chose to install a boot-selector to switch between the possible operating systems on the disk(s). The alternative uses the entire disk for FreeBSD, and makes no attempt to be compatible with other operating systems. So why it is called dangerous? A disk in this mode does not contain what normal PC utilities would consider a valid fdisk table. Depending on how well they have been designed, they might complain at you once they are getting in contact with such a disk, or even worse, they might damage the BSD bootstrap without even asking or notifying you. In addition, the dangerously dedicated disk's layout is known to confuse many BIOSes, including those from AWARD (e.g. as found in HP Netserver and Micronics systems as well as many others) and Symbios/NCR (for the popular 53C8xx range of SCSI controllers). This is not a complete list, there are more. Symptoms of this confusion include the read error message printed by the FreeBSD bootstrap when it cannot find itself, as well as system lockups when booting. Why have this mode at all then? It only saves a few kbytes of disk space, and it can cause real problems for a new installation. Dangerously dedicated mode's origins lie in a desire to avoid one of the most common problems plaguing new FreeBSD installers - matching the BIOS geometry numbers for a disk to the disk itself. Geometry is an outdated concept, but one still at the heart of the PC's BIOS and its interaction with disks. When the FreeBSD installer creates slices, it has to record the location of these slices on the disk in a fashion that corresponds with the way the BIOS expects to find them. If it gets it wrong, you will not be able to boot. Dangerously dedicated mode tries to work around this by making the problem simpler. In some cases, it gets it right. But it is meant to be used as a last-ditch alternative - there are better ways to solve the problem 99 times out of 100. So, how do you avoid the need for DD mode when you are installing? Start by making a note of the geometry that your BIOS claims to be using for your disks. You can arrange to have the kernel print this as it boots by specifying at the boot: prompt, or using boot -v in the loader. Just before the installer starts, the kernel will print a list of BIOS geometries. Do not panic - wait for the installer to start and then use scrollback to read the numbers. Typically the BIOS disk units will be in the same order that FreeBSD lists your disks, first IDE, then SCSI. When you are slicing up your disk, check that the disk geometry displayed in the FDISK screen is correct (ie. it matches the BIOS numbers); if it is wrong, use the g key to fix it. You may have to do this if there is absolutely nothing on the disk, or if the disk has been moved from another system. Note that this is only an issue with the disk that you are going to boot from; FreeBSD will sort itself out just fine with any other disks you may have. Once you have got the BIOS and FreeBSD agreeing about the geometry of the disk, your problems are almost guaranteed to be over, and with no need for DD mode at all. If, however, you are still greeted with the dreaded read error message when you try to boot, it is time to cross your fingers and go for it - there is nothing left to lose. To return a dangerously dedicated disk for normal PC use, there are basically two options. The first is, you write enough NULL bytes over the MBR to make any subsequent installation believe this to be a blank disk. You can do this for example with &prompt.root; dd if=/dev/zero of=/dev/rda0 count=15 Alternatively, the undocumented DOS feature C:\> fdisk /mbr will to install a new master boot record as well, thus clobbering the BSD bootstrap. Which partitions can safely use Soft Updates? I have heard that Soft Updates on / can cause problems. Short answer: you can usually use Soft Updates safely on all partitions. Long answer: There used to be some concern over using Soft Updates on the root partition. Soft Updates has two characteristics that caused this. First, a Soft Updates partition has a small chance of losing data during a system crash. (The partition will not be corrupted; the data will simply be lost.) Also, Soft Updates can cause temporary space shortages. When using Soft Updates, the kernel can take up to thirty seconds to actually write changes to the physical disk. If you delete a large file, the file still resides on disk until the kernel actually performs the deletion. This can cause a very simple race condition. Suppose you delete one large file and immediately create another large file. The first large file is not yet actually removed from the physical disk, so the disk might not have enough room for the second large file. You get an error that the partition does not have enough space, although you know perfectly well that you just released a large chunk of space! When you try again mere seconds later, the file creation works as you expect. This has left more than one user scratching his head and doubting his sanity, the FreeBSD filesystem, or both. If a system should crash after the kernel accepts a chunk of data for writing to disk, but before that data is actually written out, data could be lost or corrupted. This risk is extremely small, but generally manageable. Use of IDE write caching greatly increases this risk; it is strongly recommended that you disable IDE write caching when using Soft Updates. These issues affect all partitions using Soft Updates. So, what does this mean for the root partition? Vital information on the root partition changes very rarely. Files such as /kernel and the contents of /etc only change during system maintenance, or when users change their passwords. If the system crashed during the thirty-second window after such a change is made, it is possible that data could be lost. This risk is negligible for most applications, but you should be aware that it exists. If your system cannot tolerate this much risk, do not use Soft Updates on the root filesystem! / is traditionally one of the smallest partitions. By default, FreeBSD puts the /tmp directory on /. If you have a busy /tmp, you might see intermittent space problems. Symlinking /tmp to /var/tmp will solve this problem. What is inappropriate about my ccd? The symptom of this is: &prompt.root; ccdconfig -C ccdconfig: ioctl (CCDIOCSET): /dev/ccd0c: Inappropriate file type or format This usually happens when you are trying to concatenate the c partitions, which default to type unused. The ccd driver requires the underlying partition type to be FS_BSDFFS. Edit the disklabel of the disks you are trying to concatenate and change the types of partitions to 4.2BSD. Why can I not edit the disklabel on my ccd? The symptom of this is: &prompt.root; disklabel ccd0 (it prints something sensible here, so let us try to edit it) &prompt.root; disklabel -e ccd0 (edit, save, quit) disklabel: ioctl DIOCWDINFO: No disk label on disk; use "disklabel -r" to install initial label This is because the disklabel returned by ccd is actually a fake one that is not really on the disk. You can solve this problem by writing it back explicitly, as in: &prompt.root; disklabel ccd0 > /tmp/disklabel.tmp &prompt.root; disklabel -Rr ccd0 /tmp/disklabel.tmp &prompt.root; disklabel -e ccd0 (this will work now) Can I mount other foreign filesystems under FreeBSD? Digital UNIX UFS CDROMs can be mounted directly on FreeBSD. Mounting disk partitions from Digital UNIX and other systems that support UFS may be more complex, depending on the details of the disk partitioning for the operating system in question. &linux; FreeBSD supports ext2fs partitions. See &man.mount.ext2fs.8; for more information. &windowsnt; FreeBSD includes a read-only NTFS driver. For more information, see &man.mount.ntfs.8;. Any other information on this subject would be appreciated. How do I mount a secondary DOS partition? The secondary DOS partitions are found after ALL the primary partitions. For example, if you have an E partition as the second DOS partition on the second SCSI drive, you need to create the special files for slice 5 in /dev, then mount /dev/da1s5: &prompt.root; cd /dev &prompt.root; sh MAKEDEV da1s5 &prompt.root; mount -t msdos /dev/da1s5 /dos/e You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled. Is there a cryptographic filesystem for &os;? Yes; see the security/cfs port. How can I use the &windowsnt; loader to boot FreeBSD? The general idea is that you copy the first sector of your native root FreeBSD partition into a file in the DOS/&windowsnt; partition. Assuming you name that file something like c:\bootsect.bsd (inspired by c:\bootsect.dos), you can then edit the c:\boot.ini file to come up with something like this: [boot loader] timeout=30 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS [operating systems] multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" C:\BOOTSECT.BSD="FreeBSD" C:\="DOS" If FreeBSD is installed on the same disk as the &windowsnt; boot partition simply copy /boot/boot1 to C:\BOOTSECT.BSD. However, if FreeBSD is installed on a different disk /boot/boot1 will not work, /boot/boot0 is needed. /boot/boot0 needs to be installed using sysinstall by selecting the FreeBSD boot manager on the screen which asks if you wish to use a boot manager. This is because /boot/boot0 has the partition table area filled with NULL characters but sysinstall copies the partition table before copying /boot/boot0 to the MBR. Do not simply copy /boot/boot0 instead of /boot/boot1; you will overwrite your partition table and render your computer un-bootable! When the FreeBSD boot manager runs it records the last OS booted by setting the active flag on the partition table entry for that OS and then writes the whole 512-bytes of itself back to the MBR so if you just copy /boot/boot0 to C:\BOOTSECT.BSD then it writes an empty partition table, with the active flag set on one entry, to the MBR. How do I boot FreeBSD and &linux; from LILO? If you have FreeBSD and &linux; on the same disk, just follow LILO's installation instructions for booting a non-&linux; operating system. Very briefly, these are: Boot &linux;, and add the following lines to /etc/lilo.conf: other=/dev/hda2 table=/dev/hda label=FreeBSD (the above assumes that your FreeBSD slice is known to &linux; as /dev/hda2; tailor to suit your setup). Then, run lilo as root and you should be done. If FreeBSD resides on another disk, you need to add loader=/boot/chain.b to the LILO entry. For example: other=/dev/dab4 table=/dev/dab loader=/boot/chain.b label=FreeBSD In some cases you may need to specify the BIOS drive number to the FreeBSD boot loader to successfully boot off the second disk. For example, if your FreeBSD SCSI disk is probed by BIOS as BIOS disk 1, at the FreeBSD boot loader prompt you need to specify: Boot: 1:da(0,a)/kernel On FreeBSD 2.2.5 and later, you can configure &man.boot.8; to automatically do this for you at boot time. The &linux;+FreeBSD mini-HOWTO is a good reference for FreeBSD and &linux; interoperability issues. How do I boot FreeBSD and &linux; using BootEasy? Install LILO at the start of your &linux; boot partition instead of in the Master Boot Record. You can then boot LILO from BootEasy. If you are running &windows; 95 and &linux; this is recommended anyway, to make it simpler to get &linux; booting again if you should need to reinstall &windows; 95 (which is a Jealous Operating System, and will bear no other Operating Systems in the Master Boot Record). How do I change the boot prompt from ??? to something more meaningful? You can not do that with the standard boot manager without rewriting it. There are a number of other boot managers in the sysutils ports category that provide this functionality. I have a new removable drive, how do I use it? Whether it is a removable drive like a &iomegazip; or an EZ drive (or even a floppy, if you want to use it that way), or a new hard disk, once it is installed and recognized by the system, and you have your cartridge/floppy/whatever slotted in, things are pretty much the same for all devices. (this section is based on Mark Mayo's ZIP FAQ) If it is a ZIP drive or a floppy, you have already got a DOS filesystem on it, you can use a command like this: &prompt.root; mount -t msdos /dev/fd0c /floppy if it is a floppy, or this: &prompt.root; mount -t msdos /dev/da2s4 /zip for a ZIP disk with the factory configuration. For other disks, see how they are laid out using &man.fdisk.8; or &man.sysinstall.8;. The rest of the examples will be for a ZIP drive on da2, the third SCSI disk. Unless it is a floppy, or a removable you plan on sharing with other people, it is probably a better idea to stick a BSD filesystem on it. You will get long filename support, at least a 2X improvement in performance, and a lot more stability. First, you need to redo the DOS-level partitions/filesystems. You can either use &man.fdisk.8; or /stand/sysinstall, or for a small drive that you do not want to bother with multiple operating system support on, just blow away the whole FAT partition table (slices) and just use the BSD partitioning: &prompt.root; dd if=/dev/zero of=/dev/rda2 count=2 &prompt.root; disklabel -Brw da2 auto You can use disklabel or /stand/sysinstall to create multiple BSD partitions. You will certainly want to do this if you are adding swap space on a fixed disk, but it is probably irrelevant on a removable drive like a ZIP. Finally, create a new filesystem, this one is on our ZIP drive using the whole disk: &prompt.root; newfs /dev/rda2c and mount it: &prompt.root; mount /dev/da2c /zip and it is probably a good idea to add a line like this to /etc/fstab (see &man.fstab.5;) so you can just type mount /zip in the future: /dev/da2c /zip ffs rw,noauto 0 0 Why do I get Incorrect super block when mounting a CDROM? You have to tell &man.mount.8; the type of the device that you want to mount. This is described in the Handbook section on optical media, specifically the section Using Data CDs. Why do I get Device not configured when mounting a CDROM? This generally means that there is no CDROM in the CDROM drive, or the drive is not visible on the bus. Please see the Using Data CDs section of the Handbook for a detailed discussion of this issue. Why do all non-English characters in filenames show up as ? on my CDs when mounted in FreeBSD? Your CDROM probably uses the Joliet extension for storing information about files and directories. This is discussed in the Handbook chapter on creating and using CDROMs, specifically the section on Using Data CDROMs. I burned a CD under FreeBSD and now I can not read it under any other operating system. Why? You most likely burned a raw file to your CD, rather than creating an ISO 9660 filesystem. Take a look at the Handbook chapter on creating CDROMs, particularly the section on burning raw data CDs. How can I create an image of a data CD? This is discussed in the Handbook section on duplicating data CDs. For more on working with CDROMs, see the Creating CDs Section in the Storage chapter in the Handbook. Why can I not mount an audio CD? If you try to mount an audio CD, you will get an error like cd9660: /dev/acd0c: Invalid argument. This is because mount only works on filesystems. Audio CDs do not have filesystems; they just have data. You need a program that reads audio CDs, such as the audio/xmcd port. How do I mount a multi-session CD? By default, &man.mount.8; will attempt to mount the last data track (session) of a CD. If you would like to load an earlier session, you must use the command line argument. Please see &man.mount.cd9660.8; for specific examples. How do I let ordinary users mount floppies, CDROMs and other removable media? Ordinary users can be permitted to mount devices. Here is how: As root set the sysctl variable vfs.usermount to 1. &prompt.root; sysctl -w vfs.usermount=1 As root assign the appropriate permissions to the block device associated with the removable media. For example, to allow users to mount the first floppy drive, use: &prompt.root; chmod 666 /dev/fd0 To allow users in the group operator to mount the CDROM drive, use: &prompt.root; chgrp operator /dev/cd0c &prompt.root; chmod 640 /dev/cd0c Finally, add the line vfs.usermount=1 to the file /etc/sysctl.conf so that it is reset at system boot time. All users can now mount the floppy /dev/fd0 onto a directory that they own: &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t msdos /dev/fd0 ~/my-mount-point Users in group operator can now mount the CDROM /dev/cd0c onto a directory that they own: &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t cd9660 /dev/cd0c ~/my-mount-point Unmounting the device is simple: &prompt.user; umount ~/my-mount-point Enabling vfs.usermount, however, has negative security implications. A better way to access &ms-dos; formatted media is to use the mtools package in the ports collection. The du and df commands show different amounts of disk space available. What is going on? You need to understand what du and df really do. du goes through the directory tree, measures how large each file is, and presents the totals. df just asks the filesystem how much space it has left. They seem to be the same thing, but a file without a directory entry will affect df but not du. When a program is using a file, and you delete the file, the file is not really removed from the filesystem until the program stops using it. The file is immediately deleted from the directory listing, however. You can see this easily enough with a program such as more. Assume you have a file large enough that its presence affects the output of du and df. (Since disks can be so large today, this might be a very large file!) If you delete this file while using more on it, more does not immediately choke and complain that it cannot view the file. The entry is simply removed from the directory so no other program or user can access it. du shows that it is gone — it has walked the directory tree and the file is not listed. df shows that it is still there, as the filesystem knows that more is still using that space. Once you end the more session, du and df will agree. Note that Soft Updates can delay the freeing of disk space; you might need to wait up to 30 seconds for the change to be visible! This situation is common on web servers. Many people set up a FreeBSD web server and forget to rotate the log files. The access log fills up /var. The new administrator deletes the file, but the system still complains that the partition is full. Stopping and restarting the web server program would free the file, allowing the system to release the disk space. To prevent this from happening, set up &man.newsyslog.8;. How can I add more swap space? In the Configuration and Tuning section of the Handbook, you will find a section describing how to do this. How is it possible for a partition to be more than 100% full? A portion of each UFS partition (8%, by default) is reserved for use by the operating system and the root user. &man.df.1; does not count that space when calculating the Capacity column, so it can exceed 100%. Also, you'll notice that the Blocks column is always greater than the sum of the Used and Avail columns, usually by a factor of 8%. For more details, look up the option in &man.tunefs.8;. System Administration Where are the system start-up configuration files? The primary configuration file is /etc/defaults/rc.conf (see &man.rc.conf.5;) System startup scripts such as /etc/rc and /etc/rc.d (see &man.rc.8;) just include this file. Do not edit this file! Instead, if there is any entry in /etc/defaults/rc.conf that you want to change, you should copy the line into /etc/rc.conf and change it there. For example, if you wish to start named, the included DNS server, all you need to do is: &prompt.root; echo named_enable="YES" >> /etc/rc.conf To start up local services, place shell scripts in the /usr/local/etc/rc.d directory. These shell scripts should be set executable, and end with a .sh. How do I add a user easily? Use the &man.adduser.8; command, or the &man.pw.8; command for more complicated situations. To remove the user, use the &man.rmuser.8; command or, if necessary, &man.pw.8;. Why do I keep getting messages like root: not found after editing my crontab file? This is normally caused by editing the system crontab (/etc/crontab) and then using &man.crontab.1; to install it: &prompt.root; crontab /etc/crontab This is not the correct way to do things. The system crontab has a different format to the per-user crontabs which &man.crontab.1; updates (the &man.crontab.5; manual page explains the differences in more detail). If this is what you did, the extra crontab is simply a copy of /etc/crontab in the wrong format it. Delete it with the command: &prompt.root; crontab -r Next time, when you edit /etc/crontab, you should not do anything to inform &man.cron.8; of the changes, since it will notice them automatically. If you want something to be run once per day, week, or month, it is probably better to add shell scripts /usr/local/etc/periodic, and let the &man.periodic.8; command run from the system cron schedule it with the other periodic system tasks. The actual reason for the error is that the system crontab has an extra field, specifying which user to run the command as. In the default system crontab provided with FreeBSD, this is root for all entries. When this crontab is used as the root user's crontab (which is not the same as the system crontab), &man.cron.8; assumes the string root is the first word of the command to execute, but no such command exists. Why do I get the error, you are not in the correct group to su root when I try to su to root? This is a security feature. In order to su to root (or any other account with superuser privileges), you must be in the wheel group. If this feature were not there, anybody with an account on a system who also found out root's password would be able to gain superuser level access to the system. With this feature, this is not strictly true; &man.su.1; will prevent them from even trying to enter the password if they are not in wheel. To allow someone to su to root, simply put them in the wheel group. I made a mistake in rc.conf, or another startup file, and now I cannot edit it because the filesystem is read-only. What should I do? When you get the prompt to enter the shell pathname, simply press ENTER, and run mount / to re-mount the root filesystem in read/write mode. You may also need to run mount -a -t ufs to mount the filesystem where your favourite editor is defined. If your favourite editor is on a network filesystem, you will need to either configure the network manually before you can mount network filesystems, or use an editor which resides on a local filesystem, such as &man.ed.1;. If you intend to use a full screen editor such as &man.vi.1; or &man.emacs.1;, you may also need to run export TERM=cons25 so that these editors can load the correct data from the &man.termcap.5; database. Once you have performed these steps, you can edit /etc/rc.conf as you usually would to fix the syntax error. The error message displayed immediately after the kernel boot messages should tell you the number of the line in the file which is at fault. Why am I having trouble setting up my printer? Please have a look at the Handbook entry on printing. It should cover most of your problem. See the Handbook entry on printing. Some printers require a host-based driver to do any kind of printing. These so-called WinPrinters are not natively supported by FreeBSD. If your printer does not work in DOS or &windowsnt; 4.0, it is probably a WinPrinter. Your only hope of getting one of these to work is to check if the print/pnm2ppa port supports it. How can I correct the keyboard mappings for my system? Please see the Handbook section on using localization, specifically the section on console setup. Why do I get messages like: unknown: <PNP0303> can't assign resources on boot? The following is an excerpt from a post to the freebsd-current mailing list.
&a.wollman;, 24 April 2001 The can't assign resources messages indicate that the devices are legacy ISA devices for which a non-PnP-aware driver is compiled into the kernel. These include devices such as keyboard controllers, the programmable interrupt controller chip, and several other bits of standard infrastructure. The resources cannot be assigned because there is already a driver using those addresses.
Why can I not get user quotas to work properly? Do not turn on quotas on /, Put the quota file on the filesystem that the quotas are to be enforced on. ie: Filesystem Quota file /usr /usr/admin/quotas /home /home/admin/quotas … … Does FreeBSD support System V IPC primitives? Yes, FreeBSD supports System V-style IPC, including shared memory, messages and semaphores. Versions of FreeBSD later than 3.2 support System V IPC in the GENERIC kernel. In earlier versions of FreeBSD, enable this support by adding the following lines to your kernel config. options SYSVSHM # enable shared memory options SYSVSEM # enable for semaphores options SYSVMSG # enable for messaging Recompile and install your kernel. What other mail-server software can I use, instead of Sendmail? Sendmail is the default mail-server software for FreeBSD, but you can easily replace it with one of the other MTA (for instance, an MTA installed from the ports). There are various alternative MTA's in the ports tree already, with mail/exim, mail/postfix, mail/qmail, mail/zmailer, being some of the most popular choices. Diversity is nice, and the fact that you have many different mail-servers to chose from is considered a good thing; therefore try to avoid asking questions like Is Sendmail better than Qmail? in the mailing lists. If you do feel like asking, first check the mailing list archives. The advantages and disadvantages of each and every one of the available MTA's have already been discussed a few times. I have forgotten the root password! What do I do? Do not Panic! Simply restart the system, type boot -s at the Boot: prompt (just -s for FreeBSD releases before 3.2) to enter Single User mode. At the question about the shell to use, hit ENTER. You will be dropped to a &prompt.root; prompt. Enter mount -u / to remount your root filesystem read/write, then run mount -a to remount all the filesystems. Run passwd root to change the root password then run &man.exit.1; to continue booting. How do I keep ControlAltDelete from rebooting the system? If you are using syscons (the default console driver) build and install a new kernel with the following option. options SC_DISABLE_REBOOT in the configuration file. If you use the PCVT console driver, use the following kernel configuration line instead. options PCVT_CTRL_ALT_DEL How do I reformat DOS text files to &unix; ones? Simply use this perl command: &prompt.user; perl -i.bak -npe 's/\r\n/\n/g' file ... file is the file(s) to process. The modification is done in-place, with the original file stored with a .bak extension. Alternatively you can use the &man.tr.1; command: &prompt.user; tr -d '\r' < dos-text-file > unix-file dos-text-file is the file containing DOS text while unix-file will contain the converted output. This can be quite a bit faster than using perl. How do I kill processes by name? Use &man.killall.1;. Why is su bugging me about not being in root's ACL? The error comes from the Kerberos distributed authentication system. The problem is not fatal but annoying. You can either run su with the -K option, or uninstall Kerberos as described in the next question. How do I uninstall Kerberos? To remove Kerberos from the system, reinstall the bin distribution for the release you are running. If you have the CDROM, you can mount the cd (we will assume on /cdrom) and run &prompt.root; cd /cdrom/bin &prompt.root; ./install.sh Alternately, you can remove all MAKE_KERBEROS options from /etc/make.conf and rebuild world. What happened to /dev/MAKEDEV? FreeBSD 5.X uses the &man.devfs.8; device-on-demand system. Device drivers automatically create new device nodes as they are needed, obsoleting /dev/MAKEDEV. If you are running FreeBSD 4.X or earlier and /dev/MAKEDEV is missing, then you really do have a problem. Grab a copy from the system source code, probably in /usr/src/etc/MAKEDEV. How do I add pseudoterminals to the system? If you have lots of telnet, ssh, X, or screen users, you will probably run out of pseudoterminals. Here is how to add more: Build and install a new kernel with the line pseudo-device pty 256 in the configuration file. Run the commands &prompt.root; cd /dev &prompt.root; sh MAKEDEV pty{1,2,3,4,5,6,7} to make 256 device nodes for the new terminals. Edit /etc/ttys and add lines for each of the 256 terminals. They should match the form of the existing entries, i.e. they look like ttyqc none network The order of the letter designations is tty[pqrsPQRS][0-9a-v], using a regular expression. Reboot the system with the new kernel and you are ready to go. Why can I not create the snd0 device? There is no snd device. The name is used as a shorthand for the various devices that make up the FreeBSD sound driver, such as mixer, sequencer, and dsp. To create these devices you should &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd0 You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled. How do I re-read /etc/rc.conf and re-start /etc/rc without a reboot? Go into single user mode and then back to multi user mode. On the console do: &prompt.root; shutdown now (Note: without -r or -h) &prompt.root; return &prompt.root; exit I tried to update my system to the latest -STABLE, but got -RC or -PRERELEASE! What is going on? Short answer: it is just a name. RC stands for Release Candidate. It signifies that a release is imminent. In FreeBSD, -PRERELEASE is typically synonymous with the code freeze before a release. (For some releases, the -BETA label was used in the same way as -PRERELEASE.) Long answer: FreeBSD derives its releases from one of two places. Major, dot-zero, releases, such as 3.0-RELEASE and 4.0-RELEASE, are branched from the head of the development stream, commonly referred to as -CURRENT. Minor releases, such as 3.1-RELEASE or 4.2-RELEASE, have been snapshots of the active -STABLE branch. Starting with 4.3-RELEASE, each release also now has its own branch which can be tracked by people requiring an extremely conservative rate of development (typically only security advisories). When a release is about to be made, the branch from which it will be derived from has to undergo a certain process. Part of this process is a code freeze. When a code freeze is initiated, the name of the branch is changed to reflect that it is about to become a release. For example, if the branch used to be called 4.5-STABLE, its name will be changed to 4.6-PRERELEASE to signify the code freeze and signify that extra pre-release testing should be happening. Bug fixes can still be committed to be part of the release. When the source code is in shape for the release the name will be changed to 4.6-RC to signify that a release is about to be made from it. Once in the RC stage, only the most critical bugs found can be fixed. Once the release (4.6-RELEASE in this example) and release branch have been made, the branch will be renamed to 4.6-STABLE. For more information on version numbers and the various CVS branches, refer to the Release Engineering article. I tried to install a new kernel, and the chflags failed. How do I get around this? Short answer: You are probably at security level greater than 0. Reboot directly to single user mode to install the kernel. Long answer: FreeBSD disallows changing system flags at security levels greater than 0. You can check your security level with the command: &prompt.root; sysctl kern.securelevel You cannot lower the security level; you have to boot to single mode to install the kernel, or change the security level in /etc/rc.conf then reboot. See the &man.init.8; manual page for details on securelevel, and see /etc/defaults/rc.conf and the &man.rc.conf.5; manual page for more information on rc.conf. I cannot change the time on my system by more than one second! How do I get around this? Short answer: You are probably at security level greater than 1. Reboot directly to single user mode to change the date. Long answer: FreeBSD disallows changing the time by more that one second at security levels greater than 1. You can check your security level with the command: &prompt.root; sysctl kern.securelevel You cannot lower the security level; you have to boot to single mode to change the date, or change the security level in /etc/rc.conf then reboot. See the &man.init.8; manual page for details on securelevel, and see /etc/defaults/rc.conf and the &man.rc.conf.5; manual page for more information on rc.conf. Why is rpc.statd using 256 megabytes of memory? No, there is no memory leak, and it is not using 256 Mbytes of memory. It simply likes to (i.e., always does) map an obscene amount of memory into its address space for convenience. There is nothing terribly wrong with this from a technical standpoint; it just throws off things like &man.top.1; and &man.ps.1;. &man.rpc.statd.8; maps its status file (resident on /var) into its address space; to save worrying about remapping it later when it needs to grow, it maps it with a generous size. This is very evident from the source code, where one can see that the length argument to &man.mmap.2; is 0x10000000, or one sixteenth of the address space on an IA32, or exactly 256MB. Why can I not unset the schg file flag? You are running at an elevated (i.e., greater than 0) securelevel. Lower the securelevel and try again. For more information, see the FAQ entry on securelevel and the &man.init.8; manual page. Why does SSH authentication through .shosts not work by default in recent versions of FreeBSD? The reason why .shosts authentication does not work by default in more recent versions of FreeBSD is because &man.ssh.1; is not installed suid root by default. To fix this, you can do one of the following: As a permanent fix, set ENABLE_SUID_SSH to true in /etc/make.conf and rebuild ssh (or run make world). As a temporary fix, change the mode on /usr/bin/ssh to 4555 by running chmod 4555 /usr/bin/ssh as root. Then add ENABLE_SUID_SSH= true to /etc/make.conf so the change takes effect the next time make world is run. What is vnlru? vnlru flushes and frees vnodes when the system hits the kern.maxvnodes limit. This kernel thread sits mostly idle, and only activates if you have a huge amount of RAM and are accessing tens of thousands of tiny files. What do the various memory states displayed by top mean? Active: pages recently statistically used. Inactive: pages recently statistically unused. Cache: (most often) pages that have percolated from inactive to a status where they maintain their data, but can often be immediately reused (either with their old association, or reused with a new association.) There can be certain immediate transition from active to 'cache' state if the page is known to be clean (unmodified), but that transition is a matter of policy, depending upon the algorithm choice of the VM system maintainer. Free: pages without data content, and can be immediately used in certain circumstances where cache pages might be ineligible. Free pages can be reused at interrupt or process state. Wired: pages that are fixed into memory, usually for kernel purposes, but also sometimes for special use in processes. Pages are most often written to disk (sort of a VM sync) when they are in the 'inactive' state, but 'active' pages can also be synced (but requires the availability of certain CPU features.) This depends upon the CPU tracking of the 'modified' bit being available, and in certain situations there can be an advantage for a block of VM pages to be synced, whether they are active or inactive. In most common cases, it is best to think of the 'inactive' queue to be a queue of relatively unused pages that might or might not be in the process of being written to disk. 'Cached' pages are already 'synced', not mapped, but available for immediate process use with their old association or with a new association. Free pages are available at interrupt level, but cached or free pages can be used at process state for reuse. Cache pages aren't adequately locked to be available at interrupt level. There are some other flags (e.g. Busy flag or busy count) that might modify some of the rules that I described. How much free memory is available? There are a couple of kinds of free memory. One kind is the amount of memory immediately available without paging anything else out. That is approximately the size of cache queue + size of free queue (with a derating factor, depending upon system tuning.) Another kind of free memory is the total amount of VM space. That can be complex, but is dependent upon the amount of swap space and memory. Other kinds of free memory descriptions are also possible, but it is relatively useless to define these, but rather it is important to make sure that the paging rate is kept low, and to avoid running out of swap space. What is /var/empty? I can not delete it! /var/empty is a directory that the &man.sshd.8; program uses when performing privilege separation. The /var/empty directory is empty, owned by root and has the schg flag set. Although it is not recommended to delete this directory, to do so you will need to unset the schg flag first. See the &man.chflags.1; manual page for more information (and bear in mind the answer to the question on unsetting the schg flag). The X Window System and Virtual Consoles What is the X Window System? The X Window System is the most widely available windowing system capable of running on &unix; or &unix; like systems, including &os;. X.org administers the X protocol standards. The current release of the specification is 11.6, so you will often see references shortened to X11R6 or even just X11. Many implementations are available for different architectures and operating systems. For instance, an implementation of the server-side code is properly known as an X server. Which X implementations are available for &os;? Historically, the default implementation of X on &os; has been &xfree86; which is maintained by The XFree86 Project, Inc. This software was installed by default on &os; versions up until 4.10 and 5.2. Although X.org itself maintained an implementation during that time period, it was basically only provided as a reference platform, as it had suffered greatly from bitrot over the years. However, early in 2004, some XFree86 developers left that project over issues including the pace of code changes, future directions, and interpersonal conflicts, and are now contributing code directly to X.org instead. At that time, X.org updated its source tree to the last &xfree86; release before its subsequent licensing change (XFree86 version 4.3.99.903), incorporated many changes that had previously been maintained separately, and has released that software as X11R6.7.0. A separate but related project, freedesktop.org (or fd.o for short), is working on rearchitecting the original &xfree86; code to offload more work onto the graphics cards (with the goal of increased performance) and make it more modular (with the goal of increased maintainability, and thus faster releases as well as easier configuration). X.org intends to incorporate the freedesktop.org changes in its future releases. As of July 2004, in &os.current;, &xfree86; has been replaced with x.org as the default implementation. The &xfree86; ports (x11/XFree86-4 and subports) remain in the ports collection and are still the default for &os.stable;. The above describes the default X implementation installed. It is still possible to install either implementation by following the instructions in the entry for 20040723 in /usr/ports/UPDATING. It is not currently possible to mix-and-match pieces of each implementation; one must choose one or the other. The following paragraphs refer to the &xfree86; implementation, but most should also be applicable to the x.org implementation as well. While the default configuration filename for the x.org implementation is xorg.conf, it will search for XF86Config if it cannot find it. Will my existing applications run with the X.org suite? The X.org software is written to the same X11R6 specification that &xfree86; is, so basic applications should work unchanged. A few lesser-used protocols have been deprecated (XIE, PEX, and lbxproxy), but in the first two cases, the &os; port of &xfree86; did not support them either. Why did the X projects split, anyway? The answer to this question is outside the scope of this FAQ. Note that there are voluminous postings in various mailing list archives on the Internet; please use your favorite search engine to investigate the history instead of asking this question on the &os; mailing lists. It may even be the case that only the participants will ever know for certain. Why did &os; choose to go with the X.org ports by default? The X.org developers claim that their goal is to release more often and incorporate new features more quickly. If they are able to do so, this will be very attractive. Also, their software still uses the traditional X license, while &xfree86; is now using their modified one. This decision is still controversial. Only time will tell which implementation proves technically superior. Each &os; user should decide which they prefer. I want to run X, how do I go about it? The easiest way is to simply specify that you want to run X during the installation process. Then read and follow the documentation on the xf86config tool, which assists you in configuring &xfree86; for your particular graphics card/mouse/etc. You may also wish to investigate the Xaccel server. See the section on Xi Graphics or Metro Link for more details. I tried to run X, but I get an KDENABIO failed (Operation not permitted) error when I type startx. What do I do now? Your system is probably running at a raised securelevel. It is not possible to start X at a raised securelevel. To see why, look at the &man.init.8; manual page. So the question is what else you should do instead, and you basically have two choices: set your securelevel back down to zero (usually from /etc/rc.conf), or run &man.xdm.1; at boot time (before the securelevel is raised). See for more information about running &man.xdm.1; at boot time. Why does my mouse not work with X? If you are using syscons (the default console driver), you can configure FreeBSD to support a mouse pointer on each virtual screen. In order to avoid conflicting with X, syscons supports a virtual device called /dev/sysmouse. All mouse events received from the real mouse device are written to the sysmouse device via moused. If you wish to use your mouse on one or more virtual consoles, and use X, see and set up moused. Then edit /etc/XF86Config and make sure you have the following lines. Section Pointer Protocol "SysMouse" Device "/dev/sysmouse" ..... The above example is for &xfree86; 3.3.2 or later. For earlier versions, the Protocol should be MouseSystems. Some people prefer to use /dev/mouse under X. To make this work, /dev/mouse should be linked to /dev/sysmouse (see &man.sysmouse.4;): &prompt.root; cd /dev &prompt.root; rm -f mouse &prompt.root; ln -s sysmouse mouse My mouse has a fancy wheel. Can I use it in X? Yes. But you need to customize X client programs. See Colas Nahaboo's web page (http://www.inria.fr/koala/colas/mouse-wheel-scroll/) . If you want to use the imwheel program, just follow these simple steps. Translate the Wheel Events The imwheel program works by translating mouse button 4 and mouse button 5 events into key events. Thus, you have to get the mouse driver to translate mouse wheel events to button 4 and 5 events. There are two ways of doing this, the first way is to have &man.moused.8; do the translation. The second way is for the X server itself to do the event translation. Using &man.moused.8; to Translate Wheel Events To have &man.moused.8; perform the event translations, simply add to the command line used to start &man.moused.8;. For example, if you normally start &man.moused.8; via moused -p /dev/psm0 you would start it by entering moused -p /dev/psm0 -z 4 instead. If you start &man.moused.8; automatically during bootup via /etc/rc.conf, you can simply add to the moused_flags variable in /etc/rc.conf. You now need to tell X that you have a 5 button mouse. To do this, simply add the line Buttons 5 to the Pointer section of /etc/XF86Config. For example, you might have the following Pointer section in /etc/XF86Config. <quote>Pointer</quote> Section for Wheeled Mouse in &xfree86; 3.3.x series XF86Config with moused Translation Section "Pointer" Protocol "SysMouse" Device "/dev/sysmouse" Buttons 5 EndSection <quote>InputDevice</quote> Section for Wheeled Mouse in &xfree86; 4.x series XF86Config with X Server Translation Section "InputDevice" Identifier "Mouse1" Driver "mouse" Option "Protocol" "auto" Option "Device" "/dev/sysmouse" Option "Buttons" "5" EndSection <quote>.emacs</quote> example for naive page scrolling with Wheeled Mouse ;; wheel mouse (global-set-key [mouse-4] 'scroll-down) (global-set-key [mouse-5] 'scroll-up) Using Your X Server to Translate the Wheel Events If you are not running &man.moused.8;, or if you do not want &man.moused.8; to translate your wheel events, you can have the X server do the event translation instead. This requires a couple of modifications to your /etc/XF86Config file. First, you need to choose the proper protocol for your mouse. Most wheeled mice use the &intellimouse; protocol. However, &xfree86; does support other protocols, such as MouseManPlusPS/2 for the Logitech MouseMan+ mice. Once you have chosen the protocol you will use, you need to add a Protocol line to the Pointer section. Secondly, you need to tell the X server to remap wheel scroll events to mouse buttons 4 and 5. This is done with the ZAxisMapping option. For example, if you are not using &man.moused.8;, and you have an &intellimouse; attached to the PS/2 mouse port you would use the following in /etc/XF86Config. <quote>Pointer</quote> Section for Wheeled Mouse in <filename>XF86Config</filename> with X Server Translation Section "Pointer" Protocol "IntelliMouse" Device "/dev/psm0" ZAxisMapping 4 5 EndSection <quote>InputDevice</quote> Section for Wheeled Mouse in &xfree86; 4.x series XF86Config with X Server Translation Section "InputDevice" Identifier "Mouse1" Driver "mouse" Option "Protocol" "auto" Option "Device" "/dev/psm0" Option "ZAxisMapping" "4 5" EndSection <quote>.emacs</quote> example for naive page scrolling with Wheeled Mouse ;; wheel mouse (global-set-key [mouse-4] 'scroll-down) (global-set-key [mouse-5] 'scroll-up) Install imwheel Next, install imwheel from the Ports collection. It can be found in the x11 category. This program will map the wheel events from your mouse into keyboard events. For example, it might send Page Up to a program when you scroll the wheel forwards. Imwheel uses a configuration file to map the wheel events to key presses so that it can send different keys to different applications. The default imwheel configuration file is installed in /usr/X11R6/etc/imwheelrc. You can copy it to ~/.imwheelrc and then edit it if you wish to customize imwheel's configuration. The format of the configuration file is documented in &man.imwheel.1;. Configure Emacs to Work with Imwheel (optional) If you use emacs or XEmacs, then you need to add a small section to your ~/.emacs file. For emacs, add the following: <application>Emacs</application> Configuration for <application>Imwheel</application> ;;; For imwheel (setq imwheel-scroll-interval 3) (defun imwheel-scroll-down-some-lines () (interactive) (scroll-down imwheel-scroll-interval)) (defun imwheel-scroll-up-some-lines () (interactive) (scroll-up imwheel-scroll-interval)) (global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines) (global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines) ;;; end imwheel section For XEmacs, add the following to your ~/.emacs file instead: <application>XEmacs</application> Configuration for <application>Imwheel</application> ;;; For imwheel (mwheel-install) (setq mwheel-follow-mouse t) ;;; end imwheel section Run Imwheel You can just type imwheel in an xterm to start it up once it is installed. It will background itself and take effect immediately. If you want to always use imwheel, simply add it to your .xinitrc or .xsession file. You can safely ignore any warnings imwheel displays about PID files. Those warnings only apply to the &linux; version of imwheel. How do I use remote X displays? For security reasons, the default setting is to not allow a machine to remotely open a window. To enable this feature, simply start X with the optional argument: &prompt.user; startx -listen_tcp Why do X Window menus and dialog boxes not work right? Try turning off the Num Lock key. If your Num Lock key is on by default at boot-time, you may add the following line in the Keyboard section of the XF86Config file. # Let the server do the NumLock processing. This should only be # required when using pre-R6 clients ServerNumLock What is a virtual console and how do I make more? Virtual consoles, put simply, enable you to have several simultaneous sessions on the same machine without doing anything complicated like setting up a network or running X. When the system starts, it will display a login prompt on the monitor after displaying all the boot messages. You can then type in your login name and password and start working (or playing!) on the first virtual console. At some point, you will probably wish to start another session, perhaps to look at documentation for a program you are running or to read your mail while waiting for an FTP transfer to finish. Just do AltF2 (hold down the Alt key and press the F2 key), and you will find a login prompt waiting for you on the second virtual console! When you want to go back to the original session, do AltF1. The default FreeBSD installation has three virtual consoles enabled (8 starting with 3.3-RELEASE), and AltF1, AltF2, and AltF3 will switch between these virtual consoles. To enable more of them, edit /etc/ttys (see &man.ttys.5;) and add entries for ttyv4 to ttyvc after the comment on Virtual terminals: # Edit the existing entry for ttyv3 in /etc/ttys and change # "off" to "on". ttyv3 "/usr/libexec/getty Pc" cons25 on secure ttyv4 "/usr/libexec/getty Pc" cons25 on secure ttyv5 "/usr/libexec/getty Pc" cons25 on secure ttyv6 "/usr/libexec/getty Pc" cons25 on secure ttyv7 "/usr/libexec/getty Pc" cons25 on secure ttyv8 "/usr/libexec/getty Pc" cons25 on secure ttyv9 "/usr/libexec/getty Pc" cons25 on secure ttyva "/usr/libexec/getty Pc" cons25 on secure ttyvb "/usr/libexec/getty Pc" cons25 on secure Use as many or as few as you want. The more virtual terminals you have, the more resources that are used; this can be important if you have 8MB RAM or less. You may also want to change the secure to insecure. If you want to run an X server you must leave at least one virtual terminal unused (or turned off) for it to use. That is to say that if you want to have a login prompt pop up for all twelve of your Alt-function keys, you are out of luck - you can only do this for eleven of them if you also want to run an X server on the same machine. The easiest way to disable a console is by turning it off. For example, if you had the full 12 terminal allocation mentioned above and you wanted to run X, you would change settings for virtual terminal 12 from: ttyvb "/usr/libexec/getty Pc" cons25 on secure to: ttyvb "/usr/libexec/getty Pc" cons25 off secure If your keyboard has only ten function keys, you would end up with: ttyv9 "/usr/libexec/getty Pc" cons25 off secure ttyva "/usr/libexec/getty Pc" cons25 off secure ttyvb "/usr/libexec/getty Pc" cons25 off secure (You could also just delete these lines.) Once you have edited /etc/ttys, the next step is to make sure that you have enough virtual terminal devices. The easiest way to do this is: &prompt.root; cd /dev &prompt.root; sh MAKEDEV vty12 On FreeBSD 5.X you do not have to create devices manually if you are using DEVFS, since the proper device nodes will be automatically created under /dev. Next, the easiest (and cleanest) way to activate the virtual consoles is to reboot. However, if you really do not want to reboot, you can just shut down the X Window system and execute (as root): &prompt.root; kill -HUP 1 It is imperative that you completely shut down X Window if it is running, before running this command. If you do not, your system will probably appear to hang/lock up after executing the kill command. How do I access the virtual consoles from X? Use Ctrl Alt Fn to switch back to a virtual console. Ctrl Alt F1 would return you to the first virtual console. Once you are back to a text console, you can then use Alt Fn as normal to move between them. To return to the X session, you must switch to the virtual console running X. If you invoked X from the command line, (e.g., using startx) then the X session will attach to the next unused virtual console, not the text console from which it was invoked. If you have eight active virtual terminals then X will be running on the ninth, and you would use Alt F9 to return. How do I start XDM on boot? There are two schools of thought on how to start xdm. One school starts xdm from /etc/ttys (see &man.ttys.5;) using the supplied example, while the other simply runs xdm from rc.local (see &man.rc.8;) or from a X.sh script in /usr/local/etc/rc.d. Both are equally valid, and one may work in situations where the other does not. In both cases the result is the same: X will pop up a graphical login: prompt. The ttys method has the advantage of documenting which vty X will start on and passing the responsibility of restarting the X server on logout to init. The rc.local method makes it easy to kill xdm if there is a problem starting the X server. If loaded from rc.local, xdm should be started without any arguments (i.e., as a daemon). xdm must start AFTER getty runs, or else getty and xdm will conflict, locking out the console. The best way around this is to have the script sleep 10 seconds or so then launch xdm. If you are to start xdm from /etc/ttys, there still is a chance of conflict between xdm and &man.getty.8;. One way to avoid this is to add the vt number in the /usr/X11R6/lib/X11/xdm/Xservers file. :0 local /usr/X11R6/bin/X vt4 The above example will direct the X server to run in /dev/ttyv3. Note the number is offset by one. The X server counts the vty from one, whereas the FreeBSD kernel numbers the vty from zero. Why do I get Couldn't open console when I run xconsole? If you start X with startx, the permissions on /dev/console will not get changed, resulting in things like xterm -C and xconsole not working. This is because of the way console permissions are set by default. On a multi-user system, one does not necessarily want just any user to be able to write on the system console. For users who are logging directly onto a machine with a VTY, the &man.fbtab.5; file exists to solve such problems. In a nutshell, make sure an uncommented line of the form /dev/ttyv0 0600 /dev/console is in /etc/fbtab (see &man.fbtab.5;) and it will ensure that whomever logs in on /dev/ttyv0 will own the console. Before, I was able to run &xfree86; as a regular user. Why does it now say that I must be root? All X servers need to be run as root in order to get direct access to your video hardware. Older versions of &xfree86; (<= 3.3.6) installed all bundled servers to be automatically run as root (setuid to root). This is obviously a security hazard because X servers are large, complicated programs. Newer versions of &xfree86; do not install the servers setuid to root for just this reason. Obviously, running an X server as the root user is not acceptable, nor a good idea security-wise. There are two ways to be able to use X as a regular user. The first is to use xdm or another display manager (e.g., kdm); the second is to use the Xwrapper. xdm is a daemon that handles graphical logins. It is usually started at boot time, and is responsible for authenticating users and starting their sessions; it is essentially the graphical counterpart of &man.getty.8; and &man.login.1;. For more information on xdm see the &xfree86; documentation, and the the FAQ entry on it. Xwrapper is the X server wrapper; it is a small utility to enable one to manually run an X server while maintaining reasonable safety. It performs some sanity checks on the command line arguments given, and if they pass, runs the appropriate X server. If you do not want to run a display manger for whatever reason, this is for you. If you have installed the complete ports collection, you can find the port in /usr/ports/x11/wrapper. Why does my PS/2 mouse misbehave under X? Your mouse and the mouse driver may have somewhat become out of synchronization. In rare cases the driver may erroneously report synchronization problem and you may see the kernel message: psmintr: out of sync (xxxx != yyyy) and notice that your mouse does not work properly. If this happens, disable the synchronization check code by setting the driver flags for the PS/2 mouse driver to 0x100. Enter UserConfig by giving the option at the boot prompt: boot: -c Then, in the UserConfig command line, type: UserConfig> flags psm0 0x100 UserConfig> quit Why does my PS/2 mouse from MouseSystems not work? There have been some reports that certain model of PS/2 mouse from MouseSystems works only if it is put into the high resolution mode. Otherwise, the mouse cursor may jump to the upper-left corner of the screen every so often. Specify the flags 0x04 to the PS/2 mouse driver to put the mouse into the high resolution mode. Enter UserConfig by giving the option at the boot prompt: boot: -c Then, in the UserConfig command line, type: UserConfig> flags psm0 0x04 UserConfig> quit See the previous section for another possible cause of mouse problems. When building an X app, imake cannot find Imake.tmpl. Where is it? Imake.tmpl is part of the Imake package, a standard X application building tool. Imake.tmpl, as well as several header files that are required to build X apps, is contained in the X prog distribution. You can install this from sysinstall or manually from the X distribution files. An X app I am building depends on &xfree86; 3.3.X, but I have &xfree86; 4.X installed. What should I do? To tell the port build to link to the &xfree86; 4.X libraries, add the following to /etc/make.conf, (if you do not have this file, create it): XFREE86_VERSION= 4 How do I reverse the mouse buttons? Run the command xmodmap -e "pointer = 3 2 1" from your .xinitrc or .xsession. How do I install a splash screen and where do I find them? Just prior to the release of FreeBSD 3.1, a new feature was added to allow the display of splash screens during the boot messages. The splash screens currently must be a 256 color bitmap (*.BMP) or ZSoft PCX (*.PCX) file. In addition, they must have a resolution of 320x200 or less to work on standard VGA adapters. If you compile VESA support into your kernel, then you can use larger bitmaps up to 1024x768. The actual VESA support can either be compiled directly into the kernel with the VESA kernel config option or by loading the VESA kld module during bootup. To use a splash screen, you need to modify the startup files that control the boot process for FreeBSD. The files for this changed prior to the release of FreeBSD 3.2, so there are now two ways of loading a splash screen: FreeBSD 3.1 The first step is to find a bitmap version of your splash screen. Release 3.1 only supports &windows; bitmap splash screens. Once you have found your splash screen of choice copy it to /boot/splash.bmp. Next, you need to have a /boot/loader.rc file that contains the following lines: load kernel load -t splash_image_data /boot/splash.bmp load splash_bmp autoboot FreeBSD 3.2+ In addition to adding support for PCX splash screens, FreeBSD 3.2 includes a nicer way of configuring the boot process. If you wish, you can use the method listed above for FreeBSD 3.1. If you do and you want to use PCX, replace splash_bmp with splash_pcx. If, on the other hand, you want to use the newer boot configuration, you need to create a /boot/loader.rc file that contains the following lines: include /boot/loader.4th start and a /boot/loader.conf that contains the following: splash_bmp_load="YES" bitmap_load="YES" This assumes you are using /boot/splash.bmp for your splash screen. If you would rather use a PCX file, copy it to /boot/splash.pcx, create a /boot/loader.rc as instructed above, and create a /boot/loader.conf that contains: splash_pcx_load="YES" bitmap_load="YES" bitmap_name="/boot/splash.pcx" Now all you need is a splash screen. For that you can surf on over to the gallery at . Can I use the &windows; keys on my keyboard in X? Yes. All you need to do is use &man.xmodmap.1; to define what function you wish them to perform. Assuming all &windows; keyboards are standard then the keycodes for the 3 keys are 115 - &windows; key, between the left-hand Ctrl and Alt keys 116 - &windows; key, to the right of the AltGr key 117 - Menu key, to the left of the right-hand Ctrl key To have the left &windows; key print a comma, try this. &prompt.root; xmodmap -e "keycode 115 = comma" You will probably have to re-start your window manager to see the result. To have the &windows; key-mappings enabled automatically every time you start X either put the xmodmap commands in your ~/.xinitrc file or, preferably, create a file ~/.xmodmaprc and include the xmodmap options, one per line, then add the line xmodmap $HOME/.xmodmaprc to your ~/.xinitrc. For example, you could map the 3 keys to be F13, F14, and F15, respectively. This would make it easy to map them to useful functions within applications or your window manager, as demonstrated further down. To do this put the following in ~/.xmodmaprc. keycode 115 = F13 keycode 116 = F14 keycode 117 = F15 If you use fvwm2, for example, you could map the keys so that F13 iconifies (or de-iconifies) the window the cursor is in, F14 brings the window the cursor is in to the front or, if it is already at the front, pushes it to the back, and F15 pops up the main Workplace (application) menu even if the cursor is not on the desktop, which is useful if you do not have any part of the desktop visible (and the logo on the key matches its functionality). The following entries in ~/.fvwmrc implement the aforementioned setup: Key F13 FTIWS A Iconify Key F14 FTIWS A RaiseLower Key F15 A A Menu Workplace Nop How can I get 3D hardware acceleration for &opengl;? The availability of 3D acceleration depends on the version of &xfree86; you are using and the type of video chip you have. If you have an NVIDIA chip, you can use the binary drivers provided for FreeBSD 4.7 on the Drivers section of their website. For other cards with &xfree86;-4, including the Matrox G200/G400, ATI Rage 128/Radeon, and 3dfx Voodoo 3, 4, 5, and Banshee, information on hardware acceleration is available on the XFree86-4 Direct Rendering on FreeBSD page. Users of &xfree86; version 3.3 can use the Utah-GLX port found in graphics/utah-glx to get limited accelerated &opengl; on the Matrox Gx00, ATI Rage Pro, SiS 6326, i810, Savage, and older NVIDIA chips. Networking Where can I get information on diskless booting? Diskless booting means that the FreeBSD box is booted over a network, and reads the necessary files from a server instead of its hard disk. For full details, please read the Handbook entry on diskless booting Can a FreeBSD box be used as a dedicated network router? Yes. Please see the Handbook entry on advanced networking, specifically the section on routing and gateways. Can I connect my &windows; box to the Internet via FreeBSD? Typically, people who ask this question have two PC's at home, one with FreeBSD and one with some version of &windows; the idea is to use the FreeBSD box to connect to the Internet and then be able to access the Internet from the &windows; box through the FreeBSD box. This is really just a special case of the previous question and works perfectly well. If you're using dialup to connect to the Internet user-mode &man.ppp.8; contains a option. If you run &man.ppp.8; with the option, set gateway_enable to YES in /etc/rc.conf, and configure your &windows; machine correctly, this should work fine. For more information, please see the &man.ppp.8; manual page or the Handbook entry on user PPP. If you are using kernel-mode PPP or have an Ethernet connection to the Internet, you need to use &man.natd.8;. Please look at the natd section of the Handbook for a tutorial. Does FreeBSD support SLIP and PPP? Yes. See the manual pages for &man.slattach.8;, &man.sliplogin.8;, &man.ppp.8;, and &man.pppd.8;. &man.ppp.8; and &man.pppd.8; provide support for both incoming and outgoing connections, while &man.sliplogin.8; deals exclusively with incoming connections, and &man.slattach.8; deals exclusively with outgoing connections. For more information on how to use these, please see the Handbook chapter on PPP and SLIP. If you only have access to the Internet through a shell account, you may want to have a look at the net/slirp package. It can provide you with (limited) access to services such as ftp and http direct from your local machine. Does FreeBSD support NAT or Masquerading? Yes. If you want to use NAT over a user PPP connection, please see the Handbook entry on user PPP. If you want to use NAT over some other sort of network connection, please look at the natd section of the Handbook. How do I connect two FreeBSD systems over a parallel line using PLIP? Please see the PLIP section of the Handbook. Why can I not create a /dev/ed0 device? Because they aren't necessary. In the Berkeley networking framework, network interfaces are only directly accessible by kernel code. Please see the /etc/rc.network file and the manual pages for the various network programs mentioned there for more information. If this leaves you totally confused, then you should pick up a book describing network administration on another BSD-related operating system; with few significant exceptions, administering networking on FreeBSD is basically the same as on &sunos; 4.0 or Ultrix. How can I set up Ethernet aliases? If the alias is on the same subnet as an address already configured on the interface, then add netmask 0xffffffff to your &man.ifconfig.8; command-line, as in the following: &prompt.root; ifconfig ed0 alias 192.0.2.2 netmask 0xffffffff Otherwise, just specify the network address and netmask as usual: &prompt.root; ifconfig ed0 alias 172.16.141.5 netmask 0xffffff00 How do I get my 3C503 to use the other network port? If you want to use the other ports, you will have to specify an additional parameter on the &man.ifconfig.8; command line. The default port is link0. To use the AUI port instead of the BNC one, use link2. These flags should be specified using the ifconfig_* variables in /etc/rc.conf (see &man.rc.conf.5;). Why am I having trouble with NFS and FreeBSD? Certain PC network cards are better than others (to put it mildly) and can sometimes cause problems with network intensive applications like NFS. See the Handbook entry on NFS for more information on this topic. Why can I not NFS-mount from a &linux; box? Some versions of the &linux; NFS code only accept mount requests from a privileged port; try &prompt.root; mount -o -P linuxbox:/blah /mnt Why can I not NFS-mount from a Sun box? &sun; workstations running &sunos; 4.X only accept mount requests from a privileged port; try &prompt.root; mount -o -P sunbox:/blah /mnt Why does mountd keep telling me it can't change attributes and that I have a bad exports list on my FreeBSD NFS server? The most frequent problem is not understanding the correct format of /etc/exports. Please review &man.exports.5; and the NFS entry in the Handbook, especially the section on configuring NFS. Why am I having problems talking PPP to NeXTStep machines? Try disabling the TCP extensions in /etc/rc.conf (see &man.rc.conf.5;) by changing the following variable to NO: tcp_extensions=NO Xylogic's Annex boxes are also broken in this regard and you must use the above change to connect through them. How do I enable IP multicast support? FreeBSD supports multicast host operations by default. If you want your box to run as a multicast router, you need to recompile your kernel with the MROUTING option and run &man.mrouted.8;. FreeBSD will start &man.mrouted.8; at boot time if the flag mrouted_enable is set to "YES" in /etc/rc.conf. MBONE tools are available in their own ports category, mbone. If you are looking for the conference tools vic and vat, look there! Which network cards are based on the DEC PCI chipset? Here is a list compiled by Glen Foster gfoster@driver.nsta.org, with some more modern additions: Network cards based on the DEC PCI chipset Vendor Model ASUS PCI-L101-TB Accton ENI1203 Cogent EM960PCI Compex ENET32-PCI D-Link DE-530 Dayna DP1203, DP2100 DEC DE435, DE450 Danpex EN-9400P3 JCIS Condor JC1260 Linksys EtherPCI Mylex LNP101 SMC EtherPower 10/100 (Model 9332) SMC EtherPower (Model 8432) TopWare TE-3500P Znyx (2.2.x) ZX312, ZX314, ZX342, ZX345, ZX346, ZX348 Znyx (3.x) ZX345Q, ZX346Q, ZX348Q, ZX412Q, ZX414, ZX442, ZX444, ZX474, ZX478, ZX212, ZX214 (10mbps/hd)
Why do I have to use the FQDN for hosts on my site? You will probably find that the host is actually in a different domain; for example, if you are in foo.example.org and you wish to reach a host called mumble in the example.org domain, you will have to refer to it by the fully-qualified domain name, mumble.example.org, instead of just mumble. Traditionally, this was allowed by BSD BIND resolvers. However the current version of bind (see &man.named.8;) that ships with FreeBSD no longer provides default abbreviations for non-fully qualified domain names other than the domain you are in. So an unqualified host mumble must either be found as mumble.foo.example.org, or it will be searched for in the root domain. This is different from the previous behavior, where the search continued across mumble.example.org, and mumble.edu. Have a look at RFC 1535 for why this was considered bad practice, or even a security hole. As a good workaround, you can place the line search foo.example.org example.org instead of the previous domain foo.example.org into your /etc/resolv.conf file (see &man.resolv.conf.5;). However, make sure that the search order does not go beyond the boundary between local and public administration, as RFC 1535 calls it. Why do I get an error, Permission denied, for all networking operations? If you have compiled your kernel with the IPFIREWALL option, you need to be aware that the default policy is to deny all packets that are not explicitly allowed. If you had unintentionally misconfigured your system for firewalling, you can restore network operability by typing the following while logged in as root: &prompt.root; ipfw add 65534 allow all from any to any You can also set firewall_type="open" in /etc/rc.conf. For further information on configuring a FreeBSD firewall, see the Handbook section. How much overhead does IPFW incur? Please see the Handbook's Firewalls section, specifically the section on IPFW Overhead & Optimization. Why is my ipfw fwd rule to redirect a service to another machine not working? Possibly because you want to do network address translation (NAT) and not just forward packets. A fwd rule does exactly what it says; it forwards packets. It does not actually change the data inside the packet. Say we have a rule like: 01000 fwd 10.0.0.1 from any to foo 21 When a packet with a destination address of foo arrives at the machine with this rule, the packet is forwarded to 10.0.0.1, but it still has the destination address of foo! The destination address of the packet is not changed to 10.0.0.1. Most machines would probably drop a packet that they receive with a destination address that is not their own. Therefore, using a fwd rule does not often work the way the user expects. This behavior is a feature and not a bug. See the FAQ about redirecting services, the &man.natd.8; manual, or one of the several port redirecting utilities in the ports collection for a correct way to do this. How can I redirect service requests from one machine to another? You can redirect FTP (and other service) request with the socket package, available in the ports tree in category sysutils. Simply replace the service's command line to call socket instead, like so: ftp stream tcp nowait nobody /usr/local/bin/socket socket ftp.example.com ftp where ftp.example.com and ftp are the host and port to redirect to, respectively. Where can I get a bandwidth management tool? There are three bandwidth management tools available for FreeBSD. &man.dummynet.4; is integrated into FreeBSD (or more specifically, &man.ipfw.4;); ALTQ is available for free; Bandwidth Manager from Emerging Technologies is a commercial product. Why do I get /dev/bpf0: device not configured? You are running a program that requires the Berkeley Packet Filter (&man.bpf.4;), but it is not in your kernel. Add this to your kernel config file and build a new kernel: pseudo-device bpf # Berkeley Packet Filter On FreeBSD 4.X and earlier, you must also create the device node. After rebooting, go to the /dev directory and run: &prompt.root; sh MAKEDEV bpf0 Please see the Handbook entry on device nodes for more information on managing devices. How do I mount a disk from a &windows; machine that is on my network, like smbmount in &linux;? Use the SMBFS toolset. It includes a set of kernel modifications and a set of userland programs. The programs and information are available as net/smbfs in the ports collection, or in the base system as of 4.5-RELEASE and later. What are these messages about icmp-response bandwidth limit 300/200 pps in my log files? This is the kernel telling you that some activity is provoking it to send more ICMP or TCP reset (RST) responses than it thinks it should. ICMP responses are often generated as a result of attempted connections to unused UDP ports. TCP resets are generated as a result of attempted connections to unopened TCP ports. Among others, these are the kinds of activities which may cause these messages: Brute-force denial of service (DoS) attacks (as opposed to single-packet attacks which exploit a specific vulnerability). Port scans which attempt to connect to a large number of ports (as opposed to only trying a few well-known ports). The first number in the message tells you how many packets the kernel would have sent if the limit was not in place, and the second number tells you the limit. You can control the limit using the net.inet.icmp.icmplim sysctl variable like this, where 300 is the limit in packets per second: &prompt.root; sysctl -w net.inet.icmp.icmplim=300 If you do not want to see messages about this in your log files, but you still want the kernel to do response limiting, you can use the net.inet.icmp.icmplim_output sysctl variable to disable the output like this: &prompt.root; sysctl -w net.inet.icmp.icmplim_output=0 Finally, if you want to disable response limiting, you can set the net.inet.icmp.icmplim sysctl variable (see above for an example) to 0. Disabling response limiting is discouraged for the reasons listed above. What are these arp: unknown hardware address format error messages? This means that some device on your local Ethernet is using a MAC address in a format that FreeBSD does not recognize. This is probably caused by someone experimenting with an Ethernet card somewhere else on the network. You will see this most commonly on cable modem networks. It is harmless, and should not affect the performance of your FreeBSD machine. I've just installed CVSup but trying to execute it produces errors. What is wrong? First, see if the error message you are receiving is like the one shown below. /usr/libexec/ld-elf.so.1: Shared object "libXaw.so.6" not found Errors like these are caused by installing the net/cvsup port on a machine which does not have the &xfree86; suite. If you want to use the GUI included with CVSup you will need to install &xfree86; now. Alternatively if you just wish to use CVSup from a command line you should delete the package previously installed. Then install the net/cvsup-without-gui port. This is covered in more detail in the CVSup section of the Handbook. Security What is a sandbox? Sandbox is a security term. It can mean two things: A process which is placed inside a set of virtual walls that are designed to prevent someone who breaks into the process from being able to break into the wider system. The process is said to be able to play inside the walls. That is, nothing the process does in regards to executing code is supposed to be able to breech the walls so you do not have to do a detailed audit of its code to be able to say certain things about its security. The walls might be a userid, for example. This is the definition used in the security and named man pages. Take the ntalk service, for example (see /etc/inetd.conf). This service used to run as userid root. Now it runs as userid tty. The tty user is a sandbox designed to make it more difficult for someone who has successfully hacked into the system via ntalk from being able to hack beyond that user id. A process which is placed inside a simulation of the machine. This is more hard-core. Basically it means that someone who is able to break into the process may believe that he can break into the wider machine but is, in fact, only breaking into a simulation of that machine and not modifying any real data. The most common way to accomplish this is to build a simulated environment in a subdirectory and then run the processes in that directory chroot'd (i.e. / for that process is this directory, not the real / of the system). Another common use is to mount an underlying filesystem read-only and then create a filesystem layer on top of it that gives a process a seemingly writeable view into that filesystem. The process may believe it is able to write to those files, but only the process sees the effects - other processes in the system do not, necessarily. An attempt is made to make this sort of sandbox so transparent that the user (or hacker) does not realize that he is sitting in it. &unix; implements two core sandboxes. One is at the process level, and one is at the userid level. Every &unix; process is completely firewalled off from every other &unix; process. One process cannot modify the address space of another. This is unlike &windows; where a process can easily overwrite the address space of any other, leading to a crash. A &unix; process is owned by a particular userid. If the userid is not the root user, it serves to firewall the process off from processes owned by other users. The userid is also used to firewall off on-disk data. What is securelevel? The securelevel is a security mechanism implemented in the kernel. Basically, when the securelevel is positive, the kernel restricts certain tasks; not even the superuser (i.e., root) is allowed to do them. At the time of this writing, the securelevel mechanism is capable of, among other things, limiting the ability to, unset certain file flags, such as schg (the system immutable flag), write to kernel memory via /dev/mem and /dev/kmem, load kernel modules, and alter &man.ipfirewall.4; rules. To check the status of the securelevel on a running system, simply execute the following command: &prompt.root; sysctl kern.securelevel The output will contain the name of the &man.sysctl.8; variable (in this case, kern.securelevel) and a number. The latter is the current value of the securelevel. If it is positive (i.e., greater than 0), at least some of the securelevel's protections are enabled. You cannot lower the securelevel of a running system; being able to do that would defeat its purpose. If you need to do a task that requires that the securelevel be non-positive (e.g., an installworld or changing the date), you will have to change the securelevel setting in /etc/rc.conf (you want to look for the kern_securelevel and kern_securelevel_enable variables) and reboot. For more information on securelevel and the specific things all the levels do, please consult the &man.init.8; manual page. Securelevel is not a silver bullet; it has many known deficiencies. More often than not, it provides a false sense of security. One of its biggest problems is that in order for it to be at all effective, all files used in the boot process up until the securelevel is set must be protected. If an attacker can get the system to execute their code prior to the securelevel being set (which happens quite late in the boot process since some things the system must do at start-up cannot be done at an elevated securelevel), its protections are invalidated. While this task of protecting all files used in the boot process is not technically impossible, if it is achieved, system maintenance will become a nightmare since one would have to take the system down, at least to single-user mode, to modify a configuration file. This point and others are often discussed on the mailing lists, particularly the &a.security;. Please search the archives here for an extensive discussion. Some people are hopeful that securelevel will soon go away in favor of a more fine-grained mechanism, but things are still hazy in this respect. Consider yourself warned. BIND (named) is listening on port 53 and some other high-numbered port. What is going on? FreeBSD 3.0 and later use a version of BIND that uses a random high-numbered port for outgoing queries. If you want to use port 53 for outgoing queries, either to get past a firewall or to make yourself feel better, you can try the following in /etc/namedb/named.conf: options { query-source address * port 53; }; You can replace the * with a single IP address if you want to tighten things further. Congratulations, by the way. It is good practice to read your &man.sockstat.1; output and notice odd things! Sendmail is listening on port 587 as well as the standard port 25! What is going on? Recent versions of Sendmail support a mail submission feature that runs over port 587. This is not yet widely supported, but is growing in popularity. What is this UID 0 toor account? Have I been compromised? Do not worry. toor is an alternative superuser account (toor is root spelt backwards). Previously it was created when the &man.bash.1; shell was installed but now it is created by default. It is intended to be used with a non-standard shell so you do not have to change root's default shell. This is important as shells which are not part of the base distribution (for example a shell installed from ports or packages) are likely to be installed in /usr/local/bin which, by default, resides on a different filesystem. If root's shell is located in /usr/local/bin and /usr (or whatever filesystem contains /usr/local/bin) is not mounted for some reason, root will not be able to log in to fix a problem (although if you reboot into single user mode you will be prompted for the path to a shell). Some people use toor for day-to-day root tasks with a non-standard shell, leaving root, with a standard shell, for single user mode or emergencies. By default you cannot log in using toor as it does not have a password, so log in as root and set a password for toor if you want to use it. Why is suidperl not working properly? For security reasons, suidperl is installed without the suid bit by default. The system administrator can enable suid behavior with the following command. &prompt.root; chmod u+s /usr/bin/suidperl If you want suidperl to be built suid during upgrades from source, edit /etc/make.conf and add ENABLE_SUIDPERL=true before you run make buildworld. PPP I cannot make &man.ppp.8; work. What am I doing wrong? You should first read the &man.ppp.8; manual page and the PPP section of the handbook. Enable logging with the command set log Phase Chat Connect Carrier lcp ipcp ccp command This command may be typed at the &man.ppp.8; command prompt or it may be entered in the /etc/ppp/ppp.conf configuration file (the start of the default section is the best place to put it). Make sure that /etc/syslog.conf (see &man.syslog.conf.5;) contains the lines !ppp *.* /var/log/ppp.log and that the file /var/log/ppp.log exists. You can now find out a lot about what is going on from the log file. Do not worry if it does not all make sense. If you need to get help from someone, it may make sense to them. If your version of &man.ppp.8; does not understand the set log command, you should download the latest version. It will build on FreeBSD version 2.1.5 and higher. Why does &man.ppp.8; hang when I run it? This is usually because your hostname will not resolve. The best way to fix this is to make sure that /etc/hosts is consulted by your resolver first by editing /etc/host.conf and putting the hosts line first. Then, simply put an entry in /etc/hosts for your local machine. If you have no local network, change your localhost line: 127.0.0.1 foo.example.com foo localhost Otherwise, simply add another entry for your host. Consult the relevant manual pages for more details. You should be able to successfully ping -c1 `hostname` when you are done. Why will &man.ppp.8; not dial in -auto mode? First, check that you have got a default route. By running netstat -rn (see &man.netstat.1;), you should see two entries like this: Destination Gateway Flags Refs Use Netif Expire default 10.0.0.2 UGSc 0 0 tun0 10.0.0.2 10.0.0.1 UH 0 0 tun0 This is assuming that you have used the addresses from the handbook, the manual page or from the ppp.conf.sample file. If you do not have a default route, it may be because you are running an old version of &man.ppp.8; that does not understand the word HISADDR in the ppp.conf file. If your version of &man.ppp.8; is from before FreeBSD 2.2.5, change the add 0 0 HISADDR line to one saying add 0 0 10.0.0.2 Another reason for the default route line being missing is that you have mistakenly set up a default router in your /etc/rc.conf (see &man.rc.conf.5;) file (this file was called /etc/sysconfig prior to release 2.2.2), and you have omitted the line saying delete ALL from ppp.conf. If this is the case, go back to the Final system configuration section of the handbook. What does No route to host mean? This error is usually due to a missing MYADDR: delete ALL add 0 0 HISADDR section in your /etc/ppp/ppp.linkup file. This is only necessary if you have a dynamic IP address or do not know the address of your gateway. If you are using interactive mode, you can type the following after entering packet mode (packet mode is indicated by the capitalized PPP in the prompt): delete ALL add 0 0 HISADDR Refer to the PPP and Dynamic IP addresses section of the handbook for further details. Why does my connection drop after about 3 minutes? The default PPP timeout is 3 minutes. This can be adjusted with the line set timeout NNN where NNN is the number of seconds of inactivity before the connection is closed. If NNN is zero, the connection is never closed due to a timeout. It is possible to put this command in the ppp.conf file, or to type it at the prompt in interactive mode. It is also possible to adjust it on the fly while the line is active by connecting to ppp's server socket using &man.telnet.1; or &man.pppctl.8;. Refer to the &man.ppp.8; man page for further details. Why does my connection drop under heavy load? If you have Link Quality Reporting (LQR) configured, it is possible that too many LQR packets are lost between your machine and the peer. Ppp deduces that the line must therefore be bad, and disconnects. Prior to FreeBSD version 2.2.5, LQR was enabled by default. It is now disabled by default. LQR can be disabled with the line disable lqr Why does my connection drop after a random amount of time? Sometimes, on a noisy phone line or even on a line with call waiting enabled, your modem may hang up because it thinks (incorrectly) that it lost carrier. There is a setting on most modems for determining how tolerant it should be to temporary losses of carrier. On a USR &sportster; for example, this is measured by the S10 register in tenths of a second. To make your modem more forgiving, you could add the following send-expect sequence to your dial string: set dial "...... ATS10=10 OK ......" Refer to your modem manual for details. Why does my connection hang after a random amount of time? Many people experience hung connections with no apparent explanation. The first thing to establish is which side of the link is hung. If you are using an external modem, you can simply try using &man.ping.8; to see if the TD light is flashing when you transmit data. If it flashes (and the RD light does not), the problem is with the remote end. If TD does not flash, the problem is local. With an internal modem, you will need to use the set server command in your ppp.conf file. When the hang occurs, connect to &man.ppp.8; using &man.pppctl.8;. If your network connection suddenly revives (PPP was revived due to the activity on the diagnostic socket) or if you cannot connect (assuming the set socket command succeeded at startup time), the problem is local. If you can connect and things are still hung, enable local async logging with set log local async and use &man.ping.8; from another window or terminal to make use of the link. The async logging will show you the data being transmitted and received on the link. If data is going out and not coming back, the problem is remote. Having established whether the problem is local or remote, you now have two possibilities: If the problem is remote, read on entry . If the problem is local, read on entry . The remote end is not responding. What can I do? There is very little you can do about this. Most ISPs will refuse to help if you are not running a Microsoft OS. You can enable lqr in your ppp.conf file, allowing &man.ppp.8; to detect the remote failure and hang up, but this detection is relatively slow and therefore not that useful. You may want to avoid telling your ISP that you are running user-PPP... First, try disabling all local compression by adding the following to your configuration: disable pred1 deflate deflate24 protocomp acfcomp shortseq vj deny pred1 deflate deflate24 protocomp acfcomp shortseq vj Then reconnect to ensure that this makes no difference. If things improve or if the problem is solved completely, determine which setting makes the difference through trial and error. This will provide good ammunition when you contact your ISP (although it may make it apparent that you are not running a Microsoft product). Before contacting your ISP, enable async logging locally and wait until the connection hangs again. This may use up quite a bit of disk space. The last data read from the port may be of interest. It is usually ascii data, and may even describe the problem (Memory fault, core dumped?). If your ISP is helpful, they should be able to enable logging on their end, then when the next link drop occurs, they may be able to tell you why their side is having a problem. Feel free to send the details to &a.brian;, or even to ask your ISP to contact me directly. &man.ppp.8; has hung. What can I do? Your best bet here is to rebuild &man.ppp.8; by adding CFLAGS+=-g and STRIP= to the end of the Makefile, then doing a make clean && make && make install. When &man.ppp.8; hangs, find the &man.ppp.8; process id with ps ajxww | fgrep ppp and run gdb ppp PID. From the gdb prompt, you can then use bt to get a stack trace. Send the results to &a.brian;. Why does nothing happen after the Login OK! message? Prior to FreeBSD version 2.2.5, once the link was established, &man.ppp.8; would wait for the peer to initiate the Line Control Protocol (LCP). Many ISPs will not initiate negotiations and expect the client to do so. To force &man.ppp.8; to initiate the LCP, use the following line: set openmode active It usually does no harm if both sides initiate negotiation, so openmode is now active by default. However, the next section explains when it does do some harm. I keep seeing errors about magic being the same. What does it mean? Occasionally, just after connecting, you may see messages in the log that say magic is the same. Sometimes, these messages are harmless, and sometimes one side or the other exits. Most PPP implementations cannot survive this problem, and even if the link seems to come up, you will see repeated configure requests and configure acknowledgments in the log file until &man.ppp.8; eventually gives up and closes the connection. This normally happens on server machines with slow disks that are spawning a getty on the port, and executing &man.ppp.8; from a login script or program after login. I have also heard reports of it happening consistently when using slirp. The reason is that in the time taken between &man.getty.8; exiting and &man.ppp.8; starting, the client-side &man.ppp.8; starts sending Line Control Protocol (LCP) packets. Because ECHO is still switched on for the port on the server, the client &man.ppp.8; sees these packets reflect back. One part of the LCP negotiation is to establish a magic number for each side of the link so that reflections can be detected. The protocol says that when the peer tries to negotiate the same magic number, a NAK should be sent and a new magic number should be chosen. During the period that the server port has ECHO turned on, the client &man.ppp.8; sends LCP packets, sees the same magic in the reflected packet and NAKs it. It also sees the NAK reflect (which also means &man.ppp.8; must change its magic). This produces a potentially enormous number of magic number changes, all of which are happily piling into the server's tty buffer. As soon as &man.ppp.8; starts on the server, it is flooded with magic number changes and almost immediately decides it has tried enough to negotiate LCP and gives up. Meanwhile, the client, who no longer sees the reflections, becomes happy just in time to see a hangup from the server. This can be avoided by allowing the peer to start negotiating with the following line in your ppp.conf file: set openmode passive This tells &man.ppp.8; to wait for the server to initiate LCP negotiations. Some servers however may never initiate negotiations. If this is the case, you can do something like: set openmode active 3 This tells &man.ppp.8; to be passive for 3 seconds, and then to start sending LCP requests. If the peer starts sending requests during this period, &man.ppp.8; will immediately respond rather than waiting for the full 3 second period. LCP negotiations continue until the connection is closed. What is wrong? There is currently an implementation mis-feature in &man.ppp.8; where it does not associate LCP, CCP & IPCP responses with their original requests. As a result, if one PPP implementation is more than 6 seconds slower than the other side, the other side will send two additional LCP configuration requests. This is fatal. Consider two implementations, A and B. A starts sending LCP requests immediately after connecting and B takes 7 seconds to start. When B starts, A has sent 3 LCP REQs. We are assuming the line has ECHO switched off, otherwise we would see magic number problems as described in the previous section. B sends a REQ, then an ACK to the first of A's REQs. This results in A entering the OPENED state and sending and ACK (the first) back to B. In the meantime, B sends back two more ACKs in response to the two additional REQs sent by A before B started up. B then receives the first ACK from A and enters the OPENED state. A receives the second ACK from B and goes back to the REQ-SENT state, sending another (forth) REQ as per the RFC. It then receives the third ACK and enters the OPENED state. In the meantime, B receives the forth REQ from A, resulting in it reverting to the ACK-SENT state and sending another (second) REQ and (forth) ACK as per the RFC. A gets the REQ, goes into REQ-SENT and sends another REQ. It immediately receives the following ACK and enters OPENED. This goes on until one side figures out that they are getting nowhere and gives up. The best way to avoid this is to configure one side to be passive - that is, make one side wait for the other to start negotiating. This can be done with the set openmode passive command. Care should be taken with this option. You should also use the set stopped N command to limit the amount of time that &man.ppp.8; waits for the peer to begin negotiations. Alternatively, the set openmode active N command (where N is the number of seconds to wait before starting negotiations) can be used. Check the manual page for details. Why does &man.ppp.8; lock up shortly after connection? Prior to version 2.2.5 of FreeBSD, it was possible that your link was disabled shortly after connection due to &man.ppp.8; mis-handling Predictor1 compression negotiation. This would only happen if both sides tried to negotiate different Compression Control Protocols (CCP). This problem is now corrected, but if you are still running an old version of &man.ppp.8; the problem can be circumvented with the line disable pred1 Why does &man.ppp.8; lock up when I shell out to test it? When you execute the shell or ! command, &man.ppp.8; executes a shell (or if you have passed any arguments, &man.ppp.8; will execute those arguments). Ppp will wait for the command to complete before continuing. If you attempt to use the PPP link while running the command, the link will appear to have frozen. This is because &man.ppp.8; is waiting for the command to complete. If you wish to execute commands like this, use the !bg command instead. This will execute the given command in the background, and &man.ppp.8; can continue to service the link. Why does &man.ppp.8; over a null-modem cable never exit? There is no way for &man.ppp.8; to automatically determine that a direct connection has been dropped. This is due to the lines that are used in a null-modem serial cable. When using this sort of connection, LQR should always be enabled with the line enable lqr LQR is accepted by default if negotiated by the peer. Why does &man.ppp.8; dial for no reason in -auto mode? If &man.ppp.8; is dialing unexpectedly, you must determine the cause, and set up Dial filters (dfilters) to prevent such dialing. To determine the cause, use the following line: set log +tcp/ip This will log all traffic through the connection. The next time the line comes up unexpectedly, you will see the reason logged with a convenient timestamp next to it. You can now disable dialing under these circumstances. Usually, this sort of problem arises due to DNS lookups. To prevent DNS lookups from establishing a connection (this will not prevent &man.ppp.8; from passing the packets through an established connection), use the following: set dfilter 1 deny udp src eq 53 set dfilter 2 deny udp dst eq 53 set dfilter 3 permit 0/0 0/0 This is not always suitable, as it will effectively break your demand-dial capabilities - most programs will need a DNS lookup before doing any other network related things. In the DNS case, you should try to determine what is actually trying to resolve a host name. A lot of the time, &man.sendmail.8; is the culprit. You should make sure that you tell sendmail not to do any DNS lookups in its configuration file. See the section on using email with a dialup connection in the FreeBSD Handbook for details on how to create your own configuration file and what should go into it. You may also want to add the following line to your .mc file: define(`confDELIVERY_MODE', `d')dnl This will make sendmail queue everything until the queue is run (usually, sendmail is invoked with , telling it to run the queue every 30 minutes) or until a sendmail -q is done (perhaps from your ppp.linkup file). What do these CCP errors mean? I keep seeing the following errors in my log file: CCP: CcpSendConfigReq CCP: Received Terminate Ack (1) state = Req-Sent (6) This is because &man.ppp.8; is trying to negotiate Predictor1 compression, and the peer does not want to negotiate any compression at all. The messages are harmless, but if you wish to remove them, you can disable Predictor1 compression locally too: disable pred1 Why does &man.ppp.8; not log my connection speed? In order to log all lines of your modem conversation, you must enable the following: set log +connect This will make &man.ppp.8; log everything up until the last requested expect string. If you wish to see your connect speed and are using PAP or CHAP (and therefore do not have anything to chat after the CONNECT in the dial script - no set login script), you must make sure that you instruct &man.ppp.8; to expect the whole CONNECT line, something like this: set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \ \"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n" Here, we get our CONNECT, send nothing, then expect a line-feed, forcing &man.ppp.8; to read the whole CONNECT response. Why does &man.ppp.8; ignore the \ character in my chat script? Ppp parses each line in your config files so that it can interpret strings such as set phone "123 456 789" correctly and realize that the number is actually only one argument. In order to specify a " character, you must escape it using a backslash (\). When the chat interpreter parses each argument, it re-interprets the argument in order to find any special escape sequences such as \P or \T (see the manual page). As a result of this double-parsing, you must remember to use the correct number of escapes. If you wish to actually send a \ character to (say) your modem, you would need something like: set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK" resulting in the following sequence: ATZ OK AT\X OK or set phone 1234567 set dial "\"\" ATZ OK ATDT\\T" resulting in the following sequence: ATZ OK ATDT1234567 Why does &man.ppp.8; get a seg-fault, but I see no ppp.core file? Ppp (or any other program for that matter) should never dump core. Because &man.ppp.8; runs with an effective user id of 0, the operating system will not write &man.ppp.8;'s core image to disk before terminating it. If, however &man.ppp.8; is actually terminating due to a segmentation violation or some other signal that normally causes core to be dumped, and you are sure you are using the latest version (see the start of this section), then you should do the following: &prompt.user; tar xfz ppp-*.src.tar.gz &prompt.user; cd ppp*/ppp &prompt.user; echo STRIP= >>Makefile &prompt.user; echo CFLAGS+=-g >>Makefile &prompt.user; make clean all &prompt.user; su &prompt.root; make install &prompt.root; chmod 555 /usr/sbin/ppp You will now have a debuggable version of &man.ppp.8; installed. You will have to be root to run &man.ppp.8; as all of its privileges have been revoked. When you start &man.ppp.8;, take a careful note of what your current directory was at the time. Now, if and when &man.ppp.8; receives the segmentation violation, it will dump a core file called ppp.core. You should then do the following: &prompt.user; su &prompt.root; gdb /usr/sbin/ppp ppp.core (gdb) bt ..... (gdb) f 0 .... (gdb) i args .... (gdb) l ..... All of this information should be given alongside your question, making it possible to diagnose the problem. If you are familiar with gdb, you may wish to find out some other bits and pieces such as what actually caused the dump and the addresses & values of the relevant variables. Why does the process that forces a dial in auto mode never connect? This was a known problem with &man.ppp.8; set up to negotiate a dynamic local IP number with the peer in auto mode. It is fixed in the latest version - search the manual page for iface. The problem was that when that initial program calls &man.connect.2;, the IP number of the tun interface is assigned to the socket endpoint. The kernel creates the first outgoing packet and writes it to the tun device. &man.ppp.8; then reads the packet and establishes a connection. If, as a result of &man.ppp.8;'s dynamic IP assignment, the interface address is changed, the original socket endpoint will be invalid. Any subsequent packets sent to the peer will usually be dropped. Even if they are not, any responses will not route back to the originating machine as the IP number is no longer owned by that machine. There are several theoretical ways to approach this problem. It would be nicest if the peer would re-assign the same IP number if possible :-) The current version of &man.ppp.8; does this, but most other implementations do not. The easiest method from our side would be to never change the tun interface IP number, but instead to change all outgoing packets so that the source IP number is changed from the interface IP to the negotiated IP on the fly. This is essentially what the iface-alias option in the latest version of &man.ppp.8; is doing (with the help of &man.libalias.3; and &man.ppp.8;'s switch) - it is maintaining all previous interface addresses and NATing them to the last negotiated address. Another alternative (and probably the most reliable) would be to implement a system call that changes all bound sockets from one IP to another. &man.ppp.8; would use this call to modify the sockets of all existing programs when a new IP number is negotiated. The same system call could be used by dhcp clients when they are forced to re-bind() their sockets. Yet another possibility is to allow an interface to be brought up without an IP number. Outgoing packets would be given an IP number of 255.255.255.255 up until the first SIOCAIFADDR ioctl is done. This would result in fully binding the socket. It would be up to &man.ppp.8; to change the source IP number, but only if it is set to 255.255.255.255, and only the IP number and IP checksum would need to change. This, however is a bit of a hack as the kernel would be sending bad packets to an improperly configured interface, on the assumption that some other mechanism is capable of fixing things retrospectively. Why do most games not work with the -nat switch? The reason games and the like do not work when libalias is in use is that the machine on the outside will try to open a connection or send (unsolicited) UDP packets to the machine on the inside. The NAT software does not know that it should send these packets to the interior machine. To make things work, make sure that the only thing running is the software that you are having problems with, then either run tcpdump on the tun interface of the gateway or enable &man.ppp.8; tcp/ip logging (set log +tcp/ip) on the gateway. When you start the offending software, you should see packets passing through the gateway machine. When something comes back from the outside, it will be dropped (that is the problem). Note the port number of these packets then shut down the offending software. Do this a few times to see if the port numbers are consistent. If they are, then the following line in the relevant section of /etc/ppp/ppp.conf will make the software functional: nat port proto internalmachine:port port where proto is either tcp or udp, internalmachine is the machine that you want the packets to be sent to and port is the destination port number of the packets. You will not be able to use the software on other machines without changing the above command, and running the software on two internal machines at the same time is out of the question - after all, the outside world is seeing your entire internal network as being just a single machine. If the port numbers are not consistent, there are three more options: Submit support in libalias. Examples of special cases can be found in /usr/src/lib/libalias/alias_*.c (alias_ftp.c is a good prototype). This usually involves reading certain recognised outgoing packets, identifying the instruction that tells the outside machine to initiate a connection back to the internal machine on a specific (random) port and setting up a route in the alias table so that the subsequent packets know where to go. This is the most difficult solution, but it is the best and will make the software work with multiple machines. Use a proxy. The application may support socks5 for example, or (as in the cvsup case) may have a passive option that avoids ever requesting that the peer open connections back to the local machine. Redirect everything to the internal machine using nat addr. This is the sledge-hammer approach. Has anybody made a list of useful port numbers? Not yet, but this is intended to grow into such a list (if any interest is shown). In each example, internal should be replaced with the IP number of the machine playing the game. Asheron's Call nat port udp internal :65000 65000 Manually change the port number within the game to 65000. If you have got a number of machines that you wish to play on assign a unique port number for each (i.e. 65001, 65002, etc) and add a nat port line for each one. Half Life nat port udp internal:27005 27015 PCAnywhere 8.0 nat port udp internal:5632 5632 nat port tcp internal:5631 5631 Quake nat port udp internal:6112 6112 Alternatively, you may want to take a look at www.battle.net for Quake proxy support. Quake 2 nat port udp internal:27901 27910 nat port udp internal:60021 60021 nat port udp internal:60040 60040 Red Alert nat port udp internal:8675 8675 nat port udp internal:5009 5009 What are FCS errors? FCS stands for Frame Check Sequence. Each PPP packet has a checksum attached to ensure that the data being received is the data being sent. If the FCS of an incoming packet is incorrect, the packet is dropped and the HDLC FCS count is increased. The HDLC error values can be displayed using the show hdlc command. If your link is bad (or if your serial driver is dropping packets), you will see the occasional FCS error. This is not usually worth worrying about although it does slow down the compression protocols substantially. If you have an external modem, make sure your cable is properly shielded from interference - this may eradicate the problem. If your link freezes as soon as you have connected and you see a large number of FCS errors, this may be because your link is not 8 bit clean. Make sure your modem is not using software flow control (XON/XOFF). If your datalink must use software flow control, use the command set accmap 0x000a0000 to tell &man.ppp.8; to escape the ^Q and ^S characters. Another reason for seeing too many FCS errors may be that the remote end has stopped talking PPP. You may want to enable async logging at this point to determine if the incoming data is actually a login or shell prompt. If you have a shell prompt at the remote end, it is possible to terminate &man.ppp.8; without dropping the line by using the close lcp command (a following term command will reconnect you to the shell on the remote machine. If nothing in your log file indicates why the link might have been terminated, you should ask the remote administrator (your ISP?) why the session was terminated. Why do &macos; and &windows; 98 connections freeze when running PPPoE on the gateway? Thanks to Michael Wozniak mwozniak@netcom.ca for figuring this out and Dan Flemming danflemming@mac.com for the Mac solution: This is due to what is called a Black Hole router. &macos; and &windows; 98 (and maybe other Microsoft OSs) send TCP packets with a requested segment size too big to fit into a PPPoE frame (MTU is 1500 by default for Ethernet) and have the do not fragment bit set (default of TCP) and the Telco router is not sending ICMP must fragment back to the www site you are trying to load. (Alternatively, the router is sending the ICMP packet correctly, but the firewall at the www site is dropping it.) When the www server is sending you frames that do not fit into the PPPoE pipe the Telco router drops them on the floor and your page does not load (some pages/graphics do as they are smaller than a MSS.) This seems to be the default of most Telco PPPoE configurations (if only they knew how to program a router... sigh...) One fix is to use regedit on your 95/98 boxes to add the following registry entry... HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTU It should be a string with a value 1436, as some ADSL routers are reported to be unable to deal with packets larger than this. This registry key has been changed to Tcpip\Parameters\Interfaces\ID for adapter\MTU in &windows; 2000 and becomes a DWORD. Refer to the Microsoft Knowledge Base documents Q158474 - Windows TCPIP Registry Entries and Q120642 - TCPIP & NBT Configuration Parameters for &windowsnt; for more information on changing &windows; MTU to work with a NAT router. Another regedit possibility under &windows; 2000 is to set the Tcpip\Parameters\Interfaces\ID for adapter\EnablePMTUBHDetect DWORD to 1 as mentioned in the Microsoft document 120642 mentioned above. Unfortunately, &macos; does not provide an interface for changing TCP/IP settings. However, there is commercial software available, such as OTAdvancedTuner (OT for OpenTransport, the &macos; TCP/IP stack) by Sustainable Softworks, that will allow users to customize TCP/IP settings. &macos; NAT users should select ip_interface_MTU from the drop-down menu, enter 1450 instead of 1500 in the box, click the box next to Save as Auto Configure, and click Make Active. The latest version of &man.ppp.8; (2.3 or greater) has an enable tcpmssfixup command that will automatically adjust the MSS to an appropriate value. This facility is enabled by default. If you are stuck with an older version of &man.ppp.8;, you may want to look at the tcpmssd port. None of this helps - I am desperate! What can I do? If all else fails, send as much information as you can, including your config files, how you are starting &man.ppp.8;, the relevant parts of your log file and the output of the netstat -rn command (before and after connecting) to the &a.questions; or the comp.unix.bsd.freebsd.misc news group, and someone should point you in the right direction. Serial Communications This section answers common questions about serial communications with FreeBSD. PPP and SLIP are covered in the Networking section. How do I tell if FreeBSD found my serial ports? As the FreeBSD kernel boots, it will probe for the serial ports in your system for which the kernel was configured. You can either watch your system closely for the messages it prints or run the command &prompt.user; dmesg | grep sio after your system is up and running. Here is some example output from the above command: sio0 at 0x3f8-0x3ff irq 4 on isa sio0: type 16550A sio1 at 0x2f8-0x2ff irq 3 on isa sio1: type 16550A This shows two serial ports. The first is on irq 4, is using port address 0x3f8, and has a 16550A-type UART chip. The second uses the same kind of chip but is on irq 3 and is at port address 0x2f8. Internal modem cards are treated just like serial ports---except that they always have a modem attached to the port. The GENERIC kernel includes support for two serial ports using the same irq and port address settings in the above example. If these settings are not right for your system, or if you have added modem cards or have more serial ports than your kernel is configured for, just reconfigure your kernel. See section about building a kernel for more details. How do I tell if FreeBSD found my modem cards? Refer to the answer to the previous question. How do I access the serial ports on FreeBSD? The third serial port, sio2 (see &man.sio.4;, known as COM3 in DOS), is on /dev/cuaa2 for dial-out devices, and on /dev/ttyd2 for dial-in devices. What is the difference between these two classes of devices? You use ttydX for dial-ins. When opening /dev/ttydX in blocking mode, a process will wait for the corresponding cuaaX device to become inactive, and then wait for the carrier detect line to go active. When you open the cuaaX device, it makes sure the serial port is not already in use by the ttydX device. If the port is available, it steals it from the ttydX device. Also, the cuaaX device does not care about carrier detect. With this scheme and an auto-answer modem, you can have remote users log in and you can still dial out with the same modem and the system will take care of all the conflicts. How do I enable support for a multiport serial card? Again, the section on kernel configuration provides information about configuring your kernel. For a multiport serial card, place an &man.sio.4; line for each serial port on the card in the kernel configuration file. But place the irq and vector specifiers on only one of the entries. All of the ports on the card should share one irq. For consistency, use the last serial port to specify the irq. Also, specify the COM_MULTIPORT option. The following example is for an AST 4-port serial card on irq 7: options "COM_MULTIPORT" device sio4 at isa? port 0x2a0 tty flags 0x781 device sio5 at isa? port 0x2a8 tty flags 0x781 device sio6 at isa? port 0x2b0 tty flags 0x781 device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr The flags indicate that the master port has minor number 7 (0x700), diagnostics enabled during probe (0x080), and all the ports share an irq (0x001). Can FreeBSD handle multiport serial cards sharing irqs? Not yet. You will have to use a different irq for each card. Can I set the default serial parameters for a port? The ttydX (or cuaaX) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command &prompt.root; stty -a -f /dev/ttyd1 When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the initial state device. For example, to turn on CLOCAL mode, 8 bits, and XON/XOFF flow control by default for ttyd5, do: &prompt.root; stty -f /dev/ttyid5 clocal cs8 ixon ixoff A good place to do this is in /etc/rc.serial. Now, an application will have these settings by default when it opens ttyd5. It can still change these settings to its liking, though. You can also prevent certain settings from being changed by an application by making adjustments to the lock state device. For example, to lock the speed of ttyd5 to 57600 bps, do &prompt.root; stty -f /dev/ttyld5 57600 Now, an application that opens ttyd5 and tries to change the speed of the port will be stuck with 57600 bps. Naturally, you should make the initial state and lock state devices writable only by root. The &man.MAKEDEV.8; script does NOT do this when it creates the device entries. How can I enable dialup logins on my modem? So you want to become an Internet service provider, eh? First, you will need one or more modems that can auto-answer. Your modem will need to assert carrier-detect when it detects a carrier and not assert it all the time. It will need to hang up the phone and reset itself when the data terminal ready (DTR) line goes from on to off. It should probably use RTS/CTS flow control or no local flow control at all. Finally, it must use a constant speed between the computer and itself, but (to be nice to your callers) it should negotiate a speed between itself and the remote modem. For many Hayes command-set--compatible modems, this command will make these settings and store them in nonvolatile memory: AT &C1 &D3 &K3 &Q6 S0=1 &W See the section on sending AT commands below for information on how to make these settings without resorting to an &ms-dos; terminal program. Next, make an entry in /etc/ttys (see &man.ttys.5;) for the modem. This file lists all the ports on which the operating system will await logins. Add a line that looks something like this: ttyd1 "/usr/libexec/getty std.57600" dialup on insecure This line indicates that the second serial port (/dev/ttyd1) has a modem connected running at 57600 bps and no parity (std.57600, which comes from the file /etc/gettytab, see &man.gettytab.5;). The terminal type for this port is dialup. The port is on and is insecure---meaning root logins on the port are not allowed. For dialin ports like this one, use the ttydX entry. It is common practice to use dialup as the terminal type. Many users set up in their .profile or .login files a prompt for the actual terminal type if the starting type is dialup. The example shows the port as insecure. To become root on this port, you have to login as a regular user, then &man.su.1; to become root. If you use secure then root can login in directly. After making modifications to /etc/ttys, you need to send a hangup or HUP signal to the &man.init.8; process: &prompt.root; kill -HUP 1 This forces the &man.init.8; process to reread /etc/ttys. The init process will then start getty processes on all on ports. You can find out if logins are available for your port by typing &prompt.user; ps -ax | grep '[t]tyd1' You should see something like: 747 ?? I 0:00.04 /usr/libexec/getty std.57600 ttyd1 How can I connect a dumb terminal to my FreeBSD box? If you are using another computer as a terminal into your FreeBSD system, get a null modem cable to go between the two serial ports. If you are using an actual terminal, see its accompanying instructions. Then, modify /etc/ttys (see &man.ttys.5;), like above. For example, if you are hooking up a WYSE-50 terminal to the fifth serial port, use an entry like this: ttyd4 "/usr/libexec/getty std.38400" wyse50 on secure This example shows that the port on /dev/ttyd4 has a wyse50 terminal connected at 38400 bps with no parity (std.38400 from /etc/gettytab, see &man.gettytab.5;) and root logins are allowed (secure). Why can I not run tip or cu? On your system, the programs &man.tip.1; and &man.cu.1; are probably executable only by uucp and group dialer. You can use the group dialer to control who has access to your modem or remote systems. Just add yourself to group dialer. Alternatively, you can let everyone on your system run &man.tip.1; and &man.cu.1; by typing: &prompt.root; chmod 4511 /usr/bin/cu &prompt.root; chmod 4511 /usr/bin/tip My stock Hayes modem is not supported---what can I do? Actually, the manual page for &man.tip.1; is out of date. There is a generic Hayes dialer already built in. Just use at=hayes in your /etc/remote (see &man.remote.5;) file. The Hayes driver is not smart enough to recognize some of the advanced features of newer modems---messages like BUSY, NO DIALTONE, or CONNECT 115200 will just confuse it. You should turn those messages off when you use &man.tip.1; (using ATX0&W). Also, the dial timeout for &man.tip.1; is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try ATS7=45&W. Actually, as shipped &man.tip.1; does not yet support it fully. The solution is to edit the file tipconf.h in the directory /usr/src/usr.bin/tip/tip. Obviously you need the source distribution to do this. Edit the line #define HAYES 0 to #define HAYES 1. Then make and make install. Everything works nicely after that. How am I expected to enter these AT commands? Make what is called a direct entry in your /etc/remote file (see &man.remote.5;). For example, if your modem is hooked up to the first serial port, /dev/cuaa0, then put in the following line: cuaa0:dv=/dev/cuaa0:br#19200:pa=none Use the highest bps rate your modem supports in the br capability. Then, type tip cuaa0 (see &man.tip.1;) and you will be connected to your modem. If there is no /dev/cuaa0 on your system, do this: &prompt.root; cd /dev &prompt.root; sh MAKEDEV cuaa0 Or use cu as root with the following command: &prompt.root; cu -lline -sspeed with line being the serial port (e.g. /dev/cuaa0) and speed being the speed (e.g.57600). When you are done entering the AT commands hit ~. to exit. Why does the <@> sign for the pn capability not work? The <@> sign in the phone number capability tells tip to look in /etc/phones for a phone number. But the <@> sign is also a special character in capability files like /etc/remote. Escape it with a backslash: pn=\@ How can I dial a phone number on the command line? Put what is called a generic entry in your /etc/remote file (see &man.remote.5;). For example: tip115200|Dial any phone number at 115200 bps:\ :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du: tip57600|Dial any phone number at 57600 bps:\ :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du: Then you can do something like tip -115200 5551234. If you prefer &man.cu.1; over &man.tip.1;, use a generic cu entry: cu115200|Use cu to dial any number at 115200bps:\ :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du: and type cu 5551234 -s 115200. Do I have to type in the bps rate every time I do that? Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps rate is appropriate with the br capability. &man.tip.1; thinks a good default is 1200 bps which is why it looks for a tip1200 entry. You do not have to use 1200 bps, though. How can I more easily access a number of hosts through a terminal server? Rather than waiting until you are connected and typing CONNECT host each time, use tip's cm capability. For example, these entries in /etc/remote (see &man.remote.5;): pain|pain.deep13.com|Forrester's machine:\ :cm=CONNECT pain\n:tc=deep13: muffin|muffin.deep13.com|Frank's machine:\ :cm=CONNECT muffin\n:tc=deep13: deep13:Gizmonics Institute terminal server:\ :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234: will let you type tip pain or tip muffin to connect to the hosts pain or muffin; and tip deep13 to get to the terminal server. Can tip try more than one line for each site? This is often a problem where a university has several modem lines and several thousand students trying to use them... Make an entry for your university in /etc/remote (see &man.remote.5;) and use <\@> for the pn capability: big-university:\ :pn=\@:tc=dialout dialout:\ :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none: Then, list the phone numbers for the university in /etc/phones (see &man.phones.5;): big-university 5551111 big-university 5551112 big-university 5551113 big-university 5551114 &man.tip.1; will try each one in the listed order, then give up. If you want to keep retrying, run &man.tip.1; in a while loop. Why do I have to hit CTRLP twice to send CTRLP once? CTRLP is the default force character, used to tell &man.tip.1; that the next character is literal data. You can set the force character to any other character with the ~s escape, which means set a variable. Type ~sforce=single-char followed by a newline. single-char is any single character. If you leave out single-char, then the force character is the nul character, which you can get by typing CTRL2 or CTRLSPACE. A pretty good value for single-char is SHIFTCTRL6, which I have seen only used on some terminal servers. You can have the force character be whatever you want by specifying the following in your $HOME/.tiprc file: force=single-char Why is everything I type suddenly in UPPER CASE? You must have pressed CTRLA, &man.tip.1; raise character, specially designed for people with broken Caps Lock keys. Use ~s as above and set the variable raisechar to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features. Here is a sample .tiprc file perfect for Emacs users who need to type CTRL2 and CTRLA a lot: force=^^ raisechar=^^ The ^^ is SHIFTCTRL6. How can I do file transfers with tip? If you are talking to another &unix; system, you can send and receive files with ~p (put) and ~t (take). These commands run &man.cat.1; and &man.echo.1; on the remote system to accept and send files. The syntax is: ~p <local-file> [<remote-file>] ~t <remote-file> [<local-file>] There is no error checking, so you probably should use another protocol, like zmodem. How can I run zmodem with tip? First, install one of the zmodem programs from the ports collection (such as one of the two from the comms category, lrzsz or rzsz. To receive files, start the sending program on the remote end. Then, press enter and type ~C rz (or ~C lrz if you installed lrzsz) to begin receiving them locally. To send files, start the receiving program on the remote end. Then, press enter and type ~C sz files (or ~C lsz files) to send them to the remote system. Miscellaneous Questions FreeBSD uses far more swap space than &linux;. Why? FreeBSD only appears to use more swap than &linux;. In actual fact, it does not. The main difference between FreeBSD and &linux; in this regard is that FreeBSD will proactively move entirely idle, unused pages of main memory into swap in order to make more main memory available for active use. &linux; tends to only move pages to swap as a last resort. The perceived heavier use of swap is balanced by the more efficient use of main memory. Note that while FreeBSD is proactive in this regard, it does not arbitrarily decide to swap pages when the system is truly idle. Thus you will not find your system all paged out when you get up in the morning after leaving it idle overnight. Why does top show very little free memory even when I have very few programs running? The simple answer is that free memory is wasted memory. Any memory that your programs do not actively allocate is used within the FreeBSD kernel as disk cache. The values shown by &man.top.1; labeled as Inact, Cache, and Buf are all cached data at different aging levels. This cached data means the system does not have to access a slow disk again for data it has accessed recently, thus increasing overall performance. In general, a low value shown for Free memory in &man.top.1; is good, provided it is not very low. Why will chmod not change the permissions on symlinks? Symlinks do not have permissions, and by default, &man.chmod.1; will not follow symlinks to change the permissions on the target file. So if you have a file, foo, and a symlink to that file, bar, then this command will always succeed. &prompt.user; chmod g-w bar However, the permissions on foo will not have changed. You have to use either or together with the option to make this work. See the &man.chmod.1; and &man.symlink.7; manual pages for more info. The option does a RECURSIVE &man.chmod.1;. Be careful about specifying directories or symlinks to directories to &man.chmod.1;. If you want to change the permissions of a directory referenced by a symlink, use &man.chmod.1; without any options and follow the symlink with a trailing slash (/). For example, if foo is a symlink to directory bar, and you want to change the permissions of foo (actually bar), you would do something like: &prompt.user; chmod 555 foo/ With the trailing slash, &man.chmod.1; will follow the symlink, foo, to change the permissions of the directory, bar. Can I run DOS binaries under FreeBSD? Yes, you can use the integrated doscmd DOS emulation program to run a subset of DOS commands. If doscmd will not suffice, the add-on utility emulators/pcemu emulates an 8088 and enough BIOS services to run many DOS text mode applications. It requires the X Window System. What do I need to do to translate a FreeBSD document into my native language? See the Translation FAQ in the FreeBSD Documentation Project Primer. Why does my email to any address at FreeBSD.org bounce? The FreeBSD.org mail system implements some of the stricter Postfix checks on incoming mail and rejects mail that is either misconfigured or is potential spam. Your mail might bounce for one of the following reasons: The email is being sent from a known spam domain or IP block. The FreeBSD mail servers reject email from known spam sources. If you have service through a company or domain who generates or relays spam, please switch to a service provider who does not. The body of the email only contains HTML. Mail should be sent in plain text only. Please configure your mail user agent to send plain text. The mailer at FreeBSD.org cannot resolve the IP address of the connecting host back to a symbolic name. Working reverse DNS is a standard requirement for accepting mail from a host. Set up reverse DNS for your mail server's IP address. Many home services (DSL, cable, dialup, etc.) will not give you this option. In this case, relay your email through your service provider's mail server. The hostname given in the EHLO/HELO part of the SMTP exchange cannot be resolved to an IP address. A fully qualified, resolvable host name is necessary in this part of the SMTP dialogue before mail will be accepted. If you do not have a host name that is registered in the DNS, then you should use your service provider's mail server to relay your mail. Your message had a message ID ending with the string localhost. Some mail user agents generate bad message IDs which will not be accepted. You will need to persuade your mail user agent to generate a valid message ID or else configure your mail transfer agent to rewrite them. Where can I find a free FreeBSD account? While FreeBSD does not provide open access to any of their servers, others do provide open access &unix; systems. The charge varies and limited services may be available. Arbornet, Inc, also known as M-Net, has been providing open access to &unix; systems since 1983. Starting on an Altos running System III, the site switched to BSD/OS in 1991. In June of 2000, the site switched again to FreeBSD. M-Net can be accessed via telnet and SSH and provides basic access to the entire FreeBSD software suite. However, network access is limited to members and patrons who donate to the system, which is run as a non-profit organization. M-Net also provides an bulletin board system and interactive chat. Grex provides a site very similar to M-Net including the same bulletin board and interactive chat software. However, the machine is a &sun; 4M and is running &sunos;. What is sup, and how do I use it? SUP stands for Software Update Protocol, and was developed by CMU for keeping their development trees in sync. We used it to keep remote sites in sync with our central development sources. SUP is not bandwidth friendly, and has been retired. The current recommended method to keep your sources up to date is CVSup What is the cute little red guy's name? He does not have one, and is just called the BSD daemon. If you insist upon using a name, call him beastie. Note that beastie is pronounced BSD. You can learn more about the BSD daemon on his home page. Can I use the BSD daemon image? Perhaps. The BSD daemon is copyrighted by Marshall Kirk McKusick. You will want to check his Statement on the Use of the BSD Daemon Figure for detailed usage terms. In summary, you are free to use the image in a tasteful manner, for personal use, so long as appropriate credit is given. If you want to use him commercially, you must contact Kirk McKusick. More details are available on the BSD Daemon's home page. Do you have any BSD daemon images I could use? You will find eps and Xfig drawings under /usr/share/examples/BSD_daemon/. What does MFC mean? MFC is an acronym for Merged From -CURRENT. It is used in the CVS logs to denote when a change was migrated from the CURRENT to the STABLE branches. What does BSD mean? It stands for something in a secret language that only members can know. It does not translate literally but it is ok to tell you that BSD's translation is something between, Formula-1 Racing Team, Penguins are tasty snacks, and We have a better sense of humor than &linux;. :-) Seriously, BSD is an acronym for Berkeley Software Distribution, which is the name the Berkeley CSRG (Computer Systems Research Group) chose for their &unix; distribution way back when. What does POLA mean? Principle of Least Astonishment. It means that as FreeBSD evolves, changes visible to the user should be kept as unsurprising as possible. For example, arbitrarily rearranging system startup variables in /etc/defaults/rc.conf violates POLA. Developers consider POLA when contemplating user-visible system changes. What is a repo-copy? A repo-copy (which is a short form of repository copy) refers to the direct copying of files within the CVS repository. Without a repo-copy, if a file needed to be copied or moved to another place in the repository, the committer would run cvs add to put the file in its new location, and then cvs rm on the old file if the old copy was being removed. The disadvantage of this method is that the history (i.e. the entries in the CVS logs) of the file would not be copied to the new location. As the FreeBSD Project considers this history very useful, a repository copy is often used instead. This is a process where one of the repository meisters will copy the files directly within the repository, rather than using the &man.cvs.1; program. Why should I care what color the bikeshed is? The really, really short answer is that you should not. The somewhat longer answer is that just because you are capable of building a bikeshed does not mean you should stop others from building one just because you do not like the color they plan to paint it. This is a metaphor indicating that you need not argue about every little feature just because you know enough to do so. Some people have commented that the amount of noise generated by a change is inversely proportional to the complexity of the change. The longer and more complete answer is that after a very long argument about whether &man.sleep.1; should take fractional second arguments, &a.phk; posted a long message entitled A bike shed (any colour will do) on greener grass.... The appropriate portions of that message are quoted below.
&a.phk; on freebsd-hackers, October 2, 1999 What is it about this bike shed? Some of you have asked me. It is a long story, or rather it is an old story, but it is quite short actually. C. Northcote Parkinson wrote a book in the early 1960s, called Parkinson's Law, which contains a lot of insight into the dynamics of management. [snip a bit of commentary on the book] In the specific example involving the bike shed, the other vital component is an atomic power-plant, I guess that illustrates the age of the book. Parkinson shows how you can go into the board of directors and get approval for building a multi-million or even billion dollar atomic power plant, but if you want to build a bike shed you will be tangled up in endless discussions. Parkinson explains that this is because an atomic plant is so vast, so expensive and so complicated that people cannot grasp it, and rather than try, they fall back on the assumption that somebody else checked all the details before it got this far. Richard P. Feynmann gives a couple of interesting, and very much to the point, examples relating to Los Alamos in his books. A bike shed on the other hand. Anyone can build one of those over a weekend, and still have time to watch the game on TV. So no matter how well prepared, no matter how reasonable you are with your proposal, somebody will seize the chance to show that he is doing his job, that he is paying attention, that he is here. In Denmark we call it setting your fingerprint. It is about personal pride and prestige, it is about being able to point somewhere and say There! I did that. It is a strong trait in politicians, but present in most people given the chance. Just think about footsteps in wet cement.
The FreeBSD Funnies How cool is FreeBSD? Q. Has anyone done any temperature testing while running FreeBSD? I know &linux; runs cooler than DOS, but have never seen a mention of FreeBSD. It seems to run really hot. A. No, but we have done numerous taste tests on blindfolded volunteers who have also had 250 micrograms of LSD-25 administered beforehand. 35% of the volunteers said that FreeBSD tasted sort of orange, whereas &linux; tasted like purple haze. Neither group mentioned any significant variances in temperature. We eventually had to throw the results of this survey out entirely anyway when we found that too many volunteers were wandering out of the room during the tests, thus skewing the results. We think most of the volunteers are at Apple now, working on their new scratch and sniff GUI. It is a funny old business we are in! Seriously, both FreeBSD and &linux; use the HLT (halt) instruction when the system is idle thus lowering its energy consumption and therefore the heat it generates. Also if you have APM (advanced power management) configured, then FreeBSD can also put the CPU into a low power mode. Who is scratching in my memory banks?? Q. Is there anything odd that FreeBSD does when compiling the kernel which would cause the memory to make a scratchy sound? When compiling (and for a brief moment after recognizing the floppy drive upon startup, as well), a strange scratchy sound emanates from what appears to be the memory banks. A. Yes! You will see frequent references to daemons in the BSD documentation, and what most people do not know is that this refers to genuine, non-corporeal entities that now possess your computer. The scratchy sound coming from your memory is actually high-pitched whispering exchanged among the daemons as they best decide how to deal with various system administration tasks. If the noise gets to you, a good fdisk /mbr from DOS will get rid of them, but do not be surprised if they react adversely and try to stop you. In fact, if at any point during the exercise you hear the satanic voice of Bill Gates coming from the built-in speaker, take off running and do not ever look back! Freed from the counterbalancing influence of the BSD daemons, the twin demons of DOS and &windows; are often able to re-assert total control over your machine to the eternal damnation of your soul. Now that you know, given a choice you would probably prefer to get used to the scratchy noises, no? How many FreeBSD hackers does it take to change a lightbulb? One thousand, one hundred and sixty-nine: Twenty-three to complain to -CURRENT about the lights being out; Four to claim that it is a configuration problem, and that such matters really belong on -questions; Three to submit PRs about it, one of which is misfiled under doc and consists only of it's dark; One to commit an untested lightbulb which breaks buildworld, then back it out five minutes later; Eight to flame the PR originators for not including patches in their PRs; Five to complain about buildworld being broken; Thirty-one to answer that it works for them, and they must have cvsupped at a bad time; One to post a patch for a new lightbulb to -hackers; One to complain that he had patches for this three years ago, but when he sent them to -CURRENT they were just ignored, and he has had bad experiences with the PR system; besides, the proposed new lightbulb is non-reflexive; Thirty-seven to scream that lightbulbs do not belong in the base system, that committers have no right to do things like this without consulting the Community, and WHAT IS -CORE DOING ABOUT IT!? Two hundred to complain about the color of the bicycle shed; Three to point out that the patch breaks &man.style.9;; Seventeen to complain that the proposed new lightbulb is under GPL; Five hundred and eighty-six to engage in a flame war about the comparative advantages of the GPL, the BSD license, the MIT license, the NPL, and the personal hygiene of unnamed FSF founders; Seven to move various portions of the thread to -chat and -advocacy; One to commit the suggested lightbulb, even though it shines dimmer than the old one; Two to back it out with a furious flame of a commit message, arguing that FreeBSD is better off in the dark than with a dim lightbulb; Forty-six to argue vociferously about the backing out of the dim lightbulb and demanding a statement from -core; Eleven to request a smaller lightbulb so it will fit their Tamagotchi if we ever decide to port FreeBSD to that platform; Seventy-three to complain about the SNR on -hackers and -chat and unsubscribe in protest; Thirteen to post unsubscribe, How do I unsubscribe?, or Please remove me from the list, followed by the usual footer; One to commit a working lightbulb while everybody is too busy flaming everybody else to notice; Thirty-one to point out that the new lightbulb would shine 0.364% brighter if compiled with TenDRA (although it will have to be reshaped into a cube), and that FreeBSD should therefore switch to TenDRA instead of GCC; One to complain that the new lightbulb lacks fairings; Nine (including the PR originators) to ask what is MFC?; Fifty-seven to complain about the lights being out two weeks after the bulb has been changed. &a.nik; adds: I was laughing quite hard at this. And then I thought, Hang on, shouldn't there be '1 to document it.' in that list somewhere? And then I was enlightened :-) Where does data written to /dev/null go? It goes into a special data sink in the CPU where it is converted to heat which is vented through the heatsink / fan assembly. This is why CPU cooling is increasingly important; as people get used to faster processors, they become careless with their data and more and more of it ends up in /dev/null, overheating their CPUs. If you delete /dev/null (which effectively disables the CPU data sink) your CPU may run cooler but your system will quickly become constipated with all that excess data and start to behave erratically. If you have a fast network connection you can cool down your CPU by reading data out of /dev/random and sending it off somewhere; however you run the risk of overheating your network connection and / or angering your ISP, as most of the data will end up getting converted to heat by their equipment, but they generally have good cooling, so if you do not overdo it you should be OK. Paul Robinson adds: There are other methods. As every good sysadmin knows, it is part of standard practise to send data to the screen of interesting variety to keep all the pixies that make up your picture happy. Screen pixies (commonly mis-typed or re-named as 'pixels') are categorised by the type of hat they wear (red, green or blue) and will hide or appear (thereby showing the colour of their hat) whenever they receive a little piece of food. Video cards turn data into pixie-food, and then send them to the pixies - the more expensive the card, the better the food, so the better behaved the pixies are. They also need constant stimulation - this is why screen savers exist. To take your suggestions further, you could just throw the random data to console, thereby letting the pixies consume it. This causes no heat to be produced at all, keeps the pixies happy and gets rid of your data quite quickly, even if it does make things look a bit messy on your screen. Incidentally, as an ex-admin of a large ISP who experienced many problems attempting to maintain a stable temperature in a server room, I would strongly discourage people sending the data they do not want out to the network. The fairies who do the packet switching and routing get annoyed by it as well. Advanced Topics How can I learn more about FreeBSD's internals? At this time, there is no book on FreeBSD-specific OS internals. Much general &unix; knowledge is directly applicable to FreeBSD, however. Additionally, there are BSD-specific books that are still relevant. For a list, please check the Handbook's Operating System Internals Bibliography. How can I contribute to FreeBSD? Please see the article on Contributing to FreeBSD for specific advice on how to do this. Assistance is more than welcome! What are SNAPs and RELEASEs? There are currently three active/semi-active branches in the FreeBSD CVS Repository. (Earlier branches are only changed very rarely, which is why there are only three active branches of development): RELENG_3 AKA 3.X-STABLE RELENG_4 AKA 4-STABLE HEAD AKA -CURRENT AKA 5.X-CURRENT HEAD is not an actual branch tag, like the other two; it is simply a symbolic constant for the current, non-branched development stream which we simply refer to as -CURRENT. Right now, -CURRENT is the 5.X development stream and the 4-STABLE branch, RELENG_4, forked off from -CURRENT in Mar 2000. How do I make my own custom release? Please see the Release Engineering article. Why does make world clobber my existing installed binaries? Yes, this is the general idea; as its name might suggest, make world rebuilds every system binary from scratch, so you can be certain of having a clean and consistent environment at the end (which is why it takes so long). If the environment variable DESTDIR is defined while running make world or make install, the newly-created binaries will be deposited in a directory tree identical to the installed one, rooted at ${DESTDIR}. Some random combination of shared libraries modifications and program rebuilds can cause this to fail in make world however. Why isn't cvsup.FreeBSD.org a round robin DNS entry to share the load amongst the various CVSup servers? While CVSup mirrors update from the master CVSup server hourly, this update might happen at any time during the hour. This means that some servers have newer code than others, even though all servers have code that is less than an hour old. If cvsup.FreeBSD.org was a round robin DNS entry that simply redirected users to a random CVSup server, running CVSup twice in a row could download code older than the code already on the system. Why does my system say (bus speed defaulted) when it boots? The Adaptec 1542 SCSI host adapters allow the user to configure their bus access speed in software. Previous versions of the 1542 driver tried to determine the fastest usable speed and set the adapter to that. We found that this breaks some users' systems, so you now have to define the TUNE_1542 kernel configuration option in order to have this take place. Using it on those systems where it works may make your disks run faster, but on those systems where it does not, your data could be corrupted. Can I follow -CURRENT with limited Internet access? Yes, you can do this without downloading the whole source tree by using the CTM facility. How did you split the distribution into 240k files? Newer BSD based systems have a option to &man.split.1; that allows them to split files on arbitrary byte boundaries. Here is an example from /usr/src/Makefile. bin-tarball: (cd ${DISTDIR}; \ tar cf - . \ gzip --no-name -9 -c | \ split -b 240640 - \ ${RELEASEDIR}/tarballs/bindist/bin_tgz.) I have written a kernel extension, who do I send it to? Please take a look at the article on Contributing to FreeBSD to learn how to submit code. And thanks for the thought! How are Plug N Play ISA cards detected and initialized? By: Frank Durda IV uhclem@nemesis.lonestar.org In a nutshell, there a few I/O ports that all of the PnP boards respond to when the host asks if anyone is out there. So when the PnP probe routine starts, it asks if there are any PnP boards present, and all the PnP boards respond with their model # to a I/O read of the same port, so the probe routine gets a wired-OR yes to that question. At least one bit will be on in that reply. Then the probe code is able to cause boards with board model IDs (assigned by Microsoft/Intel) lower than X to go off-line. It then looks to see if any boards are still responding to the query. If the answer was 0, then there are no boards with IDs above X. Now probe asks if there are any boards below X. If so, probe knows there are boards with a model numbers below X. Probe then asks for boards greater than X-(limit/4) to go off-line. If repeats the query. By repeating this semi-binary search of IDs-in-range enough times, the probing code will eventually identify all PnP boards present in a given machine with a number of iterations that is much lower than what 2^64 would take. The IDs are two 32-bit fields (hence 2ˆ64) + 8 bit checksum. The first 32 bits are a vendor identifier. They never come out and say it, but it appears to be assumed that different types of boards from the same vendor could have different 32-bit vendor ids. The idea of needing 32 bits just for unique manufacturers is a bit excessive. The lower 32 bits are a serial #, Ethernet address, something that makes this one board unique. The vendor must never produce a second board that has the same lower 32 bits unless the upper 32 bits are also different. So you can have multiple boards of the same type in the machine and the full 64 bits will still be unique. The 32 bit groups can never be all zero. This allows the wired-OR to show non-zero bits during the initial binary search. Once the system has identified all the board IDs present, it will reactivate each board, one at a time (via the same I/O ports), and find out what resources the given board needs, what interrupt choices are available, etc. A scan is made over all the boards to collect this information. This info is then combined with info from any ECU files on the hard disk or wired into the MLB BIOS. The ECU and BIOS PnP support for hardware on the MLB is usually synthetic, and the peripherals do not really do genuine PnP. However by examining the BIOS info plus the ECU info, the probe routines can cause the devices that are PnP to avoid those devices the probe code cannot relocate. Then the PnP devices are visited once more and given their I/O, DMA, IRQ and Memory-map address assignments. The devices will then appear at those locations and remain there until the next reboot, although there is nothing that says you cannot move them around whenever you want. There is a lot of oversimplification above, but you should get the general idea. Microsoft took over some of the primary printer status ports to do PnP, on the logic that no boards decoded those addresses for the opposing I/O cycles. I found a genuine IBM printer board that did decode writes of the status port during the early PnP proposal review period, but MS said tough. So they do a write to the printer status port for setting addresses, plus that use that address + 0x800, and a third I/O port for reading that can be located anywhere between 0x200 and 0x3ff. Can you assign a major number for a device driver I have written? &os.current; after February 2003 has a facility for dynamically and automatically allocating major numbers for device drivers at runtime. This mechanism is highly preferred to the older procedure of statically allocating device numbers. Some comments on this subject can be found in src/sys/conf/majors. If you are forced for some reason to use a static major number, the procedure for obtaining one depends on whether or not you plan on making the driver publicly available. If you do, then please send us a copy of the driver source code, plus the appropriate modifications to files.i386, a sample configuration file entry, and the appropriate &man.MAKEDEV.8; code to create any special files your device uses. If you do not, or are unable to because of licensing restrictions, then character major number 32 and block major number 8 have been reserved specifically for this purpose; please use them. In any case, we would appreciate hearing about your driver on the &a.hackers;. What about alternative layout policies for directories? In answer to the question of alternative layout policies for directories, the scheme that is currently in use is unchanged from what I wrote in 1983. I wrote that policy for the original fast filesystem, and never revisited it. It works well at keeping cylinder groups from filling up. As several of you have noted, it works poorly for find. Most filesystems are created from archives that were created by a depth first search (aka ftw). These directories end up being striped across the cylinder groups thus creating a worst possible scenario for future depth first searches. If one knew the total number of directories to be created, the solution would be to create (total / fs_ncg) per cylinder group before moving on. Obviously, one would have to create some heuristic to guess at this number. Even using a small fixed number like say 10 would make an order of magnitude improvement. To differentiate restores from normal operation (when the current algorithm is probably more sensible), you could use the clustering of up to 10 if they were all done within a ten second window. Anyway, my conclusion is that this is an area ripe for experimentation. Kirk McKusick, September 1998 How can I make the most of the data I see when my kernel panics? [This section was extracted from a mail written by &a.wpaul; on the freebsd-current mailing list by &a.des;, who fixed a few typos and added the bracketed comments] From: Bill Paul <wpaul@skynet.ctr.columbia.edu> Subject: Re: the fs fun never stops To: Ben Rosengart Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT) Cc: current@FreeBSD.org Ben Rosengart posted the following panic message] > Fatal trap 12: page fault while in kernel mode > fault virtual address = 0x40 > fault code = supervisor read, page not present > instruction pointer = 0x8:0xf014a7e5 ^^^^^^^^^^ > stack pointer = 0x10:0xf4ed6f24 > frame pointer = 0x10:0xf4ed6f28 > code segment = base 0x0, limit 0xfffff, type 0x1b > = DPL 0, pres 1, def32 1, gran 1 > processor eflags = interrupt enabled, resume, IOPL = 0 > current process = 80 (mount) > interrupt mask = > trap number = 12 > panic: page fault [When] you see a message like this, it is not enough to just reproduce it and send it in. The instruction pointer value that I highlighted up there is important; unfortunately, it is also configuration dependent. In other words, the value varies depending on the exact kernel image that you are using. If you are using a GENERIC kernel image from one of the snapshots, then it is possible for somebody else to track down the offending function, but if you are running a custom kernel then only you can tell us where the fault occurred. What you should do is this: Write down the instruction pointer value. Note that the 0x8: part at the beginning is not significant in this case: it is the 0xf0xxxxxx part that we want. When the system reboots, do the following: &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxxx where f0xxxxxx is the instruction pointer value. The odds are you will not get an exact match since the symbols in the kernel symbol table are for the entry points of functions and the instruction pointer address will be somewhere inside a function, not at the start. If you do not get an exact match, omit the last digit from the instruction pointer value and try again, i.e.: &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxx If that does not yield any results, chop off another digit. Repeat until you get some sort of output. The result will be a possible list of functions which caused the panic. This is a less than exact mechanism for tracking down the point of failure, but it is better than nothing. I see people constantly show panic messages like this but rarely do I see someone take the time to match up the instruction pointer with a function in the kernel symbol table. The best way to track down the cause of a panic is by capturing a crash dump, then using &man.gdb.1; to generate a stack trace on the crash dump. In any case, the method I normally use is this: Set up a kernel config file, optionally adding options DDB if you think you need the kernel debugger for something. (I use this mainly for setting breakpoints if I suspect an infinite loop condition of some kind.) Use config -g KERNELCONFIG to set up the build directory. cd /sys/compile/ KERNELCONFIG; make Wait for kernel to finish compiling. make install reboot The &man.make.1; process will have built two kernels. kernel and kernel.debug. kernel was installed as /kernel, while kernel.debug can be used as the source of debugging symbols for &man.gdb.1;. To make sure you capture a crash dump, you need edit /etc/rc.conf and set dumpdev to point to your swap partition. This will cause the &man.rc.8; scripts to use the &man.dumpon.8; command to enable crash dumps. You can also run &man.dumpon.8; manually. After a panic, the crash dump can be recovered using &man.savecore.8;; if dumpdev is set in /etc/rc.conf, the &man.rc.8; scripts will run &man.savecore.8; automatically and put the crash dump in /var/crash. FreeBSD crash dumps are usually the same size as the physical RAM size of your machine. That is, if you have 64MB of RAM, you will get a 64MB crash dump. Therefore you must make sure there is enough space in /var/crash to hold the dump. Alternatively, you run &man.savecore.8; manually and have it recover the crash dump to another directory where you have more room. It is possible to limit the size of the crash dump by using options MAXMEM=(foo) to set the amount of memory the kernel will use to something a little more sensible. For example, if you have 128MB of RAM, you can limit the kernel's memory usage to 16MB so that your crash dump size will be 16MB instead of 128MB. Once you have recovered the crash dump, you can get a stack trace with &man.gdb.1; as follows: &prompt.user; gdb -k /sys/compile/KERNELCONFIG/kernel.debug /var/crash/vmcore.0 (gdb) where Note that there may be several screens worth of information; ideally you should use &man.script.1; to capture all of them. Using the unstripped kernel image with all the debug symbols should show the exact line of kernel source code where the panic occurred. Usually you have to read the stack trace from the bottom up in order to trace the exact sequence of events that lead to the crash. You can also use &man.gdb.1; to print out the contents of various variables or structures in order to examine the system state at the time of the crash. Now, if you are really insane and have a second computer, you can also configure &man.gdb.1; to do remote debugging such that you can use &man.gdb.1; on one system to debug the kernel on another system, including setting breakpoints, single-stepping through the kernel code, just like you can do with a normal user-mode program. I have not played with this yet as I do not often have the chance to set up two machines side by side for debugging purposes. [Bill adds: "I forgot to mention one thing: if you have DDB enabled and the kernel drops into the debugger, you can force a panic (and a crash dump) just by typing 'panic' at the ddb prompt. It may stop in the debugger again during the panic phase. If it does, type 'continue' and it will finish the crash dump." -ed] Why has dlsym() stopped working for ELF executables? The ELF toolchain does not, by default, make the symbols defined in an executable visible to the dynamic linker. Consequently dlsym() searches on handles obtained from calls to dlopen(NULL, flags) will fail to find such symbols. If you want to search, using dlsym(), for symbols present in the main executable of a process, you need to link the executable using the option to the ELF linker (&man.ld.1;). How can I increase or reduce the kernel address space? By default, the kernel address space is 256 MB on FreeBSD 3.X and 1 GB on FreeBSD 4.X. If you run a network-intensive server (e.g. a large FTP or HTTP server), you might find that 256 MB is not enough. So how do you increase the address space? There are two aspects to this. First, you need to tell the kernel to reserve a larger portion of the address space for itself. Second, since the kernel is loaded at the top of the address space, you need to lower the load address so it does not bump its head against the ceiling. The first goal is achieved by increasing the value of NKPDE in src/sys/i386/include/pmap.h. Here is what it looks like for a 1 GB address space: #ifndef NKPDE #ifdef SMP #define NKPDE 254 /* addressable number of page tables/pde's */ #else #define NKPDE 255 /* addressable number of page tables/pde's */ #endif /* SMP */ #endif To find the correct value of NKPDE, divide the desired address space size (in megabytes) by four, then subtract one for UP and two for SMP. To achieve the second goal, you need to compute the correct load address: simply subtract the address space size (in bytes) from 0x100100000; the result is 0xc0100000 for a 1 GB address space. Set LOAD_ADDRESS in src/sys/i386/conf/Makefile.i386 to that value; then set the location counter in the beginning of the section listing in src/sys/i386/conf/kernel.script to the same value, as follows: OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386") OUTPUT_ARCH(i386) ENTRY(btext) SEARCH_DIR(/usr/lib); SEARCH_DIR(/usr/obj/elf/home/src/tmp/usr/i386-unknown-freebsdelf/lib); SECTIONS { /* Read-only sections, merged into text segment: */ . = 0xc0100000 + SIZEOF_HEADERS; .interp : { *(.interp) } Then reconfig and rebuild your kernel. You will probably have problems with &man.ps.1; &man.top.1; and the like; make world should take care of it (or a manual rebuild of libkvm, &man.ps.1; and &man.top.1; after copying the patched pmap.h to /usr/include/vm/. NOTE: the size of the kernel address space must be a multiple of four megabytes. [&a.dg; adds: I think the kernel address space needs to be a power of two, but I am not certain about that. The old(er) boot code used to monkey with the high order address bits and I think expected at least 256MB granularity.] Acknowledgments
FreeBSD Core Team If you see a problem with this FAQ, or wish to submit an entry, please mail the &a.doc;. We appreciate your feedback, and cannot make this a better FAQ without your help!
&a.jkh; Occasional fits of FAQ-reshuffling and updating. &a.dwhite; Services above and beyond the call of duty on freebsd-questions &a.joerg; Services above and beyond the call of duty on Usenet &a.wollman; Networking and formatting Jim Lowe Multicast information &a.pds; FreeBSD FAQ typing machine slavey The FreeBSD Team Kvetching, moaning, submitting data And to any others we have forgotten, apologies and heartfelt thanks! &bibliography; diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml index d3cb1e1cb1..069593e594 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml @@ -1,273 +1,259 @@ -%bookinfo; - -%freebsd; - -%authors; - -%teams; - -%mailing-lists; - -%man; - -%urls; - + +%books.ent; %chapters; ]> FreeBSD Documentation Project Primer for New Contributors The FreeBSD Documentation Project 1998 1999 2000 2001 2002 2003 2004 DocEng $FreeBSD$ $FreeBSD$ &bookinfo.legalnotice; Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable. This primer covers everything you will need to know in order to start contributing to the FreeBSD Documentation Project, from the tools and software you will be using (both mandatory and recommended) to the philosophy behind the Documentation Project. This document is a work in progress, and is not complete. Sections that are known to be incomplete are indicated with a * in their name. Preface Shell Prompts The following table shows the default system prompt and superuser prompt. The examples will use this prompt to indicate which user you should be running the example as. User Prompt Normal user &prompt.user; root &prompt.root; Typographic Conventions The following table describes the typographic conventions used in this book. Meaning Examples The name of commands, files, and directories. On screen computer output. Edit your .login file.Use ls -a to list all files.You have mail. What you type, when contrasted with on-screen computer output. &prompt.user; su Password: Manual page references. Use su 1 to change user names. User and group names Only root can do this. Emphasis You must do this. Command line variables; replace with the real name or variable. To delete a file, type rm filename Environment variables $HOME is your home directory. Notes, tips, important information, warnings, and examples Within the text appear notes, warnings, and examples. Notes are represented like this, and contain information that you should take note of, as it may affect what you do. Tips are represented like this, and contain information that you might find useful, or lead to an easier way to do something. Important information is represented like this. Typically they flag extra steps you may need to carry out. Warnings are represented like this, and contain information warning you about possible damage if you do not follow the instructions. This damage may be physical, to your hardware or to you, or it may be non-physical, such as the inadvertent deletion of important files. A sample example Examples are represented like this, and typically contain examples you should walk through, or show you what the results of a particular action should be. Acknowledgments My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms. &chap.overview; &chap.tools; &chap.sgml-primer; &chap.sgml-markup; &chap.stylesheets; &chap.structure; &chap.doc-build; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; &app.examples; diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml index 8c60df416a..a14b2992d4 100644 --- a/en_US.ISO8859-1/books/handbook/book.sgml +++ b/en_US.ISO8859-1/books/handbook/book.sgml @@ -1,344 +1,329 @@ -%man; - - -%bookinfo; - - -%freebsd; - - %chapters; - -%authors; - -%teams; - %mailing-lists; - %newsgroups; - -%trademarks; - %txtfiles; - -%urls; + +%books.ent; + +%chapters; + +%txtfiles; %pgpkeys; ]> FreeBSD Handbook The FreeBSD Documentation Project February 1999 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.legalnotice; &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.3ware; &tm-attrib.arm; &tm-attrib.adaptec; &tm-attrib.adobe; &tm-attrib.apple; &tm-attrib.corel; &tm-attrib.creative; &tm-attrib.cvsup; &tm-attrib.heidelberger; &tm-attrib.ibm; &tm-attrib.ieee; &tm-attrib.intel; &tm-attrib.intuit; &tm-attrib.linux; &tm-attrib.lsilogic; &tm-attrib.m-systems; &tm-attrib.macromedia; &tm-attrib.microsoft; &tm-attrib.netscape; &tm-attrib.nexthop; &tm-attrib.opengroup; &tm-attrib.oracle; &tm-attrib.powerquest; &tm-attrib.realnetworks; &tm-attrib.redhat; &tm-attrib.sap; &tm-attrib.sun; &tm-attrib.symantec; &tm-attrib.themathworks; &tm-attrib.thomson; &tm-attrib.usrobotics; &tm-attrib.vmware; &tm-attrib.waterloomaple; &tm-attrib.wolframresearch; &tm-attrib.xfree86; &tm-attrib.xiph; &tm-attrib.general; Welcome to FreeBSD! This handbook covers the installation and day to day use of FreeBSD &rel2.current;-RELEASE and FreeBSD &rel.current;-RELEASE. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD web site. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. If you would prefer to have a hard copy of the handbook, you can purchase one at the FreeBSD Mall. You may also want to search the handbook. &chap.preface; Getting Started This part of the FreeBSD Handbook is for users and administrators who are new to FreeBSD. These chapters: Introduce you to FreeBSD. Guide you through the installation process. Teach you &unix; basics and fundamentals. Show you how to install the wealth of third party applications available for FreeBSD. Introduce you to X, the &unix; windowing system, and detail how to configure a desktop environment that makes you more productive. We have tried to keep the number of forward references in the text to a minimum so that you can read this section of the Handbook from front to back with the minimum page flipping required. Common Tasks Now that the basics have been covered, this part of the FreeBSD Handbook will discuss some frequently used features of FreeBSD. These chapters: Introduce you to popular and usesul desktop applications: browsers, productivity tools, document viewers, etc. Introduce you to a number of multimedia tools available for FreeBSD. Explain the process of building a customized FreeBSD kernel, to enable extra functionality on your system. Describe the print system in detail, both for desktop and network-connected printer setups. Show you how to run Linux applications on your FreeBSD system. Some of these chapters recommend that you do some prior reading, and this is noted in the synopsis at the beginning of each chapter. System Administration The remaining chapters of the FreeBSD Handbook cover all aspects of FreeBSD system administration. Each chapter starts by describing what you will learn as a result of reading the chapter, and also details what you are expected to know before tackling the material. These chapters are designed to be read when you need the information. You do not have to read them in any particular order, nor do you need to read all of them before you can begin using FreeBSD. Network Communication FreeBSD is one of the most widely deployed operating systems for high performance network servers. The chapters in this part cover: Serial communication PPP and PPP over Ethernet Electronic Mail Running Network Servers Other Advanced Networking Topics These chapters are designed to be read when you need the information. You do not have to read them in any particular order, nor do you need to read all of them before you can begin using FreeBSD in a network environment. Appendices &chap.colophon; diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml index 000e3c719e..270e15796a 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml @@ -1,8311 +1,8298 @@ -%man; - - -%bookinfo; - - %authors; - -%teams; - -%mailing-lists; - -%freebsd; - -%urls; + +%books.ent; ]> FreeBSD Porter's Handbook The FreeBSD Documentation Project April 2000 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.trademarks; &bookinfo.legalnotice; Introduction The FreeBSD ports collection is the way almost everyone installs applications ("ports") on FreeBSD. Like everything else about FreeBSD, it is primarily a volunteer effort. It is important to keep this in mind when reading this document. In FreeBSD, anyone may submit a new port, or volunteer to maintain an existing port if it is unmaintained—you do not need any special commit privileges to do so. Making a port yourself So, you are interested in making your own port or upgrading an existing one? Great! What follows are some guidelines for creating a new port for FreeBSD. If you want to upgrade an existing port, you should read this and then read . When this document is not sufficiently detailed, you should refer to /usr/ports/Mk/bsd.port.mk, which all port Makefiles include. Even if you do not hack Makefiles daily, it is well commented, and you will still gain much knowledge from it. Additionally, you may send specific questions to the &a.ports;. Only a fraction of the variables (VAR) that can be overridden are mentioned in this document. Most (if not all) are documented at the start of /usr/ports/Mk/bsd.port.mk; the others probably ought to be. Note that this file uses a non-standard tab setting: Emacs and Vim should recognize the setting on loading the file. Both &man.vi.1; and &man.ex.1; can be set to use the correct value by typing :set tabstop=4 once the file has been loaded. Quick Porting This section tells you how to do a quick port. In many cases, it is not sufficient, so you will have to read further on into the document. First, get the original tarball and put it into DISTDIR, which defaults to /usr/ports/distfiles. The following assumes that the software compiled out-of-the-box, i.e., there was absolutely no change required for the port to work on your FreeBSD box. If you needed to change something, you will have to refer to the next section too. Writing the <filename>Makefile</filename> The minimal Makefile would look something like this: # New ports collection makefile for: oneko # Date created: 5 December 1994 # Whom: asami # # $FreeBSD$ # PORTNAME= oneko PORTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= asami@FreeBSD.org COMMENT= A cat chasing a mouse all over the screen MAN1= oneko.1 MANCOMPRESSED= yes USE_IMAKE= yes .include <bsd.port.mk> See if you can figure it out. Do not worry about the contents of the $FreeBSD$ line, it will be filled in automatically by CVS when the port is imported to our main ports tree. You can find a more detailed example in the sample Makefile section. Writing the description files There are two description files that are required for any port, whether they actually package or not. They are pkg-descr and pkg-plist. Their pkg- prefix distinguishes them from other files. <filename>pkg-descr</filename> This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient. This is not a manual or an in-depth description on how to use or compile the port! Please be careful if you are copying from the README or manpage; too often they are not a concise description of the port or are in an awkward format (e.g., manpages have justified spacing). If the ported software has an official WWW homepage, you should list it here. Prefix one of the websites with WWW: so that automated tools will work correctly. It is recommended that you sign your name at the end of this file, as in: This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/ - Satoshi asami@cs.berkeley.edu <filename>pkg-plist</filename> This file lists all the files installed by the port. It is also called the packing list because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually /usr/local or /usr/X11R6). If you are using the MANn variables (as you should be), do not list any manpages here. Here is a small example: bin/oneko lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm @dirrm lib/X11/oneko Refer to the &man.pkg.create.1; manual page for details on the packing list. You should list all the files, but not the name directories, in the list. Also, if the port creates directories for itself during installation, make sure to add @dirrm lines as necessary to remove them when the port is deleted. It is recommended that you keep all the filenames in this file sorted alphabetically. It will make verifying the changes when you upgrade the port much easier. Creating a packing list manually can be a very tedious task. If the port installs a large numbers of files, creating the packing list automatically might save time. There is only one case when pkg-plist can be omitted from a port. If the port installs just a handful of files, and perhaps directories, the files and directories may be listed in the variables PLIST_FILES and PLIST_DIRS, respectively, within the port's Makefile. For instance, we could get along without pkg-plist in the above oneko port by adding the following lines to the Makefile: PLIST_FILES= bin/oneko \ lib/X11/app-defaults/Oneko \ lib/X11/oneko/cat1.xpm \ lib/X11/oneko/cat2.xpm \ lib/X11/oneko/mouse.xpm PLIST_DIRS= lib/X11/oneko Of course, PLIST_DIRS should be left unset if a port installs no directories of its own. The price for this way of listing port's files and directories is that you cannot use command sequences described in &man.pkg.create.1;. Therefore, it is suitable only for simple ports and makes them even simpler. At the same time, it has the advantage of reducing the number of files in the ports collection. Please consider using this technique before you resort to pkg-plist. Later we will see how pkg-plist and PLIST_FILES can be used to fulfil more sophisticated tasks. Creating the checksum file Just type make makesum. The ports make rules will automatically generate the file distinfo. Testing the port You should make sure that the port rules do exactly what you want them to do, including packaging up the port. These are the important points you need to verify. pkg-plist does not contain anything not installed by your port pkg-plist contains everything that is installed by your port Your port can be installed multiple times using the reinstall target Your port cleans up after itself upon deinstall Recommended test ordering make install make package make deinstall pkg_add package-name make deinstall make reinstall make package Make sure that there are not any warnings issued in any of the package and deinstall stages. After step 3, check to see if all the new directories are correctly deleted. Also, try using the software after step 4, to ensure that it works correctly when installed from a package. Checking your port with <command>portlint</command> Please use portlint to see if your port conforms to our guidelines. The portlint program is part of the ports collection. In particular, you may want to check if the Makefile is in the right shape and the package is named appropriately. Submitting the port First, make sure you have read the DOs and DON'Ts section. Now that you are happy with your port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too. We do not need your work directory or the pkgname.tgz package, so delete them now. Next, simply include the output of shar `find port_dir` in a bug report and send it with the &man.send-pr.1; program (see Bug Reports and General Commentary for more information about &man.send-pr.1;). If the uncompressed port is larger than 20KB, you should compress it into a tarfile and use &man.uuencode.1; before including it in the bug report (uuencoded tarfiles are acceptable even if the bug report is smaller than 20KB but are not preferred). Be sure to classify the bug report as category ports and class change-request (Do not mark the report confidential!). Also add a short description of the program you ported to the Description field of the PR and the shar or uuencoded tarfile to the Fix field. You can make our work a lot easier, if you use a good description in the synopsis of the problem report. We prefer something like New port: <category>/<portname> <short description of the port> for new ports and Update port: <category>/<portname> <short description of the update> for port updates. If you stick to this scheme, the chance that someone will take a look at your PR soon is much better. One more time, do not include the original source distfile, the work directory, or the package you built with make package. After you have submitted your port, please be patient. Sometimes it can take a few months before a port is included in FreeBSD, although it might only take a few days. You can view the list of ports waiting to be committed to FreeBSD. Once we have looked at your port, we will get back to you if necessary, and put it in the tree. Your name will also appear in the list of Additional FreeBSD Contributors and other files. Isn't that great?!? :-) Slow Porting Ok, so it was not that simple, and the port required some modifications to get it to work. In this section, we will explain, step by step, how to modify it to get it to work with the ports paradigm. How things work First, this is the sequence of events which occurs when the user first types make in your port's directory. You may find that having bsd.port.mk in another window while you read this really helps to understand it. But do not worry if you do not really understand what bsd.port.mk is doing, not many people do... :-> The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in DISTDIR. If fetch cannot find the required files in DISTDIR it will look up the URL MASTER_SITES, which is set in the Makefile, as well as our main FTP site at , where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with FETCH, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in DISTDIR for future use and proceed. The extract target is run. It looks for your port's distribution file (typically a gzip'd tarball) in DISTDIR and unpacks it into a temporary subdirectory specified by WRKDIR (defaults to work). The patch target is run. First, any patches defined in PATCHFILES are applied. Second, if any patch files named patch-* are found in PATCHDIR (defaults to the files subdirectory), they are applied at this time in alphabetical order. The configure target is run. This can do any one of many different things. If it exists, scripts/configure is run. If HAS_CONFIGURE or GNU_CONFIGURE is set, WRKSRC/configure is run. If USE_IMAKE is set, XMKMF (default: xmkmf -a) is run. The build target is run. This is responsible for descending into the port's private working directory (WRKSRC) and building it. If USE_GMAKE is set, GNU make will be used, otherwise the system make will be used. The above are the default actions. In addition, you can define targets pre-something or post-something, or put scripts with those names, in the scripts subdirectory, and they will be run before or after the default actions are done. For example, if you have a post-extract target defined in your Makefile, and a file pre-build in the scripts subdirectory, the post-extract target will be called after the regular extraction actions, and the pre-build script will be executed before the default build rules are done. It is recommended that you use Makefile targets if the actions are simple enough, because it will be easier for someone to figure out what kind of non-default action the port requires. The default actions are done by the bsd.port.mk targets do-something. For example, the commands to extract a port are in the target do-extract. If you are not happy with the default target, you can fix it by redefining the do-something target in your Makefile. The main targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one are completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix do-extract, but never ever change the way extract operates! Now that you understand what goes on when the user types make, let us go through the recommended steps to create the perfect port. Getting the original sources Get the original sources (normally) as a compressed tarball (foo.tar.gz or foo.tar.Z) and copy it into DISTDIR. Always use mainstream sources when and where you can. You will need to set the variable MASTER_SITES to reflect where the original tarball resides. You will find convenient shorthand definitions for most mainstream sites in bsd.sites.mk. Please use these sites—and the associated definitions—if at all possible, to help avoid the problem of having the same information repeated over again many times in the source base. As these sites tend to change over time, this becomes a maintenance nightmare for everyone involved. If you cannot find a FTP/HTTP site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, you might want to put a copy on a reliable FTP or HTTP server that you control (e.g., your home page). If you cannot find somewhere convenient and reliable to put the distfile we can house it ourselves on ftp.FreeBSD.org; however, this is the least-preferred solution. The distfile must be placed into ~/public_distfiles/ of someone's freefall account. Ask the person who commits your port to do this. This person will also set MASTER_SITES to MASTER_SITE_LOCAL and MASTER_SITE_SUBDIR to their freefall username. If your port's distfile changes all the time without any kind of version update by the author, consider putting the distfile on your home page and listing it as the first MASTER_SITES. If you can, try to talk the port author out of doing this; it really does help to establish some kind of source code control. Hosting your own version will prevent users from getting checksum mismatch errors, and also reduce the workload of maintainers of our FTP site. Also, if there is only one master site for the port, it is recommended that you house a backup at your site and list it as the second MASTER_SITES. If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in DISTDIR. Do not worry if they come from a site other than where you got the main source tarball, we have a way to handle these situations (see the description of PATCHFILES below). Modifying the port Unpack a copy of the tarball in a private directory and make whatever changes are necessary to get the port to compile properly under the current version of FreeBSD. Keep careful track of everything you do, as you will be automating the process shortly. Everything, including the deletion, addition, or modification of files should be doable using an automated script or patch file when your port is finished. If your port requires significant user interaction/customization to compile or install, you should take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the new ports collection is to make each port as plug-and-play as possible for the end-user while using a minimum of disk space. Unless explicitly stated, patch files, scripts, and other files you have created and contributed to the FreeBSD ports collection are assumed to be covered by the standard BSD copyright conditions. Patching In the preparation of the port, files that have been added or changed can be picked up with a recursive &man.diff.1; for later feeding to &man.patch.1;. Each set of patches you wish to apply should be collected into a file named patch-* where * denotes the sequence in which the patches will be applied — these are done in alphabetical order, thus aa first, ab second and so on. If you wish, you can use names that indicate the pathnames of the files that are patched, such as patch-Imakefile or patch-src-config.h. These files should be stored in PATCHDIR, from where they will be automatically applied. All patches should be relative to WRKSRC (generally the directory your port's tarball unpacks itself into, that being where the build is done). To make fixes and upgrades easier, you should avoid having more than one patch fix the same file (e.g., patch-aa and patch-ab both changing WRKSRC/foobar.c). Do not put RCS strings in patches. CVS will mangle them when we put the files into the ports tree, and when we check them out again, they will come out different and the patch will fail. RCS strings are surrounded by dollar ($) signs, and typically start with $Id or $RCS. Using the recurse () option to &man.diff.1; to generate patches is fine, but please take a look at the resulting patches to make sure you do not have any unnecessary junk in there. In particular, diffs between two backup files, Makefiles when the port uses Imake or GNU configure, etc., are unnecessary and should be deleted. If you had to edit configure.in and run autoconf to regenerate configure, do not take the diffs of configure (it often grows to a few thousand lines!); define USE_AUTOCONF_VER=213 and take the diffs of configure.in. Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. Once you are happy with the resulting diff, please split it up into one source file per patch file. Configuring Include any additional customization commands in your configure script and save it in the scripts subdirectory. As mentioned above, you can also do this with Makefile targets and/or scripts with the name pre-configure or post-configure. Handling user input If your port requires user input to build, configure, or install, you must set IS_INTERACTIVE in your Makefile. This will allow overnight builds to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only those ports requiring interaction are built). This will save a lot of wasted time on the set of machines that continually build ports (see below). It is also recommended that if there are reasonable default answers to the questions, you check the PACKAGE_BUILDING variable and turn off the interactive script when it is set. This will allow us to build the packages for CDROMs and FTP. Configuring the Makefile Configuring the Makefile is pretty simple, and again we suggest that you look at existing examples before starting. Also, there is a sample Makefile in this handbook, so take a look and please follow the ordering of variables and sections in that template to make your port easier for others to read. Now, consider the following problems in sequence as you design your new Makefile: The original source Does it live in DISTDIR as a standard gzip'd tarball named something like foozolix-1.2.tar.gz? If so, you can go on to the next step. If not, you should look at overriding any of the DISTNAME, EXTRACT_CMD, EXTRACT_BEFORE_ARGS, EXTRACT_AFTER_ARGS, EXTRACT_SUFX, or DISTFILES variables, depending on how alien a format your port's distribution file is. (The most common case is EXTRACT_SUFX=.tar.Z, when the tarball is condensed by regular compress, not gzip.) In the worst case, you can simply create your own do-extract target to override the default, though this should be rarely, if ever, necessary. Naming The first part of the port's Makefile names the port, describes its version number, and lists it in the correct category. <makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar> You should set PORTNAME to the base name of your port, and PORTVERSION to the version number of the port. <makevar>PORTREVISION</makevar> and <makevar>PORTEPOCH</makevar> <makevar>PORTREVISION</makevar> The PORTREVISION variable is a monotonically increasing value which is reset to 0 with every increase of PORTVERSION (i.e. every time a new official vendor release is made), and appended to the package name if non-zero. Changes to PORTREVISION are used by automated tools (e.g. &man.pkg.version.1;) to highlight the fact that a new package is available. PORTREVISION should be increased each time a change is made to the port which significantly affects the content or structure of the derived package. Examples of when PORTREVISION should be bumped: Addition of patches to correct security vulnerabilities, bugs, or to add new functionality to the port. Changes to the port Makefile to enable or disable compile-time options in the package. Changes in the packing list or the install-time behavior of the package (e.g. change to a script which generates initial data for the package, like ssh host keys). Version bump of a port's shared library dependency (in this case, someone trying to install the old package after installing a newer version of the dependency will fail since it will look for the old libfoo.x instead of libfoo.(x+1)). Silent changes to the port distfile which have significant functional differences, i.e. changes to the distfile requiring a correction to distinfo with no corresponding change to PORTVERSION, where a diff -ru of the old and new versions shows non-trivial changes to the code. Examples of changes which do not require a PORTREVISION bump: Style changes to the port skeleton with no functional change to what appears in the resulting package. Changes to MASTER_SITES or other functional changes to the port which do not affect the resulting package. Trivial patches to the distfile such as correction of typos, which are not important enough that users of the package should go to the trouble of upgrading. Build fixes which cause a package to become compilable where it was previously failing (as long as the changes do not introduce any functional change on any other platforms on which the port did previously build). Since PORTREVISION reflects the content of the package, if the package was not previously buildable then there is no need to increase PORTREVISION to mark a change. A rule of thumb is to ask yourself whether a change committed to a port is something which everyone would benefit from having (either because of an enhancement, fix, or by virtue that the new package will actually work at all), and weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, the PORTREVISION should be bumped. <makevar>PORTEPOCH</makevar> From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1). In situations such as this, the PORTEPOCH version should be increased. If PORTEPOCH is nonzero it is appended to the package name as described in section 0 above. PORTEPOCH must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail (i.e. the package would not be detected as out of date): the new version number (e.g. 1.0,1 in the above example) is still numerically less than the previous version (20000801), but the ,1 suffix is treated specially by automated tools and found to be greater than the implied suffix ,0 on the earlier package. Dropping or resetting PORTEPOCH incorrectly leads to no end of grief; if you do not understand the above discussion, please keep after it until you do, or ask questions on the mailing lists. It is expected that PORTEPOCH will not be used for the majority of ports, and that sensible use of PORTVERSION can often pre-empt it becoming necessary if a future release of the software should change the version structure. However, care is needed by FreeBSD porters when a vendor release is made without an official version number — such as a code snapshot release. The temptation is to label the release with the release date, which will cause problems as in the example above when a new official release is made. For example, if a snapshot release is made on the date 20000917, and the previous version of the software was version 1.2, the snapshot release should be given a PORTVERSION of 1.2.20000917 or similar, not 20000917, so that the succeeding release, say 1.3, is still a numerically greater value. Example of <makevar>PORTREVISION</makevar> and <makevar>PORTEPOCH</makevar> usage The gtkmumble port, version 0.10, is committed to the ports collection: PORTNAME= gtkmumble PORTVERSION= 0.10 PKGNAME becomes gtkmumble-0.10. A security hole is discovered which requires a local FreeBSD patch. PORTREVISION is bumped accordingly. PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1 PKGNAME becomes gtkmumble-0.10_1 A new version is released by the vendor, numbered 0.2 (it turns out the author actually intended 0.10 to actually mean 0.1.0, not what comes after 0.9 - oops, too late now). Since the new minor version 2 is numerically less than the previous version 10, the PORTEPOCH must be bumped to manually force the new package to be detected as newer. Since it is a new vendor release of the code, PORTREVISION is reset to 0 (or removed from the Makefile). PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.2,1 The next release is 0.3. Since PORTEPOCH never decreases, the version variables are now: PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.3,1 If PORTEPOCH were reset to 0 with this upgrade, someone who had installed the gtkmumble-0.10_1 package would not detect the gtkmumble-0.3 package as newer, since 3 is still numerically less than 10. Remember, this is the whole point of PORTEPOCH in the first place. <makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar> Two optional variables, PKGNAMEPREFIX and PKGNAMESUFFIX, are combined with PORTNAME and PORTVERSION to form PKGNAME as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure this conforms to our guidelines for a good package name. In particular, you are not allowed to use a hyphen (-) in PORTVERSION. Also, if the package name has the language- or the -compiled.specifics part (see below), use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. Package Naming Conventions The following are the conventions you should follow in naming your packages. This is to have our package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes! The package name should look like language_region-name-compiled.specifics-version.numbers. The package name is defined as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure to set the variables to conform to that format. FreeBSD strives to support the native language of its users. The language- part should be a two letter abbreviation of the natural language defined by ISO-639 if the port is specific to a certain language. Examples are ja for Japanese, ru for Russian, vi for Vietnamese, zh for Chinese, ko for Korean and de for German. If the port is specific to a certain region within the language area, add the two letter country code as well. Examples are en_US for US English and fr_CH for Swiss French. The language- part should be set in the PKGNAMEPREFIX variable. The first letter of name part should be lowercase. (The rest of the name can contain capital letters, so use your own discretion when you are converting a software name that has some capital letters in it.) There is a tradition of naming perl 5 modules by prepending p5- and converting the double-colon separator to a hyphen; for example, the Data::Dumper module becomes p5-Data-Dumper. If the software in question has numbers, hyphens, or underscores in its name, you may include them as well (like kinput2). If the port can be built with different hardcoded defaults (usually part of the directory name in a family of ports), the -compiled.specifics part should state the compiled-in defaults (the hyphen is optional). Examples are papersize and font units. The -compiled.specifics part should be set in the PKGNAMESUFFIX variable. The version string should follow a dash (-) and be a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string pl (meaning patchlevel), which can be used only when there are no major and minor version numbers in the software. If the software version has strings like alpha, beta, rc, or pre, take the first letter and put it immediately after a period. If the version string continues after those names, the numbers should follow the single alphabet without an extra period between them. The idea is to make it easier to sort ports by looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the yyyy.mm.dd format, not dd.mm.yyyy or the non-Y2K compliant yy.mm.dd format. Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name: Distribution Name PKGNAMEPREFIX PORTNAME PKGNAMESUFFIX PORTVERSION Reason mule-2.2.2 (empty) mule (empty) 2.2.2 No changes required XFree86-3.3.6 (empty) XFree86 (empty) 3.3.6 No changes required EmiClock-1.0.2 (empty) emiclock (empty) 1.0.2 No uppercase names for single programs rdist-1.3alpha (empty) rdist (empty) 1.3.a No strings like alpha allowed es-0.9-beta1 (empty) es (empty) 0.9.b1 No strings like beta allowed mailman-2.0rc3 (empty) mailman (empty) 2.0.r3 No strings like rc allowed v3.3beta021.src (empty) tiff (empty) 3.3 What the heck was that anyway? tvtwm (empty) tvtwm (empty) pl11 Version string always required piewm (empty) piewm (empty) 1.0 Version string always required xvgr-2.10pl1 (empty) xvgr (empty) 2.10.1 pl allowed only when no major/minor version numbers gawk-2.15.6 ja- gawk (empty) 2.15.6 Japanese language version psutils-1.13 (empty) psutils -letter 1.13 Papersize hardcoded at package build time pkfonts (empty) pkfonts 300 1.0 Package for 300dpi fonts If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to 1.0 (like the piewm example above). Otherwise, ask the original author or use the date string (yyyy.mm.dd) as the version. Categorization <makevar>CATEGORIES</makevar> When a package is created, it is put under /usr/ports/packages/All and links are made from one or more subdirectories of /usr/ports/packages. The names of these subdirectories are specified by the variable CATEGORIES. It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. Please take a look at the current list of categories and pick the ones that are suitable for your port. This list also determines where in the ports tree the port is imported. If you put more than one category here, it is assumed that the port files will be put in the subdirectory with the name in the first category. See below for more discussion about how to pick the right categories. If your port truly belongs to something that is different from all the existing ones, you can even create a new category name. In that case, please send mail to the &a.ports; to propose a new category. However, in general, until there are more than a handful of ports which could be reclassified into the category you propose, you will probably be turned down. Occasionally someone proposes reorganizing the categories with either a 2-level structure, or some other kind of keyword structure. To date, nothing has come of any of these proposals because, while they are very easy to make, the effort involved to retrofit the entire existing ports collection with any kind of reorganization is daunting to say the very least. Please read the history of these proposals in the mailing list archives before you post this idea; furthermore, you should be prepared to be challenged to offer a working prototype. Current list of categories Here is the current list of port categories. Those marked with an asterisk (*) are virtual categories—those that do not have a corresponding subdirectory in the ports tree. They are only used as secondary categories, and only for search purposes. For non-virtual categories, you will find a one-line description in the COMMENT in that subdirectory's Makefile. Category Description Notes accessibility Ports to help disabled users. afterstep* Ports to support the AfterStep window manager. arabic Arabic language support. archivers Archiving tools. astro Astronomical ports. audio Sound support. benchmarks Benchmarking utilities. biology Biology-related software. cad Computer aided design tools. chinese Chinese language support. comms Communication software. Mostly software to talk to your serial port. converters Character code converters. databases Databases. deskutils Things that used to be on the desktop before computers were invented. devel Development utilities. Do not put libraries here just because they are libraries—unless they truly do not belong anywhere else, they should not be in this category. dns DNS-related software. editors General editors. Specialized editors go in the section for those tools (e.g., a mathematical-formula editor will go in math). elisp* Emacs-lisp ports. emulators Emulators for other operating systems. Terminal emulators do not belong here—X-based ones should go to x11 and text-based ones to either comms or misc, depending on the exact functionality. finance Monetary, financial and related applications. french French language support. ftp FTP client and server utilities. If your port speaks both FTP and HTTP, put it in ftp with a secondary category of www. games Games. german German language support. gnome* Ports from the GNOME Project. graphics Graphics utilities. haskell* Software related to the Haskell language. hebrew Hebrew language support. hungarian Hungarian language support. ipv6* IPv6 related software. irc Internet Relay Chat utilities. japanese Japanese language support. java Software related to the Java language. kde* Ports from the K Desktop Environment (KDE) Project. korean Korean language support. lang Programming languages. linux* Linux applications and support utilities. lisp* Software related to the Lisp language. mail Mail software. math Numerical computation software and other utilities for mathematics. mbone MBone applications. misc Miscellaneous utilities Basically things that do not belong anywhere else. If at all possible, try to find a better category for your port than misc, as ports tend to get overlooked in here. multimedia Multimedia software. net Miscellaneous networking software. net-mgmt Networking management software. news USENET news software. offix* Ports from the OffiX suite. palm Software support for the Palm™ series. parallel* Applications dealing with parallelism in computing. pear* Ports related to the Pear PHP framework. perl5* Ports that require Perl version 5 to run. picobsd Ports to support PicoBSD. plan9* Various programs from Plan9. polish Polish language support. portuguese Portuguese language support. print Printing software. Desktop publishing tools (previewers, etc.) belong here too. python* Software related to the Python language. ruby* Software related to the Ruby language. russian Russian language support. science Scientific ports that do not fit into other categories such as astro, biology and math. security Security utilities. shells Command line shells. sysutils System utilities. tcl76* Ports that use Tcl version 7.6 to run. tcl80* Ports that use Tcl version 8.0 to run. tcl81* Ports that use Tcl version 8.1 to run. tcl82* Ports that use Tcl version 8.2 to run. tcl83* Ports that use Tcl version 8.3 to run. textproc Text processing utilities. It does not include desktop publishing tools, which go to print. tk42* Ports that use Tk version 4.2 to run. tk80* Ports that use Tk version 8.0 to run. tk81* Ports that use Tk version 8.1 to run. tk82* Ports that use Tk version 8.2 to run. tk83* Ports that use Tk version 8.3 to run. tkstep80* Ports that use TkSTEP version 8.0 to run. ukrainian Ukrainian language support. vietnamese Vietnamese language support. windowmaker* Ports to support the WindowMaker window manager. www Software related to the World Wide Web. HTML language support belongs here too. x11 The X Window System and friends. This category is only for software that directly supports the window system. Do not put regular X applications here; most of them should go into other x11-* categories (see below). If your port is an X application, define USE_XLIB (implied by USE_IMAKE) and put it in the appropriate category. x11-clocks X11 clocks. x11-fm X11 file managers. x11-fonts X11 fonts and font utilities. x11-servers X11 servers. x11-toolkits X11 toolkits. x11-wm X11 window managers. zope* Zope support. Choosing the right category As many of the categories overlap, you often have to choose which of the categories should be the primary category of your port. There are several rules that govern this issue. Here is the list of priorities, in decreasing order of precedence: The first category must be a physical category (see above). This is necessary to make the packaging work. Virtual categories and physical categories may be intermixed after that. Language specific categories always come first. For example, if your port installs Japanese X11 fonts, then your CATEGORIES line would read japanese x11-fonts. Specific categories are listed before less-specific ones. For instance, an HTML editor should be listed as www editors, not the other way around. Also, you should not list net when the port belongs to any of irc, mail, mbone, news, security, or www, as net is included implicitly. x11 is used as a secondary category only when the primary category is a natural language. In particular, you should not put x11 in the category line for X applications. Emacs modes should be placed in the same ports category as the application supported by the mode, not in editors. For example, an Emacs mode to edit source files of some programming language should go into lang. misc should not appear with any other non-virtual category. If you have misc with something else in your CATEGORIES line, that means you can safely delete misc and just put the port in that other subdirectory! If your port truly does not belong anywhere else, put it in misc. If you are not sure about the category, please put a comment to that effect in your &man.send-pr.1; submission so we can discuss it before we import it. If you are a committer, send a note to the &a.ports; so we can discuss it first. Too often, new ports are imported to the wrong category only to be moved right away. This causes unnecessary and undesirable bloat in the master source repository. The distribution files The second part of the Makefile describes the files that must be downloaded in order to build the port, and where they can be downloaded from. <makevar>DISTNAME</makevar> DISTNAME is the name of the port as called by the authors of the software. DISTNAME defaults to ${PORTNAME}-${PORTVERSION}, so override it only if necessary. DISTNAME is only used in two places. First, the distribution file list (DISTFILES) defaults to ${DISTNAME}${EXTRACT_SUFX}. Second, the distribution file is expected to extract into a subdirectory named WRKSRC, which defaults to work/${DISTNAME}. PKGNAMEPREFIX and PKGNAMESUFFIX do not affect DISTNAME. Also note that if WRKSRC is equal to work/${PORTNAME}-${PORTVERSION} while the original source archive is named something other than ${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}, you should probably leave DISTNAME alone— you are better off defining DISTFILES than having to set both DISTNAME and WRKSRC (and possibly EXTRACT_SUFX). <makevar>MASTER_SITES</makevar> Record the directory part of the FTP/HTTP-URL pointing at the original tarball in MASTER_SITES. Do not forget the trailing slash (/)! The make macros will try to use this specification for grabbing the distribution file with FETCH if they cannot find it already on the system. It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard against wide-area network problems. We are even planning to add support for automatically determining the closest master site and fetching from there; having multiple sites will go a long way towards helping this effort. If the original tarball is part of one of the popular archives such as X-contrib, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using MASTER_SITE_* (e.g., MASTER_SITE_XCONTRIB and MASTER_SITE_PERL_GNU). Simply set MASTER_SITES to one of these variables and MASTER_SITE_SUBDIR to the path within the archive. Here is an example: MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications These variables are defined in /usr/ports/Mk/bsd.sites.mk. There are new entries added all the time, so make sure to check the latest version of this file before submitting a port. The user can also set the MASTER_SITE_* variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. <makevar>EXTRACT_SUFX</makevar> If you have one distribution file, and it uses an odd suffix to indicate the compression mechanism, set EXTRACT_SUFX. For example, if the distribution file was named foo.tgz instead of the more normal foo.tar.gz, you would write: DISTNAME= foo EXTRACT_SUFX= .tgz The USE_BZIP2 and USE_ZIP variables automatically set EXTRACT_SUFX to .bz2 or .zip as necessary. If neither of these are set then EXTRACT_SUFX defaults to .tar.gz. You never need to set both EXTRACT_SUFX and DISTFILES. <makevar>DISTFILES</makevar> Sometimes the names of the files to be downloaded have no resemblance to the name of the port. For example, it might be called source.tar.gz or similar. In other cases the application's source code might be in several different archives, all of which must be downloaded. If this is the case, set DISTFILES to be a space separated list of all the files that must be downloaded. DISTFILES= source1.tar.gz source2.tar.gz If not explicitly set, DISTFILES defaults to ${DISTNAME}${EXTRACT_SUFX}. <makevar>EXTRACT_ONLY</makevar> If only some of the DISTFILES must be extracted—for example, one of them is the source code, while another is an uncompressed document—list the filenames that must be extracted in EXTRACT_ONLY. DISTFILES= source.tar.gz manual.html EXTRACT_ONLY= source.tar.gz If none of the DISTFILES should be uncompressed then set EXTRACT_ONLY to the empty string. EXTRACT_ONLY= <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available by FTP or HTTP, set PATCHFILES to the names of the files and PATCH_SITES to the URL of the directory that contains them (the format is the same as MASTER_SITES). If the patch is not relative to the top of the source tree (i.e., WRKSRC) because it contains some extra pathnames, set PATCH_DIST_STRIP accordingly. For instance, if all the pathnames in the patch have an extra foozolix-1.0/ in front of the filenames, then set PATCH_DIST_STRIP=-p1. Do not worry if the patches are compressed; they will be decompressed automatically if the filenames end with .gz or .Z. If the patch is distributed with some other files, such as documentation, in a gzip'd tarball, you cannot just use PATCHFILES. If that is the case, add the name and the location of the patch tarball to DISTFILES and MASTER_SITES. Then, use the EXTRA_PATCHES variable to point to those files and bsd.port.mk will automatically apply them for you. In particular, do not copy patch files into the PATCHDIR directory—that directory may not be writable. The tarball will have been extracted alongside the regular source by then, so there is no need to explicitly extract it if it is a regular gzip'd or compress'd tarball. If you do the latter, take extra care not to overwrite something that already exists in that directory. Also, do not forget to add a command to remove the copied patch in the pre-clean target. Multiple distribution files or patches from different sites and subdirectories (<literal>MASTER_SITES:n</literal>) (Consider this to be a somewhat advanced topic; those new to this document may wish to skip this section at first). This section has information on the fetching mechanism known as both MASTER_SITES:n and MASTER_SITES_NN. We will refer to this mechanism as MASTER_SITES:n hereon. A little background first. OpenBSD has a neat feature inside both DISTFILES and PATCHFILES variables, both files and patches can be postfixed with :n identifiers where n both can be [0-9] and denote a group designation. For example: DISTFILES= alpha:0 beta:1 In OpenBSD, distribution file alpha will be associated with variable MASTER_SITES0 instead of our common MASTER_SITES and beta with MASTER_SITES1. This is a very interesting feature which can decrease that endless search for the correct download site. Just picture 2 files in DISTFILES and 20 sites in MASTER_SITES, the sites slow as hell where beta is carried by all sites in MASTER_SITES, and alpha can only be found in the 20th site. It would be such a waste to check all of them if maintainer knew this beforehand, would it not? Not a good start for that lovely weekend! Now that you have the idea, just imagine more DISTFILES and more MASTER_SITES. Surely our distfiles survey meister would appreciate the relief to network strain that this would bring. In the next sections, information will follow on the FreeBSD implementation of this idea. We improved a bit on OpenBSD's concept. Simplified information This section tells you how to quickly prepare fine grained fetching of multiple distribution files and patches from different sites and subdirectories. We describe here a case of simplified MASTER_SITES:n usage. This will be sufficient for most scenarios. However, if you need further information, you will have to refer to the next section. Some applications consist of multiple distribution files that must be downloaded from a number of different sites. For example, Ghostscript consists of the core of the program, and then a large number of driver files that are used depending on the user's printer. Some of these driver files are supplied with the core, but many others must be downloaded from a variety of different sites. To support this, each entry in DISTFILES may be followed by a colon and a tag name. Each site listed in MASTER_SITES is then followed by a colon, and the tag that indicates which distribution files should be downloaded from this site. For example, consider an application with the source split in two parts, source1.tar.gz and source2.tar.gz, which must be downloaded from two different sites. The port's Makefile would include lines like . Simplified use of <literal>MASTER_SITES:n</literal> with 1 file per site MASTER_SITES= ftp://ftp.example1.com/:source1 \ ftp://ftp.example2.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 Multiple distribution files can have the same tag. Continuing the previous example, suppose that there was a third distfile, source3.tar.gz, that should be downloaded from ftp.example2.com. The Makefile would then be written like . Simplified use of <literal>MASTER_SITES:n</literal> with more than 1 file per site MASTER_SITES= ftp://ftp.example1.com/:source1 \ ftp://ftp.example2.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 \ source3.tar.gz:source2 Detailed information Okay, so the previous section example did not reflect your needs? In this section we will explain in detail how the fine grained fetching mechanism MASTER_SITES:n works and how you can modify your ports to use it. Elements can be postfixed with :n where n is [^:,]+, i.e., n could conceptually be any alphanumeric string but we will limit it to [a-zA-Z_][0-9a-zA-Z_]+ for now. Moreover, string matching is case sensitive; i.e., n is different from N. However, the following words cannot be used for postfixing purposes since they yield special meaning: default, all and ALL (they are used internally in item ). Furthermore, DEFAULT is a special purpose word (check item ). Elements postfixed with :n belong to the group n, :m belong to group m and so forth. Elements without a postfix are groupless, i.e., they all belong to the special group DEFAULT. If you postfix any elements with DEFAULT, you are just being redundant unless you want to have an element belonging to both DEFAULT and other groups at the same time (check item ). The following examples are equivalent but the first one is preferred: MASTER_SITES= alpha MASTER_SITES= alpha:DEFAULT Groups are not exclusive, an element may belong to several different groups at the same time and a group can either have either several different elements or none at all. Repeated elements within the same group will be simply that, repeated elements. When you want an element to belong to several groups at the same time, you can use the comma operator (,). Instead of repeating it several times, each time with a different postfix, we can list several groups at once in a single postfix. For instance, :m,n,o marks an element that belongs to group m, n and o. All the following examples are equivalent but the last one is preferred: MASTER_SITES= alpha alpha:SOME_SITE MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE MASTER_SITES= alpha:SOME_SITE,DEFAULT MASTER_SITES= alpha:DEFAULT,SOME_SITE All sites within a given group are sorted according to MASTER_SORT_AWK. All groups within MASTER_SITES and PATCH_SITES are sorted as well. Group semantics can be used in any of the following variables MASTER_SITES, PATCH_SITES, MASTER_SITE_SUBDIR, PATCH_SITE_SUBDIR, DISTFILES, and PATCHFILES according to the following syntax: All MASTER_SITES, PATCH_SITES, MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR elements must be terminated with the forward slash / character. If any elements belong to any groups, the group postfix :n must come right after the terminator /. The MASTER_SITES:n mechanism relies on the existence of the terminator / to avoid confusing elements where a :n is a valid part of the element with occurrences where :n denotes group n. For compatibility purposes, since the / terminator was not required before in both MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR elements, if the postfix immediate preceding character is not a / then :n will be considered a valid part of the element instead of a group postfix even if an element is postfixed with :n. See both and . Detailed use of <literal>MASTER_SITES:n</literal> in <makevar>MASTER_SITE_SUBDIR</makevar> MASTER_SITE_SUBDIR= old:n new/:NEW Directories within group DEFAULT -> old:n Directories within group NEW -> new Detailed use of <literal>MASTER_SITES:n</literal> with comma operator, multiple files, multiple sites and multiple subdirectories MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \ http://site3/:group3 http://site4/:group4 \ http://site5/:group5 http://site6/:group6 \ http://site7/:DEFAULT,group6 \ http://site8/%SUBDIR%/:group6,group7 \ http://site9/:group8 DISTFILES= file1 file2:DEFAULT file3:group3 \ file4:group4,group5,group6 file5:grouping \ file6:group7 MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ directory-one/:group6,DEFAULT \ directory The previous example results in the following fine grained fetching. Sites are listed in the exact order they will be used. file1 will be fetched from MASTER_SITE_OVERRIDE http://site1/directory/ http://site1/directory-one/ http://site1/directory-trial:1/ http://site2/ http://site7/ MASTER_SITE_BACKUP file2 will be fetched exactly as file1 since they both belong to the same group MASTER_SITE_OVERRIDE http://site1/directory/ http://site1/directory-one/ http://site1/directory-trial:1/ http://site2/ http://site7/ MASTER_SITE_BACKUP file3 will be fetched from MASTER_SITE_OVERRIDE http://site3/ MASTER_SITE_BACKUP file4 will be fetched from MASTER_SITE_OVERRIDE http://site4/ http://site5/ http://site6/ http://site7/ http://site8/directory-one/ MASTER_SITE_BACKUP file5 will be fetched from MASTER_SITE_OVERRIDE MASTER_SITE_BACKUP file6 will be fetched from MASTER_SITE_OVERRIDE http://site8/directory-one/ MASTER_SITE_BACKUP How do I group one of the special variables from bsd.sites.mk, e.g., MASTER_SITE_SOURCEFORGE? See . Detailed use of <literal>MASTER_SITES:n</literal> with <makevar>MASTER_SITE_SOURCEFORGE</makevar> MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} DISTFILES= something.tar.gz:sourceforge something.tar.gz will be fetched from all sites within MASTER_SITE_SOURCEFORGE. How do I use this with PATCH* variables? All examples were done with MASTER* variables but they work exactly the same for PATCH* ones as can be seen in . Simplified use of <literal>MASTER_SITES:n</literal> with <makevar>PATCH_SITES</makevar>. PATCH_SITES= http://site1/ http://site2/:test PATCHFILES= patch1:test What does change for ports? What does not? All current ports remain the same. The MASTER_SITES:n feature code is only activated if there are elements postfixed with :n like elements according to the aforementioned syntax rules, especially as shown in item . The port targets remain the same: checksum, makesum, patch, configure, build, etc. With the obvious exceptions of do-fetch, fetch-list, master-sites and patch-sites. do-fetch: deploys the new grouping postfixed DISTFILES and PATCHFILES with their matching group elements within both MASTER_SITES and PATCH_SITES which use matching group elements within both MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR. Check . fetch-list: works like old fetch-list with the exception that it groups just like do-fetch. master-sites and patch-sites: (incompatible with older versions) only return the elements of group DEFAULT; in fact, they execute targets master-sites-default and patch-sites-default respectively. Furthermore, using target either master-sites-all or patch-sites-all is preferred to directly checking either MASTER_SITES or PATCH_SITES. Also, directly checking is not guaranteed to work in any future versions. Check item for more information on these new port targets. New port targets There are master-sites-n and patch-sites-n targets which will list the elements of the respective group n within MASTER_SITES and PATCH_SITES respectively. For instance, both master-sites-DEFAULT and patch-sites-DEFAULT will return the elements of group DEFAULT, master-sites-test and patch-sites-test of group test, and thereon. There are new targets master-sites-all and patch-sites-all which do the work of the old master-sites and patch-sites ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many MASTER_SITE_BACKUP and MASTER_SITE_OVERRIDE as there are groups defined within either DISTFILES or PATCHFILES; respectively for master-sites-all and patch-sites-all. <makevar>DIST_SUBDIR</makevar> Do not let your port clutter /usr/ports/distfiles. If your port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (e.g., Makefile), set DIST_SUBDIR to the name of the port (${PORTNAME} or ${PKGNAMEPREFIX}${PORTNAME} should work fine). This will change DISTDIR from the default /usr/ports/distfiles to /usr/ports/distfiles/DIST_SUBDIR, and in effect puts everything that is required for your port into that subdirectory. It will also look at the subdirectory with the same name on the backup master site at ftp.FreeBSD.org. (Setting DISTDIR explicitly in your Makefile will not accomplish this, so please use DIST_SUBDIR.) This does not affect the MASTER_SITES you define in your Makefile. <makevar>MAINTAINER</makevar> Set your mail-address here. Please. :-) Note that only a single address without the comment part is allowed as a MAINTAINER value. The format used should be user@hostname.domain. Please do not include any descriptive text such as your real name in this entry—that merely confuses bsd.port.mk. Instead, put that information into your pkg-descr. For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section. If the maintainer of a port does not respond to an update request from a user after two weeks (excluding major public holidays), then that is considered a maintainer timeout, and the update may be made without explicit maintainer approval. If the maintainer does not respond within three months, then that maintainer is considered absent without leave, and can be replaced as the maintainer of the particular port in question. Exceptions to this are anything maintained by the &a.portmgr;, or the &a.security-officer;. No unauthorized commits may ever be made to ports maintained by those groups. The &a.portmgr; reserves the right to revoke or override anyone's maintainership for any reason, and the &a.security-officer; reserves the right to revoke or override maintainership for security reasons. <makevar>COMMENT</makevar> This is a one-line description of the port. Please do not include the package name (or version number of the software) in the comment. The comment should begin with a capital and end without a period. Here is an example: COMMENT= A cat chasing a mouse all over the screen The COMMENT variable should immediately follow the MAINTAINER variable in the Makefile. Please try to keep the COMMENT line less than 70 characters, as it is displayed to users as a one-line summary of the port. Dependencies Many ports depend on other ports. There are seven variables that you can use to ensure that all the required bits will be on the user's machine. There are also some pre-supported dependency variables for common cases, plus a few more to control the behavior of dependencies. <makevar>LIB_DEPENDS</makevar> This variable specifies the shared libraries this port depends on. It is a list of lib:dir:target tuples where lib is the name of the shared library, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. For example, LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install will check for a shared jpeg library with major version 9, and descend into the graphics/jpeg subdirectory of your ports tree to build and install it if it is not found. The target part can be omitted if it is equal to DEPENDS_TARGET (which defaults to install). The lib part is an argument given to ldconfig -r | grep -wF. There shall be no regular expressions in this variable. The dependency is checked twice, once from within the extract target and then from within the install target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. <makevar>RUN_DEPENDS</makevar> This variable specifies executables or files this port depends on during run-time. It is a list of path:dir:target tuples where path is the name of the executable or file, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. If path starts with a slash (/), it is treated as a file and its existence is tested with test -e; otherwise, it is assumed to be an executable, and which -s is used to determine if the program exists in the user's search path. For example, RUN_DEPENDS= ${LOCALBASE}/etc/innd:${PORTSDIR}/news/inn \ wish8.0:${PORTSDIR}/x11-toolkits/tk80 will check if the file or directory /usr/local/etc/innd exists, and build and install it from the news/inn subdirectory of the ports tree if it is not found. It will also see if an executable called wish8.0 is in your search path, and descend into the x11-toolkits/tk80 subdirectory of your ports tree to build and install it if it is not found. In this case, innd is actually an executable; if an executable is in a place that is not expected to be in a normal user's search path, you should use the full pathname. The dependency is checked from within the install target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>BUILD_DEPENDS</makevar> This variable specifies executables or files this port requires to build. Like RUN_DEPENDS, it is a list of path:dir:target tuples. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. build here means everything from extraction to compilation. The dependency is checked from within the extract target. The target part can be omitted if it is the same as DEPENDS_TARGET <makevar>FETCH_DEPENDS</makevar> This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of path:dir:target tuples. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 will check for an executable called ncftp2, and descend into the net/ncftp2 subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the fetch target. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>EXTRACT_DEPENDS</makevar> This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of path:dir:target tuples. For example, EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the extract target. The target part can be omitted if it is the same as DEPENDS_TARGET. Use this variable only if the extraction does not already work (the default assumes gzip) and cannot be made to work using USE_ZIP or USE_BZIP2 described in . <makevar>PATCH_DEPENDS</makevar> This variable specifies executables or files this port requires to patch. Like the previous, it is a list of path:dir:target tuples. For example, PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract will descend into the java/jfc subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the patch target. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>DEPENDS</makevar> If there is a dependency that does not fall into either of the above categories, or your port requires having the source of the other port extracted in addition to having it installed, then use this variable. This is a list of dir:target, as there is nothing to check, unlike the previous four. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>USE_<replaceable>*</replaceable></makevar> A number of variables exist in order to encapsulate common dependencies that many ports have. Although their use is optional, they can help to reduce the verbosity of the port Makefiles. Each of them is styled as USE_*. The usage of these variables is restricted to the port Makefiles and ports/Mk/bsd.*.mk and is not designed to encapsulate user-settable options — use WITH_* and WITHOUT_* for that purpose. It is always incorrect to set any USE_* in /etc/make.conf. For instance, setting USE_GCC=3.2 would adds a dependency on gcc32 for every port, including gcc32 itself! The <makevar>USE_<replaceable>*</replaceable></makevar> variables Variable Means USE_BZIP2 The port's tarballs are compressed with bzip2. USE_ZIP The port's tarballs are compressed with zip. USE_GMAKE The port requires gmake to build. USE_PERL5 The port requires perl 5 to build and install. See for additional variables that can be set relating to perl. USE_X_PREFIX The port installs in to X11BASE rather than PREFIX. See for additional variables that can be set relating to X11. USE_AUTOMAKE_VER The port uses GNU automake as part of its build process. See for additional variables that can be set relating to automake. USE_AUTOCONF_VER The port uses GNU autoconf as part of its build process. See for additional variables that can be set relating to autoconf. USE_LIBTOOL_VER The port uses GNU libtool as part of its build process. See for additional variables that can be set relating to libtool. GMAKE The full path for gmake if it is not in the PATH. USE_BISON The port uses bison for building. USE_SDL The port uses SDL for building and running. See on how to use USE_SDL. NO_INSTALL_MANPAGES Do not use the install.man target.
Define USE_XLIB=yes if your port requires the X Window System to be installed (it is implied by USE_IMAKE). Define USE_GMAKE=yes if your port requires GNU make instead of BSD make. Define USE_AUTOCONF_VER=213 if your port requires GNU autoconf to be run. Define USE_QT_VER=3 if your port uses the latest Qt toolkit. Use USE_PERL5=yes if your port requires version 5 of the perl language. (The last is especially important since some versions of FreeBSD have perl5 as part of the base system while others do not.) Notes on dependencies As mentioned above, the default target to call when a dependency is required is DEPENDS_TARGET. It defaults to install. This is a user variable; it is never defined in a port's Makefile. If your port needs a special way to handle a dependency, use the :target part of the *_DEPENDS variables instead of redefining DEPENDS_TARGET. When you type make clean, its dependencies are automatically cleaned too. If you do not wish this to happen, define the variable NOCLEANDEPENDS in your environment. This may be particularly desirable if the port has something that takes a long time to rebuild in its dependency list, such as KDE, GNOME or Mozilla. To depend on another port unconditionally, use the variable ${NONEXISTENT} as the first field of BUILD_DEPENDS or RUN_DEPENDS. Use this only when you need to get the source of the other port. You can often save compilation time by specifying the target too. For instance BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract will always descend to the jpeg port and extract it. Do not use DEPENDS unless there is no other way the behavior you want can be accomplished. It will cause the other port to always be built (and installed, by default), and the dependency will go into the packages as well. If this is really what you need, you should probably write it as BUILD_DEPENDS and RUN_DEPENDS instead—at least the intention will be clear. Circular dependencies are fatal Do not introduce any circular dependencies into the ports tree! The ports building technology does not tolerate circular dependencies. If you introduce one, you will have someone, somewhere in the world, whose FreeBSD installation will break almost immediately, with many others quickly to follow. These can really be hard to detect; if in doubt, before you make that change, make sure you have done the following: cd /usr/ports; make index. That process can be quite slow on older machines, but you may be able to save a large number of people—including yourself— a lot of grief in the process. Makefile Options Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Examples include choice of natural (human) language, GUI versus command-line, or type of database to support. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to control which configuration should be built. Supporting these properly will make users happy, and effectively provide 2 or more ports for the price of one. <makevar>WITH_<replaceable>*</replaceable></makevar> and <makevar>WITHOUT_<replaceable>*</replaceable></makevar> These variables are designed to be set by the system administrator. There are many that are standardized in ports/Mk/bsd.*.mk; others are not, which can be confusing. If you need to add such a configuration variable, please consider using one of the ones from the following list. You should not assume that a WITH_* necessarily has a corresponding WITHOUT_* variable and vice versa. In general, the default is simply assumed. Unless otherwise specified, these variables are only tested for being set or not set, rather than being set to some kind of variable such as YES or NO. The <makevar>WITH_<replaceable>*</replaceable></makevar> and <makevar>WITHOUT_<replaceable>*</replaceable></makevar> variables Variable Means WITH_APACHE2 If set, use www/apache2 instead of the default of www/apache. WITH_BERKELEY_DB Define this variable to specify the ability to use a variant of the Berkeley database package such as databases/db41. An associated variable, WITH_BDB_VER, may be set to values such as 2, 3, 4, 41 or 42. WITH_MYSQL Define this variable to specify the ability to use a variant of the MySQL database package such as databases/mysql40-server. An associated variable, WANT_MYSQL_VER, may be set to values such as 323, 40, 41, or 50. WITHOUT_NLS If set, says that internationalization is not needed, which can save compile time. By default, internalization is used. WITH_OPENSSL_BASE Use the version of OpenSSL in the base system. WITH_OPENSSL_PORT Use the version of OpenSSL from security/openssh, overwriting the version that was originally installed in the base system. WITH_POSTGRESQL Define this variable to specify the ability to use a variant of the PostGreSQL database package such as databases/postgresql72. WITHOUT_X11 If the port can be built both with and without X support, then it should normally be built with with X support. If this variable is defined, then then the version that does not have X support should be built instead.
Specifying the working directory Each port is extracted in to a working directory, which must be writable. The ports system defaults to having the DISTFILES unpack in to a directory called ${DISTNAME}. In other words, if you have set: PORTNAME= foo PORTVERSION= 1.0 then the port's distribution files contain a top-level directory, foo-1.0, and the rest of the files are located under that directory. There are a number of variables you can override if that is not the case. <makevar>WRKSRC</makevar> The variable lists the name of the directory that is created when the application's distfiles are extracted. If our previous example extracted into a directory called foo (and not foo-1.0) you would write: WRKSRC= ${WRKDIR}/foo or possibly WRKSRC= ${WRKDIR}/${PORTNAME} <makevar>NO_WRKSUBDIR</makevar> If the port does not extract in to a subdirectory at all then you should set NO_WRKSUBDIR to indicate that. NO_WRKSUBDIR= yes <makevar>CONFLICTS</makevar> If your package cannot coexist with other packages (because of file conflicts, runtime incompatibility, etc.), list the other package names in the CONFLICTS variable. You can use shell globs like * and ? here. Packages names should be enumerated the same way they appear in /var/db/pkg. Please make sure that CONFLICTS does not match this port's package itself, or else forcing its installation with FORCE_PKG_REGISTER will no longer work. Building mechanisms If your package uses GNU make, set USE_GMAKE=yes. If your package uses configure, set HAS_CONFIGURE=yes. If your package uses GNU configure, set GNU_CONFIGURE=yes (this implies HAS_CONFIGURE). If you want to give some extra arguments to configure (the default argument list --prefix=${PREFIX} for GNU configure and empty for non-GNU configure), set those extra arguments in CONFIGURE_ARGS. If your package uses GNU autoconf, set USE_AUTOCONF_VER=213. This implies GNU_CONFIGURE, and will cause autoconf to be run before configure. If your package uses GNU configure, and the resulting executable file has a strange name like i386-portbld-freebsd4.7-appname, you will need to additionally override the CONFIGURE_TARGET variable to specify the target in the way required by scripts generated by recent versions of autoconf. Add the following line immediately after the GNU_CONFIGURE=yes line in your Makefile: CONFIGURE_TARGET=--build=${MACHINE_ARCH}-portbld-freebsd${OSREL} If your package is an X application that creates Makefiles from Imakefiles using imake, then set USE_IMAKE=yes. This will cause the configure stage to automatically do an xmkmf -a. If the flag is a problem for your port, set XMKMF=xmkmf. If the port uses imake but does not understand the install.man target, NO_INSTALL_MANPAGES=yes should be set. In addition, the author of the original port should be shot. :-> If your port's source Makefile has something else than all as the main build target, set ALL_TARGET accordingly. Same goes for install and INSTALL_TARGET. Special considerations There are some more things you have to take into account when you create a port. This section explains the most common of those. Shared Libraries If your port installs one or more shared libraries, define a INSTALLS_SHLIB make variable, which will instruct a bsd.port.mk to run ${LDCONFIG} -m on the directory where the new library is installed (usually PREFIX/lib) during post-install target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate @exec /sbin/ldconfig -m and @unexec /sbin/ldconfig -R pair into your pkg-plist file, so that a user who installed the package can start using the shared library immediately and de-installation will not cause the system to still believe the library is there. If you need, you can override the default location where the new library is installed by defining the LDCONFIG_DIRS make variable, which should contain a list of directories into which shared libraries are to be installed. For example if your port installs shared libraries into PREFIX/lib/foo and PREFIX/lib/bar directories you could use the following in your Makefile: INSTALLS_SHLIB= yes LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar Note that content of LDCONFIG_DIRS is passed through &man.sed.1; just like the rest of pkg-plist, so PLIST_SUB substitutions also apply here. It is recommended that you use %%PREFIX%% for PREFIX, %%LOCALBASE%% for LOCALBASE and %%X11BASE%% for X11BASE. Ports with distribution restrictions Licenses vary, and some of them place restrictions on how the application can be packaged, whether it can be sold for profit, and so on. It is your responsibility as a porter to read the licensing terms of the software and make sure that the FreeBSD project will not be held accountable for violating them by redistributing the source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt, please contact the &a.ports;. In situations like this, the variables described in the following sections can be set. <makevar>NO_PACKAGE</makevar> This variable indicates that we may not generate a binary package of the application. For instance, the license may disallow binary redistribution, or it may prohibit distribution of packages created from patched sources. However, the port's DISTFILES may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless NO_CDROM is set as well. NO_PACKAGE should also be used if the binary package is not generally useful, and the application should always be compiled from the source code. For example, if the application has configuration information that is site specific hard coded in to it at compile time, set NO_PACKAGE. NO_PACKAGE should be set to a string describing the reason why the package should not be generated. <makevar>NO_CDROM</makevar> This variable alone indicates that, although we are allowed to generate binary packages, we may put neither those packages nor the port's DISTFILES onto a CD-ROM (or similar media) for resale. However, the binary packages and the port's DISTFILES will still be available via FTP/HTTP. If this variable is set along with NO_PACKAGE, then only the port's DISTFILES will be available, and only via FTP/HTTP. NO_CDROM should be set to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, this should be used if the port's license is for non-commercial use only. <makevar>RESTRICTED</makevar> Set this variable alone if the application's license permits neither mirroring the application's DISTFILES nor distributing the binary package in any way. NO_CDROM or NO_PACKAGE should not be set along with RESTRICTED since the latter variable implies the former ones. RESTRICTED should be set to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download the DISTFILES, possibly after registering for the software or agreeing to accept the terms of an EULA. <makevar>RESTRICTED_FILES</makevar> When RESTRICTED or NO_CDROM is set, this variable defaults to ${DISTFILES} ${PATCHFILES}, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them. Note that the port committer should add an entry to /usr/ports/LEGAL for every listed distribution file, describing exactly what the restriction entails. Using <literal>perl</literal> Variables for ports that use <literal>perl</literal> Variable Means USE_PERL5 Says that the port uses perl 5 to build and run. USE_PERL5_BUILD Says that the port uses perl 5 to build. USE_PERL5_RUN Says that the port uses perl 5 to run. PERL The full path of perl 5, either in the system or installed from a port, but without the version number. Use this if you need to replace #!lines in scripts. PERL_CONFIGURE Configure using Perl's MakeMaker. It implies USE_PERL5. Read only variables PERL_VERSION The full version of perl installed (e.g., 5.00503). PERL_VER The short version of perl installed (e.g., 5.005). PERL_LEVEL The installed perl version as an integer of the form MNNNPP (e.g., 500503). PERL_ARCH Where perl stores architecture dependent libraries. Defaults to ${ARCH}-freebsd. PERL_PORT Name of the perl port that is installed (e.g., perl5). SITE_PERL Directory name where site specific perl packages go. This value is added to PLIST_SUB.
Using X11 Variables for ports that use X USE_X_PREFIX The port installs in X11BASE, not PREFIX. USE_XLIB The port uses the X libraries. USE_MOTIF The port uses the Motif toolkit. Implies USE_XPM. USE_IMAKE The port uses imake. Implies USE_X_PREFIX. XMKMF Set to the path of xmkmf if not in the PATH. Defaults to xmkmf -a.
Using <command>automake</command>, <command>autoconf</command>, and <command>libtool</command> Variables for ports that use automake, autoconf or libtool Variable Means AUTOMAKE The full path for automake if it is not in the PATH. USE_AUTOMAKE_VER The port uses automake. Valid values for this variable are 14 and 15, and sets the AUTOMAKE_DIR and ACLOCAL_DIR variables appropriately. AUTOMAKE_ARGS One or more command line arguments to pass to AUTOMAKE if USE_AUTOMAKE_VER is set. AUTOMAKE_ENV One or more environment variables to set (and their values) before running AUTOMAKE. ACLOCAL Set to the path of the GNU aclocal if it is not in the PATH. The default is set according to the USE_AUTOMAKE_VER variable. ACLOCAL_DIR Set to the path of the GNU aclocal shared directory. The default is set according to the USE_AUTOMAKE_VER variable. AUTOMAKE_DIR Set to the path of the GNU automake shared directory. The default is set according to the USE_AUTOMAKE_VER variable. USE_AUTOCONF_VER Specifies that the port uses autoconf. Implies GNU_CONFIGURE. The default value is 213. AUTOCONF Set to the path of GNU autoconf if it is not in the PATH. The default is set according to the USE_AUTOCONF_VER variable. AUTOCONF_ARGS Command line arguments to pass to autoconf. AUTOCONF_ENV Set these variable=value pairs in the environment before running autoconf. USE_AUTOHEADER_VER Specifies that the port uses autoheader. Implies USE_AUTOCONF_VER. The default value is 213. AUTOHEADER Set to the path of GNU autoheader if it is not in the PATH. The default is set according to USE_AUTOCONF_VER. AUTORECONF Set to the path of GNU autoreconf if it is not in the PATH. The default is set according to USE_AUTOCONF_VER. AUTOSCAN Set to the path of GNU autoscan if it is not set in the PATH. The default is set according to USE_AUTOCONF_VER. AUTOIFNAMES Set to the path of GNU autoifnames if it is not set in the PATH. The default is set according to USE_AUTOCONF_VER. USE_LIBTOOL_VER The port uses libtool. Implies GNU_CONFIGURE. The default value is 13. LIBTOOL Set to the path of libtool if it is not set in the PATH. LIBTOOLFILES The files to patch for libtool. Defaults to aclocal.m4 if USE_AUTOCONF is defined, configure otherwise. LIBTOOLFLAGS Additional flags to pass to ltconfig. Defaults to --disable-ltlibs.
Using GNOME The FreeBSD/GNOME project uses its own set of variables to define which GNOME components a particular port uses. A comprehensive list of these variables exists within the FreeBSD/GNOME project's homepage. Using KDE Variables for ports that use KDE USE_QT_VER The port uses the Qt toolkit. Possible values are 1 and 3; each specify the major version of Qt to use. Sets both MOC and QTCPPFLAGSto default appropriate values. USE_KDELIBS_VER The port uses KDE libraries. Possible values are 3; each specify the major version of KDE to use. Implies USE_QT_VER of the appropriate version. USE_KDEBASE_VER The port uses KDE base. Possible values are 3; each specify the major version of KDE to use. Implies USE_KDELIBS_VER of the appropriate version. MOC Set to the path of moc. Default set according to USE_QT_VER value. QTCPPFLAGS Set the CPPFLAGS to use when processing Qt code. Default set according to USE_QT_VER value.
Using Bison This section is yet to be written. Using Java Variable definitions If your port needs a Java™ Development Kit (JDK) to either build, run or even extract the distfile, then it should define USE_JAVA. There are several JDKs in the ports collection, from various vendors, and in several versions. If your port must use one of these versions, you can define which one. The most current version is java/jdk14. Variables that may be set by ports that use Java Variable Means USE_JAVA Should be defined for the remaining variables to have any effect. JAVA_VERSION List of space-separated suitable Java versions for the port. An optional "+" allows you to specify a range of versions (allowed values: 1.1[+] 1.2[+] 1.3[+] 1.4[+]). JAVA_OS List of space-separated suitable JDK port operating systems for the port (allowed values: native linux). JAVA_VENDOR List of space-separated suitable JDK port vendors for the port (allowed values: freebsd bsdjava sun ibm blackdown). JAVA_BUILD When set, it means that the selected JDK port should be added to the build dependencies of the port. JAVA_RUN When set, it means that the selected JDK port should be added to the run dependencies of the port. JAVA_EXTRACT When set, it means that the selected JDK port should be added to the extract dependencies of the port. USE_JIKES Whether the port should or should not use the jikes bytecode compiler to build. When no value is set for this variable, the port will use jikes to build if available. You may also explicitely forbid or enforce the use of jikes (by setting 'no' or 'yes'). In the later case, devel/jikes will be added to build dependencies of the port.
Below is the list of all settings a port will receive after setting USE_JAVA: Variables provided to ports that use Java Variable Value JAVA_PORT The name of the JDK port (e.g. 'java/jdk14'). JAVA_PORT_VERSION The full version of the JDK port (e.g. '1.4.2'). If you only need the first two digits of this version number, use ${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}. JAVA_PORT_OS The operating system used by the JDK port (e.g. 'linux'). JAVA_PORT_VENDOR The vendor of the JDK port (e.g. 'sun'). JAVA_PORT_OS_DESCRIPTION Description of the operating system used by the JDK port (e.g. 'Linux'). JAVA_PORT_VENDOR_DESCRIPTION Description of the vendor of the JDK port (e.g. 'FreeBSD Foundation'). JAVA_HOME Path to the installation directory of the JDK (e.g. '/usr/local/jdk1.3.1'). JAVAC Path to the Java compiler to use (e.g. '/usr/local/jdk1.1.8/bin/javac' or '/usr/local/bin/jikes'). JAR Path to the jar tool to use (e.g. '/usr/local/jdk1.2.2/bin/jar' or '/usr/local/bin/fastjar'). APPLETVIEWER Path to the appletviewer utility (e.g. '/usr/local/linux-jdk1.2.2/bin/appletviewer'). JAVA Path to the java executable. Use this for executing Java programs (e.g. '/usr/local/jdk1.3.1/bin/java'). JAVADOC Path to the javadoc utility program. JAVAH Path to the javah program. JAVAP Path to the javap program. JAVA_KEYTOOL Path to the keytool utility program. This variable is availble only if the JDK is Java 1.2 or higher. JAVA_N2A Path to the native2ascii tool. JAVA_POLICYTOOL Path to the policytool program. This variable is available only if the JDK is Java 1.2 or higher. JAVA_SERIALVER Path to the serialver utility program. RMIC Path to the RMI stub/skeleton generator, rmic. RMIREGISTRY Path to the RMI registry program, rmiregistry. RMID Path to the RMI daemon program rmid. This variable is only available if the JDK is Java 1.2 or higher. JAVA_CLASSES Path to the archive that contains the JDK class files. On JDK 1.2 or later, this is ${JAVA_HOME}/jre/lib/rt.jar. Earlier JDKs used ${JAVA_HOME}/lib/classes.zip.
You may use the java-debug make target to get information for debugging your port. It will display the value of many of the forecited variables. Additionally, the following constants are defined so all Java ports may be installed in a consistent way: Constants defined for ports that use Java Constant Value JAVASHAREDIR The base directory for everything related to Java. Default: ${PREFIX}/share/java. JAVAJARDIR The directory where JAR files should be installed. Default: ${JAVASHAREDIR}/classes.
Best practices When porting a Java library, your port should install the JAR file(s) in ${JAVAJARDIR}, and everything else under ${JAVASHAREDIR}/${PORTNAME} (except for the documentation, see below). In order to reduce the packing file size, you may reference the JAR file(s) directly in the Makefile. Just use the following statement (where myport.jar is the name of the JAR file installed as part of the port): PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar When porting a Java application, the port usually installs everything under a single directory (including its JAR dependencies). The use of ${JAVASHAREDIR}/${PORTNAME} is strongly encouraged in this regard. It is up the porter to decide whether the port should install the additional JAR dependencies under this directory or directly use the already installed ones (from ${JAVAJARDIR}). Regardless of the type of your port (library or application), the additional documentation should be installed in the same location as for any other port. The JavaDoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list (pkg-plist). This is one reason why porters are strongly encouraged to use the PORTDOCS macro. Moreover, even if you can predict the set of files that will be generated by javadoc, the size of the resulting pkg-plist advocates for the use of PORTDOCS. The default value for DATADIR is ${PREFIX}/share/${PORTNAME}. It is a good idea to override DATADIR to ${JAVASHAREDIR}/${PORTNAME} for Java ports. Indeed, DATADIR is automatically addded to PLIST_SUB (documented here) so you may use %%DATADIR%% directly in pkg-plist. As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the &os; Java Project encourage porters to have their ports built from source whenever it is a trivial task. All the features that have been presented in this section are implemented in bsd.java.mk. If you ever think that your port needs more sophisticated Java support, please first have a look at the bsd.java.mk CVS log as it usually takes some time to document the latest features. Then, if you think the support you are lacking would be beneficial to many other Java ports, feel free to discuss it on the &a.java;. Although there is a java category for PRs, it refers to the JDK porting effort from the &os; Java project. Therefore, you should submit your Java port in the ports category as for any other port, unless the issue you are trying to resolve is related to either a JDK implementation or bsd.java.mk. Using Python This section is yet to be written. Using Emacs This section is yet to be written. Using Ruby This section is yet to be written. Using SDL The USE_SDL variable is used to autoconfigure the dependencies for ports which use an SDL based library like devel/sdl12 and x11-toolkits/sdl_gui. The following SDL libraries are recognized at the moment: sdl: devel/sdl12 gfx: graphics/sdl_gfx gui: x11-toolkits/sdl_gui image: graphics/sdl_image ldbad: devel/sdl_ldbad mixer: audio/sdl_mixer mm: devel/sdlmm net: net/sdl_net sound: audio/sdl_sound ttf: graphics/sdl_ttf Therefore, if a port has a dependency on net/sdl_net and audio/sdl_mixer, the syntax will be: USE_SDL= net mixer The dependency devel/sdl12, which is required by net/sdl_net and audio/sdl_mixer, is automatically added as well. If you use USE_SDL, it will automatically: Add a dependency on sdl12-config to BUILD_DEPENDS Add the variable SDL_CONFIG to CONFIGURE_ENV Add the dependencies of the selected libraries to the LIB_DEPENDS To check whether an SDL library is available, you can do it with the WANT_SDL variable: WANT_SDL=yes .include <bsd.port.pre.mk> .if ${HAVE_SDL:Mmixer}!="" USE_SDL+= mixer .endif .include <bsd.port.post.mk> <makevar>MASTERDIR</makevar> If your port needs to build slightly different versions of packages by having a variable (for instance, resolution, or paper size) take different values, create one subdirectory per package to make it easier for users to see what to do, but try to share as many files as possible between ports. Typically you only need a very short Makefile in all but one of the directories if you use variables cleverly. In the sole Makefile, you can use MASTERDIR to specify the directory where the rest of the files are. Also, use a variable as part of PKGNAMESUFFIX so the packages will have different names. This will be best demonstrated by an example. This is part of japanese/xdvi300/Makefile; PORTNAME= xdvi PORTVERSION= 17 PKGNAMEPREFIX= ja- PKGNAMESUFFIX= ${RESOLUTION} : # default RESOLUTION?= 300 .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ ${RESOLUTION} != 300 && ${RESOLUTION} != 400 @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." @${FALSE} .endif japanese/xdvi300 also has all the regular patches, package files, etc. If you type make there, it will take the default value for the resolution (300) and build the port normally. As for other resolutions, this is the entire xdvi118/Makefile: RESOLUTION= 118 MASTERDIR= ${.CURDIR}/../xdvi300 .include "${MASTERDIR}/Makefile" (xdvi240/Makefile and xdvi400/Makefile are similar). The MASTERDIR definition tells bsd.port.mk that the regular set of subdirectories like FILESDIR and SCRIPTDIR are to be found under xdvi300. The RESOLUTION=118 line will override the RESOLUTION=300 line in xdvi300/Makefile and the port will be built with resolution set to 118. Shared library versions Please read our policy on shared library versioning to understand what to do with shared library versions in general. Do not blindly assume software authors know what they are doing; many of them do not. It is very important that these details are carefully considered, as we have quite a unique situation where we are trying to have dozens of potentially incompatible software pairs co-exist. Careless port imports have caused great trouble regarding shared libraries in the past (ever wondered why the port jpeg-6b has a shared library version of 9?). If in doubt, send a message to the &a.ports;. Most of the time, your job ends by determining the right shared library version and making appropriate patches to implement it. Manpages The MAN[1-9LN] variables will automatically add any manpages to pkg-plist (this means you must not list manpages in the pkg-plist—see generating PLIST for more). It also makes the install stage automatically compress or uncompress manpages depending on the setting of NOMANCOMPRESS in /etc/make.conf. If your port tries to install multiple names for manpages using symlinks or hardlinks, you must use the MLINKS variable to identify these. The link installed by your port will be destroyed and recreated by bsd.port.mk to make sure it points to the correct file. Any manpages listed in MLINKS must not be listed in the pkg-plist. To specify whether the manpages are compressed upon installation, use the MANCOMPRESSED variable. This variable can take three values, yes, no and maybe. yes means manpages are already installed compressed, no means they are not, and maybe means the software already respects the value of NOMANCOMPRESS so bsd.port.mk does not have to do anything special. MANCOMPRESSED is automatically set to yes if USE_IMAKE is set and NO_INSTALL_MANPAGES is not set, and to no otherwise. You do not have to explicitly define it unless the default is not suitable for your port. If your port anchors its man tree somewhere other than PREFIX, you can use the MANPREFIX to set it. Also, if only manpages in certain sections go in a non-standard place, such as some perl modules ports, you can set individual man paths using MANsectPREFIX (where sect is one of 1-9, L or N). If your manpages go to language-specific subdirectories, set the name of the languages to MANLANG. The value of this variable defaults to "" (i.e., English only). Here is an example that puts it all together. MAN1= foo.1 MAN3= bar.3 MAN4= baz.4 MLINKS= foo.1 alt-name.8 MANLANG= "" ja MAN3PREFIX= ${PREFIX}/share/foobar MANCOMPRESSED= yes This states that six files are installed by this port; ${PREFIX}/man/man1/foo.1.gz ${PREFIX}/man/ja/man1/foo.1.gz ${PREFIX}/share/foobar/man/man3/bar.3.gz ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz ${PREFIX}/man/man4/baz.4.gz ${PREFIX}/man/ja/man4/baz.4.gz Additionally ${PREFIX}/man/man8/alt-name.8.gz may or may not be installed by your port. Regardless, a symlink will be made to join the foo(1) manpage and alt-name(8) manpage. Ports that require Motif There are many programs that require a Motif library (available from several commercial vendors, while there is a free clone reported to be able to run many applications in x11-toolkits/lesstif) to compile. Since it is a popular toolkit and their licenses usually permit redistribution of statically linked binaries, we have made special provisions for handling ports that require Motif in a way that we can easily compile binaries linked either dynamically (for people who are compiling from the port) or statically (for people who distribute packages). <makevar>USE_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who do not own a copy of Motif from even attempting to build it. <makevar>MOTIFLIB</makevar> This variable will be set by bsd.port.mk to be the appropriate reference to the Motif library. Please patch the source of your port to reference this wherever the Motif library is referenced in the Makefile or Imakefile. There are two common cases: If the port refers to the Motif library as -lXm in its Makefile or Imakefile, simply substitute ${MOTIFLIB} for it. If the port uses XmClientLibs in its Imakefile, change it to ${MOTIFLIB} ${XTOOLLIB} ${XLIB}. Note that MOTIFLIB (usually) expands to -L/usr/X11R6/lib -lXm or /usr/X11R6/lib/libXm.a, so there is no need to add -L or -l in front. X11 fonts If your port installs fonts for the X Window System, put them in X11BASE/lib/X11/fonts/local. This directory was new to XFree86 3.3.3. If it does not exist, please create it, and print out a message urging the user to update their XFree86 to 3.3.3 or newer, or at least add this directory to the font path in /etc/XF86Config. Info files If your package needs to install GNU info files, they should be listed in the INFO variable (without the trailing .info), and appropriate installation/de-installation code will be automatically added to the temporary pkg-plist before package registration. The <filename>pkg-<replaceable>*</replaceable></filename> files There are some tricks we have not mentioned yet about the pkg-* files that come in handy sometimes. <filename>pkg-message</filename> If you need to display a message to the installer, you may place the message in pkg-message. This capability is often useful to display additional installation steps to be taken after a &man.pkg.add.1; or to display licensing information. The pkg-message file does not need to be added to pkg-plist. Also, it will not get automatically printed if the user is using the port, not the package, so you should probably display it from the post-install target yourself. <filename>pkg-install</filename> If your port needs to execute commands when the binary package is installed with &man.pkg.add.1; you can do this via the pkg-install script. This script will automatically be added to the package, and will be run twice by &man.pkg.add.1;: the first time as ${SH} pkg-install ${PKGNAME} PRE-INSTALL and the second time as ${SH} pkg-install ${PKGNAME} POST-INSTALL. $2 can be tested to determine which mode the script is being run in. The PKG_PREFIX environmental variable will be set to the package installation directory. See &man.pkg.add.1; for additional information. This script is not run automatically if you install the port with make install. If you are depending on it being run, you will have to explicitly call it from your port's Makefile. <filename>pkg-deinstall</filename> This script executes when a package is removed. This script will be run twice by &man.pkg.delete.1;. The first time as ${SH} pkg-install ${PKGNAME} DEINSTALL and the second time as ${SH} pkg-install ${PKGNAME} POST-DEINSTALL. <filename>pkg-req</filename> If your port needs to determine if it should install or not, you can create a pkg-req requirements script. It will be invoked automatically at installation/de-installation time to determine whether or not installation/de-installation should proceed. The script will be run at installation time by &man.pkg.add.1; as pkg-req ${PKGNAME} INSTALL. At de-installation time it will be run by &man.pkg.delete.1; as pkg-req ${PKGNAME} DEINSTALL. Changing <filename>pkg-plist</filename> based on make variables Some ports, particularly the p5- ports, need to change their pkg-plist depending on what options they are configured with (or version of perl, in the case of p5- ports). To make this easy, any instances in the pkg-plist of %%OSREL%%, %%PERL_VER%%, and %%PERL_VERSION%% will be substituted for appropriately. The value of %%OSREL%% is the numeric revision of the operating system (e.g., 4.9). %%PERL_VERSION%% is the full version number of perl (e.g., 5.00502) and %%PERL_VER%% is the perl version number minus the patchlevel (e.g., 5.005). Several other %%VARS%% related to port's documentation files are described in the relevant section. If you need to make other substitutions, you can set the PLIST_SUB variable with a list of VAR=VALUE pairs and instances of %%VAR%% will be substituted with VALUE in the pkg-plist. For instance, if you have a port that installs many files in a version-specific subdirectory, you can put something like OCTAVE_VERSION= 2.0.13 PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} in the Makefile and use %%OCTAVE_VERSION%% wherever the version shows up in pkg-plist. That way, when you upgrade the port, you will not have to change dozens (or in some cases, hundreds) of lines in the pkg-plist. This substitution (as well as addition of any manual pages) will be done between the pre-install and do-install targets, by reading from PLIST and writing to TMPPLIST (default: WRKDIR/.PLIST.mktmp). So if your port builds PLIST on the fly, do so in or before pre-install. Also, if your port needs to edit the resulting file, do so in post-install to a file named TMPPLIST. Another possibility to modify port's packing list is based on setting the variables PLIST_FILES and PLIST_DIRS. The value of each variable is regarded as a list of pathnames to write to TMPPLIST along with PLIST contents. Names listed in PLIST_FILES and PLIST_DIRS are subject to %%VAR%% substitution, as described above. Except for that, names from PLIST_FILES will appear in the final packing list unchanged, while @dirrm will be prepended to names from PLIST_DIRS. To take effect, PLIST_FILES and PLIST_DIRS must be set before TMPPLIST is written, i.e. in pre-install or earlier. Changing the names of <filename>pkg-<replaceable>*</replaceable></filename> files All the names of pkg-* files are defined using variables so you can change them in your Makefile if need be. This is especially useful when you are sharing the same pkg-* files among several ports or have to write to one of the above files (see writing to places other than WRKDIR for why it is a bad idea to write directly into the pkg-* subdirectory). Here is a list of variable names and their default values. (PKGDIR defaults to ${MASTERDIR}.) Variable Default value DESCR ${PKGDIR}/pkg-descr PLIST ${PKGDIR}/pkg-plist PKGINSTALL ${PKGDIR}/pkg-install PKGDEINSTALL ${PKGDIR}/pkg-deinstall PKGREQ ${PKGDIR}/pkg-req PKGMESSAGE ${PKGDIR}/pkg-message Please change these variables rather than overriding PKG_ARGS. If you change PKG_ARGS, those files will not correctly be installed in /var/db/pkg upon install from a port. Testing your port Running <command>make describe</command> Several of the &os; port maintainance tools, such as &man.portupgrade.1;, rely on a database called /usr/ports/INDEX which keeps track of such items as port dependencies. INDEX is created by the top-level ports/Makefile via make index, which descends into each port subdirectory and executes make describe there. Thus, if make describe fails in any port, no one can generate INDEX, and many people will quickly become unhappy. It is important to be able to generate this file no matter what options are present in make.conf, so please avoid doing things such as using .error statements when (for instance) a dependency is not satisfied. How to avoid using <literal>.error</literal> Assume that someone has the line USE_POINTYHAT=yes in make.conf. The first of the next two Makefile snippets will cause make index to fail, while the second one will not: .if USE_POINTYHAT .error "POINTYHAT is not supported" .endif .if USE_POINTYHAT IGNORE=POINTYHAT is not supported .endif If make describe produces a string rather than an error message, you are probably safe. See bsd.port.mk for the meaning of the string produced. Also note that running a recent version of portlint (as specified in the next section) will cause make describe to be run automatically. Portlint Do check your work with portlint before you submit or commit it. portlint warns you about many common errors, both functional and stylistic. For a new (or repocopied) port, portlint -A is the most thorough; for an existing port, portlint -C is sufficient. Since portlint uses heuristics to try to figure out errors, it can produce false positive warnings. In addition, occasionally something that is flagged as a problem really cannot be done in any other way due to limitations in the ports framework. When in doubt, the best thing to do is ask on &a.ports;. <makevar>PREFIX</makevar> Do try to make your port install relative to PREFIX. (The value of this variable will be set to LOCALBASE (default /usr/local), unless USE_X_PREFIX or USE_IMAKE is set, in which case it will be X11BASE (default /usr/X11R6). Avoiding the hard-coding of /usr/local or /usr/X11R6 anywhere in the source will make the port much more flexible and able to cater to the needs of other sites. For X ports that use imake, this is automatic; otherwise, this can often be done by simply replacing the occurrences of /usr/local (or /usr/X11R6 for X ports that do not use imake) in the various scripts/Makefiles in the port to read ${PREFIX}, as this variable is automatically passed down to every stage of the build and install processes. Make sure your application is not installing things in /usr/local instead of PREFIX. A quick test for this is to do this is: &prompt.root; make clean; make package PREFIX=/var/tmp/port-name If anything is installed outside of PREFIX, the package creation process will complain that it cannot find the files. This does not test for the existence of internal references, or correct use of LOCALBASE for references to files from other ports. Testing the installation in /var/tmp/port-name to do that while you have it installed would do that. Do not set USE_X_PREFIX unless your port truly requires it (i.e., it links against X libs or it needs to reference files in X11BASE). The variable PREFIX can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the Makefiles. Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro PAGER to be the full pathname of less, use the compiler flag: -DPAGER=\"${PREFIX}/bin/less\" or -DPAGER=\"${LOCALBASE}/bin/less\" if this is an X port, instead of -DPAGER=\"/usr/local/bin/less\". This way it will have a better chance of working if the system administrator has moved the whole /usr/local tree somewhere else. Upgrading When you notice that a port is out of date compared to the latest version from the original authors, you should first ensure that you have the latest port. You can find them in the ports/ports-current directory of the &os; FTP mirror sites. However, if you are working with more than a few ports, you will probably find it easier to use CVSup to keep your whole ports collection up-to-date, as described in the Handbook. This will have the added benefit of tracking all the ports' dependencies. The next step is to see if there is an update already pending. To do this, you have two options. There is a searchable interface to the FreeBSD Problem Report (PR) database (also known as GNATS). Select ports in the dropdown, and enter the name of the port. However, sometimes people forget to put the name of the port into the Synopsis field in an unambiguous fashion. In that case, you can try the FreeBSD Ports Monitoring System (also known as portsmon). This system attempts to classify port PRs by portname. To search for PRs about a particular port, use the Overview of One Port. If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by make maintainer. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version); you would not want to duplicate their work. Note that unmaintained ports are listed with a maintainer of ports@FreeBSD.org, which is just the general ports mailing list, so sending mail there probably will not help in this case. If the maintainer asks you to do the upgrade or there is no maintainer, then you have a chance to help out &os; by preparing the update yourself! Please make the changes and save the result of the recursive diff output of the new and old ports directories (e.g., if your modified port directory is called superedit and the original is in our tree as superedit.bak, then save the result of diff -ruN superedit.bak superedit). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the -N option—this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. To simplify common operations with patch files, you can use /usr/ports/Tools/scripts/patchtool.py. Before using it, please read /usr/ports/Tools/scripts/README.patchtool. If the port is unmaintained, and you are actively using it yourself, please consider volunteering to become its maintainer. &os; has over 2000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section.) The best way to send us the diff is by including it via &man.send-pr.1; (category ports). If you are volunteering to maintain the port, be sure to put [maintainer update] at the beginning of your synopsis line and set the Class of your PR to maintainer-update. Otherwise, the Class of your PR should be change-request. Please mention any added or deleted files in the message, as they have to be explicitly specified to &man.cvs.1; when doing a commit. If the diff is more than about 20KB, please compress and uuencode it; otherwise, just include it in the PR as is. Before you &man.send-pr.1;, you should review the Writing the problem report section in the Problem Reports article; it contains far more information about how to write useful problem reports. If your upgrade is motivated by security concerns or a serious fault in the currently committed port, please notify the &a.portmgr; to request immediate rebuilding and redistribution of your port's package. Unsuspecting users of &man.pkg.add.1; will otherwise continue to install the old version via pkg_add -r for several weeks. Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! Now that you have done all that, you will want to read about how to keep up-to-date in . Ports security Why security is so important Bugs are occasionally introduced to the software. Arguably, the most dangerous of them are those opening security vulnerabilities. From the technical viewpoint, such vulnerabilities are to be closed by exterminating the bugs that caused them. However, the policies for handling mere bugs and security vulnerabilities are very different. A typical small bug affects only those users who have enabled some combination of options triggering the bug. The developer will eventually release a patch followed by a new version of the software, free of the bug, but the majority of users will not take the trouble of upgrading immediately because the bug has never vexed them. A critical bug that may cause data loss represents a graver issue. Nevertheless, prudent users know that a lot of possible accidents, besides software bugs, are likely to lead to data loss, and so they make backups of important data; in addition, a critical bug will be discovered really soon. A security vulnerability is all different. First, it may remain unnoticed for years because often it does not cause software malfunction. Second, a malicious party can use it to gain unauthorized access to a vulnerable system, to destroy or alter sensitive data; and in the worst case the user will not even notice the harm caused. Third, exposing a vulnerable system often assists attackers to break into other systems that could not be compromised otherwise. Therefore closing a vulnerability alone is not enough: the audience should be notified of it in most clear and comprehensive manner, which will allow to evaluate the danger and take appropriate actions. Fixing security vulnerabilities While on the subject of ports and packages, a security vulnerability may initially appear in the original distribution or in the port files. In the former case, the original software developer is likely to release a patch or a new version instantly, and you will only need to update the port promptly with respect to the author's fix. If the fix is delayed for some reason, you should either mark the port as FORBIDDEN or introduce a patch file of your own to the port. In the case of a vulnerable port, just fix the port as soon as possible. In either case, the standard procedure for submitting your change should be followed unless you have rights to commit it directly to the ports tree. Being a ports committer is not enough to commit to an arbitrary port. Remember that ports usually have maintainers, whom you should respect. Please make sure that the port's revision is bumped as soon as the vulnerability has been closed. That is how the users who upgrade installed packages on a regular basis will see they need to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. PORTREVISION should be bumped unless PORTVERSION has changed in the course of correcting the vulnerability. That is you should bump PORTREVISION if you have added a patch file to the port, but you should not if you have updated the port to the latest software version and thus already touched PORTVERSION. Please refer to the corresponding section for more information. Keeping the community informed The VuXML database A very important and urgent step to take as early as a security vulnerability is discovered is to notify the community of port users about the jeopardy. Such notification serves two purposes. First, should the danger be really severe, it will be wise to apply an instant workaround, e.g., stop the affected network service or even deinstall the port completely, until the vulnerability is closed. Second, a lot of users tend to upgrade installed packages just occasionally. They will know from the notification that they must update the package without delay as soon as a corrected version is available. Given the huge number of ports in the tree, a security advisory cannot be issued on each incident without creating a flood and losing the attention of the audience by the time it comes to really serious matters. Therefore security vulnerabilities found in ports are recorded in the FreeBSD VuXML database. The Security Officer Team members are monitoring it for issues requiring their intervention. If you have committer rights, you can update the VuXML database by yourself. So you will both help the Security Officer Team and deliver the crucial information to the community earlier. However, if you are not a committer, or you believe you have found an exceptionally severe vulnerability, or whatever, please do not hesitate to contact the Security Officer Team directly as described on the FreeBSD Security Information page. All right, you elected the hard way. As it may be obvious from its title, the VuXML database is essentially an XML document. Its source file vuln.xml is kept right inside the port security/vuxml. Therefore the file's full pathname will be PORTSDIR/security/vuxml/vuln.xml. Each time you discover a security vulnerability in a port, please add an entry for it to that file. Until you are familiar with VuXML, the best thing you can do is to find an existing entry fitting your case, then copy it and use as a template. A short introduction to VuXML The full-blown XML is complex and far beyond the scope of this book. However, to gain basic insight on the structure of a VuXML entry, you need only the notion of tags. XML tag names are enclosed in angle brackets. Each opening <tag> must have a matching closing </tag>. Tags may be nested. If nesting, the inner tags must be closed before the outer ones. There is a hierarchy of tags, i.e. more complex rules of nesting them. Sounds very similar to HTML, doesn't it? The major difference is that XML is eXtensible, i.e. based on defining custom tags. Due to its intrinsic structure, XML puts otherwise amorphous data into shape. VuXML is particularly tailored to mark up descriptions of security vulnerabilities. Now let's consider a realistic VuXML entry: <vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <topic>Several vulnerabilities found in Foo</topic> <affects> <package> <name>foo</name> <name>foo-devel</name> <name>ja-foo</name> <range><ge>1.6</ge><lt>1.9</lt></range> <range><ge>2.*</ge><lt>2.4_1</lt></range> <range><eq>3.0b1</eq></range> </package> <package> <name>openfoo</name> <range><lt>1.10_7</lt></range> <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range> </package> </affects> <description> <body xmlns="http://www.w3.org/1999/xhtml"> <p>J. Random Hacker reports:</p> <blockquote cite="http://j.r.hacker.com/advisories/1"> <p>Several issues in the Foo software may be exploited via carefully crafted QUUX requests. These requests will permit the injection of Bar code, mumble theft, and the readability of the Foo administrator account.</p> </blockquote> </body> </description> <references> <freebsdsa>SA-10:75.foo</freebsdsa> <freebsdpr>ports/987654</freebsdpr> <cvename>CAN-2010-0201</cvename> <cvename>CAN-2010-0466</cvename> <bid>96298</bid> <certsa>CA-2010-99</certsa> <certvu>740169</certvu> <uscertsa>SA10-99A</uscertsa> <uscertta>SA10-99A</uscertta> <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <url>http://j.r.hacker.com/advisories/1</url> </references> <dates> <discovery>2010-05-25</discovery> <entry>2010-07-13</entry> <modified>2010-09-17</entry> </dates> </vuln> The tag names are supposed to be self-descriptive, so we shall take a closer look only at fields you will need to fill in by yourself: This is the top-level tag of a VuXML entry. It has a mandatory attribute, vid, specifying a universally unique identifier (UUID) for this entry (in quotes). You should generate a UUID for each new VuXML entry (and don't forget to substitute it for the template UUID unless you are writing the entry from scratch). You can use &man.uuidgen.1; in FreeBSD 5.x, or you may install the port devel/p5-Data-UUID and issue the following command: perl -MData::UUID -le 'print lc new Data::UUID->create_str' This is a one-line description of the issue found. The names of packages affected are listed there. Multiple names can be given since several packages may be based on a single master port or software product. This may include stable and development branches, localized versions, and slave ports featuring different choices of important build-time configuration options. It is your resposibility to find all such related packages when writing a VuXML entry. Keep in mind that make search name=foo is your friend. The primary points to look for are as follows: the foo-devel variant for a foo port; other variants with a suffix like -a4 (for print-related packages), -without-gui (for packages with X support disabled), or similar; jp-, ru-, zh-, and other possible localized variants in the corresponding national categories of the ports collection. Affected versions of the package(s) are specified there as one or more ranges using a combination of <lt>, <le>, <eq>, <ge>, and <gt> elements. The version ranges given should not overlap. In a range specification, * (asterisk) denotes the smallest version number. In particular, 2.* is less than 2.a. Therefore an asterisk may be used for a range to match all possible alpha, beta, and RC versions. For instance, <ge>2.*</ge><lt>3.*</lt> will selectively match every 2.x version while <ge>2.0</ge><lt>3.0</lt> will obviously not since the latter misses 2.r3 and matches 3.b. The above example specifies that affected are versions from 1.6 to 1.9 inclusive, versions 2.x before 2.4_1, and version 3.0b1. Several related package groups (essentially, ports) can be listed in the <affected> section. This can be used if several software products (say FooBar, FreeBar and OpenBar) grow from the same code base and still share its bugs and vulnerabilities. Note the difference from listing multiple names within a single <package> section. The version ranges should allow for PORTEPOCH and PORTREVISION if applicable. Please remember that according to the collation rules, a version with a non-zero PORTEPOCH is greater than any version without PORTEPOCH, e.g., 3.0,1 is greater than 3.1 or even than 8.9. This is a summary of the issue. XHTML is used in this field. At least enclosing <p> and </p> should appear. More complex mark-up may be used, but only for the sake of accuracy and clarity: No eye candy please. This section contains references to relevant documents. As many references as apply are encouraged. This is a FreeBSD security advisory. This is a FreeBSD problem report. This is a Mitre CVE identifier. This is a SecurityFocus Bug ID. This is a US-CERT security advisory. This is a US-CERT vulnerability note. This is a US-CERT Cyber Security Alert. This is a US-CERT Technical Cyber Security Alert. This is a URL to an archived posting in a mailing list. The attribute msgid is optional and may specify the message ID of the posting. This is a generic URL. It should be used only if none of the other reference categories apply. This is the date when the issue was disclosed (YYYY-MM-DD). This is the date when the entry was added (YYYY-MM-DD). This is the date when any information in the entry was last modified (YYYY-MM-DD). New entries must not include this field. It should be added upon editing an existing entry. Testing your changes to the VuXML database Assume you just wrote or filled in an entry for a vulnerability in the package clamav that has been fixed in version 0.65_7. As a prerequisite, you need to install fresh versions of the ports security/portaudit and security/portaudit-db. First, check whether there already is an entry for this vulnerability. If there were such entry, it would match the previous version of the package, 0.65_6: &prompt.user; packaudit &prompt.user; portaudit clamav-0.65_6 To run packaudit, you must have permission to write to its DATABASEDIR, typically /var/db/portaudit. If there is none found, you get the green light to add a new entry for this vulnerability. Now you can generate a brand-new UUID (assume it's 74a9541d-5d6c-11d8-80e3-0020ed76ef5a) and add your new entry to the VuXML database. Please verify its syntax after that as follows: &prompt.user; cd ${PORTSDIR}/security/vuxml && make validate You will need at least one of the following packages installed: textproc/libxml2, textproc/jade. Now rebuild the portaudit database from the VuXML file: &prompt.user; packaudit To verify that the <affected> section of your entry will match correct package(s), issue the following command: &prompt.user; portaudit -f /usr/ports/INDEX -r 74a9541d-5d6c-11d8-80e3-0020ed76ef5a Please refer to &man.portaudit.1; for better understanding of the command syntax. Make sure that your entry produces no spurious matches in the output. Now check whether the right package versions are matched by your entry: &prompt.user; portaudit clamav-0.65_6 clamav-0.65_7 Affected package: clamav-0.65_6 (matched by clamav<0.65_7) Type of problem: clamav remote denial-of-service. Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html> 1 problem(s) found. Obviously, the former version should match while the latter one should not. Finally, verify whether the web page generated from the VuXML database looks like expected: &prompt.user; mkdir -p ~/public_html/portaudit &prompt.user; packaudit &prompt.user; lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html If VuXML still scares you... As an easy alternative to writing VuXML, you may opt to add a single line to a different file with much simpler syntax, PORTSDIR/security/portaudit-db/database/portaudit.txt, which resides within the port security/portaudit-db, and send a request for review to the Security Officer Team as described on the FreeBSD Security Information page. A line in that file consists of four fields separated by |, a pipe character. The first field is a &man.pkg.version.1; pattern expression matching the vulnerable packages. The second field contains URLs to relevant information, separated by space characters. The third field is a one-line description of the issue. The fourth and last field is the entry's UUID. You may want take a closer look at existing entries in portaudit.txt before adding your first line to that file. Dos and Don'ts Introduction Here is a list of common dos and don'ts that you encounter during the porting process. You should check your own port against this list, but you can also check ports in the PR database that others have submitted. Submit any comments on ports you check as described in Bug Reports and General Commentary. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing. Stripping Binaries Do not strip binaries manually unless you have to. All binaries should be stripped, but the INSTALL_PROGRAM macro will install and strip a binary at the same time (see the next section). If you need to strip a file, but do not wish to use the INSTALL_PROGRAM macro, ${STRIP_CMD} will strip your program. This is typically done within the post-install target. For example: post-install: ${STRIP_CMD} ${PREFIX}/bin/xdl Use the &man.file.1; command on the installed executable to check whether the binary is stripped or not. If it does not say not stripped, it is stripped. Additionally, &man.strip.1; will not strip a previously stripped program; it will instead exit cleanly. INSTALL_* macros Do use the macros provided in bsd.port.mk to ensure correct modes and ownership of files in your own *-install targets. INSTALL_PROGRAM is a command to install binary executables. INSTALL_SCRIPT is a command to install executable scripts. INSTALL_DATA is a command to install sharable data. INSTALL_MAN is a command to install manpages and other documentation (it does not compress anything). These are basically the install command with all the appropriate flags. See below for an example on how to use them. <makevar>WRKDIR</makevar> Do not write anything to files outside WRKDIR. WRKDIR is the only place that is guaranteed to be writable during the port build (see installing ports from a CDROM for an example of building ports from a read-only tree). If you need to modify one of the pkg-* files, do so by redefining a variable, not by writing over it. <makevar>WRKDIRPREFIX</makevar> Make sure your port honors WRKDIRPREFIX. Most ports do not have to worry about this. In particular, if you are referring to a WRKDIR of another port, note that the correct location is WRKDIRPREFIXPORTSDIR/subdir/name/work not PORTSDIR/subdir/name/work or .CURDIR/../../subdir/name/work or some such. Also, if you are defining WRKDIR yourself, make sure you prepend ${WRKDIRPREFIX}${.CURDIR} in the front. Differentiating operating systems and OS versions You may come across code that needs modifications or conditional compilation based upon what version of Unix it is running under. If you need to make such changes to the code for conditional compilation, make sure you make the changes as general as possible so that we can back-port code to older FreeBSD systems and cross-port to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD. The preferred way to tell 4.3BSD/Reno (1990) and newer versions of the BSD code apart is by using the BSD macro defined in <sys/param.h>. Hopefully that file is already included; if not, add the code: #if (defined(__unix__) || defined(unix)) && !defined(USG) #include <sys/param.h> #endif to the proper place in the .c file. We believe that every system that defines these two symbols has sys/param.h. If you find a system that does not, we would like to know. Please send mail to the &a.ports;. Another way is to use the GNU Autoconf style of doing this: #ifdef HAVE_SYS_PARAM_H #include <sys/param.h> #endif Do not forget to add -DHAVE_SYS_PARAM_H to the CFLAGS in the Makefile for this method. Once you have sys/param.h included, you may use: #if (defined(BSD) && (BSD >= 199103)) to detect if the code is being compiled on a 4.3 Net2 code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 1.1 and below). Use: #if (defined(BSD) && (BSD >= 199306)) to detect if the code is being compiled on a 4.4 code base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or above). The value of the BSD macro is 199506 for the 4.4BSD-Lite2 code base. This is stated for informational purposes only. It should not be used to distinguish between versions of FreeBSD based only on 4.4-Lite vs. versions that have merged in changes from 4.4-Lite2. The __FreeBSD__ macro should be used instead. Use sparingly: __FreeBSD__ is defined in all versions of FreeBSD. Use it if the change you are making only affects FreeBSD. Porting gotchas like the use of sys_errlist[] vs strerror() are Berkeley-isms, not FreeBSD changes. In FreeBSD 2.x, __FreeBSD__ is defined to be 2. In earlier versions, it is 1. Later versions always bump it to match their major version number. If you need to tell the difference between a FreeBSD 1.x system and a FreeBSD 2.x or above system, usually the right answer is to use the BSD macros described above. If there actually is a FreeBSD specific change (such as special shared library options when using ld) then it is OK to use __FreeBSD__ and #if __FreeBSD__ > 1 to detect a FreeBSD 2.x and later system. If you need more granularity in detecting FreeBSD systems since 2.0-RELEASE you can use the following: #if __FreeBSD__ >= 2 #include <osreldate.h> # if __FreeBSD_version >= 199504 /* 2.0.5+ release specific code here */ # endif #endif In the hundreds of ports that have been done, there have only been one or two cases where __FreeBSD__ should have been used. Just because an earlier port screwed up and used it in the wrong place does not mean you should do so too. __FreeBSD_version values Here is a convenient list of __FreeBSD_version values as defined in sys/param.h: __FreeBSD_version values Release __FreeBSD_version 2.0-RELEASE 119411 2.1-CURRENT 199501, 199503 2.0.5-RELEASE 199504 2.2-CURRENT before 2.1 199508 2.1.0-RELEASE 199511 2.2-CURRENT before 2.1.5 199512 2.1.5-RELEASE 199607 2.2-CURRENT before 2.1.6 199608 2.1.6-RELEASE 199612 2.1.7-RELEASE 199612 2.2-RELEASE 220000 2.2.1-RELEASE 220000 (no change) 2.2-STABLE after 2.2.1-RELEASE 220000 (no change) 2.2-STABLE after texinfo-3.9 221001 2.2-STABLE after top 221002 2.2.2-RELEASE 222000 2.2-STABLE after 2.2.2-RELEASE 222001 2.2.5-RELEASE 225000 2.2-STABLE after 2.2.5-RELEASE 225001 2.2-STABLE after ldconfig -R merge 225002 2.2.6-RELEASE 226000 2.2.7-RELEASE 227000 2.2-STABLE after 2.2.7-RELEASE 227001 2.2-STABLE after &man.semctl.2; change 227002 2.2.8-RELEASE 228000 2.2-STABLE after 2.2.8-RELEASE 228001 3.0-CURRENT before &man.mount.2; change 300000 3.0-CURRENT after &man.mount.2; change 300001 3.0-CURRENT after &man.semctl.2; change 300002 3.0-CURRENT after ioctl arg changes 300003 3.0-CURRENT after ELF conversion 300004 3.0-RELEASE 300005 3.0-CURRENT after 3.0-RELEASE 300006 3.0-STABLE after 3/4 branch 300007 3.1-RELEASE 310000 3.1-STABLE after 3.1-RELEASE 310001 3.1-STABLE after C++ constructor/destructor order change 310002 3.2-RELEASE 320000 3.2-STABLE 320001 3.2-STABLE after binary-incompatible IPFW and socket changes 320002 3.3-RELEASE 330000 3.3-STABLE 330001 3.3-STABLE after adding &man.mkstemp.3; to libc 330002 3.4-RELEASE 340000 3.4-STABLE 340001 3.5-RELEASE 350000 3.5-STABLE 350001 4.0-CURRENT after 3.4 branch 400000 4.0-CURRENT after change in dynamic linker handling 400001 4.0-CURRENT after C++ constructor/destructor order change 400002 4.0-CURRENT after functioning &man.dladdr.3; 400003 4.0-CURRENT after __deregister_frame_info dynamic linker bug fix (also 4.0-CURRENT after EGCS 1.1.2 integration) 400004 4.0-CURRENT after &man.suser.9; API change (also 4.0-CURRENT after newbus) 400005 4.0-CURRENT after cdevsw registration change 400006 4.0-CURRENT after the addition of so_cred for socket level credentials 400007 4.0-CURRENT after the addition of a poll syscall wrapper to libc_r 400008 4.0-CURRENT after the change of the kernel's dev_t type to struct specinfo pointer 400009 4.0-CURRENT after fixing a hole in &man.jail.2; 400010 4.0-CURRENT after the sigset_t datatype change 400011 4.0-CURRENT after the cutover to the GCC 2.95.2 compiler 400012 4.0-CURRENT after adding pluggable linux-mode ioctl handlers 400013 4.0-CURRENT after importing OpenSSL 400014 4.0-CURRENT after the C++ ABI change in GCC 2.95.2 from -fvtable-thunks to -fno-vtable-thunks by default 400015 4.0-CURRENT after importing OpenSSH 400016 4.0-RELEASE 400017 4.0-STABLE after 4.0-RELEASE 400018 4.0-STABLE after the introduction of delayed checksums. 400019 4.0-STABLE after merging libxpg4 code into libc. 400020 4.0-STABLE after upgrading Binutils to 2.10.0, ELF branding changes, and tcsh in the base system. 400021 4.1-RELEASE 410000 4.1-STABLE after 4.1-RELEASE 410001 4.1-STABLE after &man.setproctitle.3; moved from libutil to libc. 410002 4.1.1-RELEASE 411000 4.1.1-STABLE after 4.1.1-RELEASE 411001 4.2-RELEASE 420000 4.2-STABLE after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. 420001 4.3-RELEASE 430000 4.3-STABLE after wint_t introduction. 430001 4.3-STABLE after PCI powerstate API merge. 430002 4.4-RELEASE 440000 4.4-STABLE after d_thread_t introduction. 440001 4.4-STABLE after mount structure changes (affects filesystem klds). 440002 4.4-STABLE after the userland components of smbfs were imported. 440003 4.5-RELEASE 450000 4.5-STABLE after the usb structure element rename. 450001 4.5-STABLE after the sendmail_enable &man.rc.conf.5; variable was made to take the value NONE. 450004 4.5-STABLE after moving to XFree86 4 by default for package builds. 450005 4.5-STABLE after accept filtering was fixed so that is no longer susceptible to an easy DoS. 450006 4.6-RELEASE 460000 4.6-STABLE &man.sendfile.2; fixed to comply with documentation, not to count any headers sent against the amount of data to be sent from the file. 460001 4.6.2-RELEASE 460002 4.6-STABLE 460100 4.6-STABLE after MFC of `sed -i'. 460101 4.6-STABLE after MFC of many new pkg_install features from the HEAD. 460102 4.7-RELEASE 470000 4.7-STABLE 470100 Start generated __std{in,out,err}p references rather than __sF. This changes std{in,out,err} from a compile time expression to a runtime one. 470101 4.7-STABLE after MFC of mbuf changes to replace m_aux mbufs by m_tag's 470102 4.7-STABLE gets OpenSSL 0.9.7 470103 4.8-RELEASE 480000 4.8-STABLE 480100 4.8-STABLE after &man.realpath.3; has been made thread-safe 480101 4.8-STABLE 3ware API changes to twe. 480102 4.9-RELEASE 490000 4.9-STABLE 490100 4.9-STABLE after e_sid was added to struct kinfo_eproc. 490101 4.9-STABLE after MFC of libmap functionality for rtld. 490102 4.10-RELEASE 491000 4.10-STABLE 491100 5.0-CURRENT 500000 5.0-CURRENT after adding addition ELF header fields, and changing our ELF binary branding method. 500001 5.0-CURRENT after kld metadata changes. 500002 5.0-CURRENT after buf/bio changes. 500003 5.0-CURRENT after binutils upgrade. 500004 5.0-CURRENT after merging libxpg4 code into libc and after TASKQ interface introduction. 500005 5.0-CURRENT after the addition of AGP interfaces. 500006 5.0-CURRENT after Perl upgrade to 5.6.0 500007 5.0-CURRENT after the update of KAME code to 2000/07 sources. 500008 5.0-CURRENT after ether_ifattach() and ether_ifdetach() changes. 500009 5.0-CURRENT after changing mtree defaults back to original variant, adding -L to follow symlinks. 500010 5.0-CURRENT after kqueue API changed. 500011 5.0-CURRENT after &man.setproctitle.3; moved from libutil to libc. 500012 5.0-CURRENT after the first SMPng commit. 500013 5.0-CURRENT after <sys/select.h> moved to <sys/selinfo.h>. 500014 5.0-CURRENT after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. 500015 5.0-CURRENT after change allowing libc and libc_r to be linked together, deprecating -pthread option. 500016 5.0-CURRENT after switch from struct ucred to struct xucred to stabilize kernel-exported API for mountd et al. 500017 5.0-CURRENT after addition of CPUTYPE make variable for controlling CPU-specific optimizations. 500018 5.0-CURRENT after moving machine/ioctl_fd.h to sys/fdcio.h 500019 5.0-CURRENT after locale names renaming. 500020 5.0-CURRENT after Bzip2 import. Also signifies removal of S/Key. 500021 5.0-CURRENT after SSE support. 500022 5.0-CURRENT after KSE Milestone 2. 500023 5.0-CURRENT after d_thread_t, and moving UUCP to ports. 500024 5.0-CURRENT after ABI change for descriptor and creds passing on 64 bit platforms. 500025 5.0-CURRENT after moving to XFree86 4 by default for package builds, and after the new libc strnstr() function was added. 500026 5.0-CURRENT after the new libc strcasestr() function was added. 500027 5.0-CURRENT after the userland components of smbfs were imported. 500028 5.0-CURRENT after the new C99 specific-width integer types were added. (Not incremented.) 5.0-CURRENT after a change was made in the return value of &man.sendfile.2;. 500029 5.0-CURRENT after the introduction of the type fflags_t, which is the appropriate size for file flags. 500030 5.0-CURRENT after the usb structure element rename. 500031 5.0-CURRENT after the introduction of Perl 5.6.1. 500032 5.0-CURRENT after the sendmail_enable &man.rc.conf.5; variable was made to take the value NONE. 500033 5.0-CURRENT after mtx_init() grew a third argument. 500034 5.0-CURRENT with Gcc 3.1. 500035 5.0-CURRENT without Perl in /usr/src 500036 5.0-CURRENT after the addition of &man.dlfunc.3; 500037 5.0-CURRENT after the types of some struct sockbuf members were changed and the structure was reordered. 500038 5.0-CURRENT after headers stopped using _BSD_FOO_T_ and started using _FOO_T_DECLARED. This value can also be used as a conservative estimate of the start of &man.bzip2.1; package support. 500039 5.0-CURRENT after various changes to disk functions were made in the name of removing dependency on disklabel structure internals. 500040 5.0-CURRENT after the addition of &man.getopt.long.3; to libc. 500041 5.0-CURRENT after Binutils 2.13 upgrade, which included new FreeBSD emulation, vec, and output format. 500042 5.0-CURRENT after adding weak pthread_XXX stubs to libc, obsoleting libXThrStub.so. 5.0-RELEASE. 500043 5.0-CURRENT after branching for RELENG_5_0 500100 <sys/dkstat.h> is empty and should not be included. 500101 5.0-CURRENT after the d_mmap_t interface change. 500102 5.0-CURRENT after taskqueue_swi changed to run without Giant, and taskqueue_swi_giant added to run with Giant. 500103 cdevsw_add() and cdevsw_remove() no longer exists. Appearance of MAJOR_AUTO allocation facility. 500104 5.0-CURRENT after new cdevsw initialization method. 500105 devstat_add_entry() has been replaced by devstat_new_entry() 500106 Devstat interface change; see sys/sys/param.h 1.149 500107 Token-Ring interface changes. 500108 Addition of vm_paddr_t. 500109 5.0-CURRENT after &man.realpath.3; has been made thread-safe 500110 5.0-CURRENT after &man.usbhid.3; has been synced with NetBSD 500111 5.0-CURRENT after new NSS implementation and addition of POSIX.1 getpw*_r, getgr*_r functions 500112 5.0-CURRENT after removal of the old rc system. 500113 5.1-RELEASE. 501000 5.1-CURRENT after branching for RELENG_5_1. 501100 5.1-CURRENT after correcting the semantics of sigtimedwait(2) and sigwaitinfo(2). 501101 5.1-CURRENT after adding the lockfunc and lockfuncarg fields to &man.bus.dma.tag.create.9;. 501102 5.1-CURRENT after GCC 3.3.1-pre 20030711 snapshot integration. 501103 5.1-CURRENT 3ware API changes to twe. 501104 5.1-CURRENT dynamically-linked /bin and /sbin support and movement of libraries to /lib. 501105 5.1-CURRENT after adding kernel support for Coda 6.x. 501106 5.1-CURRENT after 16550 UART constants moved from <dev/sio/sioreg.h> to <dev/ic/ns16550.h>. Also when libmap functionality was unconditionally supported by rtld. 501107 5.1-CURRENT after PFIL_HOOKS API update 501108 5.1-CURRENT after adding kiconv(3) 501109 5.1-CURRENT after changing default operations for open and close in cdevsw 501110 5.1-CURRENT after changed layout of cdevsw 501111 5.1-CURRENT after adding kobj multiple inheritance 501112 5.1-CURRENT after the if_xname change in struct ifnet 501113 5.1-CURRENT after changing /bin and /sbin to be dynamically linked 501114 5.2-RELEASE 502000 5.2.1-RELEASE 502010 5.2-CURRENT after branching for RELENG_5_2 502100 5.2-CURRENT after __cxa_atexit/__cxa_finalize functions were added to libc. 502101 5.2-CURRENT after change of default thread library from libc_r to libpthread. 502102 5.2-CURRENT after device driver API megapatch. 502103 5.2-CURRENT after getopt_long_only() addition. 502104 5.2-CURRENT after NULL is made into ((void *)0) for C, creating more warnings. 502105 5.2-CURRENT after pf is linked to the build and install. 502106 5.2-CURRENT after time_t is changed to a 64-bit value on sparc64. 502107 5.2-CURRENT after Intel C/C++ compiler support in some headers and execve(2) changes to be more strictly conforming to POSIX. 502108 5.2-CURRENT after the introduction of the bus_alloc_resource_any API 502109 5.2-CURRENT after the addition of UTF-8 locales 502110 5.2-CURRENT after the removal of the getvfsent(3) API 502111 5.2-CURRENT after the addition of the .warning directive for make. 502112 5.2-CURRENT after ttyioctl() was made mandatory for serial drivers. 502113 5.2-CURRENT after import of the ALTQ framework. 502114 5.2-CURRENT after changing sema_timedwait(9) to return 0 on success and a non-zero error code on failure. 502115 5.2-CURRENT after changing kernel dev_t to be pointer to struct cdev *. 502116 5.2-CURRENT after changing kernel udev_t to dev_t. 502117 5.2-CURRENT after adding support for CLOCK_VIRTUAL and CLOCK_PROF to clock_gettime(2) and clock_getres(2). 502118 5.2-CURRENT after changing network interface cloning overhaul. 502119 5.2-CURRENT after the update of the package tools to revision 20040629. 502120 5.2-CURRENT after marking Bluetooth code as non-i386 specific. 502121 5.2-CURRENT after the introduction of the KDB debugger framework, the conversion of DDB into a backend and the introduction of the GDB backend. 502122 5.2-CURRENT after change to make VFS_ROOT take a struct thread argument as does vflush. Struct kinfo_proc now has a user data pointer. The switch of the default X implementation to xorg was also made at this time. 502123 5.2-CURRENT after the change to separate the way ports rc.d and legacy scripts are started. 502124 5.2-CURRENT after the backout of the previous change. 502125 5.2-CURRENT after the removal of kmem_alloc_pageable(). 502126 5.2-CURRENT after the change of the vfs_mount signature as well as global replacement of PRISON_ROOT with SUSER_ALLOWJAIL for the suser(9) API. 502127
Note that 2.2-STABLE sometimes identifies itself as 2.2.5-STABLE after the 2.2.5-RELEASE. The pattern used to be year followed by the month, but we decided to change it to a more straightforward major/minor system starting from 2.2. This is because the parallel development on several branches made it infeasible to classify the releases simply by their real release dates. If you are making a port now, you do not have to worry about old -CURRENTs; they are listed here just for your reference. Writing something after <filename>bsd.port.mk</filename> Do not write anything after the .include <bsd.port.mk> line. It usually can be avoided by including bsd.port.pre.mk somewhere in the middle of your Makefile and bsd.port.post.mk at the end. You need to include either the bsd.port.pre.mk/bsd.port.post.mk pair or bsd.port.mk only; do not mix these two usages. bsd.port.pre.mk only defines a few variables, which can be used in tests in the Makefile, bsd.port.post.mk defines the rest. Here are some important variables defined in bsd.port.pre.mk (this is not the complete list, please read bsd.port.mk for the complete list). Variable Description ARCH The architecture as returned by uname -m (e.g., i386) OPSYS The operating system type, as returned by uname -s (e.g., FreeBSD) OSREL The release version of the operating system (e.g., 2.1.5 or 2.2.7) OSVERSION The numeric version of the operating system; the same as __FreeBSD_version. PORTOBJFORMAT The object format of the system (elf or aout; note that for modern versions of FreeBSD, aout is deprecated.) LOCALBASE The base of the local tree (e.g., /usr/local/) X11BASE The base of the X11 tree (e.g., /usr/X11R6) PREFIX Where the port installs itself (see more on PREFIX). If you have to define the variables USE_IMAKE, USE_X_PREFIX, or MASTERDIR, do so before including bsd.port.pre.mk. Here are some examples of things you can write after bsd.port.pre.mk: # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif # only one shlib version number for ELF .if ${PORTOBJFORMAT} == "elf" TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} .else TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} .endif # software already makes link for ELF, but not for a.out post-install: .if ${PORTOBJFORMAT} == "aout" ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so .endif You did remember to use tab instead of spaces after BROKEN= and TCL_LIB_FILE=, did you not? :-). Install additional documentation If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under PREFIX/share/doc. This can be done, like the previous item, in the post-install target. Create a new directory for your port. The directory name should reflect what the port is. This usually means PORTNAME. However, if you think the user might want different versions of the port to be installed at the same time, you can use the whole PKGNAME. Make the installation dependent on the variable NOPORTDOCS so that users can disable it in /etc/make.conf, like this: post-install: .if !defined(NOPORTDOCS) ${MKDIR} ${DOCSDIR} ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR} .endif Here are some handy variables and how they are expanded by default when used in the Makefile: DATADIR gets expanded to PREFIX/share/PORTNAME. DOCSDIR gets expanded to PREFIX/share/doc/PORTNAME. EXAMPLESDIR gets expanded to PREFIX/share/examples/PORTNAME. These variables are exported to PLIST_SUB. Their values will appear there as pathnames relative to PREFIX if possible. That is, share/doc/PORTNAME will be substituted for %%DOCSDIR%% in the packing list by default, and so on. (See more on pkg-plist substitution here.) All documentation files and directories installed should be included in pkg-plist with the %%PORTDOCS%% prefix, for example: %%PORTDOCS%%%%DOCSDIR%%/AUTHORS %%PORTDOCS%%%%DOCSDIR%%/CONTACT %%PORTDOCS%%@dirrm %%DOCSDIR%% As an alternative to enumerating the documentation files in pkg-plist, a port can set the variable PORTDOCS to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to DOCSDIR. Therefore, a port that utilizes PORTDOCS and uses a non-default location for its documentation should set DOCSDIR accordingly. If a directory is listed in PORTDOCS or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. PORTDOCS should not be set if NOPORTDOCS is in effect. Installing the documentation at PORTDOCS as shown above remains up to the port itself. A typical example of utilizing PORTDOCS looks as follows: .if !defined(NOPORTDOCS) PORTDOCS= * .endif You can also use the pkg-message file to display messages upon installation. See the section on using pkg-message for details. The pkg-message file does not need to be added to pkg-plist. Subdirectories Try to let the port put things in the right subdirectories of PREFIX. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in the a subdirectory of lib, which does not work well with the BSD paradigm. Many of the files should be moved to one of the following: etc (setup/configuration files), libexec (executables started internally), sbin (executables for superusers/managers), info (documentation for info browser) or share (architecture independent files). See &man.hier.7; for details; the rules governing /usr pretty much apply to /usr/local too. The exception are ports dealing with USENET news. They may use PREFIX/news as a destination for their files. Cleaning up empty directories Do make your ports clean up after themselves when they are de-installed. This is usually accomplished by adding @dirrm lines for all directories that are specifically created by the port. You need to delete subdirectories before you can delete parent directories. : lib/X11/oneko/pixmaps/cat.xpm lib/X11/oneko/sounds/cat.au : @dirrm lib/X11/oneko/pixmaps @dirrm lib/X11/oneko/sounds @dirrm lib/X11/oneko However, sometimes @dirrm will give you errors because other ports also share the same subdirectory. You can call rmdir from @unexec to remove only empty directories without warning. @unexec rmdir %D/share/doc/gimp 2>/dev/null || true This will neither print any error messages nor cause &man.pkg.delete.1; to exit abnormally even if PREFIX/share/doc/gimp is not empty due to other ports installing some files in there. UIDs If your port requires a certain user to be on the installed system, let the pkg-install script call pw to create it automatically. Look at net/cvsup-mirror for an example. If your port must use the same user/group ID number when it is installed as a binary package as when it was compiled, then you must choose a free UID from 50 to 999 and register it below. Look at japanese/Wnn6 for an example. Make sure you do not use a UID already used by the system or other ports. This is the current list of UIDs between 50 and 999. bind:*:53:53:Bind Sandbox:/:/sbin/nologin majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent rdfdb:*:55:55:rdfDB Daemon:/var/db/rdfdb:/bin/sh cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh proxy:*:62:62:Packet Filter pseudo-user:/nonexistent:/nonexistent uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent pop:*:68:6:Post Office Owner (popper):/nonexistent:/sbin/nologin wnn:*:69:7:Wnn:/nonexistent:/nonexistent pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh oracle:*:71:71::0:0:Oracle:/usr/local/oracle7:/sbin/nologin ircd:*:72:72:IRC daemon:/nonexistent:/nonexistent ircservices:*:73:73:IRC services:/nonexistent:/nonexistent ifmail:*:75:66:Ifmail user:/nonexistent:/nonexistent www:*:80:80:World Wide Web Owner:/nonexistent:/sbin/nologin alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent qmaild:*:82:81:QMail user:/var/qmail:/nonexistent qmaill:*:83:81:QMail user:/var/qmail:/nonexistent qmailp:*:84:81:QMail user:/var/qmail:/nonexistent qmailq:*:85:82:QMail user:/var/qmail:/nonexistent qmailr:*:86:82:QMail user:/var/qmail:/nonexistent qmails:*:87:82:QMail user:/var/qmail:/nonexistent mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin vpopmail:*:89:89:VPop Mail User:/usr/local/vpopmail:/nonexistent firebird:*:90:90:Firebird Database Administrator:/usr/local/firebird:/bin/sh mailman:*:91:91:Mailman User:/usr/local/mailman:/sbin/nologin gdm:*:92:92:GDM Sandbox:/:/sbin/nologin jabber:*:93:93:Jabber Daemon:/nonexistent:/nonexistent p4admin:*:94:94:Perforce admin:/usr/local/perforce:/sbin/nologin interch:*:95:95:Interchange user:/usr/local/interchange:/sbin/nologin squeuer:*:96:96:SQueuer Owner:/nonexistent:/bin/sh mud:*:97:97:MUD Owner:/usr/local/share/dgd:/bin/sh msql:*:98:98:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh rscsi:*:99:99:Remote SCSI:/usr/local/rscsi:/usr/local/sbin/rscsi squid:*:100:100:squid caching-proxy pseudo user:/usr/local/squid:/sbin/nologin quagga:*:101:101:Quagga route daemon pseudo user:/usr/local/etc/quagga:/sbin/nologin ganglia:*:102:102:Ganglia User:/nonexistent:/sbin/nologin sgeadmin:*:103:103:Sun Grid Engine Admin:/nonexistent:/sbin/nologin slimserv:*:104:104:Slim Devices SlimServer pseudo-user:/nonexistent:/sbin/nologin dnetc:*:105:105:distributed.net client and proxy pseudo-user:/nonexistent:/sbin/nologin clamav:*:106:106:Clamav Antivirus:/nonexistent:/sbin/nologin cacti:*:107:107:Cacti Sandbox:/nonexistent:/sbin/nologin webkit:*:108:108:WebKit Default User:/usr/local/www/webkit:/bin/sh quickml:*:109:109:quickml Server:/nonexistent:/sbin/nologin fido:*:111:111:Fido System:/usr/local/fido:/bin/sh postfix:*:125:125:Postfix Mail System:/var/spool/postfix:/sbin/nologin rbldns:*:153:153:rbldnsd pseudo-user:/nonexistent:/sbin/nologin sfs:*:171:171:Self-Certifying File System:/nonexistent:/sbin/nologin agk:*:172:172:AquaGateKeeper:/nonexistent:/nonexistent moinmoin:*:192:192:MoinMoin User:/nonexistent:/sbin/nologin ldap:*:389:389:OpenLDAP Server:/nonexistent:/sbin/nologin drweb:*:426:426:Dr.Web Mail Scanner:/nonexistent:/sbin/nologin courier:*:465:465:Courier Mail Server:/nonexistent:/sbin/nologin qtss:*:554:554:Darwin Streaming Server:/nonexistent:/sbin/nologin ircdru:*:555:555:Russian hybrid IRC server:/nonexistent:/bin/sh messagebus:*:556:556:D-BUS Daemon User:/nonexistent:/sbin/nologin bopm:*:717:717:Blitzed Open Proxy Monitor:/nonexistent:/bin/sh bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologin This is the current list of reserved GIDs. bind:*:53: rdfdb:*:55: cyrus:*:60: proxy:*:62: authpf:*:63: uucp:*:66: dialer:*:68: network:*:69: pgsql:*:70: www:*:80: qnofiles:*:81: qmail:*:82: mailman:*:91: postfix:*:125: maildrop:*:126: rbldns:*:153: moinmoin:*:192: courier:*:465: qtss:*:554: ircdru:*:555: messagebus:*:556: bopm:*:717: Please include a notice when you submit a port (or an upgrade) that reserves a new UID or GID in this range. This allows us to keep the list of reserved IDs up to date. Do things rationally The Makefile should do things simply and reasonably. If you can make it a couple of lines shorter or more readable, then do so. Examples include using a make .if construct instead of a shell if construct, not redefining do-extract if you can redefine EXTRACT* instead, and using GNU_CONFIGURE instead of CONFIGURE_ARGS += --prefix=${PREFIX}. If you find yourself having to write a lot of new code to try to do something, please go back and review bsd.port.mk to see if it contains an existing implementation of what you are trying to do. While hard to read, there are a great many seemingly-hard problems for which bsd.port.mk already provides a shorthand solution. Respect both <makevar>CC</makevar> and <makevar>CXX</makevar> The port should respect both CC and CXX variables. What we mean by this is that the port should not set the values of these variables absolutely, overriding existing values; instead, it should append whatever values it needs to the existing values. This is so that build options that affect all ports can be set globally. If the port does not respect these variables, please add NO_PACKAGE=ignores either cc or cxx to the Makefile. An example of a Makefile respecting both CC and CXX variables follows. Note the ?=: CC ?= gcc CXX ?= g++ Here is an example which respects neither CC nor CXX variables: CC = gcc CXX = g++ Both CC and CFLAGS variables can be defined on FreeBSD systems in /etc/make.conf. The first example defines a value if it was not previously set in /etc/make.conf, preserving any system-wide definitions. The second example clobbers anything previously defined. Respect <makevar>CFLAGS</makevar> The port should respect the CFLAGS variable. What we mean by this is that the port should not set the value of this variable absolutely, overriding the existing value; instead, it should append whatever values it needs to the existing value. This is so that build options that affect all ports can be set globally. If it does not, please add NO_PACKAGE=ignores cflags to the Makefile. An example of a Makefile respecting the CFLAGS variable follows. Note the +=: CFLAGS += -Wall -Werror Here is an example which does not respect the CFLAGS variable: CFLAGS = -Wall -Werror The CFLAGS variable is defined on FreeBSD systems in /etc/make.conf. The first example appends additional flags to the CFLAGS variable, preserving any system-wide definitions. The second example clobbers anything previously defined. Configuration files If your port requires some configuration files in PREFIX/etc, do not just install them and list them in pkg-plist. That will cause &man.pkg.delete.1; to delete files carefully edited by the user and a new installation to wipe them out. Instead, install sample files with a suffix (filename.sample will work well) and print out a message pointing out that the user has to copy and edit the file before the software can be made to work. Feedback Do send applicable changes/patches to the original author/maintainer for inclusion in next release of the code. This will only make your job that much easier for the next release. <filename>README.html</filename> Do not include the README.html file. This file is not part of the cvs collection but is generated using the make readme command. Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise Invariably there will come a time when a particular port will contain a security vulnerability, will be radically broken and needs many hours of tender loving care, or is generally obsoleted, but for one reason or another should remain in the tree (and get fixed, right?). To designate a port as broken, there are three make variables that can be used in a port's Makefile. The value of the following make variables will be the reason that is given back to users for why the port was marked as broken. Please use the correct make variable as each make variable conveys radically different meanings to both users, and to automated systems that parse Makefiles. BROKEN is reserved for ports that do not work and should not be installed by users. This will prevent users from installing the port. TRYBROKEN is used for ports if you want to attempt a build of a BROKEN port. Ports marked as TRYBROKEN will be also built by the Pointyhat cluster. FORBIDDEN is used for ports that do contain a security vulnerability or induce grave concern regarding the security of a FreeBSD system with a given port installed (ex: a reputably insecure program or a program that provides easily exploitable services). Ports should be marked as FORBIDDEN as soon as a particular piece of software has a vulnerability and there is no released upgrade. Ideally ports should be upgraded as soon as possible when a security vulnerability is discovered so as to reduce the number of vulnerable FreeBSD hosts (we like being known for being secure), however sometimes there is a noticeable time gap between disclosure of a vulnerability and an updated release of the vulnerable software. Do not mark a port FORBIDDEN for any reason other than security. IGNORE is reserved for ports that should not be built for one reason or another. Users and the Pointyhat cluster will not, under any circumstances, build ports marked as IGNORE. If in doubt, do use IGNORE to prevent a port from being built. Do remember that these variables are to be used as a last resort if a port is not upgradeable. Permanently broken ports should be removed from the tree entirely. Necessary workarounds Sometimes it is necessary to work around bugs in software included with older versions of &os;. Some versions of &man.make.1; were broken on at least 4.8 and 5.0 with respect to handling comparisons based on OSVERSION. This would often lead to failures during make describe (and thus, the overall ports make index). The workaround is to enclose the conditional comparison in spaces, e.g.: if ( ${OSVERSION} > 500023 ) Be aware that test-installing a port on 4.9 or 5.2 will not detect this problem. Miscellanea The files pkg-descr and pkg-plist should each be double-checked. If you are reviewing a port and feel they can be worded better, do so. Do not copy more copies of the GNU General Public License into our system, please. Please be careful to note any legal issues! Do not let us illegally distribute software! If you are stuck… Do look at existing examples and the bsd.port.mk file before asking us questions! ;-) Do ask us questions if you have any trouble! Do not just beat your head against a wall! :-) A Sample <filename>Makefile</filename> Here is a sample Makefile that you can use to create a new port. Make sure you remove all the extra comments (ones between brackets)! It is recommended that you follow this format (ordering of variables, empty lines between sections, etc.). This format is designed so that the most important information is easy to locate. We recommend that you use portlint to check the Makefile. [the header...just to make it easier for us to identify the ports.] # New ports collection makefile for: xdvi [the "version required" line is only needed when the PORTVERSION variable is not specific enough to describe the port.] # Date created: 26 May 1995 [this is the person who did the original port to FreeBSD, in particular, the person who wrote the first version of this Makefile. Remember, this should not be changed when upgrading the port later.] # Whom: Satoshi Asami <asami@FreeBSD.org> # # $FreeBSD$ [ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS when it is committed to our repository. If upgrading a port, do not alter this line back to "$FreeBSD$". CVS deals with it automatically.] # [section to describe the port itself and the master site - PORTNAME and PORTVERSION are always first, followed by CATEGORIES, and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then EXTRACT_ONLY, as necessary.] PORTNAME= xdvi PORTVERSION= 18.2 CATEGORIES= print [do not forget the trailing slash ("/")! if you are not using MASTER_SITE_* macros] MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications PKGNAMEPREFIX= ja- DISTNAME= xdvi-pl18 [set this if the source is not in the standard ".tar.gz" form] EXTRACT_SUFX= .tar.Z [section for distributed patches -- can be empty] PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz [maintainer; *mandatory*! This is the person (preferably with commit privileges) whom a user can contact for questions and bug reports - this person should be the porter or someone who can forward questions to the original porter reasonably promptly. If you really do not want to have your address here, set it to "ports@FreeBSD.org".] MAINTAINER= asami@FreeBSD.org COMMENT= A DVI Previewer for the X Window System [dependencies -- can be empty] RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm [this section is for other standard bsd.port.mk variables that do not belong to any of the above] [If it asks questions during configure, build, install...] IS_INTERACTIVE= yes [If it extracts to a directory other than ${DISTNAME}...] WRKSRC= ${WRKDIR}/xdvi-new [If the distributed patches were not made relative to ${WRKSRC}, you may need to tweak this] PATCH_DIST_STRIP= -p1 [If it requires a "configure" script generated by GNU autoconf to be run] GNU_CONFIGURE= yes [If it requires GNU make, not /usr/bin/make, to build...] USE_GMAKE= yes [If it is an X application and requires "xmkmf -a" to be run...] USE_IMAKE= yes [et cetera.] [non-standard variables to be used in the rules below] MY_FAVORITE_RESPONSE= "yeah, right" [then the special rules, in the order they are called] pre-fetch: i go fetch something, yeah post-patch: i need to do something after patch, great pre-install: and then some more stuff before installing, wow [and then the epilogue] .include <bsd.port.mk> Automated package list creation First, make sure your port is almost complete, with only pkg-plist missing. Next, create a temporary directory tree into which your port can be installed, and install any dependencies. port-type should be local for non-X ports and x11-4 or x11 for ports which install into the directory hierarchy of XFree86 4 or an earlier XFree86 release, respectively. &prompt.root; mkdir /var/tmp/port-name &prompt.root; mtree -U -f /etc/mtree/BSD.port-type.dist -d -e -p /var/tmp/port-name &prompt.root; make depends PREFIX=/var/tmp/port-name Store the directory structure in a new file. &prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort > OLD-DIRS Create an empty pkg-plist file: &prompt.root; touch pkg-plist If your port honors PREFIX (which it should) you can then install the port and create the package list. &prompt.root; make install PREFIX=/var/tmp/port-name &prompt.root; (cd /var/tmp/port-name && find -d * \! -type d) | sort > pkg-plist You must also add any newly created directories to the packing list. &prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort | comm -13 OLD-DIRS - | sort -r | sed -e 's#^#@dirrm #' >> pkg-plist Finally, you need to tidy up the packing list by hand; it is not all automated. Manual pages should be listed in the port's Makefile under MANn, and not in the package list. User configuration files should be removed, or installed as filename.sample. The info/dir file should not be listed and appropriate install-info lines should be added as noted in the info files section. Any libraries installed by the port should be listed as specified in the shared libraries section. Alternatively, use the plist script in /usr/ports/Tools/scripts/ to build the package list automatically. The first step is the same as above: take the first three lines, that is, mkdir, mtree and make depends. Then build and install the port: &prompt.root; make install PREFIX=/var/tmp/port-name And let plist create the pkg-plist file: &prompt.root; /usr/ports/Tools/scripts/plist -Md -m /etc/mtree/BSD.port-type.dist /var/tmp/port-name > pkg-plist The packing list still have to tidied up the by hand as stated above. Keeping Up The &os; Ports Collection is constantly changing. Here is some information on how to keep up. FreshPorts One of the easiest ways to learn about updates that have already been committed is by subscribing to FreshPorts. You can select multiple ports to monitor. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other &os; committer has made. (These are often necessary to keep up with changes in the underlying ports framework—although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or just simply impractical. Also, in some cases, the changes are very minor in nature. We expect everyone to use their best judgement in these cases.) If you wish to use FreshPorts, all you need is an account. If your registered email address is @FreeBSD.org, you'll see the opt-in link on the right hand side of the webpages. For those of you who already have a FreshPorts account, but are not using your @FreeBSD.org email address, just change your email to @FreeBSD.org, subscribe, then change it back again. FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, you will be notified of any errors which FreshPorts detects during sanity testing of your commits. The Web Interface to the Source Repository It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the CHANGES file. Changes that affect individual ports are now documented in the UPDATING file. However, the definitive answer to any question is undoubtedly to read the source code of bsd.port.mk, and associated files. The &os; Ports Mailing List If you maintain ports, you should consider following the &a.ports;. Important changes to the way ports work will be announced there, and then committed to CHANGES. The &os; Port Building Cluster One of the least-publicized strengths of &os; is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. You can find the results of these builds at package building logs and errors. The &os; Port Distfile Survey The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. The FreeBSD Ports distfiles survey attempts to query every download site for every port to find out if each distfile is still currently available. Maintainers are asked to check this report periodically, not only to speed up the building process for users, but to help avoid wasting bandwidth of the sites that volunteer to host all these distfiles. The &os; Ports Monitoring System Another handy resource is the FreeBSD Ports Monitoring System (also known as portsmon). This system comprises a database that processes information from several sources and allows its to be browsed via a web interface. Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. In the future, this will be expanded to include the distfile survey, as well as other sources. To get started, you can view all information about a particular port by using the Overview of One Port. diff --git a/ja_JP.eucJP/articles/contributing/article.sgml b/ja_JP.eucJP/articles/contributing/article.sgml index 1cfdb76010..c00e8f59ba 100644 --- a/ja_JP.eucJP/articles/contributing/article.sgml +++ b/ja_JP.eucJP/articles/contributing/article.sgml @@ -1,731 +1,723 @@ -%man; - %freebsd; - %newsgroups; - -%ja-authors; - -%authors; - %mailing-lists; + +%articles.ent; ]>
FreeBSD への貢献 $FreeBSD$ この文書は、個人や団体が FreeBSD プロジェクトに貢献するためのいくつかの方法について説明しています。 Jordan Hubbard 寄稿: 貢献 あなたも FreeBSD のために貢献したくなりましたか? 素晴らしい! FreeBSD は生き残るためにユーザベースの貢献に頼っています。 あなたの貢献は感謝されるだけではなく、FreeBSD が成長し続けるために極めて重要なものなのです! 一部の人達が発言しているのとは反対に、 貢献を受け付けてもらうために腕利きのプログラマーになるとか FreeBSD コアチームの人と親友になる必要はありません。 多くのそして益々増加する世界中の貢献者達が FreeBSD を開発しており、 彼らの年齢、専門技術分野は多岐に渡っています。 手の空いている人よりも成すべき仕事の方が多く、 お手伝いはいつでも歓迎されています。 FreeBSD プロジェクトはカーネルや散在しているユーティリティよりも、 オペレーティングシステム環境に対して責任を持っています。 私たちの TODO リストには文書整備、 ベータテスト、インストーラや専門化されたタイプの カーネル開発の好例を紹介するなど非常に広い範囲の作業があります。 あなたの技能レベルや分野に関わらず、 プロジェクトを支援できることが必ず何かあります! FreeBSD 関連の事業に携わる商業団体が私たちにコンタクトすることも歓迎しています。 あなたの製品を (FreeBSD 上で) 動作させるには、 特別な拡張が必要ではありませんか? あまりにも風変わりな要求でなければ、 それを受け入れる用意が私たちにあるとわかるはずです。 付加価値のある製品ですか? 私たちに知らせてください! 多分私たちは、 ある面において共同して作業をすることができるでしょう。 フリーソフトウェア界は、 ソフトウェアがどのように開発され、 販売され、保守されていくかについて、既存の仮説に挑戦しています。 少なくとももう一度考慮してみることを私たちは強くお奨めします。 何が必要? 次のタスクとサブプロジェクトのリストは、コアチームの色々な TODO リストと最近 2 ヶ月で集めたユーザリクエストを合わせたものです。 可能なところでは、緊急度によってタスクがランクづけされています。 もしここにあるタスクの実行に興味があるのでしたら、 コーディネータの名前をクリックしてメールを送ってください。 もしコーディネータが決まっていなければ、 あなたがボランティアしてみませんか? 進行中のタスク 次のタスクはやっておくべきではありますが、 特にさし迫っているわけではありません: 完全な KLD ベースのドライバのサポート / コンフィグレーションマネージャ。 穏やかな方法でハードウェアを検知するコンフィグレーションマネージャの作成 (第 3 ステージ・ブートの中に?)。ハードウェアが必要とする KLD だけを残す等 PCMCIA/PCCARD。コーディネータ: &a.msmith; と &a.imp; ドキュメンテーション! pcic ドライバの信頼性のある操作 (テスト要) sio.c のリコグナイザとハンドラ (ほぼ完了) ed.c のリコグナイザとハンドラ (ほぼ完了) ep.c のリコグナイザとハンドラ (ほぼ完了) User-mode のリコグナイザとハンドラ (部分的に完了) 先進的なパワーマネージメント。コーディネータ: &a.nate; と &a.phk; APM サブドライバ (ほぼ完了) IDE/ATA ディスクサブドライバ (部分的に完了) syscons/pcvt サブドライバ PCMCIA/PCCARD ドライバ群との統合 (サスペンド / レジューム) 優先度の低いタスク 次のタスクは全くのあら隠し、 または誰もすぐにおこないそうもない投資のような仕事を表します: 最初の N 項目は Terry Lambert terry@lambert.org からのものです。 ネットワークカードと一緒に提供される ODI カードドライバを使用できるようにする、NetWare サーバ (プロテクトモードの ODI ドライバ) ローダとサブサービス。 NDIS ドライバと NetWare の SCSI ドライバについても同様。 前のリビジョンの FreeBSD マシンではなく、Linux マシンで動作する 「アップグレードシステム」オプション。 カーネルのマルチスレッド化 (カーネルのプリエンプションが必要)。 カーネルのプリエンプション付き対称マルチプロセッシング (カーネルのプリエンプションが必要)。 ポータブルコンピュータのサポートにおける協調の試み。 これは PCMCIA ブリッジング規則と電源管理イベント処理の変更により、 いくらかは処理できます。しかし、 内蔵ディスプレイと外部ディスプレイの検出、この 2 種類のディスプレイがあるという事実に基づく異なる解像度の選択、 マシンがドックにある場合にはディスクのモータ停止を防止すること、 マシンのブート能力に影響を与えずにドックベースのカードの消滅を可能にすること (PCMCIA と同じ問題) などの問題があります。 もっと簡単なタスク 上のセクションで挙げたタスクは膨大な時間の投資または FreeBSD のカーネルに関する深い知識を必要とします (もしくはそのどちらも)。しかしながら、週末ハッカー やプログラミングのスキルを持たない人々に適した立派なタスクも数多くあります。 FreeBSD-current を運用しており、 状態の良いインターネット接続があるならば、current.FreeBSD.org という一日に一回フルリリースを行っているマシンがあります — 時おり最新のリリースをそこからインストールし、 その過程で何か問題があるなら報告して下さい。 freebsd-bugs メーリングリストを読んでください。 そこではあなたが建設的なコメントを付けたりテストできるパッチが提供されているような問題があるかもしれません。 もしくはそれらの問題の一つをあなた自身で修正することさえできるかもしれません。 定期的に FAQ とハンドブックを通して読んでみてください。 もしまずい説明や古い事柄や完全に間違っていることなどがあれば我々に知らせて下さい。 さらに良いのは我々に修正案を送ることです (SGML は学ぶのにそれほど難しくありませんが、 プレインテキストでも問題はありません)。 FreeBSD の文書を自分の母国語に翻訳するのを手伝ってください。 文書がすでに存在すれば、もっと文書を翻訳したり、 その翻訳が最新の状態かどうか確認するのを手伝うことができます。 まず FreeBSD ドキュメンテーションプロジェクト入門の 翻訳に関する FAQ (よくある質問とその答え) を一読してください。 とはいっても、 そうすることによってあなたがすべての FreeBSD 文書の翻訳に携わるようになるわけではないですからね。 — ボランティアとして、 自分がやろうと思うだけ少しでもたくさんでも :) 活動してください。 いったん誰かが翻訳を始めたら、 たくさんの人達がいつだって協力してくれますから。 もし翻訳に費す時間やエネルギーが限られているなら、 まずインストール方法の翻訳からお願いします (訳注: なぜなら、 もっとも必要とされている文書がそれだからです)。 たまに (もしくは定期的に) freebsd-questions メーリングリストや &ng.misc; を読んでください。 これは、あなたの持っている専門知識を共有したり、 誰かが抱えている問題を解決するのに非常に有効なものになり得ることです。 時にはあなた自身で新しいことを学ぶことさえできるかもしれません。 これらのフォーラムはやるべきことのアイディアの源にもなり得るのです。 -current に正しく当てられるがしばらく経っても (通常は 2、3 週間) -stable に取り込まれてないようなバグフィックスがあるならばコミッターに丁寧に思い出させてください。 寄贈ソフトウェアをソースツリーの src/contrib に移動させてください。 src/contrib 以下のコードが最新のものであるか確認してください。 警告を詳細に報告するようにしてソースツリー全体 (もしくはその一部) を構築してみてください。 そして警告が出ないようにしてください。 ports で、gets() を使っているとか malloc.h をインクルードしているなどといった警告が出ないようにしてください。 もしなんらかの ports に関わっているなら、 あなたのパッチを作者にフィードバックしてください (次のバージョンが出た時にあなたが楽になります)。 このリストに追加するタスクを提案して下さい! 障害報告 (PR; Problem Report) データベースにおける作業 障害報告 (PR) データベース FreeBSD 障害報告リストでは、現在問題となっている報告と、 FreeBSD の利用者によって提出された改良の要望に関するすべてのリストを公開しています。 open 状態の障害情報を見て、興味を引く内容かどうか確かめて下さい。 本当に複雑なものも含まれているでしょうし、 たとえば、障害報告に対する修正がちゃんとしたものであるかどうか単にチェックするだけのとても簡単な作業もあるでしょう。 まず、まだ誰にも割り当てられていない障害報告から作業を始めて下さい。 もし、誰か他の人に割り当てが決まっているけれども自分が作業可能だ、 というものがあれば、作業ができるかどうか — 既にテスト用パッチが用意されているのかどうか、あるいは その問題についてあなたが考えている、 より進んだ考えに関して議論ができるかどうか、 割り当てられている人に電子メールで問い合わせて下さい。 貢献の仕方 一般的に、システムへの貢献は次の 6 つのカテゴリの 1 つ以上に分類されます: バグ報告と一般的な論評 報告するべきバグがあったり、提案したいことがあれば: 一般的な技術的関心事に関するアイデアや提案は &a.hackers; へメールしてください。同様に、このような事柄に興味のある (そして膨大なメール! に耐えられる) 人は、 &a.majordomo; へメールを送って hackers メーリングリストに参加すると良いでしょう。情報については メーリングリスト を参照してください。 バグを発見したり変更を送付しようとしている場合は &man.send-pr.1; プログラムか ウェブベースの send-pr を使用して報告してください。 バグレポートの各項目を埋めるようにしてください。65KB を超えるのでなければ、 レポート中に直接パッチを入れてくださって結構です。 パッチがソースツリーにすぐ適用できるものならば、 報告の概要に [PATCH] と書いておいてください。 その場合、カット＆ペーストはしないでください。 カット＆ペーストではタブがスペースに展開されてパッチが使い物にならなくなってしまいます。 20KB を超える場合は、 それらを compress して &man.uuencode.1; することも検討してください。とても大きくなる場合は ftp://ftp.FreeBSD.org/pub/FreeBSD/incoming/ を利用してください。 レポートがファイリングされれば、 バグ報告の確認とトラッキング番号をメールで受け取るはずです。 このトラッキング番号を覚えておき、問題に関する詳細情報を bug-followup@FreeBSD.org に メールで送って更新できるようにしてください。たとえば "Re: kern/3377" のように、 この番号をサブジェクト行に使用してください。 すべてのバグレポートの追加情報は、 この方法で送付されなければいけません。 もしタイムリーに (あなたの電子メール接続形態にもよりますが、 3 日から 1 週間) 確認を受けとれないとか、何らかの理由で &man.send-pr.1; コマンドが使用できない場合には、&a.bugs; へメールを送り、 誰か代りにバグ報告を送付してもらうようたずねてください。 良い障害報告を書く方法についてはこの文書をご覧ください。 文書の変更 文書に関する提案 文書の変更は &a.doc; が監督しています。バグ報告と一般的な論評 に記述されているように send-pr コマンドを使用して、提案や変更 (どんな些細なものでも歓迎します!) を送ってください。 現存のソースコードの変更 FreeBSD-current 現存のソースコードへの追加または変更は、 いくらかトリッキーな仕事であり、core の FreeBSD 開発の現状にあなたがどれだけ通じているかに大きく依存します。 FreeBSD-current として知られる FreeBSD の特別な継続的リリースがあります。FreeBSD-current は開発者の積極的な活動の便宜のために、 色々な方法で利用可能になっています。FreeBSD-current の入手と使用方法についての詳しい情報についてはFreeBSD ハンドブック を参照してください。 不幸にして古いソースをもとに仕事をすることは、 時々あなたの変更が時代遅れ、または FreeBSD への簡単な再統合に合わなくなっていることを意味します。 システムの現状に関する議論がおこなわれている &a.announce; と &a.current; へ参加することで、 この可能性を最小限にすることができます。 完全な最新のソースを変更のベースにできることが確実になったと仮定して、 次のステップは FreeBSD の保守担当者へ送る差分ファイルの生成です。これは &man.diff.1; コマンドを使用しておこないますが、context diff 形式が好まれるようです。たとえば: diff &prompt.user; diff -c oldfile newfile または &prompt.user; diff -c -r olddir newdir これで指定されたソースファイルまたはディレクトリ階層に対するコンテキスト形式の差分が生成されます。 詳しい説明は &man.diff.1; のマニュアルページを参照してください。 差分ファイル (&man.patch.1; コマンドでテストできます) を作ったら、それらを FreeBSD に含めてもらうようメールで送ってください。バグ報告と一般的な論評 に記述されているように &man.send-pr.1; コマンドを使用してください。差分ファイルだけを &a.hackers; へ送ってはいけません。途方にくれてしまいます! 私たちは多忙なので、あなたの提案に大変感謝します (これはボランティアのプロジェクトです!)。 すぐに取りかかることはできませんが、処理されるまではちゃんと PR データベースに残っています。 報告の概要に [PATCH] と書いてあなたの提案を表明してください。 uuencode あなたがそうした方がいいと思う場合 (たとえば、 ファイルの追加、削除または名称変更など)、変更を tar ファイルにまとめ、&man.uuencode.1; プログラムにかけてください。shar アーカイブも歓迎します。 たとえばあなたがそれ自身のさらなる配布を管理する著作権の問題を良く分かっていないとか、 単に厳しいレビューをおこなっておらずリリースする準備ができていないなど、 あなたの変更が潜在的に不安定な性質を持つものである場合、 &man.send-pr.1; で送付するよりむしろ &a.core; へ直接送ってください。コアチームメーリングリスト宛のメールは、 日々の仕事のほとんどを FreeBSD でおこなっている人たちの、 より小さなグループに届きます。 このグループもまたとても忙しいことに注意して、 本当に必要な場合にコアチームの彼らにメールを送るだけにしてください。 コーディングスタイルに関する情報は &man.intro.9; および &man.style.9; を参照してください。コードを提出する前には、 少なくともこの情報を意識しておいてくださるようお願いします。 新たなコードやメジャーな付加価値の高いパッケージ 重要な大きい仕事の寄贈や、重要な新しい機能を FreeBSD に追加する場合には通常、変更点を tar/uuencode したファイルにして送るか、それらをウェブサイトや FTP サイトへアップロードしてアクセスできるようにすることのどちらかが必要になります。 web や FTP サイトへのアクセスができないときは適切な FreeBSD のメーリングリストで誰かに変更を受け取って貰ってください。 大量のコードをともなった仕事の場合は、 常に著作権に関する微妙な問題が出てきます。FreeBSD に含めるコードのコピーライトとして受け入れることができるのは、 以下の二つです。 BSD copyright BSD コピーライト。 このコピーライトは 権利に縛られない 性格と商用企業にとって一般的な魅力をもつために最も好まれます。 FreeBSD プロジェクトは商用利用を阻んだりせず、何かを FreeBSD へ投資する気になった商業関係者による参加を積極的に奨励します。 GPLGNU General Public License GNU General Public License GNU一般公有使用許諾、または GPL。 このライセンスはコードを商用目的に使用する場合に余分な努力が求められるため、 私たちにあまり評判が良いというわけではありません。しかし、 私たちは既に GPL 下の高品質なコード (コンパイラ、アセンブラ、テキストフォーマッタ等) の提供を受けており、私たちは現在それを必要としています。そのため、 このライセンスによる新たな貢献を拒絶するというのは愚かなことでしょう。GPL 下のコードはソースツリーの別の部分、現在のところ /sys/gnu か /usr/src/gnu に入っています。 そのため、GPL が問題となるような人は、 誰でも簡単にそれとわかるようになっています。 これ以外のタイプのコピーライトによる寄贈は、FreeBSD へ含めることを考慮する前に注意深いレビューを受けなければなりません。 作者が独自のチャネルを通して配布しており、 そのような変更をおこなうことを常に奨励している場合でも、 特に限定的な商用のコピーライトが適用される寄贈は一般に拒否されます。 あなたの作品に BSD スタイル のコピーライトを付けるには、 保護したいソースコードファイルすべての一番最初に以下のテキストを入れて、 %% の間を適切な情報に置き換えください。 Copyright (c) %%適切な年%% %%あなたの名前%%, %%あなたの州%% %%郵便番号%%. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY %%あなたの名前%% ``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 %%あなたの名前%% BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $Id$ 便宜をはかるため、 このテキストのコピーは次の場所に置いてあります。 /usr/share/examples/etc/bsd-style-copyright 訳注 以下は神田敏広氏より寄贈された bsd-style-copyright の日本語訳です。 ソースファイルに含めるものは原文の方であることに注意してご利用ください。 また、原文との間に趣旨の差異が生じた場合、 原文の内容が FreeBSD プロジェクトの意思であるものとします。 Copyright (C) [年] [あなたの名前] All rights reserved. ソースとバイナリ形式の再配布および使用は、変更の有無にかかわらず以下の 条件を満たす場合に限り許可される: 1. ソースコードの再配布は、上記の著作権表示・この条件のリスト・下記の 否認声明文を保持しなければならない。 2. バイナリ形式の再配布は上記の著作権表示・この条件のリスト・下記の 否認声明文を、配布物と共に提供される文書および/または他の資料の中に 含めなければならない。 (訳注:ここから「否認声明文」です) このソフトウェアは[あなたの名前]および貢献者によって ``あるがままの状態'' で提供され、商品性と特定の目的に対する適合性についての暗黙の保証に留ま らず、いかなる明示および暗黙の保証を認めない。[あなたの名前]および貢献 者は、あらゆる直接的・間接的・偶発的・特殊的・典型的・必然的な損害 (代 替製品または代替サービスの獲得費; 効用・データ・利益の喪失; または業務 中断を含み、またそれだけに留まらない損害) に対して、たとえどのようにし て生じたとしても、そしてこのソフトウェアの使用によってどのようにであれ 生じる、契約上であろうと、厳密な責任内であろうと、あるいは不正行為 (過 失やそうでない場合を含む) における場合であろうとも、いかなる責任論上も、 たとえそのような損害の可能性が予見されていたとしても、一切の責任を持た ない。 翻訳: 神田敏広 御協力 (五十音順・敬称略): 池田研二、内川 喜章、藤村 英治、むらたしゅういちろう 杢野 雅一、横田＠宇都宮 金銭、ハードウェアまたはインターネットアクセス FreeBSD プロジェクトの目的を進めるための寄付や、 私たちと同じようなボランティアの細く長い!努力を、 私たちは常に喜んで受け入れています。 また一般的に私たちは自分達で周辺機器を買う資金が不足しているため、 周辺機器のサポートを充実させるのにハードウェアの寄付はとても重要です。 資金の寄付 FreeBSD 財団は、FreeBSD プロジェクトの目標を推進するために確立された非営利的で税金を免除された財団です。 501(c)3 の実体として、財団はコロラド州所得税ならびに、 アメリカ連邦主義者所得税を一般に免除されています。 免税実体への寄付は、 しばしば有税の連邦政府の所得から差し引くことができます。 寄付は以下に送ってください。
The FreeBSD Foundation 7321 Brockway Dr. Boulder, CO 80303 USA
現在、PayPal による寄付の受け付けを web 経由でできるようになりました。 寄付をするには、FreeBSD 財団の web サイトを ぜひご覧ください。 FreeBSD 財団に関するこれ以上の情報は The FreeBSD Foundation -- an Introduction を見てください。 財団への email での連絡は bod@FreeBSDFoundation.org へどうぞ。 ハードウェアの寄贈 寄贈 FreeBSD プロジェクトは、 次の 3 つのカテゴリのどんなハードウェアの寄贈も、 喜んで受け付けます: ディスクドライブ、 メモリまたは完全なシステムといった一般用途のハードウェアは、 資金の寄付の節にある FreeBSD, Inc. の住所まで送ってください。 進行中の受け入れテストのためのハードウェアが必要とされています。 新たなリリース毎に適切な逆行テストができるように、 私たちは現在、FreeBSD がサポートするすべてのコンポーネントのテストラボを設置しようとしています。 私たちにはまだ、 たくさんの重要な部品 (ネットワークカード、 マザーボードなど) が不足していますので、 このような寄贈をしたいと思っているならば、&a.dg; へコンタクトしてどの部品がまだ必要とされているかの情報を得てください。 現在 FreeBSD にサポートされていないハードウェアで、 サポートに追加して欲しいもの。 私たちが新しいハードウェアを受けとる前にそのタスクを引き受けてくれる開発者を探す必要があるため、 その部品を送る前に &a.core; にコンタクトを取ってください。 インターネットアクセスの寄付 私たちは常に FTP、WWW や cvsup の新しいミラーサイトを募集しています。 ミラーサイトになりたい場合には &a.hubs; にコンタクトを取って、詳しい情報を手に入れてください。
diff --git a/ja_JP.eucJP/articles/contributors/article.sgml b/ja_JP.eucJP/articles/contributors/article.sgml index 66a2148ddd..025dba2762 100644 --- a/ja_JP.eucJP/articles/contributors/article.sgml +++ b/ja_JP.eucJP/articles/contributors/article.sgml @@ -1,735 +1,723 @@ -%man; - -%ja-authors; - -%authors; - -%teams; - -%mailing-lists; - -%ja-trademarks; - -%trademarks; + +%articles.ent; %contrib.ent; ]>
FreeBSD への貢献者 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.sun; &tm-attrib.general; この文書は FreeBSD に貢献した個人や組織を列記したものです。 寄贈者ギャラリー FreeBSD プロジェクトは次の寄贈者に恩義を受けており、 ここに公表して感謝の意を表したいと思います。 セントラルサーバプロジェクトへの寄贈者: 次にあげる個人および企業からは、 新しいセントラルサーバマシンのための部品の寄贈を頂きました。 これにより、freefall.FreeBSD.org をリプレースして、新しい FreeBSD サーバマシンを 構築することができました。 &a.mbarkah と彼の所属する Hemisphere Online は、Pentium Pro (P6) 200MHz CPU を寄贈してくださいました。 ASA Computers は、Tyan 1662 マザーボード を寄贈してくださいました。 ViaNet Communications の Joe McGuckin joe@via.net は、Kingston イーサネットコントローラ を寄贈してくださいました。 Jack O'Neill jack@diamond.xtalwind.net は、 NCR 53C875 SCSI コントローラカード を寄贈してくださいました。 Alameda Networks の Ulf Zimmermann ulf@Alameda.net は、128 MB のメモリ、そして 4 GB のディスクドライブと匡体 を寄贈してくださいました。 直接的な資金提供 次にあげる個人および企業からは FreeBSD プロジェクトに対する直接的な 資金提供を頂いています。 Annelise Anderson ANDRSN@HOOVER.STANFORD.EDU &a.dillon; Blue Mountain Arts Epilogue Technology Corporation &a.sef; Global Technology Associates, Inc Don Scott Wilde Gianmarco Giovannelli gmarco@masternet.it Josef C. Grosch joeg@truenorth.org Robert T. Morris &a.chuckr; Imaginary Landscape, LLC. の Kenneth P. Stox ken@stox.sa.enteract.com Dmitry S. Kohmanyuk dk@dog.farm.org 日本の Laser5 は、さまざまな種類の FreeBSD CD の販売利益の一部を 寄付してくれました。 蕗出版 は、はじめての FreeBSD の売り上げの一部を FreeBSD プロジェクト及び XFree86 プロジェクトへ寄付してくれました。 アスキー は FreeBSD 関連の書籍の売り上げの一部を FreeBSD プロジェクトおよび FreeBSD 友の会へ寄付してくれました。 横河電機株式会社 からは FreeBSD プロジェクトへ多大な寄付をいただきました。 BuffNET Pacific Solutions Siemens AG, Andre Albsmeier andre.albsmeier@mchp.siemens.de Chris Silva ras@interaccess.com ハードウェアの寄贈者 次にあげる個人および企業からは、 テストやデバイスドライバの開発 / サポート のためのハードウェアの寄贈を頂いています。 BSDi は、 ネットワークへのアクセスおよび 他のハードウェアリソースの寄贈はいうまでもなく、 開発に使うための Pentium P5-90 と 486/DX2-66 EISA/VL のシステム数台を提供してくださいました。 Compaq から、さまざまな種類の Alpha システムを FreeBSD プロジェクトに寄贈していただきました。 この豊富な寄贈品の中には AlphaStation DS10 4 台、AlphaServer DS20 1 台、 AlphaServer 2100 数台、AlphaServer 4100 1 台、 500Mhz の CPU を搭載したパーソナルワークステーション 8 台、 433Mhz の CPU を搭載したパーソナルワークステーション 4 台が含まれ、 それ以外にも数々の支援をいただきました。 上記のマシンは、FreeBSD/Alpha における リリースエンジニアリング作業、package 構築、SMP の開発、 そして一般的な開発に利用されています。 TRW Financial Sysytems 社は、PC 130 台、68 GB のファイルサーバ 3 台、12 のイーサネット、 ディスクレスコードのデバッグをおこなうための ルータ 2台及び ATM スイッチを提供してくださいました。また、 彼らは 2、3 人の FreeBSD ハッカーを雇って、FreeBSD に専念させてくださっております。 ありがとうございます! Dermot McDonnell は、東芝 XM3401B CD-ROM ドライブを 寄贈してくださいました。その CD-ROM ドライブは現在 freefall で使用されています。 Chuck Robey chuckr@glue.umd.edu は、実験用のフロッピーテープストリーマを 寄付してくださいました。 Larry Altneu larry@ALR.COM と &a.wilko;は、wt ドライバを改良するために Wangtek と Archive の QIC-02 テープドライブを提供してくださいました。 Ernst Winter ewinter@lobo.muc.de は、 このプロジェクトへ 2.88 MB のフロッピードライブを提供してくださいました。 うまくいけば、 これでフロッピーディスクドライバを書き直すための プレッシャーが増えるでしょう。 Tekram Technologies は NCR ドライバや AMD ドライバと自社のカードの逆行テストのため FAST/ULTRA SCSI ホストアダプタ DC-390、DC-390U、DC-390F を 各１枚提供してくださいました。また、フリーな OS のためのドライバの ソースを自社の FTP サーバ で公開されていることも称賛に値するでしょう。 Larry M. Augustin は Symbios Sym8751S SCSI カードを寄贈してくださっただけでなく、Ultra-2 や LVD をサポートする次期チップ Sym53c895 のものを含む データブックのセットと、最新の Symbios SCSI チップが持つ先進的機能を安全に使う方法について書かれた 最新のプログラミングマニュアルも寄贈してくださいました。 本当にありがとうございます! Christoph Kukulies kuku@FreeBSD.org は、IDE CD-ROM ドライバ開発用の FX120 12 倍速 Mitsumi CD-ROM ドライブを提供してくださいました。 Mike Tancsa mike@sentex.ca は、 拡張カードの対応と、netatm ATM スタックの開発作業のために 4 枚の ATM PCI カードを寄贈してくれました。 特筆すべき寄贈者 BSDi (かつての Walnut Creek CDROM) は、 言い表せないほど多くの寄付をしてくださいました (詳細は FreeBSD ハンドブックの 「FreeBSD プロジェクトについて」の章をご覧ください)。 特に、私たちのもともとのプライマリ開発マシンである freefall.FreeBSD.org、 テストおよびビルドマシンである thud.FreeBSD.org で使用しているハードウェアに対し感謝したいと思います。 また彼らには、数年にわたる色々な貢献者への資金提供や、 インターネットへの T1 コネクションの無制限使用を提供して 頂いた恩義があります。 interface business GmbH, Dresden は、&a.joerg; を根気よくサポートしてくださいました。彼は本職より FreeBSD の仕事を好みがちであり、彼個人の接続があまりに 遅くなったり途切れたりして仕事にならない時は必ず interface business の (非常に高価な) EUnet インターネット接続に頼ったものです…。 Berkeley Software Design, Inc. は、同社の DOS エミュレータのコードを BSD コミュニティ全体に対して提供してくれました。このコードは、 doscmd コマンドに利用されています。 FreeBSD コアチーム FreeBSD コアチームは、 プロジェクトの 運用委員会 を形成し、FreeBSD プロジェクトの全般的な目的や方針の決定を行います。さらに、 FreeBSDプロジェクトの 特定の分野の 運用も行っています。 (姓でアルファベット順): &contrib.core; FreeBSD の開発者たち (CVS の) commitする権利を持っていて、FreeBSD のソースツリーについて 作業をおこなっている人々がいます。 すべてのコアチームのメンバはまた開発者でもあります。 (姓でアルファベット順) &contrib.committers; FreeBSD ドキュメンテーションプロジェクト FreeBSD ドキュメンテーションプロジェクトは複数のサービスを提供 しています。それぞれのサービスは、以下の担当者とその 副担当者によって運用されています。 ドキュメンテーションプロジェクト担当 &a.nik; ハンドブック編集担当 &a.doc; FAQ 編集担当 &a.doc; ニュースフラッシュ編集担当 &a.jim; In the Press 編集担当 &a.jkoshy; FreeBSD Really-Quick NewsLetter編集担当 Chris Coleman chrisc@vmunix.com ギャラリーページ担当 &a.phantom; 商用ベンダーページ担当 &a.ceri; ユーザグループ担当 &a.grog; FreeBSD &java; プロジェクト &a.patrick; LinuxDoc から DocBook への移行 &a.nik; 担当者 ドキュメンテーションプロジェクト担当 &a.nik; CVSup ミラーサイトコーディネータ &a.cvsup-master; 担当: &a.kuriyama; (責任者), &a.jdp; (アドバイザ) 地域化 &a.ache; ポストマスタ &a.jmb; リリースコーディネーション &a.re; (リーダは &a.murray;) 広報および渉外担当 空席 セキュリティオフィサ &a.security-officer; (リーダは &a.nectar;) CVS ツリー管理者 責任者: &a.peter; 副責任者: &a.markm;, &a.joe; ウェブサイト管理者 &a.www; Ports Collection 担当 &a.portmgr; 以下のメンバで構成されています。 &a.asami;, &a.knu;, &a.kris;, &a.lioux;, &a.marcus;, &a.sobomax;, &a.steve;, &a.will; 標準化担当 &a.wollman; XFree86 Project, Inc. との渉外担当 &a.rich; GNATS 管理者 &a.steve; Bugmeister &a.ceri; 寄贈品受付事務局 &a.donations; 以下のメンバで構成されています。 &a.mwlucas &a.nsayer &a.obrien &a.rwatson &a.trhodes コアチームの卒業生 コアチーム (core team) 次にあげる人々は () で記した期間、FreeBSD コアチームのメンバーでした。FreeBSD プロジェクトにおける彼らの努力に感謝の意を表します。 だいたいの年代順 &contrib.corealumni; 開発チームの卒業生 開発チーム (development team) 次にあげるのは、かつて FreeBSD 開発チームの一員だった人々です。 FreeBSD プロジェクトに貢献してくださった彼らに感謝します。 ほぼ年代順に: &contrib.develalumni; BSD 派生ソフトウェアへの貢献者 このソフトウェアは最初は William F. Jolitz の 386BSD release 0.1 から派生しましたが、オリジナルの 386BSD に固有のコードはほとんど残っていません。 このソフトウェアは基本的にはカリフォルニア大学 バークレイ校の Computer Science Research Group (CSRG) とその共同研究者 たちによる 4.4BSD-Lite リリースから再実装されました。 また、NetBSD や OpenBSD の一部も FreeBSD に取り込まれています。したがって私たちは NetBSD と OpenBSD へ貢献した人々すべてに感謝します。 その他の FreeBSD への貢献者 (名前でアルファベット順) &contrib.additional; 386BSD パッチキットへのパッチ提供者 (名前でアルファベット順): &contrib.386bsd;
diff --git a/ja_JP.eucJP/articles/dialup-firewall/article.sgml b/ja_JP.eucJP/articles/dialup-firewall/article.sgml index 7071eec378..bf398f220e 100644 --- a/ja_JP.eucJP/articles/dialup-firewall/article.sgml +++ b/ja_JP.eucJP/articles/dialup-firewall/article.sgml @@ -1,457 +1,453 @@ -%man; - -%ja-trademarks; - -%trademarks; + +%articles.ent; ]>
FreeBSD によるダイアルアップ式ファイアウォールの構築 Marc Silver
marcs@draenor.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; この記事は FreeBSD の PPP ダイアルアップと IPFW を用いながらどのようにファイアウォールをセットアップするか、 特に動的に割り当てられた IP アドレスによるダイアルアップ上のファイアウォールについて、 事実を元に詳細に説明します。 なお、前段階である PPP 接続についての設定は触れていません。 序文 FreeBSD によるダイアルアップ式ファイアウォールの構築 この文書はあなたの ISP によって IP アドレスを動的に割り当てられた時、 FreeBSD でファイアウォールをセットアップするために 要求される手順を扱うことをめざしたものです。 この文書を可能な限り有益で正確なものにするために努力しているので、 どうぞ意見や提案を marcs@draenor.org に送って下さい。 カーネルオプション 最初になすべきことはカーネルを再コンパイルすることです。 カーネルを再コンパイルする方法についてさらに情報が必要なら、 ハンドブックの カーネルのコンフィグレーションの節から読み始めるのが最適でしょう。 カーネルを以下のオプションをつけてコンパイルする必要があります: options IPFIREWALL カーネルのファイアウォールのコードを有効にします。 options IPFW2 新しいバージョンの IPFW を有効にします。 FreeBSD 4.X を運用している場合にのみ、 このオプションをつけてください。 (訳注: FreeBSD 5.X のような) 最近の FreeBSD では、 これがデフォルトになっています。 options IPFIREWALL_VERBOSE システムの logger へ記録されたパケットを送ります。 options IPFIREWALL_VERBOSE_LIMIT=100 記録されるマッチするエントリの数を制限します。 これはログファイルがたくさんの繰返しのエントリで一杯になるのを抑制します。 100 は使用上無理のない数ですが、 自分の要求に基づいて調整することができます。 options IPDIVERT divertソケット (後述) を有効にします。 更なるセキュリティのために、 カーネルの中に組み込むことのできるオプションが他にいくつかあります。 これらはファイアウォールを動かすためには必要ではありませんが、 セキュリティに猛烈にこだわるユーザは有効にしてかまいません。 options TCP_DROP_SYNFIN このオプションは SYN と FIN のフラグをもった TCP パケットを無視します。 これは マシンの TCP/IP スタックを識別するので security/nmap などのようなツールを妨げることができます。 しかし RFC1644 拡張のサポートに違反しています。 これは現在稼働している web サーバには推奨しません。 いったんカーネルを再コンパイルしたら再起動しないで下さい。 希望的にも、 ファイアウォールの設置を完了するために一回だけ再起動する必要があります。 ファイアウォールを搭載するように <filename>/etc/rc.conf</filename> を変更する ファイアウォールを機能させるために、 /etc/rc.conf を若干変更する必要があります。 単純に以下の行を加えてください。 firewall_enable="YES" firewall_script="/etc/firewall/fwrules" natd_enable="YES" natd_interface="tun0" natd_flags="-dynamic" 上記の設定に関するより詳しい情報は /etc/defaults/rc.conf を参照した上で、 &man.rc.conf.5; を読んで下さい。 PPP のネットワークアドレス変換を無効にする もしかすると既に PPP の組込みネットワークアドレス変換 (NAT) を利用しているかも知れません。 それを無効化しなければならない場合であるなら、 &man.natd.8; の例を使い、同じようにして下さい。 既に PPP の自動スタートのエントリのまとまりがあるなら、 多分こんなふうになっているでしょう: ppp_enable="YES" ppp_mode="auto" ppp_nat="YES" ppp_profile="profile" もしそうなら、/etc/rc.conf に (訳注: /etc/defaults/rc.conf で定義されている ppp_nat の初期値は YES なので) ppp_nat="NO" を明示的に設定して無効にする必要があります。 また /etc/ppp/ppp.conf の中の nat enable yes または alias enable yes を削除する必要があるでしょう。 ファイアウォールへのルールセット さて、ほとんどのことをやりおわりました。 残る最後の仕事はファイアウォールのルールを定義することです。 それから再起動すると、ファイアウォールが立ち上がり稼働するはずです。 私はルールベースを定義する段階に達すると、 すべての人が若干異なる何かを求めているのだと実感しています。 私が努力してきたのは、 ほとんどのダイアルアップユーザに適合したルールセットを書くことです。 あなたは自分の必要のために以下のルールを土台として用いることによって 自分用のルールベースに変更することができます。 まず、閉じたファイアウォールの基礎から始めましょう。 望むのは初期状態ですべてを拒否することです。 それからあなたが本当に必要とすることだけのためにファイアウォールをあけましょう。 ルールはまず許可し、それから拒否するという順番であるべきです。 その前提はあなたの許可のための規則を付加するということで、 それから他の全ては拒否されます。:) では /etc/firewall ディレクトリを作成しましょう。 ディレクトリをそこへ変更し、 rc.conf で規定した fwrules ファイルを編集します。 このファイル名を自分が望む任意のものに変更できるということに気をつけてください。 この手引きはファイル名の一例を与えるだけです。 それでは、ファイアウォールファイルの設定例を見てみましょう。 注釈も参考にしてください。 # (/etc/rc.firewall にあるように) 参照を簡単にするためにファイアウォールの # コマンドを定義します。読みやすくするのに役立ちます。 fwcmd="/sbin/ipfw" # 再読込みする前に現在のルールの消去を強制します。 $fwcmd -f flush # トンネルインタフェースを通じてすべてのパケットを divert します。 $fwcmd add divert natd all from any to any via tun0 # 動的ルールを持つすべての接続を許可します。ただし、動的ルールを持たない # RST か ACK ビットがセットされている TCP 接続は拒否します。 # 詳細は ipfw(8) をご覧ください。 $fwcmd add check-state $fwcmd add deny tcp from any to any established # ローカルホスト内のすべての接続を許可します。 $fwcmd add allow tcp from me to any out via lo0 setup keep-state $fwcmd add deny tcp from me to any out via lo0 $fwcmd add allow ip from me to any out via lo0 keep-state # 自分が着手した、自ネットワークからのすべての接続を許可します。 Allow all connections from my network card that I initiate $fwcmd add allow tcp from me to any out xmit any setup keep-state $fwcmd add deny tcp from me to any $fwcmd add allow ip from me to any out xmit any keep-state # 以下のサービスへ接続することをインターネット上のすべての人に許可します。 # この例では sshd とウェブサーバへの接続を許可します。 $fwcmd add allow tcp from any to me dst-port 22,80 in recv any setup keep-state # すべての ident パケットに RESET を送ります。 $fwcmd add reset log tcp from any to me 113 in recv any # ICMP プロトコルを有効にします。自ホストを ping(8) に応答させたくなければ、 # icmptypes から 8 を削除してください。 $fwcmd add allow icmp from any to any icmptypes 0,3,8,11,12,13,14 # 残りの全てを拒否します。 $fwcmd add deny log ip from any to any あなたは 22 番と 80 番のポートへの接続を許可し、 それ以外に試みられるすべての接続を記録する 十分に機能的なファイアウォールを手にしました。 では、あなたは安全に再起動することができて、 あなたのファイアウォールはうまく立ち上がるはずです。 もしこれに正しくないことを見つけたら、 もしくは任意の問題を経験したら、 さもなくばこのページを向上させるための任意の提案があるなら、 そのいずれにしても、どうか私に電子メールを下さい。 質問 組込みの &man.ppp.8; フィルタを使ってもよいのに、 なぜ &man.natd.8; と &man.ipfw.8 を使っているのですか? 正直に言うと、 組込みの ppp フィルタの代わりに ipfw と natd を使う決定的な理由はないと言わなければなりません。 いろいろな人と繰り返してきた議論より、 ipfw は確かに ppp フィルタよりもパワフルで設定に融通がきく一方、 それが機能的であるために作り上げたものはカスタマイズの容易さを 失っているということで意見の一致をみたようです。 私がそれを使う理由のひとつはユーザランドのプログラムでするよりも、 カーネルレベルで行うファイアウォールの方を好むからです。 limit 100 reached on entry 2800 のようなメッセージを受け取った後、 ログの中にそれ以上の拒否を全く見なくなりました。 ファイアウォールはまだ動作しているのでしょうか? 単にルールのログカウントが最大値に達したということを意味しています。 ルール自身はまだ機能していますが、 ログカウンタをリセットするまでそれ以上ログを記録しません。 ipfw resetlog コマンドにより、 ログカウンタをリセットすることができます。 また、この限界値を上述の オプションで 変更することもできます。 さらに、この値は (カーネルを再構築して再起動せずに) net.inet.ip.fw.verbose_limit を &man.sysctl.8; で変更することができます。 もし内部で 192.168.0.0 の範囲のようなプライベートアドレスを使用しているなら、 $fwcmd add deny all from any to 192.168.0.0:255.255.0.0 via tun0 のようなコマンドを 内部のマシンへ試みられる外部からの接続を防止するために ファイアウォールのルールに追加してもいいですか? 端的な答えは no です。 この問題に対するその理由は natd は tun0 デバイスを通して divert されている あらゆるもの に対してアドレス変換を行っているということです。 それが関係している限り、 入ってくるパケットは動的に割り当てられた IP アドレスに対してのみ話し、 内部ネットワークに対しては話さないのです。 ファイアウォール経由で外へ出て行くホストから あなたの内部ネットワーク上のホストを制限する $fwcmd add deny all from 192.168.0.4:255.255.0.0 to any via tun0 のようなルールを追加することができるということにも気をつけてください。 何か間違っているに違いありません。 私はあなたの説明に文字通り従いましたが、 締め出されてしまいました。 このチュートリアルはあなたが userland-ppp を稼働していて、その結果 tun0 [&man.ppp.8; (またの名を user-ppp) で作られる最初の接続に相当します] インタフェース上で供給されたルールセットが動作していることを想定しています。 さらなる接続は tun1、tun2 などを用います。 &man.pppd.8; が ppp0 インタフェースを代わりに用いるということにも注意するすべきです。 よって &man.pppd.8; による接続を始めるなら ppp0 の代わりに tun0 を用いて下さい。 この変更を反映するファイアウォールのルールを 編集する早道は以下に示されています。 元のルールセットは fwrules_tun0 としてバックアップされています。 &prompt.user; cd /etc/firewall /etc/firewall&prompt.user; su Password: /etc/firewall&prompt.root; mv fwrules fwrules_tun0 /etc/firewall&prompt.root; cat fwrules_tun0 | sed s/tun0/ppp0/g > fwrules いったん接続が確立したら、 現在 &man.ppp.8; か &man.pppd.8; のどちらを利用しているかを知るために &man.ifconfig.8; の出力で検査することができます。 例として、&man.pppd.8; で作成された接続では、 このようなものが目にするでしょう (関係のあるものだけ示しています)。 &prompt.user; ifconfig (skipped...) ppp0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xff000000 (skipped...) 他方で、&man.ppp.8; (user-ppp) で作成された接続では、 あなたはこれに似たものを目にするはずです。 &prompt.user; ifconfig (skipped...) ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 (skipped...) tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 (IPv6 stuff skipped...) inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xffffff00 Opened by PID xxxxx (skipped...)
diff --git a/ja_JP.eucJP/articles/diskless-x/article.sgml b/ja_JP.eucJP/articles/diskless-x/article.sgml index 8cc3725907..3195662601 100644 --- a/ja_JP.eucJP/articles/diskless-x/article.sgml +++ b/ja_JP.eucJP/articles/diskless-x/article.sgml @@ -1,395 +1,391 @@ -%man; - -%ja-trademarks; - -%trademarks; + +%articles.ent; ]>
ディスク無しの X サーバ: 一つのガイド Jerry Kendall
jerry@kcis.com
1996/12/28 1996 Jerry Kendall &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.microsoft; &tm-attrib.sun; &tm-attrib.general; FreeBSD-hackers メーリングリストの友人たちの助けによって、 わたしはディスクの無い X 端末を作ることができました。 X 端末の作成には、NFS によってマウントされた最小のユーティリティを持つ ディスク無しのシステムを作らなくてはなりませんでした。 同じ方法を使って 2 つの別々なディスク無しのシステムを作りました。 一つ目は altair.example.com です。 それは 340M のハードディスクが付いていますが、交換したくありませんでした。 そのため、そのマシンは antares.example.com からイーサネットを通じてブートするようになっています。 2 つ目のシステムは 486DX2-66 です。 わたしは全くローカルディスクのないディスク無しの FreeBSD を (完璧に) セットアップしました。 その場合のサーバは &sunos; 4.1.3 が動いている Sun 670MP です。 セットアップの設定は両方に同じものが必要でした。 わたしはこの文書に加えなくてはならない内容がまだあると思っています。 どんなことでもご意見がありましたら送ってください。 ブートフロッピーを作る (ディスク無しのシステム上で) ネットワークローダは TSR などの &ms-dos; が使うものがあるとうまく働かないことがあるので、 最も良い方法は専用のブートフロッピーを作るか、 もしできれば、&ms-dos; のメニューを作ってシステムが起動するときにどの設定を有効にするかを聞いてくるようにすることです。 (config.sys/autoexec.bat ファイルによって) 次に挙げるのはわたしが使っているもので、ちゃんと動作しているものです。 わたしの &ms-dos; (6.x) メニューを下に載せます。 <filename>config.sys</filename> [menu] menuitem=normal, normal menuitem=unix, unix [normal] .... normal config.sys stuff ... [unix] <filename>autoexec.bat</filename> @ECHO OFF goto %config% :normal ... normal autoexec.bat stuff ... goto end :unix cd \netboot nb8390.com :end ネットワークブートのプログラムを手に入れる (サーバ上で) /usr/src/sys/i386/boot/netboot にある net-boot プログラムをコンパイルしてください。 そのときには Makefile の先頭にあるコメントを読んでおきましょう。 要求されるように調整してください。 念のために、オリジナルのファイルはどこかにバックアップを取っておいてください。 ビルドが終わったら、2 つの &ms-dos; の実行ファイル nb8390.com と nb3c509.com ができているはずです。 これらの 2 つのプログラムの 1 つはディスク無しのサーバ上で動かすのに必要になるものです。 それはブートサーバからカーネルをロードするものです。 ここでは両方のプログラムを先程作った &ms-dos; のブートフロッピーに入れておきます。 どのプログラムを実行するかを調べる (ディスク無しのシステム上で) もしあなたのイーサネットアダプタが使っているチップセットを知っているなら、 これは簡単なことです。もしそれが NS8390 チップセットか、 NS8390 をベースとするチップセットであれば、nb8390.com を使ってください。もし &tm.3com; 509 をベースとするチップセットなら、 nb3C509.com ブートプログラムを使ってください。 もしあなたの持っているものがよくわからなければ、一つ試してみて、そこで No adapter found と言われたらまた他のを試してみてください。それでもだめだったら、 あなたのものはとても珍しいということです。 ネットワークと通じてブートする config.sys/autoexec.bat ファイルも使わずにディスク無しのシステムを立ち上げてみてください。 あなたのイーサネットアダプタのためのブートプログラムを実行してみましょう。 わたしのイーサネットアダプタは WD8013 16bit モードで動いているので nb8390.com を実行します。 C:> cd \netboot C:> nb8390 Boot from Network (Y/N) ? Y BOOTP/TFTP/NFS bootstrap loader ESC for menu Searching for adapter.. WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66 Searching for server... ここでは、 わたしのディスク無しのシステムはブートサーバとして振る舞うようなマシンを探しにいこうとします。 上の addr 行を記録しておいてください。 あとからその数が必要になります。ディスク無しのシステムを再起動して、 あなたの config.sys や autoexec.bat ファイルを修正して これらの操作が自動で行われるようにしてください。 おそらくメニューの部分になるでしょう。 もし nb3c509.com を nb8390.com の代わりに使わなくてはいけなかったとしても、出力は上と同じです。 もし Searching for adapter.. というメッセージが出るときに No adapter found ということを言われたら、 Makefile で定義されているコンパイル時間が正しくセットされているかどうかを確認してみてください。 システムがネットワーク越しにブートすることを許可する (サーバ上で) /etc/inetd.conf ファイルが tftp や bootps についてのエントリを持っているかどうかを確認してください。 わたしのは次のようになっています。 tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot # # Additions by who ever you are bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab もし /etc/inetd.conf ファイルを変更したときには、 &man.inetd.8 に HUP シグナルを送ってください。 これをするには、inetd のプロセス ID を ps -ax | grep inetd | grep -v grep して 取得してください。プロセス ID がわかったら、 それに向けて HUP シグナルを送ってください。 これは kill -HUP <pid> として行います。 これによって inetd はその設定ファイルを読み直します。 ディスク無しシステム上でブートローダが出力した addr の出力を覚えているでしょうか? ここでそれが必要となるのです。 /etc/bootptab (おそらくファイルを作成して) に エントリを加えてください。それはこれと同様の書式で書きましょう。 altair:\ :ht=ether:\ :ha=004001432666:\ :sm=255.255.255.0:\ :hn:\ :ds=199.246.76.1:\ :ip=199.246.76.2:\ :gw=199.246.76.1:\ :vm=rfc1048: これらの行は次のような意味です。 altair ドメイン名を除いたディスク無しのシステムの名前 ht=ether イーサネットハードウェアタイプ ha=004001432666 (先に記録した) ハードウェアのアドレス sm=255.255.255.0 サブネットマスク hn クライアントにクライアントのホスト名を送るよう、 サーバに伝えます ds=199.246.76.1 ドメインサーバがどれなのかをクライアントに伝えます ip=199.246.76.2 クライアントの IP アドレスが何なのかを クライアントに伝えます gw=199.246.76.1 デフォルトゲートウェイがどれなのかを クライアントに伝えます vm=... これはそのままにしておいてください IP アドレスは正しく設定してください。 上のアドレスはわたしだけのものです。 /tftpboot ディレクトリをサーバに作成して、 サーバがサービスを行うディスク無しのシステムのための設定ファイルをこのディレクトリに入れておきます。 これらのファイルは cfg.ip という名前になっていて、ip はディスク無しシステムの IP アドレスを表しています。 altair の設定ファイルは /tftpboot/cfg.199.246.76.2 となります。この中身は次のようになっています: rootfs 199.246.76.1:/DiskLess/rootfs/altair hostname altair.example.com hostname altair.example.com の行は単にディスク無しのシステムがどのような完全なドメイン名を持っているのかを表しています。 rootfs 199.246.76.1:/DiskLess/rootfs/altair の行はディスク無しのシステムが NFS でマウントできるルートファイルシステムの場所を表しています。 NFS でマウントされたルートファイルシステムは 読み出し許可だけで マウントされます。 ディスク無しのシステムの階層は要求されれば読み書き可能にして、 マウントし直すことができます。 わたしは予備の 386DX-40 を専用の X 端末として使用しています。 altair の階層は次の通りです。 / /bin /etc /tmp /sbin /dev /dev/fd /usr /var /var/run 実際のファイルのリストは次の通りです。 -r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel -r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh -rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc -rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys -rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts -rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair -r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init -r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig -r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs -r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot -r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount -r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local -r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV (FreeBSD 5.X において初期状態で有効になっている) &man.devfs.5; を利用していないのであれば、dev ディレクトリで MAKEDEV all するのを忘れずに。 altair の /etc/rc は 次の通りです。 #!/bin/sh # PATH=/bin:/ export PATH # # localhost の設定 /sbin/ifconfig lo0 127.0.0.1 # # イーサネットカードの設定 /sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00 # # NFS で root ファイルシステムをマウントする /sbin/mount antares:/DiskLess/rootfs/altair / # # NFS で /usr ファイルシステムをマウントする /sbin/mount antares:/DiskLess/usr /usr # /usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1 # # X を終了すると再起動 /sbin/reboot # # うまく行かないときには.... exit 1 コメントや質問はどんなものでも歓迎します。
diff --git a/ja_JP.eucJP/articles/fbsd-from-scratch/article.sgml b/ja_JP.eucJP/articles/fbsd-from-scratch/article.sgml index 4cfee7ea08..335fc8c817 100644 --- a/ja_JP.eucJP/articles/fbsd-from-scratch/article.sgml +++ b/ja_JP.eucJP/articles/fbsd-from-scratch/article.sgml @@ -1,639 +1,633 @@ -%man; - -%freebsd; - -%ja-trademarks; - -%trademarks; + +%articles.ent; FreeBSD をゼロから設定する"> ]>
FreeBSD をゼロから設定するには Jens Schweikhardt
schweikh@FreeBSD.org
 2002 Jens Schweikhardt $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.general; この記事は、「&scratch.ap; (FreeBSD From Scratch)」という、 わたしの個人的な経験をまとめたものです。 カスタマイズした &os; システムをソースからコンパイルし、 さらに好みの ports のコンパイルして、 あなたが望む構成のシステムの、 完全に自動化されたインストールを実現します。 make world がすばらしい考え方だとお思いの方にとって、 「&scratch.ap;」は、まさに make world を make evenmore (さらにその先) へと広げるものになることでしょう。 はじめに 今までに make world を使ってシステムをアップグレードした経験はあるでしょうか? もしディスクに一つのシステムしか入れていない場合は問題です。 installworld が途中で止まってしまったら、 あなたのシステムは壊れたまま、もう起動しなくなってしまうかも知れません。 あるいは、installworld が正常に終了しても、 新しいカーネルは起動に失敗してしまうかも知れません。 さて、そうなってしまったら、Fixit CD を取り出して半年前のバックアップを戻す、 なんてはめになってしまうかも知れませんよね。 わたしは、アップグレードの時はディスクを初期化する という方法がよいと考えています。パーティションではなくディスク全体のデータを 消去することで、アップグレードの手順では無視されるような古いデータが 残ってしまうことを防ぐことができます。ただ、 パーティションを全部初期化するということは、 ports/packages をすべて再コンパイル・再インストールしなければならず、 設定ファイルも注意深く作成し直さなければならないということです。 こういう作業を自動化したいと思いませんか? そう思う人は、この先を読み進めましょう。 どうして「&scratch.ap;」(あるいは「〜しない」) ことが必要なのか これはもっともな質問です。 すでに sysinstall がありますし、 カーネルとユーザランドツールをコンパイルする方法には、 もっと有名な方法が他にもあるからです。 sysinstall の問題は、「何を、どこに、 どうやってインストールするのか」が非常に限定されているという点です。 sysinstall は通常、構築ずみの配布物セットと packages を (CD, DVD, FTP などの) 別の場所からインストールする時に使われるものであり、 make buildworld の結果をインストールできるようにはできていません。 現在稼働中のシステム中にあるディレクトリに、 新しいシステムをインストールすることはできません。 Vinum パーティションへのインストールはできません。 構築ずみの packages はインストールできますが、 ports を構築することはできません。 スクリプトを使ったり、 インストール後に変更するための処理を自由に入れることは困難です。 最後の大きな理由として、sysinstall が、公式にもう積極的に使わないプログラムと考えられている、 ということがあげられます。 システム全体を構築してインストールする方法は、 ハンドブックにある方法が有名です。 これはデフォルトで既存のシステムを置き換えるもので、 カーネルとモジュールだけが保存され、 システムバイナリ、ヘッダ、その他の多くのファイルは上書きされます。 使われなくなった古いファイルはそのまま残り、 動作に問題が出ることもあります。 何らかの理由でアップグレードに失敗すると、 システムを元の状態に戻することは不可能か、できても非常に困難です。 「&scratch.ap;」方法は、これらの問題をすべて解決できます。 考え方は単純です。 稼働中のシステムを使って空のディレクトリにシステムをインストールします。 その時、その新しいシステムのディレクトリツリーには、 新しいパーティションを適切にマウントしておaきます。 数多くある設定ファイルは、コピーできるものは適切な場所にコピーし、 それができないものには &man.mergemaster.8; を使います。 新しいシステムに対するインストール後の設定は、 古いシステムを動作させながら、新しいシステムに対して chroot して 自由に行なうことができます。具体的には、 シェルスクリプト、もしくは make の実行で構成される、次の 3 段階でこれらを実現します。 stage_1.sh: 新しい起動可能なシステムを空のディレクトリ以下に作成し、 必要なファイルをマージ、もしくはコピーします。 そして、新しいシステムを起動します。 stage_2.sh: 必要な ports をインストールします。 stage_3.mk: ひとつ前の段階でインストールしたソフトウェアの、 インストール後の設定を行ないます。 新しいシステムを構築するために「&scratch.ap;」方法を使い、 それが数週間、満足する程度に動作していることを確認したら、 もう一度それを使って、大元のシステムを再インストールすることができます。 これからはいつでも好きな時にシステムを更新して、 初期化・再インストールしたパーティションに切り替えるだけでよくなるわけです。 Linux From Scratch (もしくは省略して LFS) について耳にしたり、試された方がいらっしゃるかも知れません。 LFS も同じように、稼働中のシステムを使ってシステムをゼロから構築し、 空のパーティションにインストールする方法が書かれています。 LFS が話題の中心としているのは、(カーネル、コンパイラ、デバイス、 シェル、端末データベースなどの) 各システムコンポーネントの役割と、 それらのインストールの詳細を見せることのようです。 この「&scratch.ap;」では、そのような詳細には触れません。 わたしの目的は、インストールを終わりまで自動化することであり、 システム構築時の泥くさい過程を全部説明することではありません。 &os; をそのようなレベルで掘り下げてみたい人は、 /usr/src/Makefile を読んで、 make buildworld の動作を追いかけるところから始めましょう。 また、「&scratch.ap;」方法にも、 次のような欠点があることを心に留めておいてください。 第 2 段階で ports をコンパイルしている間、 システムは通常の用途に使用することができません。 もしプロダクションサーバを運用しているなら、 第 2 段階でダウンタイムが発生することを考慮に入れなければなりません。 stage_2.sh の ports のコンパイルには、 AMD1800+、10,000rpm SCSI、1GB の RAM を搭載したシステムで、 約 4 時間かかります。 前提とする環境 「&scratch.ap;」方法を実行するには、 次のものが必要です。 ソースと ports ツリーを含む、稼働中の &os; システム 新しいシステムをインストールするための、 最低 1 個の未使用パーティション &man.mergemaster.8; を実行した経験。もしくは、 それを実行する勇気。 インターネット接続環境がない、あるいは遅い場合には、 インストールしたい ports の配布ファイル Bourne シェル (&man.sh.1;) を使ってシェルスクリプトを作成するための基礎知識 新しいシステムを起動する方法を、 対話的あるいは設定ファイルを使ってブートローダに 教えることができること 第 1 段階: システムのインストール 次に紹介するのは、わたしが作成した stage_1.sh です。あなたが求めているシステムに合うように、 カスタマイズしてください。カスタマイズしなければならないところには、 なるべく詳細なコメントを付けてあります。重要なポイントは、 以下のとおりです。 パーティションの配置 わたしは、システム全体を一つの大きな パーティションに入れるという考え方が好きではないので、 普通は /、 /usr、 /var の パーティションを分割し、/tmp を /var/tmp のシンボリックリンクにしています。 また、/home (ユーザのホームディレクトリ)、 /home/ncvs (&os; CVS リポジトリの複製), /usr/ports (ports ツリー), /src (チェックアウトした src ツリー)、 /share (news スプールなど、バックアップする必要がない、 その他の共有データ) といったファイルシステムを、 古いシステムと新しいシステムで共有しています。 その他の項目 これは、新しいシステムの起動後にすぐに実行したいことや、 第 2 段階の前に実行したい内容のことです。 わたしの場合は、/etc/passwd に ログインシェルとして shells/zsh が登録してあるので、それになります。 厳密には、この「その他の項目」を実行する必要は必ずしもありません。 root ユーザでログインして、次の段階を実行できさえすればよいからです。 第 1 段階で単純に好みの ports をすべてインストールしないのは、 理論的、あるいは実践的な面においてブートストラップ問題と依存問題があるからです。 第 1 段階では古いカーネルが動作しているのですが、 chroot した環境では新しいバイナリとヘッダが含まれています。 たとえば、新しいシステムが (新しいヘッダに従って) 新しいシステムコールをサポートしていた場合、 configure スクリプトがそれを使おうとしてしまうかも知れません。 そうすると、古いカーネルは対応していないので異常終了してしまうでしょう。 わたしが lang/perl5 をコンパイルした時には、他にも問題が発生するのを確認しています。 stage_1.sh を実行する前に、 make installworld installkernel を実行するために通常行なう作業を完了させておいてください。 これらは、たとえば次のようなものです。 カーネルコンフィグファイルの設定 make buildworld を正常終了させておくこと make buildkernel KERNCONF=whatever を正常終了させておくこと 初めて stage_1.sh を実行した場合は、 稼働中のシステムから新しいシステムへとコピーされる設定ファイルは /usr/src のものと比べると古いので、 mergemaster がどうするかを聞いてきます。 おすすめは、ここで変更点を統合しておくことです。 もし、何度も質問に答えるのが面倒であれば、 稼働中のシステムのファイルを更新しておきましょう (ただしこれは、そうできればの話です。 -STABLE のシステムを実行していて、 -CURRENT を構築する、 もしくはその逆のようなケースでは、そうしてはいけません)。 次に mergemaster を実行した時、 RCS バージョン ID が /usr/src にあるファイルと一致しているものは、処理が飛ばされるようになります。 stage_1.sh スクリプトは set -e が指定されており、 最初のコマンドが失敗 (終了コードが 0 以外) すると停止します。 そのため、エラーを見逃してしまうということはないでしょう。 次に進む前に、stage_1.sh にあるエラーを全部修正しておいてください。 stage_1.sh では mergemaster が実行されます。 統合作業をしなければならないファイルが一つもない状態でも、 実行の終わりに次のメッセージが表示されます。 *** Comparison complete Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] no no と答えるか、 単に Enter を押してください。 なぜかと言うと、mergemaster は /var/tmp/temproot.stage1 にサイズが 0 のファイルをいくつか残すからです。 これは、後で新しいシステムに (存在しなければ) コピーされます。 この後、インストールされたファイルのリストがページャ (デフォルトでは &man.more.1; です。&man.less.1; を使うこともできます) に表示されます。 *** You chose the automatic install option for files that did not exist on your system. The following were installed for you: /newroot/etc/defaults/rc.conf ... /newroot/COPYRIGHT (END) q を入力してページャを終了します。 すると login.conf に関して、次のように表示されます。 *** You installed a login.conf file, so make sure that you run '/usr/bin/cap_mkdb /newroot/etc/login.conf' to rebuild your login.conf database Would you like to run it now? y or n [n] これに対する答えはどちらでも構いません。 どう答えても、スクリプトから &man.cap.mkdb.1; が実行されます。 ちゃんと予想どおりに動いているかチェックできるよう、 stage_1.sh で行なわれたことは、 すべて stage_1.log に記録されます。 次に示すのは、筆者の使っている stage_1.sh です。 特にステップ 1, 2, 5, 6 は書き換える必要があるでしょう。 &man.newfs.8; コマンドには注意してください。 マウントずみのパーティションに新しいファイルシステムを作成することはできないものの、 このスクリプトはマウントされていない /dev/da3s1a, /dev/vinum/var_a, /dev/vinum/usr_a をすべて削除します。 ひとつ間違えれば、あなたの環境を破壊してしまう可能性がありますので、 デバイス名の変更は注意深く行なってください。 このスクリプトを実行すると、 起動した時に次のような状態になっているシステムがインストールされます。 稼働中のシステムと同じユーザとグループ Ethernet と PPP を経由した、 ファイアウォールありのインターネット接続環境 正しいタイムゾーンと NTP 設定 /etc/ttys や inetd など、その他の細かな設定。 他の部分に対する設定は、第 2 段階が終わるまで動作しません。 たとえば、プリンタや X11 の設定ファイルもコピーされますが、 プリンタは &postscript; ユーティリティなど、 ベースシステムに含まれないアプリケーションを使うことが多いでしょう。 X11 はサーバ、ライブラリ、プログラムをコンパイルしないと動作しません。 第 2 段階: ports のインストール この段階で ports をコンパイルするのではなく、 (コンパイルずみの) packages をインストールすることもできます。 その場合、stage_2.sh は 単に pkg_add コマンドを羅列するだけになるでしょう。 読者のみなさんにとって、そういうスクリプトを書くのは難しくないと思いますので、 ここではもっと柔軟で、ports を使った伝統的な方法について考えることにします。 次に紹介する stage_2.sh スクリプトは、 わたしが好みの ports をインストールするために使ったものです。 これは何度でも実行でき、インストールずみの ports があれば、 飛ばして処理されます。スクリプトは 実行せず、実行される内容だけ を表示する (dryrun) オプション () があります。ports リストの編集や、環境変数の設定を変更しましょう。 ports リストは、空白で区切られた 2 個以上のキーワードからなっています。 カテゴリ、port 名に始まり、オプションとして port をコンパイルしてインストールするためのコマンド (デフォルトは make install) が続きます。 空白行と # から始まる行は無視されます。 おそらく多くの場合に考えなければならないのは、カテゴリ名と port 名だけでしょう。 ports によっては、たとえば次のように make 変数を使って微調整することができます。 www mozilla make WITHOUT_MAILNEWS=yes WITHOUT_CHATZILLA=yes install mail procmail make BATCH=yes install 実際には任意のシェルコマンドを指定できますので、 make を使う以外にも応用は可能です。 java linux-sun-jdk13 yes | make install news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install news/inn-stable の行は、 CONFIGURE_ARGS という シェル変数を定義した例です。 この port の Makefile は、 この指定した値を変数の初期値として、その他の必須の引数と一緒に使います。 これと news inn-stable make CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" install のようにして make 変数をコマンドラインに設定した場合との違いは、 こちらの場合に変数そのものを完全に上書きしてしまうという点です。 どの方法を使えばいいのかについては、各 port によります。 インストールしたい ports が、 対話的インストールを使っていないことを確認してください。 ports は、あなたが標準入力に明示的に指定したもの以外、 標準入力を読み込む動作をしてはいけません。 もし ports がそのように作られていると、ports はヒアドキュメントにある ports リストの次の行を読み込んで混乱してしまいます。 stage_2.sh を実行した時、 ある port が飛ばされたり、動作が止まってしまうようなことがあれば、 おそらくこれが原因でしょう。 次に示すのが、実際の stage_2.sh です。 これは、インストールされる port それぞれに対して LOGDIR/category+port という名前のログファイルを作成します。 stage_2.sh が共有パーティションになければ、 実行前に新しいシステムにこれをコピーするようにしてください。 第 3 段階 第 2 段階で、好みの ports がインストールされましたが、 ports には、設定を必要とするものがあります。 第 3 段階は、インストール後の設定を行なう段階です。 stage_2.sh の最後にこの段階を統合することもできたのですが、 わたしは port をインストールすることと初期設定を変更することが異なる工程であると考えたため、 独立した段階としています。 第 3 段階は、Makefile として実装しています。 これは、次のように実行することで、設定対象を簡単に選ぶことができるからです。 &prompt.root; make -f stage_3.mk target stage_2.sh の段階で、 stage_3.mk を共有パーティションに置くか、 新しいシステムのどこかにコピーするなどして、 新しいシステムが起動した時に stage_3.mk が使えるようにしておきましょう。 制限事項 対話的で、かつ make BATCH=YES install でのインストールに対応していない port の自動インストールは難しいかも知れません。 対話的にインストールする ports には、ライセンス条項の同意を尋ねられた時に yes と入力するだけのものがいくつかあります。 そのように入力が標準入力から読みとられる場合は、 適切な回答をインストールコマンド (通常は make install) にパイプで渡すことができます (stage_2.sh の java/linux-sun-jdk13 でとった方法がそうです)。 しかしこの方法は、たとえば editors/staroffice52 の場合にはうまく動きません。 これは X11 が実行されていることを要求するからです。 インストール手順には多くのクリックや文字入力が必要なので、 他の ports のように自動化することはできません。 わたしは、次のようにして問題を回避しました。 最初に古いシステムで staroffice の package を作成し、 &prompt.root; cd /usr/ports/editors/staroffice52 &prompt.root; make package ===> Building package for staroffice-5.2_1 Creating package /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz Registering depends:. Creating bzip'd tar ball in '/usr/ports/editors/staroffice52/staroffice-5.2_1.tbz' その後、第 2 段階で次のようにしたわけです。 &prompt.root; pkg_add /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz その他に、設定ファイルのアップグレード問題に気をつける必要があります。 一般的に、設定ファイルの書式や内容がいつ変更されるかを知ることはできません。 新しいグループが /etc/group に追加されるかも知れませんし、/etc/passwd に新しいフィールドが追加されるかも知れません。 このような例は、実際に過去にありました。 単純に古いシステムから新しいシステムに設定ファイルをコピーするだけで ほとんどの場合は十分なのですが、時には不都合な場合もあります。 古いファイルを上書きする方法でシステムをアップグレードしたら、 ローカルにある設定ファイルに新しく追加されたかも知れない項目を統合する目的で mergemaster を使うと思います。 しかし残念なことに、mergemaster はベースシステムに存在するファイルだけで、インストールした ports については何も処理を行なってくれません。 サードパーティ製ソフトウェアには、 リリースのたびに設定ファイルのフォーマットが変更され、 わたしをイライラさせるようなものもあります。 注意すること以外にできることはありませんが、 特にメジャーバージョンがあがった時は気を付けてください。 わたしは以前、ウェブサーバ、 ニュースサーバ、ニュースリーダのファイルを書き換えたり、 書き直すはめになったことがあります。 活発に開発が進められているソフトウェアはすべて、 設定ファイルの書式が変更されていないか確認しておきましょう。 わたしは 5-CURRENT から 5-CURRENT に更新するために 「&scratch.ap;」方法を数回使いましたが、 4-STABLE と 5-CURRENT の間で更新を行なった経験はありません。 異なるメジャーリリース番号の間は、非常の多数の変更が行なわれているため、 更新作業はもっと複雑なものになると思います。 (試したわけではないのですが) 4-STABLE から 4-STABLE への更新であれば、「&scratch.ap;」方法は問題なく動作するはずです。 4-STABLE のユーザは、次の点を考慮してください。 デバイスファイルシステム (&man.devfs.5;) を使ってなければ、 第 1 段階のステップ 6 で &man.MAKEDEV.8; を使い、 ハードウェア用のデバイスファイルを作成するとよいでしょう。
diff --git a/ja_JP.eucJP/articles/fonts/article.sgml b/ja_JP.eucJP/articles/fonts/article.sgml index 532f017088..8ae3f35fd4 100644 --- a/ja_JP.eucJP/articles/fonts/article.sgml +++ b/ja_JP.eucJP/articles/fonts/article.sgml @@ -1,1018 +1,1012 @@ -%freebsd; - -%man; - -%ja-trademarks; - -%trademarks; + +%articles.ent; ]>
フォントと FreeBSD A Tutorial Dave Bodenstab
imdave@synet.net
1996 年 8 月 7 日 (水) &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.apple; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.general; ここでは FreeBSD の syscons ドライバや X11、Ghostscript、Groff で利用することができるさまざまなフォントファイルについて説明しています。 また、syscons ディスプレイを 80x60 行モードに切り替える方法や、 上述のアプリケーションでタイプ 1 フォントを利用する方法を例示します。 はじめに 数多くのフォントのソースを入手することができますが、これらを FreeBSD でどのようにして使うかはあまりよく知られていないかもしれません。 その答えは、使いたいと思う構成要素の説明書を注意深く探すことによって見つけることができます。 しかし、これはとても時間がかかる作業です。本チュートリアルは、 フォントに関して興味がある向きに、 その近道を教えようと試みるものであります。 基本用語 フォント形式の種類やそれに関連したフォントファイルの拡張子は多数存在します。 その内でここで解説するものは以下の通りです。 .pfa、.pfb &postscript; タイプ 1 フォント。拡張子 .pfa は Ascii 形式のそして拡張子 .pfb は Binary 形式を意味する。 .afm タイプ 1 フォントに関連するフォントメトリック情報。 .pfm タイプ 1 フォントに関連するプリンタ用フォントメトリック情報。 .ttf &truetype; フォント。 .fot TrueType フォントへの間接的な参照ファイル (実際にはフォントファイルではない)。 .fon、.fnt スクリーン表示用ビットマップフォント。 .fot ファイルは、&windows; で用いられ、 実際の &truetype; フォント (.ttf) ファイルへのシンボリックリンクに類する役割を果たします。 .fon フォントも Windows で用いられていますが、 FreeBSD でこの形式のフォントを利用する方法を筆者は知りません。 どのフォント形式を利用できますか? どのフォントファイル形式が有用であるかは、 利用するアプリケーションに依ります。 FreeBSD 自身はフォントファイルは利用しません。 アプリケーションプログラムやドライバ (あるいはその両方) によっては、 あるフォントファイルを利用するようにできるかもしれません。 以下は、アプリケーション、及び、 ドライバとそれが利用できるフォントタイプの拡張子の対応表を簡単に示します。 ドライバ syscons .fnt アプリケーション Ghostscript .pfa、 .pfb、 .ttf X11 .pfa、 .pfb Groff .pfa、 .afm Povray .ttf 拡張子 .fnt は極めて頻繁に使われています。 (訳注: この拡張子がフォント (font) という名前から連想しやすいので) あるアプリケーションに特化したフォントを作成しようとした際にはいつでも、 この拡張子が選択される方がそうでないときよりもかなり多いのではないかと著者は疑っています。 このため、この拡張子を持つファイル全てが同じ形式にはなっていないようです。 特に、.fnt ファイルは FreeBSD 上では syscons によって利用されていますが、これと &ms-dos; や &windows; 環境で出会った .fnt とは同じ形式ではないかもしれません。 筆者は FreeBSD で提供されている以外の .fnt ファイルを利用する試みは一切行っていません。 仮想コンソールを 80x60 行モードに設定する まず、8x8 サイズのフォントがロードされていなくてはなりません。 そのためには、/etc/rc.conf に以下の行が含まれているべきです (フォントの名称をあなたの locale に対応するものに書き換えてください)。 font8x8="iso-8x8" # font 8x8 from /usr/share/syscons/fonts/* (or NO). 実際にモードを切り替えるコマンドは &man.vidcontrol.1; です。 &prompt.user; vidcontrol VGA_80x60 &man.vi.1; のような、さまざまなスクリーン指向のプログラムに対して、 現在の画面サイズが分かるようにしておかなくてはなりません。これは ioctl を通じて (&man.syscons.4; などの) コンソールドライバに呼び掛けることで行われ、 これらを一度に済ませるために、 これらのコマンドを起動用のスクリプトに書いておき、 これをシステム起動時に実行するかもしれません。 この方法では /etc/rc.conf に以下の行を追加します allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens 参考文献: &man.rc.conf.5;、&man.vidcontrol.1; タイプ 1 フォントを X11 で利用する X11 では、.pfa 形式、もしくは、 .pfb 形式のフォントのいずれも利用することができます。 X11 では、フォントは /usr/X11R6/lib/X11/fonts 以下のさまざまなサブディレクトリに置かれています。 それぞれのディレクトリにある fonts.dir ファイルの内容によって、 それぞれのフォントのファイルと X11 上でのフォント名が関連付けられています。 Type1 という名前のディレクトリが既に存在しています。 新しいフォントを追加する最も簡単な方法は、 このディレクトリのそのフォントファイルを置くことです。 新しいフォントは別なディレクトリに置いておき、Type1 ディレクトリに追加フォントへのシンボリックリンクを張る方がより優れています。 なぜなら、この方法をとることでオリジナルで供給されているフォントと混乱することなく、 これらのフォントを追加した跡を残すことがより簡単にできるからです。 この方法は、例えば、次のように行います。 フォントファイルを入れるディレクトリを作成します。 &prompt.user; mkdir -p /usr/local/share/fonts/type1 &prompt.user; cd /usr/local/share/fonts/type1 ここに .pfa または .pfb ファイルと .afm ファイルを置きます。 フォントの readme ファイルやその他のドキュメントをこのディ レクトリに置いても構いません。 &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.pfb . &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.afm . フォントのクロスリファレンスのためにインデックスを変更します。 &prompt.user; echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX さて、新しいフォントを X11 で利用するためには、 そのフォントファイルを利用できるようにし、そして、 フォント名のファイルを更新する必要があります。 X11 でのフォント名は次のようになっています。 -bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 | | | | | | | | | | | | \ \ | | | | | \ \ \ \ \ \ \ +----+- character set | | | | \ \ \ \ \ \ \ +- average width | | | | \ \ \ \ \ \ +- spacing | | | \ \ \ \ \ \ +- vertical res. | | | \ \ \ \ \ +- horizontal res. | | | \ \ \ \ +- points | | | \ \ \ +- pixels | | | \ \ \ foundry family weight slant width additional style 新しいフォントそれぞれに対して、新しい名前を付ける必要があります。 フォント付属のドキュメントにフォントに関する情報があれば、 名前を作る際の基になるかもしれません。そのような情報がない場合は、 フォントに対して &man.strings.1; を使うと何らかのアイデアが得ることができます。例えば、 &prompt.user; strings showboat.pfb | more %!FontType1-1.0: Showboat 001.001 %%CreationDate: 1/15/91 5:16:03 PM %%VMusage: 1024 45747 % Generated by Fontographer 3.1 % Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten. FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup /UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse {save true}{false}ifelse}{false}ifelse 12 dict begin /FontInfo 9 dict dup begin /version (001.001) readonly def /FullName (Showboat) readonly def /FamilyName (Showboat) readonly def /Weight (Medium) readonly def /ItalicAngle 0 def /isFixedPitch false def /UnderlinePosition -106 def /UnderlineThickness 16 def /Notice (Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def end readonly def /FontName /Showboat def --stdin-- この情報から、次のような名前が考えられます: -type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 この名前の構成は次の通りです。 型 (foundry) 新フォントは type1 と名付けることにしましょう。 族 (family) フォントの名前です。 重み (weight) normal (普通)、bold (太い)、medium (中間)、 semibold (やや太め) などがあります。上記の &man.strings.1; の出力より、 フォントの重みは medium であると考えられます。 傾斜 (slant) roman (ローマン体)、italic (イタリック体)、oblique (斜字体) などがあります。 ItalicAngle が0になっていることにより、 roman を使っています。 幅 normal (普通)、wide (幅広)、condensed (圧縮)、extended(拡張) などがあります。上記で調べた結果から、 normal を仮定します。 追加スタイル 通常は省略されますが、フォントに装飾用 (decorative) 英大文字が含まれていることをここで示します。 スペーシング proportional (プロポーショナル (訳注: 字形に応じて幅が変化するフォント)) または monospaced (単一幅フォント) があります。ここでは Proportional としてありますが、これは isFixedPitch が false (偽) になっているためです。 これらの名前は全て任意なのですが、 既存の慣習と互換性を保つよう努力すべきでしょう。X11 プログラムでは、 フォントはワイルドカードを含んだ名前で参照されます。ですから、 フォント名は何らかの意味づけを持って選択されるべきでしょう。 (訳注 : 適当なフォントを探すとき、) ある人は単純に以下の名前を使うことから始めるかもしれません。 …-normal-r-normal-…-p-… そして、 &man.xfontsel.1; で該当するフォントを調べてみて、そのフォントの形を見ながら、 名前を調節するかもしれません。 それでは、ここまでの例を完結させることにしましょう。 X11 に対してフォントをアクセスできるようにします。 &prompt.user; cd /usr/X11R6/lib/X11/fonts/Type1 &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . fonts.dir と fonts.scale を編集して、フォントを記述する行を追加し、最初の行にある総フォント数を増やします。 &prompt.user; ex fonts.dir :1p 25 :1c 26 . :$a showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 . :wq fonts.scale は fonts.dirと同一内容のようですので… &prompt.user; cp fonts.dir fonts.scale X11 に内容が変更されたことを伝えます。 &prompt.user; xset fp rehash 新しいフォントを試してみます。 &prompt.user; xfontsel -pattern -type1-* 参考文献: &man.xfontsel.1;、&man.xset.1;、The X Windows System in a Nutshell、O'Reilly & Associates タイプ 1 フォントを Ghostscript で利用する Ghostscript では、Fontmap に従ってフォントを参照しています。このファイルを X11 の fonts.dir ファイルと同様な方法で変更しなくてはなりません。Ghostscript では、 .pfa 形式または .pfb 形式のフォントのいずれか一方を使用することができます。 前章の例で登場したフォントを使って、ここではこのフォントを Ghostscript で使用する方法について述べます。 フォントを Ghostscript のフォントディレクトリに置きます。 &prompt.user; cd /usr/local/share/ghostscript/fonts &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . Ghostscript にフォントを認識させるために Fontmap を編集します。 &prompt.user; cd /usr/local/share/ghostscript/4.01 &prompt.user; ex Fontmap :$a /Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat . :wq Ghostscript を用いてフォントを試してみます。 &prompt.user; gs prfont.ps Aladdin Ghostscript 4.01 (1996-7-10) Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... /1899520 581354 1300084 13826 0 done. GS>Showboat DoFont Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... 1939688 565415 1300084 16901 0 done. >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< GS>quit 参考文献: Ghostscript バージョン4.01 で配布されている fonts.txt タイプ 1 フォントを Groff で利用する ここまでで新しいフォントを X11 と Ghostscript の両方で用いることができるようになりましたが、 この新しいフォントをどのようにすれば groff で使うことができるでしょうか? まず第一に、&postscript; のタイプ 1 フォントを扱っていますから、 これを適用できる groff デバイスは ps デバイスです。 次に、各々のフォントを groff で使用できるように作らなくてはなりません。 groff でのフォント名は /usr/share/groff_font/devps の中のファイル名になります。上述の例では、フォントファイルは /usr/share/groff_font/devps/SHOWBOAT とすることができるでしょう。このファイルは groff によって提供されているツールを用いて生成しなくてはなりません。 最初に afmtodit というツールを使います。 このコマンドは通常ではインストールされませんので、 ソースプログラム群から該当プログラムを取り出さなくてはなりません。 このファイルの最初の一行を変更しなくてはならないことが分かっています。 著者は次のようにしました。 &prompt.user; cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp &prompt.user; ex /tmp/afmtodit.pl :1c #!/usr/bin/perl -P- . :wq このツールはメトリックファイル (.afm 拡張子) から groff フォントファイルを生成してくれます。 フォント使用方法例を続けることにしましょう。 .afm ファイルの多くは Mac 形式&hellip すなわち行が ^M で区切られています。 これを行を ^J で区切る &unix; スタイルに変換する必要があります。 &prompt.user; cd /tmp &prompt.user; cat /usr/local/share/fonts/type1/showboat.afm | tr '\015' '\012' >showboat.afm そして、groff フォントファイルを生成します。 &prompt.user; cd /usr/share/groff_font/devps &prompt.user; /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT これでフォントを SHOWBOAT という名前で参照することができました。 システムでプリンタを扱うために GhostScript を使用しているならば、 これで作業は完了しました。しかしながら、本当に PostScript プリンタを使っている場合は、フォントを使用可能にする為に、 当該フォントをプリンタにダウンロードする必要があります (showboat フォントがプリンタに偶然にも最初から組み込まれている場合、 もしくはプリンタからアクセスされるフォントディスクの中に入っている場合はこの限りではありません)。 フォント利用の最終段階として、 ダウンロード可能な形式のフォントを生成します。 ツール pfbtops は (訳注 : .pfb 形式から) .pfa 形式のフォントを生成するために、そして、 download というファイルを編集し、 フォントの内部名を参照するように変更しなくてはなりません。 この内部名は以下で示すように groff フォントファイルから容易に調べることができます。 .pfa フォントファイルを生成する。 &prompt.user; pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa もちろん、.pfa が既に利用可能であれば、 参照できるようにシンボリックリンクを張って下さい。 内部フォント名を得る。 &prompt.user; fgrep internalname SHOWBOAT internalname Showboat 該当フォントをダウンロードしなくてはならないことを groff に通知する。 &prompt.user; ex download :$a Showboat showboat.pfa . :wq フォントを試用する。 &prompt.user; cd /tmp &prompt.user; cat >example.t <<EOF .sp 5 .ps 16 This is an example of the Showboat font: .br .ps 48 .vs (\n(.s+2)p .sp .ft SHOWBOAT ABCDEFGHI .br JKLMNOPQR .br STUVWXYZ .sp .ps 16 .vs (\n(.s+2)p .fp 5 SHOWBOAT .ft R To use it for the first letter of a paragraph, it will look like: .sp 50p \s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the showboat font as its first letter. Additional vertical space must be used to allow room for the larger letter. EOF &prompt.user; groff -Tps example.t >example.ps ghostscript/ghostviewを使って表示する。 &prompt.user; ghostview example.ps 印刷する (訳注 : プリンタ名は適宜変更して下さい)。 &prompt.user; lpr -Ppostscript example.ps 参考文献: /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man、 &man.groff.font.5;、&man.groff.char.7;、&man.pfbtops.1; TrueType フォントを groff 用に groff/PostScript フォーマットに変換する これにはいくつかユーティリティが必要ですが、 ベースシステムの一部としてインストールされてはいないので若干の作業が必要となります。 インストールするものは: ttf2pf TrueType から PostScript への変換ユーティリティです。 これは TrueType フォントからアスキーフォントメトリック (.afm) ファイルへの変換を行います。 現時点では から入手できます。 注意: これらのファイルは PostScript によるプログラムなので、 Shift キーを押しながらリンクをクリックして ディスクにダウンロードしてください。 さもないとあなたのブラウザは ghostview を立ちあげます。 重要なファイルは: GS_TTF.PS PF2AFM.PS ttf2pf.ps 大文字と小文字の混在は、 これらが DOS シェルのことも考慮しているためです。 ttf2pf.ps はそれ以外のファイルを 大文字として扱いますので、 ファイル名の変更はそれに対応させてください (実際には GS_TTF.PS と PFS2AFM.PS は ghostscript の配布物の一部だと思われますが、 個別のユーティリティとして扱った方が便利なのでそうします。 FreeBSD がこれらを含むとは思われません)。 /usr/local/share/groff_font/devps にインストールされているのがいいかもしれません afmtodit はアスキーフォントメトリックファイルから groff とともに使うフォントファイルを作ります。 これは通常、 /usr/src/contrib/groff/afmtodit ディレクトリに存在していて、 使えるようにするには作業が必要です。 もしも /usr/src ツリーで作業をすることを躊躇うなら、 このディレクトリの内容を作業用の場所にコピーすればいいです。 作業エリアで以下のようにしてこのユーティリティします。 # make -f Makefile.sub afmtodit もし、まだ存在していなければ /usr/contrib/groff/devps/generate/textmap を /usr/share/groff_font/devps/generate にコピーします。 これらのユーティリティが所定の場所に収まったら いつでも開始できます。 .afm ファイルを以下のようにして作ります。 % gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name ここで、TTF_name はあなたの TrueType フォントの名前で、PS_font_name は .pfa ファイルのためのファイル名で、 AFM_name は .afm ファイルに望む名前です. .pfa や .afm 用の出力ファイル名を明示しなければ、 デフォルト名は TrueType フォントファイル名から作成されます。 この時、アスキー PostScript フォントメトリックファイルである .pfa ファイルも同時に作られます (.pfb はバイナリ形式です)。 これは不要となるでしょうが、(私が考えるに) フォントサーバには役立つでしょう。 例として、30f9 バーコードフォントをデフォルトのファイル名で変換するには以下のようにします。 % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to 3of9.pfa and 3of9.afm. 変換後のフォントを A.pfa と B.afm にするなら以下のようにします。 % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to A.pfa and B.afm. groff PostScript ファイルを作ります。 以下のコマンドの実行が用意なように /usr/share/groff_font/devps に ディレクトリを変更します。 恐らく root 特権が必要になるでしょう (そこでの作業が気にいらないなら、このディレクトリの DESC、 text.enc、 generate/textmap ファイルが参照されるということに注意してください)。 % afmtodit -d DESC -e text.enc file.afm \ generate/textmap PS_font_name ここで、file.afm は AFM_name で、上で ttf2pf.ps で作ったものです。 PS_font_name はコマンドから使われるフォント名で、 &man.groff.1; がこのフォントを参照するために使うものです。 たとえば、最初の tiff2pf.ps コマンドを上述のように行っていたとすると、 3of9 バーコードフォントは以下のコマンドで作成できます。 % afmtodit -d DESC -e text.enc 3of9.afm \ generate/textmap 3of9 得られる PS_font_name ファイル (この例では 3of9) はディレクトリ /usr/share/groff_font/devps に、コピーするなり移動するなりして置かれることに気をつけてください。 ttf2pf.ps がわりつけるフォント名は TrueType フォントファイル中に見つかったものになります。 それとは異なる名前を使いたかったら、 .afm ファイルを編集してから afmtodit を実行する必要があります。 &man.groff.1; から &man.gs.1; へパイプするつもりならば、 その名前は同時にフォントマップファイルで使われているものである必要があります。 TrueType フォントを他のプログラムで使うことができますか? TrueType フォント形式は Windows、Windows 95、Mac で用いられます。この形式は極めて有名であり、 非常にたくさんのフォントが利用できます。 不幸なことに、(訳注: FreeBSD で) この形式を利用できるアプリケーションは、著者が知る限り、 Ghostscript と povray の 2 つしかありません。 Ghostscript では、ドキュメントによれば、そのサポートは不十分であり、 フォントを利用してもタイプ 1 フォントより粗悪な結果が得られるようです。 povray バージョン 3 もまた TrueType フォントを利用可能ですが、しかし、 たくさんの人々がレイトレーシングされたページが続いているかのように、 ドキュメントを作成しているのではないかと、著者はむしろ疑っています :-) (訳注: povray はレイトレーシング関連のプログラムです。 レイトレーシングは計算に時間がかかることから、 ドキュメントを作るのが遅いんじゃないの、 と著者が遠回しに言っているようです)。 このなんとも悲惨な状況は変わりつつあります。 FreeType プロジェクト では FreeType の便利なツールを開発しています。 XFree86 4.x に含まれている freetype モジュール。 詳細は FreeBSD ハンドブックか XFree86 4.0.2 Fonts ページを見てください。 X11 用の xfsft フォントサーバは 一般のフォントに加えて TrueType フォントを提供します。 現在ベータ版であるにもかかわらずたいへん評判がいいものです。 詳しくは Juliusz Chroboczek's page をごらんください。 FreeBSD への移植についての情報は Stephen Montgomery's software page にあります。 xfstt は X11 用のもうひとつの フォントサーバで、 から入手できます。 ttf2bdf というプログラムは、 X の環境下で TrueType フォントのセットから BDF 形式のファイルを作るものです。 Linux 用のバイナリが から 入手できます。 アジア圏で TrueType フォントを利用したいみなさんには、 XTT フォントサーバは一見の価値があるでしょう。 XTT に関する情報は で得られます。 そしてその他 … FreeType プロジェクトページは、 以上に挙げたものおよびその他のフリーな TrueType プロジェクトに関する情報入手のよい出発点となるでしょう。 どこでフォントを入手できますか? インターネット上でたくさんのフォントを利用することができます。 これらは完全に無料であるか、シェアウェアです。加えて、 たくさんのフォントが収録されたあまり高価ではない CDROM がたくさんあります。インターネットでのアクセスポイント (1996年8月現在)を以下に示します。 (以前は CICA) 未解決問題 .pfm ファイルを利用するものはあるのか? .afm ファイルを .pfa もしくは .pfb から作成できるか? 非標準キャラクタ名がある PostScript フォントを groff キャラクタにマッピングするファイルをどのように作成するか? xditview と devX?? デバイスで新たなファイル全てにアクセスするためのセットアップをすることができるか? povray と Ghostscript で TrueType フォントを利用する例があるといいだろう。
diff --git a/ja_JP.eucJP/articles/ipsec-must/article.sgml b/ja_JP.eucJP/articles/ipsec-must/article.sgml index f7e2537dea..8becfc7034 100644 --- a/ja_JP.eucJP/articles/ipsec-must/article.sgml +++ b/ja_JP.eucJP/articles/ipsec-must/article.sgml @@ -1,353 +1,347 @@ -%man; - - -%ja-trademarks; - - -%trademarks; + +%articles.ent; ]>
FreeBSD の IPsec 機能を独立検証するには David Honig
honig@sprynet.com
 1999 年 5 月 3 日 &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; IPsec をインストールした時、 それがきちんと動作しているかどうか調べるにはどうしたら良いでしょう? ここでは、IPsec の動作を検証する実験的な方法を紹介します。 問題 まず、IPsec がインストールされていることを前提に話を進めます。 IPsec がきちんと動作しているかどうか知るにはどうしたら良いでしょう? もちろん設定が間違っていればネットワーク接続が行なえないでしょうし、 接続できたということは設定が合っているからだ、という認識は間違っていません。 接続状態は &man.netstat.1; コマンドで確かめることができます。 しかし、それを独立して検証することは可能なのでしょうか? 解決方法 最初に、暗号に使われている情報理論について考えます。 暗号化されたデータは、一様に分布している。つまり、 各情報源シンボルは最大のエントロピーを持っている。 通常、未処理のデータや圧縮されていないデータは冗長である。 つまり、各情報源シンボルのエントロピーは最大ではない。 ネットワークインターフェイスを入出力するデータのエントロピーを測定できると仮定すると、 「暗号化されていないデータ」と「暗号化されたデータ」の両者に、 違いを見ることができるはずです。 このことは、パケットのルーティングが行なわれる場合の一番外側の IP ヘッダなど、 データの一部が 暗号化モード で暗号化されなかったとしても成立します。 MUST Ueli Maurer 氏の Universal Statistical Test for Random Bit Generators (MUST) は、サンプルデータのエントロピーを高速に測定します。 これには圧縮と良く似たアルゴリズムが使われています。 文末に示すのは、 一つのファイル中で連続するデータ (最大 0.25 メガバイト) を測定するコードです。 Tcpdump さて次に、上記に加えてネットワーク上の生データを捕捉するための手段も必要になります。 それを実現するプログラムに、&man.tcpdump.1; と呼ばれるものがあります。 ただし、tcpdump を使うには、 カーネルコンフィグレーションファイルにおいて Berkeley Packet Filter インターフェイスが有効化されていなければなりません。 次のコマンド: tcpdump -c 4000 -s 10000 -w dumpfile.bin は、4000 個の生パケットを捕捉し、dumpfile.bin に記録します。 この例のでは 10,000 バイト以下のパケットのみ記録されます。 実験 では、実験してみましょう。 IPsec ホストと IPsec を使っていないホストの両方にネットワーク接続してください。 そして パケットの捕捉 を開始します。 次に、IPsec を使っている 接続で &man.yes.1; という &unix; コマンドを実行します。 これは、y という文字の連続データを出力するものです。 しばらくしたらコマンドを停止させ、IPsec を使っていない接続に対して同じコマンドを実行します。 こちらも、しばらくしたらコマンドを停止させてください。 ここで、MUST を捕捉したパケットに実行すると、次のような出力が得られるはずです。 この中で重要なのは、期待値 (7.18) に対して、 IPsec を使った接続が 93% (6.7)、 通常の接続が 29% (2.1) という結果になっていることです。 &prompt.user; tcpdump -c 4000 -s 10000 -w ipsecdemo.bin &prompt.user; uliscan ipsecdemo.bin Uliscan 21 Dec 98 L=8 256 258560 Measuring file ipsecdemo.bin Init done Expected value for L=8 is 7.1836656 6.9396 -------------------------------------------------------- 6.6177 ----------------------------------------------------- 6.4100 --------------------------------------------------- 2.1101 ----------------- 2.0838 ----------------- 2.0983 ----------------- 注意 この実験は暗号化の理論が示すとおり、IPsec を使った通信では確かにペイロード中のデータに含まれるシンボルの生起確率が一様に分布する、 ということを示しています。 しかし、ここで示した実験ではシステム上の欠陥 (あるのかどうか知りませんが) を検出することはできません。 ここで言う「欠陥」とは、たとえば暗号鍵生成や交換の不備や、 データや暗号鍵が他人に見られていないかどうかといった問題、 あるいはアルゴリズムの強度はどうか、 カーネルのバージョンは合っているかといったことです。 これらはソースを調べれば確かめることができます。 IPsec の定義 インターネットプロトコル セキュリティ拡張 (Internet Protocol security extensions) は IP v4 と IP v6 に適用され、IP v6 への実装は必須となっています。 このプロトコルは IP (ホスト間) レベルで暗号化と認証を実現するためのものです。 たとえば SSL は一つのアプリケーションソケット、SSH はログイン、 PGP は特定のファイルやメッセージのみに対してそれぞれ安全性を提供しますが、 IPsec は 2 ホスト間のすべての通信を暗号化します。 IPsec のインストール FreeBSD の最近のバージョンでは IPsec のサポートが基本のソースコードに含まれています。 それ故、あなたはおそらく オプションをカーネルコンフィグファイルに追加し、 カーネルを再構築/再インストールして &man.setkey.8; コマンドで IPsec 接続を設定すればよいはずです。 FreeBSD で IPsec を実行する包括的なガイドは FreeBSD ハンドブックで提供されています。 src/sys/i386/conf/KERNELNAME ネットワークデータを &man.tcpdump.1; で補足するためにはカーネルコンフィグファイルには以下の行が必要です。 追加後 &man.config.8; を実行しカーネルの再構築/再インストールを 行なってください。 device bpf Maurer's Universal Statistical Test (ブロックサイズ = 8 ビット) 同一のコードを このリンクから入手することができます。 /* ULISCAN.c ---blocksize of 8 1 Oct 98 1 Dec 98 21 Dec 98 uliscan.c derived from ueli8.c This version has // comments removed for Sun cc This implements Ueli M Maurer's "Universal Statistical Test for Random Bit Generators" using L=8 Accepts a filename on the command line; writes its results, with other info, to stdout. Handles input file exhaustion gracefully. Ref: J. Cryptology v 5 no 2, 1992 pp 89-105 also on the web somewhere, which is where I found it. -David Honig honig@sprynet.com Usage: ULISCAN filename outputs to stdout */ #define L 8 #define V (1<<L) #define Q (10*V) #define K (100 *Q) #define MAXSAMP (Q + K) #include <stdio.h> #include <math.h> int main(argc, argv) int argc; char **argv; { FILE *fptr; int i,j; int b, c; int table[V]; double sum = 0.0; int iproduct = 1; int run; extern double log(/* double x */); printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP); if (argc < 2) { printf("Usage: Uliscan filename\n"); exit(-1); } else { printf("Measuring file %s\n", argv[1]); } fptr = fopen(argv[1],"rb"); if (fptr == NULL) { printf("Can't find %s\n", argv[1]); exit(-1); } for (i = 0; i < V; i++) { table[i] = 0; } for (i = 0; i < Q; i++) { b = fgetc(fptr); table[b] = i; } printf("Init done\n"); printf("Expected value for L=8 is 7.1836656\n"); run = 1; while (run) { sum = 0.0; iproduct = 1; if (run) for (i = Q; run && i < Q + K; i++) { j = i; b = fgetc(fptr); if (b < 0) run = 0; if (run) { if (table[b] > j) j += K; sum += log((double)(j-table[b])); table[b] = i; } } if (!run) printf("Premature end of file; read %d blocks.\n", i - Q); sum = (sum/((double)(i - Q))) / log(2.0); printf("%4.4f ", sum); for (i = 0; i < (int)(sum*8.0 + 0.50); i++) printf("-"); printf("\n"); /* refill initial table */ if (0) { for (i = 0; i < Q; i++) { b = fgetc(fptr); if (b < 0) { run = 0; } else { table[b] = i; } } } } }
diff --git a/ja_JP.eucJP/articles/multi-os/article.sgml b/ja_JP.eucJP/articles/multi-os/article.sgml index ca1c5354d2..0bb4e1463f 100644 --- a/ja_JP.eucJP/articles/multi-os/article.sgml +++ b/ja_JP.eucJP/articles/multi-os/article.sgml @@ -1,852 +1,844 @@ -%ja-authors; - -%authors; - - -%ja-trademarks; - - -%trademarks; + +%articles.ent; ]>
FreeBSD と他の OS を共存させるには Jay Richmond
jayrich@sysc.com
1996 年 8 月 6 日 &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.powerquest; &tm-attrib.general; ここでは、FreeBSD を (Linux、&ms-dos;、&os2、&windows; 95 など) 人気のある他の OS とうまく同居させる方法について説明します。 この文章を書くにあたり、 Annelise Anderson andrsn@stanford.edu、 Randall Hopper rhh@ct.picker.com、 &a.jkh; には、特にお世話になりました。 概要 大容量のディスクがないと、大半の人は複数の OS を うまく共存させることはできません。そのため、この文書には大容量 EIDE ドライブに関する記述も含まれています。 複数の OS を同居させる場合、ハードディスクの設定や OS の組合せというのは非常にたくさんありますが、 おそらく が最も役に立つ章でしょう。 その章には、複数の OS を使用するために特に必要な コンピュータ設定についての詳細が書かれています。 この文書では、ハードディスクに OS を追加できるだけの空き容量があることを前提としています。 ハードディスクのパーティションを再度切り直すと、 既存のパーティションにあるデータを壊すことになりかねません。 しかし、ハードディスクが完全に DOS で占められているようであれば、 (FreeBSD CDROM の中の \TOOLS ディレクトリ、 あるいは ftp から取得できる) FIPS ユーティリティが役に立つことでしょう。 このツールを使えば、データを破壊することなくハードディスクの パーティションを切り直すことができます。 また、データを破壊せずにパーティションのサイズを変更したり削除できる &partitionmagic; という商用のプログラムも出回っています。 ブートマネージャの概要 ここでは、おそらくあなたが目にするであろう、 いくつかのブートマネージャについて簡単に説明します。 コンピュータの設定によっては、同じシステム上で 1 つ以上の ブートマネージャを使用した方が便利な場合があります。 Boot Easy これは、FreeBSD で標準に使用されている ブートマネージャです。 大半の OS が起動可能で、 BSD、&os2; (HPFS)、&windows; 95 (FAT および FAT32)、Linux などをサポートします。 ファンクションキーで起動パーティションを選択することができます。 &os2; Boot Manager これは、FAT、FAT32、HPFS、FFS (FreeBSD)、および EXT2 (Linux) の起動に対応しています。 パーティション選択は、カーソルキーで行います。 &os2; Boot Manager は、他のマスターブートレコード (MBR) を 使用するブートマネージャと異なり、 唯一、自分用にひとつパーティションを占有します。 そのため、起動時の問題を避けるために、 第 1024 番目より前のシリンダにインストールしなければいけません。 ブートマネージャが MBR ではなく、起動セクタの一部にある場合は、 LILO を使っている Linux を起動することができます。 &os2; Boot Manager で Linux を起動させる方法の詳細は、 次のサイト Linux HOWTO を参照してください。 OS-BS これは、Boot Easy に類似したもので、 起動のタイムアウト設定や起動のデフォルトパーティションを決めるといった、 起動プロセスの細かい制御が可能です。 このプログラムのベータ版では、 カーソルキーを用いて起動する OS を選択することができます。 これは、FreeBSD CD-ROM の \TOOLS ディレクトリ、 あるいは ftp に収録されています。 LILO - LInux LOader これは、動作が限定されたブートマネージャです。 FreeBSD を起動することはできますが、 LILO の設定ファイルを少々編集する必要があります。 FAT32 について FAT32 は FAT ファイルシステムに代わるものです。 これは Microsoft の OEM SR2 ベータ版 (訳注: &windows; 95 の OEM 版の一つ) に含まれていて、1996 年末へ向けて、&windows; 95 がプリインストールされた コンピュータで広く利用され始めました。 &windows; 95 は従来の FAT ファイルシステムを変換し、 大容量のハードディスクでより小さなサイズのクラスタを利用可能にします。 また、FAT32 は従来の FAT 起動セクタやアロケーションテーブルを 変更するため、いくつかのブートマネージャは利用できなくなっています。 標準的なインストール では、大容量の EIDE ハードディスクが 2 つあり、 FreeBSD、Linux、&windows; 95 を同居させたい、 という場合を考えましょう。 このようなハードディスクを使用した場合の 一例について見てみましょう: /dev/wd0 (1 番目の物理的なハードディスク) /dev/wd1 (2 番目のハードディスク) 両方のディスクとも 1416 シリンダあります。 FDISK.EXE ユーティリティが入っている &ms-dos;、あるいは &windows; 95 boot ディスクから起動させ、 1 番目のディスク上に 50MB のプライマリパーティション (&windows; 95 本体に必要な 35-40MB に、少々余分な空きを加えたもの) を作成します。 また、&windows; アプリケーションとデータ用として、 2番目のハードディスク上に大きめのパーティションを作成します。 再起動し、C: パーティション上に &windows; 95 をインストールします (一言で終わらせられるほど簡単ではありませんが)。 次に Linux をインストールします。 すべての Linux ディストリビューションについて確認したわけではありませんが、 少なくとも Slackware には LILO ( 参照) が含まれています。Linux の fdisk コマンドを使って、ハードディスクを切り分けるとしたら、 わたしの場合は最初のドライブ (ルートパーティションとスワップ を合わせてだいたい 300MBくらい) に Linux の全システムを入れるでしょう。 Linux をインストールしてから LILO をインストールするかどうか聞かれた時、 LILO のインストール先は MBR (マスターブートレコード) ではなく Linux のルートパーティション上になっていることを 必ず確認して下さい。 残りのハードディスクは、すべて FreeBSD にあてます。 この時、FreeBSD のルートスライスが 1024 シリンダを越えないように 気を付けます (ここで想定している 720MB のディスクの場合、 1024 シリンダは 528MB の位置にあります)。 残りのハードディスク (270MB) は、 /usr と / スライスにあてることもできます。 2 番目のディスクの残りは、 /usr/src とスワップ領域に使用します。 この残りの容量は、手順 1) で作成した &windows; アプリケーション / データのパーティションに依存します。 &windows; 95 fdisk ユーティリティで見た場合、 ハードドライブは次のように見えているはずです。 --------------------------------------------------------------------- 領域情報を表示 現在のハードディスク: 1 領域 状態 種類 ボリュームラベル Mバイト システム 使用 C: 1 A PRI DOS 50 FAT** 7% 2 A Non-DOS (Linux) 300 43% ディスクの総容量は 696 Mバイトです。(1 M バイト = 1048576 バイト) 続けるには Esc キーを押してください。 --------------------------------------------------------------------- 領域情報を表示 現在のハードディスク: 2 領域 状態 種類 ボリュームラベル Mバイト システム 使用 D: 1 A PRI DOS 420 FAT** 60% ディスクの総容量は 696 Mバイトです。(1 Mバイト = 1048576 バイト) 続けるには Esc キーを押してください。 --------------------------------------------------------------------- 注) 最新の OEM SR2 をお使いの場合は、 ** の部分が FAT16、FAT32 と表示されることがあります。 詳しくは をご覧下さい。 FreeBSD をインストールします。 最初のハードディスクが BIOS で NORMAL と設定された状態で起動することを確認します。 そうでない場合は、 起動時に適切なディスクジオメトリ情報を入力しなければなりません (ジオメトリ情報を得るには、&windows; 95 を起動して Microsoft Diagnostics (MSD.EXE) で調べるか、 BIOS の機能でチェックして下さい)。 ここでのパラメータ hd0=1416,16,63 は、 1416 はハードディスクのシリンダ数であり、 16 はトラックあたりのヘッド数、 63 はトラックあたりのセクタ数です。 ハードディスクのパーティションを切る時には、 Boot Easy が 1 番目のディスクにインストールされていることを確認します。 2 番目のハードディスクは起動と関係ないので、 こちらについて心配する必要はありません。 再起動すると、Boot Easy が DOS (&windows; 95)、 Linux、BSD (FreeBSD) という、 3 つの起動可能パーティションを認識します。 注意と考察 大部分の OS は、自分がハードディスクのどの領域に、 どのように配置しているか、ということを非常に気にします。 &windows; 95 や DOS は、1 番目のハードディスクの 基本領域にインストールされる必要がありますが、 &os2; は例外的に、ハードディスクの 1 番目 と 2 番目、 基本領域と拡張領域をまったく問わずにインストールすることができます。 よく分からなければ、起動可能なパーティションを 1024 シリンダ内に入れるようにして下さい。 BSD システムが存在しているところに &windows; 95 を載せると、MBR が 破壊 されてしまいます。 そのため、ブートマネージャの再インストールが必要になります。 Boot Easy は、CDROM の \TOOLS ディレクトリあるいは ftp サイトに含まれる BOOTINST.EXE ユーティリティを用いて、 再インストールすることが可能です。 また、インストーラのパーティションエディタを使って Boot Easy を再インストールすることもできます。 そこから、FreeBSD パーティションを bootable としてマークをつけ、 Boot Manager を選択します。 変更した情報を MBR に (W)rite out (= 保存) するため、W を入力します。 そして再起動すると、 Boot Easy が &windows; 95 を DOS として認識するはずです。 &os2; は FAT、HPFS パーティションを認識しますが、 FFS (FreeBSD)、EXT2 (Linux) パーティションを認識しないことを覚えておいて下さい。 同様に、&windows; 95 は、FAT と FAT32 パーティションしか読み書きすることができません ( を参照)。 FreeBSD は、 ほとんどのファイルシステムを読むことができますが、 現時点で HPFS パーティションの読み込みには対応していません。 Linux では、HPFS パーティションを読むことができますが、 書き込みはできません。 最近の Linux カーネル (2.x) のバージョンでは、 &windows; 95 VFAT パーティションに読み書きができます (VFAT は、&windows; 95 で長いファイル名を利用可能にするもので、 ほとんど FAT と一緒です)。 つまり Linux は、ほとんどのファイルシステムに読み書きができるわけです。 わかりました? そう期待して…。 例 (この章はまだまだ手を入れる必要があります。 良い例があったら、 jayrich@sysc.com までメールを送って下さい。) FreeBSD + &windows; 95: &windows; 95 の後に FreeBSD を載せた場合は、 Boot Easy メニューの DOS という部分を確認して下さい。 これが &windows; 95 になります。 もし、FreeBSD の後に &windows; 95 を載せてしまった場合は、 上記の を読んで下さい。 お持ちのハードディスクが 1024 シリンダを越えない場合は、 起動時の問題はありません。 パーティションのうち 1 つでも 1024 を越えたものがあり、 DOS (&windows; 95) で invalid system disk と表示されたり、 FreeBSD で起動できない場合には、BIOS の >1024 cylinder support あるいは NORMAL/LBA モードの設定を確認して下さい。 DOS が正常に起動するには、おそらく LBA (Logical Block Addressing) モードが必要になります。 毎回起動時にBIOS の設定を切替える方法をとりたくない場合には、 CD に収録されている FBSDBOOT.EXE ユーティリティを使い、DOS を経由して FreeBSD を起動させる方法もあります (このプログラムは、 FreeBSD パーティションを見付けて、起動します)。 FreeBSD + &os2; + &windows; 95: 特に注意すべきことはありません。 &os2; のブートマネージャは、これらすべての OS を起動することができますので、問題はないでしょう。 FreeBSD + Linux: 両方の OS を起動するのに、Boot Easy を使うこともできます。 FreeBSD + Linux + &windows; 95: ( を参照) 他の参考となる資料 ハードディスク上に複数の OS を同居させる方法について 取り扱っている Linux HOW-TO は、たくさんあります。 Linux+DOS+Win95+OS2 mini-HOWTO には、 &os2; ブートマネージャの詳細な設定法が書かれています。また、 Linux+FreeBSD mini-HOWTO も同様に参考となるでしょう。 さらに、Linux-HOWTO というサイトもあります。 &windowsnt; Loader Hacking Guide には、 &windowsnt;、&windows; 95、DOS を、他の OS とマルチブートする方法についての情報が書かれています。 Hale Landis の How It Works (動作の仕組み) ドキュメント集には、 あらゆる種類のディスクジオメトリ情報や、起動に関する情報が含まれています。 また、以下のリンク にあるものも参考になるでしょう。 最後に、 配布されているカーネルソース (/usr/src/sys/i386/boot/biosboot/README.386BSD に展開されています) に含まれている、FreeBSD カーネルの文書も見落とさないようにしてください。 技術的な詳細 (Randall Hopper、 rhh@ct.picker.com の寄稿によるものです) この章は、 ハードディスクやハードディスクの起動プロセスに関する基礎知識を提供します。 これは、複数の OS を起動する設定で問題が起こった時、 それを解決するのに役立つでしょう。 最初はごく基本的な用語から始まりますので、 章全体を流し読みして、見慣れない内容が出てくるところから 読み始めても構いません。 ハードディスクの基礎 まず、ハードディスク上のデータの位置を示すのに使われる、 基本となる用語が 3 つあります。それは、シリンダ、ヘッド、セクタです。 これらの用語の関係を知ることが、とりわけ重要と言うわけではありません。 が、これらがディスク上の物理的なデータの位置を示す、 ということは覚えておきましょう。 ハードディスクにはそれぞれ、 固有ののシリンダ数、ヘッド数、シリンダヘッドごとのセクタ数があります (シリンダヘッドはトラックとも呼ばれます)。 この情報は、ハードディスクのディスクジオメトリを定義します。 セクタ数は大抵の場合、1 セクタが 512 バイト、 1 トラックが 63 セクタに対応するようになっていますが、 シリンダとヘッドの数はディスクによってさまざまです。 このように、計算すると、 ディスクに納めることのできるデータのバイト数が分かります: (シリンダ数) × (ヘッド数) × (63 セクタ/トラック) × (512 バイト/セクタ) たとえば Western Digital AC31600 EIDE ハードディスクの場合、次のようになります。 (3148 シリンダ) × (16 ヘッド) × (63 セクタ/トラック) × (512 バイト/セクタ) これを計算すると 1,624,670,208 バイト、 つまり約 1.6 GB になります。 ハードディスクの物理的なディスクジオメトリ情報 (シリンダ数、ヘッド数、トラックあたりのセクタ数) は、 ATAID などのインターネット上にあるプログラムを用いて 調べることができます。おそらくハードディスク自体にも、 こういった情報が付属しているでしょう。 しかし注意して欲しいのですが、BIOS LBA ( 参照) を使用している場合、 物理的なジオメトリ情報を得るためのプログラムはどんなものでも良い、 というわけではありません。 これは、数多くのプログラム (たとえば MSD.EXE や FreeBSD の fdisk) が物理的なディスクジオメトリ情報を認識しないためです。 これらはその代りに、 変換されたジオメトリ (LBA を使った仮想的なセクタ数) を報告します。 この言葉が何を意味しているのかについては、後述します。 これらの用語について役立つこととしては、 与えられた三つの数字—シリンダ数、ヘッダ数、 トラックあたりのセクタ数—は、ハードディスク上の特定のセクタ (データの 512 バイトブロック) を絶対位置で決定します。 シリンダ、ヘッドは 0 から、セクタは 1 から番号付けされます。 さらに詳しい技術情報に興味がある方には、 ディスクジオメトリ、起動セクタ、BIOS などに関する情報は ネット上の至るところで得ることができることをお知らせしておきます。 Lycos、Yahoo などで boot sector (起動セクタ)、 master boot record (マスターブートレコード) などを検索してみてください。 それらの役立つ情報の中でも、 Hale Landis の How It Works (動作の仕組み) ドキュメント集は参考になります。このドキュメント集に関しては の章を参照してください。 もう用語については十分ですね。 次は起動についてお話します。 起動のプロセス ハードディスクの一番先頭のセクタ上 (シリンダ 0、ヘッド 0、セクタ 1) には、 マスターブートレコード (MBR) が存在します。 MBR には、ハードディスクのマップ情報が含まれていて、 最大 4 つの パーティション を認識することができます。それぞれのパーティションは、 ディスク上の連続したデータ領域の塊です。 FreeBSD では、このパーティションを スライス と呼んでいます。これは、FreeBSD 独自のパーティションと混乱しないようにですが、 ここではスライスという言葉は使いません。 各パーティションには、それぞれ別の OS を入れることができます。 MBR の各パーティションエントリには、 パーティション ID、 シリンダ/ヘッド/セクタの開始位置、 シリンダ/ヘッド/セクタの終了位置 があります。パーティション ID は、パーティションの種類 (どの OS を使用しているか) を、 開始位置/終了位置 はパーティションの位置を示します。 に、 良く使われるパーティション ID のリストを示します。 パーティション ID - Partition IDs ID (hex) 説明 01 DOS12 基本領域 (12-bit FAT) 04 DOS16 基本領域 (16-bit FAT) 05 DOS 拡張領域 06 大容量 DOS 基本領域 (> 32MB) 0A &os2; 83 Linux (EXT2FS) A5 FreeBSD、NetBSD、386BSD (UFS)
注: パーティションには、起動ができないものもあります (例えば DOS 拡張領域)。 つまり、できるものもあれば、できないものもあるというわけです。 パーティションが起動可能かどうかは、 各パーティションの先頭に存在する パーティション起動セクタの設定で決まります。 好みのブートマネージャを設定した場合を考えてみます。 ブートマネージャは、接続されているすべてのハードディスクの MBR パーティションテーブルのエントリをリストアップし、 そしてそのリストから、どのエントリを起動するのか 選択できるようにしてくれます。 ブートマネージャは、 起動の際、最初に接続が検出されたハードディスクのマスターブートセクタにある、 特別なプログラムコードによって呼び出されます。 呼び出されたブートマネージャは、選択したパーティションに対応するエントリを MBR パーティションテーブルから調べ、 シリンダ/ヘッド/セクタの開始位置を取得します。 それから、そのジオメトリ情報を使うことでパーティションの起動セクタを読み込み、 制御をそちらに渡します。 読み込まれる起動セクタには、そのパーティション上の OS をロードするために必要な情報が含まれています。 今、かるく触れた内容を理解することは、とても重要です。 ハードディスクには、必ず MBR が存在します。 しかし重要なのは、そのうち BIOS により最初に接続が検出された ハードディスク上にあるものです。 IDE ハードディスクだけを使用しているなら、 最初のIDE ディスクです (例えば、最初のコントローラーのプライマリ側)。 SCSI だけで構成されたシステムの場合も、同じことが言えます。 もし、IDE と SCSI の両方のハードディスクを持っている場合には、 多くの場合、IDE ディスクが先に検出されるため、 1 台目の IDE ディスクが、最初に検出されるハードディスクになります。 先ほど述べたように、インストールするブートマネージャは、 最初に検出されたハードディスク上の MBR に格納されることになります。 起動の制限と注意事項 ここでは、用心しなければならない、興味深い内容についてお話します。 恐怖の 1024 シリンダ制限と BIOS LBA の作用 起動プロセスの最初の部分は、すべて BIOS によって実現されています。 (BIOS とは、コンピュータのためのスタートアップコードを提供する、 システムマザーボードに載っているソフトウェアチップのことです)。 そのため、この最初のプロセスは BIOS インタフェースによって制限を受けます。 このプロセスの間、ハードディスクを読み込むために使用された BIOS インタフェース (INT 13H、Subfunction 2) は、 シリンダ番号へ 10 ビット、ヘッド番号へ 8 ビット、 セクタ番号へ 6 ビット割り当てます。 これがこのインタフェースを使う場合 (例 … ハードディスクの MBR から呼び出されるブートマネージャや、 起動セクタから呼び出される OS ローダーなど) に次のような制限を与えるのです: 最大 1024 シリンダ 最大 256 ヘッド 最大 64 セクタ/トラック (実際には 63 で 0 は利用できません) さて、容量の大きなハードディスクには多くのシリンダがありますが、 ヘッドは多数ありません。 そのため、大容量のハードディスクにおいては、 シリンダ数が 1024 を越えます。 このことや BIOS インタフェースを考慮すると、 ハードディスクのどこからでも起動できるとは限らないのです。 すべての起動可能なパーティションの起動セクタから呼び出されるブートマネージャや OS ローダーは 1024 シリンダより下のシリンダに存在しなければなりません。 実際に、お使いのハードディスクが典型的なものでヘッドが 16 であれば、 次のようになります: 1024 シリンダ/ディスク × 16 ヘッド/ディスク × 63 セクタ/(シリンダ - ヘッド) × 512 バイト/セクタ これが、よく言われる 528MB 制限です。 ここが BIOS LBA (Logical Block Addressing) が入ってくるところです。 BIOS LBA はシリンダを再定義することにより、 BIOS API を呼び出すコードが BIOS インタフェース経由で 1024 シリンダ より上の物理シリンダにアクセスするようにします。 つまり、BIOS を通して見る場合に、実際より少ないシリンダ数、 多いヘッド数として扱われるようにシリンダ数、 ヘッド数を再マップしてくれるのです。 言い替えれば、シリンダ数とヘッド数のバランスを変更することで、 ハードディスクが相対的にヘッドが少なく、 シリンダが多くなるということを利用することにより、 双方の数が上記に述べられている制限 (1024 シリンダ、256 ヘッド) を越えないと言うことになります。 BIOS LBA を用いることで、 ハードディスク容量の制限が仮想的になくなりました (まぁ、8GB まで上がったと言うところでしょうか)。 LBA BIOS を使用している場合は、FreeBSD または 他の OS をどこにでも載せることができ、 1024 のシリンダ制限に引っかかることもありません。 1.6GB Western Digital を再度例として考えてみましょう。 物理的なジオメトリは、次のとおりです: (3148 シリンダ、16 ヘッド、63 セクタ/トラック、512 バイト/セクタ) しかしながら、BIOS LBA は次のように再マッピングを行います: (787 シリンダ、64 ヘッド、63 セクタ/トラック、512 バイト/セクタ) 実際には同じサイズのディスクなのですが、 シリンダとヘッドの計算は BIOS API の範囲内で行われます (偶然にも、私のハードディスクの一つには、 Linux と FreeBSD が物理的なシリンダ 1024 番目より上に載っています。 これらのOS が問題なく起動するのも、BIOS LBA のおかげなのです)。 ブートマネージャとディスクの割り当て ブートマネージャのインストール時、 他に気をつけねばいけないことは、 ブートマネージャ用として領域を割り当てることです。 1 つ、あるいは複数の OS の再インストールを余儀なくされたくないなら、 一番気にしなくてはいけないトピックです。 (MBR のある) マスターブートセクタ、 パーティション起動セクタ、起動プロセス についての の説明を読んだ後は、 自分のハードディスクのどこに、 この気のきくブートマネージャが存在するのか気になるところですね。 それはと言いますと、いくつかのブートマネージャは、 パーティションテーブルの隣の、マスターブートセクタ (シリンダ 0、ヘッド 0、セクタ 1) に納まり切る程に小さいのです。 ブートマネージャによってはもう少し容量が必要なものもあり、 その領域は一般には空いているため、 シリンダ 0 ヘッド 0 セクタ 1 にあるマスターブートセクタを 越えたいくつかのセクタにまで自身を拡張しています。 ありがたいことに (FreeBSD を含む) OS のいくつかは、 必要ならばマスターブートセクタの直後、 シリンダ 0、ヘッド 0、セクタ 2 からパーティションを 起動することができます。 実際に、先頭に空きのある、あるいは全体が空のディスクで FreeBSD の sysinstall を実行すると、デフォルトではその場所から FreeBSD パーティションが始まります (少なくとも私が行った時はそうでした)。 そして、MBR の後にあるいくつかのセクタを消費するような ブートマネージャをインストールする場合、 最初のパーティションのデータの先頭が上書きされます。 FreeBSD の場合は、ディスクラベルが上書きされ、 FreeBSD が起動できなくなります。 このような問題を避ける簡単な方法としては (また、後で異なるブートマネージャを試す柔軟性を持たすためにも)、 パーティションを切る時に、 ハードディスクの最初のトラックを割り当てないまま まるまる残しておくことです。 つまり、シリンダ 0、ヘッド 0、セクタ 2 からシリンダ 0、 ヘッド 0、セクタ 63 までを空けておき、 パーティションをシリンダ 0、ヘッド 1、セクタ 1 から開始するということです。 更に良いことに、ハードディスクの先頭に DOS パーティションを 作成する際、DOS はデフォルトでこの場所を空けておきます (これがブートマネージャのいくつかはその場所が空きだと 仮定するという理由です)。 というわけで、ディスクの先頭に DOS パーティションを作成することで この問題を避けることができるのです。 私はこのやり方が好みで、自分で 1MB の DOS パーティションを先頭に 作成します。そうすると、パーティションを切り直す時、 DOS のドライブ名をずらすことも必要ないのです。 参考として、次のブートマネージャはコードとデータを 記録する際にマスターブートセクタを使用します: OS-BS 1.35 Boot Easy LILO 次のブートマネージャはマスターブートセクタの後にある セクタをいくつか使用します: OS-BS 2.0 Beta 8 (sectors 2-5) &os2; boot manager マシンが起動しない場合はどうするか? ブートマネージャをインストールした際に、 MBR が起動しない状態にしてしまうことがあります。 あまりないことですが、既にインストールしたブートマネージャが ある状態で FDISK してしまうと起こることがあります。 ハードディスクに起動可能な DOS パーティションがある場合、 DOS フロッピーから起動します。次を実行します: A:\> FDISK /MBR オリジナルに戻すには、シンプルな DOS の起動コードを システムに戻します。そうすると、ハードディスクから DOS (DOS に限る) を起動することができます。 もう一つの手としては、起動可能なフロッピーを使って、 ブートマネージャのインストールプログラムを再度実行します。
diff --git a/ja_JP.eucJP/articles/problem-reports/article.sgml b/ja_JP.eucJP/articles/problem-reports/article.sgml index 7e19303706..1c5ee69614 100644 --- a/ja_JP.eucJP/articles/problem-reports/article.sgml +++ b/ja_JP.eucJP/articles/problem-reports/article.sgml @@ -1,610 +1,606 @@ -%man; - -%mailing-lists; - -%ja-authors; + +%articles.ent; ]>
FreeBSD 障害報告の書き方 $FreeBSD$ この記事では、明瞭な障害報告 (Problem Report: PR) を FreeBSD プロジェクトに提出する方法を解説します。 Dag-Erling Smørgrav 寄稿: 障害報告
はじめに ソフトウェアの利用者が持っている 多くのいらただしい経験のうちの一つは、 それはバグじゃない、ひどい障害報告だ などのようなそっけなく理解の役に立たない説明によって、 障害報告があっさり片付けられてしまうことです。 同様に、ソフトウェア開発者が持っている 多くのいらただしい経験のうちの一つは、 実際は障害報告ではない単なるサポート要求や 何が問題でどのように再現するかについての情報が 乏しいまたは欠落している障害報告が殺到することです。 この記事のねらいは、上手な障害報告の書き方について説明することです。 上手な障害報告とはどういうものでしょうか? そうですね、単刀直入に要点を言えば、 上手な障害報告とは、迅速に解析を進め処理を行うことができ、 一度に利用者と開発者がお互いに満足できるものです。 この記事では主として FreeBSD の障害報告に焦点を絞っていますが、 他のソフトウェアプロジェクトでも多くの部分が当てはまるでしょう。 この記事はテーマ別に整理されており、順番に読めるようにはなっていません。 そのため、ステップバイステップのチュートリアルとして利用するよりも、 障害報告を提出する前に全体を通して読むとよいでしょう。
いつ障害報告を提出すればよいのか 問題には多くの種類がありますが、 それらすべてが障害報告に値するというわけではありません。 もちろん、誰しもが完璧ではありませんので、 実際はコマンドの構文を勘違いしていたり、 設定ファイルに書き間違いをしている場合などを プログラムにバグを見つけた! と思い込んでしまうことがあるでしょう (とは言っても、それ自身、文書が適切に記述されていなかったり、 アプリケーションのエラー処理が甘いことを暗示している可能性があります)。 それ以外にも、障害報告を提出することが正しい行動ではなく、 あなたや開発者たちをただ 不満にさせるためだけに作用してしまう場合があります (訳注: はっきりと把握していないことを報告すべきではありません。 要領を得ない障害報告は扱いにくいものです)。 逆に、バグというよりも、 何か別の報告として提出した方が適切な場合があります — たとえば、既存機能の拡張や新しい機能の搭載要求のようなものです。 では、何がバグで何がバグでないのか、 どのようにして決めれば良いでしょうか? 簡単な経験則として、それを質問として (だいたい どうすれば X できますか? や Y はどこで見つけることができますか? のような形式で) 表現できるなら、あなたの問題はバグではありません。 いつも白黒はっきりするわけではありませんが、 この質問規則は問題の非常に多くの部分があてはまります。 もし、このような質問に対する答えを求めているのなら、 &a.questions; にあなたの質問を送ってみることを検討してください。 訳注 &a.questions; へのメールは英語でお願いします。 日本語にでの質問は、&a.jp.users-jp; か FreeBSD-beginners-jp@ux.mycom.co.jp などに送ってください。 バグではないものに関する障害報告を 提出することが適切かもしれない条件は、以下のような時です。 機能拡張の要求。 障害報告を提出する前に、メーリングリストに これらのことを表明することは一般的に良い考えです。 外部で管理されているソフトウェアの更新通知 (主に ports のことです。BIND やさまざまな GNU ユーティリティのような システムの基礎を構成するソフトェアは外部的に管理されていますが、 ここでは除きます)。 もう一つ、もし、バグに遭遇したシステムが実際には最新でない場合、 システムを最新の状態にして、最新のシステムでも問題が再現するか試した後に 障害報告を提出することを真剣に考えるべきだということです。 既に修正されたバグに関する障害報告を受けとること以上に、 開発者を悩ませるものはほとんどありません。 最後に、再現することができないバグは、めったに直すことができません。 もし、バグが一度だけ発生してそれが再現できないもので、 なおかつ他の人のシステムでも起こらないようであれば、 開発者はそれを再現しようとしてもできませんし、 何が悪いのか理解する機会もありません。 これはバグが起こらなかったことを意味するわけではありません。 しかし、このような状況ではあなたの障害報告がバグの修正に つながる見込みは非常に薄く、報告をやめることを検討すべきです。
準備 従うべき良い規則として、 障害報告を提出する前に常に問題の背景を調べることです。 おそらく、あなたの問題は既に報告されています。 また、メーリングリストで議論されていたり、 最近議論されていたことでしょう。 さらに、あなたが動かしているものより、 既に修正された新しいバージョンがあるかもしれません。 したがって、障害報告を提出する前に明白な部分をすべて確認すべきです。 FreeBSD では、以下のような方法があります。 FAQ を調べる。 メーリングリストを利用する。 — メーリングリストを購読していなければ、 FreeBSD のウェブサイトにある アーカイブ検索を使ってください。 もし、メーリングリストで議論がされていなければ、 自分の問題についてのメッセージを送ってみて、 見落とした点を誰かが見つけてくれるかどうか 数日間待ってみると良いでしょう。 ウェブ全体を検索する (任意)。— あなたの問題に関係する話題がないか あなたのお気に入りの検索エンジンを使って探します。 アーカイブされたメーリングリストやニュースグループを 隅々まで検索すれば、知らなかったまたは思いもつかなかった結果を 得ることができるかもしれません。 最後に、FreeBSD 障害報告データベースを調べる。 あなたの問題が新しいものでなかったり不明瞭であれば、 既に報告されている可能性がかなりあります。 次に、障害報告が適切な人物に届くことを確認する必要があります。 まず、問題がサードパーティソフトウェアのバグであれば、 原作者に報告をすべきです。 そうでなければ、FreeBSD プロジェクトに報告してください。 このルールには二つの例外があります。 一つ目は、もしバグが他のプラットフォームで発生しなければ、 FreeBSD に移植されたソフトウェアに原因が存在する場合です。 二つ目は、原作者がバグを既に修正していて そのソフトウェアの新しいバージョンかパッチを公開しているが、 FreeBSD に移植されたソフトウェアがまだ更新されていない場合です。 それから、FreeBSD のバグ追跡システムは 発信者が選択した分類に従って 障害報告を分別しているということに注意してください。 もし間違った分類を選択した場合、あなたが送った障害報告は 誰かが再分類する良い機会がくるまでしばらく見落とされるでしょう。
障害報告の書き方 自分の問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したのですから、 実際に障害報告を執筆する時です。 環境変数 VISUAL (か、もし VISUAL が設定されていなければ EDITOR) が何らかの使える値に設定されているか確認して、 &man.send-pr.1; を実行します。
パッチやファイルを添付する &man.send-pr.1; プログラムは、 障害報告にファイルを添付する機能を備えています。 あなたが望む数だけ、それぞれ一意の名前を持ったファイル (すなわち、パスを除いた適切な名前のファイル) を添付することができます。 コマンドラインオプション で 添付するファイルの名前を指定してください。 &prompt.user; send-pr -a /var/run/dmesg -a /tmp/errors 添付するファイルがバイナリであっても心配しないでください。 メールエージェントが混乱しないように、自動的に符合化が行われます。 パッチは context 形式か unified 形式の差分を &man.diff.1; の か オプションを 使って作成してください。 パッチを添付する場合、 開発者があなたの報告を読んで簡単にパッチを適用できるように、 修正したファイルの正確な CVS のリビジョン番号が特定できるか 確認してください。 一般的に、 障害報告の中に小さなパッチを含める分にはいいのですが、 記載される問題についての修正が大規模な場合や新しいコードの場合は 十分な査読を行なった後にコミットすべきであるため、 パッチを Web や FTP サーバに置き、その URL を障害報告に含めてください。 電子メールに含めたパッチはサイズが大きいと分割される傾向にあり (とりわけ Gnats が処理に関わるときはそうです)、 肝心な部分が変にならないように注意をはらってください。 また、パッチに変更があった場合、 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくとも Web から該当部分のパッチを送信して変更することができます。 また、障害報告かパッチ自体に明確に指定がなければ、 あなたが提出したパッチは修正した元のファイルと同じ条件の ライセンス下にあるものと仮定されることに留意しておくべきです。
テンプレートに記入する テンプレートは特定のフィールドから成り立っており、 あらかじめ書き込まれた部分がいくつかあります。そこには フィールドの目的が何かを説明する解説や そのフィールドに利用可能な値が書かれています。 コメントの部分は、自分で変更・削除しなくても、 自動的に削除されますので心配する必要はありません。 テンプレートの先頭にある SEND-PR: と書かれている行の下が電子メールのヘッダです。 通常、この部分を変更する必要はありませんが、 障害報告を送信する機械やアカウントで メールを出すことはできるが受けとることができない場合、 From: と Reply-To: に 実際のメールアドレスを設定すべきです。 また、自分 (や他の誰か) に障害報告の複製を送りたい場合は、 電子メールアドレスを Cc: ヘッダに追加してください。 次に、一連の一行フィールドが続きます。 訳注 フィールドの意味が分かり易いように フィールド名を訳していますが、 フィールドの値も含めて 実際のフィールド名は英文字である必要があります。 Submitter-Id (提出者-Id): これは変更しないでください。 あなたが FreeBSD-STABLE を動かしている場合でも、既定値である current-users が正しいのです。 Originator (あなたの名前): これは普通、現在ログインしているユーザの GECOS フィールドを使って既に埋められています。 あなたの実際の名前を指定してください。 お好みで、名前の後ろに電子メールアドレスを 山括弧 (< と > のこと) で閉じて付けることができます。 訳注 たとえば、以下のように書くことができます。 From: FreeBSD Taro <FreeBSD-Taro@example.org> Organization (所属組織): あなたが望むのなら好きに使えます。 このフィールドは何らかの深い意味で使われることはありません。 Confidential (機密): これは no で既に埋められています。 機密扱いの FreeBSD 障害報告のようなものはないため、 変更することに意味はありません。— 障害報告データベースは CVSup によって、 世界的に配布されています。 Synopsis (概要): 問題についての簡にして要を得た説明を書き込んでください。 概要は障害報告メールのサブジェクトとして利用されており、 一覧や要旨にも使われています。 概要が不明瞭な障害報告は無視される傾向があります。 障害報告にパッチを添付する場合、概要の先頭に [PATCH] と書いてください。 Severity (重要度): non-critical (重要ではない)、 serious (重要)、 critical (致命的) のどれかです。 重要度を過大に評価しないでください。 あなたの問題が本当に致命的 (たとえば、 root 権限を悪用できたり、 パニックを容易に再現できるなど) でない場合は、 critical に分類するのは控えてください。 障害報告を提出する人達は自分の問題を大げさに評価しがちであり、 そのため開発者はこのフィールドや次のフィールドを無視する傾向があります。 Priority (優先順位): low (低い)、 medium (中間)、 high (高い) のどれかです。 分類の基準は前述されてますので読んでください。 Category (分類): 以下から一つを選んでください: advocacy: FreeBSD の一般像に関する問題。めったに使われません。 alpha: Alpha プラットフォーム固有の問題。 bin: 基本システムに含まれるユーザランドプログラムに関する問題。 conf: 設定ファイルや、既定値などに関する問題。 docs: マニュアルページ、オンライン文書に関する問題。 gnu: &man.gcc.1; や &man.grep.1; などの GNU ソフトウェアに関する問題。 i386: i386 プラットフォーム固有の問題。 ia64: ia64 プラットフォーム固有の問題。 java: Java™ に関する問題。 kern: カーネルに関する問題。 misc: これらの分類に適合しないその他の分類。 ports: ports ツリーに関する問題。 powerpc: PowerPC プラットフォーム固有の問題。 sparc64: SPARC プラットフォーム固有の問題。 standards: 標準規格への適合問題。 www: FreeBSD ウェブサイトへの変更と改善。 Class: 以下から一つを選んでください。 sw-bug: ソフトウェアのバグ。 doc-bug: 文書中の間違い。 change-request: 機能の追加や、既存の機能の変更についての要望。 update: ports やその他の寄贈ソフトウェアに対する更新。 maintainer-update: 保守者の ports に対する更新。 Release: あなたが動作させている FreeBSD のバージョン。 これは &man.send-pr.1; によって自動的に書き込まれますが、 もし、あなたが障害が起きているものと違うシステムから障害報告を 送信する場合に限り変更する必要があります。 最後に、一連の複数行フィールドがあります。 Environment (環境): 問題が発生した環境を可能な限り正確に記述すべきです。 ここには、オペレーティングシステムのバージョン、 特定のプログラムのバージョンまたは問題があるファイル、 そしてシステムの設定などのような関係する項目、 問題に影響を及ぼすインストールしたその他の ソフトウェアなどが含まれます。— その問題が生じる環境を再構築するために、 開発者はなんでも知る必要があります。 Description: あなたが経験した問題の完全で正確な説明。 開発者が誤解してしまうかもしれないので、 問題の原因について正しく追跡ができたと確信していない限り 推測は避けるようにしてください。 How-To-Repeat: 問題を再現させるために取る必要のある行動の概要。 Fix: できればパッチか、少なくとも回避方法を記述する (同じ問題を回避する方法として他の人達の助けになるだけではなく、 開発者が問題の原因を理解する役に立つかもしれません) べきですが、 はっきりとしたアイデアがなければ開発者が思索をめぐらすために、 このフィールドは空にしておけば良いでしょう。
障害報告を送信する テンプレートを書き終えて、 保存してエディタを終了すると、&man.send-pr.1; は s)end, e)dit or a)bort? のような 表示を出して指示を求めます。 s を押せば障害報告の提出に進めますし、 e だとエディタが再び実行されてさらに編集できます。 a なら作業を中止できます。 abort を選択した場合、いままで書いていた障害報告はディスクに残りますので (&man.send-pr.1; は終了前にそのファイル名を示します)、 暇な時にそれを編集したり、場合によっては よりネットワーク接続性のよいシステムに持っていくことができるでしょう。 この作業ファイルは、&man.send-pr.1; の オプションを使って送ることができます。 &prompt.user; send-pr -f ~/my-problem-report 上記の操作では、指定されたファイルを読み込み、 書式が正しいか検証し、ファイル中のコメント部分を取り除いて、 障害報告が送信されます。
フォローアップ 障害報告を提出すると、 障害報告に割り当てられた追跡用の番号と 状況を確認するために利用する URL を含む、 確認のための電子メールが送られてくるでしょう。 ちょっぴり運がよければ、誰かがあなたの問題に興味を持って それについて取り組もうとするでしょうし、 場合によってはなぜそれが問題でないか説明してくれるでしょう。 状況に何かの変更があると、 誰かがあなたの障害報告を審査追跡状態にして、 何らかのコメントかパッチの通知を自動的に受けとるでしょう。 誰かがあなたにさらなる情報を求めたり、 最初の報告の中で言及しなかったものを思い出したり発見したら、 バグ追跡システムがどの障害報告に結びつければよいか知るために、 件名に追跡用の数字が含まれているかを確かめて bug-followup@FreeBSD.org にメールを送ってください。 問題がなくなったのに障害報告の処理が完了していなければ、 できれば、どのように、いつ、問題を解決できたかの説明を添えて、 この障害報告は議論を終了することができます、と (前述の方法で) フォローアップを送ってください。
さらなる読みもの 適切な障害報告の書き方と手順について関連する資料を示しますが、 決して完全なものではありません。 効果的にバグを報告するには ( 日本語訳) — Simon G. Tatham 氏による、(FreeBSDに限らない) 役に立つ障害報告の作成についてのすぐれたエッセイ。 障害報告 取り扱いガイドライン — 障害報告が FreeBSD の開発者によってどのように 扱われるかについて有益な見識をまとめた記事。
diff --git a/ja_JP.eucJP/articles/zip-drive/article.sgml b/ja_JP.eucJP/articles/zip-drive/article.sgml index 2e78fe6aed..71a6ca035d 100644 --- a/ja_JP.eucJP/articles/zip-drive/article.sgml +++ b/ja_JP.eucJP/articles/zip-drive/article.sgml @@ -1,342 +1,336 @@ -%man; - -%freebsd; - -%ja-trademarks; - -%trademarks; + +%articles.ent; ]>
&iomegazip; ドライブ Jason Bacon
acadix@execpc.com
 &tm-attrib.freebsd; &tm-attrib.adaptec; &tm-attrib.iomega; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.general; &iomegazip; ドライブの基礎 &iomegazip; ディスクは、アイオメガ社から発売されている ZIP ディスクドライブで読み書き可能な大容量のリムーバブル磁気ディスクです。 ZIP ディスクはフロッピーディスクと似ていますが、 ZIP ディスクの方が非常に高速で比較にならないほど大容量です。 というのはフロッピーディスクの容量が大抵 1.44M バイトであるのに対し、ZIP ディスクの容量は、100M バイトか 250M バイトの二種類あります。 120M バイトの容量を持ち、 従来の 1.44M バイトのディスクも使用できる SuperDisk というフロッピーがありますが、ZIP ディスクとは混同しないでください。 アイオメガ社は、&jaz;/JAZZ ドライブというさらに大容量で優れた性能を持ったディスクドライブも発売しています。 JAZZ ドライブの容量は 1G バイトか 2G バイトの二種類です。 ZIP ドライブには、以下の 3 種類のインタフェースが用意されており、 内蔵も外付けも可能です。 SCSI (Small Computer Standard Interface) は最も高速・精巧で拡張性も高く、 そして最も高価なインタフェースです。 SCSI インタフェースは、 ディスクドライブ、テープドライブ、 スキャナーなどといったすべてのタイプの周辺機器と接続するために、 PC から RISC ワークステーション、 ミニコンに至るまで、ほとんどのコンピュータで使用されてきました。 SCSI 対応 ZIP ドライブは、 内蔵も (もし SCSI ホストアダプタに外付けコネクタがあれば) 外付けも可能です。 SCSI で接続された外付けの装置を使用する際、 動作中に SCSI バスからケーブルを抜き差ししないでください。 さもないと、挿入されていたディスクのファイルシステムを損傷 する恐れがあります。 最高のパフォーマンスとセットアップの手軽さを望むなら、 SCSI はベストチョイスです。 一部のハイエンドサーバを除き、多くの PC はビルトインの SCSI をサポートしていないため、 SCSI ホストアダプタを追加で購入する必要があります。 種類にもよりますが、SCSI ホストアダプタは 7 台か 15 台の SCSI デバイスを接続することができます。 それぞれの SCSI デバイスはそれ自身のコントローラを持っており、 そしてそれらは非常に賢く、よく標準化されているので (SCSI の 2 番目の "S" は "標準" を表します)、 OS は SCSI のディスクドライブをすべて同じように扱うことができ、 またそれは SCSI のテープドライブなども同様です。 SCSI デバイスを使用するためには、ホストアダプタ用のドライバと SCSI ディスクドライブ用ドライバ、 SCSI テープドライブ用ドライバといった装置に対応する標準のドライバを用意するだけで良いのです。 さらに機種に特化したドライバ (たとえば DAT ドライブなど) も存在しますが、 大抵標準のドライバを使用しても動作します。 そういった特別なドライバは、 機種特有の機能を利用するために書かれたものです。 ZIP ドライブを使用するためには、 単に /dev の中から ZIP ドライブのデバイスファイルを見つけるだけで良いのです。 ZIP ドライブのデバイスファイルは起動時に表示されるブートメッセージか、 /var/log/messages の中から da1: <IOMEGA ZIP 100 D.13> Removable Direct Access SCSI-2 Device というメッセージを見つけることで特定できます。 上の例の場合、 ZIP ドライブのデバイスファイルは /dev/da1 であるということを表しています。 IDE (Integrated Drive Electronics) インタフェースは、 多くのデスクトップ PC で使用されている低価格なインタフェースです。 ほとんどの IDE デバイスは必ず内蔵になっています。 IDE 接続の ZIP ドライブの性能は SCSI 接続の ZIP ドライブに匹敵します。 (IDE インタフェースは SCSI より高速ではないのですが、 ZIP ドライブの性能は、接続されているバスインタフェースよりも むしろ ZIP ドライブそのものの性能に大きく依存するためです)。 IDE インタフェースの欠点は、 その規格が定めた制限事項そのものです。 ほとんどの IDE アダプタは 2 つのデバイスしかサポートしておらず、 大抵長い期間を経て設計されたものではありません。 たとえば元来の IDE インタフェースは、 多くの人々にアップグレードを強いた 1024 シリンダ以上のハードディスクをサポートしていません。 もし ZIP ドライブの他のディスクドライブやテープドライブ、 スキャナーなどといった装置を PC に追加することを計画しているなら、 将来起こるであろう問題を回避するためにも、 SCSI ホストアダプタと SCSI 接続用 ZIP ドライブに投資した方がよいかも知れません。 FreeBSDにおいて、IDEデバイスの先頭文字は a です。 たとえば、IDEのハードディスクドライブは /dev/ad0 で、IDE (ATAPI) のCD-ROMドライブは /dev/acd1 といった具合です。 パラレルポートインタフェースは、 実際に多くのコンピューターが標準パラレルポートを備えているため (普段はプリンタ接続に使われます) ZIP ドライブやスキャナといった、 ポータブルな外付けデバイスの接続においてポピュラーなインタフェイスです。 そのため ZIP ドライブを持ち運んで、 簡単にコンピュータ間のファイルのやりとりすることができます。 一般に、パラレルポート接続の ZIP ドライブはパラレルポートの速度によって転送速度が制限されるため、 SCSI や IDE で接続された場合より低速です。 パラレルポートの速度はコンピュータによって非常にまちまちで、 また BIOS から設定することもできます。 また双方向通信を使用可能にするために BIOS の設定が必要となるマシンもあります (パラレルポートは元来、 プリンタへの出力のみを目的に設計されたものです)。 パラレルポートに接続する: <devicename>vpo</devicename> ドライバ ZIP ドライブをパラレルポートに接続して使用するには、 カーネルに vpo ドライバが設定されている必要があります。 パラレルポート接続の ZIP ドライブはビルトインの SCSI コントローラを持っており、 vpoドライバを使用するとパラレルポートを通じて ZIP ドライブの SCSI コントローラを読み込むことができます。 vpo は標準のカーネルオプションではないため (FreeBSD 3.2 現在) デバイスを使用可能にするためにカーネルを再構築する必要があります。 カーネル再構築の詳細な手順については他のセクションで説明します。 以下は、vpo ドライバを使用可能にするための大まかな手順です。 まず、/stand/sysinstall を実行し、システムにカーネルのソースコードをインストールしてください。 次に、 vpo ドライバを含むカーネルコンフィグファイルを作ります: &prompt.root; cd /sys/i386/conf &prompt.root; cp GENERIC MYKERNEL この MYKERNEL を編集し、 ident の行を MYKERNEL に変更します。 そして vpo ドライバについて書かれた行のコメントを解除してください。 もしパラレルポートが二つある場合、それに用いる ppc1 デバイスファイルを作るために ppc0 をコピーする必要がある場合があります。 二つ目のパラレルポートは普通 IRQ5 と I/O ポートアドレス 378 番を使用します。 カーネルコンフィグファイルに記述する必要があるのは IRQ だけです。 もしルートのハードディスクドライブが SCSI 接続であった場合、起動ディスクの読み込み順序に誤りが生じ、 システムが ZIP ドライブから起動しようとしてしまう場合があります。 こうなったら、あなたが ZIP ディスクに FreeBSD のルートファイルシステムでも書き込まない限り、 起動には失敗するでしょう! そうした場合は、ルートのディスクを「つなぎかえ (wire down)」、 すなわち、カーネルに特定のデバイスを SCSI ハードディスク /dev/da0 に強制的にバインドさせる必要があります。 そうすれば、ZIP ディスクドライブは二番目の SCSI デバイス、つまり /dev/da1 としてきちんと認識されます。 SCSI ハードディスクを da0 に「つなぎかえ」するには、 device da0 の行を disk da0 at scbus0 target 0 unit 0 に変更してください。 その際、ハードディスクの SCSI ID に合うように 上記の行を変更する必要があるかも知れません。 たとえば、&adaptec; 15xx コントローラの載った SCSI ホストアダプタをお持ちなら、下のように scbus0 を SCSI コントローラにつなぎかえてください。 controller scbus0 を controller scbus0 at aha0 に変更します。 最後に、カーネルコンフィグファイルを作成したら、 不要なドライバをすべて削除することができます。 その際には細心の注意を払う必要がありますが、 あとはコンフィグファイルの更新が成功することを信用するしかありません。 不要なドライバを削除することでカーネルのサイズを小さくすることができ、 アプリケーションに割り当てられるメモリの領域を拡大することができます。 不要なドライバを特定するために、 /var/log/messages の最後の方の行で「not found」と書かれている部分を見つけ、 それらのデバイスをコメントアウトします。 カーネルのサイズを縮小し、 読み込みを早くするために他のオプションを削ることも考えられます。 カーネル再構築の際に表示されるメッセージから、 不要なオプションに関してのさらに詳しい情報が得られます。 ではカーネルを完成させましょう。 &prompt.root; /usr/sbin/config MYKERNEL &prompt.root; cd ../../compile/MYKERNEL &prompt.root; make clean depend && make all install カーネルが再構築されたら、再起動します。 起動が開始する前に、ZIP ドライブがパラレルポートに接続されているかどうか確認してください。 ブートメッセージの中で ZIP ドライブが vpo0 や vpo1 (これらは接続されているパラレルポートに依存する) として認識されているか確認してください。 これが ZIP ドライブのデバイスファイルです。 ここで表示される ZIP のデバイスファイルは、 もしシステムに他の SCSI ディスクがない場合は /dev/da0 となり、 SCSI ハードディスクドライブがルートデバイスとしてつなぎかえられているならば /dev/da1 となります。 ZIP ディスクをマウントする ZIP ディスクにアクセスするには、 他の種類のディスクと同じようにマウントするだけです。 デバイス上のファイルシステムがスライス 4 となっていて、 SCSI もしくはパラレル接続の ZIP ディスクなら、 &prompt.root; mount_msdos /dev/da1s4 /mnt IDE 接続の ZIP ドライブなら、 &prompt.root; mount_msdos /dev/ad1s4 /mnt /etc/fstab を更新すれば、 マウントはさらに簡単になります。 自分のシステムに合うように編集して、以下のような行を加えましょう。 /dev/da1s4 /zip msdos rw,noauto 0 0 そしてディレクトリ /zip を作成します。 マウントするには、 &prompt.root; mount /zip マウントを解除するには、 &prompt.root; umount /zip /etc/fstab のフォーマットに関する詳細は、&man.fstab.5; を参照してください。 また、ZIP ディスク上に FreeBSD のファイルシステムを作成するには &man.newfs.8; を参照してください。 ただし、このディスクは FreeBSD か、FreeBSD を認識するごく少数の &unix; クローンのみにおいて使用することができます (DOS や &windows; 上では使用できません)。
diff --git a/ja_JP.eucJP/books/design-44bsd/book.sgml b/ja_JP.eucJP/books/design-44bsd/book.sgml index 005bf1554f..cee06f2c25 100644 --- a/ja_JP.eucJP/books/design-44bsd/book.sgml +++ b/ja_JP.eucJP/books/design-44bsd/book.sgml @@ -1,2631 +1,2631 @@ -%man; + +%books.ent; ]> 4.4BSD オペレーティングシステムの設計と実装 Marshall Kirk McKusick Keith Bostic Michael J. Karels John S. Quarterman 1996 Addison-Wesley Longman, Inc この文書は出版元の許可の下に The Design and Implementation of the 4.4BSD Operating System の第二章を抜粋したものです。 この抜粋の複製や再配布を出版元の明示的な許可なく行なうことは禁止されています。 この章で紹介されている各概念については 本の残りの部分に非常に詳細に書かれており、 BSD UNIX に興味を持つ読者にとって優れた参考文献の一つとなっています。 この本に関する詳細は出版元から提供されています。 そこで登録することで 関連書籍 のニュースを受け取ることも可能です。 また、Kirk McKusick 氏より BSD courses に関する情報も提供されています。 この文書の日本語化は FreeBSD 日本語ドキュメンテーションプロジェクトによって行なわれました。 日本語化の詳細はを参照してください。 The second chapter of the book, The Design and Implementation of the 4.4BSD Operating System is excerpted here with the permission of the publisher. No part of it may be further reproduced or distributed without the publisher's express written permission. The rest of the book explores the concepts introduced in this chapter in incredible detail and is an excellent reference for anyone with an interest in BSD UNIX. More information about this book is available from the publisher, with whom you can also sign up to receive news of related titles. Information about BSD courses is available from Kirk McKusick. 4.4BSD の設計の概要 4.4BSD の機能とカーネル 4.4BSD カーネルは 4 つの基本機能を提供します。 それはプロセス、ファイルシステム、コミュニケーション、そしてシステムの起動です。 この節ではその 4 つの基本サービスのそれぞれについて この本で書かれていることを紹介します。 プロセスはアドレス空間上でのコントロールの流れを構成します。 生成や終了やその他のプロセスをコントロールするための仕組みは 4 章に述べます。システムは各プロセスの個別の仮想アドレス空間を 多重化します。このメモリ管理については 5 章で議論します。 ファイルシステムとデバイスへのユーザインタフェースは似ているため、 6 章ではそれらに共通する特徴について議論します。 7 章で説明するファイルシステムは、 ディレクトリが木構造になった階層で組織された名前付きのファイルと、 それらを扱うための操作からなります。 ファイルはディスクのような物理的なメディア上に存在します。 4.4BSD はディスク上のデータ配置法をいくつかサポートしており、 それは 8 章の中で述べます。 遠隔マシン上のファイルへのアクセスについては 9 章、 システムにアクセスするために使われている端末とその動作については 10 章で扱います。 UNIX で古くから提供されている通信機構には、 関連するプロセス間における単純で信頼性の高いバイトストリーム (11.1 節パイプを参照)および、 例外イベントの通知 (4.7 節シグナルを参照)があります。 また、4.4BSD は汎用のプロセス間通信機構も備えています。 11 章に述べるこの通信機構は、 ファイルシステムのものとは異なるアクセス機構を使用していますが、 一度接続が確立されれば、 プロセスからはパイプと同じようにアクセスすることができます。 12 章では汎用のネットワーク通信フレームワークについて扱っています。 これは通常、IPC 機構の下位レイヤとして使われているものです。 13 章では、ある特定のネットワークの実装について詳細に述べます。 いかなる実際のオペレーティングシステムにも、 どのように起動するかというような運用上の話題があります。 14 章では起動時や運用上の話題について述べます。 2.3 節から 2.14 節は 3 章から 14 章の内容を紹介するものです。 わたしたちは用語を定義し、基本的なシステムコールについて扱い、 開発の歴史について解説していきます。 そして最後に、中心となっている数多くの設計が、 どうやって選ばれたのかという理由を示します。 カーネル カーネル はプロテクトモードで動作し、 すべてのユーザプログラムが基本的なハードウェア (たとえば CPU、ディスク、端末、ネットワーク接続機器) および ソフトウェアを構成するもの (たとえばファイルシステム、 ネットワークプロトコル) へのアクセスを解決します。 カーネルは基礎的なシステムの機能を提供します。 それはプロセスを生成して管理を行い、ファイルシステムへのアクセス機能や コミュニケーション機能を提供します。 システムコール と呼ばれるこれらの機能は ライブラリのサブルーチンとしてユーザプロセスに現れます。 これらのシステムコールはプロセスがこれらの機能に対して持っている 唯一のインタフェースです。 システムコール機構の詳細は、 システムコールを実行することで実現されているもの以外の、 いくつかのカーネル内機構を説明した 3 章で扱います。 従来のオペレーティングシステムの用語における カーネル とは、 オペレーティングシステムにサービスを追加する実装を行うために必要な 最小限の仕組みだけを提供する、 ソフトウェアの小さな核となる部分のことです。 同時代のオペレーティングシステムの研究、たとえば Chorus , Mach , Tunis , V Kernel では、 このカーネルという機能による区分が、さらに論理的に複数に分けられています。 ファイルシステムやネットワークプロトコルといったサービスは、 その核もしくはカーネルに対するクライアントアプリケーションプロセスとして 実装されています。 4.4BSD カーネルは複数のプロセスには分割されていません。 この基本設計の決定は UNIX の最初のバージョンで行われました。 Ken Thompson によって行われた初めの 2 つの実装では メモリマッピングがなく、 ユーザおよびカーネル空間はハードウェアによる分離が行なわれていませんでした 。 メッセージ伝達システムは、 実際に実装されたカーネルとユーザプロセスのモデルと 同じくらい容易に実装することが可能でした。 単純化と性能のためにモノリシックカーネルが選ばれました。 また、初期のカーネルは非常に小さいものでしたが、 ネットワークのような機能が追加されることで 次第に大きくなっていきました。 現在のオペレーティングシステムの研究の最先端では そのようなサービスをユーザ空間に置くことで カーネルの大きさを減らそうとする傾向にあります。 ユーザは通常、 シェルと呼ばれる コマンド言語インタプリタや、 追加されたユーザアプリケーションプログラムを通してシステムと対話します。 そのようなプログラムやシェルは、プロセスを使って実装されています。 それらのプログラムの詳細についてはこの本の範囲を超えますので、 ここではカーネルについてのみ、考えることにします。 2.3 節、2.4 節では 4.4BSD カーネルによって提供されるサービスや最近の設計の概要について扱います。 そして後の章では、 4.4BSD に現れるそれらのサービスの設計と実装の詳細を説明します。 カーネルの構成 この節では、2 つの側面から 4.4BSD カーネルの構成を見ていきます。 ソフトウェアの静的側面、つまりカーネルを構築するためのモジュール によって提供された機能性による分類 その動的な機能、つまりユーザに提供されるサービスによる分類 カーネルの大部分は、システムコールを通してアプリケーションが アクセスするためのシステムサービスを実装しています。 4.4BSD では、このソフトウェアは次のような構成になっています。 基礎的なカーネル機能: タイマーおよびシステム時計の取り扱い、 記述子管理、そしてプロセス管理 メモリ管理のサポート: ページングとスワッピング 汎用のシステムインタフェース: I/O、コントロール、 記述子によって実現される多重化操作 ファイルシステム: ファイル、ディレクトリ、パス名の解釈、ファイルロック、 I/O バッファ管理 端末の取り扱いのサポート: 端末のインタフェースドライバと ラインディシプリン プロセス間通信機能: ソケット ネットワーク通信への対応: 経路制御等の通信プロトコル、一般的なネットワーク機能 4.4BSD カーネルにおける機種非依存なソフトウェア 分類 コード行数 カーネル内での割合 機種非依存部分の総計 162,617 80.4 ヘッダ 9,393 4.6 初期化部分 1,107 0.6 カーネルの機能 8,793 4.4 汎用のインタフェース 4,782 2.4 プロセス間通信 4,540 2.2 端末の取り扱い 3,911 1.9 仮想メモリ 11,813 5.8 vnode 管理 7,954 3.9 ファイルシステムネーミング 6,550 3.2 FFS 4,365 2.2 ログ構造化ファイルシステム 4,337 2.1 メモリベースのファイルシステム 645 0.3 cd9660 ファイルシステム 4,177 2.1 その他のファイルシステム (10) 12,695 6.3 ネットワークファイルシステム 17,199 8.5 ネットワーク通信 8,630 4.3 インターネットプロトコル 11,984 5.9 ISO プロトコル 23,924 11.8 X.25 プロトコル 10,626 5.3 XNS プロトコル 5,192 2.6
これらのカテゴリのソフトウェアのほとんどは機種非依存であり、しかも 異なるハードウェアアーキテクチャに移植できるものです。 カーネルの機種依存部分は本流のコードから分離されています。 特に、機種依存しているコードのどれを取っても、 特定のアーキテクチャのためのコードを含んでいません。 機種に依存する機能が必要なときには、機種に依存しないコードは 機種依存のコード内にあるアーキテクチャ依存の関数を呼び出します。 機種依存であるソフトウェアは次のものを含んでいます。 低レベルなシステム起動のための動作 トラップおよびフォールトの扱い プロセスの動作状態に関する低レベルな操作 ハードウェアデバイスの設定と初期化 I/O デバイスのランタイムサポート 4.4BSD カーネル内にある HP300 用の機種依存部分 分類 コード行数 カーネル内での割合 機種依存部分の総計 39,634 19.6 機種依存部分のヘッダ 1,562 0.8 デバイスドライバのヘッダ 3,495 1.7 デバイスドライバのソースコード 17,506 8.7 仮想メモリ 3,087 1.5 他の機種依存部分 6,287 3.1 アセンブリ言語で書かれたルーチン 3,014 1.5 HP/UX 互換機能 4,683 2.3
は HP300 用 4.4BSD カーネルを構成するソフトウェアのうち、 機種非依存の部分をまとめたものです。 2 列目の数値は C 言語のソースコード、ヘッダファイル、そして アセンブリ言語のものを表しており、 アセンブリ言語のものは 2% 以下しかありません。 また、 の統計が示しているように、 機種依存のソフトウェアは、HP/UX やデバイスサポートを除いて、 カーネルのうちわずかに 6.9% しかありません。 カーネルのごく小さな部分だけがシステムの初期化に専念します。 このコードはシステムが 起動する ときに用いられ、 カーネルがハードウェアやソフトウェアの環境構築をするための基本部分と なります (14 章参照)。 (制限された物理メモリを持つものには特に) オペレーティングシステムの中には これらの機能が実行された後にそのソフトウェアを廃棄してしまうか、 上から覆ってしまう ものもあります。 4.4BSD カーネルは、起動するために要したコードのためのメモリを再利用しません。 それは通常の機種ではカーネルのリソースのうち 0.5% に過ぎないからです。 そして、起動のためのコードはカーネルの中の一部分に固まってはいません。 それは全体にわたって散在しており、初期化されたときに論理的に関連していた 場所に存在します。 カーネル サービス カーネルレベルコードとユーザレベルコードの間の境界は、 基盤となるハードウェアで提供されるハードウェアレベルの保護機能によって 分離されています。 カーネルは、ユーザプロセスにとってアクセスしにくい切り離された アドレス空間で作動します。特権のある操作 -- たとえば I/O の開始や中央処理装置 (CPU) の停止 -- は、カーネルだけが利用可能です。 アプリケーションはシステムコールを用いてカーネルに サービスを要求します。システムコールは二次記憶装置にデータを 書き込むような複雑な作業や、現在の日時を返すような単純な作業を カーネルに実行させるために使用されます。 アプリケーションからは、 すべてのシステムコールが同期的に実行するように見えます。 つまりアプリケーションは、カーネルがシステムコールに関連した 動作をしているときには停止しています。 カーネルはシステムコール操作の一部を、 システムコールが戻った後に完了することもあります。 たとえば write システムコールは、 プロセスが待っている間に書き込むデータをユーザプロセスからカーネルバッファにコピーしますが、 通常、そのカーネルバッファがディスクに書き込まれる前にシステムコールから戻ります。 通常、システムコールは CPU の実行モードおよび現在のアドレス空間マッピングを変更する ハードウェアトラップとして実装されています。 ユーザによって与えられたシステムコール中のパラメータは、 使用される前にカーネルによって検証されます。 そのようなチェックはシステムの完全性を保証します。 カーネルへ渡されたパラメータはすべてカーネルのアドレス空間にコピーされます。 これは、システムコールの副作用により検証されたパラメータが 変更されないことを保証するためです。 システムコールの戻り値は、カーネルによってハードウェアレジスタ中に返されるか、 あるいはユーザが指定したメモリアドレスにコピーされる値で返されます。 カーネルへ渡されたパラメータのように 結果を戻すためにアプリケーションによって指定されたアドレスは、 それらが確実にアプリケーションのアドレス空間の一部である、 ということが検証されなければなりません。 システムコールを処理する間にカーネルがエラーに遭遇した場合、カーネルは ユーザにエラーコードを返します。 C プログラミング言語においては、このエラーコードが大域変数 errnoに格納されます。また、システムコールを 実行した関数は -1 の値を返します。 ユーザアプリケーションとカーネルは、互いに独立して動作します。 4.4BSD は I/O コントロールブロックや、 オペレーティングシステムに関連するその他のデータ構造体を アプリケーションのアドレス空間に格納しません。 ユーザレベルのアプリケーションはそれぞれ、 実行のための独立したアドレス空間を提供されます。 カーネルは、たとえば別のプロセスが走っている間そのプロセスを停止させ、 関係するプロセスに見えないようにするというような、 状態変更のほとんどを実現しています。 プロセス管理 4.4BSD はマルチタスク環境をサポートしています。 実行されたそれぞれのタスクまたはスレッドは プロセスと呼ばれています。 4.4BSD のプロセスのコンテキストは、 アドレス空間の内容とランタイム環境を含むユーザレベルの状態と、 スケジューリングのパラメータやリソース制御、識別情報を含む カーネルレベルの状態から構成されています。 コンテキストにはカーネルがプロセスにサービスを 提供する際に使用するすべてが含まれています。 ユーザはプロセスを生成し、その実行を制御し、 プロセスの実行状態が変化したときに通知を受け取ることができます。 すべてのプロセスにはプロセス ID (PID) と呼ばれる一意の値が割り当てられます。 この値はカーネルがユーザに実行状態の変化を報告するときにプロセスの身元を確認したり、 ユーザがシステムコールを実行するために参照する際に使用されます。 カーネルは他のプロセスのコンテキストを複製してプロセスを生成します。 新しく生成されたプロセスを 元の親プロセスの 子プロセスと呼びます。 プロセス生成時に複製されたコンテキストは、ユーザレベルのプロセスの実行状態と カーネルが管理しているプロセスのシステム状態の両方を含んでいます。 カーネルの状態に関する重要な構成要素については、4 章で解説しています。
プロセスのライフサイクル +--------------+ wait +--------------+ | 親プロセス |------------------------------->| 親プロセス |---> +--------------+ +--------------+ | ^ | fork | V | +--------------+ execve +--------------+ wait +----------------+ | 子プロセス |------->| 子プロセス |------->| ゾンビプロセス | +--------------+ +--------------+ +----------------+ プロセス管理システムコール
ではプロセスのライフサイクルを示しています。 プロセスは fork システムコールを用いて、 元のプロセスのコピーとして新しいプロセスを生成することができます。 fork は呼び出されると 二度戻ります。一方は親プロセスに子プロセスのプロセス ID を返し、 もう一方は子プロセスに 0 を返します。 プロセスの親子関係はシステム上のプロセスの組に階層構造をもたらします。 新しく生成されたプロセスはファイル記述子やシグナルハンドラの状態、 メモリレイアウトのような親が持っているリソースすべてを共有します。 親のコピーとして生成された新しいプロセスであっても、 別のプログラムをロードし実行することでより便利で特有の動作をすることもできます。 プロセスは execve システムコールを用いることで、 別のプログラムのメモリイメージで自分自身を上書きして、 新しい引数の組をその新しく作成したイメージに引き渡すことができます。 引数の一つは、システムで認識されるフォーマット (バイナリ実行ファイルや指定されたインタプリタプログラムの起動を促すファイル) をしたファイルの名前です。 プロセスは exit システムコールを実行することで、 親プロセスに 8 ビットの exit ステータスを送信して終了することができます。 もしプロセスが 1 バイト以上の情報を親プロセスに伝えたい場合には、 パイプやソケット、または仲介ファイルを用いて プロセス間通信チャネルをセットアップする必要があります。 プロセス間通信については 11 章で大きく取り上げています。 プロセスは、wait システムコールを用いて 子プロセスのいずれかが終了するまで実行を中断することができ、 wait システムコールは終了した子プロセスの PID と終了ステータスを返します。 親プロセスは、子プロセスが終了または異常終了したときのシグナルによる通知のされ方を調整できます。 wait4 システムコールを使用することで、 親プロセスは子プロセスの終了を引き起こしたイベントについての情報と、 子プロセスが生存期間の間に消費したリソースについての情報を取得することができます。 もし親プロセスが先に終了したためにリソースがオーファンド (親のない状態) になってしまった場合、カーネルは init という特別なプロセスにその子プロセスの 終了ステータスが渡されるよう調整します。これについては 3.1 節および 14.6 節を参照してください。 5 章では、カーネルがどのようにしてプロセスを生成し 消滅させるかについての詳細を述べています。 プロセスはプロセス優先度というパラメータに従って 実行をスケジュールされます。 この優先度はカーネルベースのスケジューリングアルゴリズムによって管理されています。 スケジューリングの優先度全体に重みづけする特別なパラメータ (nice) によって、ユーザはプロセスの実行優先度に影響を与えることができますが、 カーネルのスケジューリングポリシに従って、基本となる CPU リソースを共有する必要があります。 シグナル システムはプロセスに送ることができる シグナルのセットを定義しています。 4.4BSD におけるシグナルはハードウェア割り込みをモデルとしています。 プロセスはユーザレベルのサブルーチンをシグナルが送られるべき ハンドラとして指定できます。 シグナルが発生して、それがハンドラによって捕捉されている間は さらなるシグナルの発生はブロックされます。 シグナルを捕捉することで、現在のプロセスのコンテキストを保存し、 ハンドラを実行するための新たなコンテキストを構築することになります。 シグナルがハンドラに伝わると、そのハンドラはプロセスをアボートさせたり、 (おそらく大域変数に値を設定した後で) 実行中のプロセスに戻ることもできます。 ハンドラから戻ると、そのシグナルはブロックされなくなり、 発生する (そして捕捉される) ことが再び可能になります。 また、プロセスはシグナルを無視することや、 カーネルで定義されているデフォルトの動作を行なうように指定することができます。 ある種のシグナルのデフォルトでの動作はプロセスを終了させることです。 このような場合の終了は、事後のデバッグに使用できるようにその時のプロセスのメモリイメージを含んだ コアファイルの生成を伴います。 いくつかのシグナルは捕捉することも無視することもできません。 そのシグナルは、暴走したプロセスを停止させる SIGKILL や、 ジョブコントロールシグナルである SIGSTOP です。 プロセスはシグナルを特別なスタックに伝達させることも選択できます。 これにより、洗練されたソフトウェアスタック操作が可能です。 たとえば、コルーチンをサポートしている言語では それぞれのコルーチンにスタックを提供する必要があります。 その言語の実行システムは、4.4BSD で提供される単一のスタックを分割することで、 これらのスタックを割り当てることができます。 もしカーネルが独立したシグナルスタックをサポートしていない場合、 それぞれのコルーチンに割り当てられた領域を シグナルの捕捉に必要な分だけ拡張しなければなりません。 すべてのシグナルは、同じ優先度を持っています。 もし複数のシグナルが同時に未処理となっている場合は、 シグナルの届く順序は実装に依存します。 シグナルハンドラは、そのシグナルがブロックされるようにして実行しますが、 他のシグナルは依然発生可能です。 このメカニズムにより、プロセスは コードのクリティカルな部分を特定のシグナルの発生に対して保護することができるのです。 シグナルの設計と実装の詳細は、4.7 節で解説しています。 プロセスグループとセッション 複数のプロセスを組織してプロセスグループが作られます。 プロセスグループは端末へのアクセスの制御や 関係プロセスの集合にシグナルを送る手段を提供するのに使用されます。 プロセスは親プロセスからプロセスグループを引き継ぎます。 プロセスが自分自身または自分の子孫のプロセスグループを変更できるようにする メカニズムをカーネルは提供しています。 新しいプロセスグループを作成することは簡単です。 新しいプロセスグループの値はたいてい 作成したプロセスのプロセス ID となります。 プロセスグループにおけるプロセスの集合は、ジョブと呼ばれることがあり、 シェルのような高レベルのシステムソフトウェアで操作されます。 シェルによって生成されるよくある類のジョブは、いくつかのプロセスをパイプでつないだ パイプラインで、最初のプロセスの出力が 2 番目の入力となり、 2 番目の出力が 3 番目の入力となり、4 番目も同様に… というものです。 シェルはパイプラインの各段階においてプロセスを fork して、 これらすべてのプロセスを別個のプロセスグループにおくことで このようなジョブを生成します。 ユーザプロセスは、単独のプロセスに送る場合と同様に プロセスグループのそれぞれのプロセスにまとめてシグナルを送ることができます。 指定されたプロセスグループに属するプロセスが そのプロセスグループに影響するソフトウェア割り込みを受け取ると、 それによってプロセスグループは実行を中断や再開をしたり、 割り込みを受けたり、終了させられたりします。 端末にはプロセスグループ ID が割り当てられています。 この ID は、端末に関連づけられたプロセスグループの ID が通常セットされます。 ジョブコントロール機能を持つシェルは、同じ端末に関連づけされた プロセスグループを多数作成することができます。 その端末は、これらのプロセスグループに属するプロセスの制御端末となります。 プロセスは、端末のプロセスグループ ID とそのプロセスのプロセスグループ ID が一致したときのみ、 制御端末を記述子から読むことができます。 もしプロセスグループ ID が一致していなければ、 プロセスがその端末から読み込もうとする際にブロックされます。 端末のプロセスグループ ID を変更することで、 シェルはいくつかの異なるジョブの間で端末を調停することができます。 この調停はジョブコントロールと呼ばれ、 プロセスグループとともに 4.8 節で解説しています。 関連するプロセスの集合をプロセスグループとしてまとめることができるのと同じように、 プロセスグループの集合をセッションとしてまとめることができます。 セッションのおもな用途は、デーモンプロセスとその子プロセスに対して隔離した環境を作り出したり、 ユーザのログインシェルとそのシェルが作り出すジョブをひとまとめにすることです。 メモリ管理 それぞれのプロセスはプロセスごとのプライベートアドレス空間を持っています。 アドレス空間は、最初に論理的な3つのセグメントに分割されます: テキスト、 データ、および スタックです。 テキストセグメントは読み出し専用で、プログラムの命令を含んでいます。 データ及びスタックセグメントは読み取り書き込みともに可能です。 データセグメントには 初期化されているデータと初期化されていないデータがあるのに対し、 スタックセグメントはランタイムスタックを保持します。 ほとんどのマシンでは、プロセスが実行するとともに、 カーネルによってスタックセグメントは自動的に拡張されます。 プロセスはシステムコールによりデータセグメントを拡張する事が可能ですが、 セグメントの内容がファイルシステムからのデータである場合、あるいは デバッグ時に限りプロセスはそのテキストセグメントのサイズを変更することができます 子プロセスのセグメントの初期の内容は親プロセスのセグメントのコピーです。 プロセスアドレス空間の全内容はプロセスが実行するのには必要がありません。 プロセスがメインメモリにおいて保持されていないアドレス空間の一部を参照する場合、 システムはメインメモリーからメモリの中の必要な情報を ページ につけます。 システムリソースが不足する場合、システムは利用可能な資源を維持するために2レベルのアプローチをします。 適度の量のメモリが利用可能な場合でこれらの資源が最近使用されていない場合、 システムはプロセスからメモリリソースを解放します。 メモリー不足が深刻だった場合、システムはプロセスの全情況を２次キャッシュの スワップ に頼ります。 ページング と スワップ の交換はシステムによって行われた、プロセスに有効です。 プロセスは実行援助として予期された将来のメモリ利用についてシステムに助言するかもしれません。 BSDメモリ管理設計の決定 疎の広いアドレス空間のサポート、 メモリマップファイル、共有メモリは、 4.2BSD に要求されたものの一つでした。 独立したプロセス群がプロセスのアドレス空間をファイルにマッピングし、 それの共有を可能にする mmap と呼ばれるインタフェースが規定されました。 複数のプロセスが同じファイルにプロセスのアドレス空間をマッピングした場合、 一つのプロセスがファイルにマッピングされたアドレス空間の一部分に対して 加えた変更は、通常のファイルがそうであるのと同様、 同じ部分をマッピングしている他のプロセスにも反映されます。 しかし結局、4.2BSDは mmap インタフェースを含まない形でリリースされました。 これはネットワークのような他の機能を実現する方が重要で、 時間的な余裕がなかったからです。 mmap インタフェースの開発は、4.3BSD の作業の間も続けられました。 40 社を超える会社と研究グループが、 Berkeley Software Architecture Manual に記載されたアーキテクチャの改訂版を策定する議論に参加し、 いくつかの企業はその改訂版のインタフェースを実装しました 。 しかし、またもや時間的な問題により 4.3BSD への mmap インタフェースの実装は見送られました。 もちろん既存の 4.3BSD 仮想記憶システムにそのインタフェースを組み込むことは 可能だったのですが、4.3BSD の仮想記憶システムの実装は 10 年近く前のものであったため、開発者たちはそれを組み込まないことに決定したのです。 4.3BSD の仮想記憶システムはローカルに接続されたディスク装置は高速・大容量・安価で、 コンピュータのメモリは小容量・高価であるという仮定に基づいて設計されており、 そのため、その設計はメモリ利用量を節約できる代わりに 余分なディスクアクセスを生成してしまうものでした。 また、この実装は VAX のメモリ管理ハードウェアに強く依存するもので、 他のコンピュータアーキテクチャへの移植が困難でした。 最後にもう一つ付け加えるなら、この仮想記憶システムは 現在普及がすすみ重要になってきている密結合マルチプロセッサに 対応するように設計されていなかったのです。 古い仮想記憶システムの実装を改良しようという試みは、 ますます失敗が運命づけられたように思われました。 その一方で、完全に新しい設計は大容量メモリを利用し、 ディスクへのデータ転送を低減し、 マルチプロセッサで動作することができる能力を持っていました。 その結果、仮想記憶システムは 4.4BSD で完全に置き換えられることになったのです。 4.4BSD 仮想記憶システムは Mach 2.0 VM システム をベースに、Mach 2.5 と Mach 2.0 の改良を採り入れたものです。 この実装は、 メモリ共有の効率が良く機種依存部分と機種非依存部分がきれいに分離されていて、 (現在は使われていませんが) マルチプロセッサに対応しているという特徴を持っています。 各プロセスは自分のアドレス空間のあらゆる部分をファイルにマッピングすることができ、 互いに同一のファイルにアドレス空間をマッピングすることで、 プロセス間でアドレス空間の一部を共有することが可能になりました。 一つのプロセスが加えた変更は他のプロセスのアドレス空間にも反映され、 マッピングされたファイル自身にも書き込まれます。 また、プロセスはファイルをプライベートマッピングすることも可能です。 プライベートマッピングとは、プロセスが加えた変更が、 そのファイルをマッピングしている他のプロセスから見えないようにしたり、 ファイル自身に書き戻されないようにするものです。 仮想記憶システムの抱えるもう一つの問題は、 システムコールが発行された時にカーネルに情報を渡す方法です。 4.4BSD では、常にプロセスのアドレス空間からカーネル内のバッファに データをコピーしていました。 大容量のデータを転送する読み書き操作が発生することを考えると、 このコピーの実行には時間がかかる可能性があります。 コピーを実現するもう一つの方法として、 プロセスのメモリをカーネル内に再マッピングする方法があります。 しかし 4.4BSD カーネルは、 以下の理由から常にデータをコピーします。 ほとんどの場合ユーザデータはページ境界にアラインされていませんし、 ハードウェアページ長の倍数でもありません。 そのページをプロセスが破棄してしまうと、 カーネルがページを参照できなくなってしまいます。 プログラムの中には、カーネル内のバッファに 書かれたデータが残っていることを想定しているものがあります。 (現在の 4.4BSD セマンティクスで可能なように) プロセスがページのコピーを持てる場合、 そのページは必ずコピーオンライト(copy-on-write) になっています。 コピーオンライトのページとは、 読み込み専用に設定することで書き込みに対する保護機能を有効化したページのことです。 プロセスがそのページを変更しようとするとカーネルは書き込み例外を検出します。 その際カーネルは、プロセスが変更できるようにそのページのコピーを作成します。 残念ながら、プロセスは通常すぐに出力バッファに新しいデータを書こうとするため、 結局データのコピーが発生してしまいます。 ページが新しい仮想メモリアドレスに再マッピングされる際、 ほとんどのメモリ管理ハードウェアでは、 ハードウェアアドレス変換キャッシュの一部を破棄する必要があります。 多くの場合、このキャッシュの破棄は時間がかかるため、 4 から 8 キロバイトより小さいデータブロックに対しては、 コピーするよりも再マッピングする方が実質的に遅い、 という結果となります。 メモリマッピングの最も大きな目的は、 巨大なファイルへのアクセスと、 プロセス間の大容量のデータ転送という要求に応えることです。 mmap インタフェースは、 両方の要求をコピーを行なうことなく実現する一つの方法を提供します。 カーネル内部のメモリ管理 カーネルは一つのシステムコールの間だけ必要とされるメモリの割り当てを頻繁に行ないます。 ユーザプロセスではおそらく、 そのような短期間使われるメモリはランタイムスタックに割り当てられるでしょう。 カーネルのランタイムスタックには上限があるため、 小さめのメモリブロックだとしてもスタックにメモリを割り当てることはできません。 そのため、 そのようなメモリはもっと動的な機能を用いて割り当てる必要があります。 たとえば、システムがパス名の解釈を行なう場合、 パス名を保持するために 1 キロバイトのバッファを割り当てる必要があります。 しかしメモリブロックは一つのシステムコールよりも 長く持続していなければならないため、 スタックに空きがあったとしても、そこに割り当てることはできないでしょう。 こういう例の一つに、ネットワークが接続されている間維持している必要がある プロトコル制御ブロックがあります。 カーネル内の動的なメモリ割り当てに対する需要は、 サービスが追加されるにつれて増加しています。 汎用のメモリアロケータがあれば、 カーネル内部のコードを書く際の複雑さを低減することができます。 そのため 4.4BSD カーネルでは、システムのあらゆる場面で利用可能な 単一のメモリアロケータを備えています。 これは、 アプリケーションプログラム用のメモリ割り付けを実現するために C ライブラリルーチンに含まれている malloc と free と類似したインタフェースを持っています 。 この割り付けルーチンは C ライブラリインタフェースと同様、 引数として必要なメモリサイズを指定します。 割り当てるメモリサイズの上限はありませんが、 割り当てられるのは物理メモリであり、ページではありません。 メモリ解放ルーチンは解放するメモリへのポインタを引数にとります。 その際、解放するメモリサイズを指定する必要はありません。 I/O システム 基本的な UNIX の I/O システムモデルは、ランダムアクセスおよび シーケンシャルアクセスの可能なバイト列です。 通常の UNIX ユーザープロセスには、 アクセスメソッド や コントロールブロック は存在しません。 I/O にさまざまなレベルの構造を期待するプログラムは各種ありますが、 カーネルは I/O に構造を課しません。 たとえば、テキストファイルは改行文字 (ASCII LF 文字) で区切られた ASCII 文字の行の集まりですが、 カーネルはそのような構造を関知しません。 ほとんどのプログラムにとって、 このモデルはデータバイトのストリームもしくは I/O ストリーム にすぎません。 このような単一のデータ構造が、UNIX のツールベースのアプローチ (tool-based approach) を可能にしているのです。 あるプログラムの出力ストリームは、他のほとんどのプログラムの入力 ストリームとしてそのまま与える事ができます (このような伝統的な UNIX の I/O ストリームを、Eighth Edition のストリーム I/O システムや、 System V Release 3 の STREAMS と混同すべきではありませんが, どちらのストリームも伝統的な I/O ストリームと同じようにアクセスすることが可能です)。 記述子と I/O UNIX のプロセスは、I/O ストリームを参照するのに 記述子(descriptor)を使用します。 記述子は open または socket システムコールにより取得される符号無しの小さな整数です。 openシステムコールは、 引数にファイル名および許可モードをとり、 それぞれ開くファイルおよび、モード (読み込み、書き込みまたは読み書き) を指定します。 open システムコールは、新しい空のファイルの作成にも使用できます。 readおよび writeシステムコールを記述子に対して使用し、 データの転送を行います。 closeシステムコールは、任意の記述子を開放します。 記述子は、カーネルでサポートされるオブジェクトを表します。 4.4BSD では、ファイル、パイプ、ソケットの 3 つのオブジェクトを 表すことができます。 ファイルは、少なくとも 1 個の名前を持つバイト列です。 ファイルは、すべての名前を明示的に削除し、 その記述子を持つすべてのプロセスが消滅するまで存在します。 プロセスは、open システムコールにより、 指定されたファイル名を持つファイルのファイル記述子を取得します。 I/O デバイスはファイルとしてアクセスされます。 パイプとは、 ファイルと同じくバイト列ですが I/O ストリームとしてのみ使われ、単一方向にのみ使われます。 パイプには名前がないので、open システムコールでは開くことができません。 パイプを開くには、pipe システムコールを使用します。 pipeシステムコールは 2 つの記述子を返します。 ひとつの記述子に入力されたデータは、 もう一方の記述子にそのまま順序を変えずに出力されます。 名前付きパイプ (FIFO) も使用できます。 名前があるのでファイルシステム上に配置され、 open システムコールでアクセスできる以外は、 パイプと同一の機能を持ちます。 FIFO を使用してプロセス間通信を行いたい場合は、 片方のプロセスが FIFO を書き込み用に開き、 もう片方では読み込み用に開きます。 ソケットは、 プロセス間通信のために使用されるオブジェクトで、 ソケットを参照する記述子を持つプロセスが存在する間のみ存在します。 ソケットは socket システムコールで作成します。 socket システムコールは、 作成したソケットの記述子を返します。 さまざまな通信方法を実現するために、 各種のソケットがあります。 たとえば、信頼性の高いデータ転送を目的としたソケット、 メッセージの順番を保持するソケット、 メッセージの境界を保護するソケットなどがあります。 4.2BSD でソケットが導入されるまで、 パイプはファイルシステムを用いて実装されていました。 4.2BSD 以降では、ソケットを使用して実装されています。 カーネルはそれぞれのプロセスの記述子テーブルを保持しており、 記述子の外部表現を内部表現に変換するために用いられます (記述子そのものはこのテーブルへのインデックス値にすぎません)。 記述子テーブルは、親プロセスから子プロセスに継承されます。 そのため、記述子の参照先も同じく継承されます。 記述子を得るためには、オブジェクトを開いたり、 作成したりする以外に、 このような親プロセスからの継承による方法があります。 また IPC ソケットを使用すれば、 同一マシン上で動作している無関係なプロセス間で、 記述子のやりとりが可能です。 すべての有効な記述子は、 オブジェクトの先頭からの位置を ファイルオフセット としてバイト単位で保持しています。 読み込みおよび書き込み動作は、 このオフセット位置から行われ、 データが転送される毎にオフセットの位置は更新されます。 ランダムアクセスを許可しているオブジェクトの場合、 ファイルオフセットは、lseek システムコールを利用して移動することもできます。 通常のファイルやある種のデバイスはランダムアクセス可能です。 パイプ、ソケットはランダムアクセスできません。 プロセスが終了すると、 カーネルはそのプロセスに使用されていたすべての識別子を回収します。 プロセスがオブジェクトへの参照を保持したまま終了した場合は、 オブジェクトマネージャに通知し、ファイルの削除、 ソケットの開放などの必要なクリーンアップを行わせます。 記述子の管理 ほとんどの場合、プロセスが起動されると、 3 つの記述子がすでに開かれています。 それらの記述子は、0、1、2 で、それぞれ一般的には、 標準入力、 標準出力、 標準エラー出力 として知られています。 通常これらの識別子は、 ログインプロセスによりユーザの端末に割り当てられています (14.6 節参照)。すなわち、キーボードからの入力を標準入力として受け取り、 標準出力への出力は端末の画面に表示されます。 標準エラー出力もエラー出力用に書き込み用に開かれていますが、 通常の出力には標準出力が利用されます。 これらの記述子を (他の記述子も) 端末以外のオブジェクトに割り当てることも可能です。 このような割り当てを、 I/O リダイレクトと呼びます。 すべての標準シェルでは、ユーザが I/O リダイレクトを行うことができます。 記述子 1 (標準出力) を閉じ、 指定したファイルを記述子 1 として開くことで、 シェルは出力をファイルに送ることができます。 同様に、記述子 0 を閉じ、 指定したファイルを開くことで、 ファイルから標準入力を受け取るようにできます。 パイプは、プログラムの変更をまったく行わず (再リンクも必要ありません)、あるプログラムの出力を 他のプログラムに入力することを可能にします。 出力側のプログラムの記述子 1 (標準出力) は、端末出力の代わりにパイプの入力記述子に割り当てられます。 同様に入力側のプログラムの記述子 0 (標準入力) は、 端末からのキーボード入力ではなくパイプの出力記述子に割り当てられます。 open、 pipe、 socket システムコールは、新しい記述子を生成し、 使用できる最も小さい番号を割り当てます。 パイプを動作させるためには、そのように生成された記述子を 0 や 1 にマップする仕組みが必要になります。 dup システムコールは、 同一のファイルテーブルエントリを指す記述子のコピーを作成します。 新しい記述子も同じく使用可能な最小の番号が使われるため、 dupシステムコールを使用して、 必要なマップを行えます。 ただ、記述子 1 が必要な場合でも、記述子 0 が既に閉じられていると、 記述子 0 が割り当てられてしまいますので注意が必要です。 この問題を避けるため、 dup2 システムコールがあります。 dup に引数が 1 つ追加され、 割り当てたい記述子の番号を指定することができます (もし、指定された番号の記述子が使用中の場合、 dup2 は、まずその記述子を閉じたのち、 再割り当てします)。 デバイス ハードウェアデバイスはファイル名を持ち、通常のファイルと 同一のシステムコールでアクセスできます。カーネルは、 デバイス特殊ファイル や 特殊ファイルを区別し、 参照しているデバイスを特定できますが、 ほとんどのプロセスにとって、このような区別は必要ありません。 端末、プリンタ、テープデバイスは、4.4BSD のディスクファイルと同様、 バイト列としてアクセスされます。そのため、デバイス依存部分や特殊部分は、 可能な限りカーネルに隠蔽され、さらにカーネル内でも、 それらの大部分がデバイスドライバ内に分離されています。 ハードウェアデバイスは、 構造を持つデバイスと 構造を持たないデバイスに分けられます。 それぞれ、 ブロックデバイス、 キャラクタデバイスと呼ばれます。 それらのデバイスファイルへのアクセスは、カーネル内の デバイスドライバ と呼ばれるソフトウェアモジュールによって処理されます。 ほとんどのネットワーク通信ハードウェアデバイスは、 ファイルシステム上に特殊ファイルを持たず、 プロセス間通信機能によってのみアクセスできます。 それは、raw-socketの方が特殊ファイルより、 より自然なインタフェースを提供できるためです。 典型的なブロックデバイス (構造を持つデバイス) としては、 ディスク、磁気テープがあげられますが、 ほとんどのランダムアクセスデバイスがそれに該当します。 カーネルは、読み込み-変更-書き込みに対してバッファリングを提供し、 通常ファイルと同様の、 完全なバイトアドレス指定のランダムアクセスを提供します。 ファイルシステムは、ブロックデバイス上に構築されます。 構造を持たないデバイスは、 ブロック構造をサポートしないデバイスで、通信線、ラスタプロッタ、 バッファのない磁気ディスクやテープなどです。 構造を持たないデバイスは通常、 大容量のブロック I/O 転送をサポートします。 構造を持たないファイルはキャラクタデバイスと呼ばれます。 これは最初に実装されたこの種類のデバイスが、 端末デバイスドライバだったからです。 このようなデバイスに対するカーネルのインタフェースは、 他のブロック構造を持たないデバイスに対しても有用であることが証明されました。 デバイス特殊ファイルは、 mknodシステムコールにより作成されます。 ioctlシステムコールは、 特殊ファイルに対応するデバイスのパラメータを操作するのに使われます。 このシステムコールは、他のシステムコールに新たな機能を追加せずに、 デバイスの特殊な機能を操作することを可能にします。 たとえば、ioctlを使用して、 終了マークをテープデバイスに書き込むことができます。 write に変更を加えたり、 特殊なバージョンを用意する必要はありません。 ソケット IPC 4.2BSD カーネルはソケットを利用して、パイプより柔軟な IPC 機能を導入しました。ソケットは、ファイルやパイプと同様、 記述子により参照される、通信の末端点です。 2 つのプロセスがそれぞれ、ソケットを作成して接続することにより、 信頼性の高いバイトストリームを作成できます。 接続されれば、それぞれのプロセスは、パイプと同じように、 読み込み書き込みをソケットに対して行えます。 ソケットの透明性により、カーネルはプロセスの出力を、 別のマシン上のプロセスの入力に送ることも可能です。 パイプとソケットの大きな違いは、 パイプは共通の親プロセスが設定する必要があるのに対して、 ソケットはまったく無関係の (異なるマシン上で動作する) プロセス間でも使用できる点です。 System V は、FIFO もしくは名前付きパイプと呼ばれる ローカルプロセス間通信の仕組みを備えています。 FIFO はファイルシステム上のオブジェクトとして現われ、 パイプと同様な方法でオープンし、データを送ることができます。 そのため、FIFO は共通の親プロセスによって設定される必要はなく、 プロセス同士が起動し動作開始してから接続することが可能です。 しかしソケットとは異なり、 異なるマシン上で動作するプロセスに対しては使用できません。 4.4BSD で、FIFO が実装されているのは、 POSIX.1 標準に準拠するためのみです。 FIFO の機能は、ソケットの機能の一部になっています。 ソケット機構を実現するには、 伝統的な UNIX の I/O システムコールに名前付けや接続機能を追加する必要がありました。 開発者は、既存のインタフェースへの拡張は既存のシステムコールが変更なしに使用できる範囲にとどめ、 追加機能を扱う新しいインタフェースを設計しました。 バイトストリーム型の接続の読み込み書き込みを行う readと write システムコールに加え、 ネットワークダイアグラムのような宛名付きメッセージを読み込むため、 新たに 6 つのシステムコールが追加されました。 メッセージ書き込み用の send、 sendto、 sendmsg システムコールと、 メッセージの読み込み用の recv、 recvfrom、 recvmsg システムコールです。 考え直して見ると、 それぞれの読み書き用のシステムコールのうち最初の 2 つは次のシステムコールの特殊な場合であるので、 recvfrom と sendto システムコールは、それぞれ recvmsg と sendmsg のライブラリインタフェースとし て追加すべきだったかも知れません。 Scatter/Gather I/O 既存の read および write システムコールに加え、 4.2BSD で scatter/gather I/O 機能が導入されました。 scatter 入力は readv システムコールによって行われ、 複数の異なるバッファに対して単一の読み込みを実行できます。 逆に writev システムコールは、複数の異なるバッファに対してアトミックな書き込みを実行できます。 read や write によって行われるように、 単一のバッファと長さをパラメータとして渡す代わりに、 バッファと長さの配列へのポインタとそのサイズを渡します。 この機能により、 プロセスアドレス空間の異なる場所にあるバッファに対してアトミックな単一の書き込みを行え、 隣接するバッファにコピーする必要もありません。 テープデバイスのように、それぞれの要求に対し、 テープブロックを出力をする必要があるようなレコードベースのデバイスを抽象化した場合、 アトミックな書き込みが必要になります。 また、単一の読み込みリクエストで複数のバッファに読み込めるのは非常に便利です (たとえばレコードヘッダとデータをそれぞれ別のバッファに読み込む場合など)。 もちろん単一の大きなバッファにデータを読み込み、 読み込んだデータを必要な場所に移動することで scatter 動作をシミュレートすることは可能です。 ただし、このようなメモリ間のコピーのコストは、 アプリケーションの動作に必要な時間を 2 倍以上にしてしまうことも良くあります。 send と recv がそれぞれ、 sendto と recvfrom のライブラリインタフェースとして実装可能であったのと同じく、 read と write をそれぞれ、 readv と writev のライブラリインタフェースとして実装も可能であったでしょう。 しかし、 read と write はより頻繁に使われるため、 シミュレートするための追加コストを考えると ライブラリインタフェースとしての実装は割に合わなかったでしょう。 複数のファイルシステムのサポート ネットワークコンピューティングの発達により、 ローカルおよびリモートファイルシステムへの対応が望まれるようになりました。 複数のファイルシステムのサポートを簡単にするために、 開発者は vnode インタフェースをカーネルに追加しました。 vnode インタフェースから提供される操作は、 以前にローカルファイルシステムでサポートされていたファイルシステム操作とほぼ同じですが、 幅広いファイルシステムにより使用ができるようになっています。 ローカルのディスクファイルシステム 各種リモートファイルシステムプロトコルによりインポートされたファイル 読み込み専用 CD-ROM ファイルシステム 特殊機能を提供するファイルシステム。 たとえば /proc ファイルシステムなど 4.4BSD 由来の OS の中には FreeBSD のように、 mount でファイルシステムが初めて参照された時にファイルシステムを動的に読み込むことが できるものもあります。 vnode インタフェースについては 6.5 節、 補助サポートルーチンについては 6.6 節、 特殊機能ファイルシステムについては 6.7 節に記載されています。 ファイルシステム 通常ファイルとは一次元のバイト列であり、 任意の場所から読み込み・書き込みが可能です。 カーネルは、ファイルのレコード境界を認識しませんが、 多くのプログラムは 改行 (LF) 文字を行の終りと認識します。 またこれとは異なるファイル構造を利用するアプリケーションもあります。 ファイル自身には、ファイルに関するシステム情報はまったく含まれません。 各ファイルのファイル所有者、許可属性、 使用状況などのいくつかの情報はファイルではなくファイルシステムが保持しています。 ファイル名は最大 255 文字までの文字列です。 ファイル名はディレクトリ と呼ばれる型のファイルに保管されます。 ディレクトリに含まれるファイルの情報はディレクトリエントリと呼ばれ、 ファイル名以外にファイルそのものへのポインタも含みます。 ディレクトリエントリには通常のファイル以外に、 他のディレクトリを参照するエントリが含まれます。 このようにしてディレクトリとファイルによる階層が形作られ、 その階層構造をファイルシステムと呼びます。
小規模なファイルシステム +-------+ | | +-------+ / \ usr / \ vmunix |/ \| +-------+ +-------+ | | | | +-------+ +-------+ / | \ staff / | \ bin |/ | tmp \| +-------+ V +-------+ | | +-------+ | | +-------+ | | +-------+ / | \ +-------+ / | \ mckusick / | \| |/ | \ ls |/ | karels | vi \| +-------+ V V +-------+ | | +-------+ +-------+ | | +-------+ | | | | +-------+ +-------+ +-------+ 小規模なファイルシステムツリー
は小規模なファイルシステムの一例です。 ディレクトリはサブディレクトリを含むことができ、 入れ子の深さには特に制限はありません。 ファイルシステムの一貫性を保つため、 カーネルはプロセスが直接ディレクトリへ書き込むことを禁止しています。 ファイルシステムには、通常ファイル、ディレクトリ以外に、 デバイスファイルやソケットなどの他のオブジェクトへの参照も含まれます。 ファイルシステムは、 ルートディレクトリ を始点とする木構造を持っています。 ルートディレクトリは、 スラッシュ と呼ばれる場合もあり、斜線文字(/)で表されます。 ルートディレクトリにはファイルが含まれます。 図 2.2 の例では、 usr ディレクトリが含まれ、その usr ディレクトリには、 bin ディレクトリが含まれます。 bin ディレクトリには、通常 ls や vi をはじめとする、プログラムの実行可能コードが含まれます。 プロセスは、ファイルの指定をパス名によって行います。 パス名は、0 個以上のファイル名を斜線文字(/)で区切った文字列です。 カーネルはパス名を解釈するため、それぞれのプロセスに 2 つのパス名を関連付けます。 プロセスのルートディレクトリは、 プロセスがアクセスできるファイルシステム上で最も上位の点です。 通常、このルートディレクトリは、 ファイルシステム全体のルートディレクトリに設定されます。 斜線文字 (/) ではじまるパス名は絶対パス名と呼ばれ、 カーネルは、そのパス名がプロセスのルートディレクトリから 開始するものと解釈します。 斜線文字 (/) ではじまらないパス名は相対パス名と呼ばれ、 プロセスのカレント作業ディレクトリを基準とした相対的なパスとして解釈されます (このディレクトリは、短縮して カレントディレクトリ または、 作業ディレクトリ とも呼ばれます)。 カレントディレクトリそのものは、 ドット とも呼ばれ、1 つのピリオド (.) で表されます。 ファイル名 ドットドット (..) は、 ディレクトリの親ディレクトリを表します。 ルートディレクトリの親ディレクトリはルートディレクトリ自身です。 chroot システムコールにより、プロセスのルートディレクトリを、 chdir システムコールにより、カレントディレクトリを変更できます。 chdir はいつでも行えますが、 chroot の実行は、管理者特権を持つプロセスに限られます。 chroot は通常、システムに対するアクセス制限を課すために用いられます。 図 2.2 のファイルシステムにおいて、プロセスのルートディレクトリ がファイルシステムのルートディレクトリで、カレントディレクトリが /usr であったとします。このとき、 vi を参照するには、絶対パスを用いて、 /usr/bin/vi とも書けますし、カレントディレクトリからの相対パスを用いて、 bin/vi とも書けます。 システムのユーティリティやデータベースは、 よく知られたある決まったディレクトリに保存されます。 ファイルシステムの階層構造としてよく知られたものに、 各々のユーザのホームディレクトリがあります。 たとえば、図 2.2 の /usr/staff/mckusick や /usr/staff/karels などです。 ユーザがログインすると、 シェルのカレントディレクトリはホームディレクトリに設定されます。 ユーザはホームディレクトリ内で通常ファイルの作成と同様にディレクトリも作成できるため、 複雑な階層構造を構築することも可能です。 ユーザからはファイルシステムが 1 つに見えますが、 システムは 1 つの仮想ファイルシステムが、 実際には異なるデバイス上の複数の物理ファイルシステムから構成されていること認識しています。 物理ファイルシステムは、異なったデバイスにまたがることはできません。 ほとんどの場合、物理ディスクデバイスは複数の論理デバイスに分割されるため、 1 つの物理デバイス上に複数のファイルシステムを構成することもできます。 すべての絶対パス名を解決できるファイルシステムを ルートファイルシステムと呼び、 常に利用可能な状態になっています。 他のファイルシステムは、マウントすることができます。 マウントとは、ルートファイルシステムのディレクトリ構造の一部として統合する操作です。 ファイルシステムにマウントされたディレクトリの参照は、 そのマウントされたファイルシステムのルートディレクトリの参照へと カーネルによって透過的に変換されます。 link システムコールは、既存のファイル名に、別名を与えます。 リンクが成功すると、 ファイルはどちらのファイル名からでもアクセスできるようになります。 ファイル名は unlink システムコールにより削除できます。 ファイルを参照していた最後の名前が削除されると (さらにファイルを開いていた最後のプロセスがファイルを閉じると) ファイルそのものも削除されます。 ファイルはディレクトリ内で階層構造を持って保持されます。 ディレクトリそのものも一種のファイルですが、 ディレクトリは一般のファイルと異なり、 システムによって決められた構造を持っています。 ディレクトリは一般のファイルと同じくプロセスから読み込むことが可能ですが、 ディレクトリに変更を加えられるのはカーネルだけです。 ディレクトリは mkdir システムコールで作成し、 rmdir システムコールで削除します。 4.2BSD 以前のシステムにおける mkdir と rmdir システムコールは、一連の link、unlink システムコールの実行として実装されていました。 明示的にディレクトリの作成、 削除を行うシステムコールを新たに追加した理由は、3 つあります。 アトミックな動作を可能にするため。 link システムコールによる実装の場合と異なり、 システムがクラッシュした場合に ディレクトリの構造が中途半端なままになることがありません。 ネットワークファイルシステムを使用している場合には シリアライズ (操作順序の保証) を行うため、ファイルおよびディレクトリの作成、 削除はアトミックに行われる必要があります。 UNIX 以外のファイルシステム (他のパーティション上の MS-DOS ファイルシステムなど) をサポートする場合、 そのファイルシステムが link システムコールをサポートしない可能性があります。 たとえそれがディレクトリをサポートするファイルシステムであっても、 UNIX ファイルシステムとは異なり、ディレクトリをリンクとして作成、 削除しないものもあります。 そのためそのようなファイルシステムでは、 ディレクトリの作成、削除は、 明示的に要求されない限り行われません。 chown システムコールはファイルの所有者とグループを設定します。 chmod システムコールは、ファイルの保護モードを変更します。 これらのファイルの属性は、 stat システムコールをファイル名に対し実行することで読み出すことができます。 fchown、 fchmod、 fstat システムコールは、同様な動作をファイル名ではなくファイル記述子に対して行います。 rename システムコールは、ファイルに新しい名前をつけて古い名前を削除します。 ディレクトリ作成・削除操作と同じように、 rename システムコールはローカルファイルシステムの名前変更動作をアトミックにするため 4.2BSD で追加されました。 後に。この動作はネットワーク上の非 UNIX ファイルシステムに対して名前変更操作を行う場合に有効であることがわかりました。 truncateは、 4.2BSD で追加されたファイルを任意の長さに切り詰めるシステムコールです。 このシステムコール追加の主な目的は ランダムアクセスファイルの最後をプログラムが最後にアクセスした場所に設定する、 という動作を持つ Fortran ランタイムライブラリのサポートでした。 truncate システムコールを使用しない場合、 ファイルの長さを縮める唯一の方法は必要な部分をコピーしたファイルを作成し、 元のファイルを削除した後にコピーしたファイルをリネームする方法です。 このアルゴリズムは遅いだけでなく、 空き容量の少ないファイルシステムでは失敗する可能性があります。 ファイルシステムにファイルを縮める機能が追加されると、 それはカーネルが大きな空のディレクトリを小さくする用途に使用するようになりました。 空のディレクトリを縮小すると、 ファイルの作成、 削除時にカーネルがファイルを検索する時間を短縮できるという利点があります。 新規に作成されたファイルには、 作成したプロセスのユーザ識別子と作成が行われたディレクトリにグループ識別子を与えられます。 ファイルの保護用に 3 レベルのアクセス制御機構が用意されています。 この 3 レベルのファイルアクセス許可は ファイルを所有しているユーザ ファイルを所有しているグループ 他のすべて に対して設定することができます。 それぞれのアクセスレベルは、さらに 読み取り許可、書き込み許可、実行許可に分けられています。 ファイルは作成時に長さが 0 であり、 書き込みされるにつれて長くなっていきます。 システムはファイルが開かれると、 対応する記述子の現在位置を指定するポインタを保持します。 このポインタはファイル内をランダムアクセスするように動かすことが可能です。 fork や dup システムコールによりファイル記述子を共有するプロセス間では、 この現在位置ポインタは共有されます。 別々の open システムコールによって 作成されたファイル記述子は、独立した現在位置ポインタを持ちます。 ファイルは穴を持つことがあります。 穴とはファイルの一次元構造の中で、 データが一度も書き込まれたことのない空の部分です。 ファイルの最後尾より後にポインタを動かし書き込みを行うことで、 ファイルに穴をつくることができます。 読み込まれた場合、穴は 0 の値をもつバイトとして扱われます。 初期の UNIX システムではファイル名に 14 文字以内という制限があり、 よく問題となっていました。 たとえば、ユーザは当然ながら長く説明的なファイル名を付けたいと望みますし、 basename.extension という慣用的なファイル命名規則を考えると、 extension (C のソースファイルの .c、 中間バイナリオブジェクトファイルの .o というように、ファイルの種類を示す部分) に 1 から 3 文字必要ですから、 basename に付けられる文字数は 10 から 12 しか残っていません。 ソースコード制御システムやエディタは通常、 独自の目的のためにさらに 2 文字をファイル名の前後に付加しますので、 実際に使えるのは、8 から 10 文字になります。 basename として英語を一単語 (たとえば multiplexer) 使うだけで、 簡単に 10 から 12 文字になってしまうでしょう。 このような制限を守るのは不可能ではありませんが、 危険な場合もあります。 他の UNIX システムでは、 より長いファイル名を受け付けるものの実際にファイルを作成する時点でファイル名を 切り詰めるものがあるからです。 C のソースコードファイル multiplexer.c (すでに 13 文字です) のソースコード制御ファイルは、 頭に s. が付加されて s.multiplexer となります。 このファイルは、C ソースの文書の troff ソースファイル multiplexer.ms のソースコード制御ファイルと区別がつきません。 ソースコード制御システムはこの問題に対して警告を出さないため、 これらの 2 つのファイル内容の取り違えは容易に発生します。 注意深くコーディングすればこのような問題は避けられますが、 4.2BSD でロングファイルネームが導入されたことで この問題は実質的になくなりました。 ファイル記録機構 ローカルファイルシステムに対する操作には二種類あります。 まず、ローカルファイルシステムすべてに共通して 階層化されたファイルのネーミング、ロック、割り当て、 属性管理、保護といった、データの記録方法とは独立した機能です。 4.4BSD はこれらの機能を提供する単一の実装を備えています。 もう一つは記録媒体上におけるデータ構成と管理です。 ファイル内容を記録媒体上に配置するのはファイル記録機構の役割であり、 4.4BSD は 3 種類の異なるファイル配置法に対応しています。 伝統的な Berkeley Fast Filesystem Sprite という OS の設計に由来する ログ構造化ファイルシステム メモリベースのファイルシステム これらのファイル記録機構の構成はまったく異なるものですが、 それを使用するプロセスからは違いを意識することはありません。 Fast Filesystem は、データをシリンダグループという単位で構成します。 ファイルシステム階層の配置から考えて同時にアクセスされやすいと考えられるファイルは、 同じシリンダグループに記録され、同時にアクセスされる可能性の低いファイルは 異なるシリンダグループに記録されます。 この記録機構では以上のように、複数のファイルが同時に書き込まれたとしても、 記録される場所はディスクのまったく違う場所になる可能性があるのです。 ログ構造化ファイルシステムは、データをログという形で構成します。 ある時点で記録されたデータはすべて一つに集められ、 同じディスクの場所に書き込まれます。 データが上書きされることは絶対にありません。 ファイルの更新は、ファイルを上書きする代わりに 新しいファイルを書き込んでそのファイルを置き換えることによって行なわれます。 ファイルシステムに空き容量がなくなり新たに空き容量が必要になった場合は ゴミ集め (garbage-collection) プロセスが実行され、 古いファイルが再利用されます。 メモリベースのファイルシステムは、 データを仮想メモリに記録するように設計されたものです。 これは /tmp のように高速アクセスが必要で、 永続的でないファイルシステムに使われます。 メモリベースファイルシステムの目標は、 仮想メモリ資源の利用量を可能な限り最小限に保つことにあります。 ネットワークファイルシステム 当初、ネットワーク通信はデータをあるマシンから 他のマシンへ転送するために用いられていましたが、 のちにそれは、ユーザが離れたマシンへログイン可能な形に発展しました。 次に期待されたのはユーザがデータを取り行くのではなく、 ユーザの元にデータがやってくるようにすることでした。 そのために生まれたのがネットワークファイルシステムです。 ローカルで作業しているユーザはキー入力時にネットワークの遅れを感じず、 より応答性の良い環境を手に入れたのです。 ファイルシステムをローカルマシンに持ってくることは 初期のサーバ-クライアント型アプリケーションの中で主要なもののひとつでした。 サーバ は 1 つもしくはそれ以上のファイルシステムを エクスポートするリモートのマシンです。 クライアント はそのファイルシステムをインポートするローカルのマシンです。 ローカルのクライアントから見ると、 リモートでマウントされたファイルシステムは ローカルにマウントされた他のファイルシステムのように ファイルツリーの名前空間に現れます。 ローカルのクライアントは リモートのファイルシステム上にディレクトリを変えたり、 ローカルのファイルシステム上でするのとまったく同じように リモートのファイルシステムで読み書きをしたり、 バイナリを実行したりできます。 ローカルのクライアントが リモートのファイルシステム上で操作すると、 その操作要求がひとまとめにされてサーバに送られます。 サーバは要求された操作を行い、 クライアントから要求された情報、もしくは、 なぜその要求が拒絶されたかを示すエラーを返します。 適切な性能を得るには、 クライアントは頻繁にアクセスされたデータをキャッシュしなければなりません。 リモートファイルシステムの複雑さは、 サーバと多くのクライアントの間のキャッシュの一貫性を維持することにあります。 長期にわたって数多くのリモートファイルシステムプロトコルが開発されてきましたが、 UNIX システムにおいて最も普及しているものは、 そのプロトコルと実装の大部分が Sun Microsystems によって行なわれた ネットワークファイルシステム (NFS) です。 実装はプロトコル規格から独立して行われましたが、 4.4BSD カーネルは NFS プロトコルをサポートしています 。 NFS プロトコルについては 9 章で説明しています。 端末 端末は、標準的なシステム I/O 操作はもちろんのこと、 入力文字の編集や出力のディレイの制御をするための端末固有の操作をひととおり サポートしています。 一番低いレベルにあるのは、ハードウェア端末ポートを制御する端末デバイスドライバです。 端末入力は、たとえばボーレートのような基礎的な通信特性や、 パリティ検査のようなソフトウェアで制御可能なパラメータ類に 従って扱われます。 端末デバイスドライバの上の層には、 文字処理をどの程度行なうかを定義している ラインディシプリン (line discipline; 回線端末制御) と呼ばれるものがあります。 対話的なログインをするためにポートが 用いられるときにはデフォルトのラインディシプリンが選択され、 そのラインディシプリンはカノニカルモードで動作します。 これは、入力が標準的な行指向編集機能を提供するように処理され、 入力自体を行単位の処理で表現するモードです。 スクリーンエディタや、他のコンピュータと通信をするプログラム (訳注: telnet など) は、普通非カノニカルモード (raw モードやキャラクタごとのモード (character-at-a-time mode) などとも呼ばれます) で動作します。 これらのモードでは、入力はそのまますぐに読み込み側の プロセスへと渡されます。 すべての特殊文字入力の処理は無効化されていて、 削除やその他の行編集処理は行なわれず、 すべての文字はその端末から読み込もうとしているプロセスへと渡されます。 端末は、この二つの両極端のモードの中間の多くの組み合わせで 設定することが可能です。 たとえば、あるスクリーンエディタがユーザからの割り込みを非同期的に 受け入れたい場合に、シグナルを生成する文字や出力の流量制御を許可したまま、 それ以外を非カノニカルモードで動かして、これらの文字以外の文字を まったく解釈しないまま渡す、ということが可能です。 出力では、端末処理は次のような単純な整形サービスを提供しています。 ラインフィードをキャリッジリターンとラインフィードの並びへと変換 特定の標準的な制御文字の後にディレイを挿入 タブ文字の展開 エコーされた非表示アスキー文字を ``^C'' (すなわち、アスキーのキャレット文字 の後に、そのキャラクタの値をアスキーの ``@'' 文字からのオフセットとした アスキー文字) という二文字の並びとして表示 これらの整形機能は、コントロールリクエストを使ってそれぞれ独立に 無効化することが可能です。 プロセス間通信 (IPC) 4.4BSD のプロセス間通信 (IPC) は、コミュニケーション ドメイン内で働くようになっています。現在サポートされて いるドメインには、同じマシン上で実行している複数のプロセス間 での通信用のローカルドメイン、 TCP/IP プロトコルスイート用の (おそらく the Internet 内) インターネットドメイン、 ISO/OSI プロトコルファミリでの通信を行なうことが必要なサイト間通信用の ISO/OSI プロトコルファミリ、 XEROX Network Systems (XNS) を使用したプロセス間通信用の XNS ドメインが含まれています。 ドメイン内では、ソケットとして知られ ている通信終端間で通信が行なわれます。 2.6 節で説明しているように、 socket システムコールはソケットを生成し、その記述子を返します。 他の IPC システムコールについては 11 章で解説します。 各ソケットは、通信セマンティクスを定義した型を持ちます。 このセマンティクスには信頼性、順序、メッセージの重複防止が 含まれています。 各ソケットは、通信プロトコル と関連しています。 ここでのプロトコルは、通信相手のソケットの型に従って そのソケットで要求されているセマンティクスを提供します。 アプリケーションは、ソケットを生成する際に特定のプロトコルを 要求することができますし、また、そのシステムは、将来生成される ソケットの型にふさわしいプロトコルを選択するようにすることも 可能です。 ソケットは、そのソケットと関連づけされた (バインドされた) アドレスを持つことができます。 ソケットアドレスの形式と意味は、そのソケットが生成された コミュニケーションドメインに依存します。 ローカルドメインにおいてソケットに名前をバインドすると、 そのファイルシステムにおいてファイルが生成されます。 ソケットを通じて送受信される通常のデータは型づけされていません。 データ表現については、プロセス間通信機能の最上位に位置するライブラリに責任があります。 通常データの配送に加えて、コミュニケーションドメインは access rights という特別な型のデータの 送受信をサポートすることができます。 たとえばローカルドメインはプロセス間で記述子を渡すために、 この機能を使用します。 4.2BSD より前の UNIX におけるネットワーク機能の実装は、 大抵キャラクタデバイスインタフェースをオーバロードさせることで 動作していました。 ソケットインタフェースの目的の一つは、単純なプログラムが ストリーム型の通信を変更せずに動作するようにすることです。 そのようなプログラムは、read と write のシステムコールが変更されなければ 動作します。 当然、元のインタフェースがそのまま残されれば、 ストリーム型のソケット上で動作し続けるようになります。 send の各呼び出しで指定しなければならない 送信先アドレスを持つデータグラムを送信するような、 より複雑なソケット用に新しいインタフェースが追加されました。 もう一つの利点は、この新しいインタフェースは移植性が 非常に良いということです。 バークレーから入手できたテストリリースのすぐ後で、 ソケットインタフェースは UNIX ベンダによって System III に移植されました (しかし、AT&T は System V Release 4 のリリースまでソケットインタフェースをサポートせず、 その代わりに Eighth Edition のストリーム機構を使用する ことを決めました)。 ソケットインタフェースはまた、Excelan 社や Interlan 社のような ベンダによって多くのイーサネットカードで動作するように移植され、 マシンが小さすぎてメインプロセッサ中でネットワーク通信を動作 させることができない PC 市場に売り出されました。 ごく最近では、Microsoft 社の Windows 用の Winsock ネットワークインタフェースの基盤として ソケットインタフェースが使われています。 ネットワーク通信 ソケット IPC 機構が対応している ネットワークドメインのいくつかは、 ネットワークプロトコルへのアクセスを提供しています。 これらのプロトコルは理論上、 カーネルのソケットソフトウェアよりも下の層にある 別のソフトウェアとして実装されています。 カーネルは、バッファ管理、メッセージ配送、 各プロトコルへの汎用インタフェースを提供し、 また、さまざまなネットワークプロトコルを使用するための ネットワークインタフェースドライバへのインタフェースなど、 多くの付随サービスを提供します。 4.2BSD が実装された時点ではさまざまなネットワークプロトコルが 使用され、また開発中の段階にありました。 それらはそれぞれ固有の強みと弱みを持っており、 明らかに優れたプロトコルやプロトコルスイートというものは存在しませんでした。 4.2BSD は複数のプロトコルに対応することで、 バークレー校の環境で利用可能だったさまざまなマシン間での 資源の共有や、相互運用の提供を可能にしていました。 またこの複数プロトコルへの対応は、 将来的な変更に備えて設計されていました。 今日利用されている 10-100Mbps のイーサネット用のプロトコルは、 将来の 1-10Gbps 光ファイバネットワークに対して、 おそらく十分なものではないでしょう。 そのため、ネットワーク通信レイヤは複数のプロトコルに対応できるように 設計されています。 新しいプロトコルがカーネルに追加されても、 既存のプロトコルがその影響を受けることはまったくありません。 新しいアプリケーションは新しいネットワークプロトコルで動作し、 一方で既存のアプリケーションもまた、 それと同じ物理ネットワーク上で今までどおりのプロトコルを 利用し続けることが可能です。 ネットワーク実装 4.2BSD で実装された最初のプロトコルスイートは DARPA の Transmission Control Protocol/Internet Protocol (TCP/IP) でした。 CSRG は、ソケット IPC フレームワークに組み込む最初のネットワークとして TCP/IP を選択しました。その理由は、4.1BSD ベースの実装が DARPA がスポンサーとなっていた Bolt、Beranek、Newman (BBN) におけるプロジェクトからパブリックに入手可能だったからです。 それは大きな選択でした。 このプロトコルスイートが非常に広く利用されたのは、 主に 4.2BSD でのこの実装が理由となっています。 TCP/IP の実装に対するその後の性能と能力の改善も広く採用されました。 TCP/IP の実装については、13 章で詳細に解説しています。 4.3BSD のリリースでは、メリーランド大学とコーネル大学で部分的に 開発された Xerox Network Systems (XNS) プロトコルスイートが追加されました。 このプロトコルスイートは、TCP/IP を使用して通信できない孤立したマシンと 通信するのに必要でした。 4.4BSD のリリースでは、近頃米国内外で増加している ISO プロトコルスイートが追加されました。 ISO プロトコル群のために多少異なるセマンティクスを定義したので、 これらのセマンティクスに適合させるため ソケットインタフェースにいくつかの小さな変更が必要となりました。 その変更は、 他の既存プロトコルのクライアントには分からないようになされています。 ISO プロトコル群用に 4.3BSD カーネルで提供された 2 レベルルーティングテーブルに対する大規模な追加も必要でした。 4.4BSD で大きく拡張されたルーティング機能は、 可変長アドレスと ネットワークマスクを持つ任意のレベルのルーティングが含まれています。 システム運用 ブートストラップ機構はシステムを起動するために利用されます。 まず最初に、4.4BSD カーネルは CPU のメインメモリに読み込まれます。 カーネルが読み込まれると、 特定の状態へハードウェアを設定する初期化フェーズに移行します。 次に、カーネルは自動設定 (autoconfiguration) を行ないます。 これは CPU に接続された周辺機器の検出と設定を行なう過程です。 システムは最初、ディスクチェック、アカウント処理、 quota チェックを行なうスタートアップスクリプトを シングルユーザモードで実行します。 スタートアップスクリプトは最後に一般的に利用されるシステムサービス群を起動し、 システムを完全なマルチユーザモードに移行させます。 マルチユーザモードでは、プロセスが ユーザがアクセスできるように設定された端末回線や ネットワークポート上でのログイン要求を待ちます。 ログイン要求が検出されるとログインプロセスが生成され、 ユーザの確認処理が行われます。 そしてユーザの確認処理が成功すると、 そのユーザに対して、 他のプロセスを実行できるようにするためのログインシェルが生成されます。 参考文献 Accetta et al, 1986 Mach: A New Kernel Foundation for UNIX Development" M. Accetta R. Baron W. Bolosky D. Golub R. Rashid A. Tevanian M. Young 93-113 USENIX Association Conference Proceedings USENIX Association June 1986 Cheriton, 1988 The V Distributed System D. R. Cheriton 314-333 Comm ACM, 31, 3 March 1988 Ewens et al, 1985 Tunis: A Distributed Multiprocessor Operating System P. Ewens D. R. Blythe M. Funkenhauser R. C. Holt 247-254 USENIX Assocation Conference Proceedings USENIX Association June 1985 Gingell et al, 1987 Virtual Memory Architecture in SunOS R. Gingell J. Moran W. Shannon 81-94 USENIX Association Conference Proceedings USENIX Association June 1987 Kernighan & Pike, 1984 The UNIX Programming Environment B. W. Kernighan R. Pike Prentice-Hall
Englewood Cliffs NJ
1984 Macklem, 1994 The 4.4BSD NFS Implementation R. Macklem 6:1-14 4.4BSD System Manager's Manual O'Reilly & Associates, Inc.
Sebastopol CA
1994 McKusick & Karels, 1988 Design of a General Purpose Memory Allocator for the 4.3BSD UNIX Kernel M. K. McKusick M. J. Karels 295-304 USENIX Assocation Conference Proceedings USENIX Assocation June 1998 McKusick et al, 1994 Berkeley Software Architecture Manual, 4.4BSD Edition M. K. McKusick M. J. Karels S. J. Leffler W. N. Joy R. S. Faber 5:1-42 4.4BSD Programmer's Supplementary Documents O'Reilly & Associates, Inc.
Sebastopol CA
1994 Ritchie, 1988 Early Kernel Design private communication D. M. Ritchie March 1988 Rosenblum & Ousterhout, 1992 The Design and Implementation of a Log-Structured File System M. Rosenblum K. Ousterhout 26-52 ACM Transactions on Computer Systems, 10, 1 Association for Computing Machinery February 1992 Rozier et al, 1988 Chorus Distributed Operating Systems M. Rozier V. Abrossimov F. Armand I. Boule M. Gien M. Guillemont F. Herrmann C. Kaiser S. Langlois P. Leonard W. Neuhauser 305-370 USENIX Computing Systems, 1, 4 Fall 1988 Tevanian, 1987 Architecture-Independent Virtual Memory Management for Parallel and Distributed Environments: The Mach Approach Technical Report CMU-CS-88-106, A. Tevanian Department of Computer Science, Carnegie-Mellon University
Pittsburgh PA
December 1987 日本語化について The Design and Implementation of 4.4BSD Operating System Chapter 2 の日本語化は、原著の出版元である Addison-Weslay、 翻訳出版権を保有する Pearson Education Japan の協力を得て、 FreeBSD 日本語ドキュメンテーションプロジェクト (FreeBSD doc-jp) によって行なわれました。 日本語版について何かお気付きの点がありましたら 日本語ドキュメンテーションプロジェクト doc-jp@jp.FreeBSD.org までご連絡ください。 この日本語版の著作権は、原著者、原著の出版元である Addison-Weslay および日本語版の翻訳出版権を保有する Pearson Education Japan に帰属します。そのため、 この文書をこれらの著作権保有者の明示的な許可なく複製、 再配布することは禁止されています。 2001 年 5 月 5 日にスタートした日本語化作業には、 さまざまな方々が翻訳に参加されました。 FreeBSD doc-jp では、FreeBSD 関連文書の日本語版を作成する作業を精力的に続けています。 この作業に協力したいと思われる方は、 ぜひFreeBSD 日本語ドキュメンテーションプロジェクトのページをご覧の上 doc-jp へご参加ください。 翻訳者 杉村 貴士 sugimura@jp.FreeBSD.org (2.1, 2.2 節) IKENO Naoki nao@mc.kcom.ne.jp (2.3 節) 田畑 喜晃 ytabata@tkf.att.ne.jp (2.4 節) Atsuto atsuto@guitar.interq.or.jp (2.5 節) はらだきろう kiroh@jp.FreeBSD.org (2.6, 2.7 節) 高田 知樹 tomoki@leergirls.org (2.8 節) 倉品 英行 rushani@bl.mmtr.or.jp (2.9 節) 塩崎 拓也 tshiozak@FreeBSD.org (2.10 節) こが よういちろう y-koga@jp.FreeBSD.org (2.11, 2.13 節) 森 直之 mori@jp.FreeBSD.org (2.12 節) 坂井 順行 sakai@lac.co.jp (2.14 節) 内川 喜章 yoshiaki@kt.rim.or.jp (査読) 日野 浩志 hino@ccm.cl.nec.co.jp (査読) 山口 雅信 yamagu-m@titan.ocn.ne.jp (翻訳提供) diff --git a/ja_JP.eucJP/books/faq/book.sgml b/ja_JP.eucJP/books/faq/book.sgml index 2960070a0a..f53cd8f95b 100644 --- a/ja_JP.eucJP/books/faq/book.sgml +++ b/ja_JP.eucJP/books/faq/book.sgml @@ -1,14980 +1,14964 @@ -%man; - -%freebsd; - - -%ja-authors; - -%authors; - -%teams; - - -%bookinfo; - - -%mailing-lists; - %newsgroups; + +%books.ent; ]> FreeBSD 2.X、3.X、4.X についての FAQ (よくある質問とその答え) FreeBSD ドキュメンテーションプロジェクト $FreeBSD$ 1995 1996 1997 1998 1999 2000 2001 FreeBSD ドキュメンテーションプロジェクト &bookinfo.legalnotice; この文書は FreeBSD システム・バージョン 2.X、3.X、4.X についての FAQ です。 特に断わりがない限り、どの項目も FreeBSD 2.0.5 以降のものを想定しています。 <XXX> のついている項目はまだ作業中のものです。 この FreeBSD ドキュメンテーションプロジェクトに協力したいと思われる方は、 &a.doc; まで (英語で) 電子メールを送ってください。 この文書の最新バージョンは、いつでも 日本国内版 FreeBSD World Wide Web サーバや FreeBSD World Wide Web サーバで 見ることができます。 また、ひとつの巨大な HTML ファイルとして HTTP でダウンロードすることもできます。 プレーンテキスト、PostScript、PDF、およびその他の形式のものは FreeBSD FTP サーバに置かれています。 また、FAQ の検索も可能です。 2000 年 3 月現在、HTML 版以外の日本語 FAQ は用意されていません。 日本語版の作成は FreeBSD 日本語ドキュメンテーションプロジェクトが オリジナルの英語版をもとにして行なっています。 FreeBSD FAQ 日本語訳および、 FreeBSD FAQ 日本語版のみに関連することは、 &a.jp.doc-jp; において日本語で議論されています。 必要に応じて日本語ドキュメンテーションプロジェクトから、 FreeBSD Documentation Project に対してフィードバックを行ないますので、 英語が得意でない方は &a.jp.doc-jp; まで日本語でコメントをお寄せください。 また、この FreeBSD FAQ とは別に、日本の FreeBSD ユーザ有志によって メーリングリスト &a.jp.users-jp; やニュースグループ fj.os.bsd.freebsd などへの投稿をもとに作成された QandA が公開されています。 特に日本語環境など日本固有の話題が充実していますので、 こちらも合わせてご覧ください。 まえがき 訳: &a.kuriyama;、 &a.hanai;、 &a.jp.nakai;、 &a.motoyuki;、 &a.jp.sugimura;、 1997 年 11 月 5 日 FreeBSD 2.X-4.X FAQ へようこそ! Usenet の FAQ がそうであるように、 この文書も FreeBSD オペレーティングシステムに関して 頻繁に尋ねられる質問を網羅することを目的としています (もちろんそれに対する答えも!)。 FAQ は本来バンド幅を減らし、 同じ質問が何度も繰り返されるのを避けるために作られたものですが、 最近は有用な情報源と見なされるようになってきました。 この FAQ をできる限り有用なものにしようと、 あらゆる努力がはらわれています。 もし何かしらの改善案が浮かんだら、ぜひ &a.faq; までメールを送ってください。 FreeBSD って何? FreeBSD とは一言で言えば、カリフォルニア大学バークレイ校から リリースされた 4.4BSD-Lite と 4.4BSD-Lite2 による 強化の一部に由来する、 i386 および Alpha/AXP 系のプラットフォーム向けの UN*X ライクなオペレーティングシステムです。 間接的には同じバークレイ校の Net/2 を William Jolitz が i386 系に移植した 386BSD も基にしていますが、 386BSD のコードはほとんど残っていません。 FreeBSD についての詳細と、何ができるかについては FreeBSD のホームページ を参照してください。 FreeBSD は企業やインターネットサービスプロバイダ、研究者、 コンピュータ専門家、学生、家庭のユーザなどにより、業務や教育、 娯楽に用いられています。これらに関しては FreeBSD ギャラリーをご覧ください。 FreeBSD に関するより詳しい情報は FreeBSD ハンドブックを参照してください。 FreeBSD が目指しているもの FreeBSD プロジェクトの目的は、 いかなる用途にも使用でき、 何ら制限のないソフトウェアを供給することです。 私たちの多くは、 コード (そしてプロジェクト) に対してかなりの投資をしてきており、 これからも多少の代償はあっても投資を続けて行くつもりです。 ただ、他の人達にも同じような負担をするように主張しているわけではありません。 FreeBSD に興味を持っている一人残らずすべての人々に、 目的を限定しないでコードを提供すること。 これが、 私たちの最初のそして最大の「任務」であると信じています。 そうすれば、コードは可能な限り広く使われ、 最大の恩恵をもたらすことができるでしょう。 これが、私たちが熱烈に支持しているフリーソフトウェアの最も基本的な目的であると、 私は信じています。 私たちのソースツリーに含まれるソースのうち、GNU 一般公有使用許諾 (GPL) または GNU ライブラリ 一般公有使用許諾 (GLPL) に従っているものについては、 多少制限が科されています。ただし、 ソースコードへのアクセスの保証という、 一般の制限とはいわば逆の制限です。 ただし GPL ソフトウェアを商用で利用する場合、 さらに複雑になるのは避けられません。 そのため、それらのソフトウェアを、より制限の少ない BSD 著作権に従ったソフトウェアで置き換える努力を、 可能な限り日々続けています。 訳注 GPL では、「ソースコードを実際に受け取るか、 あるいは希望しさえすればそれを入手することが可能であること」を求めています。 どうして FreeBSD と呼ばれているのですか? 無料 (free) で使うことができる (商利用も含む)。 オペレーティングシステムの完全なソースコードが自由 (freely) に手に入り、 商利用・非商利用にかかわらず、最低限の制限で他の仕事への利用、配布、導入が可能。 改良やバグフィックスがある場合、 誰でも (free) そのコードを提出でき、 ソースツリーに加えることができます (いくつかの簡単な条件には従ってもらいます)。 母国語が英語でない読者のために、ここでは free という単語が二つの意味で用いられていることを指摘しておくと分かりやすいかも知れません。 ひとつは「無料である」ということ、 もうひとつは「自分のやりたいようにできる」ということです。 FreeBSD のコードでできないいくつかのこと (自分が書いたものだと偽るなど) を除けば、 あなたは自分のやりたいことをやることが可能なのです。 FreeBSD の最新バージョンは? 4.3 が最新の STABLE バージョンで、 2001 年 4 月にリリースされました。 また、これは最新の RELEASE バージョンでもあります。 簡単に言ってしまうと、-STABLE は最新の -CURRENT のスナップショットのすばらしい新機能の数々よりも、 安定性と変更回数の少なさを好む ISP や、 他の企業のユーザをターゲットにしています。 リリースはこの二種類のブランチで行なわれますが、 (-STABLE と比較すると多少) 不安定な動作があるということを許容できるなら、 必要となるのは -CURRENT の方だけでしょう。 各リリースは 数カ月毎にしか行なわれません。 多くの人々が FreeBSD のソースをそのリリースよりも 最新の状態に維持している (FreeBSD-current と FreeBSD-stable に関する質問も参照してください) のですが、 ソースというのは常に改変され続けているため、 そうすることは一種の慣例になっています。 FreeBSD-CURRENTって何? FreeBSD-CURRENT はオペレーティングシステムの開発バージョンで、 やがて 5.0-RELEASE となります。よってこれは、そこに携わっている開発者や、 どんな障害をも乗り越えていけるタフな愛好家たちにとってのみ興味の対象となるものです。 -CURRENT の使用に際しての詳細は FreeBSD ハンドブック の 関連するセクション を参照してください。 オペレーティングシステムに馴染みがない場合や、 それが一時的に発生している問題なのか、 それとも本質的な問題かを見極める能力がない場合は、 FreeBSD-CURRENT を使うべきではありません。 このブランチは時々急激に拡張されたり、 システムが構築できない状態になることもしょっちゅうあります。 FreeBSD-CURRENT を使う人は問題を分析し、 「小さな欠陥」ではなく、 明らかに間違いであると思われるものだけを報告できるものと想定されています。 「make world したら group 関係でエラーがでました」のような質問は、 -CURRENT メーリングリストでは軽蔑の眼差しであしらわれることもあります。 毎日、その時点の -CURRENT と -STABLE のコードを元に snapshot が作成されています。 現在は、その snapshot の配布も利用可能です。 それぞれの snapshot には以下のような目的があります。 インストールプログラムの最新版のテスト。 試してみたいけれど、 基礎的な所から毎日変わるようなものを追いかける時間もバンド幅も無い、 という人にも -CURRENT や -STABLE を使えるようにする。 また、そのような人たちのシステム移行のための手っ取り早い方法を提供する。 あとでとんでもないことをしてしまった時のために、 問題となるコードの特定の参照基準点を保存しておく。 (通常は CVS がこういうハプニングのような恐ろしい事態を防止して いるんですけどね :) テストが必要な新しい機能を、 できる限り多くの隠れテスターに試してもらう。 どんな目的であれ、-CURRENT snapshot が 製品レベルの品質 であるとの考えに基づく要求は行わないでください。 安定性やテスト十分性にこだわる人は、 完全なリリース、あるいは -STABLE snapshot から離れてはいけません。 スナップショットリリースは、5.0-CURRENT が ftp://current.FreeBSD.org/pub/FreeBSD/ から、4-STABLE が releng4.FreeBSD.org から直接入手可能です。 また、3-STABLE スナップショットは、 この文章の執筆時点 (2000 年 5 月) で作成されていません。 スナップショットリリースは、 現在、開発や保守作業が行なわれているすべてのブランチにおいて、 平均して一日一回作成されます。 FreeBSD-STABLE のコンセプトは何ですか? FreeBSD 2.0.5 がリリースされた後、私たちは FreeBSD の開発を 2 系統に分割することにしました。 一つは -STABLE というブランチで、バグの修正はしっかりテストされ、 機能の強化は少しずつしか行われません (急な変更や実験的機能を望まない、 インターネットサービスプロバイダや営利企業向け)。 もう一方のブランチは -CURRENT で、2.0 がリリースされて以来 5.0-RELEASE (そしてその後も) へ向けて脈々と続いているものです。 ASCII で描いた簡単な図がわかりやすいかは自信がありませんが、 こんな感じになります。 2.0 | | | [2.1-STABLE] *BRANCH* 2.0.5 -> 2.1 -> 2.1.5 -> 2.1.6 -> 2.1.7.1 [2.1-STABLE 終了] | (1997/03) | | | [2.2-STABLE] *BRANCH* 2.2.1 -> 2.2.2-RELEASE -> 2.2.5 -> 2.2.6 -> 2.2.7 -> 2.2.8 [終了] | (1997/03) (1997/10) (1998/04) (1998/07) (1998/12) | | 3.0-SNAPs (1997 年第一四半期開始) | | 3.0-RELEASE (1998/10) | | [3.0-STABLE] *BRANCH* 3.1-RELEASE (1999/02) -> 3.2 -> 3.3 -> 3.4 -> 3.5 -> 3.5.1 | (1999/05) (1999/09) (1999/12) (2000/06) (2000/07) | [4.0-STABLE] *BRANCH* 4.0 (2000/03) ->4.1 -> 4.1.1 -> 4.2 -> 4.3 -> ... 将来の 4.x リリース ... | | (2000/07) (2000/09) (2000/11) | \|/ + [5.0-CURRENT として継続中] -CURRENT ブランチは 5.0 とその先へ向けてゆっくりと進化を続けています。 従来あった 2.2-STABLE ブランチは 2.2.8 のリリースをもって終了しました。 3-STABLE がそれに代わり、2000 年 7 月に 3.5.1-RELEASE (最後の 3.X リリース) がリリースされました。 2000 年 3 月 (3.5 の公開前になりますが) には、 3-STABLE ブランチはほぼ、4-STABLE ブランチによって置き換えられました。 4.3-RELEASE は 2001 年 4 月にリリースされました。 4-STABLE は現在 -STABLE ブランチで活発に開発が続けられていますが、 3-STABLE へのバグの修正 (ほとんどがセキュリティ関連のもの) もまだ行なわれています。 3.X ブランチは 2000 年の夏には公式に開発が終了する予定です。 現在の current branch は 5.0-CURRENT であり、 最初の 5.0 系列のリリース予定はまだ決定していません。 FreeBSD のリリースはいつ作られるのですか? FreeBSD コアチームは原則的に、 新しい機能やバグフィックスが充分集まり、 リリースの安定性を損なうことが無いよう、 さまざまな変更が十分に安定しているという条件を満たしている場合にのみ、 新しいバージョンの FreeBSD をリリースします。 たとえこの用心深さが新しい機能が使えるようになることを 待ち望んでいるユーザを欲求不満にさせるとしても、 多くのユーザはこのことを FreeBSD の最も良い所の一つだと考えています。 リリースの作成は、平均的に言っておよそ 4 ヶ月ごとに行なわれます。 もう少し刺激が欲しい (あるいは待ち遠しい) 方々向けには、 毎日バイナリスナップショットが作成されています。 上記を参照してください。 FreeBSD は PC 用だけしかないの? FreeBSD 3.x 以降は x86 アーキテクチャと同様、 DEC Alpha でも動作します。 また、SPARC、PowerPC、IA64 への移植という興味深い話もあります。 異なるアーキテクチャのマシンを 持っていて、ゆっくり待てないという場合には次の URL を 参照してください。 NetBSD または OpenBSD。 FreeBSD の責任者はいったい誰? プロジェクトの全体的な方向性や、 誰にソースツリーにコードの書き込み権限を与えるか、 などといった FreeBSD プロジェクトに関する重要な意思決定は、 9 名からなるコアチーム (core team) によってなされます。 ソースツリーを直接変更できる人はもっと多く、 200 名以上のソースツリー管理者 (committer) がいます。 しかし、メーリングリストで先行して議論される、 通常の変更ではないものの議論への参加には、一切制限はありません。 どこから FreeBSD を入手できますか? FreeBSD のすべての主要なリリースは anonymous FTP 経由で FreeBSD FTP サイト から入手できます。 現在の 3.X-STABLE リリース、3.5.1-RELEASE は 3.5.1-RELEASE のディレクトリにあります。 現在の 4-STABLE リリース、4.3-RELEASE は 4.3-RELEASE のディレクトリにあります。 4.X Snapshot は、ほぼ一日に一回作成されています。 5.0 Snapshot リリースは -CURRENT ブランチ用に一日に一回作成されており、 これらは純粋に最先端の開発者およびテスターのために提供されています。 また、FreeBSD は CD-ROM でも入手でき、次のところで注文できます。
BSDi 4041 Pike Lane, Suite F Concord, CA 94520 USA Orders: +1 800 786-9907 Questions: +1 925 674-0783 FAX: +1 925 674-0821 email: BSDi Orders address WWW: BSDi Home pageOrders: +1 800 786-9907
オーストラリアでは、次のところに問い合わせてください。
Advanced Multimedia Distributors Factory 1/1 Ovata Drive Tullamarine, Melbourne Victoria Australia Voice: +61 3 9338 6777 CDROM Support BBS 17 Irvine St Peppermint Grove, WA 6011 Voice: +61 9 385-3793 Fax: +61 9 385-2360
イギリスの場合は次のところです。
The Public Domain & Shareware Library Winscombe House, Beacon Rd Crowborough Sussex. TN6 1UL Voice: +44 1892 663-298 Fax: +44 1892 667-473
 FreeBSD のメーリングリストについて知りたいのですが? 完全な情報が FreeBSD ハンドブックのメーリングリストの節 にあります。 FreeBSD の西暦 2000 年問題に関する情報はどこにありますか? 完全な情報が FreeBSD Y2K のページ にあります。 FreeBSD のニュースグループは何がありますか? 完全な情報が FreeBSD ハンドブックのニュースグループの節にあります。 FreeBSD の IRC (Internet Relay Chat) について何か情報はありますか? あります。 以下のように、ほとんどの有名な IRC ネットワークには FreeBSD のチャットチャンネルがあります。 EFNet の Channel #FreeBSD は FreeBSD 関係のフォーラムですが、 そこで技術的サポートを期待してはいけません。 そこにいる人たちはあなたをマニュアルページを読むとか、 研究をするとかといった苦労から遠ざけようとします。 まず第一に、これはチャットチャンネルであり、 そこにあるトピックスは恋人募集、スポーツ、 核兵器といったようなものであり、 FreeBSD も同列に扱われています。 一応注意しましたからね! これは irc.chat.org のサーバー上にあります。 EFNet の Channel #FreeBSDhelp は FreeBSD ユーザのヘルプ専用チャネルです。 参加者は #FreeBSD チャネルよりも親切に質問に答えてくれます。 DALNET の Channel #FreeBSD はアメリカでは irc.dal.net、 ヨーロッパでは irc.eu.dal.net にあります。 UNDERNET の Channel #FreeBSD はアメリカでは us.undernet.org、 ヨーロッパでは eu.undernet.org にあります。 ここはヘルプチャンネルです。 ドキュメントを読める準備をしてから利用してください。 HybNet の Channel #FreeBSD。 このチャンネルはへルプチャンネルです。 サーバーのリストは HybNet のウェブサイト にあります。 それぞれのチャンネルは別個のもので、 互いに接続されていません。 チャットのスタイルも違っていますので、 自分のチャットのスタイルにあったものを見つけるために一つ一つ試すのもいいでしょう。 あらゆる種類の IRC トラフィックのため、失礼なことをいう若者たち (年輩の方は少数です) のために機嫌を損ねたり、 手に負えなくなっても気にしてはいけません。 FreeBSD の本 &a.doc; にコンタクトしてみてください (さらに参加すればもっとよいでしょう)。 このメーリングリストは FreeBSD 関連の文書に関する議論のためのものです。 FreeBSD に関する質問に対しては、 &a.questions; というメーリングリストがあります。 FreeBSD ハンドブックもあります。 これは現在作業中で、 不完全だったり最新情報でないものが含まれていることに注意してください。 FreeBSD のガイド本の決定版は、 Greg Lehey 氏による The Complete FreeBSD です。 これは BSDi (以前の Walnut Creek CDROM) Books から出版されています。 現在は第三版になっていて、 インストール、システム管理ガイド、プログラム設定のヘルプ、 マニュアルページまでの内容が 773 ページにわたって書かれています。 この本は (そして現在の FreeBSD リリースは) BSDi、 CheapBytes、 または最寄りの書店で注文することができます。 ISBN コードは 1-57176-246-9 です (これ以外のコードの場合もあるかもしれません)。 また、FreeBSD は Berkeley 4.4BSD-Lite ベースなので、多くの 4.4BSD のマニュアルが FreeBSD にも応用できます。 O'Reilly and Associates が以下のマニュアルを出版しています。 4.4BSD System Manager's Manual By Computer Systems Research Group, UC Berkeley 1st Edition June 1994, 804 pages ISBN: 1-56592-080-5 4.4BSD User's Reference Manual By Computer Systems Research Group, UC Berkeley 1st Edition June 1994, 905 pages ISBN: 1-56592-075-9 4.4BSD User's Supplementary Documents By Computer Systems Research Group, UC Berkeley 1st Edition July 1994, 712 pages ISBN: 1-56592-076-7 4.4BSD Programmer's Reference Manual By Computer Systems Research Group, UC Berkeley 1st Edition June 1994, 886 pages ISBN: 1-56592-078-3 4.4BSD Programmer's Supplementary Documents By Computer Systems Research Group, UC Berkeley 1st Edition July 1994, 596 pages ISBN: 1-56592-079-1 これらの詳細な説明が WWW 経由で 4.4BSD books description から読むことができます。 販売数が少ないためこれらのマニュアルは入手しにくいかもしれません。 4.4BSD のカーネル構成についてより徹底的に知りたいのなら、 これなら間違いないでしょう。 McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and John Quarterman. The Design and Implementation of the 4.4BSD Operating System. Reading, Mass. : Addison-Wesley, 1996. ISBN: 0-201-54979-4 システム管理について参考になる本は次のものです。 Evi Nemeth, Garth Snyder, Scott Seebass & Trent R. Hein, ``Unix System Administration Handbook'', Prentice-Hall, 2000 ISBN: 0-13-0206016 初版のものではなく、紫色のカバーの第三版であるか 確認してください。 この本は TCP/IP だけでなく DNS、NFS、SLIP/PPP、sendmail、 INN/NNTP、印刷などの基礎を扱っています。 高価ですが、買う価値はあります。 第三版では、Solaris, HP/UX, FreeBSD および Linux を取り扱っています。 障害報告 (PR; Problem Report) データベースにアクセスする方法は? ユーザからの変更要求がまとめられている Problem Report データベースは、 障害報告の web ベースのインタフェースを通して、 提出と問い合わせを行なうことができます。 また、send-pr(1) コマンドを使用して、 電子メール経由で障害報告や変更要求を提出することもできます。 プレインテキスト (ASCII) 版 や PostScript 版の FreeBSD 文書はないのでしょうか? はい、もちろんあります。 数多くの異なるフォーマット、圧縮形式の文書が FreeBSD FTP サイトの /pub/FreeBSD/doc/ というディレクトリから入手可能です。 文書は、次のようなさまざまな観点から分類されています。 faq や handbook といった文書名による分類。 文書の言語とエンコーディングによる分類。これは FreeBSD システムの /usr/share/locale にある locale 名に基づいています。 現在利用可能な言語、エンコーディングは以下のとおりです。 名前 意味 en_US.ISO8859-1 英語 (米国) de_DE.ISO_8859-1 ドイツ語 es_ES.ISO8859-1 スペイン語 fr_FR.ISO8859-1 フランス語 ja_JP.eucJP 日本語 (EUC エンコーディング) ru_RU.KOI8-R ロシア語 (KOI8-R エンコーディング) zh_TW.Big5 中国語 (Big5 エンコーディング) 言語によっては準備されていない文書も存在します。 文書の形式による分類。 文書は数多くの異なる出力形式を用意し、 可能な限り柔軟な対応ができるようにしています。 現在、利用可能な文書形式は以下のとおりです。 文書形式 意味 html-split サイズの小さい、 リンクされた複数の HTML ファイル html 文書全体を含んだ、単一の大きなファイル pdb iSilo で利用可能な Palm Pilot データベース形式 pdf Adobe 社の PDF (Portable Document Format) 形式 ps Postscript 形式 rtf Microsoft 社のリッチテキスト形式 この形式を Word で読み込んだ場合、 ページ番号は自動的に更新されません。 ページ番号を更新するには文書を読み込んでから CTRL+A、 CTRL+END、 F9 を押してください。 txt プレインテキスト形式 圧縮と package 形式による分類。 現在利用されているのは次の 3 種類です。 html-split 形式の場合、 ファイルはまず、&man.tar.1; を使ってまとめられ、 まとめられた .tar ファイルは次に解説する方式で圧縮されます。 その他の形式の場合、ファイルは book.format (たとえば book.pdb、 book.html など) という単一のファイルです。 上にあげたファイルは 3 種類の方式のいずれかで圧縮されます。 方式 説明 zip Zip 形式。 FreeBSD で圧縮を元に戻すには、まず archivers/unzip の port をインストールする必要があります。 gz GNU Zip 形式。圧縮を元に戻すには、 FreeBSD に含まれる &man.gunzip.1; を使います。 bz2 BZip2 形式。 他の形式に比べて普及していませんが、 一般的にファイルサイズが小さくなります。 圧縮を元に戻すには、 archivers/bzip2 port をインストールしてください。 Postscript 版のハンドブックが BZip2 形式で圧縮されている場合、ファイル名は handbook/ ディレクトリの中の book.sgml.bz2 になります。 さまざまな形式に整形された文書は、以下に述べるように FreeBSD の package としても提供されています。 ダウンロードする文書と圧縮形式を選択したら、 文書を FreeBSD package としてダウンロードするかどうか決めなければなりません。 package としてダウンロードしてインストールする場合には、 文書を &man.pkg.add.1; や &man.pkg.delete.1; といった、普通の FreeBSD package 管理システムを用いた管理が可能であるという利点があります。 文書の package をダウンロードしてインストールすることに決めたら、 まずはダウンロードするファイル名を知る必要があります。 文書の package は、packages というディレクトリに置かれています。 そしてそれぞれの package ファイルは、 文書名.言語.エンコーディング.形式.tgz というような名前になっています。 たとえば、FAQ の英語版で PDF 形式のものは、 faq.en_US.ISO8859-1.pdf.tgz というファイル名です。 ファイル名がわかったら、 次のようなコマンドで英語版の PDF 形式 FAQ の package をインストールすることができます。 &prompt.root; pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO8859-1.pdf.tgz インストールの終了後は &man.pkg.info.1; を使い、 ファイルがどこにインストールされたかを調べることができます。 &prompt.root; pkg_info -f faq.en_US.ISO8859-1.pdf Information for faq.en_US.ISO8859-1.pdf: Packing list: Package name: faq.en_US.ISO8859-1.pdf CWD to /usr/share/doc/en_US.ISO8859-1/books/faq File: book.pdf CWD to . File: +COMMENT (ignored) File: +DESC (ignored) ご覧になるとわかるとおり、book.pdf は /usr/share/doc/en_US.ISO8859-1/books/faq にインストールされます。 package を利用しない場合は、 自分で圧縮されたファイルをダウンロードして元に戻し、 適切な場所にそれをコピーする必要があります。 たとえば、分割された HTML 版の FAQ で、 &man.gzip.1; で圧縮されているものは en_US.ISO8859-1/books/faq/book.html-split.tar.gz というファイルです。 これをダウンロードして圧縮を元に戻すには、次のようにする必要があるでしょう。 &prompt.root; fetch ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz &prompt.root; gzip -d book.html-split.tar.gz &prompt.root; tar xvf book.html-split.tar こうすると、複数の .html ファイルが作成されます。 中心となっているのは index.html という名前のファイルで、 目次や前書き、文書の他の部分へのリンクが含まれています。 これらのファイルは、必要に応じて他の場所にコピーしても構いません。 FreeBSD のウェブサイトのミラーサイトになりたいです! 承知しました! ウェブページをミラーするにはいくつかの手段があります。 CVSup を使います。 CVSup を使って CVSup サーバに接続することで、 整形されたファイルを取ってくることができます。 ウェブページを取得する場合は、 /usr/share/examples/cvsup/www-supfile にある supfile の例を参考にしてください。 FTP を使ってミラーリングします。 あなたの好きな FTP ミラーリングツールを使って、 FTP サーバに置いてある web サイトのコピーをダウンロードすることができます。 タウンロードは単純に ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-CURRENT/www から始めてください。 この文書を他の言語に翻訳したいのですが? 報酬は支払えませんが、 文書の翻訳を提出してくださる方には、 フリーの CD、T シャツの手配や、 ハンドブックにある貢献者一覧への登録を行ないたいと思います。 翻訳作業をはじめる前に、 &a.doc; へ連絡するようにお願いします。 翻訳作業を手伝うという人が現われるかも知れませんし。 既に翻訳チームがあって、あなたの参加を歓迎してくれるかも知れません。 その他の情報 以下のニュースグループには FreeBSD ユーザに直接関係のある議論が行われてます。 comp.unix.bsd.freebsd.announce (moderated) comp.unix.bsd.freebsd.misc comp.unix.bsd.misc Web 上のリソース: FreeBSD のホームページ ラップトップ PC を持っている方は、 迷うことなく日本の細川 達己氏の Mobile Computing のページ を見ましょう。 SMP (Symmetric MultiProcessing) に関する情報は、 SMP サポートページをご覧ください。 FreeBSD のマルチメディアアプリケーションに関する情報は、 マルチメディアのページをご覧ください。 特に Bt848 ビデオキャプチャチップに興味のある方は、 リンクをたどってみてください。 FreeBSD ハンドブックには、 実に完成された参考図書の一覧があり、 買うべき本をさがしている方は読む価値があります。 インストール 訳: &a.iwasaki;、 &a.jp.mrt;、 1997 年 11 月 8 日 FreeBSD を入手するには、どのファイルをダウンロードすれば良いのでしょうか? FreeBSD 3.1-RELEASE 以前では、 インストールの際に必要なのは floppies/boot.flp と名前のついた 一つのフロッピーディスクイメージだけでした。 しかし FreeBSD 3.1-RELEASE 以降、 幅広い種類のハードウェアサポートが基本システムに追加され、 そのサポートが必要とする容量を補うため、 3.X と 4.X の系列では新たに、 floppies/kernel.flp および floppies/mfsroot.flp という、二つのフロッピーディスクイメージを使うようになりました。 これらのイメージをフロッピーディスクに書き込むには、 fdimage や &man.dd.1; といったツールが必要となります。 (DOS ファイルシステムからのインストールなどで) あなた自身が手動で配布ファイルをダウンロードする場合には、 以下の配布ファイルをダウンロードすることをおすすめします。 bin/ manpages/ compat*/ doc/ src/ssys.* この手順の完全な説明と、一般的なインストール時の問題については FreeBSD ハンドブックのインストールの節 を参照してください。 ブートフロッピーイメージが一枚のフロッピーディスクに納まらないみたい! 3.5 インチ (1.44MB) のフロッピーディスクには、 1474560 バイトのデータを格納できます。 ブートイメージはちょうど 1474560 バイトの大きさです。 ブートフロッピーディスクを準備する際のよくある間違いには、 以下のものがあります。 FTP によってフロッピーイメージをダウンロードする際に、 バイナリ (binary) モードにしていなかった。 FTP クライアントの中には、 転送モードのデフォルトをアスキー (ascii) モードにして、 クライアント側システムの慣習にあうよう、 すべての行末の文字を変更するものがあります。 この場合は常に、ブートイメージが壊れたものになります。 ダウンロードしたブートイメージのサイズをチェックしてください。 サーバ上のものと正確に一致しなければ、 ダウンロードの処理を疑いましょう。 これを回避するには、 サーバに接続してイメージのダウンロードを開始する前に FTP のコマンドプロンプトで binary とタイプします。 ブートイメージを DOS の copy コマンド (または GUI の同等のツール) でフロッピーディスクへ転送した。 copy のようなプログラムは、 直接起動するように作成されたブートイメージをうまく処理できません。 イメージにはフロッピーディスクの完全な中身がトラック単位で格納されており、 フロッピーディスク上に通常のファイルとして 格納されるように想定されているわけではありません。 FreeBSD のインストールに記述されているように、 低レベルのツール (たとえば fdimage や rawrite) を使用して そのままの (raw) の状態でフロッピーディスクに 転送する必要があります。 FreeBSD のインストールについての説明書はどこにありますか? インストールの説明書はFreeBSD ハンドブックのインストールの章にあります。 FreeBSD を動作させるには何が必要ですか? 386 以上の PC、5MB 以上の RAM、 そして最低 60MB のハードディスク容量が必要となります。 ローエンドの MDA カードでも動作しますが、 X11R6 を使うには VGA かそれ以上のビデオカードが必要となります。 もご覧ください。 4MB しかメモリがないのですが、インストールできますか? 4MB のシステムにインストールできた最後の FreeBSD は FreeBSD 2.1.7 でした。2.2 を含むより新しいバージョンの FreeBSD は新規のインストールに最低 5MB は必要になります。 ただし、インストールプログラムが 4MB では動作しないだけで、 3.0 を含む FreeBSD のすべてのバージョンは 4MB の RAM で動作可能です。 インストールする時だけさらに 4MB 追加しておき、 システムがセットアップされて動作するようになった後、 また 4MB を取り出して元に戻すこともできます。 あるいは 4MB より多くメモリを搭載したシステムにディスクを持っていき、 そのマシンでインストールした後にディスクを戻すこともできます。 また、FreeBSD 2.1.7 であっても、4MB ではインストールできない場合があります。 正確には、640KB のベースメモリ + 3MB の拡張メモリでは、 インストールはできません。もしマシンのマザーボードが 640KB から 1MB の領域で「失われた」メモリを再マップできる場合は、 FreeBSD 2.1.7 をインストールできるかもしれません。 BIOS のセットアップ画面で、remap のオプションを探して有効 (enable) にしてみてください。 また、ROM shadowing を無効 (disable) にする必要もあります。 簡単なやり方としては、インストールする時だけあと 4MB 追加しておく方法があります。 必要なオプションだけを選択してカスタムカーネルを構築し、 また 4MB を取り出してもとに戻せばいいのです。 また、2.0.5 をインストールして、 それから 2.1.7 のインストーラの upgrade オプションでシステムを 2.1.7 へアップグレード するというやり方もあります。 インストールしたあとでカスタムカーネルの構築をした場合には、 4MB でも動作します。 2MB で起動に成功した人もいます (でもそのシステムは、 ほとんど使いものになりませんでした :-))。 自分用のインストールフロッピーを作るには? 現在はカスタムインストールフロッピーディスク「だけ」を作る方法はありません。 カスタムインストールフロッピーディスクイメージを含む、 release 環境全体を新たに作る必要があります。 カスタムの release 環境をつくるには、 ここの指示にしたがってください。 自分の PC に複数のオペレーティングシステムを入れるには? multi-OS のページをご覧ください。 同じマシンで Windows 95/98 と共存できますか? まず Windows 95/98 をインストールしてから、そのあとで FreeBSD をインストールしてください。FreeBSD のブートマネージャが Win95 と FreeBSD のブート管理をしてくれるようになります。 Windows 95/98 を後にインストールした場合はひどいことに、 問い合わせることもなくブートマネージャを上書きしてしまいます。 そうなってしまった場合は次の節をご覧ください。 Windows 95/98 がブートマネージャを潰しちゃった! どうやって戻すの? ブートマネージャの再インストールの方法として、 FreeBSD では以下に示す三通りの方法が用意されています。 DOS を起動し、FreeBSD の配布物の中にある tools/ ディレクトリへ移動し、 bootinst.exe を探してください。 そして次のように実行します。 ...\TOOLS> bootinst.exe boot.bin こうすることで、 ブートマネージャが再インストールされます。 FreeBSD のブートフロッピーディスクから起動し、 「カスタム」インストールメニューを選択し、 続いて「パーティション」を選択します。 ブートマネージャがインストールされていたドライブ (多分最初のもの) を選択し、 パーティションエディタにたどり着いたら、 (何も変更せず) そのまま (W)rite を指定します。 確認のメッセージが出ますので「はい(Y)」と答え、 ブートマネージャ選択の画面で確実に Boot Manager を選択します。 これでブートマネージャがディスクに再び書き込まれます。 インストールメニューから抜けて再起動すると、 ハードディスクは元通りになります。 FreeBSD 起動フロッピー (もしくは CD-ROM) から起動し、 Fixit メニューを選択します。 Fixit フロッピーか CD-ROM #2 (live ファイルシステムオプション) の好きな方を選択して fixit シェルに入ります。 そして、次のコマンドを実行してください。 Fixit# fdisk -B -b /boot/boot0 起動デバイス 起動デバイス の部分は、たとえば ad0 (一番目の IDE ディスク)、 ad4 (セカンダリ IDE コントローラの一番目の IDE ディスク)、 da0 (一番目の SCSI ディスク) などといった、実際の起動デバイスを表しています。 IBM Thinkpad の A、T、X シリーズのいずれかを持っています。 FreeBSD をインストールしたら起動しなくなってしまいました。 どうすればいいですか? これらのマシンに使われている初期のリビジョンの IBM BIOS にはバグがあり、FreeBSD のパーティションをディスクサスペンド用の FAT 領域だと誤認します。 そのため、BIOS が FreeBSD のパーティションを 検出したところでシステムがハング (停止) してしまいます。 IBM これは Keith Frechette kfrechet@us.ibm.com からのメールによります。 によれば、以下のモデル/BIOS リリース番号には修正が含まれています。 モデル BIOS リビジョン番号 T20 IYET49WW 以降 T21 KZET22WW 以降 A20p IVET62WW 以降 A20m IWET54WW 以降 A21p KYET27WW 以降 A21m KXET24WW 以降 A21e KUET30WW それより新しいリビジョンの BIOS にまたバグが入り込んだか もしれないという報告がありました。Jacques Vidrine は mobile@freebsd.org メーリングリストにあてた メッセージ で、これ以降の IBM の laptop で FreeBSD が正常に起動しない 場合におそらくうまく行く、BIOS をアップグレードまたは ダウングレードできる手順を説明しています。 もし問題のある BIOS を使っていてアップグレードが選べない場合、 FreeBSD をインストールしてから FreeBSD が使っているパーティション ID を変更し、 変更されたパーティション ID を正しく扱うことのできる 新しい起動ブロックをインストールすることで解決することができます。 それにはまず、 セルフテスト画面を通過する状態にまでマシンを回復させる必要があります。 そのためには、マシンがプライマリディスクから FreeBSD パーティションを見つけないようにして起動しなければなりません。 たとえば、一度ハードディスクを外してしまって、そのディスクを古い ThinkPad (ThinkPad 600 など) やデスクトップ PC に適切な変換ケーブルで接続します。 その後 FreeBSD のパーティションを削除し、 ハードディスクを元の ThinkPad に戻します。 こうすることで ThinkPad は起動可能な状態に戻るはずです。 マシンがちゃんと動くようになったら、 以下の復旧手順に従って FreeBSD をインストールすることができます。 http://people.freebsd.org/~bmah/ThinkPad/ から boot1 と boot2 をダウンロードします。 これらのファイルは、 あとで必要になった時、取り出せる場所に置いておきます。 ThinkPad に普通に FreeBSD をインストールします。 ただし、Dangerously Dedicated モードを使ってはいけません。 また、インストールが終わっても再起動してはいけません。 緊急ホログラフィックシェル (Emergency Holographic Shell) (ALTF4) に切り替えるか、fixit シェルを起動します。 &man.fdisk.8; を使って FreeBSD のパーティション ID を 165 から 166 に 変更します (これは OpenBSD で使われているものです)。 boot1 と boot2 のファイルをローカルファイルシステムに持って来ます。 &man.disklabel.8; を使って boot1 と boot2 を FreeBSD のスライスに書き込みます。 &prompt.root; disklabel -B -b boot1 -s boot2 ad0sn n は、 あなたが FreeBSD をインストールしたスライスの番号です。 再起動します。起動プロンプトは OpenBSD と示しますが、実際には、それで FreeBSD が起動します。 この方法で FreeBSD と OpenBSD をデュアルブートする方法は、読者への練習問題としましょう。 不良ブロックのあるディスクにインストールできますか? FreeBSD 3.0 以前のシステムでは、 不良ブロックを自動的に再マッピングする bad144 というユーティリティが含まれていましたが、 現在の IDE ドライブはドライブ自身がこの機能を備えているため、 bad144 は FreeBSD ソースツリーから削除されました。 FreeBSD 3.0 かそれ以降をインストールしたいと思っているなら、 比較的新しいディスクドライブを購入することを強くおすすめします。 新しいドライブを購入する気がなければ、FreeBSD 2.x を利用するべきです。 現在の IDE ドライブで不良ブロックによるエラーが発生した場合、 まもなくドライブが故障する可能性があります (それはそのドライブ内蔵の再マッピング機能では 不良ブロックが修正できなくなったということであり、 ディスクがひどく壊れていることを意味します)。 新しいハードディスクドライブに交換しましょう。 不良ブロックのある SCSI ドライブの場合は、 この回答を参照してください。 インストーラから起動したら変なことになりました! インストーラから起動しようとしたときに、マシンが固まってし まうとか自然と再起動してしまうといった現象であれば、 次の三つの項目を確認してください。 新品の、フォーマットしたての、 エラーのないフロッピーディスクを使っていますか? (三年間もベッドの下に放置されていた雑誌の付録みたいなやつではなくて、 買ってきたばかりの新品を使ってください) フロッピーイメージをバイナリモードでダウンロードしましたか? (困った顔をしないでください。私たちの中で一番優秀な人でさえ、 少なくとも一回はバイナリファイルを ASCII モードで思いがけずダウンロードしたことがあるのです!) Windows95 あるいは Windows98 を使用しているなら、 ありのままの本物の DOS で fdimage か rawrite を実行しましたか? これらの OS はディスク作成プログラムのような、 ハードウェアに直接書き込みを行なうプログラムに干渉する可能性があります。 GUI の中の DOS シェル内部で動作している場合でも、 この問題は発生します。 また、Netscape でブートイメージをダウンロードする場合も問題があることが報告されていますので、 できれば別の FTP クライアントを使うのがよいでしょう。 APAPI CD-ROM から起動したのですが、 インストールプログラムは CD-ROM が見つかりませんと言ってきます。 CD-ROM はどこに行ってしまったのでしょうか? この問題は通常、CD-ROM ドライブの設定ミスによって発生します。 大部分の PC の CD-ROM ドライブは、 セカンダリ側の IDE コントローラのスレーブデバイスとして接続され、 マスタデバイスがない状態で出荷されています。 この接続方法は ATAPI 規格違反なので、 Windows は規格どおりに動いたり、動かなかったりしますが、 BIOS は起動時に規格違反を無視します。 そのため BIOS は起動時に CD-ROM を見つけられますが、 FreeBSD は CD-ROM を見つけられず、 インストールを完了できないのです。 CD-ROM が 接続されている IDE コントローラのマスタデバイスとなるように設定するか、 もしくはマスタ、 スレーブの両方にデバイスが接続されているようにシステムを再構成してください。 あれれ? テープからインストールできません! FreeBSD 2.1.7R をテープからインストールする場合、 tar ブロックサイズを 10 (5120 バイト) にしたテープを作る必要があります。 デフォルト の tar ブロックサイズは 20 (10240 バイト) で、 このデフォルトサイズで作られたテープでは FreeBSD 2.1.7R をインストールすることはできません。 もしこうしたテープを使うと、 レコードサイズが大きすぎるというエラーが起きることになります。 PLIP 経由で二つ FreeBSD box を接続したいのですが Laplink パラレルケーブルを用意して、 両方の PC のカーネルに lpt ドライバが組み込まれていることを確認してください。 &prompt.user; dmesg | grep lp lpt0 at 0x378-0x37f irq 7 on isa lpt0: Interrupt-driven port lp0: TCP/IP capable interface パラレルインタフェースに Laplink パラレルケーブルを接続します。 root になって、両方で lp0 のネットワークインタフェースパラメータを設定します。 たとえば、ホスト max と moritz を接続したい場合、 max <-----> moritz IP Address 10.0.0.1 10.0.0.2 max 側で次のようにして、 &prompt.root; ifconfig lp0 10.0.0.1 10.0.0.2 moritz 側で同様に次のようにします。 &prompt.root; ifconfig lp0 10.0.0.2 10.0.0.1 以上です! &man.lp.4; と &man.lpt.4; のマニュアルページも参照してください。 また、 /etc/hosts にホストの追加もしましょう。 127.0.0.1 localhost.my.domain localhost 10.0.0.1 max.my.domain max 10.0.0.2 moritz.my.domain moritz 動作確認は次のようにします。 max 側: &prompt.user; ifconfig lp0 lp0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000 &prompt.user; netstat -r Routing tables Internet: Destination Gateway Flags Refs Use Netif Expire moritz max UH 4 127592 lp0 &prompt.user; ping -c 4 moritz PING moritz (10.0.0.2): 56 data bytes 64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms 64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms 64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms 64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms --- moritz ping statistics --- 4 packets transmitted, 4 packets received, 0% packet loss round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms ラップトップ PC に PLIP 経由でインストールできますか? 次のようにして、二つのコンピュータを Laplink パラレルケーブルで接続してください。 ネットワーク接続用のパラレルケーブルの結線 A-name A 側 B 側 説明 ポート / ビット DATA0 -ERROR 2 15 15 2 Data 0/0x01 1/0x08 DATA1 +SLCT 3 13 13 3 Data 0/0x02 1/0x10 DATA2 +PE 4 12 12 4 Data 0/0x04 1/0x20 DATA3 -ACK 5 10 10 5 Strobe 0/0x08 1/0x40 DATA4 BUSY 6 11 11 6 Data 0/0x10 1/0x80 GND 18-25 18-25 GND -
また、 Mobile Computing についてのページもご覧ください。 ハードディスクドライブには、 どのジオメトリを使うべきでしょうか? ここでディスクの「ジオメトリ」とは、ディスクのシリンダ、ヘッダ、 トラック当りのセクタの数を意味しています - 便宜上、 C/H/S とすることにします。これはディスクのどの領域で読み書きを 行なうかを PC の BIOS が決定する手段となります。 これについてはある理由のために、誤解されている点が多いようです。 まず最初に、FreeBSD はディスクブロックで動作しているため、 SCSI ドライブの物理的なジオメトリという言い方は、 まったく見当違いのものです。事実、 セクタの密度はディスクによってまちまちであるため、 物理的なジオメトリというものは存在しません。 製造者が「本当の」物理的なジオメトリと公表しているものは通常、 彼らが検査して得た最小の使用不可容量の結果のジオメトリのことです。 IDE の場合、FreeBSD は C/H/S で動作しますが、 最近のドライブはすべて、これを内部で参照するブロックに変換しています。 問題はとなるのは論理的なジオメトリです。 これは BIOS がそのディスクのジオメトリについて調べた際に取得されるものであり、 その後のディスクへのアクセスに使用します。 FreeBSD は起動時に BIOS を使用するため、 これを正しく取得することは非常に重要なことなのです。 実際に、ディスク上に複数のオペレーティングシステムがある場合は、 ジオメトリはどこからでも同じように解釈される必要があります。 そうしないと、起動時に深刻な問題が発生します。 SCSI ディスクでは、 使用するジオメトリはコントローラの拡張 BIOS トランスレーション (>1GB の DOS ディスクドライブのサポート とも呼ばれます) が有効になっているかどうかによります。 無効になっている場合、N シリンダ、64 ヘッド、 32 セクタ/トラックを使用しますが、 ここで `N' は MB 単位のディスク容量です。 たとえば、2GB ディスクは見かけ上 2048 シリンダ、64 ヘッド、 32 セクタ/トラックとなります。 それが「有効」になっており (MS-DOS ではこの方法で、ある制限を回避する場合もあります)、 ディスク容量が 1GB を越える場合は、M シリンダ、 63 セクタ/トラック (64 「ではなく」)、 255 ヘッドを使用します。 `M' は MB 単位のディスク容量を 7.844238(!) で割った値となります。 ということで、2GB ディスクの例では、 261 シリンダ、63 セクタ/トラック、255 ヘッドとなります。 (訳注: 以上は Adaptec 社と NCR 社製の SCSI アダプタの場合です。 SCSI アダプタによって変換の数値が変わってくるのでマニュアルを 参照してください)。 これについてよく分からない場合や FreeBSD がインストール中に正しくジオメトリを取得できない場合、 これを回避するもっとも簡単な方法は、 ディスクに小さな DOS パーティションを作ることです。 そうすると正しいジオメトリが取得されるはずです (そして、 残しておきたくないとか、 ネットワークカードのプログラミング用に使いたい場合などには、 いつでもパーティションエディタで DOS パーティションを削除することができます)。 もう一つの方法として、FreeBSD と一緒に配布されているフリーで使えるユーティリティに pfdisk.exe (FreeBSD CD-ROM の tools ディレクトリや、他のさまざまな FTP サイトにあります)と呼ばれるものがあり、 ディスク上の他のオペレーティングシステムが使用している ジオメトリを調べるのに役立ちます。 このジオメトリ情報は、 パーティションエディタに入力することができます。 ディスクの分割の仕方で何か制限はありますか? はい。 BIOS がカーネルを起動できるようにルートパーティションが 1024 シリンダ以内にあることを確認する必要があります (これは FreeBSD ではなく PC の BIOS の制限です)。 SCSI ドライブでは、通常はルートパーティションが最初の 1024MB に収まっていることが前提となります (または拡張 BIOS トランスレーションが有効になっている場合は最初の 4096MB - 他の質問をご覧ください)。IDE でそれに相当する値は 504MB となります (訳注: E-IDE 対応の BIOS 搭載マシンの場合は IDE の 504MB という制限はありません)。 大容量ディスクを持っていますが、ディスクマネージャは使えますか? FreeBSD は Ontrack Disk Manager を認識し、これを考慮にいれます。 他のディスクマネージャはサポートしません。 ディスク全体を FreeBSD で使いたい場合、 ディスクマネージャは必要ありません。 BIOS が扱える容量 (通常 504MB) いっぱいでディスクの設定を行なうと、 FreeBSD は実際の容量を算出するはずです。 MFM コントローラ付きの古いディスクを使っている場合は、 FreeBSD に使用するシリンダ数を詳細に指定する必要があります。 FreeBSD と他のオペレーティングシステムが入っているディスクを使用したい場合は、 ディスクマネージャなしでもできるでしょう。 FreeBSD の起動パーティションと他のオペレーティングシステム用のスライスが、 最初の 1024 シリンダ内に収まっている事を確認するだけです。 気になる方は、起動パーティションを 20 メガバイトぐらいにして大きめにするとよいでしょう。 FreeBSD の起動時に Missing Operating System と表示されます これは FreeBSD や DOS、 そのほかの OS がディスク領域ジオメトリ のとらえ方で衝突しあっていることから起こる典型的な例です。 こうなったら FreeBSD をインストールし直す以外にはありませんが、 他のところで説明した手順にしたがってやれば、 ほぼ間違いなくうまくいくはずです。 ブートマネージャの F? プロンプトが表示されません。 これはすでに前に質問されている問題のもう一つの症状です。 BIOS のジオメトリと FreeBSD のジオメトリ設定が一致していないのです! コントローラや BIOS がシリンダの変換 (>1GB ドライブの サポートとも呼ばれます) をサポートしていたら、 その設定を無効化して FreeBSD をインストールし直してみてください。 ソースを全部インストールする必要はありますか? 一般的には「いいえ」です。 しかし最低でも、base ソースキット (これにはこの FAQ で述べられているファイルのいくつかが含まれています) と、 sys (kernel) ソースキット (これにはカーネルのソースが含まれています) をインストールする事を強くおすすめします。 通常、何かの実行にソースが必要になる事はありません。 しかし、カーネルをコンフィグレーションするためのプログラム &man.config.8; を実行する時は例外です。 カーネルのソースをインストールしなくてもよい例として、 どこか別の場所からカーネルのソースを読み込み専用で NFS マウントすることができます。また、 そこから新しいバイナリを作成できるようにもなっています (カーネルソースの制限があるので、直接 /usr/src をマウントする事はおすすめできません。 それよりもどこか別のディレクトリにマウントして、 ソースツリーの複製ができるように適切にシンボリックリンクを張ってください)。 ソースをネットワーク上に持ち、 そこからシステムをビルドするようにしておけば、 FreeBSD の将来のリリースへのアップグレードがずっと簡単になります。 実際にソースのサブセットを選択するには、 システムインストールツールの「配布ファイル」メニューにある、 「カスタム」メニューを使用します。 カーネルは必ず作り直さなくちゃならないんですか? カーネルを新しく作り直すのは元々、 FreeBSD のインストール時に必須の作業でした。 でも最近のリリースでは、 とてもユーザフレンドリなカーネル設定ツールの恩恵を受けています。 FreeBSD の起動プロンプト (boot:) で とタイプすればビジュアルな設定画面になり、 ほとんどの一般的な ISA カードについてのカーネルの設定をすることができるのです。 今でも、 必要なデバイスドライバだけを組み込んだカーネルを作ることはよい事とされています。 ほんのちょっとだけメモリを節約できますからね。 でもほとんどのシステムでは、 もはやどうしてもやらなくちゃならないことではないのです。 DES と MD5、どちらのパスワードを使うべきなのでしょうか? また、ユーザがどちらを使うことになるか指定する方法はありますか? FreeBSD の標準のパスワードフォーマットは MD5 を使ったものです。 これは DES アルゴリズムに基づいた手法を用いる UNIX の伝統的なパスワードフォーマットより安全 (secure) だと 信じられているものです。 DES パスワードは あなたが FreeBSD のパスワードファイルを、 安全性に劣るパスワードフォーマットを利用している古い OS と共有しなければならなくなったときのために 利用可能になっています (これは利用するためには、 sysinstall から crypto 配布物のインストール 選ぶか、ソースから build しているなら、 crypto のソースがインストールされている必要があります)。 新しいパスワードにどちらのパスワードフォーマットを使うかは /etc/login.conf の中の passwd_format という login ケーパビリティで制御されます。このケーパビリティは des (利用できるなら) か md5 のどちらかの値を取ります。 login ケーパビリティの詳細については login.conf(5) を 参照してください。 ブートフロッピーで起動すると、 Probing Devices... の画面でハングアップします。 IDE Zip か Jaz ドライブが接続されていたら、 それを取り外してもう一度試してみましょう。 ブートフロッピーはこの種のドライブを誤認してしまうのです。 システムがインストールされた後は、そのドライブを再度接続することができます。 うまくいけばこの問題は将来のリリースで解決されるでしょう。 インストール終了後にシステムを再起動すると、 panic: cant mount root のエラーとなります。 このエラーはディスクデバイスについて、 起動ブロックとカーネルの認識が混乱しているために起こります。 このエラーは通常、 2 台の IDE ディスクがそれぞれ別の IDE コントローラのマスターに一つずつ接続されているシステムにおいて、 FreeBSD がセカンダリ IDE コントローラに接続されたディスクにインストールされている場合に発生します。 起動ブロックは FreeBSD が wd1 (2 台目の BIOS ディスク) にインストール されていると認識するのに対し、 カーネルはセカンダリ IDE の 1 台目のハードディスクである wd2 にインストールされていると認識するのです。 デバイス検出後で、 カーネルは起動ブロックが起動ディスクだと認識したディスクである wd1 をマウントしようとします。 しかし、実際には起動ディスクは wd2 なので失敗してしまうのです。 この問題を解決するには、以下のどれか一つを行ってください。 FreeBSD 3.3 以降を利用している場合には、 システムを再起動して、Booting kernel in 10 seconds; hit [Enter] to interrupt が表示されている間に Enter キーを押します。 すると、ブートローダに移行します。 そうしたら、set root_disk_unit="disk_number" と入力します。 FreeBSD が最初の IDE コントローラのマスターに接続されたドライブにインストールされていれば、 disk_number は 0 です。 また、 最初の IDE コントローラのスレーブなら 1、 二番目の IDE コントローラのマスターなら 2、 二番目の IDE コントローラのスレーブなら 3 になります。 その後、boot と入力します。 システムはきちんと再起動するはずです。 この変更を恒久的なものにする (つまり、 再起動や電源を入れる度にこの操作する必要がないようにする) には、 /boot/loader.conf.local に root_disk_unit="disk_number" という行を追加してください。 FreeBSD 3.2 以前を利用している場合は、 Boot: プロンプトで 1:wd(2,a)kernel と入力してエンターキーを押します。 システムが起動したら、 echo "1:wd(2,a)kernel" > /boot.config というコマンドを実行してこれをデフォルトのブート文字列とします。 FreeBSD のディスクをプライマリ IDE コントローラに接続して、 ハードディスクが連続したドライブ番号で認識されるようにします。 カーネルのコンフィグレーションファイルで wd の行を以下のように変更し、 カーネルの再構築を行って、 新しいカーネルをインストールします。 controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr disk wd0 at wdc0 drive 0 # disk wd1 at wdc0 drive 1 # この行をコメントアウト controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr disk wd1 at wdc1 drive 0 # wd2 から wd1 へ変更 disk wd2 at wdc1 drive 1 # wd3 から wd2 へ変更 ディスクの接続を変更して元の設定に戻したい場合は、ディスクを お望みの設定の通りの接続に戻してから再起動します。 システムは正常に起動するはずです。 メモリの大きさの制限は? 認識できるメモリの上限は、4GB です。 この構成は試験済みで、 詳細は wcarchive's configuration をご覧ください。 このようにたくさんのメモリをマシンに導入しようという場合には、 注意が必要です。ECC 機能をサポートし、なおかつ 容量性負荷 (訳注: 多くのメモリ素子は容量性負荷として働きますが、 メモリバス上に容量性負荷が増えると信号の伝達が遅れ、誤動作の原因となります) を 低減させるため、18 チップ構成のメモリモジュールより 9 チップ構成のメモリモジュールを選択することが、おそらく望ましいでしょう。 ffs ファイルシステムの大きさの制限は? ffs ファイルシステムの場合、 論理的な最大の上限は 8 TB (2G ブロック)、 デフォルトのブロックサイズを 8K とすると 16 TBとなります。 実際問題として、1 TB のソフトウェアの限界がありますが、 修正すれば 4 TB のファイルシステムが可能です (実際に存在します)。 一つの ffs のファイルの最大のサイズは、ブロックサイズが 4K の場合で 約 1G ブロック (4 TB)です。 最大ファイルサイズ fs ブロックサイズ 2.2.7-stable 3.0-current 動作確認済みのサイズ 動作するはずのサイズ 4K 4T-1 4T-1 4T-1 4+t 8K 32+G 8T-1 32+G 32T-1 16K 128+G 16T-1 128+G 32T-1 32K 512+G 32T-1 512+G 64T-1 64K 2048+G 64T-1 2048+G 128T-1
fs ブロックサイズが 4K の場合は三重間接ブロックが使用され、 いずれの場合でも三重間接ブロックを使用して表現できる最大の fs ブロック番号 (およそ 1K^3 + 1K^2 + 1K) に制限されるはずなのですが、 実際は fs ブロック番号の (間違った) 上限 1G-1 で制限されます。 fs ブロック番号の制限は 2G-1 となるはずです。2G-1 付近に fs ブロック番号のバグが多少ありますが、fs ブロックサイズが 4K の場合は、ここまでのブロック番号には到達しません。 ブロックサイズが 8K 以上の場合、いずれの場合も fs ブロック番号の上限 2G-1 で制限されるはずですが、 実際は fs ブロック番号の上限 1G-1 で制限されます。 例外的に -STABLE では三重間接ブロックまでは到達しないため、 制限は二重間接ブロックで表現できる最大の fs ブロック番号 (およそ (blocksize/4)^2 + (blocksize/4)) となります。 -CURRENT ではこの制限を超えると問題を引き起こすかもしれません。 正しい制限値である 2G-1 ブロックを使用すると明らかに問題が出ます。 フロッピーに 1 TB のファイルを格納するには? 寄稿: Bruce Evans、1998 年 9 月 わたしのところでは、 フロッピーにいくつかの実際のファイルを保存しています :-)。 最大のファイルサイズは最大のディスクサイズとはあまり関係はありません。 最大のディスクサイズは 1 TB です。 ファイルサイズがディスクサイズより大きくなりうるというのは仕様です。 以下の例は、32K のディスク容量 (3 つの間接ブロックと 1 つのデータブロック) を使って、 小さなルートパーティションに 8T-1 の大きさのファイルを作成します。 ここでの dd コマンドは大きなファイルが扱えるものが必要です。 &prompt.user; cat foo df . dd if=/dev/zero of=z bs=1 seek=`echo 2^43 - 2 | bc` count=1 ls -l z du z df . &prompt.user; sh foo Filesystem 1024-blocks Used Avail Capacity Mounted on /dev/da0a 64479 27702 31619 47% / 1+0 records in 1+0 records out 1 bytes transferred in 0.000187 secs (5346 bytes/sec) -rw-r--r-- 1 bde bin 8796093022207 Sep 7 16:04 z 32 z Filesystem 1024-blocks Used Avail Capacity Mounted on /dev/da0a 64479 27734 31587 47% / 新しいカーネルをコンパイルしたら、起動時に archsw.readin.failed というエラーメッセージが表示されるようになってしまいました。 ローダがスタートする前の | が表示されているときに何かキーを押すことで、 起動のセカンドステージから直接、起動するカーネルを指定して起動することができます。 特に、カーネルのソースを更新し、make world しないで新しいカーネルだけインストールした場合にこの症状が現われます。 こういう操作は動作が保証されません。きちんと make world してください。 3.X から 4.X にアップグレードするにはどうしたら良いのですか? アップグレードには、 バイナリスナップショットを使うことを強くおすすめします。 4-STABLE スナップショットは releng4.FreeBSD.org から入手可能です。 ソースを使ってアップグレードする場合は、詳細について FreeBSD ハンドブックを参照するようにしてください。 ソースを使ったアップグレードは、 慣れていないユーザにはまったくおすすめできません。 3.X -> 4.X の場合は特にそうです。 ソースを使ったアップグレードを試す前に、 手順を注意深く読むように心がけてください。 セキュリティプロファイル (security profiles) とは何ですか? セキュリティプロファイルとは、特定の プログラムやその他の設定を有効にしたり無効にすることで、求める 比率で安全と便利さを実現しようとする構成の選択肢の集まりの ことです。セキュリティプロファイルが厳しいほど、デフォルトで 有効になるプログラムが減ります。これは、動かさなければならない もの以外は、何も動かしてはいけないというセキュリティの 基本的原則の一つです。 セキュリティプロファイルは、単にデフォルトの設定である ということに気をつけてください。FreeBSD をインストールした あとに /etc/rc.conf に適切な行を編集したり 追加すれば、どのプログラムでも有効にしたり無効にしたりできます。 後者について詳しいことは &man.rc.conf.5; のマニュアルを ご覧ください。 以下に、各セキュリティプロファイルが何を行うかを説明した 表を掲載します。列はセキュリティプロファイルの選択肢で、行は 有効または無効になるプログラムや機能です。 指定できるセキュリティプロファイル Extreme High Moderate Low &man.inetd.8; NO NO YES YES &man.sendmail.8; NO YES YES YES &man.sshd.8; NO YES YES YES &man.portmap.8; NO NO おそらく インストール時に、すでにマシンを NFS クライアントまたはサーバとして設定していると、 ポートマッパが有効になります。 YES NFS server NO NO YES YES &man.securelevel.8; YES (2) securelevel を設定するセキュリティプロファイル (Extreme または High) を選択する場合、その影響を 承知していなければなりません。&man.init.8; のマニュアルを 読み、セキュリティレベルの意味について特に注意を 払ってください。そうしないと、後で深刻な問題が 起きるかもしれません。 YES (1) NO NO
セキュリティプロファイルは魔法の薬ではありません。 High に設定したら、適当な メーリングリストを読んだり、良質なパスワードや パスフレーズを用いたり、セキュリティについてのよい習慣を 守ったりしなくていいわけではありません。求めるセキュリティと 便利さの比率を手軽に設定してくれるだけです。 セキュリティプロファイルの機構は、FreeBSD を最初に インストールする時に使うことを想定しています。すでに FreeBSD がインストールされているなら、単に求める機能を 有効にしたり無効にしたりする方が、おそらく効率が よいでしょう。もし、本当にセキュリティプロファイルを 使いたいのであれば、&man.sysinstall.8; を再実行すれば 設定できます。 ハードウェアコンパチビリティ 訳: にしか nishika@cheerful.com、 1997 年 11 月 12 日 FreeBSD は、 どんなハードディスクドライブをサポートしているのですか? FreeBSD は、EIDE と SCSI ハードディスクドライブをサポートしています (互換コントローラも含みます。 次の節参照)。 また独自の Western Digital インタフェースを使用しているすべてのドライブ (MFM、 RLL、ESDI、もちろん IDE) もサポートしています。 独自仕様のインタフェースを使用する ESDI コントローラでは動作しないものがあり、 WD1002/3/6/7 とその互換インタフェースと衝突します。 どの SCSI コントローラをサポートしているのですか? FreeBSD ハンドブックに記されている完全なリストを参照してください。 どんな CD-ROM ドライブをサポートしているのですか? サポートされている SCSI コントローラに接続できる SCSI ドライブは、すべてサポートされています。 また、以下の専用 CD-ROM インタフェースもサポートしています。 ミツミ LU002 (8bit)、LU005 (16bit) および FX001D (16bit 2倍速)。 ソニー CDU 31/33A Sound Blaster 非 SCSI タイプの CD-ROM 松下/Panasonic CD-ROM ATAPI 互換の IDE CD-ROM SCSI でないカードはすべて、SCSI ドライブよりも極めて動作速度が 遅いことが知られており、ATAPI CD-ROM には動作しないものもあるようです。 BSDi の FreeBSD 2.2 CD-ROM からは CD からの直接起動が サポートされています。 FreeBSD は、どの CD-RW ドライブに対応していますか? FreeBSD は ATAPI 互換の IDE CD-R または CD-RW ドライブで あれば対応しています。FreeBSD バージョン 4.0 以降については、 &man.burncd.8; のマニュアルをご覧ください。それ以前の バージョンの FreeBSD では、 /usr/share/examples/atapi にある例を ご覧ください。 また、FreeBSD は SCSI の CD-R または CD-RW ドライブにも 対応しています。ports または packages から cdrecord コマンドをインストールして、 カーネルに pass デバイスが組み込まれて いることを確認してください。 ZIP ドライブをサポートしていますか? もちろん、 FreeBSD は SCSI ZIP ドライブ (外付け) をサポートしています。 ZIP ドライブは SCSI ID を 5 か 6 に設定した状態でなら使用できますが、 もし SCSI ホストアダプタの BIOS がサポートしてさえいれば ZIP ドライブから起動させることもできます。 どのホストアダプタが SCSI ID を 0 や 1 以外に設定したデバイスから 起動できるのかはわかりません。そうしたい場合は、アダプタの ドキュメントを参照しなければなりません。 ATAPI (IDE) ZIP ドライブは、FreeBSD 2.2.6 以降のバージョンでサポートされています。 バージョン 3.0 以降の FreeBSD では、 パラレルポート接続の ZIP ドライブをサポートしています。 最近のバージョンの FreeBSD をお使いでしたら、 カーネルコンフィグレーションファイルに scbus0、 da0、 ppbus0、 vp0 の各ドライバが記述されていることを確認してください。 (GENERIC カーネルには vp0 を除くすべてのドライバが含まれています)。 これらすべてのドライバがあれば、 パラレルポートのドライブは /dev/da0s4 となります。 ディスクは mount /dev/da0s4 /mnt とするか mount_msdos /dev/da0s4 /mnt (DOS ディスクの場合) とすることでマウントできます。 それからリムーバブルドライブに関する注意および、 「フォーマット」に関する注意についても 確認しておいてください。 では、JAZ や EZ、 それからその他のリムーバブルドライブはサポートしていますか? FreeBSD では、IDE バージョンの EZ ドライブを除くすべての SCSI デバイスは、 SCSI のディスクと同等に扱われます。 また IDE EZ は IDE ドライブと同等となります。 システム稼働中のメディア交換について FreeBSD がどれほどうまく動くか定かではありません。 もちろんメディアを入れ替える前にそのドライブのマウントを解除しなければいけないでしょうし、 FreeBSD がそれらを認識するには、 起動時に外部ユニットにも電源が投入されていることを確認しなければいけないでしょう。 「フォーマット」に関する注意も参照のこと。 どのマルチポートシリアルカードをサポートしていますか? 一覧は その他のデバイスの節にあります。 無名のカードにもうまく動くものがあり、 特に AST 互換といわれているものに多く見られます。 カード設定の詳細な情報は、&man.sio.4; のマニュアルページを参照してください。 USB キーボードを持っているのですが、FreeBSD で使えますか? USB デバイスは FreeBSD 3.1 からサポートされましたが、 実装は FreeBSD 3.2 であってもまだ完全ではないため、 必ずしも安定して動作するとは限りません。 もし、それでも USB キーボードを使ってみたいという人は、 以下の手順を試してみてください。 FreeBSD 3.2 か、それ以降を使います。 カーネルコンフィグレーションファイルに以下の行を追加し、 カーネルを再構築します。 device uhci device ohci device usb device ukbd options KBD_INSTALL_CDEV FreeBSD 4.0 より前のバージョンでは、 代わりに次のようにします。 controller uhci0 controller ohci0 controller usb0 controller ukbd0 options KBD_INSTALL_CDEV /dev ディレクトリに移動し、 次のようにしてデバイスノードを作成します。 &prompt.root; cd /dev &prompt.root; ./MAKEDEV kbd0 kbd1 /etc/rc.conf を編集し、 以下の行を追加します。 usbd_enable="YES" usbd_flags="" システムを再起動させた後、 AT、USB 両方のキーボードが接続されていれば、 AT キーボードは /dev/kbd0 に、 USB キーボードは /dev/kbd1になります。 一方、USB キーボードだけが接続されているなら、 /dev/ukbd0 となります。 USB キーボードをコンソールで利用するには、 それをコンソールドライバに対して明示的に指定する必要があります。 システムの初期化の際に、次に示すようなコマンドを実行してください。 &prompt.root; kbdcontrol -k /dev/kbd1 < /dev/ttyv0 > /dev/null ただし、USB キーボードしか接続されていない場合、それは /dev/kbd0 としてアクセスされますので、 コマンドは次のようにしなければなりません。ご注意ください。 &prompt.root; kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null 上のコマンドは、/etc/rc.i386 に追加すると良いでしょう。 この設定を一度行なっていれば、 X 環境でも特に他の設定なしに USB キーボードが利用できます。 USB キーボードの活線挿抜 (ホットプラグ機能) は、 まだおそらくきちんと動作しないと思われます。 トラブルを避けるためにも、キーボードはシステムを起動させる前に接続しておき、 シャットダウンするまではずさないようにした方が良いでしょう。 詳細については、&man.ukbd.4; のマニュアルページを参照してください。 珍しいバスマウスを持っているのですが、どのように設定すればいいのですか? FreeBSD は Microsoft、Logitech、 ATI 等のメーカーから出ているバスマウスと InPort バスマウスをサポートしています。FreeBSD 2.X の場合、 バスマウスのデバイスドライバは GENERIC カーネルに標準で含まれますが、 FreeBSD 3.X 以降では標準で含まれていません。もしバスマウスのデバイス ドライバを含むカーネルを自分で構築する場合には、 カーネルコンフィグレーションファイルに以下の行が含まれていることを確認してください。 それは FreeBSD 3.0 を含む、それ以前のリリースの場合は次のとおり、 device mse0 at isa? port 0x23c tty irq5 vector mseintr FreeBSD 3.X では、次のとおりです。 device mse0 at isa? port 0x23c tty irq5 そして FreeBSD 4.X とそれ以降では、次のようになります。 device mse0 at isa? port 0x23c irq5 通常バスマウスには専用のインタフェースカードが附属しています。 インタフェースカードによってはポートアドレスや割り込み番号を上記の 設定以外に変更できるかもしれません。詳しくはバスマウスのマニュアルと &man.mse.4; のマニュアルページを参照してください。 PS/2 マウス (「マウスポートマウス」、「キーボードマウス」) を 使うにはどのように設定すればいいのですか? あなたが 2.2.5 以降のバージョン FreeBSD を使っているのなら、 必要なドライバ psm はカーネルに含まれていて有効になっています。 カーネルは起動時に PS/2 マウスを検出するでしょう。 あなたの使っている FreeBSD が比較的新しいけれど前のバージョン (2.1.x 以降) のものなら、 インストールの時に、単にカーネルのコンフィグレーションのメニュー上で PS/2 マウスを有効化するだけです、あるいは後で boot: プロンプト上で を指定することでもメニューは現れます。 デフォルトでは無効に設定されていますので、 明示的に有効化してあげないといけません。 あなたの使っている FreeBSD が比較的古いものなら、 カーネルコンフィグレーションファイルに以下の行を加えて カーネルを再コンパイルする必要があります。 それは FreeBSD 3.0 を含む、それ以前のリリースでは次のとおり、 device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr FreeBSD 3.1 を含む、それ以降のリリースでは次のとおり、 device psm0 at isa? tty irq 12 FreeBSD 4.0 とそれ以降のリリースでは次のとおりです。 device psm0 at atkbdc? irq 12 カーネルの再構築についてよく知らないのであれば、 カーネルのコンフィグレーションを参照してください。 起動時にカーネルが psm0 を検出したら、 psm0 のエントリが /dev の中にあることを確認してください。それには、以下のようにします。 &prompt.root; cd /dev; sh MAKEDEV psm0 これは root でログインしているときに行なってください。 X Window System 以外の環境でマウスを使うことは可能ですか? もしデフォルトのコンソールドライバである syscons を使っているのであれば、 テキストコンソール上でマウスを使って、 テキストのカットアンドペーストができます。 マウスデーモンである moused を起動し、 仮想コンソールでマウスポインタを有効にしてください。 &prompt.root; moused -p /dev/xxxx -t yyyy &prompt.root; vidcontrol -m on ここで xxxx はマウスのデバイス名、 yyyy はマウスのプロトコルタイプです。 サポートされているプロトコルタイプについては &man.moused.8; のマニュアルページを参照してください。 システムを起動する時に自動的に moused を起動したい場合には、次のようにします。 FreeBSD 2.2.1 では以下の変数を /etc/sysconfig で設定してください。 mousedtype="yyyy" mousedport="xxxx" mousedflags="" FreeBSD 2.2.2 以降のバージョンでは /etc/rc.conf で以下のように設定します。 moused_type="yyyy" moused_port="xxxx" moused_flags="" FreeBSD 3.1 とそれ以降で PS/2 マウスを利用する場合は、 moused_enable="YES" を /etc/rc.conf に書き加えるだけです。 また、起動時にすべての仮想端末で、 標準のコンソールに加えマウスデーモンも使えるようにしたい、 という場合には、以下の行を /etc/rc.conf に加えます。 allscreens_flags="-m on" FreeBSD 2.2.6 以降の場合で 比較的新しいシリアルマウスを使っているならば、 マウスデーモンはマウスのプロトコルタイプを自動判別できます。 自動判別を試みるには、プロトコルタイプとして auto を指定します。 マウスデーモンを実行中は、マウスデーモンと他のプログラム (たとえば X Window System) の間でマウスへのアクセスを調整しなければなりません。 この問題については X とマウスをご覧ください。 マウスを使って、 テキストコンソールでカットアンドペーストするにはどうしたらよいのですか? マウスデーモンを起動 (前の質問に対する答えを参照してください) したあと、 ボタン 1 (左ボタン) を押しながらマウスを動かして範囲を指定します。 ボタン 2 (中ボタン) またはボタン 3 (右ボタン) をクリックするとテキスト カーソルの位置に選択した範囲のテキストがペーストされます。 FreeBSD 2.2.6 以降では、ボタン 2 をクリックするとペーストされ、ボタン 3 をクリックした場合に既存の選択範囲が現在のマウスポインタの位置まで 「延長または短縮」されます。もしマウスに中ボタンがないなら、 moused のオプションを使って中ボタンのエミュレーションをするか、 他のボタンを中ボタンとして使う事ができます。 詳しくは &man.moused.8; のマニュアルページを参照してください。 USB マウスを持っているのですが、FreeBSD で使えますか? USB デバイスは FreeBSD 3.1 からサポートされましたが、 実装は FreeBSD 3.2 であってもまだ完全ではないため、 必ずしも安定して動作するとは限りません。 もし、それでも USB マウスを使ってみたいという人は、 以下の手順を試してみてください。 FreeBSD 3.2 か、それ以降を使います。 カーネルコンフィグレーションファイルに以下の行を追加し、 カーネルを再構築します。 device uhci device ohci device usb device ums FreeBSD 4.0 より前のバージョンでは、 代わりに次のようにします。 controller uhci0 controller ohci0 controller usb0 device ums0 /dev ディレクトリに移動し、 次のようにしてデバイスノードを作成します。 &prompt.root; cd /dev &prompt.root; ./MAKEDEV ums0 /etc/rc.conf を編集し、 以下の行を追加します。 moused_enable="YES" moused_type="auto" moused_port="/dev/ums0" moused_flags="" usbd_enable="YES" usbd_flags="" moused の設定の詳細については、 前項も参照してください。 X のセッションで USB マウスを使うには、 XF86Config を編集する必要があります。 XFree86 3.3.2、もしくはそれ以降を利用している場合は、 Pointer セクションが次のようになっていることを確認してください。 Device "/dev/sysmouse" Protocol "Auto" それより前のバージョンの XFree86 を利用している場合は、 Pointer セクションが次のようになっていることを確認してください。 Device "/dev/sysmouse" Protocol "SysMouse" X 環境でのマウスの利用については、 他の項も参照してください。 USB マウスの活線挿抜 (ホットプラグ機能) は、 まだおそらくきちんと動作しないと思われます。 トラブルを避けるためにも、マウスはシステムを起動させる前に接続しておき、 シャットダウンするまではずさないようにした方が良いでしょう。 わたしのマウスにはホイール機能や便利なボタンがついているのですが、 これは FreeBSD でも使えるのですか? 答えは残念ながら「場合によります」です。 こうしたマウスの付加的な機能は大抵の場合、特殊なドライバを必要とします。 マウスのデバイスドライバやユーザのプログラムが そのマウスに対する固有のサポートをしていない場合には、 標準的な 2 ボタン/3 ボタンマウスのように振舞います。 X ウィンドウシステムの環境でのホイールの使い方については、 X とホイールの項をご覧ください。 わたしのマウスはきちんと動いてくれないようです。 マウスカーソルが画面中をとびまわります。 このマウスにはホイールがついていて、 接続は PS/2 ポートです。 FreeBSD 3.2 およびそれ以前の PS/2 マウスドライバ psm には、 Logitech モデル M-S48 とその OEM のホイールマウスで不具合が発生します。 以下のパッチを /sys/i386/isa/psm.c に適用して、カーネルを再構築してください。 Index: psm.c =================================================================== RCS file: /src/CVS/src/sys/i386/isa/Attic/psm.c,v retrieving revision 1.60.2.1 retrieving revision 1.60.2.2 diff -u -r1.60.2.1 -r1.60.2.2 --- psm.c 1999/06/03 12:41:13 1.60.2.1 +++ psm.c 1999/07/12 13:40:52 1.60.2.2 @@ -959,14 +959,28 @@ sc->mode.packetsize = vendortype[i].packetsize; /* set mouse parameters */ +#if 0 + /* + * A version of Logitech FirstMouse+ won't report wheel movement, + * if SET_DEFAULTS is sent... Don't use this command. + * This fix was found by Takashi Nishida. + */ i = send_aux_command(sc->kbdc, PSMC_SET_DEFAULTS); if (verbose >= 2) printf("psm%d: SET_DEFAULTS return code:%04x\n", unit, i); +#endif if (sc->config & PSM_CONFIG_RESOLUTION) { sc->mode.resolution = set_mouse_resolution(sc->kbdc, - (sc->config & PSM_CONFIG_RESOLUTION) - 1); + (sc->config & PSM_CONFIG_RESOLUTION) - 1); + } else if (sc->mode.resolution >= 0) { + sc->mode.resolution + = set_mouse_resolution(sc->kbdc, sc->dflt_mode.resolution); + } + if (sc->mode.rate > 0) { + sc->mode.rate = set_mouse_sampling_rate(sc->kbdc, sc->dflt_mode.rate); } + set_mouse_scaling(sc->kbdc, 1); /* request a data packet and extract sync. bits */ if (get_mouse_status(sc->kbdc, stat, 1, 3) < 3) { FreeBSD 3.2 より新しいリリースではきちんと動作するはずです。 ラップトップ PC のマウス/トラックボール/タッチパッドは使えますか? 前の質問に対する答えと、 モバイルコンピューティングのページをご覧ください。 どんなテープドライブをサポートしていますか? FreeBSD は SCSI と QIC-36 (QIC-02 インタフェース付き) をサポートしています。 これらには 8-mm (Exabyte と呼ばれています) や DAT ドライブも含まれています。 初期の 8-mm ドライブの中には SCSI-2 とまったく互換性を持たないものがあります。 これらは FreeBSD 上では動作しません。 どんなテープチェンジャーをサポートしていますか? FreeBSD 2.2 は &man.ch.4; デバイスと &man.chio.1; コマンドを使用した SCSI チェンジャーをサポートしています。 実際のチェンジャーの制御方法の詳細は、&man.chio.1; のマニュアルページを参照してください。 使用している製品が AMANDA のようにチェンジャーに対応済みのものでない場合は、 次のことについて留意してください。 それらの製品は任意のポイント間のテープの移動を制御するだけなので、 テープがどのスロットに入っているか、現在ドライブにあるテープが どのスロットに戻るべきかを把握しておく必要があります。 どんなサウンドカードをサポートしていますか? FreeBSD は SoundBlaster、SoundBlaster Pro、SoundBlaster 16、 Pro Audio Spectrum 16、AdLib それから Gravis UltraSound サウンドカードを サポートしています。MPU-401 やその互換カードも機能に制限はあるものの サポートされています。マイクロソフトサウンドシステムのスペックに準拠 したカードも、pcm ドライバでサポートされています。 これらはサウンドについてのみの話です! これらのドライバは CD-ROM、SCSI、カード上にあるジョイスティックをサポートしていません (SoundBlaster は例外です)。SoundBlaster SCSI インタフェースと非 SCSI CD-ROM はサポートしていますが、そのデバイスからは起動できません。 pcm ドライバで es1370 から音が出ないのはどうにかなりませんか? マシンを起動するごとに以下のコマンドを実行してください。 &prompt.root; mixer pcm 100 vol 100 cd 100 どんなネットワークカードをサポートしていますか? より完全な一覧についてはイーサネットカードの節を参照してください。 数値演算コプロセッサを持っていませんが、何かまずいでしょうか? これらは 386/486SX/486SLC を持っている場合に影響します - ほかのマシンでは CPU に内蔵されています。 一般にこれらは問題とはなりません。 しかし、数値演算エミュレーションコードのパフォーマンスか、 正確さのいずれかを選択する状況があります (詳しくは FP エミュレーション についての節をご覧ください)。 とくに、X 上で弧を描く際にとても遅くなることでしょう。 数値演算コプロセッサを購入されることを強くおすすめします。 とても役立つことでしょう。 他の数値演算コプロセッサよりも優れたコプロセッサもあります。 これは言いにくいことなのですが、Intel を買うために躍起になる人もいないでしょう。 それが FreeBSD 上で動くという確信がないのなら、クローンにご用心を。 FreeBSD がサポートするデバイスは他にもあるんでしょうか? FreeBSD ハンドブックに記されている、 サポートされている他のデバイスの一覧を参照してください。 パワーマネージメント機能付きのラップトップ PC を持っているのですが…。 FreeBSD は一部のマシンの APM をサポートしています。 LINT カーネルコンフィグファイル の APM の部分をご覧ください。 さらに詳しいことは &man.apm.4; に載っています。 Micron システムが起動時に固まってしまいます。 特定の Micron 製のマザーボードの中には、PCI BIOS が規格通りに 実装されていないために FreeBSD の起動に失敗するものがあります。 その BIOS は、PCI デバイスをあるアドレスで設定したと報告するにも 関わらず、実際にはそうしていないのです。 この問題を回避するには、BIOS の Plug and Play Operating System を無効に設定してください。また、より詳しい情報は http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron を参照してください。 新しい Adaptec コントローラを持っているのですが、 FreeBSD が検出できないようです。 新しい AIC789x シリーズの Adaptec チップは、3.0 でデビューした CAM SCSI フレームワークでサポートされています。 2.2-STABLE のパッチは ftp://ftp.FreeBSD.org/pub/FreeBSD/development/cam/ にあります。 CAM システムが入っている高機能ブートフロッピーは http://people.FreeBSD.org/~abial/cam-boot/ にあります。 どちらの場合にしても、作業を始める前に README をお読みください。 内蔵の Plug & Play モデムを持っているのですが、FreeBSD が検出できないようです。 モデムの PnP ID を シリアルドライバの PnP ID リストに追加する必要があるでしょう。 Plug & Play サポートを有効にするには、 controller pnp0 をコンフィグレーション ファイルに付け加え、 新しいカーネルをコンパイルしてシステムを再起動してください。 カーネルは、検出したすべてのデバイスの PnP ID を表示します。 モデムの欄にある PnP ID を /sys/i386/isa/sio.c の 2777 行目くらいにあるテーブルに書き入れてください。 テーブルを見つけるには、構造体 siopnp_ids[] の文字列 SUP1310 を探します。 カーネルを作り直したらインストールし、システムを再起動してください。 そうすれば、モデムが検出されるはずです。 起動時のコンフィグレーションの際に、pnp コマンドを使用して PnP の設定をマニュアルで行なわなければならないかもしれません。 その場合、モデムを検出させるためのコマンドは pnp 1 0 enable os irq0 3 drq0 0 port0 0x2f8 のようになります。 シリアルコンソールで boot: プロンプトを表示するにはどうすればいい? options COMCONSOLE を指定してカーネルを構築してください。 そして /boot.config を作成して とだけ書き入れてください。 その後、キーボードをシステムから抜きます。 /usr/src/sys/i386/boot/biosboot/README.serial に、 これに関する情報が書かれています。 なぜ Micron コンピュータで 3Com PCI ネットワークカードが動かないのでしょう? 特定の Micron 製のマザーボードの中には、PCI BIOS が規格通りに 実装されていないために FreeBSD の起動に失敗するものがあります。 その BIOS は、PCI デバイスをあるアドレスで設定したと報告するにも 関わらず、実際にはそうしていないのです。 この問題を回避するには、BIOS の Plug and Play Operating System を無効に設定してください。また、より詳しい情報は http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron を参照してください。 対称型マルチプロセシング (SMP) をサポートしていますか? SMP は、3.0-STABLE とそれ以降のリリースでのみサポートされています。 GENERIC カーネルでは SMP は有効化されていませんので、 SMP を有効化するにはカーネルを再構築する必要があります。 /sys/i386/conf/LINT を見て、 カーネルコンフィグファイルにどのオプションを追加すれば良いのか確かめてください。 ASUS K7V マザーボードのシステムでブートフロッピーを使うと、 システムがハングアップします。 対応策はありませんか? BIOS セットアップで起動時のウィルス保護機能を無効化してください。 トラブルシューティング 訳: &a.jp.yoshiaki;、 1997 年 11 月 10 日 ハードディスクに不良ブロックがあります! SCSI ディスクの場合は自動的に再マップする機能があるはずです。 しかし、理解し難い理由から多くのドライブがこの機能が無効化 されて出荷されています…。 これを有効化するには、 最初のデバイスのモードページを変更する必要があります。 これは次のコマンドを実行することで、FreeBSD 上で行なうことができます (root 権限で行ないます)。 &prompt.root; scsi -f /dev/rsd0c -m 1 -e -P 3 そして、AWRE と ARRE の値を 0 から 1 へ変更します AWRE (Auto Write Reallocation Enbld): 1 ARRE (Auto Read Reallocation Enbld): 1 以下は、Ted Mittelstaedt 氏から寄せられたものです。 IDE ドライブの場合は通常、不良ブロックは潜在的な障害の兆候です。 最近の IDE ドライブは、内部の不良ブロック再マッピング機能を有効にした状態で 出荷されています。また、今日の IDE ハードディスクメーカは、 出荷以降に不良ブロックが発生することに関して保証を提供していて、 不良ブロックのあるディスクドライブを交換するサービスを行なっています。 もし、不良ブロックのある IDE ディスクドライブを復旧しようと思うなら、 IDE ドライブメーカが提供する IDE 診断プログラムをダウンロードして、 そのドライブに使ってみてください。この種のプログラムは大抵、 ドライブの制御部分に対して不良ブロックを再走査し、 不良ブロックを使用不能にするようにセットすることができます。 ESDI、RLL および MFM ドライブの場合、 不良ブロックはドライブの正常な部分であり、 一般的に言って障害を表すものではありません。 PC では、ディスクドライブコントローラカードと BIOS が不良ブロックの使用不能化の作業を行ないます。 DOS など、ディスクアクセスに BIOS を経由する OS にとっては有効に働きますが、FreeBSD のディスクドライバは BIOS を利用しません。そのため、 代替として bad144 という機構が存在します。 bad144 は、wd ドライバでだけ (つまり FreeBSD 4.0 ではサポートされていない)動作し、SCSI ドライバに利用することは できません。bad144 は、 検出された不良セクタをスペシャルファイルに記録するという機能を持っています。 bad144 を利用する上で、注意しなければならない点が一つあります。 それは、不良ブロックスペシャルファイルは、 ディスクの最終トラックに置かれるということです。 このファイルには、ディスクの先頭の付近、 /kernel ファイルが位置しているであろう部分で発生した不良セクタが記録されています。 したがって、このファイルは BIOS コールを使ってカーネルファイルを読み込む起動プログラムが、 アクセス可能でなければなりません。 これはつまり、bad144 を利用するディスクは 1024 シリンダ、16 ヘッド、63 セクタを超えてはならないということを意味し、 bad144 を利用したディスクが実質 500MB を超えられないことになります。 bad144 を使うには、FreeBSD のインストール時に表示される fdisk 画面で Bad Block 走査を ON に設定するだけです。 これは、FreeBSD 2.2.7 以降で機能します。 ディスクは、1024 シリンダ以内でなければなりません。 ディスクドライブは事前に少なくとも 4 時間、 ディスクが温度によって膨張し、 トラックに曲がりが出るまで回転させることをお薦めします (訳注: 温度変化に対する膨張によって、 ディスクが微小変形することにより発生する不良セクタを確実に検出するためです)。 大容量の ESDI ドライブのように 1024 シリンダを超えるディスクの場合、 DOS 上でそのディスクが利用できるよう、 ESDI コントローラは特殊な変換モードを利用します。 fdisk の set geometry コマンドを使って 変換された (translated) ジオメトリに切替えると、wd ドライバはこの変換モードを解釈できます。 その際、FreeBSD パーティションを作成するのに dangerously dedicated モードを利用してはいけません。 このモードは、そのようなジオメトリを無視するからです。 たとえ fdisk がオーバーライドされたジオメトリ情報を使ったとしても、 依然としてディスクの真の大きさを保持しているため、大きすぎる FreeBSD パーティションを作成しようとしてしまうでしょう。 ディスクジオメトリ情報が変換されたジオメトリ情報にかわっている場合は、 手動でブロック数を入力し、 パーティションを作成する必要があります。 大容量の ESDI ディスクを ESDI コントローラでセットアップするには、 ちょっとしたトリックを使います。まず、DOS のディスクで起動して そのディスクを DOS パーティションとしてフォーマットします。 そして FreeBSD を起動し、インストーラの fdisk 画面で DOS パーティションのブロックサイズとブロック数を読みとり、メモしておきます。 ジオメトリ情報を DOS が利用しているものと同一に再設定し、 DOS パーティションを削除して cooperative FreeBSD パーティションを 先程記録したブロックサイズを使って作成してください。 そのパーティションを起動可能パーティションに設定し、不良ブロック走査を 有効にします。 実際のインストールでは、ファイルシステムが作成される前に bad144 が最初に実行されます (Alt-F2 を押すことで状況を確認できます)。 不良セクタファイルを作成中に何らかの障害が発生したなら、 システムを再起動して、もう一度最初からやり直しになります。 おそらくディスクジオメトリ情報の設定を大きくしすぎているのでしょう (やり直しは、DOS によるフォーマットとパーティション確保を含みます)。 もし、不良ブロックの再マッピングを有効にしていて不良ブロックが見付かったら、 ドライブの交換を考えてください。不良ブロックは、時間とともに悪化するからです。 Bustek 742a EISA SCSI が認識されません。 この情報は 742a のためのものですが、他の Buslogic カードについても 同様のことが言えます。(Bustek = Buslogic) 742a カードには大きくわけて 2 つの「バージョン」が存在します。 ハードウェアリビジョンの A-G と H 以降です。リビジョンの 文字はカードの隅にあるアセンブリ番号の後ろにあります。 742a は二つの ROM チップを持っており、一つは BIOS チップで もう一つはファームウェアチップです。FreeBSD はあなたの 持っているものがどの BIOS バージョンかは問題ありませんが、 ファームウェアバージョンについては問題となります。 Buslogic の技術サポート部門に連絡すれば、アップグレード版の ROM を送ってくれることでしょう。BIOS チップと ファームウェアチップはペアで出荷されます。 アダプタカードのハードウェアリビジョンにあわせた 最も新しいファームウェア ROM を使用しなければなりません。 リビジョン A-G のカードには、2.41/2.21 までの BIOS/ファームウェアのセットを使用することができます。 リビジョン H 以降のカードには、最新のものである 4.70/3.37 の BIOS/ファームウェアのセットを 使用することができます。これらのファームウェアの違いは、 ファームウェア 3.37 が 「ラウンドロビン方式」 をサポートしているところからきています。 Buslogic のカードには、製造番号も刻印されています。古い ハードウェアリビジョンのカードを持っている場合は、Buslogic の RMA 部門に問い合わせて製造番号を伝えると、新しいハードウェアリビジョンの カードに交換することもできます。もしカードが十分新しければ、彼らは 交換に応じてくれるでしょう。 FreeBSD 2.1 は ファームウェアリビジョン 2.21 以降のものをサポートしています。 これよりも古いファームウェアリビジョンのものは、 Buslogic カードとして正常に認識されません。 しかし、Adaptec 1540 として認識されるかもしれません。 初期の Buslogic のファームウェアは AHA1540 「互換」モードを 持っています。しかし、EISA カードにとってこれは よいことではありません。 古いハードウェアリビジョンのカードを持っていてファームウェア 2.21 を入手するのであれば、ジャンパ W1 の位置をデフォルトの A-B から B-C に合わせる必要があるでしょう。 HP Netserver 上のオンボード SCSI コントローラが認識されません。 基本的にこれは既知の問題です。HP Netserver マシンの EISA オンボード SCSI コントローラは EISA のスロット番号 11 を占有しますが、「本当の」EISA スロットはすべてそれよりも前のアドレスに配置されているのです。 残念ながら、 10 番以上の EISA スロットは PCI に割り当てられたアドレス空間と衝突し、FreeBSD の自動コンフィグレーションは、 現状ではうまくこの状況を処理できていないのです。 ですから現時点での最良の方法は、カーネルオプションの EISA_SLOTS を 12 に変え、 アドレス空間の衝突がないかの ようなふりをさせることです :) カーネルの再構築に記述されているようにしてカーネルを再構築してください。 もちろん、これはこのようなマシンにインストールする際に 「卵が先か、 鶏が先か」といった問題を生み出すことになります。 この問題を回避するために、 ユーザコンフィグ (UserConfig) の中には特別な仕組みが組み込まれています。 このとき visual インタフェースは使用せず、 コマンドラインインタフェースを使用してください。単純に eisa 12 quit とプロンプト上から打ち込み、 後は普通にインストールを行なってください。 とにかくカスタムカーネルのコンパイルとインストールを行なうことを おすすめします。 うまくいけば、将来のバージョンではこの問題が解決していることでしょう。 HP Netserver では危険覚悟の専用ディスクは使用できません。 詳細については この注意事項をご覧ください。 この CMD640 IDE コントローラはどこかおかしいようです。 それは壊れているのです。両方のチャンネルを同時に制御できないのです。 現在、このチップを使っているシステムを自動的に検出して、 うまく動かすためのしくみが使えるようになっています。 くわしくは wd(4) のマニュアルページを参照してください。 CMD640 IDE コントローラを使っているシステムで FreeBSD 2.2.1 あるいは 2.2.2 を使い、 かつセカンダリのチャネルを使いたいのであれば、 options "CMD640" を有効にしてカーネルを作り直してください。 FreeBSD 2.2.5 以降では、デフォルトでそうなっています。 ed1: timeout のようなメッセージがいつも出ます。 たぶん IRQ の衝突が原因でしょう (二つのボードが同じ IRQ を使用しているなど)。FreeBSD 2.0.5R 以前はこれに関して寛大で、 IRQ の衝突があってもネットワークドライバは機能していました。 しかし 2.0.5R 以降はもはや、IRQ の衝突に寛大ではありません。 オプションをつけて起動し、 ed0/de0/... のエントリをボードの設定に合わせてください。 ネットワークカードの BNC コネクタ (訳注: 10BASE-2 タイプのインタフェース) を使っている場合、 デバイスのタイムアウトはターミネーションの不良によっても起きます。 これをチェックするにはケーブルを外してターミネータを直接 NIC に接続します。そしてエラーメッセージが消えるかどうか 確認します。 NE2000 コンパチブルカードのなかには、 UTP ポートのリンクがなかったりケーブルが接続されていない場合に このエラーを出すものがあります。 CDROM をマウントしようとすると Incorrect super block と言われます。 &man.mount.8; にマウントしたいデバイスのタイプを指定する必要があります。 デフォルトでは &man.mount.8; はファイルシステムを ufs とみなします。CDROM のファイルシステムを マウントしたいのであれば と &man.mount.8; にオプションをつけて明示する必要があります。 これはもちろん CDROM が ISO 9660 ファイルシステムである場合です。ほとんどの CDROM はこの形式です。1.1R の FreeBSD では (訳注: 2.1.5R、 2.2R でも同様です) 自動的に Rock Ridge 拡張 (長いファイル名への対応) をうまく解釈します。 CDROM のデバイス /dev/cd0c を /mnt にマウントしたい場合の例では、次のようにします。 &prompt.root; mount -t cd9660 /dev/cd0c /mnt デバイスの名前はインタフェースによっては別の名前になっている かもしれないので注意してください (/dev/cd0c はこの場合の例です)。 オプション によって mount_cd9660 コマンドが実行されることに注意してください。 このため例は次のようにすることもできます。 &prompt.root; mount_cd9660 /dev/cd0c /mnt CDROM をマウントしようとすると Device not configured と言われます。 これは 一般的に CDROM ドライブの中に CDROM が入っていないか、 ドライブがバス上に見えないことを意味します。ドライブに CDROM を入れるか、IDE (ATAPI) であれば master/slave の状態をチェックしてください。 また、CDROM ドライブに CDROM を入れてから認識するまでには数秒かかりますので、 少し待ってみてください。 SCSI CDROM ではバスリセットへの応答時間が遅いために、 失敗することがあるかもしれません。 SCSI CDROM を持っている場合は、 カーネルコンフィグレーションファイルに以下の行を加えて 再コンパイルして試してみてください。 訳注 現在の GENERIC カーネルでは上の設定はデフォルトになっています。 問題のある場合は SCSI_DELAY の数値を増やしてみてください。 options "SCSI_DELAY=15" CDROM をマウントすると、ファイル名中の英数字以外の 文字が、? と表示されてしまいます。 もっともありそうなのは、その CDROM が Joliet 拡張を利用してファイルおよび ディレクトリに関する情報を保存しているということです。この拡張は、 すべてのファイル名を Unicode の 2 バイト文字で保存するように 規定しています。現在、FreeBSD カーネルに汎用的な Unicode インタフェースを導入する作業が行われていますが、 まだ完了していません。したがって、CD9660 ドライバはファイル名の文字を解読できません。 一時的な解決策として、FreeBSD 4.3R 以降では、CD9660 ドライバに特別な仕掛けを施して、ユーザーがその場で適切な 変換表を読み込めるようにしました。一般的なエンコーディングに 対応したいくつかのモジュールが sysutils/cd9660_unicode port で提供されています。 訳注 この記述は古くなっています。 英語版の記述をご覧ください。 私のプリンタはとてつもなく遅いのです。 どうしたらよいのでしょう? パラレルインタフェースで、問題はとんでもなく遅いだけであるなら、 プリンタボートを polled モードに設定してみてください。 &prompt.root; lptcontrol -p HP の新しいプリンタには、 割り込みモードで使えないものがあるようです (完全にわかったわけではありませんが)。 タイミングの問題のように思われます。 わたしのプログラムは時々 Signal 11 のエラーで止まってしまいます。 Signal 11 エラーはオペレーティングシステムが 許可を与えていないメモリにアクセスしようとしたときに発生します。 このようなことがランダムな間隔で起っているようなら、 注意深く調査していった方が良いです。 この手の問題はたいていの場合、以下のどちらかです。 その問題が特定の、 あなたが自分で開発したアプリケーションでのみ起っているなら、 あなたのコードにバグがあるのでしょう。 それが FreeBSD のベースシステムの一部と関連する問題なら、 コードにバグがあるということになります。 しかしほとんどの場合、 普通の FAQ の読者がそのようなコードを使うようになるずっと前に、 そういった問題は発見され、修正されているはずです (それが -current の役目なのですから)。 それが FreeBSD のバグでは「ない」という決定的なケースとして、 その問題の発生がプログラムをコンパイルしているときであり、 コンパイル毎に毎回、コンパイラの挙動が変るというものがあります。 たとえば、あなたが make buildworld を実行していて、 コンパイラが ls.c から ls.o をコンパイルしようとしたときに コンパイルに失敗したとします。もう一度 make buildworld を実行したときに、まったく同じ場所でコンパイルが失敗したのなら、 それは build が壊れている (訳注: つまりソースにバグがある) と言うことです -- ソースを更新してやりなおしてみてください。 もしコンパイルが別の場所でしくじっていたら、 それはハードウェアの問題です。 あなたのやるべき事は: 前者の場合は、 そのプログラムの間違ったアドレスへアクセスしようとしている部分を、 gdb 等のデバッガで見つけて修正します。 後者の場合は、 ハードウェアに問題がないことを確かめる必要があります。 その一般的な原因として : ハードディスクが熱を持ちすぎているかも知れません: ケースのファンがちゃんと動いていてディスクを冷やしているか 確かめてください (たぶん、他の部品も過熱しています)。 CPU がオーバーヒートしています: CPU をオーバークロックしていませんか? さもなければ CPU ファンが死んでいるのかもしれません。 いずれにせよ、少なくとも問題解決の間では ハードウェアが動くべく指定された条件で動かしてください。 クロックはデフォルトの設定に戻してください。 もしあなたがクロックアップをしているのなら、 遅いシステムでも、システムが焼き付いて 買い換えなければならなくなるよりずっとマシだということを 覚えておいた方が良いでしょう。 大きいコミュニティでは特に、 あなたがそれが安全だと思っているかどうかは関係なく、 オーバークロックしたシステムに発生した問題には同情的ではありません。 怪しいメモリ: もし複数の SIMM や DIMM を使っているならそれを全部抜いてから 各 SIMM や DIMM を別個に組み込んだシステムを立ち上げてることで どの DIMM/SIMM が怪しいのか、それとも組合わせが悪いのか と問題の幅が狭まります。 楽観的すぎるマザーボードの設定: ほとんどの場合に標準設定で十分なタイミングを、 BIOS の設定やマザーボード上のジャンパピンを変えることで、 さまざまに変更することができます。しかし時には RAM の アクセスウェイトを低くしすぎたり RAM Speed: Turbo や その手の BIOS の設定でおかしな挙動が起こることがあります。 BIOS を標準の設定に戻すというのはいいアイディアですが、 その前にあなたの設定を書き留めておいた方がいいでしょう。 マザーボードへの電源が安定していない。 もし使っていない I/O ボードやハードディスク、 CDROM 等があるなら、一旦それらから電源ケーブルを抜き、 電源が小さな負荷ならなんとか動作するか確認しましょう。 あるいは別の電源を試してみましょう。 その時はなるべく、少し容量の大きいもので試しましょう (たとえば、今の電源容量が 250W だったら 300W のものを試します)。 SIG11 FAQ (下に示します) にはこれらの問題のすべてが 詳しく説明されています。Linux の視点に基づくものですが、 これも読んでおいた方がいいでしょう。そこではまた、 メモリのテストを行うソフトウェアや、 ハードウェアがなぜ問題のあるメモリを見逃してしまうかについても 議論されています。 最後に、これらがどれも助けにならなかったら、 FreeBSD のバグを発見した可能性があります。 以下の説明を読んで障害報告を送ってください。 詳細な FAQ は、 the SIG11 problem FAQ にあります。 起動の時に画面が真っ暗になって同期も取れません。 これは ATI Mach 64 ビデオカードの既知の問題です。 この問題はカードがアドレス 2e8 を使い、 4 番目のシリアルポートもここを使うということにあります。 &man.sio.4; ドライバのバグ (仕様?) のため、 4 番目のシリアルポートがなくても、 通常このアドレスを使う sio3 (4 番目のポートにあたります) を無効にしても、ドライバはこのアドレスをさわります。 バグが修正されるまでは、次のようにして対処してください。 起動プロンプトが出たら と入力します (これによりカーネルはコンフィグレーションモードに入ります)。 sio0、 sio1、 sio2、 sio3 (これらすべて) を無効にします。 これによって &man.sio.4; ドライバは動作しなくなりますが、問題はありません。 exit と入力して起動を続行します。 もしシリアルポートを有効にしたいのであれば以下の変更を行なって 新しいカーネルを作る必要があります。 /usr/src/sys/i386/isa/sio.c の中で 1 ヵ所ある 0x2e8 という文字列を探し、 この文字列とその手前にあるコンマを削除します (後ろのコンマは残します)。 後は通常の手続きにしたがって新しいカーネルを作ります。 この対処を行なった後でもまだ X ウィンドウシステムはうまく動かないかもしれません。 その場合は、 使用している XFree86 がすくなくとも XFree86 3.3.3 以降であることを確かめてください。 それ以降のバージョンでは、 Mach64 カードやそれらのカードのためにつくられた X サーバ の組込みをサポートします。 128MB の RAM があるのですが、64MB しか認識しません。 FreeBSD がメモリのサイズを BIOS から取得する方法の制限により、 KB 単位で 16 ビット分までしか検出できません (すなわち最大 65535KB=64MB です。これより少ない場合もあります。 ある BIOS の場合はメモリサイズが 16MB に制限されます)。 64MB 以上のメモリを積んでいる場合、 FreeBSD はそれを検出しようとします。 しかしその試みは失敗するかもしれません。 この問題を回避するには、 以下に示すカーネルオプションを使用する必要があります。 完全なメモリ情報を BIOS から取得する方法もありますが、 起動ブロックに空きが無いため実装できません。 起動ブロックの問題が解決されれば、 いつか拡張 BIOS 機能を使用して完全なメモリ情報を取得できるようになるでしょう。 とりあえず現在は、カーネルオプションを使ってください。 options "MAXMEM=n" n には、 キロバイト単位でメモリの量を指定します。128MB の場合は、131072 となります。 FreeBSD 2.0 が kmem_map too small! と言ってパニックします。 メッセージは、mb_map too small! の場合もあります。 このパニックは、ネットワークバッファ (特に mbuf クラスタ) の仮想メモリが無くなったことを示します。 以下のオプションをカーネルコンフィグファイルに追加して mbuf クラスタに使用できる仮想メモリの量を増やしてください。 options "NMBCLUSTERS=n" n には、 同時に使用したい TCP コネクションの数に応じて 512 から 4096 までの数値を指定できます。 とりあえず 2048 を試してみるのをおすすめします。 これでパニックは完全の予防できるはずです。 mbuf クラスタの割り当て、使用状況については、 netstat -m で知ることができます (&man.netstat.1; をご覧ください)。 NMBCLUSTERS のデフォルト値は 512 + MAXUSERS * 16 です。 新しいカーネルで再起動すると CMAP busy panic となってパニックを起こしてしまいます。 ファイル /var/db/kvm_*.db において範囲外のデータを検出するためのロジックは失敗することがあり、 こうした矛盾のあるファイルを使用することでパニックを引き起こすことがあります。 これが起こったなら、シングルユーザで再起動した後に、 以下のコマンドを実行してください。 &prompt.root; rm /var/db/kvm_*.db ahc0: brkadrint, Illegal Host Access at seqaddr 0x0 というエラーが出ます これは Ultrastor SCSI Host Adapter と衝突しています。 起動時に kernel configuration メニューに入り、 問題を起こしている uha0 を disable にしましょう。 sendmail が mail loops back to myself というメッセージを出すのですが。 この事は、sendmail FAQ に次のように書いてあります。 * "Local configuration error" というメッセージが出ます。たとえば: 553 relay.domain.net config error: mail loops back to myself 554 <user@domain.net>... Local configuration error のような物ですが、どのようにしたらこの問題を解決できますか? これは、たとえば domain.net のようなドメイン宛てのメールを MX record で 特定のホスト (ここでは relay.domain.net) に送ろうとしたのに、 そのホストでは domain.net 宛てのメールを受け取れるような設定に なっていない場合です。設定の際に FEATURE(use_cw_file) を 指定してある場合には /etc/sendmail.cw の中に domain.net を 追加してください。もしくは、/etc/sendmail.cf の中に "Cw domain.net" を追加してください。 もはや現在の sendmail FAQ は sendmail release とは一緒には保守されていません。 しかし次のネットニュースに定期的に投稿されてます。 comp.mail.sendmail、 comp.mail.misc、 comp.mail.smail、 comp.answers、 news.answers。 また、メール経由でコピーを入手する場合は mail-server@rtfm.mit.edu 宛まで本文に send usenet/news.answers/mail/sendmail-faq と書いて送ります。 リモートマシン上のフルスクリーンアプリケーションがうまく動かない リモートマシンのターミナルタイプが FreeBSD のコンソールで必要とされている cons25 以外のものです。 この問題を解決しうる方法はいろいろあります: リモートマシンにログインした後、 そのリモートマシンが ansi か sco のターミナルタイプを知っているなら、 shell 変数の TERM にそれらのいずれかを設定します。 FreeBSD のコンソール側で screen のような VT100 エミュレータを使用します。 screen は一つのターミナルの中で複数のセッションを並列動作させることができますし、 本来の機能も優れています。 各々の screen のウィンドウは VT100 ターミナルのように振る舞うので、 リモート側で設定されるべき TERM 変数は vt100 となります。 リモートマシンのターミナルデータベースに cons25 のエントリをインストールします。 このインストール方法はリモートマシンのオペレーティングシステムに依存します。 リモートのシステムのシステム管理マニュアルが役に立つことでしょう。 FreeBSD 側で X サーバを起動して、 リモートマシンに xterm や rxvt のような X ベースのターミナルエミュレータを使ってログインします。 (訳注: 日本語が必要な場合は kterm 等を 利用します) リモートホストの TERM 変数は xterm もしくは vt100 (訳注: もしくは kterm) に設定します。 私のマシンで calcru: negative time... と表示されるのですが これは、割り込みに関連するさまざまな不具合によって発生します。 あるいは、あるデバイスが元々持っているバグが表面化したのかも知れません。 この症状を再現させる一つの方法として、パラレルポート上で、 TCP/IP を 大きな MTU で走らせるというものがあります。 グラフィックアクセラレータがこの症状を起こすことがありますが、 その場合はまず、カードの割り込み設定を確認してください。 この問題の副作用として、 プロセスが SIGXCPU exceeded cpu time limit というメッセージとともに終了してしまう、というものがあります。 1998 年 11 月 29 日に公開された FreeBSD 3.0 以降で この問題が解決しないなら、次の sysctl 変数をセットしてください。 &prompt.root; sysctl -w kern.timecounter.method=1 これは、パフォーマンスへ強い影響を与えますが、 問題の発生に比べればおそらく気にならない程度でしょう。 もし、これでもまだ問題が残るようなら、 カーネルオプションの NTIMECOUNTER を大きな値に増やしてください。 NTIMECOUNTER=20 にまで増やしても解決しない場合は、 計時処理の信頼性が保てない程の割り込みが、 そのマシン上で起こっていることを意味します。 pcm0 not found という表示を見たり カーネルコンフィグレーションファイルには device pcm0 と 書いてあるのにサウンドカードが pcm1 として 発見されたりします。 これは FreeBSD 3.x で PCI のサウンドカードを使っているときに 発生します。pcm0 デバイスは ISA のカード専用に予約されているものです。このため、 あなたが PCI カードを持っているときはこのエラーが表示され、 カードは pcm1 として検出されます。 この警告を、単にカーネルコンフィグファイルの当該行を device pcm1 に変更することで 抑制することはできません。その時は pcm1 が ISA カードのために予約され、PCI のカードは pcm2 として (pcm1 not found の警告とともに) 検出されます。 PCI のサウンドカードを持っているのならば、以下のようにして snd0 デバイスのかわりに snd1 を作る必要があります。 &prompt.root; cd /dev &prompt.root; ./MAKEDEV snd1 この状況は FreeBSD 4.x では生じません。多くの努力の結果より PnP 中心に作り替えられ、 現在、pcm0 デバイスは ISA カード専用に予約されたものではなくなりました。 プラグアンドプレイのカードが認識されなくなりました (または、unknown と認識されるようになりました)。 現在の FreeBSD 4.x はより PnP 中心に なっています。その副作用の影響で、FreeBSD 3.x で動いていた PnP デバイス (たとえばサウンドカードや内蔵モデム) の中には、 動かなくなってしまったものもあります。 この挙動の原因は Peter Wemm が freebsd-questions メーリングリストに書いた、以下の 「FreeBSD 4.x にアップグレードしたところ内蔵モデムが 見つからなくなった」というメールで解説されています。 (わかりやすくするために [] 内に コメントを加えました)。
PnP BIOS はあらかじめ、[モデムを] ポート空間に存在しているかのように設定します。 そのため [3.x では] 従来の手法に基づく ISA デバイスの検索により、モデムの存在を「発見」できます。 4.0 の ISA コードは、より PnP 中心になっています。 [3.x では] ISA デバイスの検索が「はぐれた」デバイスを発見して、 次に PNP デバイス ID のマッチが行なわれることでリソースの競合が発生し、 デバイスの検索に失敗する可能性があります。 したがって、4.0 の ISA コードでは 二重に検索しないよう、プログラマブルなカードを 最初に無効にしています。 これは、対応している PnP ハードウェアの PnP ID が、 予めわかっている必要がある、ということを意味します。 ユーザがこの挙動にもっと手を入れられるようにすることが TODO リスト中にあげられています。
3.0 で動作していたデバイスを 4.0 でも動作するようにするには、 それの PnP ID を調べ、ISA デバイスの検索が PnP デバイスの識別に使っているリストにそれを追加する必要があります。 デバイスの検索に使われる &man.pnpinfo.8; を用いて、 PnP ID を得ることができます。 たとえば、内蔵モデムに関する &man.pnpinfo.8; の出力は、 以下のようになります。 &prompt.root; pnpinfo Checking for Plug-n-Play devices... Card assigned CSN #1 Vendor ID PMC2430 (0x3024a341), Serial Number 0xffffffff PnP Version 1.0, Vendor Version 0 Device Description: Pace 56 Voice Internal Plug & Play Modem Logical Device ID: PMC2430 0x3024a341 #0 Device supports I/O Range Check TAG Start DF I/O Range 0x3f8 .. 0x3f8, alignment 0x8, len 0x8 [16-bit addr] IRQ: 4 - only one type (true/edge) [more TAG lines elided] TAG End DF End Tag Successfully got 31 resources, 1 logical fdevs -- card select # 0x0001 CSN PMC2430 (0x3024a341), Serial Number 0xffffffff Logical device #0 IO: 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 IRQ 5 0 DMA 4 0 IO range check 0x00 activate 0x01 必要な情報は、出力の冒頭にある Vendor ID 行にあります。 かっこの中の 16 進数 (例の中では 0x3024a341) が PnP ID で、 直前の文字列 (PMC2430) はユニークな ASCII ID です。 この情報はファイル /usr/src/sys/isa/sio.c に 追加する必要があります。 まず失敗したときに備えて sio.c の バックアップを取るべきです。障害報告を送るために修正パッチを 作る時にも必要になるでしょう (send-pr しようとしていますよね?)。 sio.c を編集して以下の行を探してください。 static struct isa_pnp_id sio_ids[] = { そしてあなたのデバイスのエントリを追加する正しい場所を探します。 エントリは以下のような形をしていて、&man.pnpinfo.8; の 出力にある デバイスの説明の全部 (もし収まれば) か一部とともに行の右の方のコメント領域に書かれている ASCII ベンダ ID でソートされています。 {0x0f804f3f, NULL}, /* OZO800f - Zoom 2812 (56k Modem) */ {0x39804f3f, NULL}, /* OZO8039 - Zoom 56k flex */ {0x3024a341, NULL}, /* PMC2430 - Pace 56 Voice Internal Modem */ {0x1000eb49, NULL}, /* ROK0010 - Rockwell ? */ {0x5002734a, NULL}, /* RSS0250 - 5614Jx3(G) Internal Modem */ あなたのデバイスの16進数のベンダ ID を正しい場所に 追加し、ファイルをセーブしてカーネルを作り直して再起動します。 あなたのデバイスは FreeBSD 3.x の時と同じように sio として見つかるようになっているはずです。 top や systat の 実行中に nlist failed という エラーがでます。 このエラーは、 実行しようとしたアプリケーションが あるカーネルシンボルを検索した結果、 何らかの理由でその検索に失敗した、ということを意味しています。 これは、以下に示すいずれかの理由によるものです。 カーネルとユーザランドが同期していない (つまり カーネルは新しいものを構築したが、 installworld は行なっていない。 あるいはその逆) ので、 シンボルテーブルがユーザアプリケーションの考えているものと異なっている。 もしこのケースなら、一連のアップグレード手順に従ってアップグレードを行なってください (正しいやり方は /usr/src/UPDATING に書いてあります)。 カーネルをロードするのに /boot/loader を使わず、 直接 boot2 (&man.boot.8; 参照) からロードしている。 もちろん /boot/loader を使わなくとも問題はないのですが、 /boot/loader は一般的に、 ユーザアプリケーションからカーネルシンボルを アクセスできるようにするための機能を持っています。 &man.ssh.1; や &man.telnet.1; でコンピュータに接続する のに、どうしてこんなに時間がかかるのですか? 症状: TCP コネクションが確立してから、 クライアントソフトウェアがパスワードを尋ねてくるまで (&man.telnet.1; の場合は、ログインプロンプトが表示されるまで) に長い時間がかかる、というもの。 問題: おそらく、サーバソフトウェアがクライアントの IP アドレスからホスト名を解決しようとして、遅れが生じている のでしょう。FreeBSD に付属する SSH や Telnet を含む多くの サーバソフトウェアは、この名前解決をおこないます。これは、 管理者が後日参照するログファイルに、その他の情報と一緒に ホスト名を記録できるようにするのが目的です。 対処法: もし、あなたのコンピュータ (クライアント) からどのサーバに接続する場合にも問題が起こるのであれば、 クライアントに問題があります。そして、誰かがあなたの コンピュータ (サーバ) に接続するときだけ問題が起こるのであれば、 そのサーバの問題です。 問題がクライアントにある場合、唯一の対処法は サーバがそのクライアントの名前を解決できるように DNS を修正することです。 症状がローカルネットワークで発生しているなら、サーバの設定に 原因がありますので、このまま続きを読みましょう。 そうではなく、グローバルなインターネット環境で発生しているなら、 ISP に連絡して問題の修正をお願いしなければならない可能性が高いでしょう。 問題がサーバにあって、症状がローカルネットワークで 発生しているなら、ローカルのアドレス範囲にあるアドレスを、 それに対応するホスト名に解決する問合せを処理できるように、 サーバを設定する必要があります。 詳しくは、&man.hosts.5; および &man.named.8; のマニュアルをご覧ください。グローバルなインターネット環境の場合は、 サーバのリゾルバが正しく動作していないのが原因かもしれません。 確認するには、他のホスト (たとえば www.yahoo.com) を引いてみてください。 うまくいかなければ、あなたのコンピュータの問題です。 file: table is full という メッセージが繰り返し dmesg にあらわれます。 このエラーは、システムのファイル記述子を使い果たして しまった時に発生します。メモリ中のファイルテーブルが一杯に なっているのです。 解決法: 手動で sysctl 変数 kern.maxfiles の限界値を調整します。 &prompt.root; sysctl -w kern.maxfiles=n n は、システム要件に合わせてください。 オープンされたファイル、ソケットまたは fifo のそれぞれが ファイル記述子を消費します。規模の大きなサーバは、 同時に実行されるサービスに応じて、いともたやすく何万もの ファイル記述子を要求します。 カーネルに設定されたデフォルトのファイル記述子の 数を決定するのは、次の maxusers 32 カーネル設定ファイルの maxusers 行 です。kern.maxfiles はこの値に比例して 増加します。 現在設定されている kern.maxfiles の 値は、次のコマンドで調べることができます。 &prompt.root; sysctl kern.maxfiles kern.maxfiles: 1064 laptop の時間が狂って、大きく進んだり遅れたりします。 laptop には二つ以上の時計が内蔵されていますが、FreeBSD が間違った方を選択して使用しています。 &man.dmesg.8; を実行して Timecounter を含む行を確認してください。 最後に出力された行が FreeBSD が選択したもので、まず間違い なく TSC でしょう。 &prompt.root; dmesg | grep Timecounter Timecounter "i8254" frequency 1193182 Hz Timecounter "TSC" frequency 595573479 Hz &man.sysctl.3; 変数 kern.timecounter.hardware を確認すれば 裏付けがとれます。 &prompt.root; sysctl kern.timecounter.hardware kern.timecounter.hardware: TSC バッテリ駆動している時に、BIOS が CPU の速度を変えるために TSC クロックを変更したり、電力節約モードに入ることがあります。 しかし、FreeBSD はそういった調整を関知しないので、 時間が早まったり遅れたりするようです。 上記の例では、i8254 クロックも利用できます。 &man.sysctl.3; 変数 kern.timecounter.hardware にその名称を書き込んで選択できます。 &prompt.root; sysctl -w kern.timecounter.hardware=i8254 kern.timecounter.hardware: TSC -> i8254 これで、laptop はより正確な時間を刻むでしょう。 この変更を起動時に自動で行うには、次の行を /etc/sysctl.conf に追加してください。 kern.timecounter.hardware=i8254 商用アプリケーション 訳: 山下 淳 junkun@esys.tsukuba.ac.jp、 1997 年 11 月 10 日 この章はまだまだ情報が足りません。 情報を追加してくれるような企業を待ち望んでいます。 FreeBSD グループはここに載っている企業からの金銭的な支援を期待してはいませんので、 奉仕作業の一つとして掲載しています (そして FreeBSD が係わる宣伝は、長い目で見ると FreeBSD に対してよい方向へ働くと思っています)。 私たちは商用ソフトウェアベンダに、 ここで製品を宣伝してもらうことを望んでいます。詳しくは、 商用ソフトウェアベンダ覧のページをご覧ください。 FreeBSD 用のオフィススイートはどこで入手できますか? BSDi は FreeBSD ネイティブ版の VistaSource ApplixWare 5 を提供しています。 ApplixWare は、豪華で機能満載の FreeBSD 向けの 商用オフィススイートで、ワードプロセッサ、表計算、 プレゼンテーションソフトウェア、ベクタ描画ソフトウェア、 その他のアプリケーションを揃えています。 FreeBSD 版の ApplixWare の購入は こちらからどうぞ。 Linux 版の StarOffice は FreeBSD で完璧に動作します。Linux 版の StarOffice をインストールするもっとも簡単な方法は、FreeBSD Ports コレクションを利用することです。 また、オープンソースの OpenOffice も将来のバージョンで動作するでしょう。 FreeBSD 用の Motif はどうやったら手に入りますか FreeBSD 用の廉価版 ELF Motif 2.1.20 (i386 版、Alpha 版) に関する情報はApps2go から 手に入れることができます。 この製品には、「開発者版 (development edition)」 と、 より安価な「ランタイム版 (runtime edition)」 の二つの版があります。これらの製品は以下の物が含まれています。 OSF/Motif manager、xmbind、panner、wsm。 uil、mrm、xm、xmcxx、インクルードファイルや Imake ファイルといった開発者向けキット FreeBSD 3.0 以降で利用できる ELF 版スタティックライブラリ、 およびダイナミックライブラリ デモンストレーションプログラム 注文する際には FreeBSD 用の Motif であることをきちんと 確認してください (あなたの欲しいアーキテクチャを指定するのも 忘れないでください!)。NetBSD や OpenBSD 用の Motif もまた、 Apps2goから販売されています。現在、FTP による ダウンロードのみ利用可能です。 より詳しい情報は Apps2go WWW page 問い合わせは Sales または Support 電子メールアドレス。 もしくは phone (817) 431 8775 or +1 817 431-8775 他の FreeBSD 用 Motif 2.1 (ELF 版、a.out 版) に関する情報は Metro Link から手に入れることができます。 この製品は以下の物が含まれています。 OSF/Motif manager、xmbind、panner、wsm。 uil、mrm、xm、xmcxx、インクルードファイルや Imake ファイルといった開発者向けキット スタティックライブラリ、およびダイナミックライブラリ。 (FreeBSD 3.0 以降で利用できる ELF 版か、 FreeBSD 2.2.8 以前で利用できる a.out 版を指定してください) デモンストレーションプログラム 整形済みのマニュアルページ 注文する際には FreeBSD 用の Motif であることをきちんと 確認してください。Linux 用の Motif も Metro Link から販売されています。現在、CDROM および FTP によるダウンロードが利用可能です。 FreeBSD 用の a.out 版 Motif 2.0 に関する情報は Xi Graphics から 手に入れることができます。 この製品には以下の物が含まれています。 OSF/Motif manager、xmbind、panner、wsm。 uil、mrm、xm、xmcxx、インクルードファイルや Imake ファイルといった開発者向けキット FreeBSD 2.2.8 以前のバージョンで利用できるスタティックライブラリ、 およびダイナミックライブラリ デモンストレーションプログラム 整形済みのマニュアルページ 注文する際には FreeBSD 用の Motif であることをきちんと 確認してください。BSDI や Linux 用の Motif もまた、Xi Graphics から販売されています。現在フロッピーディスク 4枚組ですが、 将来的には CDE のように統合された CD に変わるでしょう。 FreeBSD 用の CDE はどうやったら手に入りますか 以前 Xi Graphics より FreeBSD 用の CDE が 販売されていましたが、現在は既に販売が終了しています。 KDE 多くの点で CDE と類似しているオープンソースの X11 デスクトップ環境です。 xfce の ルック & フィール (訳注: 外観や操作方法のこと) も気に入るかも知れません。 KDE、xfce は、いずれも FreeBSD Ports Collection に含まれています。 高機能な商用 X サーバってあるんですか? はい、Xi Graphics と Metro Link から、FreeBSD ほか Intel ベースのシステムで動作する Accelerated-X という製品が販売されています。 Metro Link は、FreeBSD のパッケージ操作ツールを利用することで 容易に設定が行なえるほか、数多くのビデオボードをサポートした 高機能な X サーバを提供しています。配布はバイナリ形式のみで、 FTP が利用可能です。もちろん、とても安価 ($39) に手に入れることができます。 また、Metro Link は ELF 版、a.out 版の FreeBSD 用 Motif も販売しています (前を参照)。 より詳しい情報は Metro Link WWW page 問い合わせは Sales または Support 電子メールアドレス もしくは phone (954) 938-0283 or +1 954 938-0283 Xi Graphics が提供している高性能な X サーバは楽に設定を行なえるほか、 数多くのビデオボード をサポートしています。サーバはバイナリのみが含まれます。 FreeBSD 用と Linux 用の統合されたフロッピーディスクに入っています。 Xi Graphics は Laptop サポートに特化した高性能 X サーバも提供しています。 バージョン 5.0 の「互換デモ」が無料で入手できます。 また Xi Graphics は FreeBSD 用の Motif と CDE も販売しています (前を参照)。 より詳しい情報は Xi Graphics WWW page 問い合せは Sales または Support もしくは phone (800) 946 7433 or +1 303 298-7478. FreeBSD 用のデータベースシステムはありますか? もちろんです。FreeBSD のウェブサイトにある 商用ベンダー というセクションをご覧ください。 また、FreeBSD Ports Collection のデータベースのセクションも参考になるでしょう。 Oracle を FreeBSD 上で動かすことはできますか? はい。Linux 版 Oracle を FreeBSD でセットアップするための方法は、 次に示すページに詳しく書かれています。 http://www.scc.nl/~marcel/howto-oracle.html http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd ユーザアプリケーション 訳: 山下 淳 junkun@esys.tsukuba.ac.jp、 &a.jp.shou;、 1997 年 11 月 8 日 そういうユーザアプリケーションはどこにあるの? FreeBSDに移植されたソフトウェアパッケージについては、 FreeBSD Ports Collection のページをご覧ください。 このリストには現在 3400 を越える項目があり、 しかも毎日更新されています。このページをこまめに訪れるか、 freebsd-announce メーリングリストを購読すると、 新しく入った ports を定期的にチェックすることができます。 大部分の ports は 2.2 と 3.x および 4.x ブランチで利用できるはずです。 多くは 2.1.x 系のシステムでも同様に動作するでしょう。 FreeBSD のリリースが出る度に、そのリリースの時点での ports ツリーの スナップショットが撮られ、ports/ ディレクトリに 納められることになっています。 また、package という考えも採用されています。これは基本的には gzip で圧縮されたバイナリディストリビューションに、 インストール時に環境に合わせた作業が必要になった場合、 行う機能を多少付け加えたものです。 package を使えば、どのようなファイルが配布物として含まれているか、 と言った細かい事柄にいちいち煩わされることなく、 簡単にインストールやアンインストールを繰り返すことができます。 インストールしたい package があるなら、 /stand/sysinstallの、 「インストール後の FreeBSD の設定を行う」の下にある package のインストールメニューを使うか、 package のファイル名を指定して pkg_add(1) を使用してください。 package のファイル名には、 通常末尾に .tgz がついています。 CDROM をご使用の方は、CD の packages/All ディレクトリからそれらのファイルを利用することができます。 また、以下の場所から、 FreeBSD の各種バージョンにあわせた package をダウンロードする こともできます。 2.2.8-RELEASE/2.2.8-STABLE 用 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-2.2.8/ 3.X-RELEASE/3.X-STABLE 用 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-3-stable/ 4.X-RELEASE/4-STABLE 用 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/ 5.X-CURRENT 用 ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current お近くのミラーサイトもご利用ください。 新しい ports が続々と追加されている状態なので、すべての ports に 対応する package が存在するわけではないことを覚えておいてください。 定期的に ftp.FreeBSD.org マスターサイトを訪れて、どのような package が利用できるのかチェックするのも良いでしょう。 なぜ /bin/sh はこんなに低機能なのですか? どうして bash や他のシェルを採用しないのでしょう? それは、POSIX がそのようなシェルがあることを規定しているからです。 もっと込み入った回答: 多くのユーザは、多くのシステムで同じように動作できるシェルスクリプトを書く必要があります。 これが、POSIX でシェルやユーティリティコマンドが細く規定されている理由です。 ほとんどすべてのスクリプトは Bourne shell で書かれているのですが、 それは、数多くの重要なプログラミングインタフェイス (&man.make.1;、 &man.system.3;、&man.popen.3;、や Perl や Tcl 等の類似の 高水準スクリプト言語) が、コマンドの解釈に Bourne shell を使うからです。 このように Bourne shell が極めて頻繁にかつ広範囲で使われているため、 素早く起動できて確実に動作し、メモリを少ししか消費しないということが 重要になります。 既存の実装は、 私たちに可能な限りこれらの多くの要求を同時に満足することができる最良のものです。 /bin/sh を小さいままに保つため、 私たちは他のシェルが持つ様々な便利な機能を提供していません。 Ports コレクションが bash や scsh、tcsh、zsh などの 多機能なシェルを含んでいるからです (これらのシェルすべての メモリ使用状況は、ps -u の VSZ や RSS の行で、あなた自身が確認することができます)。 libc.so.3.0 はどこにありますか? FreeBSD 2.1.x のシステムで 2.2 以降用の package を動かそうとしていますね? 前のセクションを読んで、システムに合った正しい port/package を入手してください。 Error: can't find libc.so.4.0 というメッセージが表示されるのですが。 何かの手違いで、4.X と 5.X のシステム用 package をダウンロードし、 FreeBSD 2.X、もしくは 3.X のシステムにインストールしてしまったのでしょう。 対応する正しいバージョンの package をダウンロードしてください。 386/486SX のマシンで ghostscript を動かすとエラーがでます。 あなたのマシンには数値演算プロセッサが搭載されていませんね? カーネルにコプロセッサの代わりとなる数値演算エミュレータを追加する必要があります。 以下のオプションをカーネルのコンフィグレーションファイルに追加して、 カーネルを再構築してください。 options GPL_MATH_EMULATE このオプションを追加する場合、 MATH_EMULATE の行を削除してください。 SCO/iBCS2 のアプリケーションを実行すると、 socksys で落ちてしまいます。 (FreeBSD 3.0 とそれ以前のみ) まず最初に /etc/sysconfig (または /etc/rc.conf, &man.rc.conf.5; 参照) の最後のセクションを編集し、 以下の変数を YES に直します。 # Set to YES if you want ibcs2 (SCO) emulation loaded at startup ibcs2=NO これでシステムの起動時に ibcs2 カーネルモジュールが読み込まるようになります。 次に /compat/ibcs2/dev/ を以下のように編集します。 lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 X0R@ -> /dev/null lrwxr-xr-x 1 root wheel 7 Oct 15 22:20 nfsd@ -> socksys -rw-rw-r-- 1 root wheel 0 Oct 28 12:02 null lrwxr-xr-x 1 root wheel 9 Oct 15 22:20 socksys@ -> /dev/null crw-rw-rw- 1 root wheel 41, 1 Oct 15 22:14 spx open や close の処理は、 socksys から /dev/null (&man.null.4; 参照) へシンボリックリンクを張ることで代用します。 残りの処理は、-CURRENT に入っているコードが担当しています。 これは以前のものより ずっとスッキリした方法です。 INN (インターネットニュース) の設定方法は? inn の package や port をインストールしたあとに Dave Barr's INN Page を見てみましょう。初心者向けの INN FAQ があります。 どのバージョンの Microsoft FrontPage を手に入れる必要がありますか? ルーク、ports を使うのだ! パッチ処理済みの Apache が ports ツリーから入手できます。 FreeBSD は Java をサポートしていますか? はい。 http://www.FreeBSD.org/java/ をご覧ください。 日本語訳 もあります。 3.x-STABLE を載せているマシンで port がコンパイルできないことがあります。それはどうしてですか? もし、その時点の -CURRENT か -STABLE に比べてずっと古いバージョンの FreeBSD を利用しているなら、 http://www.FreeBSD.org/ports/ にある ports アップグレードキットが必要です。 最新の FreeBSD を利用しているのに発生する場合はおそらく、 -CURRENT では正常なのに -STABLE ではうまく動かなくなるような変更がその port に対して行なわれ、受理されてしまっているのでしょう。 ports コレクションは -CURRENT と -STABLE、 両方のブランチで動かなければならないものですので、 もしそれを発見したら send-pr(1) コマンドを使ってバグレポートの提出をお願いします。 ld.so はどこにありますか? 3.1-R 以降などの Elf 化されたマシンで Netscape Navigator などの aout 形式のアプリケーションを動かすときには、 /usr/libexec/ld.so と aout ライブラリのファイルが必要です。 それらは配布物の compat22 に納められています。 /stand/sysinstall や compat22 サブディレクトリ内の install.sh を使って compat22 をインストールしてください。 合わせて 3.1-R と 3.2-R の ERRATA もお読みください。 ソースコードを更新しました。さて、インストール済みの ports を更新するにはどうすればよいでしょうか? 残念ながら、インストール済みの ports を更新する簡単な 方法はありません。pkg_version コマンドを 用いて ports ツリー中の新しいバージョンに更新する スクリプトを次のように生成することができます。 &prompt.root; pkg_version > /tmp/myscript 出力されたスクリプトを使う前に、手で 編集しなければなりません。現在のバージョンの pkg_version では、スクリプトの先頭に exit を挿入して強制しています。 スクリプトの出力には、更新された packages に依存する packages が記載されているので、保存しておきましょう。これらも やはり更新する必要があるかもしれません。通常、更新が 必要となるのは、共有ライブラリのバージョンが変化し、 そのライブラリを利用している ports が新しいライブラリを用いるために 再構築する必要がある場合です。 システムが常時稼動しているならば、 /etc/periodic.conf に weekly_status_pkg_enable="YES" を 設定して、&man.periodic.8 システムによって毎週更新が必要な ports の一覧を生成できます。 カーネルコンフィグレーション 訳: &a.jp.kiroh;、 1997 年 11 月 10 日 カーネルをカスタマイズしたいんですが、難しいですか? 全然難しくありません。 カーネルの再構築を調べてください。 うまく動作するカーネルができたら、 日付入りのカーネルのスナップショットを kernel.YYMMDD のように作成することをおすすめします。 こうしておけば、次にカーネルの構築をやってうまくいかなくなってしまっても、 kernel.GENERIC にわざわざ戻る必要がなくなります。 これは、GENERIC カーネルでサポートされないデバイスから起動している場合は、 特に重要です。 _hw_float が無いので、カーネルのコンパイルがうまくいきません。 推測ですけど、数値演算コプロセッサを持ってないからと思って、 npx0 (&man.npx.4; 参照) をカーネルコンフィグファイルから削除しちゃったんじゃないですか? npx0 は必須です。 コプロセッサがなくても、npx0 デバイスは削除してはいけません。 わたしのカーネルはどうしてこんなに大きい (10MB 以上) のでしょうか? これはデバッグモードでカーネルを構築していることが原因です。 デバッグモードで構築されたカーネルは、 デバッグに用いられる膨大なシンボル情報を含んでいるため、 カーネルのサイズが非常に大きくなります。 ただし FreeBSD 3.0 とそれ以降のシステムの場合は カーネルのサイズは小さくなりますし、 デバッグカーネルを実行する時のパフォーマンスの低下もありません。 また、そのカーネルはシステムがパニックした場合に有用です。 しかし、容量の小さなディスクでシステムを運用していたり、 単にデバッグカーネルを実行したくない場合は、 以下の両方が当てはまっているかどうか確認してください。 カーネルコンフィグファイルに以下の行が書かれていないこと。 makeoptions DEBUG=-g config を実行する際、 オプションを付けていないこと。 上に書かれた指定は両方ともカーネルをデバッグモードで構築するためのものです。 上の手順を従っている限り、カーネルを普通に構築してサイズの小さなカーネルを得ることができます。 その場合のカーネルサイズは、およそ 1.5MB から 2MB 程度になります。 マルチポートシリアルのコードで割り込みが衝突しています。 Q. マルチポートシリアルを サポートするコードを含んだカーネルをコンパイルしようとすると、 最初のポートだけ検出され、 残りのポートは割り込みの競合のためスキップされたと言われます。 どうやったらいいでしょうか? A. ここでの問題は、FreeBSD にはハードウェアまたはソフトウェアの競合により、 カーネルがクラッシュするのを防ぐコードが含まれているという点です。 解決するには、最初のポートにだけ IRQ の設定を書き、 残りは IRQ の設定を削除します。 以下に例を示します。 # Multiport high-speed serial line - 16550 UARTS # device sio2 at isa? port 0x2a0 tty irq 5 flags 0x501 vector siointr device sio3 at isa? port 0x2a8 tty flags 0x501 vector siointr device sio4 at isa? port 0x2b0 tty flags 0x501 vector siointr device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr カーネルを構築にいつも失敗します。 GENERIC カーネルも構築できません。 さまざまな理由が考えられます。以下、順に列記します。 あなたは新しい make buildkernel や make installkernel ターゲットを使わず、 現在走っているシステムを構築した時と異なるソースツリーを 構築しようとしている (たとえば、4.0-RELEASE のシステム上で 4.3-RELEASE を構築しようとしている) のではないでしょうか? もしシステムをアップグレードしようとしているのなら、 /usr/src/UPDATING ファイルを 共通項目 (COMMON ITEMS) 節に注意しながら最後までお読みください。 あなたは新しい make buildkernel や make installkernel ターゲットを 使っているのにも関わらず、 make buildworld を行なっていないのではないでしょうか? make buildkernel ターゲットは、 make buildworld ターゲットによって作られるファイルに依存しています そのため、make buildkernel が正常に終了するためには make buildworld ターゲットが正常に完了している必要があります。 構築しようとしているのが FreeBSD-STABLE だったとしても、あなたが入手したソースツリーが何らかの理由で 書き換わったり、壊れてしまっているのかも知れません。 FreeBSD-STABLE はほとんどの場合、きちんと構築できるようになっていますが、 確実に構築可能であることが保証されているのは リリース版だけです。一度ソースツリーを再取得して、 問題が解決しないかどうか試してみてください。 また、あるサーバから取得した時に問題が発生したら、 別のサーバを試すのも効果があるかも知れません。 システム管理 訳: にしか nishika@cheerful.com、 1997 年 11 月 12 日 システムスタートアップファイルはどこにあるのですか? FreeBSD 2.0.5R から 2.2.1R までは、 プライマリコンフィグレーションファイルは /etc/sysconfig にあります。 オプションはすべてこのファイルで設定され、他の /etc/rc (&man.rc.8; 参照) および /etc/netstart といった ファイルはこれを読み込むだけです。 ファイル /etc/sysconfig を見て、システムに適合するように変更してください。 このファイルには、 それぞれの場所に何を書けばいいのかを表すコメントがたくさん書かれています。 FreeBSD 2.2.2 から 3.0 までのシステムでは、 /etc/sysconfig は、 より分りやすい名前の &man.rc.conf.5; に改名され、それに従って書式もいくぶん改められています。 /etc/netstart も /etc/rc.network に改名され、 全部のファイルを cp /usr/src/etc/rc* /etc で一度にコピーすることが出来るようになります。 FreeBSD 3.1 とそれ以降では、 /etc/rc.conf が /etc/defaults/rc.conf に移動しました。 このファイルを編集してはいけません! 代わりに、 /etc/defaults/rc.conf の中で変えたいエントリの行を /etc/rc.conf にコピーし、 そこで変更するようにしてください。 たとえば named を起動したいとしましょう。 FreeBSD 3.1 かそれ以降のシステムで FreeBSD 付属の DNS サーバを起動するには、次のようにするだけです。 &prompt.root; echo named_enable="YES" >> /etc/rc.conf FreeBSD 3.1 かそれ以降でローカルサービスを起動するためには、 /usr/local/etc/rc.d ディレクトリにシェルスクリプトを置きます。 シェルスクリプトは起動可能に設定し、ファイル名が .sh で終わっていなければなりません。 FreeBSD 3.0 とそれ以前のリリースでは、 /etc/rc.local を編集する必要があります。 ファイル /etc/rc.serial はシリアルポートの初期化 (たとえばポートの設定を固定したり等々) のためにあります。 ファイル /etc/rc.i386 は iBCS2 エミュレーションのような Intel アーキテクチャ固有の設定や、 PC システムコンソール設定のためにあります。 簡単にユーザを追加するにはどうすればいいのですか? &man.adduser.8; コマンドを使用してください。 また、&man.pw.8; コマンドを用いることで、さらに細かい操作が可能です。 ユーザを削除するには &man.rmuser.8; コマンドを使用してください。 繰り返しになりますが、pw でも構いません。 FreeBSD システムに新しいハードディスクを追加するには? www.FreeBSD.org に書かれているディスクフォーマットチュートリアルを参照してください。 新しいリムーバブルドライブを持っていますが、どうやって使うの? そのリムーバブルドライブが ZIP であれ EZ drive であれ (あるいはもしそういう風に使いたいのなら、フロッピーであれ)、 またハードディスクであれ、一旦システムにインストールされて認識され、 カートリッジ、フロッピー等々が挿入されていれば、 ことはどのデバイスでも全く同じように進みます。 (このセクションはMark Mayo's ZIP FAQ に基づいています) ZIP ドライブやフロッピーで、すでに DOS のファイルシステムで フォーマットしてある場合、次のコマンドを使うことができます。 これはフロッピーの場合です。 &prompt.root; mount -t msdos /dev/fd0c /floppy 出荷時の設定の ZIP ディスクではこうです。 &prompt.root; mount -t msdos /dev/da2s4 /zip その他のディスクに関しては、&man.fdisk.8; や /stand/sysinstall を使って、 どのようにレイアウトされているか確かめてください。 以降は ZIP ドライブが 3 番目の SCSI ディスクで、 da2 と認識されている場合の例です。 他人と共有しなければならないフロッピーやリムーバブルディスク でなければ、BSD ファイルシステムを載せてしまうのが良い考えでしょう。 ロングファイル名もサポートされ、パフォーマンスは少なくとも 2 倍は向上しますし、おまけにずっと安定しています。 まず最初に、DOS レベルでのパーティション / ファイルシステムを無効にしておく必要があります。使用するのは fdisk でも /stand/sysinstall でも結構です。 複数のオペレーティングシステムを入れることを考慮する 必要がないような容量の小さなドライブの場合は、 次のように FAT パーティションテーブル (スライス) 全体を飛ばして、BSD のパーティション設定を行うだけで良いでしょう。 &prompt.root; dd if=/dev/zero of=/dev/rda2 count=2 &prompt.root; disklabel -Brw da2 auto 複数の BSD パーティションをつくる場合、 disklabel か /stand/sysinstall を使います。 固定ディスク上にスワップ領域を加える場合、 そういうことをしたいと思うのはもっともですが、 ZIP のようなリムーバブルドライブの上ではそういう考えは不適切 でしょう。 最後に、新しいファイルシステムをつくります。ディスク全体を使用する ZIP ドライブの場合は、以下のようにします。 &prompt.root; newfs /dev/rda2c 次にマウントします。 &prompt.root; mount /dev/da2c /zip また、次のような行を /etc/fstab (&man.fstab.5; 参照) に入れておくのも良い考えでしょう。 mount /zip と入力するだけでマウントできるようになります。 /dev/da2c /zip ffs rw,noauto 0 0 自分の crontab ファイルを編集した後 root: not found のようなメッセージが延々と表示されるのですが、 これはなぜですか? これは通常、システム crontab (/etc/crontab) を編集し、&man.crontab.1; を使ってインストールした場合に起こります。 &prompt.root; crontab /etc/crontab この方法は正しくありません。 システム crontab のフォーマットは &man.crontab.1; が更新する各ユーザの crontab とは異なります (フォーマットの相違点の詳細は &man.crontab.5; で説明されています)。 もしこのような操作をしてしまったなら、 あらたな crontab は誤ったフォーマットの /etc/crontab のコピーになってしまっているからです。 以下のコマンドで削除してください。 &prompt.root; crontab -r 今度 /etc/crontab を編集する時は、 その変更を &man.cron.8; に伝えるような操作をしてはいけません。 &man.cron.8; は、自動的にその変更を認識するからです。 もしあなたが何かを一日一回、あるいは一週間や一ヶ月に一回だけ 実行させたいなら、シェルスクリプトを /usr/local/etc/periodic に追加し、 &man.periodic.8; コマンドにシステムの cron スケジュールから 他の定期的なシステムのタスクとともに 実行させたほうが良いかもしれません。 このエラーの実際の原因は、システム crontab には どのユーザ権限でコマンドを実行するかを指定する余分なフィールドがあることによるものです。 FreeBSD に添付されている標準のシステム crontab には、 すべてのエントリに root が書かれています。 この crontab が root ユーザの crontab (システム crontab とは 異なります) として使われた場合、&man.cron.8; は root を実行するコマンドの最初の単語だと認識しますが、 そのようなコマンドは存在しないのです。 &man.su.1; コマンドを実行して root になろうとすると、 su が you are not in the correct group to su root と警告します。 これは、セキュリティ上の機能です。su コマンドを実行して root (またはスーパーユーザ権限を持つ 他のアカウント) になるには、wheel グループに所属していなければなりません。この機能がないと、 システムにアカウントがあって root の パスワードを見つけさえすれば、誰でもスーパーユーザ権限で システムにアクセスできてしまいます。この機能がある場合は、 必ずしもそうはなりません。wheel グループに 所属していなければ、&man.su.1; がパスワードの入力すら 拒否するからです。 誰かが root に su できるように するには、その人を wheel グループに追加してください。 rc.conf やその他の スタートアップファイルを書き間違えてしまいました。 しかもそのためファイルシステムがリードオンリーになってしまっていて 編集ができません。どうすればいいですか? シェルのパス名を入力するプロンプトが表示されたときに、 単に ENTER を押し、mount / を 実行してそルートファイルシステムを再マウントさせます。 また、お気に入りのエディタがあるファイルシステムを マウントするために mount -a -t ufs を する必要があるかも知れません。あなたのお気に入りのエディタが ネットワークファイルシステム上にある場合は、 ネットワークファイルシステムをマウントする前にネットワークを 手動で設定するか、&man.ed.1; のようなローカルファイルシステムにある エディタを使うかしなければなりません。 &man.vi.1; や &man.emacs.1; の様なフルスクリーンエディタを 使うつもりなら export TERM=cons25 と やってエディタが &man.termcap.5; データベースから正しい データを読み取れるようにしなければなりません。 これを行ったあとはいつもと同様、 /etc/rc.conf を編集して間違いを訂正することができるようになります。 カーネル起動メッセージの直後に表示されたエラーメッセージには、 問題の起こったファイル内での行番号を表示されているはずです。 どのようにしたら DOS の拡張パーティションをマウントできますか? DOS 拡張パーティションは、 すべての基本パーティションの後に認識されます。 たとえば、2台目の SCSIドライブの拡張パーティションに E パーティションがあるとしますと、 これは /dev に「スライス 5 」のスペシャルファイルを作る必要があり、 /dev/da1s5 としてマウントされます。 &prompt.root; cd /dev &prompt.root; ./MAKEDEV da1s5 &prompt.root; mount -t msdos /dev/da1s5 /dos/e 他のシステムのファイルシステムを FreeBSD でマウントすることはできますか? Digital UNIX: UFS CDROM は直接 FreeBSD でマウントすることができます。 Digital UNIX やそれ以外のシステムのサポートする UFS のディスクパーティションをマウントすることはもっと複雑なことで、 オペレーティングシステムのディスクパーティションの詳細に依存します。 Linux: 2.2 以降は ext2fs パーティションをサポートします。 マニュアルの &man.mount.ext2fs.8; を見てください。より多くの情報があります。 NT: FreeBSD 用の読みだしのみ可能な NTFS ドライバがあります。 詳しくは、Mark Ovens 氏によって書かれたチュートリアル http://ukug.uk.freebsd.org/~mark/ntfs_install.html をご覧ください。 この問題について他の情報があれば、他の人から感謝されるでしょう。 どのようにしたら FreeBSD を NT ローダーから起動させることができますか? この手順は 2.2.x と (起動が 3 つのステージに分かれている) 3.x のシステムとで多少異なります。 FreeBSD のネイティブルートパーティションの最初のセクタをファイルにして DOS/NT パーティション上に置くという画期的なアイディアがあります。 ファイル名を c:\bootsect.bsd (c:\bootsect.dos からの発想です) としたとします。 c:\boot.iniファイルを次のように編集します。 [boot loader] timeout=30 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS [operating systems] multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" C:\BOOTSECT.BSD="FreeBSD" C:\="DOS" この手順は、利用しているシステムが 2.2.x であり、DOS、NT、FreeBSD あるいはその他のオペレーティングシステムがすべて、 同じディスクのそれぞれの fdisk パーティションにインストールされていることを想定しています。 この例は、DOS と NT を最初の fdisk パーティションにおき、 FreeBSD は 2 番目においたシステムで確認しています。 また、FreeBSD は MBR を使わずに、 ネイティブパーティションから起動するように設定してあります (訳注: FreeBSD のインストールで、ブートマネジャを使わずに標準 MBR を使う場合に相当します)。 (もし NTFS に変換してしまっているなら)DOS フォーマットのフロッピーディスクか FAT パーティションを /mnt に DOS マウントします。 &prompt.root; dd if=/dev/rda0a of=/mnt/bootsect.bsd bs=512 count=1 再起動して DOS か NT に切替えます。NTFS ユーザは bootsect.bsd や bootsect.lnx をフロッピーディスクから C:\ へコピーします。 boot.ini のファイル属性 (パーミッション) の変更を以下のように行ないます。 > attrib -s -r c:\boot.ini 上の例の boot.ini で示したような正しいエントリを加え、 ファイル属性を元に戻します。 > attrib +s +r c:\boot.ini FreeBSD が MBR から起動するようになっている場合、 それぞれのネイティブパーティションから起動するように設定した後で、 DOS から fdisk コマンドを実行して元に戻してください。 FreeBSD 3.X における手順は、これよりいくぶん簡単です。 FreeBSD が NT 起動パーティションとして同じディスクにインストールされている場合には、 /boot/boot1 を単純に C:\BOOTSECT.BSD へコピーします。 もし FreeBSD が異なったディスクにインストールされている場合には、 /boot/boot1 では動作しませんので、 /boot/boot0 が必要です。 ここで /boot/boot1 の代わりに /boot/boot0 をコピーするようなことをしてはいけません! そうすると、パーティションテーブルを上書きしてしまい、 コンピュータが起動できなくなってしまいます。 /boot/boot0 をインストールするには、 sysinstall のブートマネージャを利用するかどうか尋ねられる画面で FreeBSD ブートマネージャを選択する必要があります。 /boot/boot0 のパーティションテーブル部分は NULL 文字で埋められているのですが、 sysinstall は /boot/boot0 を MBR にコピーする前にパーティションテーブルをきちんとコピーしてくれるからです。 FreeBSD ブートマネージャは最後に起動した OS を記録するために パーティションテーブルの最後に起動した OS のエントリにあるアクティブフラグをセットし、512 バイト全体を MBR に書き戻します。 これは /boot/boot0 を C:\BOOTSECT.BSD にコピーし、 エントリの一つにアクティブフラグをセットして空のパーティションテーブルを MBR に書き込むことと同じです。 FreeBSD と Linux を LILO から起動するには? FreeBSD と Linux が同じディスクにインストールされている場合、 単に Linux 以外の OS を起動するための LILO のインストール手順に 従えばいいだけです。非常に簡単にではありますが、記してみましょう。 Linux を起動し、/etc/lilo.conf に以下の行を加えて ください。 other=/dev/hda2 table=/dev/hda label=FreeBSD (上記の手順は FreeBSD のスライスが Linux から /dev/hda2 という名前で見えていると仮定しています。 あなたの設定にあわせてください) その後、lilo を root で実行すれば完了です。 FreeBSD が別のディスクにインストールされているのなら、 LILO のエントリに loader=/boot/chain.b を追加してください。たとえば、このようになります。 other=/dev/dab4 table=/dev/dab loader=/boot/chain.b label=FreeBSD 場合によっては、二つ目のディスクを正しく起動するために FreeBSD ブートローダに BIOS ドライブ番号を指定する必要があるかもしれません。 たとえば、FreeBSD SCSI ディスクが BIOS によって BIOS ディスク 1 として認識されるのなら、 FreeBSD のブートローダのプロンプトで、次のように指定する必要があります。 Boot: 1:da(0,a)/kernel FreeBSD 2.2.5 やそれ以降の版では、&man.boot.8; を設定すれば 起動時に上記のことが自動的に行えます。 Linux+FreeBSD mini-HOWTO が FreeBSD と Linux とを相互に使えるようにするためのよい参考資料になるでしょう。 FreeBSD と Linux を BootEasy から起動するには? LILO をマスターブートレコード (MBR) ではなく Linux の起動パーティションにインストールしてください。 これで BootEasy から LILO を起動できるようになります。 Windows95 と Linux を使用している場合は、 いずれにせよ後者の方がおすすめです。 Windows95 を再インストールする必要にかられたとき、 Linux を起動可能に戻す手続きが簡単ですむからです (Windows95 は偏屈なオペレーティングシステムで、 マスターブートレコード (MBR) から他のオペレーティングシステムを追い払ってしまうのです)。 「危険覚悟の専用 (dangerously dedicated) ディスク」は健康に悪いの? インストール作業中、 ハードディスクのパーティションを切る際に 2 つの方法を選ぶことができます。 デフォルトの方法では、fdisk のテーブルエントリ (FreeBSD ではスライスと呼ばれる) を使って、 自身のパーティションを使用する FreeBSD のスライスを、 同じマシンの他のオペレーティングシステムと互換性のある形にします。 それに付随して、ブートセレクタをインストールすれば、 ディスク上の使用可能なオペレーティングシステムを切り替えることができます。 もう一つの方法はディスクすべてを FreeBSD で使うというもので、 この場合ほかのオペレーティングシステムとの互換性を考慮しないことになります。 では、なぜこれが 「危険覚悟の」と言われるのでしょう? このモードのディスクが、通常の PC のユーティリティが有効な fdisk テーブルと見なす情報を持っていないからです。 ユーティリティの出来如何によりますが、 そのようなディスクを発見したとき、 警告を出すものもあります。また、もっと悪い場合、 確認も通告もなしに BSD のブートストラップにダメージを与えるものもあるでしょう。 さらには、「危険覚悟の」ディスクレイアウトは多数の BIOS、 AWARD (たとえば HP Netserver や Micronics システム、 他多数で使用されていた) や Symbios/NCR (人気のあるSCSI コントローラ 53C8xx 用) などを混乱させることが分かっています。 これは完全なリストではありません。 他にもまだまだあります。この混乱の兆候は、 起動時にシステムがロックするというだけでなく、 FreeBSD のブートストラップが自分自身を見つけられないために表示する read error というメッセージなどにも現れることでしょう。 そもそもいったいなぜこのモードがあるのでしょうか? これはわずかに数キロバイトのディスク容量を節約するのみであり、 新規インストールで実際に問題を生ずるのです。 「危険覚悟の」モードの起源は新しい FreeBSD インストーラでの、 BIOS から見えるディスクの 「ジオメトリ」の値とディスク自身との整合性という、 もっとも一般的な問題のひとつを回避したいという要求が背景にあります。 「ジオメトリ」は時代遅れの概念ですが、 未だに PC BIOS とディスクへの相互作用の中核をなしています。 FreeBSD のインストーラがスライスを作る時、 ディスク上のスライスを BIOS が見つけられるように、 スライス位置をディスク上に記録します。それが誤っていれば、 起動できなくなってしまうでしょう。 「危険覚悟の」モードはこれを、 問題を単純にすることで回避しようとします。 状況によってはこれでうまくいきます。 しかし次善の策として使われているに過ぎません。 この問題を解決するもっと良い方法はいくらでもあるのです。 では、 インストール時に「危険覚悟の専用」モードが必要になる 状況を回避するにはどうすればよいのでしょうか? まず BIOS が報告するディスクのジオメトリの値を覚えておくことからはじめましょう。 boot: プロンプトで を指定するか、ローダで boot -v と指定して、 起動時にカーネルにこの値を表示させることができます。 インストーラが起動する直前に、 カーネルがジオメトリ値のリストを表示するでしょう。 パニックを起こさないでください。 インストーラが起動するのを待ち、 逆スクロールでさかのぼって値を確認してください。 普通は BIOS ディスクユニット番号は、 FreeBSD がディスクを検出する順序と同様であり、 最初に IDE、次に SCSI となります。 ディスクをスライシングする際に、 FDISK の画面で表示されるディスクのジオメトリが正しいこと (BIOS の返す値と一致しているか) を確認してください。 万一異なっていたら g を押して修正してください。 ディスクにまったくなにもない場合や、 他のシステムから持ってきたディスクの場合は これを行なう必要があるかもしれません。 これはそのディスクから起動させようとしている場合にのみ、 問題になることに注意してください。 FreeBSD はそのディスクをうまい具合いに他のディスクと区別してくれます。 ディスクのジオメトリについて BIOS と FreeBSD 間で一致させることができたら、この問題はほぼ解決したと思ってよいでしょう。 そしてもはや「危険覚悟の専用」モードは必要ありません。 しかし、まだ起動時に恐怖の read error メッセージが出るようであれば、 お祈りを捧げて新しいディスクを買いましょう。 もう失うものは何もありません。 「危険覚悟の専用ディスク」を通常の PC での使用法に戻すには、 原則として 2 つ方法があります。1 つは十分な NULL バイトを MBR に書き込んで、 きたるべきインストーラにディスクはまっさらだと思い込ませる方法です。 たとえば、こんな感じです。 &prompt.root; dd if=/dev/zero of=/dev/rda0 count=15 また、マニュアルには書かれていない DOS の「機能」 > fdisk /mbr は、BSD ブートストラップを追い払ってくれる上に、 新しいマスターブートレコードをインストールしてくれます。 どのようにしたらスワップ領域を増やせますか? スワップパーティションのサイズを増やすのが最良の方法ですが、 別のディスクを追加しなくて済むという利点のある方法があります。 経験から得た一般的な方法はメインメモリの 2倍程度のスワップ領域を とるというものです。しかしごく小さなメインメモリしかない場合は、 それ以上のスワップを構成したいと思うでしょう。また、将来のメモリの アップグレードに備え、後でスワップの構成を変更する必要がないように 十分なスワップを構成しておくことは良い考えです。 スワップを別のディスク上に追加することは、単純に同じディスク上 にスワップを追加する場合よりも高速に動作するようになります。 例に挙げれば、あるディスク上のソースをコンパイルしているとして、 スワップが別のディスク上に作られていれば、これらが同じディスク上 にある場合よりも断然速いです。SCSI ディスクの場合は特にそうだと言えます。 ディスクが複数ある場合、スワップパーティションを各ディスクに 作るように構成すると、使用中のディスク上にスワップを置いたとしても、 通常の場合は有益です。一般的に、システムにある高速なディスクには スワップを作るようにすべきでしょう。 FreeBSD はデフォルトでインターリーブなスワップデバイスを 4つまで サポートします。複数のスワップパーティションを構成する際に、 普通はそれらを大体同じくらいの大きさにして作りたいところですが、 カーネルのコアダンプを取るのに都合が良いようにメインの スワップパーティションを大きめにとる人もいます。 メインのスワップパーティションはカーネルのコアがとれるように 最低でも実メモリと同じ大きさにすべきでしょう。 IDE ドライブは同時に同じチャネル上の複数のドライブには アクセスできません (FreeBSD は mode 4 をサポートしていないので、 すべての IDE ディスク I/O は programmed です)。 IDE の場合であってもやはり、スワップを別のハードディスク上に 作成することをおすすめします。 ドライブは実に安いものです、心配するだけ無駄です。 NFS 越しにスワッピングさせる方法は、 スワップ用のローカルディスクが無い場合にのみ推奨されます。 NFS 越しのスワッピングは遅く、FreeBSD 4.x より前のリリースでは 効率が悪いのですが、4.0 以降ではそれなりに高速になります。 そうはいっても、利用できるネットワークの太さに制限されますし、 NFS サーバに余計な負荷がかかります。 これは 64MBの vn-swap を作る例です (ここでは /usr/swap0 としますが、もちろん好きな名前を使うことができます)。 カーネルが次の行を含むコンフィグファイルから構成されているかを 確認します。GENERIC カーネルには、この行が含まれています。 pseudo-device vn 1 #Vnode driver (turns a file into a device) vn デバイスを作ります &prompt.root; cd /dev &prompt.root; sh ./MAKEDEV vn0 スワップファイルを作ります (/usr/swap0) &prompt.root; dd if=/dev/zero of=/usr/swap0 bs=1024k count=64 スワップファイルに適切なパーミッションを設定します &prompt.root; chmod 0600 /usr/swap0 /etc/rc.conf でスワップファイルを有効化させます swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired. マシンを再起動します スワップファイルをすぐに有効化させたいのなら以下のようにタイプします。 &prompt.root; vnconfig -e /dev/vn0b /usr/swap0 swap プリンタのセットアップで問題があります ハンドブックのプリンタの部分を参照してください。 探している問題のほとんどが書かれているはずです。 FreeBSD ハンドブックの「プリンタの利用」をご覧ください。 プリンタによっては、印刷するのにホスト側にドライバが 必要です。これら WinPrinters と呼ばれるものは、 素の FreeBSD では使えません。DOS や Windows NT 4.0 で動作しない なら、そのプリンタはおそらく WinPrinter でしょう。 ただし、唯一の希望が残されています。 ports/print/pnm2ppa の port が 対応しているかどうか確認してみてください。 パッケージの説明にはこう書いてあります。
このソフトウェアは PPA (printer performance architecture) プロトコルの出力を行います。このプロトコル は HP の "Windows 専用" プリンタの一部に使われています。 そのなかには、HP Deskjet 820C シリーズ、HP DeskJet 720 シリーズ、および HP DeskJet 1000 シリーズがあります。(略) WWW: http://pnm2ppa.sourceforge.net/
私のシステムのキーボードマッピングは間違っています。 kbdcontrol プログラムは、 キーボードマップファイルを読み込むためのオプションを備えています。 /usr/share/syscons/keymaps の下にたくさんのマップファイルがあります。 システムに関連のあるものを一つ選んで、ロードしてください。 &prompt.root; kbdcontrol -l uk.iso /usr/share/syscons/keymaps と拡張子 .kbd は、どちらも &man.kbdcontrol.1; によって使用されます。 これは /etc/sysconfig (または &man.rc.conf.5;) 中で設定することができます。 このファイル中にあるそれぞれのコメントを参照してください。 FreeBSD 2.0.5R やそれ以降の版では、 テキストフォントやキーボードマッピングに関係のあるものはすべて、 /usr/share/examples/syscons の中におさめられています。 現在以下のマッピングがサポートされています。 Belgian ISO-8859-1 Brazilian 275 keyboard Codepage 850 Brazilian 275 keyboard ISO-8859-1 Danish Codepage 865 Danish ISO-8859-1 French ISO-8859-1 German Codepage 850 German ISO-8859-1 Italian ISO-8859-1 Japanese 106 Japanese 106x Latin American Norwegian ISO-8859-1 Polish ISO-8859-2 (programmer's) Russian Codepage 866 (alternative) Russian koi8-r (shift) Russian koi8-r Spanish ISO-8859-1 Swedish Codepage 850 Swedish ISO-8859-1 Swiss-German ISO-8859-1 United Kingdom Codepage 850 United Kingdom ISO-8859-1 United States of America ISO-8859-1 United States of America dvorak United States of America dvorakx 起動時に、unknown: <PNP0303> can't assign resources というメッセージが表示されるのですが? 以下は、freebsd-current メーリングリストへの投稿からの 抜粋です。
&a.wollman;, 2001 年 4 月 24 日 can't assign resources というメッセージは、 そのデバイスがレガシー ISA デバイスで、PnP を意識していない ドライバがカーネルに組み込まれていることを示します。 これには、キーボードコントローラ、プログラム可能な 割り込み制御 IC やその他さまざまな標準的なデバイスが あります。リソースが割り当てられないのは、既にそのアドレスを 使っているドライバがあるからです。
ユーザディスククォータが正常に動作していないようです。 / にはディスククォータを設定しないでください。 クォータファイルが置かれるファイルシステム上に クォータファイルを置くようにしてください。 Filesystem Quota file /usr /usr/admin/quotas /home /home/admin/quotas … … わたしの ccd は、 何が適合していない (Inappropriate) のでしょう? 次のような症状が現れます。 &prompt.root; ccdconfig -C ccdconfig: ioctl (CCDIOCSET): /dev/ccd0c: Inappropriate file type or format 通常この現象はタイプを「未使用 (unused)」のまま放っておかれた c パーティションをつなげようとした場合に現れます。ccd ドライバは FS_BSDFFS タイプをベースとするパーティションを要求します。 つなげようとしているディスクのディスクラベルを編集して、 パーティションのタイプを 4.2BSD に変更してください。 どうしてわたしの ccd のディスクラベルを変更することができないのでしょう? 次のような症状が現れます。 &prompt.root; disklabel ccd0 (it prints something sensible here, so let's try to edit it) &prompt.root; disklabel -e ccd0 (edit, save, quit) disklabel: ioctl DIOCWDINFO: No disk label on disk; use "disklabel -r" to install initial label これは ccd から返されるディスクラベルが、 実はディスク上にはないまったくの偽の情報だからです。 これを明示的に書き直すことで問題を解消できます、 それには、つぎのようにします。 &prompt.root; disklabel ccd0 > /tmp/disklabel.tmp &prompt.root; disklabel -Rr ccd0 /tmp/disklabel.tmp &prompt.root; disklabel -e ccd0 (this will work now) FreeBSD は System V の IPC プリミティブをサポートしますか? はい。 FreeBSD は System-V スタイルの IPC をサポートします。 共有メモリ、メッセージ、セマフォが含まれます。 以下の行をカーネルコンフィグファイルに加えると、 サポートが有効になります。 options SYSVSHM # enable shared memory options SYSVSEM # enable for semaphores options SYSVMSG # enable for messaging FreeBSD 3.2 とそれ以降では、 これらのオプションがあらかじめ GENERIC カーネルに含まれていますので、 あなたのシステムにはすでに組み込まれています。 カーネルを再構築してインストールしてください。 UUCP でメールを配送するには sendmail をどう使えばよいのですか? FreeBSD に付属している sendmail は、 インターネットに直接つながっているサイトにあわせて設定してあります。 UUCP 経由で mail を交換したい場合には sendmail の設定ファイルを改めてインストールしなければなりません。 /etc/sendmail.cf を自分の手で改造するのは純粋主義者のやるような事です。 sendmail の version 8 は &man.m4.1; のようなプリプロセッサを通して設定ファイルを生成する新しいアプローチを取っており、 より抽象化されたレベルの設定ファイルを編集します。 /usr/src/usr.sbin/sendmail/cf ディレクトリの中にある設定ファイルを使用してください。 もしすべてのソースをインストールしていない場合には sendmail の設定ツールは、別の tar ファイルにまとめてあります。CD-ROM が mount されている場合には、次のようにしてください。 &prompt.root; cd /cdrom/src &prompt.root; cat scontrib.?? | tar xzf - -C /usr/src contrib/sendmail これはたった数 100Kbyte ですから心配ないでしょう。 cf ディレクトリにある README に、m4 での設定の基本的な説明があります。 UUCP での配送のためには、mailertable を使用すれば よいでしょう。これによって、sendmail が配送方式を決定するデータベースを 作成することができます。 まずはじめに、 .mc ファイルを作成しなければなりません。 /usr/src/usr.sbin/sendmail/cf/cf というディレクトリが、 これらのファイルを作成する場所です。既にいくつか例があると思います。 これから作成するファイルの名前を foo.mc とすると、 sendmail.cf を求めているような形式に変換するには、 次のようにしてください。 &prompt.root; cd /usr/src/usr.sbin/sendmail/cf/cf &prompt.root; make foo.cf &prompt.root; cp foo.cf /etc/sendmail.cf 標準的な .mc ファイルは次のようになります。 include(`../m4/cf.m4') VERSIONID(`Your version number') OSTYPE(bsd4.4) FEATURE(nodns) FEATURE(nocanonify) FEATURE(mailertable) define(`UUCP_RELAY', your.uucp.relay) define(`UUCP_MAX_SIZE', 200000) MAILER(local) MAILER(smtp) MAILER(uucp) Cw your.alias.host.name Cw youruucpnodename.UUCP nodns と nocanonify という指定をすることで、 mail の配送に DNS を使用しなくなります。 UUCP_RELAY という 行に関しては、 ある理由から必要ですがそれは聞かないでください。 .UUCP で終わる仮想ドメインを処理することのできるインターネット上での ホスト名をここに書いてください。通常は、ISP の mail リレーホストを 書くことになると思います。 これが終了したら、次に /etc/mailertable というファイルが必要です。標準的な例は次のとおりです。 # # makemap hash /etc/mailertable.db < /etc/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: 見れば分かるように、これは実在する設定のファイルです。はじめの 3 行はドメイン名で指定されたメールが default の経路で配送されずに、 「近道」するために UUCP で隣りのサイトに送るための特別な状況を 処理するものです。 次の行は Ethernet でつながっているローカルのドメインに対しては SMTP で送るための設定です。 最後に、UUCP での隣りのサイトが .UUCP で終わる仮想ドメインの書式で 指定されており、default の rule を uucp-neighbour! recipient で上書きするためのものです。一番最後の行はいつもドットを一つ書きます。 これは、ここまでの行でマッチしなかったすべてのホストにマッチし、 このサイトから世界に向けて出ていくための mail gateway に UUCP で配送するためのものです。 uucp-dom: に続けて書かれているノード名は、 uuname コマンドで指定することによって UUCP で直接配送される正しいノード名でなければなりません。 最後に、このファイルは使用する前に DBM データベースのファイルに 変換する必要があります。これを行なうコマンドラインは mailertable の最初のコメントに書いてあります。mailertable を変更した時には、 必ずこのコマンドを実行してください。 最後のヒントです: もし特定のメール配送がうまく作動するかどうか 確かめたい場合には、sendmail の オプションを 使用してください。このオプションによって sendmail は アドレステストモードで起動します。 0 の後に配送したいアドレスを書いてください。最後の行に、実際に使用される mail agent、この mail agent で送られる送信先のホスト、そして (多分変換されている) アドレスが表示されます。このモードを抜けるには Control-D を押してください。 &prompt.user; sendmail -bt ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) Enter <ruleset> <address> > 0 foo@interface-business.de rewrite: ruleset 0 input: foo @ interface-business . de ... rewrite: ruleset 0 returns: $# uucp-dom $@ if-bus $: foo \ < @ interface-business . de > > ^D ダイアルアップでインターネットに接続する環境でメールをセットアップするにはどうやるの? 静的に IP アドレスが割り当てられる場合は、 デフォルトの状態を変更する必要はありません。 割り当てられた名前をホストネームと するだけで、sendmail が後のことを引き受けてくれます。 ダイアルアップ ppp をインターネット接続に使用し、動的に IP アドレスが割り当てられる場合は、 インターネットサービスプロバイダ (ISP) のメールサーバにメールボックスがあるはずです。 ISP のドメインが myISP.com で、あなたのユーザ名が user だと仮定します。 また、あなたが自分のマシンを bsd.home と呼んでおり、ISP が relay.myISP.com をメールリレーとして使用できると言っているとしましょう。 メールボックスからメールを取ってくるためには、 回収 (retrieval) エージェントをインストールする必要があります。 Fetchmail は多種多様なプロトコルをサポートしているのでお勧めです。 ISP が使用しているのは、大抵 POP3 プロトコルです。 ユーザ ppp を使用している場合、 /etc/ppp/ppp.linkup に以下のように記述すると、 インターネットと接続が完了した時点で自動的にメールを取得するようになります。 MYADDR: !bg su user -c fetchmail ローカルでないアカウントにメールを配送するのに sendmail を使用している場合 (後述)、 上に示したエントリの後に !bg su user -c "sendmail -q" を記述します。これはネットワーク接続が確立したらすぐに sendmail に溜っている mailqueue を強制的に処理させるようにします。 この例では、user が bsd.home にアカウントを持ち、 bsd.home 上の user のホームディレクトリに、以下のような .fetchmailrc ファイルがつくられていることを想定しています。 poll myISP.com protocol pop3 fetchall pass MySecret; 言うまでもなく、このファイルは user 以外のユーザが読むことが出来ないようにしなくてはなりません。 内容にパスワード MySecret が含まれているからです。 正しい from: ヘッダをつけてメールを送るためには、 sendmail に user@bsd.home ではなく user@myISP.com を使用するよう教える必要があります。 メールをより早く転送するために、すべてのメールを relay.myISP.com へ送るように sendmail に 指示しておくのも良いでしょう。 上の要件を満たすには、以下のような .mc ファイルが適しています。 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(`myISP.com')dnl FEATURE(allmasquerade)dnl FEATURE(masquerade_envelope)dnl FEATURE(nocanonify)dnl FEATURE(nodns)dnl define(`SMART_HOST', `relay.myISP.com') Dmbsd.home define(`confDOMAIN_NAME',`bsd.home')dnl define(`confDELIVERY_MODE', `deferred')dnl .mc ファイルから sendmail.cf への変換方法については、 前のセクションを参照してください. sendmail.cf を更新した後に sendmail をリスタートするのもお忘れなく。 この UID が 0 の toor という アカウントとは何ですか? 危険にさらされているのでしょうか? 心配無用です。toor は 代替の スーパーユーザーアカウントです (toor は root を逆に綴ったものです)。 以前は、&man.bash.1; シェルがインストールされた時に 作成されていましたが、現在は標準で作成されています。 このユーザーが作成されるのは、 スーパーユーザが非標準のシェルを使う場合を想定しており、 root の標準のシェルを変更しなくてもよくなっています。 基本配布に含まれていないシェル (たとえば ports や packages からインストールされるシェル) は、デフォルトでは別のファイルシステムに存在する 可能性のある /usr/local/bin に インストールされることが多いので、これは重要です。 root のシェルが /usr/local/bin にあり、 /usr (または、/usr/local/bin があるいずれかのファイルシステム) が何らかの理由でマウントされていないとすると、 root は問題を解決するために ログインすることができません (シングルユーザーモードで再起動すれば、 シェルのパスの入力を促されるのですが)。 toor を日々の root の仕事を 非標準のシェルで行うために使い、root は シングルユーザーモードや緊急時のために、標準のシェルのままに している人がいます。何もしなければ、パスワードを無効にしてあるので toor ではログインできません。 使いたいなら、root でログインして toor の パスワードを設定しましょう。 しまった! root のパスワードを忘れてしまった! 慌てないでください! 単にシステムを再起動し、 シングルユーザモードに移るために Boot: と表示されるプロンプトで boot -s と入力してください (FreeBSD の 3.2 より前のリリースでは -sとなります)。 どのシェルを使うのかという質問には、ENTER キーを押してください。&prompt.root; に移ることができるでしょう。 mount -u / と入力して ルートファイルシステムの読み書きを再マウントし、 mount -a と入力して、 すべてのファイルシステムをマウントし直した後、 passwd root と入力して root のパスワードを設定し直してください。 その後、exit と入力すれば、起動が続けられます。 Control-Alt-Delete でシステムが再起動しないようにするにはどうすればいい? FreeBSD 2.2.7-RELEASE 以降で syscons (デフォルトのコンソールドライバ) を使用している場合には、次の行をカーネルコンフィグレーションファイルに追加して カーネルを再構築し、インストールしてください。 options SC_DISABLE_REBOOT FreeBSD 2.2.5-RELEASE 以降で PCVT コンソールドライバを使用している 場合には、同様に次の行をカーネルコンフィグレーションファイルに追加して カーネルを再構築し、インストールしてください。 options PCVT_CTRL_ALT_DEL 上にあげたものよりも古い FreeBSD の場合、 現在コンソールが使用しているキーマップを編集し、 キーワード boot を nop に書き換えてください。 /usr/share/syscons/keymaps/us.iso.kbd にあります。 その変更を反映させようとして、 このキーマップのロードを明示的に行なうために、 /etc/rc.conf を実行すべきかもしれません。 もちろん他の国のキーマップを使っているのであれば、 代わりにそのキーマップファイルを編集してください。 DOS のテキストファイルを UNIX のテキストファイルに整形するにはどうすればいい? 単に次の perl コマンドを実行してください。 &prompt.user; perl -i.bak -npe 's/\r\n/\n/g' file ... file の部分には処理するファイルを指定してください。 整形後のファイルは元のファイル名で作成され、 整形前のファイルはバックアップとして元の ファイル名の末尾に拡張子 .bak のつけられた名前で作成されます。 あるいは &man.tr.1; コマンドを使うこともできます。 &prompt.user; tr -d '\r' < dos-text-file > unix-file dos-text-file は DOS 形式のテストファイル、 unix-file には変換された出力が格納されます。 perl を使うよりほんのちょっぴり速くなります。 名前で指定してプロセスにシグナルを送るにはどうすればいい? &man.killall.1; を使ってください。 su が not in root's ACL と言って私を悩ませるのはなぜ? Kerberos の認証システムからくるエラーです。 この問題は致命的なものではなく、 うっとおしいといったものです。 su に オプションをつけて起動するか、 次の質問で説明されている方法で Kerberos をアンインストールしてください。 Kerberos をアンインストールするにはどうすればいいの? システムから Kerberos を削除するには、 あなたの動かしているリリースの bin ディストリビューションを再インストールしてください。 もし CDROM を持っているのなら、 その CDROM をマウント (マウントポイントは /cdrom と仮定) して、 次のように入力してください。 &prompt.root; cd /cdrom/bin &prompt.root; ./install.sh 疑似ターミナルを追加するには? telnet、ssh、X、screen をたくさん利用されている場合、 疑似ターミナルが足りなくなっている可能性があります。 これを増やすには次のようにします。 次の行をカーネルコンフィグレーションファイルに追加して pseudo-device pty 256 新たにカーネルを作りインストールします。 次のコマンドを実行して &prompt.root; cd /dev &prompt.root; ./MAKEDEV pty{1,2,3,4,5,6,7} 新たなターミナル用の 256 個のデバイスノードを作ります。 /etc/ttys を編集し 256 個のターミナルごとの定義を追加します。 既存のエントリーの形式にあわせる必要があるでしょう。 たとえばこんな感じです。 ttyqc none network 正規表現を使った指定は tty[pqrsPQRS][0-9a-v] となります。 新しいカーネルでシステムを再起動すると完了です。 snd0 デバイスを作成することができません! snd というデバイスは存在しません。 この名前は、FreeBSD サウンドドライバによって作成されるさまざまなデバイス、 mixer や sequencer、 dsp などを総称したものです。 これらのデバイスを作成するには、次のようにする必要があります。 &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd0 再起動せずにもう一度 /etc/rc.conf を読み込んで /etc/rc を開始させるには? シングルユーザモードに移行して、 マルチユーザモードに戻ってください。 コンソールで次のように実行します。 &prompt.root; shutdown now(注: や は付けません) &prompt.root; return &prompt.root; exit 砂場 (sandbox) とは何ですか? 砂場 (Sandbox) とはセキュリティ用語の一つで、 次の二つの意味があります。 一つ目は、「仮想的な『防壁』で囲まれているプロセス」です。 その『防壁』は、そのプロセスに侵入した第三者が、 さらにシステムの広い範囲に影響を与えることを防ぐように設計されます。 このプロセスの振舞いは、『防壁』の中だけに制限される、と表現できます。 つまり、このプロセスにおいて、『防壁』を越えるようなコードの実行は できないという意味です。そのため、コードの実行におけるセキュリティは 確かなものであると保証でき、実行の詳細な追跡を行なう必要はなくなります。 その『防壁』とは、たとえばユーザ ID がそれにあたるでしょう。 この定義は、security(7) や named(8) のマニュアルページで用いられています。 ntalk サービス (/etc/inetd.conf 参照のこと) を例にとってみます。 このサービスはかつて、実行時の ユーザ ID として root を用いていましたが、現在では tty というユーザ ID で動作します。 ユーザ tty は、 ntalk を経由してシステムの侵入に成功した第三者が そのユーザ ID 以上の権限を得ることを、 より一層困難にするために設計された砂場 (sandbox) なのです。 二つ目は「シミュレートされたマシンの内側で実行されるプロセス」のことで、 こちらはより中核的です。 普通に考えれば、あるプロセスに侵入することができる第三者は、 マシンのより広い範囲にも侵入できると信じるものなのですが、 この種のプロセスの場合、それは実際にはシミュレートされたマシンに 侵入しただけなので、現実のデータを変更することは何一つできません。 これを実現するための最も広く用いられている方法は、 シミュレートされた環境をサブディレクトリに構築し、 そのディレクトリに chroot して、そのディレクトリで プロセスを実行すること (つまり、そのプロセスにとって / は システムの実際のルートディレクトリ / ではなく、 chroot されたサブディレクトリを指す) です。 広く用いられているもう一つの方法があります。 それは、既に存在しているファイルシステムを 読み込み専用 (read-only) でマウントし、その上に、あるプロセスに対して そのファイルシステムが書き込み可能であるように見せるような、 もう一つのファイルシステムの層を用意するものです。すると、 そのプロセスはファイルを書き込むことができると認識し、 実際に書き込むことができるのもその特定のプロセスだけ - システムにある他のプロセスは書き込めないのに対して - であるという状況を実現することができます。 この種の砂場 (sandbox) は、 その非常に透過的な性質を使って、ユーザ (もしくは侵入者) が その事実に気付かないように実現されます。 UNIX は、内部的に二つの砂場 (sandbox) を実装しています。 一つはプロセスレベルのもの、もう一つはユーザ ID レベルのものです。 UNIX プロセスはすべて、他の UNIX プロセスから完全に隔離されています。 どのプロセスも、他のプロセスのアドレス空間を変更することはできません。 これは、あるプロセスが他のプロセスのアドレス空間を上書きできるような、 クラッシュにつながる行為が容易に実現できる Windows とは全く異なるものです。 UNIX プロセスは、特定のユーザ ID が所有します。 もし、実行者のユーザ ID が root ユーザのものでなければ、 ユーザ ID は、他のユーザが所有するプロセスから そのプロセスを守る機能を果たすわけです。 また、そのユーザ ID は、ディスク上にあるデータを 保護するのにも使われています。 セキュアレベル (securelevel) って何ですか? セキュアレベルとはカーネルに実装されているセキュリティ機構の一つです。 簡単に言うと、カーネルはセキュアレベルが正の値の時に、 ある特定の操作を制限します。この制限は、たとえスーパユーザ (root のこと) であっても例外ではありません。 この文を書いている時点では、 セキュアレベル機構を使って以下のような操作を制限することができます。 schg (system immutable flag) のようなファイルフラグの変更 /dev/mem および /dev/kmem 経由でのカーネルメモリへの書き込み カーネルモジュールのロード &man.ipfirewall.4; ルールの変更 稼働中のシステムでセキュアレベルの状態をチェックするには、 次のコマンドを実行します。 &prompt.root; sysctl kern.securelevel 出力には、&man.sysctl.8; 変数 (今の場合は kern.securelevel) と数字が現れます。 数字が現在のセキュアレベルの値です。 これがもし正の値なら、 何らかのセキュアレベルによる制限が有効になっています。 システム稼働中にセキュアレベルを下げることはできません。 これは、それを可能にするとセキュアレベルの意味がなくなってしまうからです。 セキュアレベルが正の値でないことを要求する操作 (たとえば installworld や日付の変更など) を行なう必要がある場合は、/etc/rc.conf にあるセキュアレベルの設定 (kern_securelevel と kern_securelevel_enable という変数) を変更して再起動する必要があります。 セキュアレベルに関する詳しい情報や、 各レベルで実現される機能に関しては &man.init.8; のマニュアルページを参照してください。 セキュアレベルは万能というわけではなく、 弱点も数多く存在します。また、場合によっては、 セキュリティを低下させてしまうこともあります。 最も大きな問題の一つに、 セキュアレベルの機能を有効にするには、 起動処理でセキュアレベルが設定されるまでに使われるすべてのファイルを 保護する必要があるということがあります。 もし攻撃者が、システムがセキュアレベルを設定する前にコードを実行することができるとしたら、 セキュアレベルによる保護は無意味になってしまいます (起動時には低いセキュアレベルでしか実行できない処理を行なう必要があるため、 セキュアレベルの設定は、起動処理の最後の方で行なわれます)。 起動処理で使われるすべてのファイルを保護することは技術的に不可能です。 もしそうできたとしても、システムの保守はまさに悪夢となるでしょう。 設定ファイル一つ書き換えるのにも、 シングルユーザモードに切替えなければならなくなるのですから。 以上で説明した内容やその他の点については、 メーリングリストでも良く話題にのぼります。 議論のようすをこのページから検索してみてください。 セキュアレベルは、 いずれより粒度の細かい機構にとって代わるだろうと考えている人々もいますが、 その点についてはまだ不透明なままです。 どうか注意するようにしてください。 フロッピーや CDROM や他のリムーバブルメディアのマウントを一般ユーザーに許可するには? 一般ユーザーでもデバイスをマウントできるようにすることができます。 手順は次のとおりです。 root になって、 sysctl 変数である vfs.usermount を 1 に設定します。 &prompt.root; sysctl -w vfs.usermount=1 root になって、 リムーバブルメディアに関連するブロックデバイスに適切なパーミッションを設定します。 例として、最初のフロッピーデバイスをユーザーがマウントできるようにするには、 次のようにします。 &prompt.root; chmod 666 /dev/fd0 operator グループに所属するユーザが CDROM ドライブをマウントできるようにするには 以下のようにします。 &prompt.root; chgrp operator /dev/cd0c &prompt.root; chmod 640 /dev/cd0c 最後に vfs.usermount=1 という行を /etc/sysctl.conf ファイルに追加し、 ブート時にセットされるようにしておきます。 これで、すべてのユーザは フロッピー /dev/fd0 を 自身の所有するディレクトリへマウントすることができます。 &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t msdos /dev/fd0 ~/my-mount-point これで、operator グループに所属するユーザは CDROM /dev/cd0c を 自身の所有するディレクトリへマウントすることができます。 &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t msdos /dev/cd0c ~/my-mount-point デバイスのアンマウントは簡単です。 &prompt.user; umount ~/my-mount-point しかし、 vfs.usermount を有効にすることは、セキュリティ上よいことではありません。 MSDOS 形式のメディアにアクセスには、Ports コレクションにある パッケージ mtools を使用した方がよいでしょう。 システムを新しい巨大ディスクへ移すにはどうするのですか? 一番良いのは新しいディスクに OS を再インストールして、 それからユーザデータを移すことです。特にあなたが -stable を 複数のリリースを跨いで追い掛けている場合にはこの方法をおすすめします。 あなたは &man.boot0cfg.8; を使うことで booteasy を両方の ディスクにインストールでき、新しい配置で満足している間 デュアルブートができます。これを行ったあとデータを移す 方法を探すなら次の段落は読み飛ばしてください。 何もないディスクへインストールしないことに決めたならば /stand/sysinstall、なり &man.fdisk.8; と &man.disklabel.8; なりを使って新しいディスクに パーティションとディスクラベルを作らなければなりません。 また &man.boot0cfg.8; で booteasy を両方のディスクに インストールして、コピーの作業が終わったあとに 古いシステムからでも新しいディスクからでも起動できるように しておく必要があります。この作業の詳細は formatting-media tutorial を見てください。 新しいディスクの立ち上げが終わってデータの移動を 待つばかりになりました。しかし悲しいかな、無闇やたらと コピーすればいいというものではありません。デバイスファイル (/dev) やシンボリックリンクなどは 失敗の元になります。これらを理解するツール、すなわち &man.dump.8; や &man.tar.1; 等を使う必要があります。 データの移転はシングルユーザで行うことをお勧めしますが、 絶対と言うわけではありません。 あなたは &man.dump.8; と &man.restore.8; 以外のもので root ファイルシステムを移行してはなりません。 &man.tar.1; コマンドでもたぶんうまく行くでしょうが、 やらないほうがいいでしょう。パーティション一つを もう一つのからのパーティションに移すときは &man.dump.8; と &man.restore.8; 使うべきです。 パーティションのデータを新しいパーティションに移すのに dump を使うやり方は以下の通りです。 新しいパーティションに newfs をかける。 それを暫定的なマウントポイントにマウントする。 そのディレクトリに cd。 古いパーティションを dump し、 その出力をパイプで新しい方へ。 たとえば root を /dev/ad1s1a へ、暫定的なマウントポイントを /mnt として移そうとすると以下のようになります。 &prompt.root; newfs /dev/ad1s1a &prompt.root; mount /dev/ad1s1a &prompt.root; cd /mnt &prompt.root; dump 0uaf - / | restore xf - もしパーティションの構成を変えようと思っているなら - つまり一つだったものを二つにしたり二つだったものをくっつけたり しようとしているなら、自前であるディレクトリ以下のすべてを 新しい場所へ移す必要が出てくるかも知れません。&man.dump.8; は ファイルシステムに働くのでこの目的には使えません。この場合は &man.tar.1; を使います。一般に /old から /new への移動は &man.tar.1; で 以下のようにします。 &prompt.root; (cd /old; tar cf - .) | (cd /new; tar xpf -) /old に他のファイルシステムが マウントされていて、そのデータの移動までは考えてないならば 最初の &man.tar.1; に 'l' フラグを追加します。 &prompt.root; (cd /old; tar clf - .) | (cd /new; tar xpf -). tar のかわりに cpio(1) や pax(1)、cpdup (ports/sysutils/cpdup) 等を 使っても構いません。 システムを最新の -STABLE にアップデートしようとしたのですが -RC や -BETA になってしまいました! 何が起こったのですか? 短い答え: ただの名前です。RC は リリース候補 (Release Candidate) に 由来するもので、リリースが間近であることを意味します。 また、FreeBSD における -BETA は通常、 リリース前のコードフリーズ期間に入っているという意味になります。 長い答え: FreeBSD はそのリリースを 2 ヶ所あるうちの 一方から派生させます。3.0-RELEASE や 4.0-RELEASE の様な (0 のマイナー番号を持つ) メジャーリリースは、一般に -CURRENT と呼ばれる 開発版の流れから分岐させられてできます。3.1-RELEASE や 4.2-RELEASE などのマイナーリリースはアクティブな -STABLE ブランチ (枝) の スナップショットでした。 4.3-RELEASE からは、リリース毎にブランチが作成されるように なりました。ものすごく保守的な開発速度 (主にセキュリティ 勧告のみ) を求めている人は、このブランチを追跡すると よいでしょう。 リリースを作る時になるとそれを分岐させるブランチは 特定のプロセスへ突入します。そのプロセスの一つは コードフリーズ (コードの凍結) です。コードフリーズが 始まると、そのブランチの名前がリリースになろうとしていることを 反映するものに変えられます。たとえば、4.0-STABLE と 呼ばれていたブランチは名前が 4.1-BETA へと 変えられ、コードフリーズとリリース前のテストが 始まったことを示します。 バグの修正はリリースの一部としてコミットされます。 ソースコードがリリースの形を取ったなら名前が 4.1-RC へと 変えられ、それからリリースが作られることを示します。 ひとたび RC のステージになってしまうと、発見された もっとも致命的なバグの修正しかできなくなります。 ひとたびリリースが (この例では 4.1-RELEASE) 作られれば、 そのブランチは 4.1-STABLE と改名されます。 新しいカーネルを入れようとしたのですが、 chflags に失敗します。どうすれば良いのでしょう? 簡単な回答: 多分、セキュアレベルが 0 より大きくなっているのでしょう。 直接シングルユーザモードで再起動して、 カーネルをインストールしてください。 詳しい回答: FreeBSD では、セキュアレベルが 0 より大きい場合、 システムフラグの変更が禁止されます。 現在のセキュアレベルは、次のコマンドを使って調べることができます。 &prompt.root; sysctl kern.securelevel セキュアレベルを下げる操作は、できないようになっています。 そのため、カーネルをインストールするには、 シングルユーザモードで起動するか、/etc/rc.conf のセキュリティ設定を変更して再起動する必要があります。 セキュアレベルの詳細は &man.init.8; を、 rc.conf の詳細は /etc/defaults/rc.conf および、 &man.rc.conf.5; のマニュアルページをご覧ください。 システムの時刻を 1 秒以上変更することができないのです! どうすれば良いのでしょう? 簡単な回答: 多分、セキュアレベルが 1 より大きくなっているのでしょう。 直接シングルユーザモードで再起動して、 時刻の変更をしてください。 詳しい回答: FreeBSD では、セキュアレベルが 1 より大きい場合、 1 秒以上の時刻変更が禁止されます。 現在のセキュアレベルは、次のコマンドを使って調べることができます。 &prompt.root; sysctl kern.securelevel セキュアレベルを下げる操作は、できないようになっています。 そのため、システムの時刻を変更するには、 シングルユーザモードで起動するか、/etc/rc.conf のセキュリティ設定を変更して再起動する必要ばあります。 セキュアレベルの詳細は &man.init.8; を、 rc.conf の詳細は /etc/defaults/rc.conf および、 &man.rc.conf.5; のマニュアルページをご覧ください。 &man.rpc.statd.8; にメモリリークを見つけました! メモリを 256 メガバイトも使っています。 いいえ。それはメモリリークではありませんし、 256 メガバイトのメモリを使っている、ということでもありません。 おそらく (ほとんどの場合)、 処理に都合が良いように非常にたくさんの量のメモリを そのプロセスのアドレス空間にマッピングしているのでしょう。 技術的な見地から考えても、これは大きな害があることではなく、 単に &man.top.1; や &man.ps.1; といったツールの表示に影響がある程度です。 &man.rpc.statd.8; は、(/var にある) ステータスファイルを自分のアドレス空間にマッピングします。 マッピングは、後で大きな空間が必要になった時に再マッピングしないで済むよう、 非常に大きなサイズを指定して行なわれます。 これは、ソースコードに含まれる &man.mmap.2; 関数のマッピング長を示す引数に 0x10000000 が指定されていることからも分かります。 この数字が IA32 アーキテクチャの持つアドレススペース全体の 16 分の 1、すなわち、ちょうど 256 メガバイトに相当するのです。 X Window System と仮想コンソール 訳: &a.motoyuki; 1997 年 11 月 13 日 X を動かしたいのですが、どうすればいいのですか? もっとも簡単な方法は FreeBSD のインストールの際に X を動かすことを指定するだけです。 それから xf86config ツールのドキュメントを読んでこれに従ってください。 このツールはあなたのグラフィックカードやマウスなどに合わせて XFree86(tm) の設定を行うのを助けてくれます。 Xaccel サーバーについて調べてみるのもいいでしょう。 詳しくは Xi Graphics について か Metro Link をご覧ください。 X を実行しようとして startx と入力したのですが、 KDENABIO failed (Operation not permitted) というエラーが表示されます。 何かおかしなことをやってしまったんでしょうか? あなたのシステムは高いセキュアレベルで運用されていますね? 実は、高いセキュアレベルで X を起動することはできないのです。 どうしてなのかについては、&man.init.8; のマニュアルページに書かれています。 では、代わりにどうすれば良いのかお答えしましょう。 基本的に 2 つの方法があります。 一つはセキュアレベルを 0 にする (通常、これは /etc/rc.conf で指定します) こと、 もう一つは起動時 (セキュアレベルを上げる前) に &man.xdm.1; を実行するかです。 起動時に &man.xdm.1; を実行する方法の詳細については、 を参照してください。 私のマウスはなぜ X で動かないのでしょうか? syscons (デフォルトのコンソールドライバ) を使っているのであれば、 それぞれの仮想スクリーンでマウスポインターをサポートするように FreeBSD を設定できます。X でのマウスの衝突を避けるために、syscons は /dev/sysmouse という仮想デバイスをサポートしています。 本物のマウスデバイスから入力されたすべてのマウスのイベントは、 moused を経由して sysmouse デバイスへ出力されます。 一つ以上の仮想コンソールと X の 両方で マウスを使いたい場合、 を参照して moused を設定してください。 そして、/etc/XF86Config を編集し、 次のように書かれていることを確認してください。 Section Pointer Protocol "SysMouse" Device "/dev/sysmouse" ..... 上の例は、XFree86 3.3.2 以降の場合の例です。 それより前のバージョンでは、 Protocol という部分を MouseSystems と置き換える必要があります。 X で /dev/mouse を使うのを好む人もいます。 この場合は、 /dev/mouse を /dev/sysmouse (&man.sysmouse.4; 参照) にリンクしてください。 &prompt.root; cd /dev &prompt.root; rm -f mouse &prompt.root; ln -s sysmouse mouse わたしのマウスにはホイール機能が付いているのですが、X で使うことはできますか? はい、もちろん使えますが、そのためには X クライアントプログラムを適切に設定する必要があります。これについては、 Colas Nahaboo 氏のウェブページ(http://www.inria.fr/koala/colas/mouse-wheel-scroll/) を参照してください。 imwheel というプログラムを使う場合は、 次のような簡単な手順にしたがってください。 ホイールイベントの変換 imwheel は、 マウスのボタン 4、ボタン 5 をキー押下イベントに変換するプログラムです。 そのためホイールマウスで利用するには、マウスホイールのイベントをボタン 4、 ボタン 5 のイベントに変換するマウスドライバを利用する必要があります。 この変換を行なうには二つの方法があります。 一つは &man.moused.8; で行なう方法、二つめは X サーバ自身に変換を行なわせる方法です。 ホイールイベントの変換に &man.moused.8; を使う &man.moused.8; にイベントを変換させるには、 &man.moused.8; 起動時にオプション を追加します。 たとえば、普段 &man.moused.8; を moused -p /dev/psm0 として起動しているなら、その代わりに moused -p /dev/psm0 -z 4 とします。 もし、 /etc/rc.conf を使って自動的に起動するように設定しているなら、 /etc/rc.conf の中の moused_flags という変数に を追加するだけです。 そして、5 ボタンマウスを使うことを X サーバに伝える必要があります。 これを行なうには /etc/XF86Config の Pointer セクションに Buttons 5 という行を追加するだけです。 そうすると /etc/XF86Config の Pointer は、 たとえば次のようになるでしょう。 moused による変換を利用してホイールマウスを 使用するための XFree86 3.3.x 系列の XF86Config の <quote>Pointer</quote> セクションの設定例 Section "Pointer" Protocol "SysMouse" Device "/dev/sysmouse" Buttons 5 EndSection 自動的なプロトコル認識機能およびボタン配置変換機能を 利用し、ホイールマウスを使用するための XFree86 4.x 系列の XF86Config の <quote>InputDevice</quote> セクションの設定例 Section "InputDevice" Identifier "Mouse1" Driver "mouse" Option "Protocol" "auto" Option "Device" "/dev/psm0" Option "Buttons" "5" Option "ZAxisMapping" "4 5" EndSection ホイールマウスで Emacs 上でのページスクロールを 行うための <quote>.emacs</quote> の設定例 ;; wheel mouse (global-set-key [mouse-4] 'scroll-down) (global-set-key [mouse-5] 'scroll-up) X サーバを使ったホイールイベントの変換 &man.moused.8; を起動していなかったり、 ホイールイベントの変換に &man.moused.8; を起動したくない場合には、その代わりに X サーバを使うことができます。 これには、/etc/XF86Config ファイルを書き換える必要があります。 まず最初に必要なのは、 マウスがどのプロトコルを使っているのかを確認することです。 ほとんどのホイールマウスは IntelliMouse プロトコルを使用していますが、 XFree86 サーバはその他のプロトコル、 たとえば Logitech MouseMan+ マウスが利用している MouseManPlusPS/2 プロトコルなどもサポートしています。 使用されているプロトコルが確認できたら Pointer セクションに Protocol の行を追加してください。 つぎに、 ホイールのスクロールイベントをマウスボタン 4、 マウスボタン 5 に割り当てることを X サーバに伝えます。 これを行なうには ZAxisMapping オプションを使用します。 たとえば、&man.moused.8; が起動していない状態で、 PS/2 マウスポートに IntelliMouse が接続されているとしたら /etc/XF86Config はおそらく次のようになります。 X サーバによる変換を利用してホイールマウスを使用するための XF86Config の <quote>Pointer</quote> セクションの設定例 Section "Pointer" Protocol "IntelliMouse" Device "/dev/psm0" ZAxisMapping 4 5 EndSection imwheel のインストール さて、つぎに Ports Collection から imwheel をインストールします。 これがあるのは x11 カテゴリです。 このプログラムは、 マウスイベントをキーボードイベントに変換します。 たとえば、マウスホイールを前に回した時、 imwheel は PageUp をアプリケーションプログラムに送るような動作をするわけです。 Imwheel はホイールイベントとキーボード押下の対応を設定ファイルを使って設定するため、 アプリケーション毎に異なる対応を持たせることも可能です。 imwheel のデフォルトの設定ファイルは /usr/X11R6/etc/imwheelrc にインストールされます。 これを ~/.imwheelrc にコピーして編集し、 お好きなように imwheel で利用したいアプリケーションの設定をカスタマイズしてください。 設定ファイルの書式は &man.imwheel.1; に説明されています。 Emacs で Imwheel を使うように設定する (必須ではありません) emacs や Xemacs で利用するには、 ~/.emacs にいくらか書き加える必要があります。 emacs の場合は次の部分を追加してください。 <application>Imwheel</application> を利用するための <application>Emacs</application> の設定例 ;;; For imwheel (setq imwheel-scroll-interval 3) (defun imwheel-scroll-down-some-lines () (interactive) (scroll-down imwheel-scroll-interval)) (defun imwheel-scroll-up-some-lines () (interactive) (scroll-up imwheel-scroll-interval)) (global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines) (global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines) ;;; end imwheel section Xemacs の場合は ~/.emacs に次の部分を追加してください。 <application>Imwheel</application> を利用するための <application>XEmacs</application> の設定例 ;;; For imwheel (setq imwheel-scroll-interval 3) (defun imwheel-scroll-down-some-lines () (interactive) (scroll-down imwheel-scroll-interval)) (defun imwheel-scroll-up-some-lines () (interactive) (scroll-up imwheel-scroll-interval)) (define-key global-map [(control meta \))] 'imwheel-scroll-up-some-lines) (define-key global-map [(control meta \()] 'imwheel-scroll-down-some-lines) ;;; end imwheel section Imwheel の実行 インストールが完了していれば、単に xterm (訳注: 日本語環境で広く使われている kterm でも構いません) から imwheel を入力するだけで起動できます。 起動するとバックグラウンドで動作し、すぐに利用できます。 imwheel をいつも使うように設定するには、 .xinitrc か .xsession のファイルにそのままコマンドを追加してください。 imwheel が PID ファイルに関する警告を表示するかも知れませんが、 無視しても危険はありません。この警告が意味を持つのは、 Linux 版の imwheel だけです。 X のメニューやダイアログボックスがうまく動きません。 Num Lock キーをオフにしてください。 Num Lock キーがデフォルトで起動時にオンになる場合は、 XF86Config ファイルの Keyboard セクションに以下の行を加えてもいいでしょう。 # Let the server do the NumLock processing. This should only be # required when using pre-R6 clients ServerNumLock 訳注 この問題は XFree86 3.2 以降では解決しています。 仮想コンソールとは何ですか? どうやったら使えますか? 仮想コンソールは、簡単にいうと、ネットワークや X を動かすなどの複雑なことを行なわずに、 いくつかのセッションを同時に行なうことを可能にします。 システムのスタート時には、 起動メッセージが出た後に login プロンプトが表示されます。そこで ログイン名とパスワードを入力すると 1 番目の仮想コンソール上で仕事 (あるいは遊び) を始めることができます。 他のセッションを始めたい場合もあるでしょう。 それは動かしているプログラムのドキュメントを見たり、 FTP の転送が終わるまで待つ間、 メールを読もうとしたりすることかもしれません。 Alt-F2 を押す (Alt キーを押しながら F2 キーを押す) と、 2 番目の「仮想コンソール」で ログインプロンプトが待機していることがわかります。 最初のセッションに戻りたいときは Alt-F1 を押します。 標準の FreeBSDインストールでは、 3 枚 (3.3-RELEASE では 8 枚) の仮想コンソールが有効になっていて、 Alt-F1、 Alt-F2、 Alt-F3 で仮想コンソール間の切替えを行ないます。 より多くの仮想コンソールを有効にするには、 /etc/ttys (&man.ttys.5; 参照) を編集して Virtual terminals のコメント行の後に ttyv4 から ttyvc の手前までのエントリを加えます (以下の例は先頭には空白は入りません)。 # /etc/ttys には ttyv3 がありますので # "off" を "on" に変更します。 ttyv3 "/usr/libexec/getty Pc" cons25 on secure ttyv4 "/usr/libexec/getty Pc" cons25 on secure ttyv5 "/usr/libexec/getty Pc" cons25 on secure ttyv6 "/usr/libexec/getty Pc" cons25 on secure ttyv7 "/usr/libexec/getty Pc" cons25 on secure ttyv8 "/usr/libexec/getty Pc" cons25 on secure ttyv9 "/usr/libexec/getty Pc" cons25 on secure ttyva "/usr/libexec/getty Pc" cons25 on secure ttyvb "/usr/libexec/getty Pc" cons25 on secure 多くするか少なくするかはあなたの自由です。 より多くの仮想ターミナルを使うとより多くのリソースを使うことになります。 8MB 以下のメモリしかない場合はこれは重要な問題です。 もし必要があれば secure を insecure に変更してください。 X を使いたいのであれば、 最低一つの仮想ターミナル (のエントリ) を使わずに残しておくか、 off にしておく必要があります。 つまり、12 個の Alt-ファンクションキーすべてでログインプロンプトを 出したいのならば、 残念ながら X は利用できないということです。 同じマシンで X サーバーも動かしたいのならば 11 個しか使えません。 仮想コンソールを無効にするもっとも簡単な方法は、 コンソールを off にすることです。 たとえば 12 個すべてのターミナルを割り当てている状態で X を動かしたいときは、 仮想ターミナル 12 を変更します。 ttyvb "/usr/libexec/getty Pc" cons25 on secure これを次のように変更します。 ttyvb "/usr/libexec/getty Pc" cons25 off secure キーボードにファンクションキーが 10 個しかないのであれば、 次のように設定します。 ttyv9 "/usr/libexec/getty Pc" cons25 off secure ttyva "/usr/libexec/getty Pc" cons25 off secure ttyvb "/usr/libexec/getty Pc" cons25 off secure (これらの行を消すだけでもいいです。) /etc/ttys を編集したら、 次は十分な数の仮想ターミナルデバイスを作らなくてはなりません。 もっとも簡単な方法を示します。 &prompt.root; cd /dev &prompt.root; ./MAKEDEV vty12 (12 個のデバイスをつくる場合) さて、仮想コンソールを有効にするもっとも簡単 (そして確実) な方法は、 再起動することです。しかし、再起動したくない場合は、 X ウィンドウシステムを終了させて次の内容を (root権限で) 実行します。 &prompt.root; kill -HUP 1 重要な点は、 このコマンドを実行する前に X ウィンドウシステムを完全に終了させておくことです。 もしそうしないと kill コマンドを実行した後、 システムはおそらくハングアップするでしょう。 X から仮想コンソールに切替えるにはどうすればよいのですか? 仮想コンソールへ戻るには Ctrl Alt Fn を使ってください。 最初の仮想コンソールへは Ctrl Alt F1 で戻れます。 テキストコンソールへ移った後は、その中で移動するのに 今度はいつもどおり Alt Fn を使ってください。 X のセッションへ戻るには X の走っている仮想コンソールへ 切り替える必要があります。もしあなたが X をコマンドラインから 実行していたのであれば (たとえば startx を使う) X のセッションはそれを実行したテキストコンソールではなく 最初の使われていない仮想コンソールに割り当てられているはずです。 あなたが仮想端末を 8 個用意している場合は X を 9 番目の コンソールにいるはずで、 Alt F9 を使うことになります。 訳注 X に戻るには、 3 枚の仮想コンソールが有効になっている場合は Alt-F4 です。 有効な仮想コンソールの数 +1 のファンクションキーの 位置に X が割り当てられます。 XDM を起動時に起動させるにはどうしますか? xdm の起動方法については二つの流派があります。 一方の流派では提供された例を使用して xdm を /etc/ttys (&man.ttys.5; 参照) から起動し、もう一方の流派では xdm を単に rc.local (&man.rc.8; 参照) または /usr/local/etc/rc.d においた X.sh スクリプトから起動します。 どちらも正しく、片方が動作しない場合は、もう片方が動作するでしょう。 どちらも場合でも結果は同じであり、X はグラフィカルな login: プロンプトを表示します。 ttys を利用する方法の利点は、 どの vty で X が起動したかの記録が残せることと、 ログアウト時に X サーバを再起動する責任を init に押しつけることができることでしょう。 rc.local からロードされる場合、 xdm は引数を持たずに (すなわち、デーモンとして) 起動します。 xdm は getty が起動した後にロードされなければなりません。 そうでないと、xdm は getty と衝突し、コンソールをロックアウトしてしまいます。 この問題に対処する最善の方法は、 起動スクリプト (訳注: rc.local のこと) で 10 秒ほどの sleep を実行させ、 その後に xdm をロードすることです。 /etc/ttys から xdm を起動させている場合には、 xdm と getty が衝突する可能性があります。 この問題を回避するには、/usr/X11R6/lib/X11/xdm/Xservers に vt 番号を追加してください。 :0 local /usr/X11R6/bin/X vt4 上の例は、/dev/ttyv3 を X サーバに対応させます。番号は 1 から始まりますので注意してください。 X サーバは vty を 1 から数えますが、 FreeBSD カーネルは vty を 0 から数えます。 xconsole を動かそうとすると Couldn't open console とエラーが出ます。 X を startx で起動しますと、/dev/console のパーミッションは 変更ができないようになっていますので、 xterm -C や xconsole は動きません。 これはコンソールのパーミッションが、 標準ではそのように設定されているからです。 マルチユーザシステムでは、 ユーザの誰もがシステムコンソールに書き込むことが可能である必要は必ずしもありません。 VTY を使い直接マシンにログインするユーザのために、 このような問題を解決するために &man.fbtab.5; というファイルがあります。 要点を述べると、次のような形式の行を /etc/fbtab (&man.fbtab.5; 参照) に加えます。 /dev/ttyv0 0600 /dev/console そうすると、 /dev/ttyv0 からログインしたユーザが コンソールを所有することになるでしょう。 わたしはいつも XFree86 を一般ユーザから起動していたのですが、 最近になって root ユーザでなければならないと言われるようになりました。 すべての X サーバは、 ビデオハードウェアに直接アクセスするために root ユーザで実行される必要があります。 古いバージョンの XFree86 (<= 3.3.6) に含まれるすべてのサーバは、 自動的に root 権限で実行されるように (root ユーザに setuid されて) インストールされます。 X サーバは大きく複雑なプログラムであり、 これは明らかにセキュリティを危険に晒す要因となります。 そのため新しいバージョンの XFree86 では、 サーバを root ユーザに seruid しないでインストールするようになりました。 X サーバを root ユーザで動かすというのは、 明らかにセキュリティ的に不適当で受け入れられないことです。 X を一般ユーザで実行するには、二つの方法があります。 一つは xdm や、その他のディスプレイマネージャ (たとえば kdm など) を使うこと、 もう一つは Xwrapper を使うことです。 xdm は、 グラフィカルなログイン画面を扱うデーモンです。 通常、起動時に実行され、 各ユーザの認証とユーザセションを開始させる機能を実現します。 基本的に、getty と login のグラフィック版、と考えて良いでしょう。 xdm の詳細については、 XFree86 関連文書 および FAQ 項目をご覧ください。 Xwrapper とは、X サーバ用のラッパ (wrapper) のことです。 これは必要なセキュリティを確保しつつ、一般ユーザが X サーバを実行できるようにした小さなユーティリティで、 コマンドライン引数の正当性チェックを行ない、 それを通過すれば適切な X サーバを起動します。 何らかの理由でディスプレイマネージャを使いたくない場合に これを使うと良いでしょう。 Ports Collection 全体をインストールしていれば、 /usr/ports/x11/wrapper にあります。 私の PS/2 マウスは X ウィンドウシステム上でうまく動きません。 あなたのマウスとマウスドライバがうまく同期していないからかもしれません。 FreeBSD 2.2.5 までのバージョンでは、X から仮想ターミナルへ切替えて、 また X へ戻ると再同期するかもしれません。 この問題がよく起きるようであれば、カーネルコンフィグレーション ファイルに次のオプションを書いてカーネルを再構成してみてください。 options PSM_CHECKSYNC もし、カーネルの再構築を行なったことがないのであれば、 カーネルを構築するの項を参照してください。 このオプションにより、 マウスとドライバの同期で問題が起きる可能性は少なくなるでしょう。 もしそれでもこの問題が起きるようならば、 再同期させるにはマウスを動かさないようにしておいて マウスボタンのどれかを押してください。 このオプションは残念ながらすべてのシステムで働くわけではなく、 また、PS/2 マウスポートにつながれているのが タップ (tap) 機能を持つ アルプス社製 GlidePoint デバイスの場合、 タップ機能が無効となってしまいます。 FreeBSD 2.2.6 以降のバージョンでは、 同期のチェック方法が少し改善されたので標準で有効になっています。 GlidePoint でもうまく働きます (同期チェックが標準の機能になったので PSM_CHECKSYNC オプションはこれらのバージョンからは削除されました)。 しかしながら、 まれにドライバが間違って (訳注: 問題がないのに) 同期に関して問題があると報告し、カーネルから psmintr: out of sync (xxxx != yyyy) というメッセージが出力されて、マウスが正しく動作していないように見える ことがあるかもしれません。 もしこのようなことが起こる場合には、PS/2 マウスドライバのフラグに 0x100 を指定して同期チェックを無効にしてください。システムの起動時に 起動オプションを与えて UserConfig に入ります。 boot: -c boot: UserConfig のコマンドラインで以下のように入力してください。 UserConfig> flags psm0 0x100 UserConfig> quit MouseSystems の PS/2 マウスがうまく動きません。 MouseSystems の PS/2 マウスのあるモデルは、 高解像度モードの場合にのみ正しく動作するということが報告されています。 それ以外のモードでは、 マウスカーソルがしょっちゅうスクリーン左上に行ってしまうかもしれません。 残念ながら FreeBSD 2.0.X や 2.1.X のバージョンでは、 この問題の解決する方法はありません。 2.2 から 2.2.5 のバージョンでは、 以下のパッチを /sys/i386/isa/psm.c に適用しカーネルの再構築を行なってください。 もし、カーネルの再構築を行なったことがないのであれば、 カーネルの構築の項を参照してください。 @@ -766,6 +766,8 @@ if (verbose >= 2) log(LOG_DEBUG, "psm%d: SET_DEFAULTS return code:%04x\n", unit, i); + set_mouse_resolution(sc->kbdc, PSMD_RES_HIGH); + #if 0 set_mouse_scaling(sc->kbdc); /* 1:1 scaling */ set_mouse_mode(sc->kbdc); /* stream mode */ FreeBSD 2.2.6 以降のバージョンでは、 PS/2 マウスドライバのフラグに 0x04 を指定してマウスを高解像度モードにします。 システムの起動時に 起動オプションを与えて UserConfig に入ります。 boot: -c UserConfig のコマンドラインで以下のように入力してください。 UserConfig> flags psm0 0x04 UserConfig> quit マウスに関する不具合の他の原因の可能性については、 直前のセクションも見てみてください。 X のアプリケーションを構築する時に、 imake can't find Imake.tmpl となります。どこにあるのでしょうか? Imake.tmpl は X の標準アプリケーション構築ツールである Imake パッケージの一部です。 Imake.tmpl は、 X アプリケーションの構築に必要な多くのヘッダファイルと同様に、 X のプログラムディストリビューションに含まれています。 sysinstall を使うか、 手動で X のディストリビューションファイルからインストールすることができます。 マウスのボタンを入れ替える方法はありますか? .xinitrc か .xsession で xmodmap というコマンドを実行してください。 スプラッシュスクリーンのインストールはどうするのですか。 どこで見つけることができますか? FreeBSD 3.1 のリリース直前に、起動メッセージの表示期間に いわゆる "スプラッシュ" スクリーンを表示させることができる新しい機能が追加されました。 いまのところスプラッシュスクリーンは 256 色のビットマップ (*.BMP) か ZSoft PCX (*.PCX) ファイルです。 それに加えて、標準の VGA アダプタでの動作させるには 320x200 以下の解像度である必要があります。 カーネルに VESA サポートを追加すれば 1024x768 までのより大きいビットマップを使用できます。 VESA サポートを有効化するにはまず、 カーネルが VM86 カーネルオプションとともにコンパイルされている必要があることに注意してください。 VESA サポートそのものは VESA カーネルコンフィグオプション によって直接カーネル中にコンパイルするか、 起動時に VESA kld モジュールを読み込ませることができます。 スプラッシュスクリーンを使うには、 FreeBSD の起動プロセスをコントロールするスタートアップファイルを書き換える必要があります。 これらのファイルは FreeBSD 3.2 のリリース以前に変更されましたので、 現在は、スプラッシュスクリーンを読み込む方法が二つあります。 FreeBSD 3.1 の場合 まず最初のステップは、 スプラッシュスクリーンのビットマップ版を探してくることです。 3.1-RELEASE では Windows のビットマップ形式のスプラッシュスクリーンだけをサポートしています。 お望みのスプラッシュスクリーンを見つけたなら、それを /boot/splash.bmp にコピーします。次に、これらの行が書かれた /boot/loader.rc ファイルが必要です。 load kernel load -t splash_image_data /boot/splash.bmp load splash_bmp autoboot FreeBSD 3.2 以降の場合 PCX 形式のスプラッシュスクリーンのサポートが追加されると同時に、 FreeBSD 3.2 には起動プロセスを設定する、 より洗練された方法が含まれています。 もしお望みなら、上に示した FreeBSD 3.1 用の方法を使うこともできます。 もしそうしたくて、かつ PCX 形式を使いたいなら、 splash_bmp を splash_pcx と読み換えてください。 そうではなくて、新しい起動設定方法を使うのなら、 次の数行が書かれた /boot/loader.rc ファイルと、 include /boot/loader.4th start 次の数行が含まれた /boot/loader.conf ファイルを作ることが必要です。 splash_bmp_load="YES" bitmap_load="YES" この例では、スプラッシュスクリーンとして /boot/splash.bmp を使うことを想定しています。PCX 形式のファイルを使う場合には、 そのファイルを /boot/splash.pcx にコピーして、 上で示したように /boot/loader.rc を作ります。 そして、次の内容の /boot/loader.conf というファイルを作ってください。 splash_pcx_load="YES" bitmap_load="YES" bitmap_name="/boot/splash.pcx" さて、あとはスプラッシュスクリーンを用意するだけです。 それには http://www.baldwin.cx/splash/ のギャラリーをサーフしてみてください。 X で Windows(tm) キーを使うことはできるのでしょうか? はい、もちろん。 どういう動作をするかについて定義するには &man.xmodmap.1; を使います。 標準的な "Windows(tm)" キーボードの場合、 対応するキーコードは 3 種類あります。 115 - 左の Ctrl と Alt の間にある Windows(tm) キー 116 - 右の Alt と Gr の間にある Windows(tm) キー 117 - 右の Ctrl の左隣にあるメニューキー 左にある Windows(tm) キーを押すとカンマ記号が入力されるようにするには、 こんな風にします。 &prompt.root; xmodmap -e "keycode 115 = comma" 設定を反映させるには、おそらくウィンドウマネージャを再起動する必要があります。 Windows(tm) キーのキーマップを X 起動時に毎回、 自動的に有効化するには xmodmap コマンドを ~/.xinitrc に追加するか、 もしくはおすすめできる方法として ~/.xmodmaprc というファイルを作成して、 そのファイルの一行一行に xmodmap のオプションを記述し、次の一行 xmodmap $HOME/.xmodmaprc を ~/.xinitrc に追加するという方法があります。 たとえば、先ほどあげた三つのキーを F13、F14、F15 に割り当てるとします。 こうしておけば、後ほど示すように、アプリケーションや ウィンドウマネージャの便利な機能を その三つのキーに簡単に割り当てることができます。 こうするには、次の内容を ~/.xmodmaprc に追加します。 keycode 115 = F13 keycode 116 = F14 keycode 117 = F15 たとえば fvwm2 を使っていたら、 F13 をカーソル下のウィンドウのアイコン化、 F14 をウィンドウの前面/背面化、 F15 を、あたかもデスクトップにカーソルが存在しないかのように、 メインワークスペース (アプリケーション) のメニューを呼び出せる機能に割り当てられます。 最後の機能は、そのデスクトップがまったく見えないときに便利です。 (また、キートップのロゴにもぴったりです) ~/.fvwmrc の次のエントリは、前述の 設定を実現します。 Key F13 FTIWS A Iconify Key F14 FTIWS A RaiseLower Key F15 A A Menu Workplace Nop ネットワーキング 訳: &a.jp.arimura;、 &a.jp.shou;、 にしか nishika@cheerful.com、 &a.jp.kiroh;、 1998 年 10 月 4 日 ディスクレスブート (diskless boot) に関する情報はどこで得られますか? ディスクレスブート (diskless boot) というのは、FreeBSD がネットワーク上で起動し、 必要なファイルを自分のハードディスクではなくてサーバから読み込むものです。 詳細については FreeBSD ハンドブックの「ディスクレスブート」を読んでください。 FreeBSD をネットワークのルータ (router) として使用することはできますか? インターネット標準やこれまでのよい経験によって指摘されている通り、 FreeBSD は標準ではパケットを転送 (forward) するように設定されていません。 しかし、 &man.rc.conf.5; の中で次の変数の値を YES とする事によってこの機能を有効にすることができます。 gateway_enable=YES # Set to YES if this host will be a gateway このオプションによって &man.sysctl.8; の変数 net.inet.ip.forwarding が 1 になります。 ほとんどの場合、 ルータについての情報を同じネットワークの他の計算機等に知らせるために、 経路制御のためのプロセスを走らせる必要があるでしょう。 FreeBSD には BSD の標準経路制御デーモンである &man.routed.8; が付属していますが、より複雑な状況に対処するためには GaTeD(http://www.gated.org/ から入手可能) を使用することもできます。 3_5Alpha7 において FreeBSD がサポートされています。 注意してほしいのは、FreeBSD をこのようにして使用している場合でも、 ルータに関するインターネット標準の必要条件を完全には満たしていない ということです。しかし、普通に使用する場合にはほとんど問題ありません。 Win95 の走っているマシンを、FreeBSD 経由でインターネットに接続できますか? 通常、この質問が出てくる状況は自宅に二台の PC があり、一台では FreeBSD が、もう一台では Win95 が走っているような場合です。 ここでやろうとしていう事は FreeBSD の走っている計算機をインターネット に接続し、Win95 の走っているマシンからは FreeBSD の走っているマシンを経由して接続を行なう事です。 これは二つ前の質問の特別な場合に相当します。 …で、答えは「はい」です。 FreeBSD 3.x のユーザモード ppp には オプションがあります。 ppp を オプション付きで起動し、 /etc/rc.conf にある gateway_enable を YES に設定します。 そして Windows マシンを正しく設定すれば、 きちんと動作するでしょう。 設定に関するさらに詳しい情報は、 Steve Sims 氏による Pedantic PPP Primer にあります。 カーネルモード ppp を利用する場合や、 インターネットとのイーサネット接続が利用できる場合は、 natd を利用する必要があります。 この FAQ の natd のセクションを参照してください。 ISC からリリースされている BIND の最新版はコンパイルできないんでしょうか? BIND の配布物と FreeBSD とでは cdefs.h というファイルの中でデータ型の矛盾があります。 compat/include/sys/cdefs.h を削除してください。 FreeBSD で SLIP と PPP は使えますか? 使えます。FreeBSD を用いて他のサイトに接続する場合には、 &man.slattach.8;、&man.sliplogin.8;、&man.ppp.8; そして &man.pppd.8; のマニュアルページをご覧ください。 &man.ppp.8; と &man.pppd.8; は、 PPP のサーバ、クライアント両方の機能を持っています。 その一方で、&man.sliplogin.8; は SLIP のサーバ専用で、 &man.slattach.8; は SLIP のクライアント専用です。 これらを使うためのさらなる情報については、ハンドブックの PPP と SLIP の章をご覧ください。 「シェルアカウント」を通じてのみインターネットへアクセス可能な場合、 slirp package みたいなものが欲しくなるかもしれませんね。 これを使えば、ローカルマシンから直接 ftp や http のようなサービスに (限定的ではありますが) アクセスすることができます。 FreeBSD は NAT か IP マスカレードをサポートしていますか? ローカルなサブネット (一台以上のローカルマシン) を持っているが、 インターネットプロバイダから 1 つしか IP アドレスの割り当てを受けていない場合 (または IP アドレスを動的に割り当てられている場合でも)、 &man.natd.8; プログラムを使いたくなるかもしれませんね。 natd を使えば、 1 つしか IP アドレスを持っていない場合でも、 サブネット全体をインターネットに接続させることができます。 &man.ppp.8; も同様の機能を持っており、 スイッチで有効にすることができます。 どちらの場合も alias ライブラリ (&man.libalias.3;) が使われます。 /dev/ed0 デバイスを作成することができません。 Berkeley UNIX におけるネットワークの構成において、 ネットワークのインタフェースはカーネルコードからのみ、 直接あつかうことができます。 より詳しく知りたい場合は、 /etc/rc.network というファイルや、 このファイルの中に書いてある、 さまざまなプログラムについてのマニュアルページを見てください。 それでもまだ分からない場合には、 他の BSD 系の OS のネットワーク管理についての本を読むべきでしょう。 ごく少しの例外をのぞいては、FreeBSD のネットワーク管理は SunOS 4.0 や Ultrix と基本的に同じです。 Ethernet アドレスのエイリアス (alias) はどのようにして設定できますか? &man.ifconfig.8; のコマンドラインに netmask 0xffffffff を追加して、次のように書いてください。 &prompt.root; ifconfig ed0 alias 204.141.95.2 netmask 0xffffffff 3C503 で他のネットワークポートを使用するにはどのようにすればよいですか? 他のポートを使用したい場合には、 &man.ifconfig.8; のコマンドラインにパラメータを追加しなければなりません。 デフォルトでは link0 が用いられるようになっています。 BNC のかわりに AUI ポートを使用したい場合には、 link2 というパラメータを追加してください。 これらのフラグは、 /etc/rc.conf (&man.rc.conf.5; 参照) にある ifconfig_* の変数を使って指定されるはずです。 FreeBSD との間で NFS がうまくできません。 PC 用のネットワークカードによっては、 NFS のような、 ネットワークを酷使するアプリケーションにおいて問題を起こすものがあります。 この点に関しては FreeBSD ハンドブックの「NFS」を参照してください。 何故 Linux のディスクを NFS マウントできないのでしょうか? Linux の NFS のコードには、 許可されたポートからのリクエストしか受けつけないものがあります。 以下を試してみてください。 &prompt.root; mount -o -P linuxbox:/blah /mnt 何故 Sun のディスクを NFS マウントできないのでしょうか? SunOS 4.X が走っている Sun Workstation は、 許可されたポートからのマウント要求しか受けつけません。 以下を試してみてください。 &prompt.root; mount -o -P sunbox:/blah /mnt mountd から can't change attributes というメッセージがずっと出続けていて、 FreeBSD の NFS サーバでは bad exports list と表示されます。これは何が原因なのでしょう? 最も良くある問題は、&man.exports.5; のマニュアルページの以下の部分を正しく理解していないことです。
このファイルの各行 (# ではじまるコメント行を除く) は、 NFS サーバのローカルファイルシステムに存在する、 他のホストにエクスポートされるマウントポイント (複数可) と、 それに対するエクスポートフラグを指定します。 特定のエクスポート先ホストおよび、 すべてのホストに適用されるデフォルトエントリは両方とも、 サーバの各ローカルファイルシステムに対して一回だけしか指定できません。
さて、ありがちな間違いをご覧になればはっきりするでしょう。 もし /usr 以下が単一のファイルシステムである (つまり /usr に何もマウントされない) 場合、 次の exports リストは正しくありません。 /usr/src client /usr/ports client 一つのファイルシステムに対して属性の指定が二行になっています。 /usr は同じホスト client にエクスポートされますから、 正しい書き方は次のようになります。 /usr/src /usr/ports client もう一度マニュアルページの文章を確認すると、 あるホストにエクスポートされる各ファイルシステムの属性は すべて一行に書かれていなければならない、となっています (ここでは、「アクセス可能なすべてのホスト」 も一つの独立したホストとして扱われることに注意してください)。 このことは、ファイルシステムをエクスポートするために 奇妙な書式を使わなければならない原因にもなっているのですが、 ほとんどの人にとって、これは問題にはならないでしょう。 次に示すのは、有効な exports リストの例です。 ここでは、/usr と /exports がローカルファイルシステムです。 # Export src and ports to client01 and client02, but only # client01 has root privileges on it /usr/src /usr/ports -maproot=0 client01 /usr/src /usr/ports client02 # The "client" machines have root and can mount anywhere # up /exports. The world can mount /exports/obj read-only /exports -alldirs -maproot=0 client01 client02 /exports/obj -ro PPP で NeXTStep に接続する際に問題があるのですが。 /etc/rc.conf (&man.rc.conf.5; 参照) の中で次の変数を NO にして、 TCP extension を無効にしてみてください。 tcp_extensions=NO Xylogic の Annex も同様の問題がありますので、 Annex 経由で PPP を行なう場合にもこの変更を行ってください。 IP マルチキャスト (multicast) を有効にするには? FreeBSD 2.0 かそれ以降では、 標準の状態で完全にマルチキャストに対応しています。 現在使用している計算機をマルチキャストのルータ (router) として使用するには、 MROUTING というオプションを定義したカーネルを作ったうえで、 mrouted を走らせる必要があります。2.2 かそれ以降の FreeBSD ならば、 /etc/rc.conf でフラグ mrouted_enable を YES にセットしておくことで、 起動時に mrouted を起動できます。 MBONE 用のツールは ports 内の専用のカテゴリー mbone にあります。 vic や vat といった会議用のツールを探している場合は、 この場所を見てください。 詳しい情報は Mbone Information Web にあります。 DEC の PCI チップセットを用いているネットワークカードには、 どのような物がありますか? Glen Foster 氏による一覧に、 最近の製品を追加したものを以下に示します。 Vendor Model ---------------------------------------------- ASUS PCI-L101-TB Accton ENI1203 Cogent EM960PCI Compex ENET32-PCI D-Link DE-530 Dayna DP1203, DP2100 DEC DE435, DE450 Danpex EN-9400P3 JCIS Condor JC1260 Linksys EtherPCI Mylex LNP101 SMC EtherPower 10/100 (Model 9332) SMC EtherPower (Model 8432) TopWare TE-3500P Znyx (2.2.X) ZX312, ZX314, ZX342, ZX345, ZX346, ZX348 (3.X) ZX345Q, ZX346Q, ZX348Q, ZX412Q, ZX414, ZX442, ZX444, ZX474, ZX478, ZX212, ZX214 (10mbps/hd) 何故自分のサイトのホストに対して FQDN を使用する必要があるのですか? 実際にはそのホストは別のドメインにあるのではないですか。 たとえば、foo.bar.edu というドメインの中から、 bar.edu ドメインにある mumble というホストを指定したい場合には、 mumble だけではダメで、 mumble.bar.edu という FQDN (fully-qualified domain name) で指定しなければなりません。 伝統的に、BSD の BIND のリゾルバ (resolver) ではこのような事は可能でしたが、 FreeBSD に入っている bind (&man.named.8; 参照) の現在のバージョンでは、 自分以外のドメインに対して FQDN でない別名を自動的につけてくれるような事はありません。 したがって mumble というホスト名は、 mumble.foo.bar.edu という名前か、もしくは root ドメイン内にある場合にしか適用されません。 これは、 mumble.bar.edu と mumble.edu ということなったドメイン名に対してホスト名のサーチが行なわれていた 以前の振る舞いとは異なったものです。このような事が悪い例もしくは セキュリティホールとみなされる理由については RFC 1535 を見てください。 /etc/resolv.conf ファイル (&man.resolv.conf.5; 参照) の中で domain foo.bar.edu と書いてある行を、 search foo.bar.edu bar.edu のように書きかえることで、上のような事ができます。しかし、 RFC 1535 にあるように、 検索順序が「内部 (local) と外部 (public) の管理の境界」をまたがないようにしてください。 すべてのネットワークの操作に対して Permission denied というメッセージが表示されるのですが。 IPFIREWALL オプションを付けてカーネルをコンパイルした場合には、 2.1-STABLE の開発の途中から変更になった 2.1.7R の標準的な方針として、 明示的に許可されていないすべてのパケットは落とされる設定 になっている事を覚えておいてください。 もしファイアウォールの設定を間違えた場合にネットワークの操作が再びできる ようにするには、root でログインして次のコマンドを実行してください。 &prompt.root; ipfw add 65534 allow all from any to any /etc/rc.conf に firewall_type='open' を追加してもよいでしょう。 FreeBSD のファイアウォールの設定についての情報は FreeBSD ハンドブックの「ファイアウォール」にあります。 IPFW のオーバヘッドはどのくらいでしょうか? この答えは、 使っているルールセットとプロセッサのスピードによってほとんど決まります。 イーサネットに対して少しのルールセットだけを使っている場合には、 ほとんどその影響は無視できる程度です。 実際の測定値を見ないと満足できない方々のために、 実際の測定結果をお見せしましょう。 次の測定は 486-66 (訳注: Intel 社製 CPU i486、66MHz のこと) 上で 2.2.5-STABLE を使用して行なわれました。 IPFW は変更が加えられて、ip_fw_chk ルーチン内でかかる時間を 測定して 1000 パケット毎に結果をコンソールに表示するようになっています。 それぞれ 1000 ずつのルールが入っている 2 つのルールセットでテストが行なわれました。 ひとつ目のルールセットは最悪のケースを見るために ipfw add deny tcp from any to any 55555 というルールを繰り返したものです。 IPFW のパケットチェックルーチンは、 パケットが (ポート番号のせいで) このルールにマッチしないことがわかるまでに、 何度も実行されます。そのため、これは最悪のケースを示します。 このルールを 999 個繰り返し並べた後に allow ip from any to any が書かれています。 2つ目のルールセットは、なるべく早くチェックが終了するように書かれたものです。 ipfw add deny ip from 1.2.3.4 to 1.2.3.4 このルールでは、発信元の IP アドレスがマッチしないので、 チェックはすぐに終了します。上のルールセットとおなじように、 1000 個目のルールは allow ip from any to any です。 1 つ目のルールセットの場合、 パケットあたりのオーバヘッドはおよそ 2.703ms/packet、 これはだいたい 1 つのルールあたり 2.7 マイクロ秒かかっていることになります。 したがって、 このルールにおけるパケット処理時間の理論的な限界は、 毎秒約 370 パケットです。 10Mbps のイーサネットで 1500 バイト以下のパケットサイズを仮定すると、 バンド幅の利用効率は 55.5% が限界となることになります。 2 つ目のルールセットでは、それぞれのパケットがおよそ 1.172msで処理されていますので、 だいたい 1 つのルールあたり 1.2 マイクロ秒かかっていることになります。 パケット処理時間の理論的な限界は、 毎秒約 853 パケットとなりますので、 10Mbps Ethernet のバンド幅を使い切ることができます。 このテストでのルール数は多過ぎるため、 実際に使用する際の結果を反映している訳ではありません。 これらは上に示した数値を出すためだけに用いられたものです。 効率の良いルールセットを作るためには、 次のような事を考えておけばよいでしょう。 「確定している」ルールは先頭の方に持ってきてください。 これは、多数の TCP のトラフィックがこのルールで処理されるためです。 そしてこのルールの前には allow tcp という記述を置かないでください。 良く使われるルールを、あまり良く使われないルールよりも 前の方に (もちろんファイアウォールの許可設定を変えない範囲で) 持ってきてください。 ipfw -a l のようしてパケット数の統計を取ることで、 どのルールが最もよく使われているかを調べることができます。 &man.ipfw.8; fwd ルールを使って他のマシンにサービスをリダイレクトしたのですが、 うまく動いてくれないようです。どうしてなんでしょう? おそらく、あなたが期待している動作とは、 単なるパケット転送ではなくネットワークアドレス変換 (NAT) と呼ばれるものだからでしょう。 fwd ルールは文字どおり、本当に転送しか行ないません。 パケットの中身については一切手を加えないのです。 そのため、次のようなルールを設定したとすると、 01000 fwd 10.0.0.1 from any to foo 21 宛先アドレスに foo と書かれたパケットが このルールを設定したマシンに到着した場合、そのパケットは 10.0.0.1 に転送されますが、宛先アドレスは foo のままになります。 つまり、パケットに宛先アドレスが 10.0.0.1 に書き換えられるということはありません。 自分宛でないパケットを受けとったマシンは、 おそらくほとんどの場合、そのパケットを破棄すると思います。 そのため fwd ルールは、 そのルールを書いたユーザが意図したようには動かないことが良くあります。 この動作はバグではなく、仕様なのです。 サービスの転送をきちんと動作させる方法については、 サービスのリダイレクトに関する FAQ や &man.natd.8; のマニュアルページ、 Ports Collection にいくつか含まれているポート転送ユーティリティなどをご覧になると良いでしょう。 サービス要求を他のマシンにリダイレクトするには? FTP などのサービスのリクエストは、socket パッケージを利用してリダイレクトできます。 socket パッケージは ports の sysutils カテゴリに含まれています。 (/etc/inet.confに書かれている) コマンド行を、次のように socket を呼ぶように変更してください。 ftp stream tcp nowait nobody /usr/local/bin/socket socket ftp.foo.com ftp ここで ftp.foo.com はリダイレクト先のホスト名、 行の最後の ftp はポート名です。 バンド幅の管理を行なえるツールはどこで手に入れられますか? FreeBSD 用のバンド幅管理ツールには、無料で手に入れられる ALTQ と、 Emerging Technologies から入手できる Bandwidth Manager という市販のものの 2 種類があります。 BIND (named) が、53 番ポートのほかに 大きな番号のポートで受け付けています。私のホストは 乗っ取られたのでしょうか。 おそらく違います。FreeBSD 3.0 以降では、外向けの問合せに ランダムな大きな番号のポートを用いるバージョンの BIND を 用いています。ファイアウォールを通すため、またはあなたの 気分で、外向きの問合せを 53 番ポートから行いたいならば、 /etc/namedb/named.conf に次のように 設定してみてください。 options { query-source address * port 53; }; 更に限定したければ、* を単一の IP アドレスに置き換えることもできます。 それはともかく、おめでとうごさいます。 sockstat の出力を見て、おかしな現象に 注目するのはよい習慣です。 なぜ /dev/bpf0: device not configured が出るのでしょうか? バークレーパケットフィルタ (&man.bpf.4;) ドライバは、それを利用するプログラムを実行する前に有効にしておく必要があります。 カーネルコンフィグファイルに、次のように追加してカーネルの再構築をしてください。 pseudo-device bpfilter # Berkeley Packet Filter そして再起動してから、次にデバイスノードを作成する必要があります。 これは、次のように入力し、/dev を変更することで行ないます。 &prompt.root; sh MAKEDEV bpf0 デバイスノードの作成の詳細は、 FreeBSD ハンドブックの「デバイスノード」を参照してください。 Linux の smbmount のように、 ネットワーク上の Windows マシンのディスクをマウントするにはどうしたら良いのでしょう? Ports Collection に含まれる sharity light パッケージを使ってください、 icmp-response bandwidth limit 300/200 pps というメッセージがログファイルに現れるのですが、 どういうことでしょう? これは、カーネル自身から「ICMP や TCP のリセット (RST) 応答を、妥当な数よりも多く送っている」ということを、 あなたに伝えるメッセージです。 ICMP 応答は良く、使われていない UDP ポートに接続しようとした結果として生成されます。 また、TCP リセットはオープンされていない TCP ポートに接続しようとした結果として生成されます。 その他、これらのメッセージが表示される原因となる状況として、 以下のようなものがあります。 (特定のセキュリティ上の弱点を悪用しようとする攻撃ではなく) 膨大な数のパケットを使った強引なサービス妨害 (DoS) 攻撃。 (一部のウェルノウンポートを狙ったものではなく) 非常に広い範囲のポートに接続を試みるポートスキャン。 メッセージ中の最初の数字は、 上限を設定しなかった場合にカーネルが送っていたであろうパケットの数を示し、 二番目の数字は、パケット数の上限値を示します。 この上限値は net.inet.icmp.icmplim という sysctl 変数を使うことで、以下のように変更可能です。 ここでは上限を 1 秒あたりのパケット数で 300 にしています。 &prompt.root; sysctl -w net.inet.icmp.icmplim=300 カーネルの応答制限を無効にせず、 ログファイル中のメッセージだけを抑制したい場合、 net.inet.icmp.icmplim_output sysctl 変数を次のようにすることで出力を止めることができます。 &prompt.root; sysctl -w net.inet.icmp.icmplim_output=0 最後に、もし応答制限を無効にしたい場合は、 net.inet.icmp.icmplim sysctl 変数に (上の例のようにして) 0 を設定することで実現できます。 ただし応答制限を無効化するのは、上記の理由からおすすめしません。 PPP ppp が動きません。どこを間違えているのでしょう? まず &man.ppp.8; のマニュアルと、 FreeBSD ハンドブックの「PPP」を読んでみましょう。 次に、 set log Phase Chat Connect Carrier lcp ipcp ccp command という命令を ppp のコマンドプロンプトに対して打ち込むか、 設定ファイル /etc/ppp/ppp.conf に加えて (default セクションの先頭に加えるのが一番良いでしょう) ログを有効にしてみてください。 その際、 /etc/syslog.conf (&man.syslog.conf.5; 参照) に !ppp *.* /var/log/ppp.log と書かれた行が含まれているか、また、 /var/log/ppp.log が存在しているかどうか確かめておいてください。 さて、これで何が起きているのか突き止めるために、 ログファイルからたくさんの情報を得られるようになりました。 ログに訳の分らない部分があっても心配ご無用。 あなたが助けを求めた誰かにとっては、 その部分が意味をなす場合があるのです。 訳注 ログの取得に syslog を使用するようになったのは 2.2.5 以降からです。 使用中の ppp のバージョンで set log 命令を解釈しない場合は、最新版をダウンロードすべきです。 FreeBSD の 2.1.5 以降でビルドできます。 ppp を実行するとハングします ホスト名の解決がうまくいっていないのでしょう。まず、 リゾルバ (resolver) が /etc/hostsを参照するように、 /etc/host.conf の最初の行に host と書き込んでください。 つぎに、/etc/hosts に使用しているマシンのエントリを書き加えます。 ローカルでネットワークを使用していない場合は、 localhost の行を以下のように変更してください。 127.0.0.1 foo.bar.com foo localhost 使用しているホストのエントリを追加してもかまいません。 詳細は関連するマンページを参照してください。 ppp が モードでダイアルしてくれない まず最初に、デフォルトルートが確立しているかどうかチェックしてください。 netstat -rn (&man.netstat.1; 参照) を実行すると、以下のような情報が表示されるはずです。 Destination Gateway Flags Refs Use Netif Expire default 10.0.0.2 UGSc 0 0 tun0 10.0.0.2 10.0.0.1 UH 0 0 tun0 これはあなたがハンドブックやマニュアル、 ppp.conf.sample の中で出てくるアドレスを使用していると仮定した場合の例です。 デフォルトルートが確立していない場合、 ppp.conf の中の HISADDR が理解できない、 古いバージョンの &man.ppp.8; が走っている可能性があります。 FreeBSD 2.2.5 より前のバージョンに付属していた ppp を使用している場合、 add 0 0 HISADDR と書かれた行を以下のように修正してください。 add 0 0 10.0.0.2 netstat -rn でデフォルトルートの情報が表示されない場合、もう一つ、 /etc/rc.conf (&man.rc.conf.5; 参照) (2.2.2 より前のリリースでは /etc/sysconfig と呼ばれていました) の中でデフォルトのルータを誤って設定し、 ppp.conf から delete ALL の行をうっかり消してしまった可能性があります。 この場合は、 FreeBSD ハンドブックの「システムの最終設定」の項を読み直してください。 No route to host とはどういう意味ですか? このエラーは通常、 /etc/ppp/ppp.linkup に以下のようなセクションが無い場合に起こります。 MYADDR: delete ALL add 0 0 HISADDR これは動的 IP アドレスを使用している場合、 またはゲートウェイのアドレスを知らない場合にのみ必要な設定です。 インタラクティブモードを使用している場合、 パケットモードに入った後で (プロンプトが PPP と大文字に変わったらパケットモードに入ったしるしです)、 以下の命令を入力してください。 delete ALL add 0 0 HISADDR 詳しい情報については、 FreeBSD ハンドブックの「PPP と動的 IP 設定」の項を参照してください。 3 分ほど経つと接続が切れてしまう ppp のタイムアウトは デフォルトでは 3 分です。 これは set timeout NNN という命令によって調整することができます。 NNN には、 接続が切れるまでのアイドル時間が秒数で入ります。 NNN が 0 の場合、 タイムアウトによる切断は起こりません。 このコマンドは ppp.conf に入れることも、 インタラクティブモードでプロンプトから入力することも できます。 ソケットを用いる &man.telnet.1; か &man.pppctl.8; を使用し、 ppp サーバに接続することによって、 回線がアクティブな間に限定してタイムアウトの時間を調整することも可能です。 訳注 pppctl は 2.2.5R からです。 詳しい情報は &man.ppp.8; のマニュアルページを参照してください。 負荷が高いと接続が切れてしまう Link Quality Reporting (LQR) の設定を行っている場合、 マシンと接続先の間で非常にたくさんの LQR パケットが失われている可能性があります。結果として ppp は回線の具合いが悪いと考え、 回線を切断するのです。2.2.5 より前のバージョンの FreeBSD では LQR はデフォルトで有効になっています。 現在ではデフォルトの状態で無効です。 LQR は以下の命令で無効にすることができます。 disable lqr 接続がランダムに切れてしまう ノイズの多い回線、あるいは待ち機能付きの回線では、 時々モデムが (誤って) キャリアを失ったと思い込み、 回線が切断されてしまうことがあります。 大多数のモデムでは、 一時的なキャリアの喪失をどれくらいの時間で検出するかを、 設定で決めることができます。 たとえば USR Sportster では、S10 レジスタ の値を 10 倍した秒数がその値になります。 この場合、モデムをもっとのんびり屋さんにするには、 dial 行に次のような文字列を加えると良いでしょう。 set dial "...... ATS10=10 OK ......" 詳しくはお使いのモデムのマニュアルをご覧ください。 接続が不規則にハングアップしてしまう たくさんの人が、原因不明のハングアップを経験しています。 検証のために必要なのは、まずどちら側のリンクでそれが起こっているか、 ということです。 外部接続型モデムを利用しているなら、 単に ping を使うことで、 データを送信するときに TD ランプが点灯するかどうかを確認することができます。 もし、TD ランプが点灯して、 RD ランプが点灯しなければ、 問題は回線の向こう側にあります。TD が点灯しなければ、 問題は回線のこちら側です。内蔵型モデムの場合、 ppp.conf ファイルに set server コマンドを入れる必要があるでしょう。 回線が切断されたとき、pppctl を使って ppp に接続してください。 そのとき、 ネットワーク接続が急に復旧 (診断ソケットへのアクセスで、 ppp が復活します) するか、 もしくは接続自体が全くできない (ただし、 ppp 起動時に set socket コマンドがちゃんと実行されているとします) としたら、 問題は回線のこちら側です。 もし、接続可能で、かつ状況が変化しなければ、 set log local async を使ってローカル非同期ログ (async logging) を有効にし、 ping を他のウィンドウかターミナルから使ってください。 非同期ログには、こちら側のリンクの送受信データが記録されます。 もし、データが送信されたにもかかわらず返って来ていなければ、 問題は回線の向こう側にあることになります。 問題が回線のどちら側かにあることが分かったら、 つぎの二つの可能性が考えられるでしょう。 回線の向こう側での反応がない これに対処できることはほとんどありません。大部分の ISP は、Microsoft 社製 OS 以外の利用者に対してのサポートを拒否するでしょう。 ppp.conf ファイルの中に enable lqr を記述することで ppp が回線の向こう側で発生する切断を検出することができますが、 この検出は比較的遅いため、あまり役に立ちません。また、あなたは user-ppp を利用していることを ISP に知られたくないと思うかも知れませんね。 まず最初に、こちら側の圧縮機能をすべて無効にしてみてください。 それには、設定ファイルをつぎのようにします。 disable pred1 deflate deflate24 protocomp acfcomp shortseq vj deny pred1 deflate deflate24 protocomp acfcomp shortseq vj そして再接続し、変更前と同じように通信できることを確認します。 もしこれによって状況が改善されるか、完全に解決したら、 (上の設定のうち) どの設定で状況が変化したのかを、 色々な組合せで試してみてください。これは、ISP に問い合わせを行なうときの有効な情報となります (ただし、 あなたが Microsoft 社製品以外のものを利用していることも明らかにしてしまいますが)。 ISP に問い合わせを行なう前に、こちら側の非同期ログを有効にして、 接続がハングアップするまで待ってください。この作業は、 非常に多くのディスク空間を消費するかも知れません。 興味の対象となっているのは、通信ポートから最後に読み込まれたデータです。 それは通常 ASCII データで、 問題点の詳細 (Memory fault, core dump など) が 記載されている可能性があります。 回線の向こう側で通信ログを監視することは可能なはずですので、 切断が発生した時、ISP の対応が好意的ならば どうして ISP 側で問題が発生したのかこちらに伝えてくれるかも知れません。 brian@Awfulhak.org まで詳細を送って頂くか、ISP に直接私に連絡するように伝えて下さっても構いません。 ppp がハングアップする ベストな方法は、 CFLAGS+=-g と STRIP= を ppp の Makefile に追加して、 ppp を再構築し、 そして make clean && make && make install を行なうことです。 ppp がハングアップした時、 ps ajxww | fgrep ppp を使って ppp のプロセス ID を調べ、 gdb ppp PID を実行してください。 gdb のプロンプトから、 bt を使ってスタックをトレースすることができます。 スタックトレースの結果は、brian@Awfulhak.org まで送ってください。 Login OK! のメッセージが出た後、何も起こらない 2.2.5 より前のリリースの FreeBSD では、 &man.ppp.8; はリンクが確立した後、接続先が Line Control Protocol (LCP) を発信するのを待ちます。しかし、多くの ISP ではネゴシエーションを自分からは起こさず、 クライアントが起こすのを待っています。 ppp に強制的に LCP を発信させるには、 次の命令を使います。 set openmode active 両方の側がネゴジェーションを起こしても、 大抵の場合は何の問題もありません。 ですから、現在では openmode はデフォルトで active になっています。 次のセクションでこれが問題になる場合を説明します。 でもまだ magic is the same というエラーが出る 時折、接続直後のログに magic is the same というメッセージがあらわれることがあります。 このメッセージがあらわれても何も起きない場合もありますし、 どちらかの側が接続を切ってしまう場合もあります。 ppp の実装の多くはこの問題に対応できておらず、 その場合にはちゃんと link が上がっている状態であっても、 ppp が最終的にあきらめてしまい、 接続を切るまで設定のリクエストが繰り返し送られ、 設定が行われたという通知がログファイルに残ると思います。 これは通常、 ディスクアクセスの遅いサーバマシンのシリアルポートで getty が生きていて、 ppp がログインスクリプトか、 ログイン直後に起動されたプログラムから実行されている場合に起こります。 slirp を使用している場合に同様の症状が見られたという報告もあります。 原因は getty の終了されるまでと、 ppp が実行され、 クライアント側の ppp が Line Control Protocol (LCP) を送り始めるまでのタイミングにあります。 サーバ側のシリアルポートで ECHO が有効なままになっているので、 クライアント側の ppp にパケットが「反射」してしまうのです。 LCP ネゴシエーションの一部として、 リンクの両サイドで magic number を定めて、 「反射」が起きていないかどうか確かめる作業があります。 規約では、接続相手がこちらと同じ magic number を提示してきたら、 NAK を送って新しい magic number を選択しなければならないと定めています。 この作業の間、サーバのシリアルポートの ECHO がずっと有効になったままなので、 クライアント側の ppp は LCP パケットを送り、 パケットが反射して全く同じ magic number が送られてくるのを見つけ、 それに対して NAK を送るのです。一方 NAK 自体も (これは ppp が magic number を変更しなければいけないことを意味しています) 反射してくるので、 結果として magic number が数えきれないほど変更され、 そのすべてがサーバの tty バッファの中に積み重なることになるのです。 サーバでスタートした ppp は、すぐに magic number であふれかえってしまい、 LCP のネゴシエーションを十分に行ったものと判断して、 さっさと接続を切ってしまいます。 一方、 クライアント側は反射が帰ってこなくなったので満足しますが、 それもサーバが接続を切ったことを知るまでです。 この事態は、以下の行を ppp.conf の中に書いて、 相手がネゴシエーションを開始できるようにする事によって回避できます。 set openmode passive これで ppp はサーバが LCP ネゴシエーションを起こすのを待つようになります。 しかし、 自分からは決してネゴジェーションを起こさないサーバもあるかもしれません。 もしこの状況に遭遇した場合には、次のようにしてください。 set openmode active 3 これによって ppp は 3 秒間 passive モードを続けた後で、 LCP リクエストを送り始めます。 この間に相手がリクエストを送り始めた場合には 3 秒間待たずにこのリクエストに即座に応答します。 接続が切れるまで LCP のネゴシエーションが続くのですが。 現在の ppp は、まだ LCP や CCP、 IPCP の返事が、 元のリクエストと連携してくれる機能がきちんと実装されていません。 その結果、ある ppp が相手よりも 6 秒以上遅い場合には、 LCP 設定のリクエストをさらに 2 回送ります。 これは致命的な物です。 A と Bという 2 つの実装を考えてみましょう。 A が接続の直後に LCP リクエストを送り、 一方 B の方はスタートするのに 7 秒かかったとします。B がスタートする時には A は LCP リクエストを 3 回送ってしまっています。 前の節で述べた magic number の問題が起きないよう、 ECHO は off になっていると考えています。 B は REQ を送ります。 するとこれは A の REQ のうち、 最初の物に対する ACK となります。 結果として、A は OPENED の状態に入り、 B に対して (最初の) ACK を送ります。 そのうちに B は、 B がスタートする前に A から送られたもう 2 つの REQ に対する ACK を送り返します。 B は A からの最初の ACK を受け取り OPENED の状態に入ります。 A は B からの 2 つ目の ACK を受け取りますので、 REQ-SENTの状態に戻り、 さらに、RFC のとおりに (4 つ目の) REQ を送ります。そして 3 つ目の ACK を受け取って OPENED の状態に入ります。 一方、B は A からの 4 つ目の REQ を受け取りますので、 ACK-SENT の状態に入り、2 つ目の REQ と 4 つ目の ACK を RFC のとおりに送ります。 Aは、 REQ を受けとると REQ-SENT の状態になり、さらに REQ を送ります。 そしてすぐに ACK を受け取って OPENED の状態に入ります。 これが、片方の ppp があきらめてしまうまで続きます。 これを回避する最も良い方法は、 片方を passive モードに設定する、 すなわち反対側がネゴシエーションを開始するまで待つようにする事です。 これは、 set openmode passive というコマンドでできます。 このオプションは気を付けて使わないといけません。さらに set stopped N というコマンドを追加して、 ppp がネゴシエーションが開始するまで待つ 最大の時間を設定してください。もしくは、 set openmode active N というコマンド (ここで、 N はネゴシエーションが始まるまで待つ時間) を使うこともできます。 詳しくはマニュアルページを参照してください。 ppp が接続直後に固まってしまう 2.2.5 より前のバージョンの FreeBSD では、ppp が Predictor1 圧縮のネゴシエーションを誤って解釈して、 接続直後にリンクを無効にしている可能性があります。 これは両サイドが異なる Compression Control Protocols (CCP) を使ってネゴジェーションを行った場合にのみ発生します。 この問題は現在は解決していますが、あなたの走らせている ppp のバージョンが古い場合でも、次の命令で解決することができます。 disable pred1 ppp の内部でシェルを起動しようとすると固まってしまう shell あるいは ! コマンドを使用すると、 ppp はシェルを起動し (何か引数を渡した場合は、 ppp は引数も実行します)、 コマンドが終了するまで処理を中断します。 コマンドを実行中に ppp のリンクを使おうとすると、 リンクが固まっているように見えますが、 これは ppp がコマンドの終了を待っているからです。 このような場合は、代わりに !bg コマンドを使用してください。 与えられたコマンドがバックグラウンドで実行されるので、 ppp はリンクに関するサービスを継続することができます。 ヌルモデムケーブルを使用しているとき、 ppp が終了しない ヌルモデムケーブルを使用して直接接続している場合、 ppp は自動的には接続の終了を知ることができません。 これはヌルモデムシリアルケーブルの配線に起因しています。 この種の接続形態を用いる場合は、 以下の命令を用いて LQR を常に有効にする必要があります。 enable lqr こうすると、接続先がネゴシエーションを行う場合、デフォルトで LQR の使用を受け入れるようになります。 ppp を モードで動かすと、 勝手にダイアルすることがある ppp が思いもしないときにダイアルを始める場合、その原因を突き止め、 防止のためにダイヤルフィルタ (dfilters) をかけてやる 必要があります。 原因を突き止めるためには、以下の命令を使用してください。 set log +tcp/ip これで接続を通過するすべてのトラフィックをログに残すことができるようになりました。 次に突然回線がつながったときのログのタイムスタンプをたどれば、 原因を突き止めることができるはずです。 原因がわかったら、次に、このような状況ではダイヤルが起こらないようにしましょう。 通常、この手の問題は、DNS で名前の解決をしようとしたために起こります。 DNS による名前の解決によって、 接続が行われるのを防止するには、 次のような手段を用います (これは ppp の既に確立した接続に関してパケットのフィルタリングをするものではありません)。 set dfilter 1 deny udp src eq 53 set dfilter 2 deny udp dst eq 53 set dfilter 3 permit 0/0 0/0 これはデマンドダイヤル機能に問題を生じさせるため、 常に適切であるとはかぎりません。 ほとんどのプログラムは他のネットワーク関連の処理を行なう前に DNS への問い合わせが必要になります。 DNS の場合は、 何が実際にホスト名を検索しようとしているのかを突き止めるべきでしょう。 大抵の場合は、 &man.sendmail.8; が犯人です。 設定ファイルで sendmail が DNS に問い合わせないようになっているか確認すべきです。 自分用の設定ファイルを作成するための詳しい方法は、 メールの設定 の項をご覧ください。 または、 .mc ファイルに次のような行を追加してもよいでしょう。 define(`confDELIVERY_MODE', `d')dnl この行を追加すると、sendmail はメールキューを処理する (通常 sendmail は 30 分ごとにキューを処理するよう、 というオプションを付けて起動されます) までか、 または (多分 ppp.linkup というファイルの中で) sendmail -q というコマンドが実行されるまで、 すべてのメールをキューに溜めるようになります。 訳注 sendmail -q はその時点のメールキューの内容を処理して終了します。 CCP エラーとはどういう意味ですか ログファイル中の以下のエラーは、 CCP: CcpSendConfigReq CCP: Received Terminate Ack (1) state = Req-Sent (6) のネゴシエーションにおいて ppp は Predictor1 圧縮を用いるべく主張したのに対して、 接続先は圧縮を使用しないことを主張した場合に起こります。 このメッセージには何の害もありませんが、 出るのが嫌なら、以下の命令を用いてこちら側でも Predictor1 圧縮を無効にすることで対応できます。 disable pred1 ファイル転送の途中で、ppp が IO エラーを出して固まってしまう FreeBSD 2.2.2 以前のバージョンの tun ドライバには、tun インタフェースの MTU のサイズより大きなパケットを受け取ることができないというバグがありました。 MTU のサイズより大きなパケットを受け付けると IO エラーが起こり、 syslogd 経由で記録されるのです。 ppp の仕様では、 LCP のネゴシエーションを行う場合を含むどのような場合でも最低 1500 オクテットの Maximum Receive Unit (MRU) を受け入れる必要があります。 ですから、MTU を 1500 以下に設定した場合でも、ISP はそれに関係なく 1500 の大きさのパケットを送ってくるでしょう。 そしてこのイケてない機能にぶちあたって、 リンクが固まるのを目にすることになるのです。 FreeBSD 2.2.2 以前のバージョンでは、MTU を決して 1500 より小さくしないことで、 この問題を回避することができます。 どうして ppp は接続速度をログに残さないんでしょう? モデムとの「やり取り」すべての行をログに残すには、 以下のようにして接続速度のログの有効化を行ってください。 set log +connect これは &man.ppp.8; に最後にくることが要求されている expect という文字列がくるまでのすべてのものをログに記録させます。 接続速度はログにとりたいけれど、PAP や CHAP を使っている (その結果、ダイヤルスクリプト中の CONNECT 以降に全く「やりとり」を行わない - set login スクリプトには何も書かない) のであれば、 ppp に expect を含んだ CONNECT 行すべてがくるまで待たせるようにしないといけません、 以下のようになります。 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n" ここで、CONNECT を受信してから、 何も送らず、復帰改行 (linefeed) を待っています、 ppp に CONNECT の応答すべてを読み込ませているわけです。 私の chat スクリプトでは \ という文字を PPP が解釈してくれません。 PPP は設定ファイルを読み込むときに、 set phone "123 456 789" のような文字列を正しく解釈し、 番号が実際に1 つの引数であると理解します。 " という文字を指定するには、バックスラッシュ (backslash; \) でエスケープしなければなりません。 chat の各引数が解釈されるときには、 \P や \T のような特別なエスケープシーケンス (マニュアルページ参照のこと) を見付けるために、 もう 1 回、字句解析を行います。 このように字句解析は 2 回繰り返されますので、 正しい回数だけエスケープ処理を行わないといけません。 モデムにたとえば \ のような文字を送りたい場合には、 次のようにする必要があります。 set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK" 実際にモデムに送られる文字列は次のようになります。 ATZ OK AT\X OK 他の例ですと set phone 1234567 set dial "\"\" ATZ OK ATDT\\T" は次のようになります。 ATZ OK ATDT1234567 ppp が segmentation fault になるのですが、 ppp.core ファイルがありません ppp (や他のプログラム) は決して core を吐いてはいけません。 ppp は実効 uid が 0 で動いていますので、 オペレーティングシステムは ppp を終了させる前にディスクに core イメージを書き込みません。 しかし ppp は実際にはセグメンテーション違反や、 他の core を吐く原因となるようなシグナルによって終了して おり、 さらに最新のバージョン (このセクションの始めを見てください) を使用しているならば、次のようにしてください。 &prompt.user; tar xfz ppp-*.src.tar.gz &prompt.user; cd ppp*/ppp &prompt.user; echo STRIP= >>Makefile &prompt.user; echo CFLAGS+=-g >>Makefile &prompt.user; make clean all &prompt.user; su &prompt.root; make install &prompt.root; chmod 555 /usr/sbin/ppp これでデバッグ可能なバージョンの ppp がインストールされます。 root で ppp を実行し、 すべての特権が無効になっているようにする必要があるでしょう。 ppp を実行する時には、 カレントディレクトリが make したディレクトリであるようにしてください。 これで、ppp がセグメンテーション例外を受け取ったときには ppp.core という名前の core ファイルを吐くようになります。core が 吐かれたら次のようにしてください。 &prompt.user; su &prompt.root; gdb /usr/sbin/ppp ppp.core (gdb) bt ..... (gdb) f 0 .... (gdb) i args .... (gdb) l ..... 質問する際には、これらすべての情報を提供して、 問題点の分析ができるようにしてください。 gdb の使い方に慣れている場合には、実際に dump の原因となった理由やそのアドレス、 関連した変数の値なども調べる事ができるでしょう。 auto モードでダイアルをするようなプロセスが接続されない。 これは ppp がローカル側の IP アドレスを、 動的に通信相手と交渉するように設定されている時に発生する良く知られた障害でした。 最新のバージョンでは、 この問題は修正されています。 iface をマニュアルページから検索してみてください。 これは、最初のプログラムが &man.connect.2; を呼び出した時、tun インターフェイスの IP アドレスが、 ソケットの終端に割り当てられてしまうという問題です。 カーネルは、 外へ出ていく最初のパケットを作り、それを tun デバイスへ書き込みます。 そして ppp は、 そのパケットを読み込んで接続を確立します。 ppp は動的に IP アドレスを割り当てるため、 もしインターフェイスのアドレスが変化してしまうと、 最初に割り当てられたソケット終端の IP アドレスは無効になってしまいます。 そのため、それ以降相手に送られるすべてのパケットは通常、 相手に届くことはないでしょう。もし仮に届いたとしても、 既にこちらの IP アドレスは変更されているので、 どんな反応も最初のマシンには戻ってきません。 この問題に対処する理論的な方法がいくつかあります。もし可能なら、 相手が再度、同じ IP アドレスを割り当ててくれることが一番です :-) ppp の現在のバージョンはこれを行ないますが、 他のほとんどの実装はそういった動作をしません。 我々の側から対処できる最も簡単な方法は、tun インターフェイスの IP アドレスを固定する事です。またそのかわりに、 外に出ていくパケットを変更して、 発信元 IP アドレスをインターフェイスの IP アドレスから、交渉によって得られた IP アドレスに、 適宜書きかえる事によっても対処できます。 これは、基本的に ppp の最新バージョンにある iface-alias オプションが行なっていることと同じです (&man.libalias.3; および、ppp の スイッチにも関係します)。それは、以前の IP アドレスをすべて管理し、 それらを最後の交渉によって得られた IP アドレスに対して NAT 機能を有効化します。 もう 1 つの (おそらく最も信頼できる) 方法は、bind された すべてのソケットの IP アドレスを、 異なるものに変更できるシステムコールを実装することです。 pppは、 交渉によって新しい IP アドレスを得た時、 このシステムコールを用いて実行されているプログラムにある、 すべてのソケットを書きかえてやるわけです。 同じシステムコールが、DHCP クライアントが利用するソケットを 強制的に再 bind するのにも使うことができるでしょう。 3 つ目の方法は、IP アドレスを指定しないでインターフェイスを利用できるようにすることです。 外に出ていくパケットは、最初の SIOCAIFADDR ioctl の完了まで、 255.255.255.255 という IP アドレスが与えられます。 これによって、ソケットは常に bind することができます。 ppp に対して発信元 IP アドレスを変更させる事になりますが、 もしそれが 255.255.255.255 になっていたら、IP アドレスと IP チェックサムだけ変更すれば良ければの話になります。 この方法はちょっとした変更ですが、 他の機構が今までのように、IP アドレスを固定して利用する場合に、 カーネルが不適切に設定されたインターフェイスに向けて、 正常でないパケットを送り出してしまう可能性があります。 何故ほとんどのゲームが スイッチ付きだと動かないんですか? libalias を使っている時にゲームなどの類のものが動作しない理由は、 外側にあるマシンが接続しようとしているか、内側にあるマシンに (余計な) UDP パケットを送信しようとしているからです。 内側のマシンにこれらのパケットを送るべきかについて、 NAT ソフトウェアは関知しません。 うまく動かすためには、 実行中のものが問題の発生しているソフトウェアだけであるかを確認し、 ゲートウェイの tun インタフェースに対して tcpdump を実行するか、 ゲートウェイ上で ppp の TCP/IP ログ記録を有効化 (set log +tcp/ip) してください。 行儀の悪いソフトウェアを起動する際に、 ゲートウェイマシンを通過するパケットを監視すべきです。 外側から何かパケットが戻ってきた時に、 そのパケットは破棄されるでしょう (それが問題なのです)。 これらのパケットのポート番号に注意して、 その行儀の悪いソフトウェアを停止してください。 これを数回繰り返してポート番号が常に同じであるかを確認してみてください。 同じであった場合は、 /etc/ppp/ppp.conf の適切なセクションに次の行を入れると、 そのソフトウェアは動作するようになるでしょう。 nat port proto internalmachine:port port ここで proto は tcp か udp であり、 internalmachine はパケットを送りたいマシン、そして port はパケットの送信先のポート番号です。 上記のコマンドを変更せずに、 他のマシン上でそのソフトウェアを使用できるようにはしたくないかもしれません。 そして同時に二つの内部のマシン上でそのソフトウェアを実行することは、 この質問の範囲を超えています。結局、外側の世界からは、 内部ネットワーク全体がただ一つのマシンとして見えるのです。 ポート番号が常に同じとは限らない場合、さらに三つのオプションがあります。 libalias でサポートするようにし、結果を送り付ける。 特定の場合の例は /usr/src/lib/libalias/alias_*.c にあります (alias_ftp.c は良いプロトタイプです)。これには通常、外向きの特定のパケットを読み、 内部の計算機のある特定のポートへの接続を開始するような命令が、 外部の計算機対して送られていることを見分け、 後続のパケットがどこに行けばいいのかが分かるように、 エイリアステーブル中の route の部分を設定する、という作業が含まれます。 これは最も難しい方法ですが、最も良い方法でもありますし、ソフトウェアが 複数の計算機で動くようにできます。 プロキシ (proxy) を使う。アプリケーションが、たとえば socks5 をサポートしているか、(cvsup のように) passive オプションを持っているとこの方法が使えます。 passive とは相手側のほうから接続を求めてくることを避けるためにあるオプションです。 nat addr を使ってなんでもかんでも内部の計算機に向けて流してしまう。 これはちょっと無理矢理な解決法です。 有用なポート番号のリストはありませんか? まだ出来ていません。しかし、 これは (関心を持って頂けるならば) そういったリストにしていく予定です。 それぞれの例にある internal は、 ゲームで遊ぶマシンの IP アドレスに置き換えてください。 Asheron's Call nat port udp internal:65000 65000 手動でゲームのポート番号を 65000 に変更してください。 マシンが複数ある場合は、それぞれのマシンに重複しないポート番号 (つまり 65001、65002 など) を設定し、その設定ごとに nat port の行を追加します。 Half Life nat port udp internal:27005 27015 PCAnywhere 8.0 nat port udp internal:5632 5632 nat port tcp internal:5631 5631 Quake nat port udp internal:6112 6112 このように設定する代わりに、 www.battle.net で Quake のプロキシ (proxy) がサポートされているか調べてもいいでしょう。 Quake2 alias port udp internal:27901 27910 Red Alert nat port udp internal:8675 8675 nat port udp internal:5009 5009 FCS エラーって何? FCS とは Frame Check Sequence (フレームチェックシーケンス) の略です。 個々の ppp パケットには、 送受信するデータが正しいかを調べるためのチェックサムが含まれています。 受信したパケットの FCS が正しくない場合は、そのパケットは廃棄され、 HDLC FCS カウントが増やされます。 HDLC エラーの数は、 show hdlc コマンドを使って表示できます。 リンクの品質が悪かったり、 シリアルドライバがパケットを取りこぼしていたりすると、 FCS エラーがたびたび発生します。 FCS エラーは、 圧縮プロトコルの速度低下の原因にはなりますが、 特に心配する必要はありません。 外付けモデムを使っている場合は、 ケーブルがちゃんとシールドされているかを確認してください。 そうでない場合、 FCS エラーの原因となる場合があります。 接続直後からリンクがフリーズし、大量の FCS エラーが発生する場合は、 リンクが 8 ビットクリーンでない可能性があります。 ソフトウェアフロー制御 (XON/XOFF) が使われていないことを確認してください。 どうしてもソフトウェアフロー制御を使わなければならない場合は、 set accmap 0x000a0000 コマンドを使用して、 ppp に ^Q と ^S をエスケープさせてください。 リモートホストが PPP プロトコルを使用してない場合も、大量の FCS エラーが発生します。 この場合はログをとりながら非同期で接続し、 ログインプロンプトやシェルプロンプトが送られて来ていないか確認してください。 ログファイルにリンクを終了した原因となるような記録がない場合は、 リモートホスト (プロバイダ?) の管理者に、 セッションを終了された理由を尋ねてください。 ゲートウェイで PPPoE を実行すると MacOS や Windows 98 との接続がフリーズしてしまうのですが、 これはなぜなのでしょうか? Michael Wozniak mwozniak@netcom.ca 氏が、この現象に関して説明してくれました。 また、Dan Flemming danflemming@mac.com 氏は MacOS での解決策を提供してくれました。 情報の提供に感謝します。 これは、いわゆる「ブラックホールルータ (Black Hole router)」に原因があります。 Windows 98 と MacOS (および、おそらく他の Microsoft 社製 OS) の TCP パケット送出は、 PPPoE のフレーム (Ethernet の MTU は標準で 1500) に入らないような大きなセグメントサイズを要求します。 そしてさらに分割禁止 ("don't fragment") フラグビットを (TCP パケットにデフォルトで) セットするのですが、 Telco のルータは、分割が必須 ("must fragment") であることを示す ICMP メッセージを、接続しようとするウェブサイトに対して送出しません (つまり、ルータは正しく ICMP パケットを送出しているのですが、 ウェブサイトのファイアウォールがそれを落としているのです)。 そのためウェブサーバが PPPoE 接続に対して大きすぎるフレームを送出すると Telco のルータはそのフレームを捨ててしまい、 見ようとしたページが表示されないという症状が現われます (MSS より小さいページや画像は表示されます)。 ほとんどの Telco PPPoE 設定は、標準でこのように設定されているようです。 (ああ、彼らがルーティングプログラムの作り方を理解してさえいれば…)。 一つの解決法は、Windows 95/98 マシンで regedit を使い、 次のレジストリエントリを追加することです。 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTU レジストリエントリは、1450 の値 (もっと正確に言うと、TCP パケットを PPPoE フレームに完全に適合させるには 1464 であるべきでですが、 1450 とすると、現われる可能性がある他の IP プロトコルに対してエラーマージンを確保することができます) にする必要があります。 このレジストリキーは、Windows2000 で Tcpip\Parameters\Interfaces\ID for adapter\MTU に移されたという報告がありました。 FreeBSD/NAT/PPPoE ルータと共存させるために Windoze の MTU を変更する方法に関する詳細は、 Microsoft Knowledge Base にある、 番号 Q158474 - Windows TCPIP Registry Entries、 および番号 Q120642 - TCPIP & NBT Configuration Parameters for Windows NT を参照してください。 残念なことに、MacOS には TCP/IP 設定を変更する方法がありません。 しかし、Sustainable Softworks 社 が販売している OTAdvancedTuner (OT は OpenTransport という MacOS の TCP/IP スタックの名前のこと) のような商用ソフトウェアが存在します。 このソフトウェアは、ユーザから TCP/IP 設定の変更を行なうことを可能にします。 MacOS NAT ユーザはドロップダウンメニューから ip_interface_MTU を選択し、 ボックスにある 1500 の代わりに 1450 を入力し、 Save as Auto Configure の隣のボックスをクリックして Make Active をクリックする必要があります。 ppp の最新版 (2.3 かそれ以降) には、自動的に MSS を適切な値に調節する enable tcpmssfixup コマンドがあります。 この機能は標準で有効になっています。 もし旧バージョンの ppp を使わなければならない状況にあるなら、 tcpmssd の port をご覧になると良いでしょう。 どれにも当てはまらない! どうしたらいいの? これまでのすべての質問に当てはまらない場合、設定ファイル、 ppp の実行方法、ログファイルの該当部分と netstat -rn コマンドの出力 (接続前と接続後) を含む、 あなたの持っているすべての情報を &a.questions; や comp.unix.bsd.freebsd.misc ニュースグループへ送ってください。誰かがあなたを正しい方向へ導いてくれるでしょう。 シリアル接続 訳: 一宮 亮 ryo@azusa.shinshu-u.ac.jp、 1997 年 11 月 16 日 このセクションでは、FreeBSD でシリアル接続をする時の一般的な質問に答えます。 PPP および SLIP については、 のセクションを参照してください。 どうやったら FreeBSD がシリアルポートを認識したことを知る事ができますか? FreeBSD のカーネルが起動する時、カーネルはその設定にしたがって、 システムのシリアルポートを検出します。起動時に表示されるメッセージをよく観察するか、 起動後に次のコマンドを実行する事によって確認できます。 dmesg | grep sio ここに上に挙げたコマンドの出力例を示します。 sio0 at 0x3f8-0x3ff irq 4 on isa sio0: type 16550A sio1 at 0x2f8-0x2ff irq 3 on isa sio1: type 16550A これは、二つのシリアルポートを示しています。1 番目は、 irq が 4 で 0x3f8 のポートアドレスを使用しています。 そして、16550A-type UART チップが存在します。 2 番目は、同じチップを使っていますが、 irq は 3 で、0x2f8 のポートアドレスを使用しています。内蔵のモデムカードは、 通常のシリアルポートと同じように扱われますが、 常時シリアルポートにモデムが接続されているという点で異なります。 GENERIC カーネルは、上の例と同じ irq とポートアドレスの設定の二つのシリアルポートをサポートしています。 これらの設定があなたのシステムに合わない場合、 またはモデムカードを追加した場合やカーネルの設定以上にシリアルポートを持っている場合は、 カーネルを再構築してください。 詳しくは、 カーネルの構築の項を参照してください。 どうやったら FreeBSD がモデムカードを認識したことを知ることができますか? 前の質問を参照してください。 FreeBSD 2.0.5 にアップグレードしたら tty0X が見つからなくなってしまったのですが 心配ありません。ttydX に統合されました。 ただ、古い設定ファイルのすべてを更新する必要があります。 どうやったら FreeBSD でシリアルポートにアクセスできますか? 3 番目のポート sio2 (&man.sio.4; をご覧ください。DOS では、COM3 と呼ばれます。) には、 ダイヤルアウトデバイスとしては /dev/cuaa2、 ダイヤルインデバイスとして /dev/ttyd2 があります。 それではこの両者にはどのような違いがあるのでしょうか? まず、ダイヤルインの時には ttydX を使います。 /dev/ttydX をブロッキングモードでオープンすると、 プロセスは対応する cuaaX デバイスがインアクティブになるのを待ちます。 次に CD 信号がアクティブになるのを待ちます。 cuaaX デバイスをオープンすると、シリアルポートが ttydX デバイスによってすでに使われていないかどうかを確認します。 もしこのポートが使用可能であれば、ポートの使用権を ttydX から「奪い取る」のです。 また、cuaXX デバイスは CD 信号を監視しません。 この仕組みと自動応答モデムによって、 リモートユーザーをログインさせたり、 同じモデムでダイヤルアウトしたりすることができ、 システムのあらゆるトラブルの面倒を見ることができるでしょう。 マルチポートシリアルカードをサポートさせるにはどうしたらよいのでしょうか? 繰り返しになりますが、 カーネルコンフィグレーションのセクションでは、 あなたのカーネルの設定についての情報が得られるでしょう。 マルチポートシリアルカードを使用するためには、カーネルの設定ファイルに、 カードの持つそれぞれのシリアルポートに対応する &man.sio.4; の行を記述する必要があります。しかし、 irq とベクタアドレスは一つのエントリにのみ記述してください。 カード上のすべてのポートは一つの irq を共有しなければなりません。 一貫性を持たせるためにも、 最後のシリアルポートの所で irq を指定してください。 また、COM_MULTIPORT オプションも付けてください。 次に示す例は、AST の 4 ポートシリアルカードを irq 7 で設定したものです。 options "COM_MULTIPORT" device sio4 at isa? port 0x2a0 tty flags 0x781 device sio5 at isa? port 0x2a8 tty flags 0x781 device sio6 at isa? port 0x2b0 tty flags 0x781 device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr このフラグはマスタポートがマイナー番号 7 (0x700) を持っていて、 検出時の診断機能を有効にし (0x080)、 そしてすべてのポートで irq を共有する (0x001) ということを意味しています。 FreeBSD で複数のマルチポートシリアルカード間で irq を共有することはできますか? 現在のところはできません。それぞれのカード毎に異なった irq を使ってください。 ポートにデフォルトのパラメータを設定する事は出来ますか? ttydX デバイス (または cuaaX デバイス) は、 アプリケーションのためにオープンする標準的なデバイスです。 プロセスがそのポートをオープンする時、 プロセスはデフォルトの端末 I/O 設定を取得します。 これらの設定は次のコマンドで確認することができます。 stty -a -f /dev/ttyd1 このデバイスに対する設定を変更した場合、 その設定はデバイスをクローズするまで有効です。 デバイスを再オープンした場合、それらの設定はデフォルトに戻ってしまいます。 デフォルトの設定に変更を加えるために、 「初期設定」デバイスをオープンし、 設定を修正することができます。 たとえば、CLOCAL モード、8 ビット、 XON/XOFF フロー制御という設定を ttyd5 のデフォルトにしたい場合、次のように行なってください。 stty -f /dev/ttyid5 clocal cs8 ixon ixoff この設定を行なうためのコマンドを記述するのに適切なファイルは、 /etc/rc.serial です。 これでアプリケーションが ttyd5 をオープンした時に、 これらの設定をデフォルトで取得します。 しかし、こういったリンクによる設定は変更可能です。 「設定固定」デバイスを調整してやることによって、 アプリケーションによる設定の変更を禁止することができます。 たとえば、ttyd5 の通信速度を 57600bps に固定するには、次のように行ってください。 stty -f /dev/ttyld5 57600 これにより、アプリケーションは ttyd5 をオープンし、ポートの通信速度を変更しようとしますが、 通信速度は 57600bps のままになります。 当然のことながら、初期設定デバイスおよび、設定固定デバイスは root のみが書き込みできるようになっていなければなりません。 しかし、&man.MAKEDEV.8; スクリプトはデバイスエントリを作成する時に、 このような設定は行いません。 どのようにしたらモデム経由でダイヤルアップログインができるのでしょうか? つまり、インターネットサービスプロバイダーになりたいのですね。 それにはまず、1 台ないし複数の自動応答モデムが必要です。 モデムには、キャリアーを検出した時には CD 信号を出力し、 そうでない場合には出力しないことが必要とされます。 また DTR 信号が on から off になった時には、 電話回線を切断し、モデム自身をリセットしなければなりません。 おそらく、RTS/CTS フロー制御を使うか、 ローカルフロー制御をまったく使わないかのどちらかでしょう。 最後に、コンピュータとモデムの間は固定速度でなければなりません。 ただ、(ダイヤルアップの発呼者に対して親切であるためには、 ) こちらのモデムと相手側のモデムの間の速度を、 モデム間で自動調整できるようにすべきでしょう。 多くあるヘイズコマンド互換モデムに対して、次のコマンドはこれらの設定を行ない、 その設定を不揮発性メモリーに保存します。 AT&C1&D3&K3&Q6S0=1&W MS-DOS のターミナルプログラムに頼らずに AT コマンドを送出するには、 「AT コマンドを入力するには」のセクションを参照してください。 次に、モデム用のエントリを /etc/ttys (&man.ttys.5; 参照) に作成しましょう。 このファイルには、 オペレーティングシステムがログインを待っているすべてのポートが記述されています。 以下のような行を追加してください。 ttyd1 "/usr/libexec/getty std.57600" dialup on insecure この行は、2 番目のシリアルポート (/dev/ttyd1) には、 57600bps の通信速度でノンパリティ (std.57600: これは /etc/gettytab に記述されています。&man.gettytab.5; 参照) のモデムが接続されていることを示しています。 このポートの端末タイプは dialup です。 またこのポートは、on すなわちログイン可能であり、 insecure これは root がこのポートから直接ログインするのは、 許可されていないということを意味します。 このようなダイヤルインポートに対しては、 ttydX のエントリを使用してください。 これが一般的な、ターミナルタイプとして dialup を使う方法です。多くのユーザーは、 .profile や .login で、 ログイン時の端末タイプが dialup であった場合には、 実際の端末タイプをユーザーに問い合わせるように設定しています。 この例は、ポートが insecure でした。このポートで root になるには、 一般ユーザーとしてログインし、それから su を使って root になってください。 もし、secure を指定したならば、 直接 root がそのポートからログインできます。 /etc/ttys に変更を加えた後は、HUP シグナル (SIGHUP) を &man.init.8; プロセスに送る必要があります。 &prompt.root; kill -HUP 1 この操作は init プロセスに /etc/ttys を再読み込みさせます。 これにより、init プロセスは getty プロセスをすべての on となっているポートに起動させます。 次のようにして、ポートがログイン可能かを知ることができます。 &prompt.user; ps -ax | grep '[t]tyd1' ログイン可能であれば、次のような出力が得られるはずです。 747 ?? I 0:00.04 /usr/libexec/getty std.57600 ttyd1 ダムターミナルを FreeBSD マシンに接続するにはどうしたらよいのでしょうか? もし、他のコンピューターを FreeBSD の端末として接続したいのならば、 お互いのシリアルポート間をつなぐヌルモデムケーブル (訳注: リバースケーブルもしくはクロスケーブルとも呼ばれます) を用意してください。 もし、既製の端末を使う場合は、付属するマニュアルを参照してください。 そして、/etc/ttys (&man.ttys.5; 参照) を上と同じように変更してください。 たとえば、WYSE-50 という端末を 5 番目のポートに接続するならば、 次のようなエントリを使用してください。 ttyd4 "/usr/libexec/getty std.38400" wyse50 on secure この例は、/dev/ttyd4 ポートにノンパリティ、 端末タイプが wyse50、通信速度が 38400bps (std.38400: この設定は、 /etc/gettytab に記述されています。&man.gettytab.5; 参照) の端末が存在しており、 root のログインが許可されている (secure) であることを示しています。 どうして tip や cu が動かないのですか? おそらくあなたのシステムでは &man.tip.1; や &man.cu.1; は uucp ユーザーか、 dialer グループによってのみ実行可能なのでしょう。 dialer グループは、 モデムやリモートシステムにアクセスするユーザーを管理するために、 使用することができます。 それには、/etc/group ファイルの dialer グループにあなた自身を追加してください。 そうする代わりに、次のようにタイプすることにより、 あなたのシステムの全ユーザーが tip や cu を実行できるようになります。 &prompt.root; chmod 4511 /usr/bin/cu &prompt.root; chmod 4511 /usr/bin/tip 私の Hayes モデムはサポートされていないのですが、 どうしたらいいのでしょうか。 実際、 &man.tip.1; のオンラインマニュアルは古くなっています。 すでに、Hayes ダイアラが実装されています。 /etc/remote ファイル (&man.remote.5; 参照) で、 at=hayes と指定してください。 Hayes ドライバは、最近のモデムの新しい機能である、 BUSY、 NO DIALTONE、 CONNECT 115200 などのメッセージを認識できるほど賢くはなく、 単に混乱を起こすだけです。 &man.tip.1; を使う場合には (ATX0&Wとするなどして)、 これらのメッセージを表示させないようにしなくてはいけません。 また、tip のダイヤルのタイムアウトは 60 秒です。 モデムのタイムアウト設定はそれより短くすべきであり、 そうしないと tip は通信に問題があると判断するでしょう。 ATS7=45&W を実行してください。 実際、デフォルトの tip は Hayes の完全なサポートをしているわけではありません。 解決方法は /usr/src/usr.bin/tip/tip の下の tipconf.h を変更することです。 もちろん、これにはソース配布ファイルが必要です。 #define HAYES 0 と記述されている行を #define HAYES1 と変更し、そして make と make install を実行します。これでうまく動作するでしょう。 これらの AT コマンドを入力するには? /etc/remote ファイル (&man.remote.5; 参照) の中で direct エントリを作ります。 たとえばモデムが 1 番目のシリアルポートである /dev/cuaa0に接続されている場合、 次のようにします。 cuaa0:dv=/dev/cuaa0:br#19200:pa=none モデムがサポートする最大の bps レートを br フィールドに使います。 そして tip cuaa0 (&man.tip.1; 参照) を実行すると、モデムが利用できるようになります。 /dev/cuaa0がシステムに存在しない場合は、次のようにします。 &prompt.root; cd /dev &prompt.root; ./MAKEDEV cuaa0 または root になって以下のように cu コマンドを実行します。 &prompt.root; cu -lline -sspeed line にはシリアルポート (たとえば /dev/cuaa0)を指定します。 そして speed には接続する速度 (たとえば 57600) を指定します。 その後 AT コマンドを実行したら、 ~. と入力すれば終了します。 pn 機能の <@> 記号が使えません! 電話番号 (pn) 機能の中での <@> 記号は、 tip に /etc/phones にある電話番号を参照するように伝えます。しかし <@> の文字は /etc/remote のような設定ファイルの中では特殊文字となります。 そこで、バックスラッシュを使ってエスケープを行います。 pn=\@ コマンドラインから電話番号を指定するには? generic エントリと呼ばれるものを /etc/remote ファイル (&man.remote.5; 参照) に追加します。 たとえば、次のようにします。 tip115200|Dial any phone number at 115200 bps:\ :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du: tip57600|Dial any phone number at 57600 bps:\ :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du: そして tip -115200 5551234 のように利用できます。 &man.tip.1; より &man.cu.1; を使いたい場合、 cu の generic エントリを使います。 cu115200|Use cu to dial any number at 115200bps:\ :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du: そして cu 5551234 -s 115200 と実行します。 毎回 bps レートを入力しなければいけませんか? tip1200 や cu1200 用のエントリを記述し、 適切な通信速度を br フィールドに設定します。 &man.tip.1; は 1200bps が正しいデフォルト値であるとみなすので、 tip1200 エントリを参照します。 もちろん 1200bps を使わなければならないわけではありません。 ターミナルサーバを経由して複数のホストへアクセスしたいのですが。 毎回接続されるのを待って CONNECT <host> と入力するかわりに、 tip の cm 機能を使います。 たとえば、/etc/remote (&man.remote.5; 参照) に次のようなエントリを追加します。 pain|pain.deep13.com|Forrester's machine:\ :cm=CONNECT pain\n:tc=deep13: muffin|muffin.deep13.com|Frank's machine:\ :cm=CONNECT muffin\n:tc=deep13: deep13:Gizmonics Institute terminal server:\ :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234: これで、tip pain や tip muffin と実行すると pain や muffin のホストに接続することができ、 tip deep13 を実行するとターミナルサーバに接続します。 tip を使ってそれぞれのサイトの複数の回線に接続できますか? これは大学に電話回線がいくつかあって、 数千人の学生が接続しようとする場合によくある問題です。 あなたの大学のエントリを /etc/remote ファイル (&man.remote.5; 参照) に作成して、 pn のフィールドには <\@> を使います。 big-university:\ :pn=\@:tc=dialout dialout:\ :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none: そして /etc/phones ファイル (&man.phones.5; 参照) に大学の電話番号の一覧を書きます。 big-university 5551111 big-university 5551112 big-university 5551113 big-university 5551114 &man.tip.1; は一連の電話番号を上から順に試みて、 最終的に接続できなければあきらめます。リトライを続けさせたい場合は、 tip を while ループに入れて実行します。 CTRL+P を 1 回送るために 2 度押す必要があるのはなぜ? CTRL+P は通常「強制 (force)」文字であり、 &man.tip.1; に次の文字がリテラルデータであることを伝えます。 強制文字は「変数の設定」を意味する ~s エスケープによって、 他の文字にすることができます。 ~sforce=<single-char> と入力して改行します。 <single-char> は、任意の 1 バイト文字です。 <single-char> を省略すると NUL 文字になり、 これは CTRL+2 や CTRL+SPACE を押しても入力できます。 いくつかのターミナルサーバで使われているのを見ただけですが、 <single-char> に SHIFT+CTRL+6 に割り当てるのもよいでしょう。 $HOME/.tiprc に次のように定義することで、 任意の文字を強制文字として利用できます。 force=<single-char> 打ち込んだ文字が突然すべて大文字になりました?? CTRL+A を押してしまい、caps-lock キーが壊れている場合のために設計された &man.tip.1; の raise character モードに入ったのでしょう。 既に述べた ~s を使って、 raisechar をより適切な値に変更してください。 もしこれら両方の機能を使用しないのであれば、 強制文字と同じ設定にすることもできます。 以下は CTRL+2 や CTRL+A などを頻繁に使う必要のある Emacs ユーザにうってつけの .tiprc ファイルのサンプルです。 force=^^ raisechar=^^ ^ は SHIFT+CTRL+6 です。 tip でファイルを転送するには? もし他の UNIX のシステムと接続しているなら、 ~p (送信) や ~t (受信) でファイルの送受信ができます。 これらのコマンドは、相手のシステムの上で &man.cat.1; や &man.echo.1; を実行することで送受信をします。書式は以下のようになります。 ~p <ローカルのファイル名> [<リモートのファイル名>] ~t <リモートのファイル名> [<ローカルのファイル名>] この方法ではエラーチェックを行いませんので、 zmodem などの他のプロトコルを使った方がよいでしょう。 tip から zmodem を実行するには? まず始めに、FreeBSD Ports Collection (lrzszと rzsz との、2 つの通信カテゴリーのプログラムのどちらか) をインストールします。 ファイルを受信するには、リモート側で送信プログラムを起動します。 そして、Enter キーを押してから ~C rz (lrzsz をインストールした場合は ~C lrz) と入力すると、 ローカル側へのファイルの受信が始まります。 ファイルを送信するには、リモート側で受信プログラムを起動します。 そして、Enter キーを押してから ~C sz <files> (lrzsz をインストールした場合は ~C lsz <files>) と入力すると、リモート側へのファイルの送信が始まります。 設定が正しいのにもかかわらず、FreeBSD がシリアルポートを見付けられません。 マザーボードやシリアルカードが Acer の UART チップを使った物の場合、 FreeBSD の sio ドライバでは正しく検出する事が出来ません。 この問題を解決するためには、 www.lemis.com からパッチを入手してください。 その他の質問 訳: &a.jp.yoshiaki;、 &a.jp.sugimura;、 福間 康弘 yasuf@big.or.jp、 1997 年 11 月 10 日 - 1999 年 5 月 8 日 FreeBSD は Linux より多くのスワップ領域を消費するのはなぜですか? 実際にはそうではありません。 FreeBSD は Linux よりもスワップを多く使っているように見えるだけです。 この点における FreeBSD と Linux の主な違いは、 FreeBSD はより多くのメインメモリを有効利用できるようにするため、 完全にアイドルになったものやメインメモリ上の使われなくなったページを、 スワップにあらかじめ積極的に移動しているということです。 Linux では、 最後の手段としてページをスワップに移動させるだけという傾向があります。 このスワップの使い方は、 メインメモリをより効果的に使用することによってバランスが保たれています。 FreeBSD はこのような状況では先手策を取りますが、 システムが本当に空き状態の時に、 理由も無くページをスワップしようと決めることはないということに注意してください。 したがって、 夜中に使わずにおいたシステムが朝起きたとき、 すべてページアウトされているということはないのです。 ほとんどプログラムは実行されていないのに、 どうして &man.top.1; は非常に少ない free memory を報告するのでしょうか? 簡単に言えば、free memory とは無駄になっているメモリのことだからです。 プログラムが確保しているメモリ以外のすべてのメモリは、 FreeBSD カーネル内でディスクキャッシュとして利用されます。 この値は &man.top.1; において Inact、 Cache Buf として表示され、 それぞれは異なるエージングレベル (訳注: データがどれだけ古いかを示す評価値) でキャッシュされた全データを表します。 データがキャッシュされると言うのは、 最近アクセスされたデータであれば、 再度そのデータをアクセスするためにシステムが遅いディスクにアクセスする必要がない、 ということを意味します。 そのため、全体のパフォーマンスが向上します。 一般的に、&man.top.1; で表示される Free メモリが小さい値を示すことは良いことで、 自由に使えるメモリの残量が本当に少ない、 ということを表しているわけではありません。 FreeBSD の実行フォーマットの a.out、ELF とはどのようなものですか? また、a.out、ELF を使う理由は何でしょう? FreeBSD が何故 ELF フォーマットを利用しているのかを理解するためには、 まず UNIXにおいて現在「優勢」な 3 種類の実行フォーマットについて いくらか知っておく必要があります。 FreeBSD 3.x より前の FreeBSD では a.out フォーマットが使われていました。 &man.a.out.5; 最も古く 「由緒正しい」 unix オブジェクトフォーマットです。 マジックナンバを含む短くてコンパクトなヘッダが先頭にあり、 これがフォーマットの特徴とされています (&man.a.out.5; に詳細な内容があります)。 ロードされる 3種類のセグメント、 .text、 .data、 .bss と加えてシンボルテーブルと文字列テーブルを含みます。 COFF SVR3 のオブジェクトフォーマットです。 ヘッダは単一のセクションテーブルから成り、 .text、 .data、 .bss セクション以外の部分を持つことができます。 ELF COFFの後継です。複数のセクションをサポートし、32-bit と 64-bitのいずれの値も可能です。大きな欠点の一つは、ELF はそれぞれのシステムアーキテクチャ毎に単一の ABI のみが存在するという仮定で設計されていることです。 この仮定はまったく正しくありません。 商用の SYSV の世界でさえそうです (少なくとも SVR4、 Solaris、SCO の 3種類の ABI があります)。 FreeBSD はこの問題を解決するための試みとして、 既知の ELF 実行ファイルに ABI に応じた情報を 書き加えるユーティリティを提供しています。 詳しくは &man.brandelf.1; のマニュアルページを参照してください。 FreeBSD は伝統的な立場をとり、数多くの世代の BSD のリリースで試され、実証されてきた &man.a.out.5; フォーマットを伝統的に使用しています。 いつかは FreeBSD システムでネイティブ ELF バイナリを作り、 実行することができるようになるかもしれませんが、 初期の頃 FreeBSD では ELF をデフォルトのフォーマットに変更するという動きは ありませんでした。なぜでしょうか? ところで Linux においては、 ELF への苦痛をともなった変更は、 その時に a.out 実行フォーマットから逃れたというよりは、 ジャンプテーブルベースの共有ライブラリのメカニズムの柔軟性の低さからの脱却でした。 これはベンダや開発者全体にとって、 共有ライブラリの作成が非常に難しかった原因でした。 ELF のツールには共有ライブラリの問題を解決することができるものが提供されており、 またいずれにせよ一般的に「進歩」していると考えられます。 このため移行のコストは必要なものとして容認され、 移行は行なわれました。 FreeBSD の場合は、共有ライブラリのメカニズムは Sun の SunOS スタイルの共有ライブラリのメカニズムに極めて近いものになっていて、 非常に使いやすいものになっています。 しかしながら、FreeBSD では 3.0 から ELF バイナリをデフォルトのフォーマットとして公式にサポートしています。 a.out 実行フォーマットはよいものを私達に提供してくれているものの、 私たちの使っているコンパイラの作者である GNU の人々は a.out フォーマットのサポートをやめてしまったのでした。 このことは、 私たちに別バージョンのコンパイラとリンカを保守することを余儀なくされることとなり、 最新の GNU 開発の努力による恩恵から遠ざかることになります。 その上、ISO C++ の、 とくにコンストラクタやデストラクタがらみの要求もあって、今後の FreeBSD のリリースでネイティブの ELF のサポートされる方向へと話が進んでいます。 それにしても、なぜそんなに多くのフォーマットがあるのですか? もうおぼろげになってしまった暗い過去に、単純なハードウェアがありました。 この単純なハードウェアは、単純で小さなシステムをサポートしていました。 a.out はこの単純なシステム (PDP-11) での作業を行なうバイナリとして完全に適したものだったのです。 人々はこの単純なシステムから UNIX を移植する際に、a.out フォーマットをそのまま使いました。というのは Motorola 68k、VAXen、 といったアーキテクチャへの UNIX の初期の移植ではこれで十分だったからです。 やがてある聡明なエンジニアが、 ソフトウェアでちょっとしたトリックを使うことを決めました。 彼はいくつかのゲートを削り取って CPU のコアをより速く走らせることができたのです。 これは新しい種類のハードウェア (今日では RISC として知られています) で動いたのです。 a.out はこのハードウェアには適していなかったので、 このハードウェア上で多くのフォーマットが、 限定された単純な a.out フォーマットでのものよりもより良いパフォーマンスを出すことを目指して開発されたのです。 COFF、ECOFF、 そしていくつかの有名でないフォーマットが ELF が標準になる前に開発され、 それらの限界が探求されたのです。 さらに、プログラムサイズは巨大になり、 ディスク (および物理メモリ) は依然として相対的に小さかったため、 共用ライブラリのコンセプトが誕生しました。 また、VM システムはより複雑なものになりました。 これらの個々の進歩は a.out フォーマットを使用して遂げられましたが、 その有用性は新しい機能とともにどんどん広がってきました。 これらに加え、実行時に必要なものを動的にロードする、 または初期化コードの実行後にプログラムの一部を破棄し、 コアメモリおよびスワップ空間を節約するという要望が高まりました。 プログラミング言語はさらに複雑になり、main 関数の前に自動的にコールされるコードの要望が高まりました。 多くの機能拡張が行なわれ、a.out フォーマットがこれらすべてを実現できるようになり、 それらはしばらくは基本的に動作していました。 やがて、a.out はコードでのオーバヘッドと複雑さを増大させずに、 これらの問題すべてを処理することに無理がでてきました。 一方、ELF はこれらの問題の多くを解決しますが、 現状稼働しているシステムからの切替えは厄介なものになるでしょう。 そのため ELF は、a.out のままでいることが ELF への移行よりももっと厄介なものになるまで待つ必要がありました。 しかし時が経つにつれ、FreeBSD のビルドツールの元となったツール群 (特にアセンブラとローダ) と FreeBSD のビルドツール群は異なった進化の経路をたどりました。 FreeBSD のツリーでは、共有ライブラリが追加され、 バグフィックスも行われました。 もともとのツール群を作成した GNU の人たちは、プログラムを書き直し、 クロスコンパイラのサポート、 異なるフォーマットを任意に取り込む機能などを追加していきました。 多くの人々が FreeBSD をターゲットとしたクロスコンパイラの構築を試みましたが、 FreeBSD の使っている as と ld の古いプログラムコードはクロスコンパイルをサポートしておらず、 うまくいきませんでした。 新しい GNU のツール群 (binutils) は、 クロスコンパイル、共有ライブラリ、C++ 拡張などの機能をサポートしています。 さらに数多くのベンダが ELF バイナリをリリースしています。 FreeBSD にとって ELF バイナリが実行できることは、 非常にメリットがあります。ELF バイナリが FreeBSD で動くのなら、a.out を動かすのに手間をかける必要はありませんね。 長い間忠実によく働いた老いた馬は、 そろそろ牧草地で休ませてあげましょう。 ELF は a.out に比べてより表現力があり、 ベースのシステムに対してより幅広い拡張性を提供できます。 ELF 用のツールはよりよく保守されています。 また多くの人にとって重要なクロスコンパイルもサポートしています。 ELF の実行速度は、ほんの少し a.out より遅いかもしれませんが、 実際に速度の差をはかるのは困難でしょう。 ELF と a.out の間には、ページマッピング、 初期化コードの処理など多くの違いがありますが、 とりたてて重要なものはありません。しかし違いがあるのは確かです。ほどなく、 GENERIC カーネルから a.out のサポートが外されます。 a.out のプログラムを実行する必要性がなくなれば、 最終的に a.out のサポートはカーネルから削除されます。 シンボリックリンクの許可属性を chmod で変えられないのはなぜですか? シンボリックリンクは許可属性を持ちません。 また &man.chmod.1; のデフォルト動作は、 シンボリックリンクをたどってリンク先のファイルの許可属性を変更するようになっていません。 そのため、 foo というファイルがあり、 このファイルへのシンボリックリンク bar があったとすると、 以下のコマンドは常に成功します。 &prompt.user; chmod g-w bar しかしこの場合、foo の許可属性は変更されません。 この場合、 か のどちらかのオプションを と同時に使う必要があります。 &man.chmod.1; と &man.symlink.7; のマニュアルページにはもっと詳しい情報があります。 オプションは再帰的に chmod を実行します。ディレクトリやディレクトリへのシンボリックリンクを chmod する場合は気をつけてください。 シンボリックリンクで参照されている単一のディレクトリのパーミッションを変更したい場合は、 &man.chmod.1; をオプションをつけずに、 シンボリックリンクの名前の後ろにスラッシュ (/) をつけて使います。たとえば、foo がディレクトリ bar へのシンボリックリンクである場合、 foo (実際には bar) のパーミッションを変更したい場合には、このようにします。 &prompt.user; chmod 555 foo/ 後ろにスラッシュをつけると、 &man.chmod.1; はシンボリックリンク foo を追いかけてディレクトリ bar のパーミッションを変更します。 ログイン名がいまだに 8 文字に制限されているのはなぜですか? UT_NAMESIZE を変更してシステム全体を作り直せば十分で、 それだけでうまくいくだろうとあなたは考えるかもしれません。 残念ながら多くのアプリケーションやユーティリティ (システムツールも含めて) は、 小さな数値を構造体やバッファなどに使っています (必ずしも 8 や 9 ではなく、 15 や 20 などの変った値を使うものもあります)。 (固定長のレコードを期待するところで可変長レコードになるため、 ) 台無しになったログファイルを得ることになるということだけでなく、 Sun の NIS のクライアントの場合は問題が起きますし、他の UNIX システムとの関連においてこれら以外の問題も起きる可能性があります。 しかし、FreeBSD 3.0 以降では 16 文字となり、 多くのユーティリティのハードコードされた名前の長さの問題も解決されます。 実際にはシステムのあまりに多くの部分を修正するために、 3.0 になるまでは変更が行われませんでした。 それ以前のバージョンでは、これらの問題が起こった場合に、 問題を自分自身で発見し、解決できることに絶対的な自信がある場合は /usr/include/utmp.h を編集し、 UT_NAMESIZE の変更にしたがって、 長いユーザ名を使うことができます。 また、 UT_NAMESIZE の変更と一致するように /usr/include/sys/param.h の MAXLOGNAME 更新しなくてはなりません。 最後に、ソースからビルドする場合は /usr/include を毎回アップデートする必要があることを忘れないように! /usr/src/.. 上のファイルを変更しておいて置き換えましょう。 FreeBSD 上で DOS のバイナリを動かすことはできますか? はい、FreeBSD 3.0 からは、 統合と改良が重ねられた BSDI の doscmd DOS エミュレーションサブシステムを使ってできるようになりました。 今なお続けられているこの努力に興味を持って参加していただけるなら、 &a.emulation; へメールを送ってください。 FreeBSD 3.0 以前のシステムでは、 pcemu という巧妙なユーティリティが FreeBSD Ports Collection にあり、 8088 のエミュレーションと DOS のテキストモードアプリケーションを動かすに十分な BIOS サービスを行ないます。これは X ウィンドウシステムが必要です (XFree86 として提供されています)。 どこで無料の FreeBSD のアカウントを取得できますか? FreeBSD はいずれのサーバーにもアクセスを開放していませんが、 Unix システムへの自由なアクセスを提供しているところがあります。 費用はまちまちで、限定されたサービスが利用できます。 M-Net としても知られる Arbornet, Inc は 1983 年から Unix システムへのアクセスを提供しています。 System III が動作する Altos に始まり、1991 年には BSD/OS に移行しました。2000 年 6 月には、再び FreeBSD に 移行しています。M-Net には SSH または telnet 経由で アクセスすることができ、FreeBSD ソフトウェア一式が 利用できるようになっています。ただし、ネットワーク接続は 会員と、非営利組織として運営されているシステムに寄付をする 後援者に制限されています。また、M-Net は掲示板システムと 双方向チャットも提供しています。 Grex は、 掲示板システムと双方向チャットソフトウェアが同じであることも含め、 M-Net とよく似たサイトを提供しています。しかし、 マシンは Sun 4M で、SunOS が動作しています。 sup とは何で、 どのようにして使うものなのでしょうか? SUP とは、ソフトウェアアップデートプロトコル (Software Update Protocol) で カーネギーメロン大学 (CMU) で開発ツリーの同期のために開発されました。 私たちの中心開発ツリーをリモートサイトで同期させるために使っていました。 SUP はバンド幅を浪費しますので、今は使っていません。 ソースコードのアップデートの現在のおすすめの方法は FreeBSD ハンドブックの「CVSup」にあります。 FreeBSD をクールに使うには? FreeBSD を動かす時に温度測定を行なった人はいますか? Linux は dos よりも温度が下がるということは知っていますが、FreeBSD についてはこのようなことに触れたものを見たことはありません。 実際熱くなっているように見えます。 いいえ。 私たちは 250 マイクログラムの LSD-25 をあらかじめ与えておいたボランティアに対する、 目隠し味覚テストを大量に行なっています。 35% のボランティアは FreeBSD はオレンジのような味がすると言っているのに対し、 Linux は紫煙のような味わいがあると言っている人もいます。 両方のグループとも温度の不一致については何も触れていません。 この調査で、非常に多くのボランティアがテストを行なった部屋から不思議そうに出てきて、 このようなおかしな結果を示したことに私たちは当惑させられました。 私たちは、ほとんどのボランティアは Apple にいて彼らの最新の「引っかいて匂いをかぐ」GUI を使っているのではないかと考えています。 私たちは奇妙な古い仕事をしているのでしょう! 真面目に言うと、FreeBSD や Linux は共に HLT (停止) 命令をシステムのアイドル (idle) 時に使い、 エネルギーの消費を押えていますので熱の発生も少なくなります。 また、APM (advanced power management) を設定してあるなら FreeBSD は CPU をローパワーモードにすることができます。 誰かが私のメモリカードをひっかいているのですか?? FreeBSDでカーネルのコンパイルをしている時、 メモリから引っかいているような奇妙な音が聞こえるようなことはあるのでしょうか? コンパイルをしている時 (あるいは起動時にフロッピドライブを認識した後の短い間など)、 奇妙な引っかくような音がメモリカードのあたりから聞こえてきます。 その通り! BSD の文書には良く、デーモン (daemon) という言葉が出てきます。 ほとんどの人は知らないのですが、 デーモンとは、あなたのコンピュータを依り代とする、 純粋で非物質的な存在のことです。 メモリから聞こえるひっかくような音は、 さまざまあるシステム管理タスクの扱いをいかに最善なものにするか、 といったことを決めるときにデーモンたちが交わす、 かん高いささやき声なのです。 この雑音が聞こえたとき、DOS から fdisk /mbr というプログラムを実行すれば、 うまくデーモンを追い出すことができるでしょう。 でも、デーモンはそれに歯向かって fdisk の実行をやめさせようとするかも知れません。 もし、それを実行しているときにスピーカならビル ゲイツ (Bill Gates) の悪魔のささやきが聞こえてきたら、 すぐに立ち上がって逃げてください。決して振り返ってはいけません! BSD のデーモンたちが押え込んでいた双子のデーモン、DOS と Windows が解放され、 あなたの魂を永遠の破滅へ導こうとマシンを再び支配してしまうことでしょう。 それを知った今や、選べと言われたら、 むしろひっかき音に慣れる方を選ぶのではありませんか? "MFC" とはどういう意味ですか MFC とは、 「CURRENT との合流 (Merged From -CURRENT)」の頭文字をとったものです。 CVS ログで -CURRENT から -STABLE ブランチへの合流を示します。 "BSD" とはどういう意味ですか? この言葉は、仲間うちだけに分かる隠語で何とかという意味です。 文字どおりに訳すことはできませんが、 BSD の訳は「F1 のレーシングチーム」か「ペンギンはおいしいスナック」、 あるいは「俺たちゃ Linux より洒落は利いてるぜ」とかそのへんだと言っておけばおっけーでしょう。 :-) 冗談はさておき、BSD とは、Berkeley CSRG (コンピュータシステム評議会) が彼らの UNIX の配布形態の名前として当時選んだ "Berkeley Software Distribution" の略です。 リポジトリ・コピー (repo-copy) とは一体何のことでしょう? repo-copy (repository copy の略) とは、 CVS リポジトリの中で直接ファイルをコピーすることを示す用語です。 repo-copy を行なわない場合を考えます。 リポジトリの中の異なる場所にファイルをコピーしたり、 移動したりする必要性が生じると、コミッターは ファイルを新しい場所に置くために cvs add を、 そして古いファイルが削除される場合は、古いファイルに対して cvs rm を実行するでしょう。 この方法の欠点は、ファイルの変更履歴 (たとえば CVS ログのエントリ) が新しい場所にコピーされないことです。 FreeBSD プロジェクトではこの変更履歴をとても有用なものだと考えているため、 前述の方法の代わりにリポジトリコピーが良く用いられます。 この操作は cvs プログラムを利用するのではなく、 リポジトリの管理担当者がリポジトリの中でファイルを直接コピーすることによって行なわれます。 なんでバイク小屋 (bikeshed) の色にまで気を使わなければいけないんですか? 一言で言ってしまえば、そうすべきではありません。 もう少し詳しく説明しましょう。 たとえば、あなたがバイク小屋を建てる技術を持っていたとします。 しかしそれは、塗ろうとしている色が気に入らないからと言って、 他人がバイク小屋を建てようとしているのを止めて良い理由にはなりませんよね。 これは、自分の行動について十分な理解を持っているなら、 あなたは細かな機能すべてにわたって議論する必要はないことを示す比喩です。 ある変更によって産み出されるノイズの総量は、 その変更の複雑さに反比例するのだと言っている人達もいます。 さらに詳しく、完全な回答を紹介しましょう。 Poul-Henning Kamp は、 「&man.sleep.1; は分数の秒数を引数として取るべきか」という 非常に長い議論の後で、 A bike shed (any colour will do) on greener grass... というタイトルの長文を投稿しました。 関係のある部分だけを以下に掲載します。
1999 年 10 月 2 日 freebsd-hackers にて Poul-Henning Kamp このバイク小屋、どうだろう? 誰かがたずねました。 長い…というか、むしろ古い話になりますが、 中身はわりと簡単な話です。パーキンソン (C. Northcote Parkinson) は 1960 年代初頭に パーキンソンの法則 と呼ばれる本を書きました。 この中にはさまざまな経営の力学に関する洞察が含まれています。 [ この本に関する解説があったが省略 ] バイク小屋に関連する例として、 もう一つの重要な構成要素となっているのは原子力発電所です。 この本の年代がわかりますね。 パーキンソンは、あなたが重役会に出席して 数百万から数10億ドル規模の原子力発電所の建設の承認を得る ことはできるでしょうが、あなたが建てたいのがバイク小屋ならば、 終わりなき議論に巻き込まれるだろうと言っています。 パーキンソンはこのように説明しています。 これは原発が余りに巨大で高価で複雑なので誰もこれを一手に握ることができず、 それを試みるくらいならむしろ、手が出せなくなる前に 他の誰かがすべてを詳細にチェックすることを 引き受けることに頼るのです。 リチャード・ファインマン (Richard P. Feynmann) は、 ロスアラモスでこの手の重要な経験を何度も見てきたと本に書いています。 一方でバイク小屋の場合は、誰でも週末にこれを作り上げることができ、 しかも TV の試合を見る時間があまるほどです。 なので、どんなに準備が整えてあって、どんなに計画が順当であったとしても、 わたしは仕事をやっているよ、 わたしは注意を払っているよ、そして わたしはここにいるよ、 ということを示そうとする人が必ず現れます。 デンマークではこれを「指紋をつける」と呼んでいます。 これは個人的なプライドや名声を求め、 ある場所を指し示して「ここ! ここは俺が やったんだぜ〜」というようなものです。 これは政治家に見られる強い特徴ですが、 その他のほとんどの人もこういう風に振舞う可能性はあるのです。 生乾きのセメントにつけられた足跡のことを考えればお分かりでしょう。
ひとつの電球を取り替えるのに、何人の FreeBSD ハッカーが必要? 1,172人です。 電球が消えていると -CURRENT で文句を言うのに 23 人。 設定上の問題で -questions で話をすべきことについて騒ぐのに 4 人。 それを send-pr (訳注: 障害報告) するのに 3 人 (そのうちのひとつは間違って doc カテゴリに送りつけられたうえに、 内容が「暗くなった」というだけのもの)。 buildworld を失敗させ、5 分後には元に戻されるような電球を テストもせずにコミットするのに 1 人。 send-pr した人に、パッチが含まれていないと「いちゃもん」を付けるのに 8 人。 buildworld が失敗すると文句を言うのに 5 人。 自分のところではちゃんと動く、 cvsup したタイミングが悪かったんだろうと答えるのに 31 人。 新しい電球のためのパッチを -hackers に投げるのに 1 人。 自分は 3 年も前にパッチを作ったが、それを -CURRENT に投げたときには無視されただけだった、 自分は send-pr のシステムには嫌な経験があると (おまけに、 提案された新しい電球には柔軟性が無いとまで) 文句を言うのに 1 人。 電球が基本システムに組み込まれていない、 committer はコミュニティの意見を聞くこと無しにこんなことをする権利は無いと叫び、 「こんなときに -core は何をやってるんだ!?」とわめきちらすのに 37 人。 自転車置き場の色に文句を言うのに 200 人。 パッチが style(9) 違反だと指摘するのに 3 人。 提案された新しい電球は GPL の下にあると文句を言うのに 70 人。 GPL と BSD ライセンスと MIT ライセンスと NPL と、 某 FSF 創立者らの個人的な健康法の優位性についての論争を戦わすのに 586 人。 スレッドのあちこちの枝を -chat や -advocacy に移動するのに 7 人。 提案された電球を、古いのよりずっと薄暗いのにコミットしてしまうのに 1 人。 FreeBSD に薄暗い電球を付けるくらいなら真っ暗のほうがましだという、 コミットメッセージへの凄まじい非難の嵐によって、 それを元に戻すのに 2 人。 薄暗い電球が帳消しにされたことに対してどなり声で口論し、 -core の声明を要求するのに 46 人。 もし FreeBSD をたまごっちに移植することになったときに都合がいいように、 もっと小さな電球を要求するのに 11 人。 -hackers と -chat の S/N比に文句を言い、 抗議のため講読を取りやめるのに 73 人。 「unsubscribe」「どうやったら講読をやめられるんですか?」 「このメーリングリストからわたしを外してください」といった メッセージを、例のフッタをくっつけて投稿するのに 13 人。 みんなが激論を戦わせるのに忙がしくて気付かない間に、 作業中の電球をコミットするのに 1 人。 新しい電球は TenDRA を使ってコンパイルされた場合に 0.364% も明るくなる (ただし電球を立方体にしなければならない)、 だから FreeBSD は EGCS から TenDRA に変えるべきだと指摘するのに 31 人。 新しい電球は美しさに欠けていると文句を言うのに 1 人。 「MFC って何ですか?」と聞くのに 9 人 (send-pr した人も含む)。 電球が取り替えられてから 2 週間も消えっぱなしだと文句を言うのに 57 人。 &a.nik; による追記 これには爆笑しました。 それからわたしは考えました。 「ちょっと待てよ? このリストのどこかに、 『これを文書にまとめるのに 1人』というのがあってもいいんじゃないか?」 それからわたしは悟りを開いたのです :-) この項目の著作権は Copyright (c) 1999 &a.des; にあります。 無断で使用しないでください。 まじめな FreeBSD ハッカーだけの話題 訳: &a.iwasaki;、 1997 年 11 月 8 日 SNAP とか RELEASE とかは何? 現在、FreeBSD の CVS リポジトリ には、三つのアクティブ/準アクティブなブランチがあります (アクティブな開発ブランチは三つしか存在しないため、 おそらく RELENG_2 ブランチの変更は年に 2 回だけになるでしょう)。 RELENG_2_2 通称 2.2-STABLE RELENG_3 通称 3.X-STABLE RELENG_4 通称 4-STABLE HEAD 通称 あるいは 5.0-CURRENT HEAD は他の二つと違って、 実際のブランチタグではなく、 「current、 分岐していない開発本流」のための単なるシンボリックな定数です。 私たちはこれを -CURRENT と呼んでいます。 現在、 -CURRENT は 5.0 の開発本流であり、 4.0-STABLE ブランチ、 つまり RELENG_4 は 2000 年 3 月に -CURRENT から分岐しています。 2.2-STABLE ブランチ、 RELENG_2_2 は 1996 年 11 月に -CURRENT から分岐しました。 これは保守が完全に終了しています。 自分用のカスタムリリースを構築するには? リリースを構築するには三つのことが必要です。まず、 &man.vn.4; ドライバが組み込まれたカーネルを実行させている必要があります。 以下をカーネルコンフィグレーションファイルに追加し、 カーネルを作り直してください。 pseudo-device vn #Vnode driver (turns a file into a device) 次に、CVS リポジトリ全体を手元においておく必要があります。 これを入手するには CVSUP が使用できますが、supfile で release の名称を cvs にして 他のタグや date フィールドを削除する必要があります。 *default prefix=/home/ncvs *default base=/a *default host=cvsup.FreeBSD.org *default release=cvs *default delete compress use-rel-suffix ## Main Source Tree src-all src-eBones src-secure # Other stuff ports-all www doc-all そして cvsup -g supfile を実行して自分のマシンに CVS リポジトリ全体をコピーします…。 最後に、ビルド用にかなりの空き領域を用意する必要があります。 そのディレクトリを /some/big/filesystem として、 上の例で CVS リポジトリを /home/ncvs に置いたものとすると、 以下のようにしてリリースを構築します。 &prompt.root; setenv CVSROOT /home/ncvs # or export CVSROOT=/home/ncvs &prompt.root; cd /usr/src &prompt.root; make buildworld &prompt.root; cd /usr/src/release &prompt.root; make release BUILDNAME=3.0-MY-SNAP CHROOTDIR=/some/big/filesystem/release
ただし、すでに /usr/obj 以下に構築物が存在しているなら、buildworld の必要はありません。
処理が終了すると、 リリース全体が /some/big/filesystem/release に構築され、完全な FTP インストール用の配布物が /some/big/filesystem/release/R/ftp に作成されます。 -current 以外の開発ブランチの SNAP を自分で構築したい場合は、 RELEASETAG=SOMETAG を上の make release のコマンドラインに追加します。 たとえば、RELEASETAG=RELENG_2_2 とすると最新の 2.2-STABLE snapshot が構築されます。 カスタムのインストールディスクを作るにはどうすればいいのですか? /usr/src/release/Makefile のいろいろなターゲットとしてインストールディスク、 ソース、バイナリアーカイブを作る完全な処理を自動的に行なうようになっています。 Makefile に十分な情報があります。 しかし、実行には make world が必要で、 多くの時間とディスクの容量が必要です。 make world を行なうと既存のバイナリを上書きしてしまうのですが。 ええ、それが一般的な考え方です。名前が示しているように make world はすべてのシステムのバイナリを最初から作り直しますので、結果として、 クリーンで一貫性のある環境を得ることができます (これがそれだけ長い時間がかかる理由です)。 環境変数 DESTDIR を make world や make install を実行する時に定義しておくと、新しく作られたバイナリは ${DESTDIR}を root とみなしたディレクトリツリーにインストールされます。 あるでたらめな共有ライブラリの変更やプログラムの再構築によって make world は失敗することもあります。 システム起動時に (bus speed defaulted) とメッセージが出ます。 Adaptec の 1542 SCSI ホストアダプタは、 ユーザがソフトウェア的にバスアクセス速度の設定を行なうことができます。 以前のバージョンの 1542 ドライバは、 使用可能な最大の速度を求めてアダプタをその設定にしようとしました。 これは特定のユーザのシステムでは問題がある事がわかり、 現在ではカーネルコンフィグオプションに TUNE_1542 が加えられています。 これを使用すると、これが働くシステムではディスクが速くなりますが、 データの衝突が起きて速くはならないシステムもあるでしょう インターネットアクセスに制限があっても current を追いかけられますか? はい、 CTM システムを使って、 ソースツリー全体のダウンロードを行なわずに追いかけることができます。 どのようにして配布ファイルを 240KB に分割しているのですか? 比較的新しい BSD ベースのシステムでは、 split に任意のバイト境界で分割する オプションがあります。 以下は /usr/src/Makefile からの例です。 bin-tarball: (cd ${DISTDIR}; \ tar cf - . \ gzip --no-name -9 -c | \ split -b 240640 - \ ${RELEASEDIR}/tarballs/bindist/bin_tgz.) 私はカーネルに拡張を行ないました。 誰に送ればいいですか? FreeBSD ハンドブックの「FreeBSD への貢献」を参照してください。 あなたのアイディアに感謝します! PnP ISA カードの検出と初期化はどのように行なうのですか? Frank Durda IV 氏 より:
要点は、ホストが認識されていないボードを探す時に、すべての PnP ボードが応答することのできる少数の I/O ポートがあるということです。 それにより、PnP プローブルーチンが開始したとき、PnP ボードが存在するなら、すべての PnP ボードは自分のモデル番号を返します。 そのポートを I/O read するとプローブルーチンは問いに対するワイアード-OR された yes を得ます。この場合は 少なくとも 1 ビットが ON になります。 そして、プローブルーチンはモデル ID (Microsoft/Intel によって割り当てられています)が X より小さいボードを オフライン にすることができます。 この操作を行ない、問い合わせに応答しているボードがまだ 残っているかどうかを調べます。 もし 0 が返ってくるなら X より大きな ID を持つボードはないことになります。 今度は X よりも小さな値を持つボードについて問い合わせます。 もしあるのであれば、 プローブルーチンはモデル番号が X より小さいことを知ります。 今度は、X-(limit/4) より大きな値を持つボードをオフラインにして問い合わせを繰り返します。 この ID の範囲による準バイナリサーチを十分繰り返すことにより、 プローブルーチンはマシンに存在するすべての PnP ボードの値を最終的に得ることができます。その繰り返しの回数は 2^64 よりはるかに少ない回数です。 ID は二つの 32-bit (つまり 64bit) フィールド + 8 bit チェックサムからなります。最初の 32 bits はベンダの識別子です。 これは公表されてはいませんが、 同一のベンダから供給されている異なるタイプのボードでは異なる 32-bit ベンダ ID を持つことができるように考えられます。 製造元を特定するだけのために 32-bit はいくらか過剰です。 下位の 32-bit はシリアル番号、 イーサネットアドレスなどのボードを特定するものです。 ベンダは上位 32 bits が異なっていないのであれば、 下位 32-bit が同一である 2枚目のボードを製造することはありません。 したがって、同じタイプの複数のボードをマシンにいれることができ、 この場合でも 64-bit 全体ではユニークです。 32-bit のフィールドはすべてを 0 にすることはできません。 これは初期化のバイナリサーチの間ワイアード-OR によって 0 ではない ビットを参照するからです。 システムがすべてのボードの与えられた ID を認識すると、 それぞれのボードに対応した処理を一つずつ (同一の I/O ポートを通して) 行ないます。 そして、利用できる割り込みの選択などのボードが必要とするリソースを検出します。 すべてのボードについてこの情報を集めます。 この情報はハードディスク上の ECU ファイルなどの情報とまとめられ、 マザーボードの BIOS にも結合されます。 マザーボード上のハードウェアへの ECU と BIOS PnP のサポートは通常は統合されていますが、 周辺機器については真の PnPであるとはいえません。 しかし、BIOS の情報に ECU の情報を加えて調査することで、 プローブルーチンは PnP デバイスが再配置できなくなることを避けることができます。 それから、再度 PnP デバイスにアクセスし、I/O、DMA、IRQ、 メモリマップアドレスの設定をします。 デバイスはこのアドレスに見えるようになり、 次に再起動するまでこの位置を占めます。しかし、 あなたの望む時に移動させることが不可能である、 といっているわけではありません。 以上の話では大きく単純化をしてありますが、 基本的な考え方は得られたでしょう。 マイクロソフトは、ボードのロジックが対立する I/O サイクルではデコードしていない (訳注: おそらく read 時しかデコードされていず write 時はポートが空いているという意味でしょう)、 プライマリプリンタのステータスポートのいくつかを PnP のために占有しました。 私は初期の PnP の提案レビュー時に IBM 純正のプリンタボードでステータスポートの write のデコードがされているということに気がつきましたが、 MS は tough (頑固、不運、無法な) と言っています。 そしてプリンタのステータスポートへアドレスの設定のために write を行なっています。また、 そのアドレス + 0x800 と read のための 3番目の I/O ポートが 0x200 から 0x3ff の間のどこかに置かれるでしょう。
FreeBSD は、他のアーキテクチャをサポートしないんですか? いくつかのグループの人々が、FreeBSD の他のアーキテクチャへの移植に関心を示しており、 FreeBSD/AXP (ALPHA) はこれらの成果としてはとても成功したものの一つです。 FreeBSD/AXP は現在 ftp://ftp.FreeBSD.org/pub/FreeBSD/alpha から入手できます。 ALPHA への移植版が現在動く機種は増えつつあり、 その中には AlphaStation、AXPpci、PC164、Miata そして Multia といったモデルが含まれています。 現状についての情報を得るには freebsd-alpha@FreeBSD.orgメーリングリストに参加してください。 その他に FreeBSD の SPARC アーキテクチャへの移植があります。 プロジェクトへの参加に興味がある方は freebsd-sparc@FreeBSD.orgメーリングリスト に参加してください。 進行中のプラットホームのリストにもっとも最近追加されたのが IA-64 と PowerPCです。詳細は freebsd-ia64@FreeBSD.org および/あるいは freebsd-ppc@FreeBSD.orgメーリングリストに参加してください。 新しいアーキテクチャに関する一般的な議論については 新しいアーキテクチャに関する一般的な議論については freebsd-platforms@FreeBSD.orgメーリングリスト へ参加してください。 デバイスドライバを開発したので、メジャー番号が欲しいのですが。 これは、開発したドライバを公開するかどうかに依存します。 公開するのであれば、ドライバのソースコード、 files.i386 の変更、 コンフィグファイルのサンプル、 デバイスが使うスペシャルファイルを作成する &man.MAKEDEV.8; のコードを私たちに送ってください。 公開するつもりがない場合、ライセンスの問題により公開できない場合は、 キャラクタメジャー番号 32 および、 ブロックメジャー番号 8 がこのような目的のために予約されています。 これらの番号を使用してください。 どちらの場合であれ、ドライバに関する情報を &a.hackers; に流して頂けると助かります。 代替のディレクトリ配置ポリシー 現在使われているディレクトリの配置ポリシーは、 私が 1983 年に書いたものから全く変更されていません。 私は当初の配置ポリシーを、オリジナルの fast filesystem のために書き、 まったく改定していません。 このポリシーはシリンダグループを使い尽くすのを防ぐにはうまくいきましたが、 お気づきの方もいる通り find の動作には不適切です。 ほとんどのファイルシステムの内容は、 深さ優先検索 (ftw とも呼ばれます) によって作られたアーカイブから、 抽出 (restore) して作成されます。この際、 ディレクトリは、シリンダグループにまたがって配置され、 以降の深さ優先検索を行うには、 考え得る限り最悪の状態になります。 もし作成するディレクトリの総数がわかっていれば、 解決方法はあります。(総数/シリンダグループ数) 個のディレクトリを、 シリンダグループごとにまとめて作成すれば良いのです。 もちろん最適なディレクトリ配置になるように、 総数を予測する方法を考えなければなりません。 しかし仮にシリンダグループあたりのディレクトリ数を 10 くらいの小さな数に固定してしまったとしても、 大幅な改善が望めるでしょう。 このポリシーを用いるべきリストア作業を、通常の作業 (おそらく既存のポリシーを使用したほうが良いでしょう) を区別するには、 10 秒間の間に作成されたディレクトリを最大 10 個までまとめて単一のシリンダグループに書き込むという手順が使えるでしょう。 とにかく私の結論は、そろそろ実験を始めて見る時期だろうということです。 カーネルパニックを最大限に利用する この節は、freebsd-current メーリングリストに &a.wpaul; 氏が投稿したメールを、 &a.des; 氏が校正し、[] 内のコメントを追加して引用したものです。 From: Bill Paul <wpaul@skynet.ctr.columbia.edu> Subject: Re: the fs fun never stops To: ben@rosengart.com Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT) Cc: current@FreeBSD.ORG [<ben@rosengart.com> が以下のパニックメッセージを投稿しました。] > Fatal trap 12: page fault while in kernel mode > fault virtual address = 0x40 > fault code = supervisor read, page not present > instruction pointer = 0x8:0xf014a7e5 ^^^^^^^^^^ > stack pointer = 0x10:0xf4ed6f24 > frame pointer = 0x10:0xf4ed6f28 > code segment = base 0x0, limit 0xfffff, type 0x1b > = DPL 0, pres 1, def32 1, gran 1 > processor eflags = interrupt enabled, resume, IOPL = 0 > current process = 80 (mount) > interrupt mask = > trap number = 12 > panic: page fault このようなメッセージが表示された場合、問題が起きる状況を確認して、 情報を送るだけでは十分ではありません。 下線をつけた命令ポインタ値は重要な値ですが、 残念ながらこの値は構成に依存します。つまり、 この値は使っているカーネルのイメージに依存するのです。 もしスナップショットなどの GENERIC カーネルを使っているのであれば、 他の人間が問題のある関数について追試をすることができますが、 カスタマイズされたカーネルの場合は、 使っている本人にしか問題の起こった場所は特定できないのです。 何をすれば良いのでしょう? 命令ポインタ値をメモします。 0x8: という部分は今回必要ありません。 必要なのは 0xf0xxxxxx という部分です。 システムが再起動したら、以下の操作を行います。 &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxxx ここで、f0xxxxxx は命令ポインタ値です。 カーネルシンボルのテーブルは関数のエントリポイントを含み、 命令ポインタ値は、関数内部のある点であり最初の点ではないため、 この操作を行っても完全に一致するものが表示されない場合もあります。 この場合は、 最後の桁を省いてもういちどやってみてください。 このようになります。 &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxx これでも一致しない場合は、 桁を減らしながら何らかの出力があるまで繰り返してください。 何か出力されたら、 それがカーネルパニックを引き起こした可能性のある関数のリストです。 これは、問題点を見付ける正確な方法ではありませんが、何もないよりましです。 このようなパニックメッセージを投稿している人はよく見掛けますが、 このように、命令ポインタ値を、 カーネルシンボルテーブルの中の関数とつき合わせて調べている人はまれです。 パニックの原因を突き止める最良の方法は、クラッシュダンプをとり、 gdb(1) でスタックトレースを行うことです。 どっちにしろ、私は普通以下のようにします。 カーネルコンフィグファイルを作ります。 カーネルデバッガが必要そうであれば options 'DDB' を加えても良いです (私は永久ループが起こっていそうな場合に、 ブレークポイントを設定するのに使っています)。 config -g KERNELCONFIG としてビルドディレクトリを設定します。 cd /sys/compile/KERNELCONFIG; make を実行します。 カーネルのコンパイルが終了するのを待ちます。 make install を実行します。 再起動します。 &man.make.1; プロセスは２つのカーネル、 kernel と kernel.debug をビルドします。 kernel は /kernel としてインストールされ、 kernel.debug は gdb(1) のデバッグ用シンボル情報を取り出すために利用されます。 確実にクラッシュダンプをとるには、/etc/rc.conf を編集して dumpdev を使用しているスワップパーティションに指定する必要があります。 こうすると rc(8) スクリプトから dumpon(8) コマンドが実行され、 クラッシュダンプ機能が有効になります。 手動で dumpon(8) コマンドを実行してもかまいません。 パニックの後、クラッシュダンプは savecore(8) コマンドを使用して取り出すこと ができます。 dumpdev が /etc/rc.conf で設定されていれば、 rc(8) スクリプトから savecore(8) が自動的に実行され、クラッシュダンプを /var/crash に保存します。 FreeBSD のクラッシュダンプのサイズは、 ふつう物理メモリサイズと同じです。 つまり 64MB のメモリを積んでいれば、 64MB のクラッシュダンプが生成されることになります。 /var/crash に十分な空き容量があることを確認してください。手動で savecore(8) を実行すれば、 もっと空き容量のあるディレクトリにクラッシュダンプを保存できます。 options MAXMEM=(foo) という行をカーネルコンフィグファイルに追加することで、 カーネルのメモリ使用量を制限できます。 たとえば 128MB のメモリがある場合も、 カーネルのメモリ使用量を 16MB に制限し、クラッシュダンプのサイズも 128MB ではなく 16MB にすることができます。 クラッシュダンプを取り出せたら、 以下のように gdb(1) を使ってスタックトレースをとります。 &prompt.user; gdb -k /sys/compile/KERNELCONFIG/kernel.debug /var/crash/vmcore.0 (gdb) where 必要な情報が 1 画面に収まらないことも多いので、できれば script(1) を使って出力を記録します。 strip していないカーネルイメージを使うことで、 すべてのデバッグシンボルが参照でき、 パニックの発生したカーネルのソースコードの行が表示されているはずです。 通常、正確なクラッシュへの過程を追跡するには、 出力を最後の行から逆方向に読まなければなりません。 また gdb(1) を使って、 変数や構造体の内容を表示させ、 クラッシュした時のシステムの状態を調べられます。 もしあなたがデバッグ狂で、同時に別のコンピュータを利用できる環境にあれば、 gdb(1) をリモートデバッグに使うこともできます。 リモートデバッグを使うと、あるコンピュータ上の gdb(1) を使って、 別のコンピュータのカーネルをデバッグできます。 ブレークポイントの設定、カーネルコードのステップ実行など、 ふつうのプログラムのデバッグと変わりません。 コンピュータを 2 台並べてデバッグするチャンスにはなかなか恵まれないので、 私はまだリモートデバッグを試したことはありません。 Bill による追記 DDB を有効にしていてカーネルがデバッガに 落ちたら、ddb のプロンプトで "panic" と入力すれば、強制的にパニックを起こしクラッシュダンプさせることができます。 パニックの途中で、再びデバッガに落ちるかもしれませんが、 "continue" と入力すれば、 クラッシュダンプを最後まで実行させられます。 dlsym() が ELF 実行形式では動作しなくなります! ELF のツール類は、 デフォルトでは実行形式の中に定義されているシンボルを、 ダイナミックリンカから見えるようにはしません。 このため、dlopen(NULL, flags) を呼び出して得られたハンドルに対して、 dlsym() で探索を行っても、 こういったシンボルを見つけられません。 もし、あなたがプロセスの中心にあたる実行形式の中にあるシンボルを探索したければ、 ELF リンカ (&man.ld.1;) に オプションを付けて実行形式をリンクする必要があります。 カーネルアドレス空間を大きくしたり、 小さくするにはどうしたら良いのですか? カーネルアドレス空間は、FreeBSD 3.X 上で 256MB、FreeBSD 4.X 上で 1GB がデフォルトになっています。 負荷の高いネットワークサーバ (たとえば大きな FTP、HTTP サーバ) を運用する場合は、256MB では足りないことに気付くかも知れません。 では、アドレス空間を大きくするにはどうしたら良いのでしょうか? それには、二つの段階を踏みます。まず、 より大きいアドレス空間を割り当てることをカーネルに知らせる必要があります。 次に、カーネルはアドレス空間の先頭にロードされるため、 アドレスの先頭が天井 (訳注:カーネルアドレス空間の最下端アドレスのこと) と ぶつかることのないように、ロードアドレスを今までより低位に設定する必要があります。 最初の段階は、src/sys/i386/include/pmap.h にある NKPDE の値を増加させることで行ないます。 ここに 1GB のアドレス空間にするために、どのようにすれば良いかを示します。 #ifndef NKPDE #ifdef SMP #define NKPDE 254 /* addressable number of page tables/pde's */ #else #define NKPDE 255 /* addressable number of page tables/pde's */ #endif /* SMP */ #endif 正確な NKPDE の値を計算するには、 望みのアドレス空間の大きさ (メガバイト単位) を 4 で割って、 それから単一プロセッサ (UP) なら 1、SMP なら 2 を引き算してください。 次の段階を行なうには、ロードアドレスを正確に計算することが必要です。 単純に、アドレス空間の大きさ (バイト単位) を 0x100100000 から引き算してください。 1GB アドレス空間の場合、その結果は 0xc0100000 になります。 そして、src/sys/i386/conf/Makefile.i386 にある LOAD_ADDRESS に、今計算した値を入れます。また、次のように src/sys/i386/conf/kernel.script のセクションの始めの方にあるロケーションカウンタにも同じ値を入れてください。 OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386") OUTPUT_ARCH(i386) ENTRY(btext) SEARCH_DIR(/usr/lib); SEARCH_DIR(/usr/obj/elf/home/src/tmp/usr/i386-unknown-freebsdelf/lib); SECTIONS { /* Read-only sections, merged into text segment: */ . = 0xc0100000 + SIZEOF_HEADERS; .interp : { *(.interp) } それが完了したら、config し直してカーネルを再構築してください。 おそらく、ps(1)、top(1) などに不具合が出るでしょう。 それらを正常にするために、make world (もしくは、変更した pmap.h を /usr/include/vm/ にコピーした後に、 libkvm、 ps および top を手動で再構築すること) を行なうべきです。 カーネルアドレス空間の大きさは、4MB の倍数である必要があります。 &a.dg; 氏による補足 カーネルアドレス空間は 2 の乗数である必要があると思いますが、 それが確かなことかどうかははっきりしていません。 昔の起動コードには、良く高位アドレスビットのトリックが使われていたため、 少なくとも 256MB の粒度であることが想定されていたと思います。 謝辞 訳: &a.jp.y-koga;、 1997 年 11 月 10 日
FreeBSD Core Team この FAQ について問題を見つけたり、何か登録したい場合は、 &a.faq; までメールを送ってください。 フィードバックしてくれるみなさんには感謝感謝なのです。 みなさんに手伝ってもらわないとこの FAQ はよくなりませんから!
&a.jkh; たまに起こす FAQ の並べ替えや更新の発作 &a.dwhite; freebsd-questions メーリングリストでの義務を超えたサービス &a.joerg; Usenet (NetNews) での義務を超えたサービス &a.wollman; ネットワーク節の執筆と文書整形 Jim Lowe マルチキャストについて &a.pds; FreeBSD FAQ タイピング機械奴隷 FreeBSD チーム 不平を言ったり、うめいたり、情報提供してくれたり あと、抜けてしまった他の方々に対して、謝罪と心からの感謝を捧げます! FreeBSD FAQ 日本語化について FreeBSD 日本語ドキュメンテーションプロジェクトは、 FreeBSD 関係の日本語文書が少ないことを嘆いた数人の FreeBSD ユーザの提唱によって 1996 年 2 月 26 日にスタートし、 FreeBSD 日本語ハンドブックの作成をはじめとした活動を行なってきました。 FreeBSD FAQ の日本語化についてはオリジナルの翻訳作業だけでなく、 日本国内に固有の話題についても広く情報を集め、 日本の FreeBSD ユーザにとって真に有益なドキュメントを提供しようと考えています。 オリジナルの FAQ は日毎に更新されており、 私たちもまたこれに追い付くために作業を続けていきます。もちろん、新しいメンバも大歓迎です。 日本語翻訳版について、何かお気づきの点がありましたら、 &a.jp.doc-jp; までご連絡ください。 また、もし私たちの作業を手伝ってくれるなら、 FreeBSD 日本語ドキュメンテーションプロジェクトのページをご覧の上、是非参加してください。 翻訳者 (五十音順) &a.jp.arimura; 一宮 亮 ryo@azusa.shinshu-u.ac.jp &a.iwasaki; &a.jp.yoshiaki; &a.kuriyama; &a.jp.y-koga; &a.motoyuki; &a.jp.sugimura; &a.jp.nakai; にしか nishika@cheerful.com &a.hanai; &a.jp.kiroh; &a.jp.shou; 福間 康弘 yasuf@big.or.jp &a.jp.mrt; 山下 淳 junkun@esys.tsukuba.ac.jp 査読者 (五十音順) &a.asami; &a.iwasaki; &a.jp.yoshiaki; 大橋 健 ohashi@mickey.ai.kyutech.ac.jp &a.kuriyama; &a.motoyuki; &a.jp.saeki; &a.jp.sugimura; &a.hanai; &a.jp.nao; &a.jp.kiroh; &a.jp.hino; 檜山 卓 shiyama@intercity.or.jp &a.jp.shou; &a.jp.mrt; 若井 久史 earth@hokuto7.or.jp 作業環境整備 (五十音順) 一宮 亮 ryo@azusa.shinshu-u.ac.jp &a.jp.iwasaki; &a.jp.simokawa; 鈴木 秀幸 hideyuki@jp.FreeBSD.org diff --git a/ja_JP.eucJP/books/fdp-primer/book.sgml b/ja_JP.eucJP/books/fdp-primer/book.sgml index 052b06c63d..9200c1b127 100644 --- a/ja_JP.eucJP/books/fdp-primer/book.sgml +++ b/ja_JP.eucJP/books/fdp-primer/book.sgml @@ -1,308 +1,308 @@ -%man; + +%books.ent; %chapters; ]> 新しい貢献者のための FreeBSD ドキュメンテーションプロジェクト入門 Nik Clayton
nik@FreeBSD.org
 1998 1999 Nik Clayton - $FreeBSD: doc/ja_JP.eucJP/books/fdp-primer/book.sgml,v 1.1 2001/03/07 19:40:47 hrs Exp $ + $FreeBSD$ - $FreeBSD: doc/ja_JP.eucJP/books/fdp-primer/book.sgml,v 1.1 2001/03/07 19:40:47 hrs Exp $ + $FreeBSD$ 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 NIK CLAYTON "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 NIK CLAYTON 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. FreeBSD ドキュメンテーションプロジェクトに参加してくださってありがとうございます. あなたの貢献は非常に価値のあることです. この入門では FreeBSD ドキュメンテーションプロジェクトへの貢献を始めるにあたって理解する必要のあること, すなわち(必須のものだけでなく, 推奨されるものも含めた)ツールやソフトウェアの使い方から, ドキュメンテーションプロジェクトの方針にわたる内容のすべてを扱っています. この文書は発展途上にあり, まだ完成していません. まだ完成していない節の名前には *(アスタリスク) が付けてあります. まえがき シェルプロンプト 以下の表は, 標準のシステムプロンプトとスーパーユーザのプロンプト示しています. この文書であげる実例では, どちらのユーザでその例を実行すべきか示すためにこれらのプロンプトを使用します. ユーザ プロンプト 通常ユーザ &prompt.user; root &prompt.root; 表記上の慣例 下の表は, この文書で使われる表記上の慣例を示しています. 意味 例 コマンド, ファイル, ディレクトリの名前および, コンピュータ画面への出力 あなたの .login ファイルを編集してください. ファイルの一覧を表示するには ls -a を使います. You have mail. コンピュータの画面に表示されるものと, あなたが入力するものを区別する場合 &prompt.user; su Password: マニュアルページの参照 ユーザ名を変更するには su 1 を使います. ユーザ名とグループ名 これが行なえるのは root だけです. 強調部分 必ずこれを行なわなければいけません. コマンドラインに書かれる引数. これは実際にあるファイル名や変数名などに置き換えられます. ファイルを消去するには, rm ファイル名 と入力します. 環境変数 $HOMEは, あなたのホームディレクトリです. 注記(notes), 警告(warnings), 例示(examples) 注記や警告, 例示は本文中に書かれています. 注記はこのような感じで表示されます. これには, 読者が行なう操作に関連して 注意しなければならないことを伝えるための内容が含まれています. 警告は, このような感じで表示されます. これには, 手順に従わない場合に何らかの損害を被る可能性があることを 伝える内容が含まれています. その損害はハードウェアや操作者に対する物理的なものかも知れませんし, 不注意で重要なファイルが削除されてしまうような非物理的なものかも知れません. 例示のサンプル 例示は, このような感じで表示されます. これには通常, 読者自身が試す必要のある例や, ある操作がどのような結果をもたらすのか, 読者に示すための例が含まれています. 謝辞 Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, Christopher Maden はこの文書の初稿を読む時間を割いて, たくさんの有益なコメントや批評を送ってくれました. ここに感謝の意を表します. &chap.overview; &chap.tools; &chap.sgml-primer; &chap.sgml-markup; &chap.stylesheets; &chap.structure; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; diff --git a/ja_JP.eucJP/books/handbook/book.sgml b/ja_JP.eucJP/books/handbook/book.sgml index 4aacffbe28..35b03a87a8 100644 --- a/ja_JP.eucJP/books/handbook/book.sgml +++ b/ja_JP.eucJP/books/handbook/book.sgml @@ -1,272 +1,251 @@ -%man; - - -%bookinfo; - - -%freebsd; - + +%books.ent; %chapters; - -%ja-authors; - -%authors; - -%teams; - -%ja-mailing-lists; - %newsgroups; - -%ja-trademarks; - -%trademarks; %txtfiles; %pgpkeys; ]> FreeBSD ハンドブック FreeBSD ドキュメンテーションプロジェクト 1999 年 2 月 1995 1996 1997 1998 1999 2000 2001 2002 2003 The FreeBSD Documentation Project &bookinfo.legalnotice; &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.3ware; &tm-attrib.arm; &tm-attrib.adaptec; &tm-attrib.adobe; &tm-attrib.apple; &tm-attrib.corel; &tm-attrib.creative; &tm-attrib.heidelberger; &tm-attrib.ibm; &tm-attrib.ieee; &tm-attrib.intel; &tm-attrib.intuit; &tm-attrib.linux; &tm-attrib.lsilogic; &tm-attrib.m-systems; &tm-attrib.macromedia; &tm-attrib.microsoft; &tm-attrib.netscape; &tm-attrib.opengroup; &tm-attrib.oracle; &tm-attrib.powerquest; &tm-attrib.realnetworks; &tm-attrib.redhat; &tm-attrib.sap; &tm-attrib.sun; &tm-attrib.symantec; &tm-attrib.themathworks; &tm-attrib.thomson; &tm-attrib.usrobotics; &tm-attrib.vmware; &tm-attrib.waterloomaple; &tm-attrib.wolframresearch; &tm-attrib.xfree86; &tm-attrib.xiph; &tm-attrib.general; FreeBSD へようこそ! このハンドブックは FreeBSD &rel2.current;-RELEASE と FreeBSD &rel.current;-RELEASE のインストールおよび、日常での使い方について記述したものです。 本ハンドブックは改編作業中であり、 さまざまな人々が編集に携わっています。 多くのセクションはまだ存在しませんし、 いま存在するセクションにも更新作業の必要があるものも含まれています。 もし、このハンドブックを編集するプロジェクトに協力したいとお考えなら、 &a.doc; まで電子メールを(英語で)送ってください。 この文書の最新バージョンは、いつでも 日本国内版の FreeBSD ウェブサイト および FreeBSD ウェブサイト で入手することができます。 また、他のさまざまな文書形式、圧縮形式のものが FreeBSD FTP サーバや数多くのミラーサイトからダウンロードすること ができます。このハンドブックの書籍版 (英語版) は、 FreeBSD Mall から購入することができます。また、 ハンドブックの検索を行なうことも可能です。 FreeBSD ハンドブック日本語版の作成は FreeBSD 日本語ドキュメンテーションプロジェクト (FreeBSD doc-jp) がおこなっています。 ハンドブックの日本語訳に関することは FreeBSD &a.jp.doc-jp; において日本語で議論されています。 文書の日本語訳に関するお問い合わせや、 文書の原文に関する問い合わせをしたいが英語が得意でないという方は FreeBSD &a.jp.doc-jp; まで、日本語でコメントをお寄せください。 導入 FreeBSD ハンドブックの第 1 部はユーザと FreeBSD が初めての管理者向けです。各章の内容は以下のとおりです。 FreeBSD の紹介 インストールの手順の解説 &unix; の基礎 FreeBSD で利用できる豊富なサードパーティ製のアプリケーションの インストール方法 &unix; におけるウィンドウシステム X、 およびクリエイティブなデスクトップ環境の設定の詳細の紹介 このハンドブックでは頻繁にページを飛すことなく前から後へと スムーズに読み進めるように、 後方への参照を極力抑えるようにしています。 システム管理 FreeBSD ハンドブックの以下の章は、 FreeBSD のシステム管理の面について書かれています。 各章のはじめでは、その章で学ぶ内容や 実際に取り組む前に知っておくべきことについて説明します。 各章は、必要になった時に個別に参照できるように構成されています。 どの順番で読んでも構いませんし、FreeBSD を使うのに、 すべてを読み通す必要がある、というわけでもありません。 付録 &chap.colophon; diff --git a/ja_JP.eucJP/books/porters-handbook/book.sgml b/ja_JP.eucJP/books/porters-handbook/book.sgml index 5faa5e6b50..bf876ac7b6 100644 --- a/ja_JP.eucJP/books/porters-handbook/book.sgml +++ b/ja_JP.eucJP/books/porters-handbook/book.sgml @@ -1,5028 +1,5018 @@ -%man; - - -%bookinfo; - - -%ja-authors; - -%authors; - -%mailing-lists; + +%books.ent; ]> FreeBSD port 作成者のためのハンドブック FreeBSD ドキュメンテーションプロジェクト 2000 年 4 月 2000 The FreeBSD Documentation Project このハンドブックは FreeBSD の port 作成者 (porter) 向けに, 具体的な port の作成方法や注意点などをまとめたものです. 日本語版の作成は FreeBSD 日本語ドキュメンテーション プロジェクト (FreeBSD doc-jp) が行なっています. 日本語訳および, 日本語版のみに関することは FreeBSD &a.jp.doc-jp; に おいて日本語で議論されています. 文書の日本語訳に関するお問い合わせや, 文書の原文に関する問い合わせをしたいが英語が得意でないという方は, FreeBSD &a.jp.doc-jp; まで日本語でコメントをお寄せください. &bookinfo.legalnotice; 自分で port を作成するには 自分で port を作ることや, 既存の port の 更新作業に興味があるのですか. それはすばらしい! ここでは FreeBSD 用の port を作る際の ガイドラインをいくつか示します. 既存の port を更新したいと考えている場合であっても, まずこの章を読んでから, 次に を読むようにしてください. この文書では充分に詳細がわからない場合には, /usr/ports/Mk/bsd.port.mk を参照してください. このファイルは, port の Makefile が例外なくインクルードしているものです. これには細かくコメントが書かれていますので, Makefile を読むのに あまり慣れていない人でも, たくさんの情報を得ることができるでしょう. それでも解決できないような質問は, &a.ports; にポストしてみるのも 良いでしょう. この文書では, 上書き可能な 変数 (VAR) のうち 一部のものについてだけ述べています. (すべてでは無いかもしれませんが,) ほとんどの変数は bsd.port.mk の先頭部分に記述されています. なお, このファイルは非標準のタブ設定を使用しています. Emacs や Vim は, この設定をファイルの読み込み時に認識するはずです. vi と ex では, 一旦ファイルを読み込んでから :set tabstop=4 と タイプすることで, 正しい値に設定することができます. 3 分間 porting このセクションでは, 簡単な port の作り方について説明します. 多くの場合, これだけでは不充分ですが, まあ うまくいくかどうか試してみて損はないでしょう. まず, 元の tar ファイルを DISTDIR に置きます. この変数の デフォルト値は /usr/ports/distfiles です. 以下の例では, そのソフトウェアが そのままコンパイル可能なものと仮定しています. つまり, FreeBSD マシンで動かすために, 変更がまったく必要ないという意味です. もし何か変更が必要な場合には, 次のセクションも 参照する必要があるでしょう. <filename>Makefile</filename> の作成 最小限の Makefile は 次のようなものになります. # New ports collection makefile for: oneko # Date created: 5 December 1994 # Whom: asami # # $FreeBSD$ # PORTNAME= oneko PORTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= asami@FreeBSD.org MAN1= oneko.1 MANCOMPRESSED= yes USE_IMAKE= yes .include <bsd.port.mk> おわかりでしょうか. $FreeBSD$ を 含む行の内容については, 気にする必要はありません. この行は, このファイルが FreeBSD の ports ツリーに 取り込まれる際に, CVS によって自動的に書き込まれます. もっと詳しい例が見たい場合には, Makefile のサンプルの セクションをご覧ください. package 記述ファイルの作成 package にするしないに関わらず, どのような port でも 三つの記述ファイルが必要です. それは pkg-comment, pkg-descr, と pkg-plist の３つで, ファイル名が pkg- で始まっていることで 他のファイルと区別できるようになっています. <filename>pkg-comment</filename> このファイルには, その port についての説明を一行で書きます. package の名前だとか, バージョン番号などを 含めてはいけません. 説明は大文字で始め, 最後にピリオドは付けないでください. たとえば, こんな具合です. A cat chasing a mouse all over the screen <filename>pkg-descr</filename> このファイルには, その port についての少し長い説明を書きます. その port が何をするのかについての, 数段落程度の簡潔な解説があれば充分です. これはマニュアルでもなければ, 使用方法やコンパイル方法に ついての細かい説明書でもありません. README ファイルや マニュアルを引用するつもりなら注意が必要です. これらは多くの場合, その port の簡潔な説明になっていなかったり, 扱いにくい形式になっていたりします. (マニュアルの場合, 行を揃えるために空白が調整されていたりします.) このソフトウェアに公式のウェブサイトがあるのなら, ここに書いてください. その際自動化ツールが正しく動作するように, ウェブサイトのうちの一つには, 先頭に WWW: をつけておいてください. このファイルの最後に, あなたの名前を書くことが推奨されています. たとえば, こんな具合です. This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (うんぬん.) WWW: http://www.oneko.org/ - Satoshi asami@cs.berkeley.edu <filename>pkg-plist</filename> このファイルには, その port によってインストールされる すべてのファイルを列挙します. このファイルは package を作る際のリストとして使われるため, パッキングリスト (packing list) とも呼ばれます. ここに書くパス名は, インストール時のプレフィックス (通常 /usr/local または /usr/X11R6) からの相対パスです. MANn 変数を 使用している場合 (使用することが推奨されています), このリストに マニュアルは入れないようにしてください. 簡単な例を載せておきましょう. bin/oneko lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm @dirrm lib/X11/oneko パッキングリストの詳細については, &man.pkg.create.1; のマニュアルを参照してください. このリストには, すべてのファイルを列挙しなければ なりませんが, ディレクトリそのものは列挙する必要がありません. また, この port がインストール時に独自のディレクトリを 作成する場合には, この port が削除されるときに そのディレクトリも削除されるよう, @dirrm の行を 追加しておくのを忘れないでください. このファイルでは, すべてのファイル名を アルファベット順にソートしておくことを推奨します. そうすることで, port を更新する際の 変更点の確認が楽になります. パッキングリストを手作業で作成するのは, 時にとても退屈な作業になります. その port が非常に多数のファイルをインストールするとしたら, パッキングリストの 自動生成を行なえば, 時間の節約になるかもしれません. チェックサムファイルの作成 make makesum と入力するだけで, (訳注: bsd.port.mk に書かれている) port 生成ルールに従い, 自動的に distinfo ファイルが生成されます. port のテスト package 化も含め, その port が思った通りに 動くことを確認してください. 確認の必要な重要ポイントは以下の通りです. その port がインストールしないものが pkg-plist に含まれていないこと. その port がインストールする, すべてのものが pkg-plist に含まれていること. reinstall ターゲットを使うことで, その port が 何度でもインストール可能なこと. その port が deintall される際には 後片付けをすること. 推奨されるテストの手順 make install make package make deinstall pkg_add package 名 make deinstall make reinstall make package package および deinstall の段階で, どんな警告 (warning) も出力されないことを確認してください. ステップ 3 の後, (訳注: その port が作成した) すべての新しい ディレクトリが正しく消去されていることを確認してください. また, ステップ 4 の後にそのソフトウェアを使用してみて, package からインストールされた場合にも正しく動作することを 確認してください. <command>portlint</command> によるチェック portlint を使い, その port が FreeBSD の ガイドラインに沿っているかどうかを確認してください. portlint プログラムは ports collection に 含まれています. 特に, Makefile が 正しい形式になっているか, package の 名前が正しいかどうかをチェックするのに良いでしょう. port の提出 まず, やって良いこと悪いことの セクションを読んでください. さて, 満足のいく port が完成したら, 残るは それを FreeBSD のメインの ports ツリーに置いて, 他の人にも使ってもらうだけです. work ディレクトリや pkgname.tgz といった package は 必要ありませんから, まずこれらを消去してください. あとは shar `find port_dir` の出力を バグレポートに入れ, &man.send-pr.1; プログラムを使用して 送ってください (&man.send-pr.1; についての詳細はバグ報告と 一般的な論評を参照してください). もし, 圧縮していない状態で 20KB 以上あるような port であれば, それを ひとつの tar ファイルにまとめて圧縮し, バグレポートに入れる前に &man.uuencode.1; を使用してください (20KB 以下のものを tar ファイルにして送っても良いのですが, あまり歓迎されません). バクレポートの category は必ず ports, class は change-request としてください (レポートを confidential (機密) 指定には しないでください!). また, port 化したプログラムの短い説明文を バグレポートの Description フィールドに追加して, Fix フィールドには shar したファイル, もしくは uuencode した tar ファイルを追加するようにしてください. 後者は, ports 管理の作業をスクリプトで行なっている コミッターの助けとなります. もう一度, オリジナルのソースファイルや work ディレクトリ, make package で作成した package が 含まれていないことを確認してください. 以前には, 新しい port を提出する際に FreeBSD の FTP サイト (ftp.FreeBSD.org) に アップロードするように お願いしていたことがあります. 現在このサイトの incoming ディレクトリは 読み出し不可になっており, アップロードは推奨されていません. たくさんの海賊版ソフトウェアがそこに置かれたためです. わたしたちはその port をチェックし, 必要なら あなたに確認して, それをツリーへ置きます. あなたの名前は FreeBSD ハンドブックやその他のファイルの Additional FreeBSD contributors の リストにも載るでしょう. う〜ん, 素晴らしい. :-) わたしたちが作業しやすいように, 障害報告の概要 (synopsis) は適切に記述してください. たとえば新しい port の提出なら New port: <port の簡単な説明>, port の更新なら Update port: <カテゴリ>/<port 名> <更新内容の簡単な説明> といった形式が歓迎されます. こういう方法で報告するように心がけていれば, あなたの報告 (PR) が すぐに誰かの目にとまる確率が ぐっと高くなるのです. 本格的な port 残念ながら移植がそう簡単ではなく, それを動かすために 多少の変更が必要になる場合もあるでしょう. このセクションでは, 模範的な ports の作法に従い, どのように変更を行なって動くようにするのかを 順を追って説明します. port 構築の詳細 まず, あなたが port のディレクトリで make と 入力してから起こる一連の出来事について, 順を追って説明します. ここを読むときには, 別のウィンドウに bsd.port.mk を表示しておくと 理解の助けになるかもしれません. しかし, bsd.port.mk が何をしているのか 完全に理解できなくても 心配する必要はありません. それほど多くの人が理解している というわけでは ありませんから... f(^_^;) まず, fetch という ターゲットが実行されます. この fetch ターゲットは, 配布ファイルがローカルの DISTDIR に 存在することを保証する役目を持っています. もし必要なファイルが DISTDIR に 存在しなければ, fetch ターゲットは Makefile で指定された MASTER_SITES 中の URL や, FreeBSD のメイン FTP サイト ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ (ここにはバックアップとして, われわれ ports 管理者が確認した 配布ファイルを置いてあります) を探しにいきます. make を実行するマシンがインターネットに 接続されていて, 目的のファイルを FETCH で 取ってこれた場合には, それを DISTDIR に 保存します. 次に extract ターゲットが実行されます. このターゲットは DISTDIR から 配布ファイル (普通は gzip された tar ファイル) を読み込み, その内容を作業ディレクトリ WRKDIR (デフォルトでは work) に展開します. 次に patch ターゲットが実行されます. まず, PATCHFILES にパッチファイルが 指定されていれば, そのパッチを適用します. 次に, PATCHDIR ディレクトリ (デフォルトでは files サブディレクトリ) に patch-* という 名前のパッチファイルが存在すれば, これらをアルファベット順に適用します. 次に configure ターゲットが 実行されます. これには, いろいろな場合があります. scripts/configure が 存在する場合には, そのスクリプトが実行されます. HAS_CONFIGURE または GNU_CONFIGURE がセットされていれば, WRKSRC/configure が 実行されます. USE_IMAKE がセットされていれば, XMKMF (デフォルトでは xmkmf -a) が 実行されます. 最後に build ターゲットが実行されます. これは作業ディレクトリ (WRKSRC) に降りていき, ビルド (コンパイル) を実行するのが役目です. USE_GMAKE がセットされていれば GNU make が使用され, セットされていなければ FreeBSD の make が 使用されます. 上記はデフォルトの動作です. これに加えて pre- 何とかや post- 何とかという ターゲットを定義したり, そのような名前のスクリプトを scripts サブディレクトリに置くことも可能で, それぞれデフォルトの動作の前や後に実行されます. たとえば, post-extract ターゲットが Makefile に定義されていて, scripts サブディレクトリに pre-build というファイルが置かれている場合, post-extract ターゲットは 通常の展開動作の後に呼び出され, pre-build スクリプトは デフォルトのコンパイル動作の前に実行されます. 実行する動作が簡単であれば, スクリプトよりも Makefile のターゲットを使用することが 推奨されています. なぜなら, その port では どのような非標準の動作が必要とされるのか, 一箇所にまとめて書いてあった方が他の人に理解しやすいからです. デフォルトの動作は bsd.port.mk の do- 何とかという ターゲットで実行されます. たとえば port を展開するコマンドは do-extract ターゲットに書かれています. もしデフォルトのターゲットに不満があれば, Makefile 中で do- 何とかという ターゲットを再定義することにより, 好きなように変更することができます. メインのターゲット (たとえば extract, configure, その他) は, すべての前段階が実行されていることを確認してから, 実際のターゲットやスクリプトを呼び出す以外のことは 行ないませんし, これらが変更されることも想定されていません. もし展開の方法を変更したいときには do-extract の変更によって実現し, 絶対に extract には 手を触れないでください. これで, ユーザが make と 入力したときに何が起こるのかが理解できたと思います. では, 完璧な port を作成するための推奨手順を 順に見ていきましょう. オリジナルのソースの入手 (通常の場合,) 圧縮された tar ファイルの形 (foo.tar.gz あるいは foo.tar.Z) で オリジナルのソースを入手して, それを DISTDIR にコピーします. できる限り, 主流のソースを 使用するようにしてください. ネットワークへの接続の良好な FTP/HTTP サイトを 見つけることができなかったり, 頭にくるような非標準的な形式しか 置いていないサイトしか見つけられないときには, 自分の管理下にあり信頼できる FTP サーバや http サーバ (たとえば, あなた自身のホームページ) に置くこともできます. あなたが選んだサーバが MASTER_SITES に 正しく反映されていることを確認してください. そのような便利かつ信頼のおける置き場所が見つからない場合, 我々が ftp.FreeBSD.org に 置き場所を提供することもできます. 配布ファイルは, 誰かの freefall アカウントの ~/public_distfiles/ に置かれることでしょう. その port をコミットする人に, 置いてもらえるように頼んでください. その人は配布ファイルを置いて, MASTER_SITES を MASTER_SITE_LOCAL にセットし, MASTER_SITE_SUBDIR には 自分の freefall ユーザ名を 入れておいてくれるでしょう. その port の配布ファイルが特に理由もなく しょっちゅう変わる場合には, その配布ファイルを あなたのホームページに置いて, MASTER_SITES の 最初に指定することも考えてみてください. そうすれば, ユーザが checksum mismatch エラーに 悩まされることもなくなりますし, FreeBSD の FTP サイトの 保守担当者の負担も減らすこともできます. また, その port にマスターサイトが一つしか存在しない場合には, あなたのサイトにバックアップを置き, それを MASTER_SITES の 2 番目に 指定すると良いでしょう. その port がインターネット上で入手できる追加パッチを 必要とするのなら, それも取ってきて DISTDIR に置いてください. それらがメインのソースの tar ファイルとは別のサイトに あったとしても, 心配する必要はありません. そのような状況にも ちゃんと対応できるようになっています (後述の PATCHFILES の記述を ご覧ください). port の修正 作業用のディレクトリに tar ファイルを展開し, 最新バージョンの FreeBSD 上で正しくコンパイルするために必要な, あらゆる変更を行ないます. この処理は最終的に自動化するわけですから, 何を行なったかを注意深く記録しておきましょう. この port が完成した暁には, ファイルの削除, 追加, 修正を含むすべての処理が自動化されたスクリプトや パッチファイルで行なえるようになっていなければなりません. その port のコンパイルやインストールのために必要な手作業が あまりに多いようならば, Larry Wall の芸術的な Configure スクリプトを 参考にしたほうが良いかもしれません. 新しい ports collection は, エンドユーザにとって個々の port が 可能な限りプラグ & プレイかつ 最小のディスク消費で make できることを目指しています. 明示的に記述されている場合を除き, あなたが作成して FreeBSD の ports collection に寄付したパッチファイル, スクリプトおよびその他のファイルは, 標準的な BSD の 著作権条件によりカバーされているものと見なされます. パッチの適用 port の準備段階で追加されたり変更されたりしたファイルは, 再帰的 diff によりパッチファイル化することができます. パッチは適当にまとめて patch-* という名前のファイルに入れてください. * は パッチが適用される順番を示します — これらは アルファベット順, つまり aa が最初, ab が その次といった順番で処理されます. お望みなら, patch-Imakefile とか patch-src-config.h のように, パッチ対象のファイルのパス名を示す名前を使うこともできます. これらのファイルは PATCHDIR に置いてください. そうすれば自動的に適用されるようになっています. すべてのパッチは WRKSRC からの相対パスにする べきです (通常, WRKSRC は port の tar ファイルが 展開されるディレクトリで, make が実行されるところと同じです). 修正やアップグレードを容易にするため, 複数のパッチで 同じファイルを修正するのは避けてください (たとえば, patch-aa と patch-ab が共に WRKSRC/foobar.c を 修正するなど). コンフィグレーション カスタマイズのために追加したいコマンドがあれば, configure という名前のスクリプトに入れて scripts サブディレクトリに置いてください. 上で述べたように, pre-configure あるいは post-configure という Makefile ターゲットや, スクリプトで処理することもできます. ユーザからの入力の扱い もし, その port がビルド, コンフィグレーション, または インストールの際にユーザからの入力を必要とするならば, Makefile 中で IS_INTERACTIVE をセットしてください. これにより, ユーザが環境変数 BATCH を セットしている場合には, この port の処理がスキップされるので “夜間の無人ビルド“ が実行可能になります. (逆に環境変数 INTERACTIVE がセットされていると, ユーザからの入力を必要とする port だけが コンパイルされます). もし, 適切なデフォルト設定が存在するのであれば, PACKAGE_BUILDING 変数をチェックして, それが設定されている場合には ユーザ入力のスクリプトを起動しないようにしてください. こうすることによって, 我々 ports 管理者が CDROM や FTP に 置く package を作成することができます. <filename>Makefile</filename> の作成 Makefile の作成は非常に単純です. 繰り返しますが, 始めるまえに既存の例を見ておくことを推奨します. また, このハンドブックには Makefile のサンプルがあります. それを見て, Makefile 内の変数の順番や 空行を入れるところなどの参考にしてください. そうすると他の人々にも読みやすいものとなります. では, Makefile を設計するときに 問題となるところを順に追って見てみましょう. オリジナルのソース ソースは foozolix-1.2.tar.gz といった名前の 標準的な gzip された tar ファイルの形式で DISTDIR に置かれていますか? そうなっていれば, 次のステップに進めます. 異なっている場合には, 変数 DISTNAME, EXTRACT_CMD, EXTRACT_BEFORE_ARGS, EXTRACT_AFTER_ARGS, EXTRACT_SUFX, DISTFILES のうち いくつかを書き換える必要があります. どれだけ変更しないといけないかは, その port の配布ファイルが どの程度標準からかけはなれているかによります (最もよくあるのは gzip ではなく普通の compress コマンドで tar ファイルが圧縮されている場合で, そのときは EXTRACT_SUFX=.tar.Z とするだけです). 最悪の場合には, 自分で do-extract ターゲットを作成して, デフォルトを上書きすることもできます. しかし, そこまでする必要があることはめったにないでしょう. <makevar>PORTNAME</makevar> および <makevar>PORTVERSION</makevar> DISTNAME には port の名前の基幹部分を入れ, PORTVERSION には port のバージョン番号を入れます. <makevar>PORTREVISION</makevar> および <makevar>PORTEPOCH</makevar> <makevar>PORTREVISION</makevar> PORTREVISION 変数は単調増加する値です. PORTVERSION が増加した時 (つまり, 新しいオフィシャルベンダーリリースが行なわれた時) には いつでも 0 にリセットされます. また, その値が 0 でない場合には package 名に追加されます. その port から作られる package の内容や構造に 大きな影響を与える変更を行なった時には, PORTREVISION を増やしてください. PORTREVISION を上げる必要がある変更の例: セキュリティ上の脆弱性やバグを修正するため, または その port に新しい機能性を追加するためのパッチの追加. package のコンパイル時オプションの有効化や 無効化のための Makefile の変更. パッキングリストの変更や, package のインストール時の 挙動の変更 (たとえば, ssh のホストキーのような package の 初期データを生成するスクリプトの変更など). その port が依存する共有ライブラリのバージョンを 上げる場合 (新しいバージョンの共有ライブラリが インストールされた後に, そのライブラリに依存していた 古い package をインストールを試みる場合, その package は新しい libfoo.(x+1) ではなく 古い libfoo.x を探そうとするため, インストールに失敗します. (訳注: そのため, PORTREVISION を上げた package を 作成する必要があるわけです)). ひそかに port 配布ファイルの変更が行なわれ, その機能に大きな変化があった場合. つまり, distinfo の修正を 必要とするような配布ファイルの変更が行なわれ, 新旧のバージョンの diff -ru を取ると 些細とは言えない変更が認められるにもかかわらず, オリジナルのバージョン番号が変更されていないことから PORTVERSION の変更は難しい場合. PORTREVISION を上げる必要の無い変更の例: 生成される package に機能の変化が起らないような port スケルトンのスタイル変更. 生成される package に影響しないような MASTER_SITES その他の port に対する機能変更. 誤植の修正などの些細な変更で, その package のユーザが アップグレードを必要とするほどには重要でないパッチ. 以前にはコンパイルが通らなかった package を ビルド可能にするための修正 (その port が以前にビルド可能だった プラットフォームにおいて, その変更により何らかの機能的な 違いが発生しない場合に限ります). PORTREVISION は package の内容を 反映したものなので, その package が以前にビルド可能でなければ 内容の変更も無いため, PORTREVISION を 増やす必要はありません. 経験的な判断方法としては, ある port にコミットされた変更が (それが強化や修正によるものであれ, 新しい package による 実質的な効能であれ), アップデートすることにより誰かがどこかで 利益を受けるような何か かどうか自問してみることです. もし答がイエスであれば, 新しい package が利用可能になった事実を (例えば pkg_version 等の) 自動化ツールが 強調することができるように, PORTREVISION を 上げるべきでしょう. <makevar>PORTEPOCH</makevar> ソフトウェアのベンダや FreeBSD の port 作成者は, 以前のものよりも小さい数字のバージョン番号をつけたソフトウェアを リリースするといった, 何か馬鹿げたことをすることが時々あります. 例をあげると, ある port が foo-20000801 から foo-1.0 になる といった具合です (数字として見ると 20000801 は 1 よりも大きいため, 間違って前者の方が新しいバージョンとして扱われてしまいます). このような場合には PORTEPOCH バージョンを 増やしてください. 上のセクション 0 で説明したように, PORTEPOCH がゼロでない場合には, それがパッケージ名の後ろにつけられます. PORTEPOCH は減らされたり, ゼロに リセットされることはありません. さもないと, 以前に作成された package との比較に失敗する (つまり, その package が古くなっていることがわからない) ためです: 新しいバージョン番号 (上の例では1.0,1) は 依然として前のバージョン番号 (20000801) よりも 数字としては小さいのですが, 自動化ツールが サフィックス ,1 を特別扱いすることで, 以前の package には明示されていないサフィックス ",0" よりも 新しいことがわかります. 大多数の ports では, PORTEPOCH が 必要になることは まず無いものと考えられています. また, 注意深く PORTVERSION を 使用することで, そのソフトウェアの将来のリリースが バージョン構造を変更する必要が出てきた場合にも, 多くの場合 前もって対応しておくことができるでしょう. しかし, 「スナップショット」リリースのように, オフィシャルな バージョン番号を持たないベンダーリリースが行なわれた時には, FreeBSD 版の port 作者によるケアが必要になります. そういったリリースに対し, リリース日付を使ったラベルを 付けたいという誘惑にかられることがあるでしょうが, そうすると新しい「オフィシャル」リリースが行なわれた時に, 上の例で示したような問題が起きることでしょう. 例えば, あるソフトウェアのスナップショットリリースが 20000917 に行なわれ, 以前のバージョン番号が 1.2 だったとすると, そのスナップショットの PORTVERSION には 20000917 ではなく 1.2.20000917 か何か, そのような番号を 指定するのが良いでしょう. そうしておけば, 例えばバージョン番号 1.3 として後続のリリースが 行なわれた場合にも, 大小関係が崩されずにすむわけです. <makevar>PORTREVISION</makevar> と <makevar>PORTEPOCH</makevar> の使い方の例 gtkmumble の port, バージョン 0.10 が ports collection にコミットされます. PORTNAME= gtkmumble PORTVERSION= 0.10 PKGNAME は gtkmumble-0.10 になります. ローカルな FreeBSD パッチを必要とする セキュリティホールが発見されました. それに合わせて PORTREVISION を増やします. PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1 PKGNAME は gtkmumble-0.10_1 になります. ベンダから 0.2 という番号が振られた 新バージョンがリリースされます (これにより, 作者は 0.10 という番号を 0.9 の次という意味ではなく, 実際には 0.1.0 のつもりで 使用していたことがわかります - あらら, 今さら遅すぎる). 新しいマイナーバージョン 2 は数字として 以前のバージョン番号 10 より小さいので, 強制的に新しい package の方を「より新しい」と認識させるため PORTEPOCH を増やす必要があります. これは新しいベンダーリリースなので, PORTREVISION は 0 にリセット (または Makefile から削除) されます. PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1 PKGNAME は gtkmumble-0.2,1 になります. 次のリリースは 0.3 です. PORTEPOCH は減少することが無いため, 今度のバージョン変数は次のようになります: PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1 PKGNAME は gtkmumble-0.3,1 になります. もし, このアップグレードによって PORTEPOCH が 0 に リセットされたとすると, 3 は数字として 10 よりも小さいため, gtkmumble-0.10_1 の package をインストールした誰かは gtkmumble-0.3 の package の方が新しいことに 気がつかないことになるでしょう. <makevar>PKGNAMEPREFIX</makevar> および <makevar>PKGNAMESUFFIX</makevar> 二つのオプション変数 PKGNAMEPREFIX と PKGNAMESUFFIX は, PORTNAME および PORTVERSION と結合され, PKGNAME を ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION} として定義します. この時, 適切な package 名を選ぶための ガイドラインに沿っているかどうかを確認してください. 特に, PORTVERSION 中に ハイフン (-) を使用することは禁止されています. また, package 名に language- もしくは compiled.specifics 部分が 含まれる場合, それぞれ PKGNAMEPREFIX と PKGNAMESUFFIX を使用してください. これらを PORTNAME の一部としてはいけません. <makevar>DISTNAME</makevar> DISTNAME は製作者が決めたソフトウェアの名前です. デフォルトでは DISTNAME は ${PORTNAME}-${PORTVERSION} になりますが, 必要に応じて書き換えることができます. DISTNAME は二つの場所でしか使われません. 一つ目は配布ファイルリスト (DISTFILES) のデフォルト ${DISTNAME}${EXTRACT_SUFX} で, 二つ目は配布ファイルが展開される サブディレクトリ WRKSRC のデフォルト work/${DISTNAME} です. PKGNAMEPREFIX や PKGNAMESUFFIX は DISTNAME に影響を与えません. また, 元のソースアーカイブが ${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX} という 名前ではないのに, WRKSRC を work/${PORTNAME}-${PORTVERSION} と 設定している場合, おそらく DISTNAME は そのままにしておく必要があることに注意してください — DISTNAME と WRKSRC の 両方を (そして おそらく EXTRACT_SUFX も) セットするよりは, DISTFILES を 定義する方が楽でしょう. <makevar>CATEGORIES</makevar> 完成した package の実体は /usr/ports/packages/All に置かれ, 一つかそれ以上の /usr/ports/packages の サブディレクトリからのシンボリックリンクが作られます. これらのサブディレクトリの名前は CATEGORIES という 変数によって指定されます. これは, ユーザが FTP サイトや CDROM 上の package の山を 渡り歩くことを容易にするためのものです. 既存のカテゴリを見て, その port に適したものを選んでください. このリストは, この port が port ツリーの どこに取り込まれるかも決定します. 二つ以上のカテゴリを指定した場合には, 最初のカテゴリで指定されるサブディレクトリに置かれることになります. 適切なカテゴリを選ぶ方法については, カテゴリのセクションを 参照してください. 本当にその port が現存するカテゴリのいずれにも 当てはまらない場合には, 新しいカテゴリ名を作ることもできます. その場合, 新しいカテゴリ名を提案するメールを &a.ports; あてに 送ってください. <makevar>MASTER_SITES</makevar> 元になる配布ファイルを指し示す, FTP/HTTP の URL のファイル名を 除いた部分を MASTER_SITES に設定します. 最後にスラッシュ (/) をつけることを お忘れなく! このシステム上に配布ファイルが見つからなかった場合, make マクロは FETCH を使って この変数に指定されたサイトから配布ファイルを取得しようとします. このリストには, できれば異なる大陸に存在する 複数のサイトを入れておくことが推奨されています. これにより, 広域ネットワークのトラブルに対する 耐性を高めることができます. さらに私たちは, 自動的に最も近いマスタサイトを判断して, そこから取ってくるメカニズムの導入を計画しています. 元になる tar ファイルが X-contrib や GNU, Perl CPAN 等の 有名なアーカイブサイトに置かれている場合には, MASTER_SITE_* を使って これらのサイトを簡潔に (例えば MASTER_SITE_XCONTRIB とか, MASTER_SITE_PERL_CPAN のように) 指定することができます. MASTER_SITES を これらの変数の一つにセットし, サイト内でのパスを MASTER_SITE_SUBDIR に 指定するだけです. 以下に例を示します. MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications これらの変数は /usr/ports/Mk/bsd.sites.mk で 定義されています. いつでも新しいアーカイブサイトが追加されますので, port を提出する前に このファイルの最新版を チェックするように心掛けてください. ユーザは /etc/make.conf 中で MASTER_SITE_* 変数を上書きすることもできます. そうすることで, これらの有名なアーカイブそのものではなく, 好みのミラーサイトを使用することができます. <makevar>PATCHFILES</makevar> その port が配布ファイルの他に FTP や HTTP で手に入る 追加パッチを必要とする場合には, PATCHFILES には そのパッチのファイル名を, PATCH_SITES には そのファイルが置かれているディレクトリの URL をセットしてください. (書き方は MASTER_SITES と同じです.) そのパッチに記録されているファイル名に余計なパス名が ついていて, ソースツリーのトップディレクトリ (つまり WKRSRC) からの相対パスになっていない場合には, それに応じた PATCH_DIST_STRIP を指定してください. たとえば, パッチ内のすべてのファイル名の先頭に, 余計な foozolix-1.0/ がついている場合には, PATCH_DIST_STRIP=-p1 としてください. これらのパッチは圧縮されていても大丈夫です. ファイル名が .gz や .Z で 終わる場合には, 自動的に展開されるようになっています. もしパッチが, ドキュメント等その他のファイルと一緒に gzip された tar ファイルで配布されている場合には, 単に PATCHFILES を使うだけではうまくいきません. このような場合には, このパッチの tar ファイルの名前と場所を DISTFILES と MASTER_SITES に 追加しておきます. それから, EXTRA_PATCHES 変数に それらのパッチを指定すれば, bsd.port.mk が 自動的にパッチを適用してくれます. 特に注意が必要なのは, パッチファイルを PATCHDIR ディレクトリにコピーしてはならないことです — (訳注: port が CD-ROM 上に置かれている等の場合には,) そのディレクトリには書き込みができないかもしれません. それが普通の gzip か compress された tar ファイルであれば, 通常のソースファイルと一緒にパッチ適用時までに展開されていますので, 明示的に展開する必要はないことに注意してください. もしパッチを DISTFILES に追加した場合には, パッチを含むファイルが展開される際に, そのディレクトリにある 何かを上書きしないように注意してください. さらに, コピーされたパッチファイルを削除するコマンドを pre-clean ターゲットに追加することを 忘れないでください. <makevar>MAINTAINER</makevar> あなたのメールアドレスをここに入れてください. お願いします. :-) 保守担当者 (maintainer) の責任に関する詳細説明は, Makefile 中の MAINTAINER の セクションを参照してください. 依存関係 多くの port は他の port に依存しています. 必要なものすべてがユーザのマシン上に存在することを 保証するために使用可能な, 5 つの変数が用意されています. よくあるケースのためにあらかじめ設定された依存変数に加え, いくつかの依存関係の制御のための変数があります. <makevar>LIB_DEPENDS</makevar> その port が必要とする共有ライブラリを, この変数で指定します. (訳注: libc 等, 標準のライブラリは指定する必要がありません.) これは lib:dir:target という 組のリストです. lib が共有ライブラリの名前, dir が そのライブラリが見つからない場合に インストールされる port のディレクトリ, targetが そのディレクトリで呼ばれるターゲットです. たとえば, LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install と指定されていた場合, まずメジャーバージョンが 9 の jpeg 共有 ライブラリがインストールされているかどうかを確認します. インストールされていない場合には, ports ツリーの graphics/jpeg サブディレクトリに移動し, target のコンパイルとインストールを 行ないます. target の部分は, それが DEPENDS_TARGET (デフォルトでは install) と 等しいときには省略することができます. 先頭の lib の部分は ldconfig -r | grep -wF への 引数になります. この変数には正規表現を入れないようにしてください. この依存関係のチェックは, extract ターゲットと install ターゲットの中で, 2 回行なわれます. (訳注: これは, その port をビルドするマシンと インストールされるマシンが違う場合, どちらのマシンでも そのライブラリが利用できることを確認するためです.) 同様に, 依存するライブラリの名前は package 中にも書き込まれていて, pkg_add 実行時に そのライブラリが ユーザのシステムに存在していなければ, 自動的にインストールされます. <makevar>RUN_DEPENDS</makevar> この port の実行時に必要となるプログラム, またはファイルがあるときにはこの変数で指定します. これは path:dir:target という 組のリストです. path がファイルまたはプログラムの名前, dir が それが見つからない場合に インストールされる port のディレクトリ, target が そのディレクトリで呼ばれる ターゲットです. path の最初の文字が スラッシュ (/) の場合には ファイルかディレクトリとみなし, 存在するかどうか test -e を使ってチェックします. そうでない場合には実行可能ファイルであると考えて, そのプログラムがユーザのサーチパス上にあるかどうか which -s を使って確認します. たとえば Makefile に以下のように書いてあるとします. RUN_DEPENDS= ${PREFIX}/etc/innd:${PORTSDIR}/news/inn \ wish8.0:${PORTSDIR}/x11-toolkits/tk80 まず, /usr/local/etc/innd という ファイルかディレクトリが存在するか確認します. 存在しない場合には, ports ツリーの news/inn というサブディレクトリで ビルドとインストールを行ないます. さらに, wish8.0 というプログラムが ユーザのサーチパス中にあるかどうか探します. ない場合には同じく ports ツリーの x11-toolkits/tk80 というサブディレクトリで コンパイルとインストールを行ないます. この例で, innd は実際にはプログラムです. このように, プログラムであっても一般ユーザのサーチパスに 含まれているとは考えにくいところに置かれているものの場合には, 絶対パスで指定してください. この依存関係は install ターゲット中で チェックされます. また, pkg_add によるインストールの際に, その package が依存するものがユーザのシステムに存在しない場合には 自動的に追加インストールできるように, 依存するものの名前も package 中に記録されます. target の部分が DEPENDS_TARGET と同じ場合には, target の部分を省略することができます. <makevar>BUILD_DEPENDS</makevar> この port のビルド時に必要となるプログラム, またはファイルがあるときにはこの変数で指定します. RUN_DEPENDS と同様に, これは path:dir:target という 組のリストです. たとえば, BUILD_DEPENDS=unzip:${PORTSDIR}/archivers/unzip と指定されていた場合, まず unzip という名前の プログラムがインストールされているかどうかを確認します. インストールされていない場合には ports ツリーの archivers/unzip サブディレクトリに移動し, ビルドとインストールを行ないます. ここで言うビルドとは, ファイルの展開から コンパイルまでのすべての処理を意味します. この依存関係は, extract ターゲットの中で チェックされます. target の部分は, DEPENDS_TARGET と同じ場合には 省略することができます. <makevar>FETCH_DEPENDS</makevar> この port を取ってくるのに必要となるプログラム, またはファイルがあるときにはこの変数で指定します. 上の二つと同様に, これは path:dir:target という 組のリストです. たとえば, FETCH_DEPENDS=ncftp2:${PORTSDIR}/net/ncftp2 と指定されていれば, ncftp2 という名前の プログラムを探します. 見つからない場合には, ports ツリーの net/ncftp2 サブディレクトリで ビルドとインストールを行ないます. この依存関係は fetch ターゲット中で チェックされます. target の部分は, DEPENDS_TARGET と同じ場合には 省略することができます. <makevar>DEPENDS</makevar> 上記の四つのいずれにもあてはまらないような依存関係がある場合, または他の port がインストールされているだけではなく ソースが展開されている必要がある場合には, この変数を使います. これは上記の四つと違い, 特に確認するものが ありませんので, dir:target という形式のリストになります. target の部分は DEPENDS_TARGET と同じ場合には 省略することができます. よくある依存関係を表す変数 その ports が X Window System を必要とするのであれば, USE_XLIB=yes を定義してください (これは USE_IMAKE が定義されていれば 自動的に定義されます). BSD make ではなく GNU make を必要とする場合には USE_GMAKE=yes を, GNU autoconf を実行する必要がある場合には USE_AUTOCONF=yes を, 最新の qt toolkit を使用する場合には USE_QT=yes を, perl 言語のバージョン 5 を必要とする場合には USE_PERL5=yes を定義してください (特に最後のものは重要です. FreeBSD のバージョンにより, 基本システムに perl5 が 含まれていたり, いなかったりします). 依存関係に関する注意 上で述べたように, 依存する ports が必要になったときに 呼ばれるデフォルトのターゲットは DEPENDS_TARGET で, そのデフォルトは install です. これはユーザが使用する変数であり, port の Makefile で定義するものではありません. もし, その port が特別な方法で依存関係を扱う必要がある場合には, DEPENDS_TARGET を再定義するのではなく *_DEPENDS 変数の :target 部分を使用してください. make clean と入力したときには, その port が依存する port も自動的に clean されます. そうならないようにしたい場合には, 環境変数 NOCLEANDEPENDS を設定してください. 無条件に他の port に依存させるには, BUILD_DEPENDS や RUN_DEPENDS の最初のフィールドに ${NONEXISTENT} という変数を指定してください. これは, 他の port のソースが必要なときのみ使用してください. ターゲットも指定することで, コンパイルの時間を節約できる場合もあります. たとえば BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract とすると, 常に JPEG port のディレクトリに行って ソースの展開を行ないます. あなたがやりたいことが他の方法ではできない場合以外には DEPENDS を使わないでください. これは常に他の port の作成を行ない (さらにデフォルトでは インストールも行ない), package まで作成します. この動作が本当に所望のものでしたら, それを BUILD_DEPENDS と RUN_DEPENDS に書くべきでしょう — 少なくとも意図を明確にすることができます. オプション選択可能な依存ライブラリ 巨大なアプリケーションの中には, 複数のコンフィギュレーションで ビルドすることができるものがあります. つまり, いくつもの外部ライブラリやアプリケーションの中の, あるものが利用可能な場合に, それを拡張機能として使用するように 設定することができるということです. それらのライブラリやアプリケーションを, 必ずしも すべてのユーザが 必要としているわけではありませんので, ports システムでは どのコンフィギュレーションがビルドされるべきかを port 作者が 決めるために使えるフックを用意しています. これらを適切にサポートすることにより, ユーザをハッピーにしたり, port 1 つ分のコストで 2 つまたはそれ以上の port を提供するのと 同様の効率化を行なうことが可能です. これらのフックのうちで最も簡単に使えるものは WITHOUT_X11 でしょう. その port が X Window System のサポートありと, サポートなしの設定でビルドできるのであれば, 通常は X Window System サポートありでビルドするべきでしょう. ビルド時に WITHOUT_X11 が定義されていれば, その時は X Window System サポートなしのバージョンが ビルドされるべきです. GNOME 環境の様々なパーツも, そのようなノブ (フック) を 持っていますが, それらは幾分使いにくいものです. Makefile 中で その目的に使用される変数は WANT_* と HAVE_* になります. そのアプリケーションが, 以下に示されている依存ライブラリの 一つについて, サポートあり, なしの両方でビルドできる場合, Makefile には WANT_PKG を セットする必要があります. そして, ビルド時に HAVE_PKG が定義されていれば PKG を使うバージョンがビルドされることになります. 現在, このような形でサポートされている WANT_* 変数は, WANT_GLIB, WANT_GTK, WANT_ESOUND, WANT_IMLIB, そして WANT_GNOME です. ビルドのメカニズム そのソフトウェアがビルドの際に GNU make を 使う場合には, USE_GMAKE=yes をセットしてください. configure を使う場合には, HAS_CONFIGURE=yes をセットしてください. GNU configure を使う場合には, GNU_CONFIGURE=yes をセットしてください (これにより HAS_CONFIGURE もセットされます). configure に追加の引数を渡したい場合には, 追加部分を CONFIGURE_ARGS に指定してください. (デフォルトの引数リストは, GNU configure では --prefix=${PREFIX} に, GNU でない configure では空リストになります.) GNU autoconf を使う場合には, USE_AUTOCONF=yes をセットしてください. これにより GNU_CONFIGURE もセットされ, configure を実行する前に autoconf が実行されます. そのソフトウェアが X Window System のアプリケーションなどで, imake を使って Imakefile から Makefile を作成する場合には, USE_IMAKE=yes を指定してください. そうするとコンフィグレーションステージで自動的に xmkmf -a が実行されます. もし フラグが問題を引き起こすなら, さらに XMKMF=xmkmf をセットしてください. もし, その port が imake を使用するけれども install.man ターゲットを持たない場合には, NO_INSTALL_MANPAGES=yes をセットしてください. ついでに, そのソフトウェアの作者を探し出して八つ裂きにすると いいでしょう. (-_-#) そのソフトウェアの元々の Makefile が all 以外のものをメインのターゲットと している場合には, それを ALL_TARGET に 指定してください. install と INSTALL_TARGET も同様です. 特別な配慮 port を作成する場合, 考慮しなくてはいけないことが 他にもいくつかあります. このセクションでは, それらのうちでも 特によくあることについて説明します. 共有ライブラリ その port が共有ライブラリのインストールを行なう場合, make 変数 INSTALLS_SHLIB を定義してください. これにより, bsd.port.mk が post-install ターゲットの実行時に 新しいライブラリがインストールされたディレクトリ (通常は PREFIX/lib) に ${LDCONFIG} -m を実行し, 共有ライブラリキャッシュへの登録が行なわれるようになります. また, この変数が定義されている場合, 共有ライブラリを インストールしたユーザが それをすぐに使い始められるように, また, 削除の際には そのライブラリが まだ存在していると システムに誤認されないように, 適切な @exec /sbin/ldconfig -m と @unexec /sbin/ldconfig -R のペアが pkg-plist ファイルに 指定されているように扱われます. 必要であれば, 共有ライブラリがインストールされるディレクトリの リストを格納する make 変数 LDCONFIG_DIRS を 定義することにより, 新しいライブラリがインストールされる デフォルトの位置を上書きすることも可能です. 例えば, その port が共有ライブラリを PREFIX/lib/foo と PREFIX/lib/bar に インストールする場合, Makefile で 以下の記述を使用することができます: INSTALLS_SHLIB= yes LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar pkg-plist の他の部分と同様に, LDCONFIG_DIRS の内容も &man.sed.1; による 処理が行なわれるため, ここでも PLIST_SUB に 指定した置換が行なわれることに注意してください. PREFIX には %%PREFIX%% を, LOCALBASE には %%LOCALBASE%%, X11BASE には %%X11BASE%% を 使用することを推奨します. <makevar>MASTERDIR</makevar> その port の変数 (たとえば解像度とか紙のサイズなど) を 変えたりした, 少しだけ違うバージョンを作成する必要があるときには, ユーザが分りやすいように package ごとに別々のサブディレクトリを作成し, できるだけ port 間でファイルを共有するようにしてください. ほとんどの場合, うまく変数を使えば, 一つを除くすべてのディレクトリには とても短い Makefile を置くだけで済みます. その短い Makefile では, MASTERDIR を使って, 残りのファイルがあるディレクトリを指定できます. また, PKGNAMESUFFIX の 一部に変数に使って, package が別々の名前を持つようにしてください. 具体的な例を示すのが一番わかりやすいでしょう. これは japanese/xdvi300/Makefile の一部です. PORTNAME= xdvi PORTVERSION= 17 PKGNAMEPREFIX= ja- PKGNAMESUFFIX= ${RESOLUTION} : # default RESOLUTION?= 300 .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ ${RESOLUTION} != 300 && ${RESOLUTION} != 400 @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." @${FALSE} .endif japanese/xdvi300 には Makefile の他に通常のパッチや, package ファイル等が置かれています. このディレクトリで make を実行すると, デフォルトの解像度 (300) を使って, 普通に port のビルドを行ないます. 他の解像度に関していうと, xdvi118/Makefile に 必要なのはこれだけです: RESOLUTION= 118 MASTERDIR= ${.CURDIR}/../xdvi300 .include ${MASTERDIR}/Makefile (xdvi240/Makefile や xdvi400/Makefile も同様のものになります). bsd.port.mk は, MASTERDIR の定義から FILESDIR や SCRIPTDIR 等の 通常のサブディレクトリが xdvi300 以下に 存在することを理解します. RESOLUTION=118 の行が, xdvi300/Makefile の RESOLUTION=300 の行を上書きし, port は解像度を 118 として作成されます. 共有ライブラリのバージョン まず 共有ライブラリの バージョンについての指針を読んで, 一般的に 共有ライブラリのバージョンをどうすれば良いかを理解してください. ソフトウェアの作者は自分がしていることを理解していると, 盲目的に信じていてはいけません; 多くの場合は理解していないのです. 細部にわたって注意深く考慮することは大変重要です. なぜなら我々は, 互換性がないかもしれない大量のソフトウェアを 共存させようとする特殊な状況にあるからです. むかし, 不注意な port の導入が共有ライブラリに関する重大な問題を 引き起してしまったことがあります (なぜ jpeg-6b の 共有ライブラリのバージョン番号が 9 なのか, 今まで不思議に思ったことは ありませんか?). もし疑問があれば, &a.ports; にメールを送ってください. ほとんどの時間は正しい共有ライブラリのバージョンを決めることと, それを実現するためのパッチを作成することに終始します. マニュアルページ MAN[1-9LN] 変数に指定したマニュアルは 自動的に pkg-plist に追加されます (つまり, マニュアルを pkg-plist に加えては いけません— pkg-plist の生成を参照してください). また, /etc/make.conf 中の NOMANCOMPRESS の設定に従って, インストール時に マニュアルを自動的に圧縮したり復元したりします. その port が, シンボリックリンクやハードリンクを用いて, 複数のファイル名を持つマニュアルをインストールする場合には, それらを識別するために MLINKS 変数を 使用しなければなりません. port によってインストールされたリンクは, 意図したファイルを きちんと指しているかどうか確認するため, bsd.port.mk によって 削除されたり, 再作成されたりします. MLINKS に指定されたマニュアルも, pkg-plist に 含めてはいけません. マニュアルをインストール時に圧縮するかどうかを 指定するには, MANCOMPRESSED 変数を使用します. この変数は yes, no そして maybe の三つの値をとることができます, yes はマニュアルが既に圧縮されてインストール されていること, no は圧縮されていないこと, maybe は既にそのソフトウェアが NOMANCOMPRESS の値に従っていて, bsd.port.mk は 特別なにもする必要がないことを意味します. USE_IMAKE がセットされていて, NO_INSTALL_MANPAGES がセットされていなければ, MANCOMPRESSED は自動的に yes に 設定されます. それ以外の場合には, MANCOMPRESSED は no に設定されます. その port にとって, デフォルトの設定が適切でない場合以外には, 明示的に設定する必要はありません. PREFIX 以外のディレクトリの下に マニュアルを置くような port では, そのディレクトリを MANPREFIX で指定することができます. さらに, いくつかの Perl モジュールの ports のように, 特定のセクションのマニュアルだけを非標準の場所に インストールする場合, 個々のマニュアルのパスを MANsectPREFIX (ここで sect は 1-9, L, または N のいずれか) により 指定することができます. マニュアルが言語特有のサブディレクトリに置かれる場合には, その言語名を MANLANG に設定してください. この変数のデフォルト値は "" に なっています (つまり, 英語のみ). これは, 全部をまとめた例です. MAN1= foo.1 MAN3= bar.3 MAN4= baz.4 MLINKS= foo.1 alt-name.8 MANLANG= "" ja MAN3PREFIX= ${PREFIX}/share/foobar MANCOMPRESSED= yes これは, この port により以下の 6 個のファイルが インストールされることを表しています. ${PREFIX}/man/man1/foo.1.gz ${PREFIX}/man/ja/man1/foo.1.gz ${PREFIX}/share/foobar/man/man3/bar.3.gz ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz ${PREFIX}/man/man4/baz.4.gz ${PREFIX}/man/ja/man4/baz.4.gz さらに ${PREFIX}/man/man8/alt-name.8.gz が この port によってインストールされるかどうかわかりませんが, それとは無関係に foo(1) と alt-name(8) のマニュアルページを指す シンボリックリンクが作成されます. Motif を必要とする port コンパイルに Motif ライブラリを必要とするアプリケーションが いくつかあります (Motif 自体は有料のものがいくつかの会社から 手に入りますし, x11-toolkits/lesstif には 多くのアプリケーションを動作させることが可能な 無料の互換ライブラリもあります). Motif は広く使われているツールキットですし, 有料のもののライセンスでも ライブラリを静的にリンクした実行形式の再配布が認められている場合が 多いので, Motif を必要とするソフトウェアを簡単に (port からコンパイルする人々のために) 動的にでも, (package を配布する人々のために) 静的にでも リンクできるような仕組みが用意されています. <makevar>REQUIRES_MOTIF</makevar> Motif が無いとコンパイルできない port の Makefile では, この変数を指定してください. これにより, Motif を持っていない人が この port をコンパイルしようとするのを未然に防ぎます. <makevar>MOTIFLIB</makevar> この変数は bsd.port.mk によって Motif ライブラリの指定に置き換えられます. ソース内の Makefile や Imakefile で Motif ライブラリを指定している ところを, この変数に置き換えるようにパッチを適用してください. 代表的な例としては以下の二つがあげられます: Makefile か Imakefile の中で Motif ライブラリが として使われている場合には, かわりに MOTIFLIB と書いてください. Imakefile の中で XmClientLibs が使われている場合には, それを ${MOTIFLIB} ${XTOOLLIB} ${XLIB} と書きかえてください. なお MOTIFLIB は通常, -L/usr/X11R6/lib -lXm か /usr/X11R6/lib/libXm.a に置き換えられます. したがって前に や をつける必要はありません. X11 のフォント もし, あなたの port が X window system のフォントをインストールするのであれば, それらを X11BASE/lib/X11/fonts/local に置くようにしてください. このディレクトリは XFree86 release 3.3.3 で新設されたものです. もしそれが存在しなければ作成し, ユーザに XFree86 を 3.3.3 かそれより新しいものに更新か, 少なくともこのディレクトリを /etc/XF86Config のフォントパスに加えるように促すメッセージを出力するようにしてください. Info ファイル 新しい版の texinfo (2.2.2-RELEASE およびそれ以降に入っています) には install-info というコマンドが含まれており, dir ファイルに項目を追加したり削除したりすることができます. もし, あなたの port が info 文書をインストー ルするのであれば, 以下の指示に従ってその port および package が正しくユーザの ${PREFIX}/info/dir ファイルを更新するようにしてください (このセクションはとても長くてすいません. しかし info ファイルを作りあげるためにはこれらは不可欠です. 正しく行なえば美しいリストができますので, 辛抱してください! :-) まず, これを知っておかなければなりません. &prompt.user; install-info --help install-info [OPTION]... [INFO-FILE [DIR-FILE]] Install INFO-FILE in the Info directory file DIR-FILE. (訳注: Info ディレクトリの INFO-FILE を DIR-FILE にインストールする) Options: --delete Delete existing entries in INFO-FILE; don't insert any new entries. (訳注: INFO-FILE の中の項目を削除, 新しい項目は一切追加しない.) : --entry=TEXT Insert TEXT as an Info directory entry. (訳注: TEXT を Info ディレクトリの項目として追加する.) : --section=SEC Put this file's entries in section SEC of the directory. (訳注: このファイルの項目を Info ディレクトリの SEC というセクションに置く.) : このプログラムは, 実際には info ファイルをインストールしません. 単に dir ファイルにエントリを挿入したり削除したりするだけです. これから, install-info を使用するように, ports を変換する 7 段階の工程を示します. 例として editors/emacs を使用します. まず, texinfo のソースを見て, @dircategory と @direntry 文がないファイルについて, それらを追加するパッチを作成します. 以下は, ここでの例での patchの一部です: --- ./man/vip.texi.org Fri Jun 16 15:31:11 1995 +++ ./man/vip.texi Tue May 20 01:28:33 1997 @@ -2,6 +2,10 @@ @setfilename ../info/vip @settitle VIP +@dircategory The Emacs editor and associated tools +@direntry +* VIP: (vip). A VI-emulation for Emacs. +@end direntry @iftex @finalout : フォーマットについては見ればわかると思います. dir というファイルに必要な項目を書いておいてくれる作者も多いので, まず自分で書く前にさがしてみてください. また, 関係する ports も調べて, セクションの名前やインデントなどがきちんと合っているかどうかを確認してください (項目のテキスト は, すべて 4 つめのタブ・ストップ (tab stop) から始めることを推奨します). 一つファイルに対して一つの info の項目しか書けないことに注意してください. これは install-info --delete のバグにより @direntry セクションに複数の項目を書いても初めの一つの項目しか削除してくれないからです. texinfo のソースにパッチを適用する代わりに dir の項目を install-info の引数 (, ) として与えることもできますが, あまり良い方法とは言えません. なぜなら同じ情報を三つの場所 (Makefile, pkg-plist の @exec/@unexec: 以下参照) に重複して書く必要があるからです. しかし, もし日本語 (あるいは, 他のマルチバイト文字)の info ファイルがある場合には install-info の特別な引数を使用する必要があるでしょう. なぜなら makeinfo がこのような texinfo ソースファイルを扱えないからです. (このようなものをどう扱うかの例としては japanese/skk の Makefile と pkg-plist を見てください). portのディレクトリに戻って make clean; make を実行し, info ファイルが texinfo ソースファイルから再び生成されることを確認してください. texinfo ソースファイルのほうが info ファイルよりも新しいので make と入力すれば info ファイルは再構築されるはずですが, 多くの Makefile には info ファイルの正しい依存関係が書かれていません. emacs の場合, info ファイルの再構築の際には man サブディレクトリに降りるように メインの Makefile.in に パッチを適用する必要がありました. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Tue Apr 15 00:15:28 1997 @@ -184,7 +184,7 @@ # Subdirectories to make recursively. `lisp' is not included # because the compiled lisp files are part of the distribution # and you cannot remake them without installing Emacs first. -SUBDIR = lib-src src +SUBDIR = lib-src src man # The makefiles of the directories in $SUBDIR. SUBDIR_MAKEFILES = lib-src/Makefile man/Makefile src/Makefile oldXMenu/Makefile lwlib/Makefile --- ./man/Makefile.in.org Thu Jun 27 15:27:19 1996 +++ ./man/Makefile.in Tue Apr 15 00:29:52 1997 @@ -66,6 +66,7 @@ ${srcdir}/gnu1.texi \ ${srcdir}/glossary.texi +all: info info: $(INFO_TARGETS) dvi: $(DVI_TARGETS) man メインの Makefile からは, all として呼びたいのですが, サブディレクトリでのデフォルトターゲットは info になっています. このため, 二つ目のパッチが必要になります. また, info info ファイルのインストールも削除しました. なぜなら, それは同じ名前ですでに /usr/share/info にあるからです (そのパッチはここでは示しません). もし, Makefile に dir ファイルをインストールする個所があれば削除します. あなたの port がインストールしてはいけません. また, dir ファイルを壊してしまうようなコマンドの類も削除します. --- ./Makefile.in.org Mon Aug 19 21:12:19 1996 +++ ./Makefile.in Mon Apr 14 23:38:07 1997 @@ -368,14 +368,8 @@ if [ `(cd ${srcdir}/info && /bin/pwd)` != `(cd ${infodir} && /bin/pwd)` ]; \ then \ (cd ${infodir}; \ - if [ -f dir ]; then \ - if [ ! -f dir.old ]; then mv -f dir dir.old; \ - else mv -f dir dir.bak; fi; \ - fi; \ cd ${srcdir}/info ; \ - (cd $${thisdir}; ${INSTALL_DATA} ${srcdir}/info/dir ${infodir}/dir); \ - (cd $${thisdir}; chmod a+r ${infodir}/dir); \ for f in ccmode* cl* dired-x* ediff* emacs* forms* gnus* info* message* mh-e* sc* vip*; do \ (cd $${thisdir}; \ ${INSTALL_DATA} ${srcdir}/info/$$f ${infodir}/$$f; \ chmod a+r ${infodir}/$$f); \ (これは, 既存のportを修正するときのみ必要です.) pkg-plist を見て, info/dir にパッチをあてようとするものすべてを削除します. これらは pkg-install やその他のファイルにもあるかもしれないので, いろいろさがしてみてください. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/04/15 06:32:12 @@ -15,9 +15,6 @@ man/man1/emacs.1.gz man/man1/etags.1.gz man/man1/ctags.1.gz -@unexec cp %D/info/dir %D/info/dir.bak -info/dir -@unexec cp %D/info/dir.bak %D/info/dir info/cl info/cl-1 info/cl-2 post-install ターゲットを Makefile に加えてインストールされた info ファイルについては, install-info を実行するようします (dir ファイルが存在しない場合にそれを作成するようにする必要はなくなりました. install-info はこのファイルが存在しなければ自動的に作成します). Index: Makefile =================================================================== RCS file: /usr/cvs/ports/editors/emacs/Makefile,v retrieving revision 1.26 diff -u -r1.26 Makefile --- Makefile 1996/11/19 13:14:40 1.26 +++ Makefile 1997/05/20 10:25:09 1.28 @@ -20,5 +20,11 @@ post-install: .for file in emacs-19.34 emacsclient etags ctags b2m strip ${PREFIX}/bin/${file} .endfor +.for info in emacs vip viper forms gnus mh-e cl sc dired-x ediff ccmode + install-info ${PREFIX}/info/${info} ${PREFIX}/info/dir +.endfor .include <bsd.port.mk> pkg-plist を編集して, 同じ働きをする @exec 文, それに pkg_delete のために @unexec 文を加えてください. Index: pkg-plist =================================================================== RCS file: /usr/cvs/ports/editors/emacs/pkg-plist,v retrieving revision 1.15 diff -u -r1.15 pkg-plist --- pkg-plist 1997/03/04 08:04:00 1.15 +++ pkg-plist 1997/05/20 10:25:12 1.17 @@ -16,7 +14,14 @@ man/man1/etags.1.gz man/man1/ctags.1.gz +@unexec install-info --delete %D/info/emacs %D/info/dir : +@unexec install-info --delete %D/info/ccmode %D/info/dir info/cl info/cl-1 @@ -87,6 +94,18 @@ info/viper-3 info/viper-4 +@exec install-info %D/info/emacs %D/info/dir : +@exec install-info %D/info/ccmode %D/info/dir libexec/emacs/19.34/i386--freebsd/cvtmail libexec/emacs/19.34/i386--freebsd/digest-doc @unexec install-info --delete コマンドは info ファイル自身より先に置き, コマンドがファイルを読めるようにしておかなければならないことに注意してください. また @exec install-info コマンドは, info ファイルおよび dir ファイルを作る @exec コマンドより後におかなければなりません. テスト をして出来栄えに感服しましょう :) 各段階の前後に dir ファイルをチェックしましょう. <filename>pkg-<replaceable>*</replaceable></filename> ファイル pkg-* ファイルには, まだ取り上げていない何かと重宝なトリックがいくつかあります. <filename>pkg-message</filename> もしインストールする人にメッセージを表示する必要がある場合には, そのメッセージを pkg-message に置くことができます. この機能は pkg_add の後の追加のインストール手続きを表示するときなどに重宝します. pkg-message ファイルは pkg-plist に加える必要はありません. また, もしユーザが package ではなく port を使用している場合には自動的には表示されませんので, 明示的に post-install で表示するようにするべきでしょう. <filename>pkg-install</filename> バイナリパッケージが pkg_add でインストールされるときに実行する必要のあるコマンドがあれば, pkg-install スクリプトを使って実行することができます. このスクリプトは自動的に package に加えられ, pkg_add によって 2 回実行されます. 1 回目は ${SH} pkg-install ${PKGNAME} PRE-INSTALL として, 2 回目には ${SH} pkg-install ${PKGNAME} POST-INSTALL として実行されます. どちらのモードで実行されているかは $2 を調べることによってわかります. 環境変数 PKG_PREFIX には package がインストールされるディレクトリが設定されます. 詳細は &man.pkg.add.1; を見てください. port を make install でインストールするときにはこのスクリプトは自動的に実行されません. もし実行される必要があるならば port の Makefile から明示的に呼ぶ必要があります. <filename>pkg-req</filename> (訳注: 実行されるマシンの状態に応じて) その port を インストールするべきか, そうでないかを判断する必要があるときには, 要件 (requirements) スクリプト pkg-req を作ることができます. インストールや削除を実行すべきかどうか判断するために, このスクリプトがインストールや削除を実行する際に自動的に 実行されます. このスクリプトはインストール時には pkg_add により pkg-req ${PKGNAME} INSTALL として実行され, 削除時には pkg_delete により pkg-req ${PKGNAME} DEINSTALL として 実行されます. make の変数にあわせた <filename>pkg-plist</filename> の変更 いくつかの port, 特に p5-ports などは configure のオプション (あるいは, p5-ports の場合は perl のバージョン) によって pkg-plist を変える必要があります. これを容易に実現するために pkg-plist 中の %%OSREL%%, %%PERL_VER%%, %%PERL_VERSION%% は適切に置き換えられるようになっています. %%OSREL%% の値はオペレーティングシステムの数字で表されたリビジョンです (たとえば 2.2.7). %%PERL_VERSION%% は perl のバージョン番号全体 (たとえば 5.00502) で, %%PERL_VER%% はバージョン番号からパッチレベルを引いたものです (たとえば 5.005). 他の置き換えが必要であれば, PLIST_SUB 変数に VAR=VALUE という形式のペアのリストを設定することによって, pkg-plist 中の %%VAR%% は VALUE に置き換えられます. たとえばバージョンに固有のたくさんのファイルをインストールする場合には, Makefile に OCTAVE_VERSION= 2.0.13 PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} と書いて, PLIST 中のバージョン番号が表われるすべてのところに, %%OCTAVE_VERSION%% と書きます. このようにしておけば, port をアップグレードするときに, 何十行 (時として, 何百行) も pkg-plist を書き替えないですみます. この書き換えは (マニュアルの追加も) do-install と post-install ターゲットの間に pkg-plist を読み TMPPLIST (デフォルトは WRKDIR/.PLIST.mktmp) に書き込むことによって行なわれます. もし, あなたの port が PLIST を実行時に生成するのであれば, do-install の間かその前に行なうようにしてください. また, 書きかえられたあとのファイルを編集する必要がある場合には, post-install で TMPPLIST を書きかえてください. <filename>pkg-<replaceable>*</replaceable></filename>ファイルの名前変更 pkg-*ファイルの 名前はすべて変数を使用して定義されていますので, 必要であれば Makefile 中で変更可能です. いくつかの ports で一つの pkg-* ファイルを共有する場合や, 上記のファイルに書き込みをしなければならないときなど特に便利です (pkg-* サブディレクトリに直接書き込むのが良くない理由については WRKDIR 以外への書きこみ を参照してください). 以下に変数名と そのデフォルト値のリストを示します. (PKGDIR のデフォルト値は ${MASTERDIR} になっています.) 変数名 デフォルト値 COMMENT ${PKGDIR}/pkg-comment DESCR ${PKGDIR}/pkg-descr PLIST ${PKGDIR}/pkg-plist PKGINSTALL ${PKGDIR}/pkg-install PKGDEINSTALL ${PKGDIR}/pkg-deinstall PKGREQ ${PKGDIR}/pkg-req PKGMESSAGE ${PKGDIR}/pkg-message PKG_ARGS を上書きせずにこれらの変数を変更するようにしてください. PKG_ARGS を変更すると, これらのファイルは port から正しく /var/db/pkg にインストールされなくなります. ライセンス上の問題 ソフトウェアによっては, 制約の厳しいライセンス条件が 定められている場合もありますし, 国によっては (特許権の侵害などで) 法律的に問題がある可能性もあります. それらをどう扱えばいいかは, それぞれのライセンスの文面によって 大きく異なります. ソフトウェア移植者として, あなたにはライセンスをよく読み FreeBSD プロジェクトが FTP または CD-ROM で配布してはいけないソフトウェアを配布してしまうことのないよう注意する義務があります. 何か疑問がある場合には &a.ports; に聞いてみてください. よく見られるケースに対処するために, Makefile に指定できる二つの変数が用意されています. ソフトウェアに有償再配布を禁ずるという趣旨のライセン スがついてきた場合には, NO_CDROM という変数にその理由を記述してください. わたしたちはこれがついている port を CDROM リリースに入れないようにしますが, オリジナルのソースファイルと package を FTP で取れるようにしておきます. もし生成される package が個々のサイトで独自に構築される必要があったり, ライセンスによって生成されるバイナリが配布できない場合には NO_PACKAGE 変数にその理由を記述してください. そのような package は FTP サイトに置かれたり, リリース 時の CDROM へ入らないようにします. ただし, いずれの場合も 配布ファイルは (FTP や CD-ROM に) 含まれるようになります. (特許などの関係で) 使用者によっては法律上の問題が生じたり, 商用利用を禁ずるライセンスを持つ port の場合には, その理由を RESTRICTED という変数に入れてください. このような port の場合には, 配布ファイルや package も FreeBSD の FTP サイトに置かれないようになります. GNU 一般公有使用許諾書 (GPL) は, バージョン 1, 2 とも port 作成上何ら問題にはなりません. もしあなたがソースツリー管理者 (committer) であれば, ソースツリーにこのような port を入れる際に ports/LEGAL ファイルを書き換えるのを忘れないようにしてください. アップグレード port のバージョンが原作者からのものに比べて古いことに気がついたら, まずはあなたの持っている port が私たちの最新のもの (FTP ミラーサイトの ports/ports-current というディレクトリにあります) であることを確認してください. また, Ports Collection 全体を最新の状態に保つために CVSup を利用することもできます. 詳しくは FreeBSD ハンドブックをご覧ください. 次に port の Makefile に MAINTAINER (保守担当者) のアドレスが書いてある場合には, その人にメールを出してみましょう. 保守担当者の人がすでにアップグレードの準備をしているかも知れませんし, (新しいバージョンの安定度に問題があるなど) あえてアップグレードをしない理由があるのかも知れません. 保守担当者にアップグレードをしてくれと頼まれた場合, あるいは, そもそも port の Makefile に保守担当者が書いてない場合などは, あなたがアップグレードをしてくださると助かります. その場合にはアッ プグレードをした後, 変更前と変更後のディレクトリの再帰的 diff (unified diff と context diff のどちらでもいいのですが, port のコミッター達は unified diff の方を好むようです) をとって送ってください (たとえば変更前のディレクトリが superedit.bak という名前でとってあり, 変更後のものが superedit に入っているなら, diff -ruN superedit.bak superedit の結果を送ってください). diff の出力を見て, すべての変更が正しくなされているか確認してください. 変更箇所については, &man.send-pr.1; (カテゴリは ports) に diff の出力結果を添えて, わたしたちに送ってもらうのが一番良いです. commit する際に CVS に明確に記述しなければならないので, 付け加えたり削除したりしたファイルがあればそれについて書いておいてください. もし diff の大きさが 20 KB 程度を超えるようであれば, 圧縮したものを uuencode してください. そうでなければそのまま PR に入れるだけで構いません. 繰り返しになりますが, 既存の ports の変更を送るときには &man.shar.1; ではなく &man.diff.1; を使用してください! やっていいことといけないこと このセクションではソフトウェアを port する上で, 良くある落し穴などについて説明します. このリストを使ってあなた自身が作成した port のチェックはもとより, PR データベースにある, 他の人が作成した port のチェックもできます. あなたがチェックした port についてのコメントをバグ報告と一般的な論評にしたがって送ってください. PR データベースにある port をチェックすると, わたしたちがそれらを commit するのを早くし, あなたが何をしているか理解していることも示します. バイナリの strip バイナリは strip してください. オリジナルのソースがバイナリを strip してくれる場合は良いですが, そうでない場合には port の Makefile が install ターゲットを持っているなら BSD_INSTALL_PROGRAM を, 持っていないなら strip するための post-install ルールを追加して strip するようにするとよいでしょう. たとえばこんな風になります: post-install: strip ${PREFIX}/bin/xdl インストールされた実行形式がすでに strip されているかどうかは file コマンドで確認できます. not stripped と表示されなければ strip されていることを示しています. <makevar>INSTALL_*</makevar> マクロ あなた自身の *-install ターゲットでファイルの正しいモードとオーナを保証するために, 必ず bsd.port.mk で提供されているマクロを使用してください. ${INSTALL_PROGRAM} は実行可能なバイナリをインストール (し, その過程で strip 処理)するコマンドです. ${INSTALL_SCRIPT} は実行可能なスクリプトをインストールするコマンドです. ${INSTALL_DATA} は共有可能なデータをインストールするコマンドです. ${INSTALL_MAN} はマニュアルとその他の文書をインストールするコマンドです (圧縮はしません). これらは基本的に install コマンドに適切なフラグを与えたものです. それらは distfile の Makefile で, 頭に BSD_ が付けられた (つまり BSD_INSTALL_PROGRM というような) 形で使うことができます. どのようにこれらを使用するかは以下の例を見てください. <makevar>WRKDIR</makevar> WRKDIR の外に存在するファイルには 何も書き込んではいけません. port のビルド中に書き込み可能なことが保証されているのは WRKDIR の中だけです (書き込み不可のツリー上での port ビルドの例については, CDROM からの ports のコンパイル を参照のこと). pkg-* ファイルを 変更する必要があるときには, ファイルを上書きするのではなく 変数の再定義により 行なうようにしてください. <makevar>WRKDIRPREFIX</makevar> WRKDIRPREFIX を尊重していることを確認してください. 特に, 別の port の WRKDIR を参照しているときには気を付けてください. 正しい場所は, WRKDIRPREFIXPORTSDIR/subdir/name/work です, PORTSDIR/subdir/name/work や .CURDIR/../../subdir/name/work ではありません. また, 自分で WRKDIR 定義するときには先頭に ${WRKDIRPREFIX}${.CURDIR} が付いていることを確認してください. OS の種類やバージョンの識別 どのバージョンの Unix で動かすかによって, 変更や 条件つきコンパイルが必要なコードに出くわすこともあるでしょう. そのような変更を行なう場合には, FreeBSD 1.x システムへのバックポートや, CSRG の 4.4BSD, BSD/386, 386BSD, NetBSD, OpenBSD 等, 他の BSD システムへの移植が可能なように, できるだけ汎用的な変更を行なうことを心がけてください. 4.3BSD/Reno (1990) と, それより新しいバージョンの BSD コードを 区別するには, <sys/param.h> で定義されている BSD マクロを利用するのがよいでしょう. このファイルがすでにインクルードされていれば良いのですが, そうでない場合には, その .c ファイルの 適当な場所に以下のコードを追加してください. #if (defined(__unix__) || defined(unix)) && !defined(USG) #include <sys/param.h> #endif これらの二つのシンボルが定義されているシステムには必ず sys/param.h があるはずです. もしそうでないシステムを発見したら, &a.ports; までメールを送ってわたしたちに伝えてください. あるいは, GNU Autoconf のスタイルを使用することもできます, #ifdef HAVE_SYS_PARAM_H #include <sys/param.h> #endif この方法を使用するときには, Makefile 中の CFLAGSに -DHAVE_SYS_PARAM_H を加えることを忘れないようにしてください. いったん sys/param.h がインクルードされると, #if (defined(BSD) && (BSD >= 199103)) このようにしてそのコードが 4.3 Net2 コードベース, またはそれより新しいもの (例: FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 1.1 とそれ以前) の上でコンパイルされているかを検出できます. #if (defined(BSD) && (BSD >= 199306)) これは, 4.4コードベース, またはそれより新しいもの (例: FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 とそれ以後) の上でコンパイルされているかどうかを検出するために使用します. 4.4BSD-Lite2 コードベースでは BSD マクロの値は 199506 になっています. これは参考程度の意味合いしかありません. 4.4-Lite ベースの FreeBSD と 4.4-Lite2 での変更がマージされたバージョンとを区別するのに使用するべきものではありません. この目的のためにはかわりに __FreeBSD__ マクロを使用してください. 以下は控え目に使ってください. __FreeBSD__ はFreeBSDのすべての版で定義されています. 変更が FreeBSD だけに適用されるとき以外は使用しないでください. port でよくある strerror() ではなく sys_errlist[] を使うなどは FreeBSDでの変更ではなく BSD の流儀です. FreeBSD 2.xでは __FreeBSD__ が 2 と定義されています. それ以前の版では 1 になっています. その後の版ではそのメジャー番号に合うように上がっていきます. もし FreeBSD 1.x システムと FreeBSD 2.x, あるいは FreeBSD 3.x システムを区別する必要があれば, 上で述べた BSD マクロを使用するのが大抵の場合において正しい答です. もし FreeBSD 特有の変更であれば (ld を使うときの共有ライブラリ用のオプションなど), __FreeBSD__を使い #if __FreeBSD__ > 1 のようにFreeBSD 2.x および, それ以降のシステムを検出するのはかまいません. もし 2.0-RELEASE 以降の FreeBSD システムを細かく検出したければ, 以下を使用することができます. #if __FreeBSD__ >= 2 #include <osreldate.h> # if __FreeBSD_version >= 199504 /* 2.0.5+ release specific code here */ # endif #endif Release __FreeBSD_version 2.0-RELEASE 119411 2.1-CURRENT 199501, 199503 2.0.5-RELEASE 199504 2.1 以前の 2.2-CURRENT 199508 2.1.0-RELEASE 199511 2.1.5 以前の 2.2-CURRENT 199512 2.1.5-RELEASE 199607 2.1.6 以前の 2.2-CURRENT 199608 2.1.6-RELEASE 199612 2.1.7-RELEASE 199612 2.2-RELEASE 220000 2.2.1-RELEASE 220000 (変更なし) 2.2.1-RELEASE 以降の 2.2-STABLE 220000 (変更なし) texinfo-3.9 以降の 2.2-STABLE 221001 top 導入以降の 2.2-STABLE 221002 2.2.2-RELEASE 222000 2.2.2-RELEASE 以降の 2.2-STABLE 222001 2.2.5-RELEASE 225000 2.2.5-RELEASE 以降の 2.2-STABLE 225001 ldconfig -R マージ以降の 2.2-STABLE 225002 2.2.6-RELEASE 226000 2.2.7-RELEASE 227000 2.2.7-RELEASE 以降の 2.2-STABLE 227001 &man.semctl.2; 変更以降の 2.2-STABLE 227002 2.2.8-RELEASE 228000 2.2.8-RELEASE 以降の 2.2-STABLE 228001 &man.mount.2; 変更以前の 3.0-CURRENT 300000 &man.mount.2; 変更以降の 3.0-CURRENT 300001 &man.semctl.2; 変更以降の 3.0-CURRENT 300002 ioctl 引数変更以降の 3.0-CURRENT 300003 ELF 化以降の 3.0-CURRENT 300004 3.0-RELEASE 300005 3.0-RELEASE 以降の 3.0-CURRENT 300006 3/4 の分岐以降の 3.0-STABLE 300007 3.1-RELEASE 310000 3.1-RELEASE 以降の 3.1-STABLE 310001 C++ コンストラクタ/デストラクタ順序変更の後の 3.1-STABLE 310002 3.2-RELEASE 320000 3.2-STABLE 320001 バイナリ互換性のない IPFW とソケットの変更後の 3.2-STABLE 320002 3.3-RELEASE 330000 3.3-STABLE 330001 libc に &man.mkstemp.3; が追加された後の 3.3-STABLE 330002 3.4-RELEASE 340000 3.4-STABLE 340001 3.4 が分岐した後の 4.0-CURRENT 400000 dynamic linker の変更後の 4.0-CURRENT 400001 C++ コンストラクタ/デストラクタ順序変更の後の 4.0-CURRENT 400002 &man.dladdr.3; 機能追加後の 4.0-CURRENT 400003 __deregister_frame_info dynamic linker のバグ修正, EGCS 1.1.2 導入後の 4.0-CURRENT 400004 &man.suser.9; の API 変更, newbus 化 以降の 4.0-CURRENT 400005 cdevsw 登録方法の変更後の 4.0-CURRENT 400006 ソケットレベルの証明書 (credential) のために so_cred が追加された後の 4.0-CURRENT 400007 libc_r への poll syscall ラッパー追加後の 4.0-CURRENT 400008 kernel の dev_t 型から struct spacinfo ポインタへの 変更後の 4.0-CURRENT 400009 &man.jail.2; のセキュリティホール 修正後の 4.0-CURRENT 400010 sigset_t の データ型変更後の 4.0-CURRENT 400011 システムコンパイラを gcc 2.95.2 にアップグレードした 後の 4.0-CURRENT 400012 動的組み込み可能な Linux モードの ioctl ハンドラが 追加された後の 4.0-CURRENT 400013 OpenSSL 導入後の 4.0-CURRENT 400014 GCC 2.95.2 の C++ ABI 変更で, デフォルトを -fvtable-thunks から -fno-vtable-thunks に 変更した後の 4.0-CURRENT 400015 OpenSSH 導入後の 4.0-CURRENT 400016 4.0-RELEASE 400017 4.0-RELEASE 以降の 4.0-STABLE 400018 libxpg4 が libc にマージされた後の 4.0-STABLE 400020 Binutils を 2.10.0 にアップグレードし, ELF バイナリのマーク付け (branding) 方法を変更し, tcsh をベースシステムに導入した後の 4.0-STABLE 400021 4.1-RELEASE 410000 4.1-RELEASE 以降の 4.1-STABLE 410001 &man.setproctitle.3; が libutil から libc に 移動した後の 4.1-STABLE 410002 4.1.1-RELEASE 411000 4.1.1-RELEASE 以降の 4.1.1-STABLE 411001 4.2-RELEASE 420000 libgcc.a と libgcc_r.a の結合および, 関連する GCC linkage 変更が行なわれた後の 4.2-STABLE 420001 4.3-RELEASE 430000 wint_t 導入後の 4.3-STABLE 430001 PCI パワーステート API マージ後の 4.3-STABLE 430002 5.0-CURRENT 500000 ELF ヘッダフィールドの追加と ELF バイナリのマーク付け (branding) 方法の変更後の 5.0-CURRENT 500001 kld メタデータ変更後の 5.0-CURRENT 500002 buf/bio 変更後の 5.0-CURRENT 500003 binutils アップグレード後の 5.0-CURRENT 500004 libxpg4 コードの libc へのマージと, TASKQ インターフェイスの導入後の 5.0-CURRENT 500005 AGP インターフェイス追加後の 5.0-CURRENT 500006 Perl を 5.6.0 にアップグレードした後の 5.0-CURRENT 500007 KAME コードを 2000/07 版のソースに更新した後の 5.0-CURRENT 500008 ether_ifattach() および ether_ifdetach() 変更後の 5.0-CURRENT 500009 mtree のデフォルトをオリジナルの変種に戻し, シンボリックリンクをたどる -L オプションを追加した後の 5.0-CURRENT 500010 kqueue API 変更後の 5.0-CURRENT 500011 &man.setproctitle.3; が libutil から libc へ移動した後の 5.0-CURRENT 500012 最初の SMPng がコミットされた後の 5.0-CURRENT 500013 <sys/select.h> が <sys/selinfo.h> に 移動した後の 5.0-CURRENT 500014 libgcc.a と libgcc_r.a の結合および関連する GCC linkage 変更が行なわれた後の 5.0-CURRENT 500015 libc と libc_r の混合リンクを許し, -pthread オプションを deprecate する 変更後の 5.0-CURRENT 500016 mountd 等が使用する kernel-exported API の 安定化のため, ucred 構造体から xucred 構造体へ 移行した後の 5.0-CURRENT 500017 CPU 依存の最適化を制御するための make 変数 CPUTYPE が追加された後の 5.0-CURRENT 500018 <machine/ioctl_fd.h> が <sys/fdcio.h> に移動した後の 5.0-CURRENT 500019 ロケール名変更の後の 5.0-CURRENT 500020 Bzip2 導入後の 5.0-CURRENT 500021 SSE サポート後の 5.0-CURRENT 500022 (2.2-STABLE は 2.2.5-RELESE 以後, 2.2.5-STABLE と呼ばれることがあります.) 見てのとおりこれは年・月というフォーマットになっていましたが, バージョン 2.2 からより直接的にメジャー/マイナー番号を使うように変更になりました. 並行していくつかのブランチ (枝分かれしたバージョン) を開発する場合には, リリースされた日付でそれらのリリースを分類することが不可能だからです (あなたが今 port を作成するときに, 古い -CURRENT 達について心配する必要はありません. これは参考のために挙げられているに過ぎないからです). これまで, 何百もの port が作られてきましたが, __FreeBSD__ が正しく使われたのは一つか二つの場合だけでしょう. 以前の port が誤った場所でそのマクロを使っているからといって, それをまねする理由はありません. <filename>bsd.port.mk</filename> の後に書くこと .include <bsd.port.mk> の行の後には何も書かないようにしてください. 大抵の場合は Makefile の中程のどこかで bsd.port.pre.mk をインクルードして, 最後に bsd.port.pre.mk をインクルードすることによって避けることができます. pre.mk/post.mk のペアか bsd.port.mk だけのどちらかだけをインクルードし, 二つを混ぜないでください. 前者はいくつかの変数の定義だけをして Makefile でのテストに使用し, 後者は残りを定義します. 以下は bsd.port.pre.mk で定義される重要な変数です (これは, すべてではありません. 完全なリストは bsd.port.mk を参照してください). 変数名 解説 ARCH uname -m で返される アーキテクチャ. (例, i386). OPSYS uname -s で返される オペレーティングシステム (例, FreeBSD). OSREL オペレーティングシステムの リリースバージョン (例., 2.1.5, 2.2.7). OSVERSION 数字形式のオペレーティングシステム のバージョン, 上記の __FreeBSD_version と同じです. PORTOBJFORMAT システムのオブジェクト フォーマット (aout あるいは elf). LOCALBASE local ツリーのベース. (例, /usr/local/). X11BASE X11 ツリーのベース. (例, /usr/X11R6/). PREFIX ports のインストール先 ( PREFIXについてを参照). USE_IMAKE, USE_X_PREFIX あるいは MASTERDIR などの変数を定義する必要がある場合には, bsd.port.pre.mk をインクルード前に定義してください. 他のものは bsd.port.pre.mk の前でも後でもかまいません. 以下は bsd.port.pre.mk の後に書けるものの例です. # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif # only one shlib version number for ELF .if ${PORTOBJFORMAT} == "elf" TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} .else TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} .endif # software already makes link for ELF, but not for a.out post-install: .if ${PORTOBJFORMAT} == "aout" ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so .endif 付加的な文書のインストール 普通のマニュアルや info ファイルの他にユーザにとって有用だと思えるような文書がある場合には, PREFIX/share/doc の下にインストールしてください. これは前記と同様 post-install ターゲットの中から行なうと良いでしょう. まず, あなたの port のために新しいディレクトリを作ります. どの port の文書か簡単にわかるような名前にする必要がありますので, 普通は PORTNAME を使うと良いでしょう. もちろん, ユーザが異なるバージョンのものを同時に使うことが予想される port の場合には PKGNAME をそのまま使っても構いません. ユーザが /etc/make.conf でこの部分を禁止するために NOPORTDOCS という変数をセットしている場合には, これらの文書がインストールされないようにしてください. こんな具合です. post-install: .if !defined(NOPORTDOCS) ${MKDIR} ${PREFIX}/share/doc/xv ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${PREFIX}/share/doc/xv .endif 文書ファイルおよびディレクトリはすべて pkg-plist の中に %%PORTDOCS%% を頭につけて書く必要があります. たとえば, 次のようにしてください. %%PORTDOCS%%share/doc/pure-ftpd/AUTHORS %%PORTDOCS%%share/doc/pure-ftpd/CONTACT %%PORTDOCS%%@dirrm share/doc/pure-ftpd インストール時に pkg-message ファイルを利用してメッセージを表示することができます. 詳細は pkg-message を使うのセクションを 参照してください. pkg-message ファイルを pkg-plist に加える必要はありません. <makevar>DIST_SUBDIR</makevar> /usr/ports/distfiles ディレクトリ内をあまり散らかさないようにしてください. たくさんのファイルを取ってくる port や, 数は少なくても他の port のファイルと混同される恐れがあるファイル (Makefile など) がある場合には, DIST_SUBDIR に port の名前 (${PORTNAME} か ${PKGNAMEPREFIX}${PORTNAME} を使うといいでしょう) を入れてください. すると DISTDIR がデフォルトの /usr/ports/distfiles から /usr/ports/distfiles/DIST_SUBDIR に変更され, 取ってきたファイルはすべてそのサブディレクトリの中に置かれるようになります. また, ファイルを取ってくるときにバックアップサイトとして使われる ftp.FreeBSD.org のディレクトリ名にもこの変数の値が使われます (DISTDIR を明示的に指定した場合, ローカルのファイルを置くところは変わりますが, このサイトのディレクトリ名は変わりません. 必ず DIST_SUBDIR を使うようにしてください). この変数は Makefile 中で明示的に指定された MASTER_SITES には影響しないことに注意してください. package 情報 pkg-comment や pkg-descr, pkg-plist といった package 情報を必ず入れるようにしてください. これらのファイルはもはや package の作成だけに使われるものではなくなっています. たとえ NO_PACKAGEが定義されていたとしても 必須であることに注意してください. RCS 文字列 RCS にとって特別な意味を持つ文字列をパッチ内に入れないようにしてください. ファイルを私たちのソースツリーに入れる時, これらの文字列は CVS によって書き換えられてしまい, 後でまたパッチを使おうとした時にうまくいかないことがあります. RCS 文字列はドル記号 ($) で囲まれており, $FreeBSD や $RCS などで始まります. 再帰的 diff diff の再帰 () フラグを使って再帰的なパッチを作るのは大変結構なのですが, でき上がったパッチは必ず目でチェックして余計なゴミが入っていないことを確認してください. よくあるのはバックアップファイル同士の変更点, あるいは Imake や GNU configure を使うソフトウェアの Makefile の変更点が入っている場合などです. また configure.in を編集して autoconf を使って configure を作り直すときには, configure の diff は含めずに (それらは良く数千行におよぶことがあります), USE_AUTOCONF=yes を定義して configure.in の diff をとってください. ファイルをまるごと消す場合には, パッチを使わずに post-extract ターゲットで消す方が簡単です. できあがった差分に満足したら, それらをソースのファイルごとに別々のパッチファイルに分割してください. <makevar>PREFIX</makevar> なるべく port は PREFIX に対する相対パスにインストールすることができるように心がけてください (この変数の値は USE_X_PREFIX か USE_IMAKE が指定してある時には X11BASE (デフォルトは /usr/X11R6), そうでない場合にはLOCALBASE (デフォルトは /usr/local) にセットされます). サイトによってフリーソフトウェアがインストールされる場所が違いますので, ソース内で /usr/local や /usr/X11R6 を明示的に書かないようにしてください. X のプログラムで imake を使うものについては, これは問題にはなりません. それ以外の場合にはソース中の Makefile やスクリプトで /usr/local (imake を使わない X のプログラムは /usr/X11R6) と書いてあるところを PREFIX に書き換えてください. この値は port のコンパイルおよび, インストール時に自動的に環境変数として下位 make に渡されます. そのアプリケーションが PREFIX を 使用しないで, 何かを直接 /usr/local に インストールしないことを確認してください. 以下のようにすると, 簡単なテストを行なうことができます: &prompt.root; make clean; make package PREFIX=/var/tmp/port-name この時, もし PREFIX の外に 何かがインストールされていた場合, package 生成プロセスは ファイルが見つからないと文句を言うはずです. ただし, これは そのソフトウェアが内部で決め打ちの参照を していないかどうか だとか, 他の port によってインストールされる ファイルを参照する際に LOCALBASE を 正しく使用しているかどうかをテストしているわけではありません. その port を他の場所にインストールした状態で, /var/tmp/port-name に 対するインストールを試みることにより, そのテストをすることができるでしょう. USE_X_PREFIX は本当に必要な時 (つまり X のライブラリをリンクしたり, X11BASE 以下にある ファイルを参照したりする必要がある時) 以外には 設定しないでください. 変数 PREFIX の値は port の Makefile やユーザの環境で変更することもできます. しかし, 個々の port が Makefile でこの変数の値を明示的に設定することはなるべくしないでください. また, 他の port によりインストールされるプログラムや ファイルを指定する場合には, 直接的なパス名を使用するのではなく 上で述べた変数を使用してください. たとえば less のフルパスを PAGER というマクロに入れたい場合は, -DPAGER=\"/usr/local/bin/less\" というフラグをコンパイラに渡すかわりに -DPAGER=\"${PREFIX}/bin/less\" (X Window System を使う port の場合には -DPAGER=\"${LOCALBASE}/bin/less\") を渡してください. こうしておけば, システム管理者が /usr/local を まるごと どこか他の場所に移していたとしても, その port が そのまま使える可能性が高くなります. ディレクトリ構成 インストール時には PREFIX の正しいサブディレクトリにファイルを置くように心がけてください. ソフトウェアによっては新しいディレクトリを一つ作って, ファイルを全部それに入れてしまうものがありますが, それは良くありません. また, バイナリ, ヘッダファイルとマニュアル以外のすべてを lib というディレクトリに入れてしまう port もありますが, これも BSD 的なファイルシステム構成からいうと正しくありません. これは以下のように分散すべきです. etc にセットアップ/コンフィグレーションファイル, libexec に内部で使用されるプログラム (コマンドラインから呼ばれることのないコマンド), sbin に管理者用のコマンド, info に GNU Info 用の文書, そして share にアーキテクチャに依存しないファイルが入ります. 詳細については &man.hier.7; のマニュアルページを参照してください. /usr の構成方針はほとんどそのまま /usr/local にもあてはまります. USENET ニュースを扱う ports は例外です. これらはファイルのインストール先として PREFIX/news を使用します. 空のディレクトリの削除 ports は削除の際に, 自分自身を消去したあとに (ディレクトリの) 削除をするようにしてください. これは大抵の場合 @dirrm の行を ports が作成するすべてのディレクトリについて加えることによって実現できます. 親ディレクトリは子ディレクトリを先に消さないと消せないことに注意してください. : lib/X11/oneko/pixmaps/cat.xpm lib/X11/oneko/sounds/cat.au : @dirrm lib/X11/oneko/pixmaps @dirrm lib/X11/oneko/sounds @dirrm lib/X11/oneko といった感じです. しかし時として, 他の port とディレクトリを共有しているために @dirrm がエラーを返すことがあります. rmdir を @unexec から呼びだすことによって, 警告(warning)なしで空のディレクトリのみを削除することができます. @unexec rmdir %D/share/doc/gimp 2>/dev/null || true これを使えば, たとえ他の port がファイルをインストールしていて PREFIX/share/doc/gimp が空でない場合でもエラーメッセージは表示されませんし, pkg_delete が異常終了することもありません. UID あなたの port が, インストールされるシステム上に特定のユーザを必要とする場合は pkg-install スクリプトから pw コマンドを実行して自動的にそのユーザを追加するようにしてください. net/cvsup-mirror の port が参考になるでしょう. あなたの port がバイナリの package としてインストールされる場合とコンパイルされる場合の両方で, 同じユーザー/グループ ID を使わなければならないのなら, 50 から 99 の間で空いている UID を選んで登録してください. japanese/Wnn の port が参考になるでしょう. 既にシステムや他の port で利用されている UIDを使わないように十分注意してください. 現在の 50 から 99 までの間の UID は以下のとおりです. majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent pop:*:68:6:Post Office Owner (popper):/nonexistent:/nonexistent wnn:*:69:7:Wnn:/nonexistent:/nonexistent ifmail:*:70:66:Ifmail user:/nonexistent:/nonexistent pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh ircd:*:72:72:IRCd hybrid:/nonexistent:/nonexistent alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent qmaill:*:83:81:QMail user:/var/qmail:/nonexistent qmaild:*:82:81:QMail user:/var/qmail:/nonexistent qmailq:*:85:82:QMail user:/var/qmail:/nonexistent qmails:*:87:82:QMail user:/var/qmail:/nonexistent qmailp:*:84:81:QMail user:/var/qmail:/nonexistent qmailr:*:86:82:QMail user:/var/qmail:/nonexistent msql:*:87:87:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin vpopmail:*:89:89::0:0:User &:/usr/local/vpopmail:/nonexistent このリストを最新の状態に保つためにも, この範囲の UID や GID を予約するような port を作ったり, 既存の port にそのような改変を行なってわたしたちに送るときには UID の予約に関する注意書きをつけてください. 合理的な port Makefile は単純かつ適切であるべきです. もし, Makefile を数行短かくできたり, もっと読みやすくできるのであればそうしてください. たとえば, シェルの if 構文を使うかわりに make の .if 構文を使う, EXTRACT* の再定義で代用できるのであれば do-extract を再定義しない, CONFIGURE_ARGS += --prefix=${PREFIX} とするかわりに GNU_CONFIGURE とする, などです. <makevar>CFLAGS</makevar> の尊重 CFLAGS 変数は尊重すべきです. port がこれを無視する場合は, NO_PACKAGE=ignores cflags を Makefile に加えてください. CFLAGS 変数をきちんと考慮した Makefile の例を以下に示します. += の部分に注目してください. CFLAGS += -Wall -Werror 次は CFLAGS 変数を考慮しない Makefile の例です. CFLAGS = -Wall -Werror CFLAGS 変数は, FreeBSD システムの /etc/make.conf で定義されています. 最初の例では既存の定義を保存しつつ CFLAGS 変数にオプションフラグを追加しているのに対し, 二番目の例では既存の定義をすべて無効にしてしまっています. コンフィグレーション (設定) ファイル もしあなたの port が設定ファイルを PREFIX/etc に置く必要がある場合には, それを単純にインストールしたり, pkg-plist に加えてはいけません. こうしてしまうと pkg_delete によってユーザが苦労して作ったファイルが消えてしまったり, 新しくインストールする時に上書きされてしまったりします. かわりに見本となるファイルを サフィックス (filename.sample が良いでしょう) を付けてインストールしてメッセージを表示し, ソフトウェアを動かす前にユーザがそのファイルをコピーして編集をしなければならないことを知らせましょう. portlint 送付や commit をする前に portlint を使ってチェックしましょう. フィードバック port を作るためにソフトウェアに変更を加えたら, なるべく原作者にその旨を伝えてパッチ等を送ってください. これらが次のリリースに取り入れられればアップグレードが楽になります. <filename>README.html</filename> README.html というファイルを含めてはいけません. このファイルは, cvs コレクションの一部ではなく, make readme コマンドで生成されるファイルです. その他諸々 pkg-comment, pkg-descr, pkg-plist などのファイルはそれぞれ二重にチェックしてください. 再検討してもっと良い記述があればそれに置きかえてください. GNU General Public License (GNU一般公有使用許諾) のコピーは (すでにあるので) コピーしないでください. お願いします. 法律に関することには十分注意をはらってください. わたしたちに法律に反するような形でソフトウェアの配布をさせないでください! 困ったら.... わたしたちに質問を送る前に, 既存の port の例と bsd.port.mk をちゃんと読んでください! ;) それでもわからないことがあったら一人で悩まないでどんどん質問してください! :-) <filename>Makefile</filename> のサンプル これは port の Makefile を作る際のお手本です. かぎかっこ ([]) 内のコメントは忘れずに取ってください. 変数の順番, 段落の間の空行など, Makefile を作るときはなるべくこの形式に従ってください. この形式は重要な情報が簡単に見つけられるように設計されています. portlint を使って Makefile をチェックすることが推奨されています. [ヘッダ ... どのような port の Makefile かすぐにわかるようになっています] # New ports collection makefile for: xdvi ["version required" 行は, PORTVERSION 変数では port のバージョンを 十分に表現できない場合にのみ必要です. ] # Date created: 26 May 1995 [このソフトウェアを最初に FreeBSD に port した人の名前, つまり, この Makefile の最初の版を書いた人です. この port をアップグレー ドするとき, この行も変えないでください.] # Whom: Satoshi Asami <asami@FreeBSD.org> # # $FreeBSD$ [ ^^^^^^^^^ この部分は, CVS ツリーに入れる時に自動的に RCS の ID 文字列に 置き換えられます.] # [port 自体, およびオリジナルのソースを取ってくるところを記述する部分. 最初は必ず PORTNAME と PORTVERSION, そして必要なら PKGNAME, CATEGORIES, 続いて MASTER_SITES が置かれ, さらに MASTER_SITE_SUBDIR が 置かれることもあります. 必要なら PKGNAMEPREFIX と PKGNAMESUFFIX が それに続き, そして DISTNAME, EXTRACT_SUFX, DISTFILES が, また, その後に必要に応じて EXTRACT_ONLY が置かれます.] PORTNAME= xdvi PORTVERSION= 18.2 CATEGORIES= print [MASTER_SITE_* マクロを使用しない場合は, 最後のスラッシュを忘れないように ("/")!] MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications DISTNAME= xdvi-pl18 [ソースファイルが標準の ".tar.gz" 形式でない時にこれを使いましょう] EXTRACT_SUFX= .tar.Z [配布パッチセクション -- ない場合もあります] PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz [保守責任者 -- これは *必ず* 必要です. 担当者 (あなた) 自身, あるいは 担当者に素早く連絡をとれる人のアドレスを書いてください. どうしてもこ こに自分のアドレスを書くのがいやな人は "ports@FreeBSD.org" と書いて もいいです] MAINTAINER= asami@FreeBSD.org [依存するport -- ない場合もあります] RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm [ここには標準の bsd.port.mk の変数で, 上のどれにもあてはまらないものを 書きます] [コンフィグレーション, コンパイル, インストールなどの時に質問をする なら...] IS_INTERACTIVE=yes [${DISTNAME} 以外のディレクトリにソースが展開されるなら...] WRKSRC= ${WRKDIR}/xdvi-new [配布されているパッチが ${WRKSRC} に対する相対パスで作られてい い場合にこの変数の指定が必要かも...] PATCH_DIST_STRIP= -p1 [GNU autoconf によって生成された "configure" スクリプトを走らせたいなら...] GNU_CONFIGURE= yes [/usr/bin/makeでなく, GNU make を使わないといけないなら...] USE_GMAKE= yes [これが X のアプリケーションで, "xmkmf -a" を走らせたいなら...] USE_IMAKE= yes [などなど] [下の方のルールで使う非標準の変数] MY_FAVORITE_RESPONSE= "yeah, right" [そして, 特別なターゲット, 使用順に] pre-fetch: i go fetch something, yeah post-patch: i need to do something after patch, great pre-install: and then some more stuff before installing, wow [最後には必ず] .include <bsd.port.mk> パッキングリストの自動生成 まず, あなたの port に pkg-plist がないことを除いて完全なことを確認して, 空の pkg-plist を作ってください. &prompt.root; touch pkg-plist 次に, あなたの port をインストールすることができるディレクトリ階層を新たに作成してください. また, 依存するものをインストールしてください. &prompt.root; mtree -U -f /etc/mtree/BSD.local.dist -d -e -p /var/tmp/port-name &prompt.root; make depends PREFIX=/var/tmp/port-name このディレクトリ構造を新しいファイルに保存してください. &prompt.root; (cd /var/tmp/port-name && find * -type d) > OLD-DIRS もしあなたの port が PREFIX にちゃんと従うなら, ここで port をインストールしてパッキングリストを作ることができます. &prompt.root; make install PREFIX=/var/tmp &prompt.root; (cd /var/tmp/port-name && find * \! -type d) > pkg-plist 新しく生成されたディレクトリはすべてパッキングリストに追加する必要があります. &prompt.root; (cd /var/tmp/port-name && find * -type d) | comm -13 OLD-DIRS - | sed -e 's#^#@dirrm#' >> pkg-plist 最後にパッキングリストを手で整える必要があります; すべてが自動化されているわけではありません. マニュアルはパッキングリストに記述するのではなく, port の Makefile 中の MANn に 記述しなければなりません. ユーザ設定ファイルは削除するか filename.sample としてインストールされなければなりません. また info/dir ファイルはリストに含めず, info ファイルに記述されているように, 適切な install-info 行に追加しなければなりません. port によってインストールされるライブラリは, 共有ライブラリ のセクションで示したように記載されるべきです. package の名前 package の名前は以下のルールにしたがってつけてください. これは package のディレクトリを見やすくするためで, 無秩序な名前がたくさん並んでいるとユーザが使いづらくなるのではという心配からです (FTP サイトなどにはたくさん package がありますからね). package の名前は以下のようにしてください. 言語-名前-オプションバージョン.番号 package 名は ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION} というように定義されています. 変数がこの書式と適合していることを確認してください. FreeBSD はユーザの慣れ親しんだ言語のサポートに力を入れています. 特定の言語のための port の package 名には 言語- に ISO-639 で定義されている言語名の略称を入れてください. たとえば日本語なら ja, ロシア語なら ru, ベトナム語なら vi, 中国語なら zh, 韓国語ならば ko, ドイツ語なら de といった具合です. port がある言語地域に特化したものである場合には, さらに二文字の国名コードを付加してください. たとえば合衆国英語圏は en_US となり, スイスのフランス語圏は fr_CH となります. 言語- 部分は, PKGNAMEPREFIX 変数に 定義されなければなりません. 名前の部分の最初の文字は 小文字でなければなりません. (名前の残りの部分は大文字を含んでいても構わないため, 大文字を含んだソフトウェア名を変換する際の規則は, あなた自身の裁量に任されています.) Perl 5 のモジュールでは先頭に p5- を付け, 二重コロン (::) のセパレータをハイフン (-) に置きかえる習慣になっています. たとえば Data::Dumper は p5-Data-Dumper になります. また, そのソフトウェアの名前として通常使われるものに番号, ハイフン, あるいは下線が入っている場合には, それらを使うことも構いません (kinput2など). コンパイル時に環境変数や make の引数などでハードコードされたデフォルトを変えてコンパイルできる場合, -compiled.specifics にそのコンパイル時のデフォルトを入れてください (ハイフンはあってもなくてもかまいません). 用紙のサイズ, あるいはフォントの解像度などがこれにあたります. compiled.specifics 部分は, PKGNAMESUFFIX 変数に定義されなければなりません. バージョン番号は数字とアルファベットからなり, ピリオド (.) で区切ります. アルファベットは二文字以上続けてはいけません. ただ一つの例外は「パッチレベル」を意味する pl で, それ以外にバージョン番号がまったくついていない場合にのみ使うことができます. もしソフトウェアのバージョンに "alpha", "beta", "rc" や "pre" といった文字列が含まれる場合には, ピリオドの後に最初の一文字をとってください. これらの後に, さらにバージョン文字列が続く場合には, 一文字のアルファベットの後にピリオドをつけずに番号を続けます. この考え方は, バージョン文字列を見て簡単に ports を並べられるようにするためのものです. 特に, バージョン番号の各部分が必ずピリオドで区切られていること, また日付の部分がバージョン文字列の一部となっている場合には yyyy.mm.dd という書式を使っていることを確認してください. dd.mm.yyyy や, 2000 年問題に対応していない yy.mm.dd という書式を使ってはいけません. では, DISTNAMEを正しい PKGNAME に直す例を見てみましょう: 以下は, ソフトウェアの作者が決めた名前から 適切な package 名に変換する方法を示した (実際の) 例です. 配布名 PKGNAMEPREFIX PORTNAME PKGNAMESUFFIX PORTVERSION 理由 mule-2.2.2 (空) mule (空) 2.2.2 変更の必要はありません XFree86-3.3.6 (空) XFree86 (空) 3.3.6 変更の必要はありません EmiClock-1.0.2 (空) emiclock (空) 1.0.2 プログラム一つだけの時は小文字のみ rdist-1.3alpha (空) rdist (空) 1.3.a alpha のような文字列は使えない es-0.9-beta1 (空) es (空) 0.9.b1 alpha のような文字列は使えない mailman-2.0rc3 (空) mailman (空) 2.0.r3 rc のような文字列は使えない v3.3beta021.src (空) tiff (空) 3.3 なんなんでしょう ;) tvtwm (空) tvtwm (空) pl11 バージョン番号は必ず必要 piewm (空) piewm (空) 1.0 同上 xvgr-2.10pl1 (空) xvgr (空) 2.10.1 pl が使えるのは, 他にメジャー/マイナーバージョン番号がない場合のみ gawk-2.15.6 ja- gawk (空) 2.15.6 日本語バージョン psutils-1.13 (空) psutils -letter 1.13 コンパイル時に用紙のサイズを指定 pkfonts (空) pkfonts 300 1.0 300dpiフォント用の package オリジナルのソースにまったくバージョン情報が見当たらず, また原作者が新しいバージョンをリリースする可能性が低いときには, バージョン番号として 1.0 を使えばいいでしょう (上記の piewm の例がこれにあたります). そうでない場合には原作者に聞くか, 日付 (yyyy.mm.dd) を使うなどしてください. カテゴリ すでにご存知のように, ports はいくつかのカテゴリに分類されています. これを有効に利用するためには, port を作成する人々とユーザが, それぞれのカテゴリが何であるか, どのようにしてカテゴリに分類するかを理解する必要があります. 現在のカテゴリのリスト まず, これが現在の port のカテゴリのリストです. アスタリスク(*) が付いているものは仮想 (virtual) カテゴリです — これらには対応するサブディレクトリが port ツリーにはありません. 仮想カテゴリでないものは, そのサブディレクトリ内の pkg/COMMENT に一行の記述があります (例: archivers/pkg/COMMENT). カテゴリ 説明 afterstep* AfterStep ウィンドウマネージャをサポートする ports archivers アーカイブ用ツール astro 天文学関連の ports audio サウンドをサポートする ports benchmarks ベンチマークユーティリティ biology 生物学関連のソフトウェア cad CAD ツール chinese 中国語サポート comms 通信ソフトウェア. ほとんどはシリアルポート用です. converters 文字コード変換 databases データベース deskutils コンピュータが発明される以前に机上で使われていた道具 (訳注: いわゆるデスクトップユーティリティのこと) devel 開発ユーティリティ. どうしてもここに置かなければならない理由があるのでない限り, ライブラリをここに含めないでください. editors 一般的なエディタ. 特殊なエディタはそれぞれふさわしいセクションに入れます (たとえば数式エディタは math です). elisp Emacs-lisp の ports emulators 他のオペレーティングシステムのエミュレータ. 端末エミュレータはここに含まれません — X ベースのものは x11 に, テキストベースのものは機能によって comms か misc に分類されます. french フランス語サポート ftp FTP クライアントとサーバユーティリティ. port が FTP と HTTP の両方をサポートしていれば, ftp に入れ, 第二カテゴリを www とします. games ゲーム german ドイツ語サポート gnome* GNU Object Model Environment (GNOME) プロジェクトの ports graphics グラフィックユーティリティ hebrew ヘブライ語サポート irc インターネットリレーチャット (IRC) 用ユーティリティ ipv6* IPv6 関連のソフトウェア japanese 日本語サポート java Java 言語サポート kde* K Desktop Environment (kde) の ports korean 韓国語サポート lang プログラミング言語 linux* Linux アプリケーションとサポートユーティリティ mail メールソフトウェア math 数値計算ソフトウェアやその他の数学ソフトウェア mbone MBone アプリケーション misc 種々のユーティリティ — 基本的に他のカテゴリに属さないものです. これは他の仮想でないカテゴリを伴わない, 唯一のカテゴリです. misc と他のカテゴリが CATEGORIES 行に書かれている場合, misc を削除して他のサブディレクトリにおいて良いという意味になります. net 種々のネットワークソフトウェア news USENET ニュースソフトウェア offix* OffiX suite の ports palm 3Com Palm(tm) シリーズをサポートするソフトウェア perl5* 実行に perl バージョン 5 を必要とする ports picobsd PicoBSD をサポートするための ports plan9* Plan9 に由来するさまざまなソフトウェア print 印刷ソフトウェア. DTP 用ツール (プレビュアなど) もここに分類されます. python* python 言語で書かれたソフトウェア ruby* ruby 言語で書かれたソフトウェア russian ロシア語サポート science astro や biology, math 等, 他のカテゴリには あてはまらない科学関連の ports security セキュリティ関連のユーティリティ shells コマンドラインシェル sysutils システムユーティリティ tcl75* 実行に Tcl バージョン 7.5 を必要とする ports tcl76* 実行に Tcl バージョン 7.6 を必要とする ports tcl80* 実行に Tcl バージョン 8.0 を必要とする ports tcl81* 実行に Tcl バージョン 8.1 を必要とする ports textproc テキスト処理ユーティリティ. DTP ツールはここではなく, print/ に分類されます. tk41* 実行に Tk バージョン 4.1 を必要とする ports tk42* 実行に Tk バージョン 4.2 を必要とする ports tk80* 実行に Tk バージョン 8.0 を必要とする ports tk81* 実行に Tk バージョン 8.1 を必要とする ports tkstep80* 実行に TkSTEP バージョン 8.0 を必要とする ports ukrainian ウクライナ語サポート vietnamese ベトナム語サポート windowmaker* WindowMaker ウィンドウマネージャをサポートする ports www World Wide Web 関連のソフトウェア. HTML 言語サポートもここに分類されます. x11 X ウィンドウシステムとその関連ソフトウェア. このカテゴリは, 直接ウィンドウシステムをサポートするソフトウェアのみを対象とするものです. 通常の X アプリケーションをここに分類しないでください. あなたの port が X アプリケーションで, USE_XLIB が定義 (USE_IMAKE を定義すると自動的に定義されます) されている場合は, 適切なカテゴリに分類してください. また, それらのほとんどは他の x11-* カテゴリ (下記参照) に分類されます. x11-clocks X11 用時計 x11-fm X11 用ファイルマネージャ x11-fonts X11 フォントとフォントユーティリティ x11-servers X11 サーバ x11-toolkits X11 ツールキット x11-wm X11 ウィンドウマネージャ zope* Zope サポート 適切なカテゴリの選択 多くのカテゴリに重なるので, どれを第一カテゴリにするかを決めなければならないことがたびたびあるでしょう. これをうまく決めるルールがいくつかあります. 以下はその優先順のリストで, 優先度の高いものから低いものの順に書いてあります. 言語特有のカテゴリがまず最初です. たとえば日本語の X11 のフォントをインストールする port の場合, CATEGORIES 行は japanese x11-fonts となるでしょう. より特徴的なカテゴリが, 一般的なカテゴリより優先されます. たとえば, HTML エディタの場合は www editors となります. これを逆順にはしないでください. また, port が irc, mail, mbone, news, security, www のいずれかに属する場合には net は必要ありません. x11 を第二カテゴリにするのは第一カテゴリが自然言語の場合のみにしてください. 特に X のアプリケーションには x11 を指定しないでください. もし, あなたの port が他のどのカテゴリにも属しない場合には misc にしてください. もし, あなたがカテゴリについて自信が持てない場合には, そのことを send-pr する時に書き加えてください. そうすれば import する前にそれについて議論できます (もしあなたがコミッターであれば, そのことを &a.ports; に送って先に議論するようにしてください — 新しい port が間違ったカテゴリに import されて, すぐ移動されることが多いので). この文書と ports システムの変更 もしあなたが, たくさんの ports の保守をしているのであれば, &a.ports; メーリングリストの内容を読むことを考えてください. ports のしくみについての重要な変更点はここに アナウンスされます. 最新の変更点については, いつでも, bsd.port.mk の CVS ログで詳細な情報を得ることができます. やっとおしまい! いやはや, 長い文章ですみません. ここまで読んでくださった方には感謝, 感謝でございます. さあ, port の作り方がわかったところで世界中のソフトウェアを port 化しましょう. FreeBSD プロジェクトに貢献するには, それが最も簡単な方法です! :-) diff --git a/ja_JP.eucJP/books/ppp-primer/book.sgml b/ja_JP.eucJP/books/ppp-primer/book.sgml index 03ac24d245..10a14ca888 100644 --- a/ja_JP.eucJP/books/ppp-primer/book.sgml +++ b/ja_JP.eucJP/books/ppp-primer/book.sgml @@ -1,2376 +1,2376 @@ -%man; + +%books.ent; ]> PPP - Pedantic PPP Primer Steve Sims
SimsS@IBM.net
 $FreeBSD$ これは FreeBSD システムをローカル環境のダイアルアップルータ / ゲートウェイとしてセットアップするためのステップアップガイドです. 内容は, 特に指定のない限り FreeBSD 2.2 以降のバージョンを想定しています. 概要: FreeBSD 2.2 におけるユーザモード PPP ("IIJ-PPP" としても知られています) は, 現在ダイアルアップインターネット環境における Packet Aliasing をサポートしています. この機能は, "Masquerading", "IP Aliasing", そして "Network Address Translation" としても 知られており, この機能を生かせば FreeBSD システムをイーサネットを基盤とした ローカルエリアネットワーク (LAN) とインターネットサービスプロバイダ間の ダイアルオンデマンドルータとして活用することができます. LAN 上のシステムは FreeBSD システムを経由することにより, 単一のダイアルアップ接続を通してインターネットと情報を交換することが できるのです. このガイドは FreeBSD システムをダイアルアウト接続できるように設定し, ダイアルアウト接続をネットワーク上の他のシステムと共用し, Windows システムが FreeBSD システムをインターネットへの ゲートウェイとして用いる のための方法を説明しています. このガイドは IP Aliasing の設定を助けることに重点を置いたものですが, 個々の構成要素をインストールし設定する時に必要となる具体例も含まれていますから, どの章をとっても, FreeBSD でネットワークに関する様々な設定を行うときの 助けになるでしょう. ローカルエリアネットワーク (LAN) をつくる ppp は通常 一台の ローカルな FreeBSD マシンに サービスを提供するために設定されていますが, LAN に接続された資源とインターネット, またはその他のダイアルアップサービス間の「ゲートウェイ」(または「ルータ」)として 使用することもできます. 典型的なネットワークトポロジ このガイドでは, 典型的なローカルエリアネットワークでは, 次のような接続を行っていると想定しています. +---------+ ----> ダイアルアップインターネット接続 | FreeBSD | \ (例: So-net, Infoweb, RIMNET, 等) | |-------- | "Curly" | | | +----+----+ | |----+-------------+-------------+----| <-- イーサネットネットワーク | | | | | | +----+----+ +----+----+ +----+----+ | | | | | | | Win95 | | WFW | | WinNT | | "Larry" | | "Moe" | | "Shemp" | | | | | | | +---------+ +---------+ +---------+ ローカルエリアネットワークに関する想定 このガイド中のネットワークでは, 次のようなことを想定しています. 三台のワークステーションとサーバはイーサネットでつながっています. FreeBSD サーバ ("Curly") は 'ed0' として設定された NE-2000 アダプタを使用しています. Windows-95 ワークステーション ("Larry") は Microsoft 「ネイティブ」な 32 ビット TCP/IP ドライバを使用しています. Windows for Wrokgroups ワークステーション ("Moe") は Microsoft の 16 ビット TCP/IP エクステンションを使用しています. Windows NT ワークステーション ("Shemp") は Microsoft 「ネイティブ」な 32 ビット TCP/IP ドライバを使用しています. イーサネットで結ばれた LAN 内部での IP アドレスは, RFC-1597 で提案された「予約」アドレスの中から選ばれています. 具体的には以下の通り. 名前 IP Address 備考 Curly 192.168.1.1 FreeBSD マシン Larry 192.168.1.2 Win95 マシン Moe 192.168.1.3 WfW マシン Shemp 192.168.1.4 Windows NT マシン このガイドではモデムは FreeBSD マシンの一番目のシリアルポート ('/dev/cuaa0' DOS 用語では 'COM1:') に接続されているものとします. 最後に, インターネットサービスプロバイダ (ISP) は PPP/FreeBSD サイドと ISP サイドの両方に自動的に IP アドレスを割り当てるものとします. (つまり, リンクの両端で動的 IP アドレス割り当てが行われます.) PPP のダイアルアウトの設定の詳細については, 第 2 章 「FreeBSD システムの設定」で扱います. FreeBSD システムの設定 ローカルエリアネットワーク (LAN) の統合を進める前に FreeBSD マシンについて基本的な情報を三つ知っておく必要があります. FreeBSD システムのホスト名 (ガイドの例の中では "Curly"), ネットワークの設定, /etc/hosts ファイル. (ネットワーク内の 他のシステムの名前を IP アドレスをリストにしたもの) FreeBSD システムをネットワークインストールした場合, これらの幾つかはすでに設定されている場合があります. インストール時に FreeBSD システムの設定を正しく行った自信がある場合でも, 後のステップでつまずかないよう, もう一度見直しておくと良いでしょう. FreeBSD のホスト名の確認 FreeBSD システムのインストール時に, マシンのホスト名が指定, 保存されている場合があります. 確認のため, 以下のコマンドをプロンプトから入力してください. # hostname FreeBSD システムのホスト名が表示されたはずです. もしホスト名が正しければ (すぐわかるでしょ :-), まで進んでください. 例えば, ガイド中のネットワークでは, インストール中 / 後にホスト名を正しく設定していれば, 'hostname` コマンドは 'curly.my.domain' を返します. (ここでは ".my.domain" の部分はあまり気にしないでください. それは後で片付けます. ここで大事なのは最初のドットまでの部分です.) FreeBSD のインストール時にホスト名を設定していない場合, たぶん 'myname.my.domain` という答が返ってくるはずです. /etc/rc.conf を編集し, マシンに名前をつけてください. FreeBSD のホスト名を設定する 念のため: システム設定ファイルを編集するためには 'root' でログインする必要があります! 警告: システム設定ファイルにおかしな変更を 加えた場合, システムが正常に **起動しない** 可能性があります! くれぐれもご注意を! ブート時に FreeBSD システムのホスト名を決定している設定ファイルは /etc/rc.conf です. デフォルトのテキストエディタ ('ee') を使ってこのファイルを編集しましょう. ユーザ 'root' でログインし, 以下のコマンドを入力して /etc/rc.conf をエディタに読み込みましょう. # ee /etc/rc.conf 矢印キーや scroll down を使って, FreeBSD システムのホスト名を 記述した部分を見つけましょう. デフォルトではこうなっているはずです. --- ### Basic network options: ### hostname="myname.my.domain" # Set this! --- これを次のように変えましょう.(あなたの環境に合わせてください) --- ### Basic network options: ### hostname="curly.my.domain" # Set this! --- ホスト名を変更したら, 'Esc' キーを押してコマンドメニューを呼び出して下さい. "leave editor" を選択し, 確認を求めてきたら "save changes" を選びましょう. イーサネットインタフェイスの設定の確認 もう一度確認ですが, このガイドでは FreeBSD システムのイーサネットインタフェイスとして 'ed0' が用いられていると想定しています. これは NE-1000, NE-2000, WD/SMC models 8003, 8013 と Elite Ultra (8216) ネットワークアダプタがデフォルトで使用するものです. これ以外のネットワークアダプタは FreeBSD では異なったデバイス名で参照されます. FAQ をチェックして, ネットワークアダプタの記述を探してください. アダプタのデバイス名が分からない場合は, FreeBSD FAQ を読んで, 使用中のカードのデバイス名を確かめ, 以下のステップで登場するデバイス名をその名前 (例えば 'de0', 'zp0' など) に読み替えてください. ホスト名と同様, イーサネットインタフェイスも FreeBSD システムのインストール時に設定されている場合があります. FreeBSD システムの (イーサネットその他の) インタフェイスに関する設定を表示するために, 以下のコマンドを入力してください. # ifconfig -a (フツーの言葉に直すと, 「うちのネットワークデバイスの InterFace CONFIGuration を見せて」って意味です) 例えば... # ifconfig -a ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255 ether 01:02:03:04:05:06 lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 tun0: flags=8050<POINTOPOINT,RUNNING, MULTICAST> mtu 1500 sl0: flags=c010<POINTOPOINT,LINK2,MULTICAST> mtu 552 ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 inet 127.0.0.1 netmask 0xff000000 # _ この例では, 以下のデバイスが表示されました. ed0: イーサネットインタフェイス lp0: パラレルポートインタフェイス (このガイドでは触れません) tun0: 「トンネル」デバイス ユーザモード ppp が使うやつです! sl0: SL/IP デバイス (このガイドでは触れません) ppp0: もう一つの PPP デバイス (カーネル ppp 用. このガイドでは触れません) lo0: 「ループバック」デバイス (このガイドでは触れません) この例では, 'ed0' デバイスは「上がって」動作しています. 以下の表示がキーになります. このデバイスのステータスは "UP" で, インターネット ("inet") アドレス (この例では 192.168.1.1) を持ち, 有効なサブネットマスク ("netmask" 0xffffff00 は 255.255.255.0 に等しい) を持ち, 有効なブロードキャストアドレス (この例では 192.168.1.255) を持っている. もしイーサネットカードに関する表示がこんな感じだったら, ed0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 ether 01:02:03:04:05:06 イーサネットカードはまだ設定されていません. イーサネットインタフェイスの設定が正しく行われているなら, まで進んでください. イーサネットインタフェイスの設定 年のため: システム設定ファイルを編集するためには 'root' でログインする必要があります! 警告: システム設定ファイルにおかしな変更を 加えた場合, システムが正常に **起動しない** 可能性があります! くれぐれもご注意を! ブート時に FreeBSD システムのネットワークインタフェイスの設定を決定している設定ファイルは /etc/rc.conf です. デフォルトのテキストエディタ ('ee') を使ってこのファイルを編集しましょう. ユーザ 'root' でログインし, 以下のコマンドを入力して /etc/rc.conf をエディタに読み込みましょう. # ee /etc/rc.conf /etc/rc.conf の先頭から 20 行ほどの所に, システムのブート時にアクティブにするネットワークインタフェイスを記述する節があります. デフォルトの設定ファイルでは, 当該行は次のようになっています. network_interfaces="lo0" # List of network interfaces (lo0 is loopback). FreeBSD に 'ed0' という名前の 別のデバイスを加えることを伝えるには, この行を修正する必要があります. この行を次のように変えてください. network_interfaces="lo0 ed0" # List of network interfaces (lo0 is loopback). (ループバックデバイス ("lo0") と イーサネットデバイス ("ed0") の定義の間に スペースを入れるのを忘れないでください!) 念のため: イーサネットカードの名前が 'ed0' でない場合, きちんとその正しいデバイス名を指定してください FreeBSD をネットワークインストールした場合, 'network_interfaces=' の行がすでにイーサネットアダプタを参照している場合があります. その場合, それが正しいデバイス名かどうかを確認してください. 次に, イーサネットデバイス ('ed0') インタフェイスの設定を行いましょう. アクティブにするインタフェイスの指定行の下に, 各インタフェイスに対する実際の設定を記述する行があります. /etc/rc.conf のデフォルトでは, この一行があるだけです. ifconfig_lo0="inet 127.0.0.1" # default loopback device configuration. この下に 'ed0' デバイスの 設定を記述する行を加えましょう. FreeBSD をネットワークインストールした場合, 'ifconfig_ed0=' の行がループバックデバイスの定義の下に存在する場合があります. その場合, 記述された値が正しいものであるかどうか確認してください. このガイドでは, ループバックデバイスの定義のすぐ次の行に次の一文を加えることにします. ifconfig_ed0="inet 192.168.1.1 netmask 255.255.255.0" /etc/rc.conf の編集が終わったとき, ネットワークインタフェイスの記述と設定を行う行は, だいたいこんな感じになっているはずです. --- network_interfaces="ed1 lo0" # List of network interfaces (lo0 is loopback). ifconfig_lo0="inet 127.0.0.1" # default loopback device configuration. ifconfig_ed1="inet 192.168.1.1 netmask 255.255.255.0" --- /etc/rc.conf の編集が終わったら, 'Esc' キーを押してコントロールメニューを呼び出して下さい. "leave editor" を選択し, 確認を求めてきたら "save changes" を選びましょう. パケットフォワーディングの有効化 デフォルトでは, FreeBSD システムは様々なネットワークインタフェイス間で IP パケットのフォワードを行いません. 言い換えると, ルーティングの機能 (ゲートウェイの機能とも言えます) は無効にされています. FreeBSD システムただ一台をインターネット用のワークステーションとして使用し, LAN ノードと ISP 間とのゲートウェイとして使用しない場合は, まで進みましょう. PPP プログラムを使用してローカルの FreeBSD マシンを LAN のワークステーション (つまりルータ) としても機能させる場合は, IP フォワーディングを有効にする必要があります. IP パケットのフォワーディングを有効にするためには /etc/rc.conf を編集する必要があります. このファイルは /etc/defaults/rc.conf によるデフォルト値を上書きします. デフォルトゲートウェイの設定はそのファイルの 以下の行で行われています. gateway_enable="NO" 上書きするには, 以下の様な行を gateway_enable="YES" /etc/rc.conf に追加します. 注意: FreeBSD システムのインストール時に IP フォワーディングが有効になっていた場合, すでに 'gateway_enable=YES' という設定が行われている場合があります. 他の LAN ホストのリスト (<filename>/etc/hosts</filename>) をつくる FreeBSD システムの LAN に関する設定の最後のステップは, ローカルエリアネットワーク (LAN) に接続された様々なシステムのホスト名と TCP/IP アドレスのリストをつくることです. このリストは '/etc/hosts' の中に記述されます. デフォルトの状態では, このファイルにはホスト名が一つしか含まれていません. ループバックデバイス ('lo0') のホスト名とアドレスです. ネットワークに関する約束事にしたがって, このデバイス名はいつも "localhost" と名付けられ, 127.0.0.1 という IP アドレスを持つことになっています . /etc/hosts を編集するために, 以下のコマンドを入力してください. # ee /etc/hosts ファイルの終りまで一気に移動して, (途中のコメントも気をつけて見ておきましょう. 有益な情報がいくつか書いてありますよ!) LAN 上のホストの IP アドレスとホスト名を入力してください. ガイド中のネットワークでは次のようになります. 192.168.1.1 curly curly.my.domain # FreeBSD システム 192.168.1.2 larry larry.my.domain # Windows '95 システム 192.168.1.3 moe moe.my.domain # Windows for Workgroups システム 192.168.1.4 shemp shemp.my.domain # Windows NT システム ('127.0.0.1 localhost' のエントリが書かれた行は変更する必要はありません.) 入力を終えたら, 'Esc' キーを押してコントロールメニューを呼び出してください. "leave editor" を選択し, 確認を求めてきたら "save changes" を選びましょう. FreeBSD システムのテスト おめでとう! これで FreeBSD システムはネットワークに接続された UNIX システムとして設定されました. /etc/rc.conf を変更した場合, ここで FreeBSD システムをリブートしてください. これには二つの大きな目的があります. インタフェイスの設定に加えた変更を反映させ, システムが設定エラーを報告せずに再起動することを確かめるためです. システムのリブートが完了したら, ネットワークインタフェイスのテストを行ってください. ループバックデバイスの動作点検 ループバックデバイスが正しく設定されているかどうか確かめるために, 'root' でログインしてこう入力してください. # ping localhost こういうメッセージが見えるはずです. # ping localhost PING localhost.my.domain. (127.0.0.1): 56 data bytes 64 bytes from 127.0.0.1: icmp_seq=0 ttl=255 time=0.219 ms 64 bytes from 127.0.0.1: icmp_seq=1 ttl=255 time=0.287 ms 64 bytes from 127.0.0.1: icmp_seq=2 ttl=255 time=0.214 m [...] このメッセージは Ctrl-C を押すまで延々流れ続けます. イーサネットデバイスの動作点検 イーサネットデバイスが正しく設定されているかどうか確かめるために, こう入力してください. # ping curly こういうメッセージが見えるはずです. # ping curly PING curly.my.domain. (192.168.1.1): 56 data bytes 64 bytes from 192.168.1.1: icmp_seq=0 ttl=255 time=0.219 ms 64 bytes from 192.168.1.1: icmp_seq=1 ttl=255 time=0.200 ms 64 bytes from 192.168.1.1: icmp_seq=2 ttl=255 time=0.187 ms [...] この二つの例で大事なのは, ホスト名 (loopback と curly) が正しく IP アドレス (127.0.0.1 と 192.168.1.1) に関連づけられているのを確認することです. これで /etc/hosts ファイルの内容が正しいかどうか確認できます. もし "curly" の IP アドレスが 192.168.1.1 ではない, あるいは "localhost" のアドレスが 127.0.0.1 ではない場合, まで戻って /etc/hosts の内容を見直してください. ping コマンドの出力でホスト名とアドレスは正しく対応づけられているが, 何か他のエラーが表示されるなら, インタフェイスの設定がうまく行っていないのでしょう. まで戻って最初から確認し直してください. チェックが全部終わったら, つぎの章に進んでください. PPP のダイアルアウト接続の設定 ppp ドライバには, 基本的には "Interactive" と "Automatic" という二つの動作モードがあります. Interactive モードでは, 手動で ISP に接続を確立し, ネットサーフィンを楽しんだり, ファイルやメールを転送したりのなにやかやの後で, 手動で ISP との接続を切断することになります. Automatic モードでは, PPP プログラムは FreeBSD システムが内部的にどういう処理を行っているかじっと観察していて, 必要に応じて自動的に ISP と接続, 切断し, あたかもネットワークがインターネットに直接接続されているかのように振る舞います. この章ではこの二つのモードのうち, `ppp` 環境を "Automatic" モードで動作させる設定に重点を置いて説明します. オリジナルの PPP 設定ファイルをバックアップする FreeBSD の最近のバージョンではサンプルファイルが /usr/share/examples/ppp にありますので この段階は不要です. PPP 用のファイルに何か変更を加える前に, FreeBSD システムのインストール時につくられたデフォルトのファイルのコピーを取っておきましょう. 'root' でログインして, 次の手順を踏んでください. '/etc' ディレクトリに移ります. # cd /etc 'ppp' ディレクトリ内のオリジナルのファイルのバックアップをつくります. # cp -R ppp ppp.ORIGINAL これで '/etc' ディレクトリの下に 'ppp' と 'ppp.ORIGINAL' という二つのサブディレクトリができました. お手製の PPP 設定ファイルをつくる FreeBSD のインストール中に, たくさんの設定ファイルのサンプルが /usr/share/examples/ppp ディレクトリの中につくられます. 少し時間を取ってファイルの内容を眺めてみてください. これらのサンプルは実際の稼働例に基づいたもので, PPP プログラムの機能や特長がよくあらわれています. これらのサンプルファイルを参考にし, 必要に応じて実際の設定に生かすことを強くお勧めします. `ppp` プログラムに関する詳細な情報がほしいなら, ppp の man を 読んでください. # man ppp PPP ダイアラで使われている `chat` スクリプト言語に関する詳細な情報がほしいなら, chat の man を読んでください. # man chat この章の残りの部分は PPP 関連のファイルのお勧め設定です. '<filename>/etc/ppp/ppp.conf</filename>' ファイル '/etc/ppp/ppp.conf' ファイルにはダイアルアウト PPP 接続に必要な設定と情報が含まれています. このファイルには複数の接続の設定が含まれていてもかまいません. FreeBSD ハンドブック (XXX URL? XXX) には, このファイルの内容と文法に関する詳しい記述があります. この章では, ダイアルアウト接続を行うための必要最小限の設定についてのみ説明します. 下の /etc/ppp/ppp.conf ファイルは, ガイド中の LAN において, ダイアルアウトインターネットゲートウェイの機能を提供するのに十分なものです. ppp.confの文法の完全なものは&man.ppp.8;に記述されています. 特に, コロンで終了しない行 (例えばdefault:やinteractive:), !で始まるコマンド (例えば!include) はラベルではないことに注意してください. また, コメントはインデントされなければいけないにも注意してください! ################################################################ # PPP 設定ファイル ('/etc/ppp/ppp.conf') # # デフォルト設定; PPP が発動した時常に実行され, 全ての # システム設定に適用される. ################################################################ default: set device /dev/cuaa0 set speed 57600 disable pred1 deny pred1 disable lqr deny lqr set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" set redial 3 10 # # ################################################################ # # interactive モード用の設定: # # `ppp -alias interactive` で発動せよ. # ################################################################ interactive: set authname _リモートシステムでのユーザ ID_ set authkey _リモートシステムでのパスワード_ set phone 1-800-123-4567 set timeout 300 set openmode active accept chap # ################################################################ # # demand-dial (automatic) モードではこの設定が使われる: # # 'ppp -auto -alias demand' で発動せよ. # ################################################################ demand: set authname _リモートシステムでのユーザ ID_ set authkey _リモートシステムでのパスワード_ set phone 1-800-123-4567 set timeout 300 set openmode active accept chap set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 add 0 0 127.2.2.2 ################################################################ # /etc/ppp/ppp.conf はこれでおしまい このファイル - 実際のシステムから持ってきたものですが - には, 設定に関連する三つのセクションがあります. "<emphasis remap=tt>default</emphasis>" セクション 'default:' セクションには, このファイルの他のどのセクションからも参照される値と設定がおさめられています. このセクションの内容が, 暗黙の内に他のセクションの設定に書き加えられるものと考えておけば良いでしょう. ここは全てのダイアルアップセッションにおいて共通な 「グローバルなデフォルト設定」を置いておくのに丁度良い場所です. 例えばモデムの設定やダイアルの前準備等の, 通常接続先のシステムに応じて変更する必要のない設定を置くのに特に適しています. サンプルとして挙げた '/etc/ppp/ppp.conf' ファイルの "default" セクションを一行づつ見ていきましょう. set device /dev/cuaa0 この文は PPP プログラムに一番目のシリアルポートを使用するよう通知しています. FreeBSD 下における '/dev/cuaa0' デバイスとは, DOS, Windows, Windows 95 なんかで言うところの "COM1:" と同じポートのことです. モデムが COM2: につながれている場合は, '/dev/cuaa1' を指定してください. COM3: の場合は '/dev/cuaa2' です. set speed 57600 この文はシリアルポートとモデム間での送信 / 受信速度を設定しています. この例で使用されているのは 28.8k のモデムですが, 値を 57600 に設定しておけば, 最近のモデムに組み込みのデータ圧縮機能のおかげでスループットが上がり, シリアルリンク間でより高い転送速度を得ることができます. モデムとの通信に問題がある場合, この設定を 38400, あるいは 19200 まで下げてみてください. disable pred1 deny pred1 この二行は PPP プログラムの "CCP/Predictor type 1" 圧縮機能を無効にしています. 現在のバージョンの `ppp` は draft Internet standards に従ったデータ圧縮法をサポートしていますが, 残念なことに, 多くの ISP では, この機能をサポートしていない機器が使用されています. どちらにせよ多くのモデムは実行時に圧縮を行っていますから, FreeBSD 側でこの機能を無効にし, リモート側がこの機能を要求してきた場合に拒否しても, 大してパフォーマンスは落ちないでしょう. disable lqr deny lqr この二行は Point-to-Point protocol (PPP) の完全な仕様の一部である "Line Quality Reporting" (回線品質報告) 機能を制御しています. (詳細は RFC-1989 を参照してください.) 一行目 "disable lqr" は回線の品質状態をリモートエンドのデバイスへ報告しないよう, PPP プログラムに命じています. 二行目, "deny lqr" はリモートエンドからの回線品質報告要求を拒否するよう, PPP プログラムに命じています. 最近のダイアルアップ用のモデムには大抵自動エラー検出 / 訂正機能がついていますし, LQR 報告機能は多くのベンダの製品で完全には実装されていませんから, 通常はこの二行をデフォルト設定に加えておいても大丈夫でしょう. set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \"\" ATE1Q0M0 OK-AT-OK\\dATDT\\T TIMEOUT 40 CONNECT" 注意: (このドキュメントでは改行が入っているように見えるかもしれませんが, 実際にはこの文の途中で改行を入れないでください.) この行は PPP プログラムにモデムのダイアル法と, 以下のようなダイアル時の基本的なガイドラインを指定しています. モデムが "BUSY" リザルトコードを返した場合, ダイアル試行は失敗したものとし, モデムが "NO CARRIER" リザルトコードを返した場合もダイアル試行は失敗したものとし, PPP プログラムは以下のイベント各々が 5 秒間のタイムアウト期間内に終了するものと想定する. 初期状態では, PPP プログラムはモデムに対して何も想定していない (上の例の \"\" の部分で指定されている) プログラムはモデムにモデム初期化文字列 "ATE1Q0M0" を送り, "OK" という返事が返ってくるのを待つ. レスポンスが帰ってこない場合, プログラムはモデムに attention コマンド ("AT") を送り, 再び "OK" という返事が返ってくるのを待つ. プログラムは一秒間待ち時間を入れ ("\\d" の部分で指定されている), モデムにダイアリング文字列を送る. "ATDT" はトーンダイアリングを用いてダイアルを行う場合の標準モデムコマンドであり, 回線がトーンダイアルではない場合, "ATDT" を "ATDP" と置換する必要がある. "\\T" 文字列は実際の電話番号が入る場所である ("set dial 123-4567" で指定された値が自動的に挿入される). 最後に, (最大) 40 秒のタイムアウトの前に, PPP プログラムはモデムが "CONNECT" リザルトコードを返すと想定している. この対話におけるいかなる時点での失敗もダイアリングの失敗と解釈され, PPP プログラムは接続に失敗します. (PPP ダイアラで使用されているミニスクリプト言語の詳細については "chat" の man を参照してください.) set redial 3 10 この行はダイアル接続を直ちに確立することができなかった場合, リダイアルまで 10 秒の間隔を挟んで (必要な場合は 3 回まで) 再試行するよう, PPP プログラムに指定しています. "<emphasis remap=tt>interactive</emphasis>" セクション 'interactive:' セクションには, 特定のリモートシステムと「対話的 (interactive)」に PPP セッションを確立するときに使用される値と設定がおさめられています. このセクションの設定には, "default" セクションの内容が自動的に追加されます. このガイド中の "interactive" セクションの例では, 接続先のリモートシステムは, 何らかの風変わりなスクリプト言語を使用しないでもユーザ認証を行うことができるものと想定しています. つまり, このサンプルでは接続を確立するために CHAP プロトコルを使用します. おおざっぱに言うと, もし Windows95 のダイアラの「接続」ボタンを押しただけで接続が確立できる環境なら, このサンプルはうまく働きます. 一方, もし Microsoft Windows95 のダイアルアップネットワーク機能を利用して ISP に接続するとき, Microsoft Plus! の「ダイアルアップスクリプトツール」に頼るか, Windows 95 の接続オプションで「ダイアル後にターミナルウィンドウを表示する」を選択しなければならない場合, ISP と接続を行うためには, PPP 設定ファイルのサンプルや ppp の man で "expect / response" スクリプトの例を参考にする必要があるでしょう. "set login" コマンドはそのような目的に使用できます. まあ、それよりも PAP / CHAP 認証を提供している ISP を探した方が良いかもしれませんけどね! この設定例は, 以下のプロパイダと接続するために使えることが分かっています. Various Shiva LanRovers The IBM Network (http://www.ibm.net/) AT&T WorldNet (http://att.com/worldnet/) Erol's (http://www.erols.com/) サンプルとして挙げた '/etc/ppp/ppp.conf' ファイルの "interactive" セクションを一行づつ見ていきましょう. set authname _リモートシステムでのユーザ ID_ リモートシステムでログイン時に使用する名前を指定します. set authkey _リモートシステムでのパスワード_ リモートシステムで使用するパスワードです. set phone 1-800-123-4567 リモートシステムの電話番号です. PBX (Private Branch eXchange, 構内交換機) の内部にいる場合は, 9, を番号の前に加えることができます. set timeout 300 300 秒 (5 分) 間データが流れなかった場合, 自動的に回線を切断するよう PPP プログラムに命じています. この値は必要に応じて変更することができます. set openmode active モデムが接続したらすぐに交渉を試みるよう PPP プログラムに命じています. 自動的にこれを行うリモートサイトもありますが, 自分からは行わないサイトもあります. このオプションを使えば, リンクのこちら側でイニシアチブを取って接続確立を試みることができます. accept chap ユーザ認証に "Challenge-Handshake Authentication Protocol" を用いるよう PPP プログラムに命じています. ローカル側とリモート側でユーザ ID とパスワードとしてやり取りされる値は, 上の 'authname' と 'authkey' のエントリからとられます. "<emphasis remap=tt>demand</emphasis>" セクション 特定のリモートサイトと「ダイアル・オン・デマンド」な PPP セッションを確立するときに使用される値と設定がおさめられています. このセクションの設定にも, "default" セクションの内容が自動的に追加されます. 最後の二行を除いて, このセクションの設定は "interactive" モードの設定で用いられているのと全く同じものです. 前の方でも述べているように, このガイド中にあらわれる "demand" セクションの例では, 接続先のリモートシステムは CHAP プロトコルを利用した接続確立法を理解できるものと想定しています. サンプルとして挙げた '/etc/ppp/ppp.conf' ファイルの "demand" セクションを一行づつ見ていきましょう. set authname _リモートシステムでのユーザ ID_ リモートシステムでログイン時に使用する名前を指定します. set authkey _リモートシステムでのパスワード_ リモートシステムで使用するパスワードです. set phone 1-800-123-4567 リモートシステムの電話番号です. set timeout 300 300 秒 (5 分) 間データが流れなかった場合, 自動的に回線を切断するよう PPP プログラムに命じています. この値は必要に応じて変更することができます. set openmode active モデムが接続したらすぐにネゴジェーションを試みるよう PPP プログラムに命じています. 自動的にこれを行うリモートサイトもありますが, 自分からは行わないサイトもあります. このオプションを使えば, リンクのこちら側でイニシアチブを取って接続確立を試みることができます. accept chap ユーザ認証に "Challenge-Handshake Authentication Protocol" を用いるよう PPP プログラムに命じています. ローカル側とリモート側でユーザ ID とパスワードとしてやり取りされる値は, 上の 'authname' と 'authkey' のエントリからとられます. set ifaddr 127.1.1.1/0 127.2.2.2/0 255.255.255.0 PPP リンクのローカル側とリモート側の「偽の」 IP アドレスのペアを設定し, ローカル側の 'tun0' (トンネル) デバイス に 127.1.1.1 の, リモート側には 127.2.2.2 の IP アドレスを生成するように PPP プログラムに命じています. 両方のアドレスに '/0' をつけておけば, それらのアドレスの先頭から 0 ビットまでが重要な部分で, 残りの部分はリンクが確立されたときに, ローカル側とリモート側のシステムの交渉によって変更してもよい (というか, この場合は必ず変更されなければならない) と PPP プログラムに教えることができます. 255.255.255.0 という文字列は, それらの仮想デバイス間に適用されるサブネットマスク値を PPP プログラムに教えています. 注意. この例では ISP がリンクの両端に対して IP アドレスを動的に提供するものと想定しています! もし ISP からローカル側で使用すべき具体的な IP アドレスの割り当てを受けている場合, 127.1.1.1 の代わりにその IP アドレスを入力してください. 逆に, ISP がリモート側で使用する具体的な IP アドレスを指定している場合, 127.2.2.2 の代わりにその IP アドレスを入力してください. これらの場合においても, 各アドレスの後ろの '/0' を残しておくのが良い考えでしょう. もしそれらのアドレスが実際に変更された場合でも, PPP プログラムはその変更に対応することができるからです. add 0 0 127.2.2.2 最後の行では, ISP システムの (偽の) IP アドレスを指す IP トラフィックのデフォルトルートを追加するよう, PPP プログラムに命じています. 注意: 前の行で 127.2.2.2 の代わりに ISP に指定されたアドレスを用いている場合, ここでも 127.2.2.2 の代わりにその番号を使用してください. この「偽」の IP トラフィックルートを追加しておけば, アイドル中の PPP プログラムは以下の動作を自動的に行うことができます. ISP と「自動的に」 接続を確立し, リンクのローカル側とリモート側の IP アドレスを再設定し, ローカルのマシンと ISP 間でパケットを転送する. "default" セクションの timeout の値に指定された秒間 TCP/IP のトラフィックが流れなかった場合, PPP プログラムは自動的にダイアルアップ接続を切断し, 始めの状態に戻ります. '<filename>/etc/ppp/ppp.linkup</filename>' ファイル PPP の設定を完全にするために必要なもう一つのファイルが '/etc/ppp/ppp.linkup' です. このファイルにはダイアルアップリンクが確立した後に, PPP プログラムが実行すべき命令が含まれています. ダイアルアップ接続の場合, PPP プログラムはリモート側の偽の IP アドレス (前の章の例では 127.2.2.2) に対して生成されたデフォルトルートを削除し, (ダイアルアップ接続の確立中にわかる) 実際のリモートエンドの IP アドレスを指す新しいデフォルトルートをインストールする必要があります. 典型的な '/etc/ppp/ppp.linkup' ファイル: #########################################################################= # PPP Link Up File ('/etc/ppp/ppp.linkup') # # このファイルは PPP がネットワーク接続を確立した後でチェックされます. # # このファイルは以下の順序で検索されます. # # 1) まず, ローカル側に割り当てられた IP アドレスが検索され, # 関連するコマンドが実行されます. # # 2) IP アドレスが見つからない場合, PPP の起動時に指定されたラベル名が # 検索され, 関連するコマンドが実行されます. # # 3) いずれの場合にも当てはまらない場合, 'MYADDR:' ラベルの下の # コマンドが実行されます. # #########################################################################= # # このセクションは /etc/ppp/ppp.conf 内の "demand" の設定で # 使用される. demand: delete ALL add 0 0 HISADDR # # /etc/ppp/ppp.conf 中の他の全ての設定ではこちらを用いる # MYADDR: add 0 0 HISADDR ######################################################################## # End of /etc/ppp/ppp.linkup '/etc/ppp/ppp.conf' で使用されているのと全く同じ "demand:" というタグのセクションがあることに注意して下さい. このセクションでは, "demand" の設定を用いてリンクが確立された場合, PPP プログラムが生成した全ての IP ルーティング情報を削除し, リモートエンドの実際のアドレスをデフォルトルートに追加する よう, PPP プログラムに命じています. '/etc/ppp/ppp.conf' 内で 'set ifaddr' や 'add 0 0' を使用している設定 (つまり, ダイアルオンデマンドの設定) においては, /etc/ppp/ppp.linkup 内で "delete ALL" や "add 0 0 HISADDR" コマンドを実行することが重要になります. これこそがリンクのオンデマンド設定を制御するメカニズムだからです. /etc/ppp/ppp.linkup 内で明示的に名前を指定されていない設定は, "MYADDR:" セクションにあるコマンドを (それが何であれ) 実行します. 非デマンドダイアルの設定 (例えばサンプルの "interactive:") はこれに該当します. このセクションでは, ISP (リモートエンド) の IP アドレスをデフォルトルートに追加しているだけです. IP Aliasing 今までのステップは, ISP にダイアルアップで接続しようとしているどのような FreeBSD システムにとっても共通のものです. もしこのガイドを読む目的が FreeBSD とインターネットをダイアルアウト ppp で接続することだけである場合, まで進んでください. PPP プログラムをオンデマンドモードで動かす非常に大きな利点の一つは, プログラムがローカルエリアネットワーク (LAN) 上の他のシステム間の IP トラフィックを自動的にルーティングできる点にあります. この機能は "IP Aliasing", "Network Address Translation", "Address Masquerading" または "Transparent Proxying" などの様々な名前で知られています. しかしながら, どのような呼び名が使用されるにせよ, このモードは自動的に得られるものではありません. PPP プログラムをごく普通に起動した場合, プログラムは LAN のインタフェイスとダイアルアウト接続間でパケットを転送しません. 要するに, FreeBSD システムだけが ISP に接続され, 他のワークステーションはその接続を「共用」することができないのです. プログラムが以下のコマンドのいずれかで起動されたとしましょう. # ppp interactive (Interactive mode) または # ppp -auto demand (Dial-on-Demand mode) すると, システムは FreeBSD マシンに対してのみ, インターネットに接続されたワークステーションとしての機能を提供するでしょう. PPP プログラムを LAN の資源とインターネット間のゲートウェイとして起動するには, 代わりに以下のコマンドのいずれかを使用してください. # ppp -alias interactive (Interactive mode) または # ppp -auto -alias demand (Dial-on-Demand mode) また, ``alias enable yes'' というコマンドを ppp の設定ファイルにいれておく方法をとることもできます (詳細については man をご覧ください). に進んでも, このことは忘れないでおいてください. Windows システムの設定 第 1 章で説明したように, ガイド中のネットワークはローカルエリアネットワーク (LAN) 間のゲートウェイ (ルータ) として FreeBSD システム ("Curly") を使用しています. LAN 自体は二系統の Windows ワークステーションで構成されていますが, LAN のノードが Curly をルータとして使用するには, 各ノードが適切に設定される必要があります. このセクションは Windows ワークステーションのダイアルアップネットワークの 設定法を説明するものではありません. そちらの説明をお捜しなら, http://www.aladdin.co.uk/techweb/ をお勧めします. Windows 95 の設定 Windows 95 を LAN に接続された資源として設定するのは比較的簡単です. Windows 95 のネットワークの設定で ISP に対するデフォルトのゲートウェイとして FreeBSD システムを使用するよう変更するだけで済むからです. 以下の手順を踏んでください. Windows 95 用の "hosts" ファイルをつくる LAN 上の他の TCP/IP システムに接続するためには, で FreeBSD システムにインストールした "hosts" ファイルとまったく同じものを作成してやる必要があります. 「スタート」ボタンを押し,「ファイル名を指定して実行」を選択して "notepad \WINDOWS\HOSTS" (引用符は除いてください) と入力し, 「OK」ボタンを押してください. エディタが開いたら, の hosts ファイルに書いてあるアドレスとシステム名を入力してください. 編集が終わったらノートパッドを閉じてください (ファイルをセーブするのをお忘れ無く!). Windows 95 の TCP/IP ネットワークの設定 タスクバーの「スタート」ボタンを押し, 「設定」「コントロールパネル」を選択してください. 「ネットワーク」アイコンをダブルクリックして開いてください. ネットワークのすべての構成要素に対する設定が表示されます. 「ネットワークの設定」 タブを選択し, 現在のネットワーク構成の中から "TCP/IP->インタフェイスのタイプ" を選択してください ("インタフェイスのタイプ" の部分には, あなたのシステムのイーサネットの名称かタイプが入ります). TCP/IP がネットワーク構成に入っていない場合は, 次の作業に進む前に「追加」ボタンを押し, TCP/IP をインストールしてください. (ヒント: 「追加」「プロトコル」「Microsoft」「TCP/IP」「OK」) 「プロパティ」ボタンを押し, TCP コンポーネント関連の設定を表示させて下さい. IP アドレス情報の設定 「IP アドレス」のタブをクリックし 「IP アドレスを指定」ラジオボタンをクリックしてください. (ガイド中の LAN では Windows 95 システムは "Larry" という名前です.) 「IP アドレス」のフィールドに "192.168.1.2" を入力してください. 「サブネット マスク」フィールドに 255.255.255.0 を入力してください. ゲートウェイの情報の設定 「ゲートウェイ」タブをクリックしてください. ガイド中のネットワークでは, FreeBSD マシンがインターネットへのゲートウェイとして働き, イーサネットで結ばれた LAN と PPP ダイアルアップ接続間でパケットをルーティングします. FreeBSD のイーサネットインタフェイスの IP アドレス, 192.168.1.1 を「新しいゲートウェイ」フィールドに入力し, 「追加」ボタンを押してください. 他のゲートウェイが「インストール済のゲートウェイ」リスト内に定義されているなら, 削除しておいたほうが良いかもしれません. DNS 情報の設定 このガイドでは, インターネットサービスプロバイダ (ISP) が利用可能なドメインネームサーバ (または「DNS サーバ」) のリストを提供しているものと想定しています. ローカル側の FreeBSD システム上で DNS サーバを走らせたいなら, 第 6 章「熱心な学習者への練習問題」に DNS を FreeBSD システム上でセットアップする時の tips がありますので参照してみてください. 「DNS 設定」のタブをクリックしてください 「DNS を使用する」のラジオボタンが選択されているかどうか確認してください. (このボタンが選択されていない場合, アクセスできるのは hosts ファイルに書かれたエントリだけなので, ネットサーフィンをしようとしてもうまく行きません!) 「ホスト名」フィールドに Windows 95マシンの名前を入力してください. このガイドでは "Larry" です. 「ドメイン名」フィールドにローカルネットワーク名を入力してください. このガイドでは "my.domain" です. 「DNS サーバの検索順」セクションに ISP の DNS サーバの IP アドレスを入力してください. 一つ入力するごとに "Add" ボタンを押して, この作業を ISP の提供するアドレスをすべて入力するまで続けてください. その他の Windows 95 の TCP/IP オプション このガイドでは, 「詳細設定」「WINS 設定」「バインド」のタブの下にある設定は重要ではありません. Windows Internet Naming Service ("WINS") を使用したいなら, http://www.localnet.org/ へ行ってみましょう. WINS の設定, 特にインターネット透過でのファイル共有に関する詳細な情報が得られます. 後始末 「OK」ボタンを押して TCP/IP プロパティのウィンドウを閉じてください. 「OK」ボタンを押してネットワークコントロールパネルを閉じてください. 要求された場合, コンピュータをリブートしてください. これでおしまいです! Windows NT の設定 Windows NT を LAN の資源として設定するのも比較的簡単です. Windows NT を設定する手順は, ユーザインタフェイスの些細な差異を除けば Windows 95 と似ています. ここでの手順は Windows NT 4.0 ワークステーション用のものですが, 原則的には NT 3.5x でも同じです. Windows NT 3.5x を使用している場合, 「Windows for Workgroups の設定」を参照するのも良いかもしれません. NT 3.5 と WfW はユーザインタフェイスが同じだからです. 次の手順を踏んでください. Windows NT 用の "hosts" ファイルをつくる LAN 上の他の TCP/IP システムに接続するためには, 3.4 章で FreeBSD システムにインストールした "hosts" ファイルとまったく同じものを作成してやる必要があります. 「スタート」ボタンを押し, 「ファイル名を指定して実行」を選択して "notepad \WINNT\SYSTEM32\DRIVERS\ETC\HOSTS" (引用符は除いてください) と入力し, 「OK」ボタンを押してください. エディタが開いたら, 3.4 章の hosts ファイルに書いてあるアドレスとシステム名を入力してください. 編集が終わったらノートパッドを閉じてください (ファイルをセーブするのをお忘れ無く!). Windows NT の TCP/IP ネットワークの設定 タスクバーの「スタート」ボタンを押し, 「設定」「コントロールパネル」を選択してください. 「ネットワーク」アイコンをダブルクリックして開いてください. "Identification" タブを選択し, "Computer Name" と "Workgroup" フィールドの内容を確かめてください. このガイドでは "Shemp" を名前に, "Stooges" をワークグループに使用します. 必要に応じて "Change" ボタンを押し, 内容を修正してください。 "Protocols" タブを選択してください. インストール済のネットワークプロトコルが表示されます. プロトコルが幾つも表示されるかもしれませんが, このガイドで大事なのは 「TCP/IP プロトコル」だけです. 「TCP/IP プロトコル」が表示されていない場合, 「追加」ボタンを押してこのプロトコルを読み込んでください. (ヒント:「追加」「TCP/IP プロトコル」「OK」) 「TCP/IP プロトコル」を選択し, 「プロパティ」ボタンを押してください. TCP/IP の様々な設定を行うためのタブが表示されるはずです. IP アドレスの設定 イーサネットインタフェイスが「アダプタ」ボックスの中に表示されているかどうか確かめてください. 表示されていない場合, アダプタの一覧表をスクロールさせて正しいインタフェイスを探してください. 「IP アドレスを指定する」ラジオボタンを押して, 三つのテキストボックスを有効にしてください. ガイド中の LAN では, Windows NT システムは "Shemp" という名前です 「IP アドレス」フィールドに "192.168.1.4" を入力してください. 「サブネットマスク」フィールドに 255.255.255.0 を入力してください. ゲートウェイの情報の設定 ガイド中のネットワークでは, FreeBSD マシンがインターネットへのゲートウェイとして働き, イーサネットで結ばれた LAN と PPP ダイアルアップ接続間でパケットをルーティングします. FreeBSD のイーサネットインタフェイスの IP アドレス, 192.168.1.1 を「新しいゲートウェイ」フィールドに入力し, 「追加」ボタンを押してください. 他のゲートウェイが「インストール済のゲートウェイ」リスト内に定義されているなら, 削除しておいたほうが良いかもしれません. DNS の設定 繰り返しますが, このガイドでは, インターネットサービスプロバイダ (ISP) が利用可能なドメインネームサーバ (または「 DNS サーバ」) のリストを提供しているものと想定しています. ローカル側の FreeBSD システム上で DNS サーバを走らせたいなら, 第 6 章「熱心な学習者への練習問題」に DNS を FreeBSD システム上でセットアップする時の tips がありますので参照してみてください. 「DNS」タブをクリックしてください. 「ホスト名」フィールドに Windows NT マシンの名前を入力してください. このガイドでは "Shemp" です. 「ドメイン名」フィールドにローカルネットワーク名を入力してください. このガイドでは "my.domain" です. 「DNS サーバの検索順」セクションに ISP の DNS サーバの IP アドレスを入力してください. 一つ入力するごとに "Add" ボタンを押して, この作業を ISP の提供するアドレスをすべて入力するまで続けてください. その他の Windows NT の TCP/IP オプション このガイドでは, "WINS Address" と "Routing" タブの下にある設定は使用しません. Windows Internet Naming Service ("WINS") を使用したいなら, http://www.localnet.org/ へ行ってみましょう. WINS の設定, 特にインターネット透過でのファイル共有に関する詳細な情報が得られます. 後始末 「OK」ボタンを押して TCP/IP プロパティセクションを閉じてください. 「閉じる」ボタンを押してネットワークコントロールパネルを閉じてください. 要求された場合, コンピュータをリブートしてください. これでおしまいです! Windows for Workgroups の設定 Windows for Workgroups をネットワーククライアントとして作動させるには, Microsoft TCP/IP-32 ドライバディスクがワークステーションにインストールされている必要があります. TCP/IP ドライバは WfW の CD / ディスクには付属していません. コピーは ftp://ftp.microsoft.com:/peropsys/windows/public/tcpip/ から手に入ります. TCP/IP ドライバを読み込んだら、次の手続きを踏んでください. Windows for Workgroups 用の "hosts" ファイルをつくる LAN 上の他の TCP/IP システムに接続するためには, 3.4 章で FreeBSD システムにインストールした "hosts" ファイルとまったく同じものを作成してやる必要があります. プログラムマネージャで "File" ボタンを押し, "Run" を選択して "notepad \WINDOWS\HOSTS" (引用符は除いてください) と入力し, "OK" ボタンを押してください. エディタが開いたら, 3.4 章の hosts ファイルに書いてあるアドレスとシステム名を入力してください. 編集が終わったらノートパッドを閉じてください (ファイルをセーブするのをお忘れ無く!). Windows for Workgroups の TCP/IP ネットワークの設定 プログラムマネージャのメインウィンドウで, "Network" グループのアイコンをダブルクリックして開いてください. "Network Setup" アイコンをダブルクリックしてください. "Network Drivers Box" で "Microsoft TCP/IP-32" のエントリをダブルクリックしてください. Windows for Workgroups の IP アドレスの設定 正しいイーサネットインタフェイスが "Adapter" リストで選択されているかどうか確認してください. 選択されていない場合, インタフェイスが表示されるまでリストをスクロールさせ, クリックして選択してください. "Enable Automatic DHCP Configuration" チェックボックスが選択されていないことを確かめてください. 選択されている場合, クリックして "X" 印を取り除いてください. ガイド中の LAN では, Windows for Workgroups システムは "Moe" という名前です. "IP Address" フィールドには "192.168.1.3" を入力してください. "Subnet Mask" フィールドに 255.255.255.0 を入力してください. ゲートウェイの情報の設定 ガイド中のネットワークでは, FreeBSD マシンがインターネットへのゲートウェイとして働き, イーサネットで結ばれた LAN と PPP ダイアルアップ接続間でパケットをルーティングします. FreeBSD システムの IP アドレス, 192.168.1.1 を "Default Gateway" フィールドに入力してください. DNS の設定 繰り返しますが, このガイドでは, インターネットサービスプロバイダ (ISP) が利用可能なドメインネームサーバ (または「DNS サーバ」) のリストを提供しているものと想定しています. ローカル側の FreeBSD システム上で DNS サーバを走らせたいなら, 第 6 章「インターネット初心者への課題」に DNS を FreeBSD システム上でセットアップする時の tips がありますので参照してみてください. "DNS" ボタンを押してください. "Host Name" フィールドに Windows for Workgroups マシンの名前を入力してください. このガイドでは "Moe" です. "Domain" フィールドにローカルネットワーク名を入力してください. このガイドでは "my.domain" です. "Domain Name Service (DNS) Search Order" セクションに ISP の DNS サーバの IP アドレスを入力してください. 一つ入力するごとに "Add" ボタンを押して, この作業を ISP の提供するアドレスをすべて入力するまで続けてください. 後始末 "OK" ボタンを押して TCP/IP 設定ウィンドウを閉じてください. "OK" ボタンを押してネットワークセットアップウィンドウを閉じてください. 要求された場合, コンピュータを再起動してください. これでおしまいです! ネットワークのテスト 上記の作業を適切に完了したなら, PPP をインターネットへのゲートウェイとして機能させることができるはずです. ダイアルアップリンクのテスト 最初に, モデムと ISP 間で接続を確立できるかどうかテストします. イーサネット LAN のテスト *** TBD *** 熱心な学習者への練習問題 ミニ DNS システムの作成 確かにドメインネームサービス (DNS) ヒエラルキーの管理は黒魔術にも似た作業ではありますが, FreeBSD システムを ISP へのゲートウェイとして作動させながら, 同時に小さな DNS サーバとしても働かせることも可能なのです. FreeBSD システムのインストール時に /etc/namedb ディレクトリに作成されるファイルを元にすれば, ガイド中のネットワークに権威を持ちながら, インターネットの DNS アーキテクチャに対する正面玄関としての役割も果たすネームサーバをつくることができるのです. 最小限の DNS の設定を行うには, 以下の三つのファイルが必要になります. /etc/namedb/named.boot /etc/namedb/named.root /etc/namedb/mydomain.db /etc/namedb/named.root ファイルは FreeBSD のベースインストールの一部として自動的にインストールされますが, 他の二つのファイルは手で書いてやる必要があります. <filename>/etc/namedb/named.boot</filename> ファイル /etc/namedb/named.boot ファイルは DNS サーバのスタートアップ時の設定をコントロールします. 基本的には, ネームサーバに以下の情報を伝えます. どこに設定ファイルが存在し, どの「ドメイン名」を管理するのか. そして どこへ行けば他の DNS サーバを見つけられるのか. 'ee' エディタを使って, 以下の内容の /etc/namedb/named.boot ファイルをつくってください. ; boot file for mini-name server directory /etc/namedb ; type domain source host/file backup file cache . named.root primary my.domain. mydomain.db セミコロンで始まる行はコメントです. このファイル内で重要な行は directory /etc/namedb ネームサーバに '/etc/namedb/named.boot' の残りのセクションで参照される設定ファイルの存在するディレクトリを伝えています. cache . named.root ネームサーバにインターネットの "Top-Level" の DNS サーバの一覧が 'named.root' ファイルに書いてあることを伝えています. (このファイルはベースインストールの一部に含まれているので, このドキュメントでは内容については説明しません.) ネームサーバに対して, "my.domain" という DNS ドメインを 「管理する (authoritative)」こと, "my.domain" (このローカルネットワーク) 上のシステムのホスト名と IP アドレスのリストは 'mydomain.db' ファイル内にあることを伝えています. /etc/namedb/named.boot ファイルをつくってセーブしたら, つぎの章に進んで /etc/namedb/mydomain.db ファイルをつくってください. <filename>/etc/namedb/mydomain.db</filename> ファイル /etc/namedb/mydomain.db ファイルはローカルエリアネットワーク (LAN) のすべてのシステムのホスト名と IP アドレスを一覧にしたものです. このファイルで使用されている文の詳細な説明については, named の man を参照してください. このガイド中のネットワークで DNS サーバの設定を最低限行う /etc/namedb/mydomain.db ファイルは, 次のような内容になるでしょう. @ IN SOA my.domain. root.my.domain. ( 961230 ; 通し番号 3600 ; 問い合わせ 300 ; 再試行 3600000 ; 無効化 3600 ) ; 有効期間 IN NS curly.my.domain. curly.my.domain. IN A 192.168.1.1 # FreeBSD マシン larry.my.domain. IN A 192.168.1.2 # Win'95 マシン moe.my.domain. IN A 192.168.1.3 # WfW マシン shemp.my.domain. IN A 192.168.1.4 # Windows NT マシン $ORIGIN 1.168.192.IN-ADDR.ARPA IN NS curly.my.domain. 1 IN PTR curly.my.domain. 2 IN PTR larry.my.domain. 3 IN PTR moe.my.domain. 4 IN PTR shemp.my.domain. $ORIGIN 0.0.127.IN-ADDR.ARPA IN NS curly.my.domain. 1 IN PTR localhost.my.domain. 簡単に説明すると, このファイルでは, ローカルの DNS サーバは以下のようであると宣言しています. 'my.domain' というドメインに対する管理情報の始点 (Start of Authority, "SOA") であり, 'my.domain' に対するネームサーバ ("NS") であり, '192.168.1.' と '127.0.0.' で始まる全ての IP アドレスに対する逆引き情報に責任があること ("$ORIGIN ...") このファイルにワークステーションのエントリを加えるとき, 一つのシステムにつき二つの行を加える必要があります. 一つは頭のセクション, ホスト名がインターネットアドレス ("IN A") に対応づけられる部分で, もう一つは $ORIGIN 1.168.192.IN-ADDR.ARPA セクションの, アドレスをホスト名に逆付けする部分です. DNS サーバの起動 デフォルトではシステムのブート時に DNS サーバ ('/usr/sbin/named') は起動しません. この振る舞いは, 以下のように '/etc/rc.conf' を一行変えるだけで変更することができます. 'ee' エディタを使って /etc/rc.conf を読み込み, このようなセクションに当たるまで 40 行ほど下ってください. --- named_enable="NO" # Run named, the DNS server (or NO). named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled). --- このセクションを次のように変えましょう. --- named_enable="YES" # Run named, the DNS server (or NO). named_flags="-b /etc/namedb/named.boot" # Flags to named (if enabled). --- ファイルをセーブしてマシンを再起動してください. または, 次のコマンドを打ち込んでネームサーバデーモンを起動してください. # named -b /etc/namedb/named.boot /etc/namedb 以下のファイルを変更した場合はいつも, 変更に対応させるために, ネームサーバのプロセスにキックスタートをかけてやる必要があります. これは以下のシステムコマンドで実行できます. # kill -HUP `cat /var/run/named.pid` PPP フィルタとの戯れ PPP プログラムには, PPP 経由のトラフィックに対して, 選択的にフィルタをかける能力があります. これが正式のファイアウォールほどセキュアーだとはとても言えませんが, リンクの使用についてある種のアクセス制御を提供することはできるのです. (FreeBSD システムをよりセキュアーにする方法を知りたい方は 'man ipfw' してください) PPP 下で使用できる様々なフィルタとその制御法についての完全な説明は PPP の man にあります. PPP プログラムに適用できる制御法には四つのクラスがあります. afilter - アクセスカウンタ (または "Keep Alive") のフィルタ 設定ファイル中の set timeout= 文に無視されるイベントの種類を制御します. dial - ダイアリングフィルタ デマンドダイアルモードの PPP に無視されるイベントの種類を制御します. in - インプットフィルタ システムに入ってくるパケットを, 破棄すべきものと通過してよいものに仕分けるやり方を制御します. out - アウトプットフィルタ システムから出てゆくパケットを, 破棄すべきものと通過してよいものに仕分けるやり方を制御します. 以下は実際に稼働しているオペレーティングシステムから一部拝借して来たものです. このシステムは「通常の」インターネットオペレーションに十分な素地を提供しつつ, PPP がすべてのデータをダイアルアップ接続越しにやり取りすることのないようにしています. 各ルールセットのロジックを解説する簡単なコメントをつけてあります. # # KeepAlive フィルタ # ICMP,DNS と RIP パケットが流れても「通信中」とはみなさない # set filter alive 0 deny icmp set filter alive 1 deny udp src eq 53 set filter alive 2 deny udp dst eq 53 set filter alive 3 deny udp src eq 520 set filter alive 4 deny udp dst eq 520 set filter alive 5 permit 0/0 0/0 # # ダイアルフィルタ # 注意: この設定では ICMP もダイアルアウトのトリガになる # set filter dial 0 permit 0/0 0/0 # # ident パケットの通過を許可する # set filter in 0 permit tcp dst eq 113 set filter out 0 permit tcp src eq 113 # # インターネットへの telnet 接続を許可する # set filter in 1 permit tcp src eq 23 estab set filter out 1 permit tcp dst eq 23 # # インターネットへの ftp アクセスを許可する # set filter in 2 permit tcp src eq 21 estab set filter out 2 permit tcp dst eq 21 set filter in 3 permit tcp src eq 20 dst gt 1023 set filter out 3 permit tcp dst eq 20 # # DNS への問い合わせを許可する # set filter in 4 permit udp src eq 53 set filter out 4 permit udp dst eq 53 # # DNS ゾーン転送を許可する # set filter in 5 permit tcp src eq 53 set filter out 5 permit tcp dst eq 53 # # ローカルネットワークから / へのアクセスを許可する # set filter in 6 permit 0/0 192.168.1.0/24 set filter out 6 permit 192.168.1.0/24 0/0 set ifilter 6 permit 0/0 192.168.1.0/24 set ofilter 6 permit 192.168.1.0/24 0/0 # # ping と traceroute への返答を許可する # set filter in 7 permit icmp set filter out 7 permit icmp set filter in 8 permit udp dst gt 33433 set filter out 9 permit udp dst gt 33433 # # cvsup を許可する # set filter in 9 permit tcp src eq 5998 set filter out 9 permit tcp dst eq 5998 set filter in 10 permit tcp src eq 5999 set filter out 10 permit tcp dst eq 5999 # # 時間の同期のために NTP を許可する # set filter in 11 permit tcp src eq 123 dst eq 123 set filter out 11 permit tcp src eq 123 dst eq 123 set filter in 12 permit udp src eq 123 dst eq 123 set filter out 12 permit udp src eq 123 dst eq 123 # # SMTP もいいかも! # set filter in 13 permit tcp src eq 25 set filter out 13 permit tcp dst eq 25 # # # `whois` を多用するので, これも通す # set filter in 14 permit tcp src eq 43 set filter out 14 permit tcp dst eq 43 set filter in 15 permit udp src eq 43 set filter out 15 permit udp dst eq 43 # # 上記のどのルールにもマッチしない場合, パケットはブロックされる. #------- フィルタクラス一つにつき, 20 個までのフィルタリングルールを適用することができます. 各クラスのルールは 0 から 20 までの連続した数字である必要がありますが, あるフィルタクラスに対するルールは, ルールセット '0' が定義されるまでは有効になりません! PPP の設定でフィルタリングルールを使用しない場合, ISP への接続中はすべてのトラフィックがシステムに出入りすることになります. フィルタリングルールを使用したいなら, 上記の設定を /etc/ppp/ppp.conf ファイルの "default:", "demand:", または "interactive:" セクションのどれか (あるいはすべて - 選ぶのはあなたです) に追加してください. diff --git a/ja_JP.eucJP/share/sgml/articles.ent b/ja_JP.eucJP/share/sgml/articles.ent new file mode 100644 index 0000000000..295683d765 --- /dev/null +++ b/ja_JP.eucJP/share/sgml/articles.ent @@ -0,0 +1,32 @@ + + + +%man; + +%freebsd; + +%authors-ja; + +%authors; + +%teams-ja; + +%teams; + +%mailing-lists-ja; + + +%newsgroups; + +%trademarks-ja; + +%trademarks; + +%l10n; + +%l10n-common; + +%urls; diff --git a/ja_JP.eucJP/share/sgml/books.ent b/ja_JP.eucJP/share/sgml/books.ent new file mode 100644 index 0000000000..f2ee648abb --- /dev/null +++ b/ja_JP.eucJP/share/sgml/books.ent @@ -0,0 +1,34 @@ + + + +%man; + +%bookinfo; + +%freebsd; + +%authors-ja; + +%authors; + +%teams-ja; + +%teams; + +%mailing-lists-ja; + + +%newsgroups; + +%trademarks-ja; + +%trademarks; + +%l10n; + +%l10n-common; + +%urls; diff --git a/ja_JP.eucJP/share/sgml/catalog b/ja_JP.eucJP/share/sgml/catalog index ed4fc4872a..d186204941 100644 --- a/ja_JP.eucJP/share/sgml/catalog +++ b/ja_JP.eucJP/share/sgml/catalog @@ -1,23 +1,29 @@ -- ...................................................................... -- -- FreeBSD SGML Public Identifiers ...................................... -- -- $FreeBSD$ -- PUBLIC "-//FreeBSD//DOCUMENT DocBook Stylesheet//EN" "freebsd.dsl" +PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN" + "articles.ent" + +PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//EN" + "books.ent" + PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//JA" "mailing-lists.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Language Specific Entities//EN" "l10n.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//JA" "authors.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//JA" "teams.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//JA" "trademarks.ent" diff --git a/share/sgml/articles.ent b/share/sgml/articles.ent new file mode 100644 index 0000000000..1628e94813 --- /dev/null +++ b/share/sgml/articles.ent @@ -0,0 +1,22 @@ + + + +%man; + +%freebsd; + +%authors; + +%teams; + +%mailing-lists; + +%newsgroups; + +%trademarks; + +%l10n; + +%l10n-common; + +%urls; diff --git a/share/sgml/books.ent b/share/sgml/books.ent new file mode 100644 index 0000000000..5043825e74 --- /dev/null +++ b/share/sgml/books.ent @@ -0,0 +1,24 @@ + + + +%man; + +%bookinfo; + +%freebsd; + +%authors; + +%teams; + +%mailing-lists; + +%newsgroups; + +%trademarks; + +%l10n; + +%l10n-common; + +%urls; diff --git a/share/sgml/catalog b/share/sgml/catalog index af74be245b..6b82633e6d 100644 --- a/share/sgml/catalog +++ b/share/sgml/catalog @@ -1,64 +1,70 @@ -- ...................................................................... -- -- FreeBSD SGML Public Identifiers ...................................... -- -- $FreeBSD$ -- -- ...................................................................... -- -- Language neutral ..................................................... -- -- These identifiers are shared across all translations of the FreeBSD documentation, even though the listed language is "EN" -- PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" "freebsd.dtd" PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" "freebsd41.dtd" -PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" - "man-refs.ent" - PUBLIC "-//FreeBSD//DOCUMENT DocBook Stylesheet//EN" "freebsd.dsl" PUBLIC "-//FreeBSD//DOCUMENT DocBook Language Neutral Stylesheet//EN" "freebsd.dsl" +PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN" + "articles.ent" + +PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//EN" + "books.ent" + +PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN" + "man-refs.ent" + PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN" "freebsd.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Language Specific Entities//EN" "l10n.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Language Neutral Entities//EN" "l10n.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN" "trademarks.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook URL Entities//EN" "urls.ent" -- ...................................................................... -- -- English specific ..................................................... -- -- These identifiers should only be used by English language versions of the FreeBSD Documentation. All other translations should base their FPIs on these, but change the final parameter in the FPI to represent the target language, as appropriate. Do not change the rest of the FPI -- PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN" "../../en_US.ISO8859-1/share/sgml/bookinfo.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN" "../../en_US.ISO8859-1/share/sgml/authors.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN" "../../en_US.ISO8859-1/share/sgml/teams.ent" PUBLIC "-//FreeBSD//ENTITIES DocBook Newsgroup Entities//EN" "../../en_US.ISO8859-1/share/sgml/newsgroups.ent"