diff --git a/en_US.ISO8859-1/articles/5-roadmap/article.sgml b/en_US.ISO8859-1/articles/5-roadmap/article.sgml index 26f2c82f11..596a39016f 100644 --- a/en_US.ISO8859-1/articles/5-roadmap/article.sgml +++ b/en_US.ISO8859-1/articles/5-roadmap/article.sgml @@ -1,644 +1,645 @@ %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 + 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 + . + 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/console-server/article.sgml b/en_US.ISO8859-1/articles/console-server/article.sgml index cc148bda5a..3847c630b8 100644 --- a/en_US.ISO8859-1/articles/console-server/article.sgml +++ b/en_US.ISO8859-1/articles/console-server/article.sgml @@ -1,1475 +1,1475 @@ %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 + URL="&url.base;/index.html">&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 359598150f..0082d9daae 100644 --- a/en_US.ISO8859-1/articles/contributing/article.sgml +++ b/en_US.ISO8859-1/articles/contributing/article.sgml @@ -1,554 +1,554 @@ %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 + url="&url.base;/projects/c99/index.html">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 + url="&url.base;/cgi/query-pr-summary.cgi">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 + url="&url.base;/donations/">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.