diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml index 5cc63585d6..b6486c7115 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml @@ -1,1555 +1,1555 @@ Jim Mock Updated and restructured by Jake Hamby Originally contributed by Configuring the FreeBSD Kernel Synopsis kernel building a custom kernel The kernel is the core of the &os; operating system. It is responsible for managing memory, enforcing security controls, networking, disk access, and much more. While more and more of &os; becomes dynamically configurable it is still occasionally necessary to reconfigure and recompile your kernel. After reading this chapter, you will know: Why you might need to build a custom kernel. How to write a kernel configuration file, or alter an existing configuration file. How to use the kernel configuration file to create and build a new kernel. How to install the new kernel. How to create any entries in /dev that may be required. How to troubleshoot if things go wrong. Why Build a Custom Kernel? Traditionally, &os; has had what is called a monolithic kernel. This means that the kernel was one large program, supported a fixed list of devices, and if you wanted to change the kernel's behavior then you had to compile a new kernel, and then reboot your computer with the new kernel. Today, &os; is rapidly moving to a model where much of the kernel's functionality is contained in modules which can be dynamically loaded and unloaded from the kernel as necessary. This allows the kernel to adapt to new hardware suddenly becoming available (such as PCMCIA cards in a laptop), or for new functionality to be brought into the kernel that was not necessary when the kernel was originally compiled. This is known as a modular kernel. Colloquially these are called KLDs. Despite this, it is still necessary to carry out some static kernel configuration. In some cases this is because the functionality is so tied to the kernel that it can not be made dynamically loadable. In others it may simply be because no one has yet taken the time to write a dynamic loadable kernel module for that functionality yet. Building a custom kernel is one of the most important rites of passage nearly every Unix user must endure. This process, while time consuming, will provide many benefits to your &os; system. Unlike the GENERIC kernel, which must support a wide range of hardware, a custom kernel only contains support for your PC's hardware. This has a number of benefits, such as: Faster boot time. Since the kernel will only probe the hardware you have on your system, the time it takes your system to boot will decrease dramatically. Less memory usage. A custom kernel often uses less memory than the GENERIC kernel, which is important because the kernel must always be present in real memory. For this reason, a custom kernel is especially useful on a system with a small amount of RAM. Additional hardware support. A custom kernel allows you to add in support for devices such as sound cards, which are not present in the GENERIC kernel. Building and Installing a Custom Kernel kernel building / installing First, let us take a quick tour of the kernel build directory. All directories mentioned will be relative to the main /usr/src/sys directory, which is also accessible through /sys. There are a number of subdirectories here representing different parts of the kernel, but the most important, for our purposes, are arch/conf, where you will edit your custom kernel configuration, and compile, which is the staging area where your kernel will be built. arch represents either i386, alpha, or pc98 (an alternative development branch of PC hardware, popular in Japan). Everything inside a particular architecture's directory deals with that architecture only; the rest of the code is common to all platforms to which &os; could potentially be ported. Notice the logical organization of the directory structure, with each supported device, file system, and option in its own subdirectory. &os; 5.X and up has support for sparc64, and a few other architectures under development. If there is not a /usr/src/sys directory on your system, then the kernel source has not been installed. The easiest way to do this is by running /stand/sysinstall as root, choosing Configure, then Distributions, then src, then sys. If you have an aversion to sysinstall and you have access to an official &os; CDROM, then you can also install the source from the command line: &prompt.root; mount /cdrom &prompt.root; mkdir -p /usr/src/sys &prompt.root; ln -s /usr/src/sys /sys &prompt.root; cat /cdrom/src/ssys.[a-d]* | tar -xzvf - Next, move to the arch/conf directory and copy the GENERIC configuration file to the name you want to give your kernel. For example: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; cp GENERIC MYKERNEL Traditionally, this name is in all capital letters and, if you are maintaining multiple &os; machines with different hardware, it is a good idea to name it after your machine's hostname. We will call it MYKERNEL for the purpose of this example. Storing your kernel config file directly under /usr/src can be a bad idea. If you are experiencing problems it can be tempting to just delete /usr/src and start again. Five seconds after you do that you realize that you have deleted your custom kernel config file. Do not edit GENERIC directly, as it may get overwritten the next time you update your source tree, and your kernel modifications will be lost. You might want to keep your kernel config file elsewhere, and then create a symbolic link to the file in the i386 directory. For example: &prompt.root; cd /usr/src/sys/i386/conf &prompt.root; mkdir /root/kernels &prompt.root; cp GENERIC /root/kernels/MYKERNEL &prompt.root; ln -s /root/kernels/MYKERNEL You must execute these and all of the following commands under the root account or you will get permission denied errors. Now, edit MYKERNEL with your favorite text editor. If you are just starting out, the only editor available will probably be vi, which is too complex to explain here, but is covered well in many books in the bibliography. However, &os; does offer an easier editor called ee which, if you are a beginner, should be your editor of choice. Feel free to change the comment lines at the top to reflect your configuration or the changes you have made to differentiate it from GENERIC. SunOS If you have built a kernel under SunOS or some other BSD operating system, much of this file will be very familiar to you. If you are coming from some other operating system such as DOS, on the other hand, the GENERIC configuration file might seem overwhelming to you, so follow the descriptions in the Configuration File section slowly and carefully. Be sure to always check the file /usr/src/UPDATING, before you perform any update steps, in the case you sync your source tree with the latest sources of the &os; project. In this file all important issues with updating &os; are typed out. /usr/src/UPDATING always fits your version of the &os; source, and is therefore more accurate for new information than the handbook. You must now compile the source code for the kernel. There are two procedures you can use to do this, and the one you will use depends on why you are rebuilding the kernel, and the version of &os; you are running. If you have installed only the kernel source code, use procedure 1. If you are running a &os; version prior to 4.0, and you are not upgrading to &os; 4.0 or higher using the make world procedure, use procedure 1. If you are building a new kernel without updating the source code (perhaps just to add a new option, such as IPFIREWALL) you can use either procedure. If you are rebuilding the kernel as part of a make world process, use procedure 2. - Procedure 1. Building a kernel the <quote>traditional</quote> way + Procedure 1. Building a Kernel the <quote>Traditional</quote> Way Run &man.config.8; to generate the kernel source code. &prompt.root; /usr/sbin/config MYKERNEL Change into the build directory. This is printed out after running the aforementioned command. &prompt.root; cd ../compile/MYKERNEL For &os; version prior to 5.0, use instead: &prompt.root; cd ../../compile/MYKERNEL Compile the kernel. &prompt.root; make depend &prompt.root; make Install the new kernel. &prompt.root; make install - Procedure 2. Building a kernel the <quote>new</quote> - way + Procedure 2. Building a Kernel the <quote>New</quote> + Way Change to the /usr/src directory. &prompt.root; cd /usr/src Compile the kernel. &prompt.root; make buildkernel KERNCONF=MYKERNEL Install the new kernel. &prompt.root; make installkernel KERNCONF=MYKERNEL In &os; 4.2 and older you must replace KERNCONF= with KERNEL=. 4.2-STABLE that was fetched before Feb 2nd, 2001 does not recognize KERNCONF=. cvsup anonymous CVS CTM CVS anonymous If you have not upgraded your source tree in any way (you have not run CVSup, CTM, or used anoncvs), then you should use the config, make depend, make, make install sequence. kernel.old The new kernel will be copied to the root directory as /kernel and the old kernel will be moved to /kernel.old. Now, shutdown the system and reboot to use your new kernel. In case something goes wrong, there are some troubleshooting instructions at the end of this chapter. Be sure to read the section which explains how to recover in case your new kernel does not boot. As of &os; 5.0, kernels are installed along with their modules in /boot/kernel, and old kernels will be backed up as /boot/kernel.old. Other files relating to the boot process, such as the boot &man.loader.8; and configuration are also stored in /boot. Third party or custom modules may be placed in /boot/modules, although users should be aware that keeping modules in sync with the compiled kernel is very important. Modules not intended to run with the compiled kernel may result in instability or incorrectness. If you have added any new devices (such as sound cards) and you are running &os; 4.X or previous versions, you may have to add some device nodes to your /dev directory before you can use them. For more information, take a look at Making Device Nodes section later on in this chapter. The Configuration File kernel LINT LINT kernel config file The general format of a configuration file is quite simple. Each line contains a keyword and one or more arguments. For simplicity, most lines only contain one argument. Anything following a # is considered a comment and ignored. The following sections describe each keyword, generally in the order they are listed in GENERIC, although some related keywords have been grouped together in a single section (such as Networking) even though they are actually scattered throughout the GENERIC file. An exhaustive list of options and more detailed explanations of the device lines is present in the LINT configuration file, located in the same directory as GENERIC. If you are in doubt as to the purpose or necessity of a line, check first in LINT. In &os; 5.X and above the LINT is non-existent. See the NOTES file for architecture dependent options. Some options, mainly architecture independent ones, are stored in the /usr/src/sys/conf/NOTES file. Its advisable to review the options in here also. - Quoting numbers + Quoting Numbers In all versions of &os; up to and including 3.X, &man.config.8; required that any strings in the configuration file that contained numbers used as text had to be enclosed in double quotes. This requirement was removed in the 4.X branch, which this book covers, so if you are on a pre-4.X system, see the /usr/src/sys/i386/conf/LINT and /usr/src/sys/i386/conf/GENERIC files on your system for examples. kernel example config file The following is an example GENERIC kernel configuration file with various additional comments where needed for clarity. This example should match your copy in /usr/src/sys/i386/conf/GENERIC fairly closely. For details of all the possible kernel options, see /usr/src/sys/i386/conf/LINT. # # GENERIC -- Generic kernel configuration file for &os;/i386 # # For more information on this file, please read the handbook section on # Kernel Configuration Files: # # http://www.&os;.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig-config.html # # The handbook is also available locally in /usr/share/doc/handbook # if you've installed the doc distribution, otherwise always see the # &os; World Wide Web server (http://www.FreeBSD.org/) for the # latest information. # # An exhaustive list of options and more detailed explanations of the # device lines is also present in the ../../conf/NOTES and NOTES files. # If you are in doubt as to the purpose or necessity of a line, check first # in NOTES. # # $FreeBSD: src/sys/i386/conf/GENERIC,v 1.380 2003/03/29 13:36:41 mdodd Exp $ The following are the mandatory keywords required in every kernel you build: kernel options machine machine i386 This is the machine architecture. It must be either i386, pc98, sparc64, alpha, ia64, amd64, or powerpc. kernel options cpu cpu I486_CPU cpu I586_CPU cpu I686_CPU The above option specifies the type of CPU you have in your system. You may have multiple instances of the CPU line (i.e., you are not sure whether you should use I586_CPU or I686_CPU), however, for a custom kernel, it is best to specify only the CPU you have. If you are unsure of your CPU type, you can check the /var/run/dmesg.boot file to view your boot up messages. kernel options cpu type Support for I386_CPU is still provided in the source of &os;, but it is disabled by default in both -STABLE and -CURRENT. This means that to install &os; with a 386-class cpu, you now have the following options: Install an older &os; release and rebuild from source as described in . Build the userland and kernel on a newer machine and install on the 386 using the precompiled /usr/obj files. Roll your own release of FreeBSD which includes I386_CPU support in the kernels of the installation CD-ROM. The first of these options is probably the easiest of all, but you will need a lot of disk space on a 386-class machine which may be difficult to find. kernel options ident ident GENERIC This is the identification of the kernel. You should change this to whatever you named your kernel, i.e. MYKERNEL if you have followed the instructions of the previous examples. The value you put in the ident string will print when you boot up the kernel, so it is useful to give the new kernel a different name if you want to keep it separate from your usual kernel (i.e. you want to build an experimental kernel). kernel options maxusers maxusers n The maxusers option sets the size of a number of important system tables. This number is supposed to be roughly equal to the number of simultaneous users you expect to have on your machine. Starting with &os; 4.5, the system will auto-tune this setting for you if you explicitly set it to 0 The auto-tuning algorithm sets maxuser equal to the amount of memory in the system, with a minimum of 32, and a maximum of 384.. In &os;-5.x, maxusers will default to 0 if not specified. If you are using an version of &os; earlier than 4.5, or you want to manage it yourself you will want to set maxusers to at least 4, especially if you are using the X Window System or compiling software. The reason is that the most important table set by maxusers is the maximum number of processes, which is set to 20 + 16 * maxusers, so if you set maxusers to 1, then you can only have 36 simultaneous processes, including the 18 or so that the system starts up at boot time, and the 15 or so you will probably create when you start the X Window System. Even a simple task like reading a manual page will start up nine processes to filter, decompress, and view it. Setting maxusers to 64 will allow you to have up to 1044 simultaneous processes, which should be enough for nearly all uses. If, however, you see the dreaded proc table full error when trying to start another program, or are running a server with a large number of simultaneous users (like ftp.FreeBSD.org), you can always increase the number and rebuild. maxusers does not limit the number of users which can log into your machine. It simply sets various table sizes to reasonable values considering the maximum number of users you will likely have on your system and how many processes each of them will be running. One keyword which does limit the number of simultaneous remote logins and X terminal windows is pseudo-device pty 16. # Floating point support - do not disable. device npx0 at nexus? port IO_NPX irq 13 npx0 is the interface to the floating point math unit in &os;, which is either the hardware co-processor or the software math emulator. This is not optional. # Pseudo devices - the number indicates how many units to allocate. pseudo-device loop # Network loopback This is the generic loopback device for TCP/IP. If you telnet or FTP to localhost (a.k.a., 127.0.0.1) it will come back at you through this pseudo-device. This is mandatory. Everything that follows is more or less optional. See the notes underneath or next to each option for more information. #To statically compile in device wiring instead of /boot/device.hints #hints "GENERIC.hints" #Default places to look for devices. In &os; 5.x and newer versions the &man.device.hints.5; is used to configure options of the device drivers. The default location that &man.loader.8; will check at boot time is /boot/device.hints. Using the hints option you can compile these hints statically into your kernel. Then there is no need to create a device.hints file in /boot. #makeoptions DEBUG=-g #Build kernel with gdb(1) debug symbols The normal build process of the &os; does not include debugging information when building the kernel and strips most symbols after the resulting kernel is linked, to save some space at the install location. If you are going to do tests of kernels in the -CURRENT branch or develop changes of your own for the &os; kernel, you might want to uncomment this line. It will enable the use of the option which enables debugging information when passed to &man.gcc.1;. The same can be accomplished by the &man.config.8; option, if you're using the old procedure of building your kernels (config; make depend; etc.). options MATH_EMULATE #Support for x87 emulation This line allows the kernel to simulate a math co-processor if your computer does not have one (386 or 486SX). If you have a 486DX, or a 386 or 486SX (with a separate 387 or 487 chip), or higher (Pentium, Pentium II, etc.), you can comment this line out. The normal math co-processor emulation routines that come with &os; are not very accurate. If you do not have a math co-processor, and you need the best accuracy, it is recommended that you change this option to GPL_MATH_EMULATE to use the GNU math support, which is not included by default for licensing reasons. In &os; 5.0, math emulation is disabled by default, as older CPUs that do not have native floating point math support are far less common, and in many cases not supported by the native &os; kernel without other additional options. options INET #InterNETworking Networking support. Leave this in, even if you do not plan to be connected to a network. Most programs require at least loopback networking (i.e., making network connections within your PC), so this is essentially mandatory. options INET6 #IPv6 communications protocols This enables the IPv6 communication protocols. options FFS #Berkeley Fast Filesystem options FFS_ROOT #FFS usable as root device [keep this!] This is the basic hard drive Filesystem. Leave it in if you boot from the hard disk. In &os; 5.0, FFS_ROOT is no longer required. options UFS_ACL #Support for access control lists This option, present only in &os; 5.0, enables kernel support for access control lists. This relies on the use of extended attributes and UFS2, and the feature is described in detail in the . ACLs are enabled by default, and should not be disabled in the kernel if they have been used previously on a file system, as this will remove the access control lists changing the way files are protected in unpredictable ways. options UFS_DIRHASH #Improve performance on big directories This option includes some code to speed up disk operations on large directories, at the expense of using a some additional memory. You would normally keep this for a large server, or interactive workstation, and remove it if you are using &os; on a smaller system where memory is at a premium and disk access speed is less important, such as a firewall. options SOFTUPDATES #Enable FFS Soft Updates support This option enables Soft Updates in the kernel, this will help speed up write access on the disks. They are enabled by default in the 4.X branch but may not be turned on. Review the output from &man.mount.8; to see if you have them enabled. If you do not see the soft-updates option then you will need to activate it using the &man.tunefs.8; or &man.newfs.8; for new filesystems. options MFS #Memory Filesystem options MD_ROOT #MD is a potential root device This is the memory-mapped Filesystem. This is basically a RAM disk for fast storage of temporary files, useful if you have a lot of swap space that you want to take advantage of. A perfect place to mount an MFS partition is on the /tmp directory, since many programs store temporary data here. To mount an MFS RAM disk on /tmp, add the following line to /etc/fstab: /dev/ad1s2b /tmp mfs rw 0 0 Now you simply need to either reboot, or run the command mount /tmp. In &os; 5.0, &man.md.4;-backed UFS file systems are used for memory file systems rather than MFS. Information on configuring MD-backed file systems may be found in the man pages for &man.mdconfig.8; and &man.mdmfs.8;. As a result, the MFS option is no longer supported. kernel options NFS kernel options NFS_ROOT options NFS #Network Filesystem options NFS_ROOT #NFS usable as root device, NFS required The network Filesystem. Unless you plan to mount partitions from a Unix file server over TCP/IP, you can comment these out. kernel options MSDOSFS options MSDOSFS #MSDOS Filesystem The MS-DOS Filesystem. Unless you plan to mount a DOS formatted hard drive partition at boot time, you can safely comment this out. It will be automatically loaded the first time you mount a DOS partition, as described above. Also, the excellent mtools software (in the ports collection) allows you to access DOS floppies without having to mount and unmount them (and does not require MSDOSFS at all). options CD9660 #ISO 9660 Filesystem options CD9660_ROOT #CD-ROM usable as root, CD9660 required The ISO 9660 Filesystem for CDROMs. Comment it out if you do not have a CDROM drive or only mount data CDs occasionally (since it will be dynamically loaded the first time you mount a data CD). Audio CDs do not need this Filesystem. options PROCFS #Process filesystem The process filesystem. This is a pretend filesystem mounted on /proc which allows programs like &man.ps.1; to give you more information on what processes are running. In &os; 5.0, use of PROCFS is not required under most circumstances, as most debugging and monitoring tools have been adapted to run without PROCFS. In addition, 5.0-CURRENT kernels making use of PROCFS must now also include support for PSEUDOFS: options PSEUDOFS #Pseudo-filesystem framework PSEUDOFS is not available in &os; 4.X. Unlike in &os; 4.X, new installs of &os; 5.0 will not mount the process file system by default. options COMPAT_43 #Compatible with BSD 4.3 [KEEP THIS!] Compatibility with 4.3BSD. Leave this in; some programs will act strangely if you comment this out. options COMPAT_FREEBSD4 #Compatible with &os;4 This option is required on &os; 5.0 i386 and alpha systems to support applications compiled on older versions of &os; that use older system call interfaces. It is recommended that this option be used on all i386 and alpha systems that may run older applications; platforms that gained support only in 5.0, such as ia64 and sparc64, do not require this option. options SCSI_DELAY=15000 #Delay (in ms) before probing SCSI This causes the kernel to pause for 15 seconds before probing each SCSI device in your system. If you only have IDE hard drives, you can ignore this, otherwise you will probably want to lower this number, perhaps to 5 seconds, to speed up booting. Of course, if you do this, and &os; has trouble recognizing your SCSI devices, you will have to raise it back up. options UCONSOLE #Allow users to grab the console Allow users to grab the console, which is useful for X users. For example, you can create a console xterm by typing xterm -C, which will display any &man.write.1;, &man.talk.1;, and any other messages you receive, as well as any console messages sent by the kernel. In &os; 5.0, UCONSOLE is no longer required. options USERCONFIG #boot -c editor This option allows you to boot the configuration editor from the boot menu. options VISUAL_USERCONFIG #visual boot -c editor This option allows you to boot the visual configuration editor from the boot menu. From &os; versions 5.0 and later, userconfig has been depreciated in favor of the new &man.device.hints.5; method. For more information on &man.device.hints.5; please visit options KTRACE #ktrace(1) support This enables kernel process tracing, which is useful in debugging. options SYSVSHM #SYSV-style shared memory This option provides for System V shared memory. The most common use of this is the XSHM extension in X, which many graphics-intensive programs will automatically take advantage of for extra speed. If you use X, you will definitely want to include this. options SYSVSEM #SYSV-style semaphores Support for System V semaphores. Less commonly used but only adds a few hundred bytes to the kernel. options SYSVMSG #SYSV-style message queues Support for System V messages. Again, only adds a few hundred bytes to the kernel. The &man.ipcs.1; command will list any processes using each of these System V facilities. options P1003_1B #Posix P1003_1B real-time extensions options _KPOSIX_PRIORITY_SCHEDULING Real-time extensions added in the 1993 POSIX. Certain applications in the ports collection use these (such as StarOffice). In &os; 5.0, all of this functionality is now provided by the _KPOSIX_PRIORITY_SCHEDULING option, and P1003_1B is no longer required. kernel options ICMP_BANDLIM Denial of Service (DoS) options ICMP_BANDLIM #Rate limit bad replies This option enables ICMP error response bandwidth limiting. You typically want this option as it will help protect the machine from denial of service packet attacks. In &os; 5.0, this feature is enabled by default and the ICMP_BANDLIM option is not required. kernel options SMP # To make an SMP kernel, the next two are needed #options SMP # Symmetric MultiProcessor Kernel #options APIC_IO # Symmetric (APIC) I/O The above are both required for SMP support. device isa All PCs supported by &os; have one of these. If you have an IBM PS/2 (Micro Channel Architecture), &os; provides some limited support at this time. For more information about the MCA support, see /usr/src/sys/i386/conf/LINT. device eisa Include this if you have an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus. device pci Include this if you have a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus. device agp Include this if you have an AGP card in the system. This will enable support for AGP, and AGP GART for boards which have these features. # Floppy drives device fdc0 at isa? port IO_FD1 irq 6 drq 2 device fd0 at fdc0 drive 0 device fd1 at fdc0 drive 1 This is the floppy drive controller. fd0 is the A: floppy drive, and fd1 is the B: drive. device ata This driver supports all ATA and ATAPI devices. You only need one device ata line for the kernel to detect all PCI ATA/ATAPI devices on modern machines. device atadisk # ATA disk drives This is needed along with device ata for ATA disk drives. device atapicd # ATAPI CDROM drives This is needed along with device ata for ATAPI CDROM drives. device atapifd # ATAPI floppy drives This is needed along with device ata for ATAPI floppy drives. device atapist # ATAPI tape drives This is needed along with device ata for ATAPI tape drives. options ATA_STATIC_ID #Static device numbering This makes the controller number static (like the old driver) or else the device numbers are dynamically allocated. # ATA and ATAPI devices device ata0 at isa? port IO_WD1 irq 14 device ata1 at isa? port IO_WD2 irq 15 Use the above for older, non-PCI systems. # SCSI Controllers device ahb # EISA AHA1742 family device ahc # AHA2940 and onboard AIC7xxx devices device amd # AMD 53C974 (Teckram DC-390(T)) device dpt # DPT Smartcache - See LINT for options! device isp # Qlogic family device ncr # NCR/Symbios Logic device sym # NCR/Symbios Logic (newer chipsets) device adv0 at isa? device adw device bt0 at isa? device aha0 at isa? device aic0 at isa? SCSI controllers. Comment out any you do not have in your system. If you have an IDE only system, you can remove these altogether. # SCSI peripherals device scbus # SCSI bus (required) device da # Direct Access (disks) device sa # Sequential Access (tape etc) device cd # CD device pass # Passthrough device (direct SCSI access) SCSI peripherals. Again, comment out any you do not have, or if you have only IDE hardware, you can remove them completely. # RAID controllers device ida # Compaq Smart RAID device amr # AMI MegaRAID device mlx # Mylex DAC960 family Supported RAID controllers. If you do not have any of these, you can comment them out or remove them. # atkbdc0 controls both the keyboard and the PS/2 mouse device atkbdc0 at isa? port IO_KBD The keyboard controller (atkbdc) provides I/O services for the AT keyboard and PS/2 style pointing devices. This controller is required by the keyboard driver (atkbd) and the PS/2 pointing device driver (psm). device atkbd0 at atkbdc? irq 1 The atkbd driver, together with atkbdc controller, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller. device psm0 at atkbdc? irq 12 Use this device if your mouse plugs into the PS/2 mouse port. device vga0 at isa? The video card driver. # splash screen/screen saver pseudo-device splash Splash screen at start up! Screen savers require this too. # syscons is the default console driver, resembling an SCO console device sc0 at isa? sc0 is the default console driver, which resembles a SCO console. Since most full-screen programs access the console through a terminal database library like termcap, it should not matter whether you use this or vt0, the VT220 compatible console driver. When you log in, set your TERM variable to scoansi if full-screen programs have trouble running under this console. # Enable this and PCVT_FREEBSD for pcvt vt220 compatible console driver #device vt0 at isa? #options XSERVER # support for X server on a vt console #options FAT_CURSOR # start with block cursor # If you have a ThinkPAD, uncomment this along with the rest of the PCVT lines #options PCVT_SCANSET=2 # IBM keyboards are non-std This is a VT220-compatible console driver, backward compatible to VT100/102. It works well on some laptops which have hardware incompatibilities with sc0. Also set your TERM variable to vt100 or vt220 when you log in. This driver might also prove useful when connecting to a large number of different machines over the network, where termcap or terminfo entries for the sc0 device are often not available — vt100 should be available on virtually any platform. # Power management support (see LINT for more options) device apm0 at nexus? disable flags 0x20 # Advanced Power Management Advanced Power Management support. Useful for laptops. # PCCARD (PCMCIA) support device card device pcic0 at isa? irq 10 port 0x3e0 iomem 0xd0000 device pcic1 at isa? irq 11 port 0x3e2 iomem 0xd4000 disable PCMCIA support. You want this if you are using a laptop. # Serial (COM) ports device sio0 at isa? port IO_COM1 flags 0x10 irq 4 device sio1 at isa? port IO_COM2 irq 3 device sio2 at isa? disable port IO_COM3 irq 5 device sio3 at isa? disable port IO_COM4 irq 9 These are the four serial ports referred to as COM1 through COM4 in the MS-DOS/Windows world. If you have an internal modem on COM4 and a serial port at COM2, you will have to change the IRQ of the modem to 2 (for obscure technical reasons, IRQ2 = IRQ 9) in order to access it from &os;. If you have a multiport serial card, check the manual page for &man.sio.4; for more information on the proper values for these lines. Some video cards (notably those based on S3 chips) use IO addresses in the form of 0x*2e8, and since many cheap serial cards do not fully decode the 16-bit IO address space, they clash with these cards making the COM4 port practically unavailable. Each serial port is required to have a unique IRQ (unless you are using one of the multiport cards where shared interrupts are supported), so the default IRQs for COM3 and COM4 cannot be used. # Parallel port device ppc0 at isa? irq 7 This is the ISA-bus parallel port interface. device ppbus # Parallel port bus (required) Provides support for the parallel port bus. device lpt # Printer Support for parallel port printers. All three of the above are required to enable parallel printer support. device plip # TCP/IP over parallel This is the driver for the parallel network interface. device ppi # Parallel port interface device The general-purpose I/O (geek port) + IEEE1284 I/O. #device vpo # Requires scbus and da zip drive This is for an Iomega Zip drive. It requires scbus and da support. Best performance is achieved with ports in EPP 1.9 mode. # PCI Ethernet NICs. device de # DEC/Intel DC21x4x (Tulip) device fxp # Intel EtherExpress PRO/100B (82557, 82558) device tx # SMC 9432TX (83c170 EPIC) device vx # 3Com 3c590, 3c595 (Vortex) device wx # Intel Gigabit Ethernet Card (Wiseman) Various PCI network card drivers. Comment out or remove any of these not present in your system. # PCI Ethernet NICs that use the common MII bus controller code. device miibus # MII bus support MII bus support is required for some PCI 10/100 Ethernet NICs, namely those which use MII-compliant transceivers or implement transceiver control interfaces that operate like an MII. Adding device miibus to the kernel config pulls in support for the generic miibus API and all of the PHY drivers, including a generic one for PHYs that are not specifically handled by an individual driver. device dc # DEC/Intel 21143 and various workalikes device rl # RealTek 8129/8139 device sf # Adaptec AIC-6915 (Starfire) device sis # Silicon Integrated Systems SiS 900/SiS 7016 device ste # Sundance ST201 (D-Link DFE-550TX) device tl # Texas Instruments ThunderLAN device vr # VIA Rhine, Rhine II device wb # Winbond W89C840F device xl # 3Com 3c90x (Boomerang, Cyclone) Drivers that use the MII bus controller code. # ISA Ethernet NICs. device ed0 at isa? port 0x280 irq 10 iomem 0xd8000 device ex device ep # WaveLAN/IEEE 802.11 wireless NICs. Note: the WaveLAN/IEEE really # exists only as a PCMCIA device, so there is no ISA attachment needed # and resources will always be dynamically assigned by the pccard code. device wi # Aironet 4500/4800 802.11 wireless NICs. Note: the declaration below will # work for PCMCIA and PCI cards, as well as ISA cards set to ISA PnP # mode (the factory default). If you set the switches on your ISA # card for a manually chosen I/O address and IRQ, you must specify # those parameters here. device an # The probe order of these is presently determined by i386/isa/isa_compat.c. device ie0 at isa? port 0x300 irq 10 iomem 0xd0000 device fe0 at isa? port 0x300 device le0 at isa? port 0x300 irq 5 iomem 0xd0000 device lnc0 at isa? port 0x280 irq 10 drq 0 device cs0 at isa? port 0x300 device sn0 at isa? port 0x300 irq 10 # requires PCCARD (PCMCIA) support to be activated #device xe0 at isa? ISA Ethernet drivers. See /usr/src/sys/i386/conf/LINT for which cards are supported by which driver. pseudo-device ether # Ethernet support ether is only needed if you have an Ethernet card. It includes generic Ethernet protocol code. pseudo-device sl 1 # Kernel SLIP sl is for SLIP support. This has been almost entirely supplanted by PPP, which is easier to set up, better suited for modem-to-modem connection, and more powerful. The number after sl specifies how many simultaneous SLIP sessions to support. pseudo-device ppp 1 # Kernel PPP This is for kernel PPP support for dial-up connections. There is also a version of PPP implemented as a userland application that uses tun and offers more flexibility and features such as demand dialing. The number after ppp specifies how many simultaneous PPP connections to support. pseudo-device tun # Packet tunnel. This is used by the userland PPP software. A number after tun specifies the number of simultaneous PPP sessions to support. See the PPP section of this book for more information. pseudo-device pty # Pseudo-ttys (telnet etc) This is a pseudo-terminal or simulated login port. It is used by incoming telnet and rlogin sessions, xterm, and some other applications such as Emacs. A number after pty indicates the number of ptys to create. If you need more than the default of 16 simultaneous xterm windows and/or remote logins, be sure to increase this number accordingly, up to a maximum of 256. pseudo-device md # Memory disks Memory disk pseudo-devices. pseudo-device gif or pseudo-device gif 4 # IPv6 and IPv4 tunneling This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. Beginning with &os; 4.4 the gif device is auto-cloning, and you should use the first example (without the number after gif). Earlier versions of &os; require the number. pseudo-device faith 1 # IPv6-to-IPv4 relaying (translation) This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon. # The `bpf' pseudo-device enables the Berkeley Packet Filter. # Be aware of the administrative consequences of enabling this! pseudo-device bpf # Berkeley packet filter This is the Berkeley Packet Filter. This pseudo-device allows network interfaces to be placed in promiscuous mode, capturing every packet on a broadcast network (e.g., an Ethernet). These packets can be captured to disk and or examined with the &man.tcpdump.1; program. The bpf pseudo-device is also used by &man.dhclient.8; to obtain the IP address of the default router (gateway) and so on. If you use DHCP, leave this uncommented. # USB support #device uhci # UHCI PCI->USB interface #device ohci # OHCI PCI->USB interface #device usb # USB Bus (required) #device ugen # Generic #device uhid # Human Interface Devices #device ukbd # Keyboard #device ulpt # Printer #device umass # Disks/Mass storage - Requires scbus and da #device ums # Mouse # USB Ethernet, requires mii #device aue # ADMtek USB ethernet #device cue # CATC USB ethernet #device kue # Kawasaki LSI USB ethernet Support for various USB devices. For more information and additional devices supported by &os;, see /usr/src/sys/i386/conf/LINT. Making Device Nodes device nodes MAKEDEV If you are running &os; 5.0 or later you can safely skip this section. These versions use &man.devfs.5; to allocate device nodes transparently for the user. Almost every device in the kernel has a corresponding node entry in the /dev directory. These nodes look like regular files, but are actually special entries into the kernel which programs use to access the device. The shell script /dev/MAKEDEV, which is executed when you first install the operating system, creates nearly all of the device nodes supported. However, it does not create all of them, so when you add support for a new device, it pays to make sure that the appropriate entries are in this directory, and if not, add them. Here is a simple example: Suppose you add the IDE CD-ROM support to the kernel. The line to add is: device acd0 This means that you should look for some entries that start with acd0 in the /dev directory, possibly followed by a letter, such as c, or preceded by the letter r, which means a raw device. It turns out that those files are not there, so you must change to the /dev directory and type: MAKEDEV &prompt.root; sh MAKEDEV acd0 When this script finishes, you will find that there are now acd0c and racd0c entries in /dev so you know that it executed correctly. For sound cards, the following command creates the appropriate entries: &prompt.root; sh MAKEDEV snd0 When creating device nodes for devices such as sound cards, if other people have access to your machine, it may be desirable to protect the devices from outside access by adding them to the /etc/fbtab file. See &man.fbtab.5; for more information. Follow this simple procedure for any other non-GENERIC devices which do not have entries. All SCSI controllers use the same set of /dev entries, so you do not need to create these. Also, network cards and SLIP/PPP pseudo-devices do not have entries in /dev at all, so you do not have to worry about these either. If Something Goes Wrong There are five categories of trouble that can occur when building a custom kernel. They are: config fails: If the &man.config.8; command fails when you give it your kernel description, you have probably made a simple error somewhere. Fortunately, &man.config.8; will print the line number that it had trouble with, so you can quickly skip to it with vi. For example, if you see: config: line 17: syntax error You can skip to the problem in vi by typing 17G in command mode. Make sure the keyword is typed correctly, by comparing it to the GENERIC kernel or another reference. make fails: If the make command fails, it usually signals an error in your kernel description, but not severe enough for &man.config.8; to catch it. Again, look over your configuration, and if you still cannot resolve the problem, send mail to the &a.questions; with your kernel configuration, and it should be diagnosed very quickly. Installing the new kernel fails: If the kernel compiled fine, but failed to install (the make install or make installkernel command failed), the first thing to check is if your system is running at securelevel 1 or higher (see &man.init.8;). The kernel installation tries to remove the immutable flag from your kernel and set the immutable flag on the new one. Since securelevel 1 or higher prevents unsetting the immutable flag for any files on the system, the kernel installation needs to be performed at securelevel 0 or lower. The kernel does not boot: If your new kernel does not boot, or fails to recognize your devices, do not panic! Fortunately, &os; has an excellent mechanism for recovering from incompatible kernels. Simply choose the kernel you want to boot from at the &os; boot loader. You can access this when the system counts down from 10. Hit any key except for the Enter key, type unload and then type boot kernel.old, or the filename of any other kernel that will boot properly. When reconfiguring a kernel, it is always a good idea to keep a kernel that is known to work on hand. After booting with a good kernel you can check over your configuration file and try to build it again. One helpful resource is the /var/log/messages file which records, among other things, all of the kernel messages from every successful boot. Also, the &man.dmesg.8; command will print the kernel messages from the current boot. If you are having trouble building a kernel, make sure to keep a GENERIC, or some other kernel that is known to work on hand as a different name that will not get erased on the next build. You cannot rely on kernel.old because when installing a new kernel, kernel.old is overwritten with the last installed kernel which may be non-functional. Also, as soon as possible, move the working kernel to the proper kernel location or commands such as &man.ps.1; will not work properly. The proper command to unlock the kernel file that make installs (in order to move another kernel back permanently) is: &prompt.root; chflags noschg /kernel If you find you cannot do this, you are probably running at a &man.securelevel.8; greater than zero. Edit kern_securelevel in /etc/rc.conf and set it to -1, then reboot. You can change it back to its previous setting when you are happy with your new kernel. And, if you want to lock your new kernel into place, or any file for that matter, so that it cannot be moved or tampered with: &prompt.root; chflags schg /kernel In &os; 5.0, kernels are not installed with the system immutable flag, so this is unlikely to be the source of the problem you're experiencing. The kernel works, but &man.ps.1; does not work any more: If you have installed a different version of the kernel from the one that the system utilities have been built with, for example, a 4.X kernel on a 3.X system, many system-status commands like &man.ps.1; and &man.vmstat.8; will not work any more. You must recompile the libkvm library as well as these utilities. This is one reason it is not normally a good idea to use a different version of the kernel from the rest of the operating system. diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml index 8c9d9d8d62..77a1eaa51e 100644 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml @@ -1,973 +1,973 @@ Andrey A. Chernov Contributed by Michael C. Wu Rewritten by Localization - I18N/L10N Usage and Setup Synopsis FreeBSD is a very distributed project with users and contributors located all over the world. This chapter discusses the internationalization and localization features of FreeBSD that allow non-English speaking users to get real work done. There are many aspects of the i18n implementation in both the system and application levels, so where applicable we refer the reader to more specific sources of documentation. After reading this chapter, you will know: How different languages and locales are encoded on modern operating systems. How to set the locale for your login shell. How to configure your console for non-English languages. How to use X Windows effectively with different languages. Where to find more information about writing i18n-compliant applications. Before reading this chapter, you should: Know how to install additional third-party applications (). The Basics - What is I18N/L10N? + What Is I18N/L10N? internationalization localization Developers shortened internationalization into the term I18N, counting the number of letters between the first and the last letters of internationalization. L10N uses the same naming scheme, coming from localization. Combined together, I18N/L10N methods, protocols, and applications allow users to use languages of their choice. I18N applications are programmed using I18N kits under libraries. It allows for developers to write a simple file and translate displayed menus and texts to each language. We strongly encourage programmers to follow this convention. Why Should I Use I18N/L10N? I18N/L10N is used whenever you wish to either view, input, or process data in non-English languages. What Languages Are Supported in the I18N Effort? I18N and L10N are not FreeBSD specific. Currently, one can choose from most of the major languages of the World, including but not limited to: Chinese, German, Japanese, Korean, French, Russian, Vietnamese and others. Using Localization In all its splendor, I18N is not FreeBSD-specific and is a convention. We encourage you to help FreeBSD in following this convention. locale Localization settings are based on three main terms: Language Code, Country Code, and Encoding. Locale names are constructed from these parts as follows: LanguageCode_CountryCode.Encoding Language and Country Codes language codes country codes In order to localize a FreeBSD system to a specific language (or any other I18N-supporting Unixes), the user needs to find out the codes for the specify country and language (country codes tell applications what variation of given language to use). In addition, web browsers, SMTP/POP servers, web servers, etc. make decisions based on them. The following are examples of language/country codes: Language/Country Code Description en_US English - United States ru_RU Russian for Russia zh_TW Traditional Chinese for Taiwan Encodings encodings ASCII Some languages use non-ASCII encodings that are 8-bit, wide or multibyte characters, see &man.multibyte.3; for more details. Older applications do not recognize them and mistake them for control characters. Newer applications usually do recognize 8-bit characters. Depending on the implementation, users may be required to compile an application with wide or multibyte characters support, or configure it correctly. To be able to input and process wide or multibyte characters, the FreeBSD Ports collection has provided each language with different programs. Refer to the I18N documentation in the respective FreeBSD Port. Specifically, the user needs to look at the application documentation to decide on how to configure it correctly or to pass correct values into the configure/Makefile/compiler. Some things to keep in mind are: Language specific single C chars character sets (see &man.multibyte.3;), i.e., ISO-8859-1, ISO-8859-15, KOI8-R, CP437. Wide or multibyte encodings, i.e. EUC, Big5. You can check the active list of character sets at the IANA Registry. FreeBSD versions 4.5 and up use X11-compatible locale encodings instead. I18N Applications In the FreeBSD Ports and Package system, I18N applications have been named with I18N in their names for easy identification. However, they do not always support the language needed. Setting Locale Usually it is sufficient to export the value of the locale name as LANG in the login shell. This could be done in the user's ~/.login_conf file or in the startup file of the user's shell (~/.profile, ~/.bashrc, ~/.cshrc). There is no need to set the locale subsets such as LC_CTYPE, LC_CTIME. Please refer to language-specific FreeBSD documentation for more information. You should set the following two environment variables in your configuration files: POSIX LANG for POSIX &man.setlocale.3; family functions MIME MM_CHARSET for applications' MIME character set This includes the user shell configuration, the specific application configuration, and the X11 configuration. Setting Locale Methods locale login class There are two methods for setting locale, and both are described below. The first (recommended one) is by assigning the environment variables in login class, and the second is by adding the environment variable assignments to the system's shell startup file. Login Classes Method This method allows environment variables needed for locale name and MIME character sets to be assigned once for every possible shell instead of adding specific shell assignments to each shell's startup file. User Level Setup can be done by an user himself and Administrator Level Setup require superuser privileges. User Level Setup Here is a minimal example of a .login_conf file in user's home directory which has both variables set for Latin-1 encoding: me:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1: Traditional ChineseBIG-5 encoding Here is an example of a .login_conf that sets the variables for Traditional Chinese in BIG-5 encoding. Notice the many more variables set because some software does not respect locale variables correctly for Chinese, Japanese, and Korean. #Users who do not wish to use monetary units or time formats #of Taiwan can manually change each variable me:\ lang=zh_TW.Big5:\ lc_all=zh_TW.Big:\ lc_collate=zh_TW.Big5:\ lc_ctype=zh_TW.Big5:\ lc_messages=zh_TW.Big5:\ lc_monetary=zh_TW.Big5:\ lc_numeric=zh_TW.Big5:\ lc_time=zh_TW.Big5:\ charset=big5:\ xmodifiers="@im=xcin": #Setting the XIM Input Server See Administrator Level Setup and &man.login.conf.5; for more details. Administrator Level Setup Verify that the user's login class in /etc/login.conf sets the correct language. Make sure these settings appear in /etc/login.conf: language_name:accounts_title:\ :charset=MIME_charset:\ :lang=locale_name:\ :tc=default: So sticking with our previous example using Latin-1, it would look like this: german:German Users Accounts:\ :charset=ISO-8859-1:\ :lang=de_DE.ISO8859-1:\ :tc=default: Changing Login Classes with &man.vipw.8; vipw Use vipw to add new users, and make the entry look like this: user:password:1111:11:language:0:0:User Name:/home/user:/bin/sh Changing Login Classes with &man.adduser.8; adduser login class Use adduser to add new users, and do the following: Set defaultclass = language in /etc/adduser.conf. Keep in mind you must enter a default class for all users of other languages in this case. An alternative variant is answering the specified language each time that Enter login class: default []: appears from &man.adduser.8;. Another alternative is to use the following for each user of a different language that you wish to add: &prompt.root; adduser -class language Changing Login Classes with &man.pw.8; pw If you use &man.pw.8; for adding new users, call it in this form: &prompt.root; pw useradd user_name -L language Shell Startup File Method This method is not recommended because it requires a different setup for each possible shell program chosen. Use the Login Class Method instead. MIME locale To add the locale name and MIME character set, just set the two environment variables shown below in the /etc/profile and/or /etc/csh.login shell startup files. We will use the German language as an example below: In /etc/profile: LANG=de_DE.ISO8859-1; export LANG MM_CHARSET=ISO-8859-1; export MM_CHARSET Or in /etc/csh.login: setenv LANG de_DE.ISO8859-1 setenv MM_CHARSET ISO-8859-1 Alternatively, you can add the above instructions to /usr/share/skel/dot.profile (similar to what was used in /etc/profile above), or /usr/share/skel/dot.login (similar to what was used in /etc/csh.login above). For X11: In $HOME/.xinitrc: LANG=de_DE.ISO8859-1; export LANG Or: setenv LANG de_DE.ISO8859-1 Depending on your shell (see above). Console Setup For all single C chars character sets, set the correct console fonts in /etc/rc.conf for the language in question with: font8x16=font_name font8x14=font_name font8x8=font_name The font_name here is taken from the /usr/share/syscons/fonts directory, without the .fnt suffix. sysinstall keymap screenmap Also be sure to set the correct keymap and screenmap for your single C chars character set through /stand/sysinstall. Once inside sysinstall, choose Configure, then Console. Alternatively, you can add the following to /etc/rc.conf: scrnmap=screenmap_name keymap=keymap_name keychange="fkey_number sequence" The screenmap_name here is taken from the /usr/share/syscons/scrnmaps directory, without the .scm suffix. A screenmap with a corresponding mapped font is usually needed as a workaround for expanding bit 8 to bit 9 on a VGA adapter's font character matrix in pseudographics area, i.e., to move letters out of that area if screen font uses a bit 8 column. If you have the moused daemon enabled by setting the following in your /etc/rc.conf: moused_enable="YES" then examine the mouse cursor information in the next paragraph. moused By default the mouse cursor of the &man.syscons.4; driver occupies the 0xd0-0xd3 range in the character set. If your language uses this range, you need to move the cursor's range outside of it. To enable the workaround for FreeBSD versions before 5.0, insert the following line into your kernel configuration: options SC_MOUSE_CHAR=0x03 For the FreeBSD versions 4.4 and up insert the following line into /etc/rc.conf: mousechar_start=3 The keymap_name here is taken from the /usr/share/syscons/keymaps directory, without the .kbd suffix. If you're uncertain which keymap to use, you use can &man.kbdmap.1; to test keymaps without rebooting. The keychange is usually needed to program function keys to match the selected terminal type because function key sequences cannot be defined in the key map. Also be sure to set the correct console terminal type in /etc/ttys for all ttyv* entries. Current pre-defined correspondences are: Character Set Terminal Type ISO-8859-1 or ISO-8859-15 cons25l1 ISO-8859-2 cons25l2 ISO-8859-7 cons25l7 KOI8-R cons25r KOI8-U cons25u CP437 (VGA default) cons25 US-ASCII cons25w For wide or multibyte characters languages, use the correct FreeBSD port in your /usr/ports/language directory. Some ports appear as console while the system sees it as serial vtty's, hence you must reserve enough vtty's for both X11 and the pseudo-serial console. Here is a partial list of applications for using other languages in console: Language Location Traditional Chinese (BIG-5) chinese/big5con Japanese japanese/ja-kon2-* or japanese/Mule_Wnn Korean korean/ko-han X11 Setup Although X11 is not part of the FreeBSD Project, we have included some information here for FreeBSD users. For more details, refer to the XFree86 web site or whichever X11 Server you use. In ~/.Xresources, you can additionally tune application specific I18N settings (e.g., fonts, menus, etc.). Displaying Fonts X11 True Type font server Install the X11 True Type-Common server (x11-servers/XttXF86srv-common) and install the language truetype fonts. Setting the correct locale should allow you to view your selected language in menus and such. Inputting Non-English Characters X11 Input Method (XIM) The X11 Input Method (XIM) Protocol is a new standard for all X11 clients. All X11 applications should be written as XIM clients that take input from XIM Input servers. There are several XIM servers available for different languages. Printer Setup Some single C chars character sets are usually hardware coded into printers. Wide or multibyte character sets require special setup and we recommend using apsfilter. You may also convert the document to PostScript or PDF formats using language specific converters. Kernel and File Systems The FreeBSD fast filesystem (FFS) is 8-bit clean, so it can be used with any single C chars character set (see &man.multibyte.3;), but there is no character set name stored in the filesystem; i.e., it is raw 8-bit and does not know anything about encoding order. Officially, FFS does not support any form of wide or multibyte character sets yet. However, some wide or multibyte character sets have independent patches for FFS enabling such support. They are only temporary unportable solutions or hacks and we have decided to not include them in the source tree. Refer to respective languages' web sites for more informations and the patch files. DOS Unicode The FreeBSD MS-DOS filesystem has the configurable ability to convert between MS-DOS, Unicode character sets and chosen FreeBSD filesystem character sets. See &man.mount.msdos.8; for details. Compiling I18N Programs Many FreeBSD Ports have been ported with I18N support. Some of them are marked with -I18N in the port name. These and many other programs have built in support for I18N and need no special consideration. MySQL However, some applications such as MySQL need to be have the Makefile configured with the specific charset. This is usually done in the Makefile or done by passing a value to configure in the source. Localizing FreeBSD to Specific Languages Andrey A. Chernov Originally contributed by - Russian Language (KOI8-R encoding) + Russian Language (KOI8-R Encoding) localization Russian For more information about KOI8-R encoding, see the KOI8-R References (Russian Net Character Set). Locale Setup Put the following lines into your ~/.login_conf file: me:My Account:\ :charset=KOI8-R:\ :lang=ru_RU.KOI8-R: See earlier in this chapter for examples of setting up the locale. Console Setup For the FreeBSD versions before 5.0 add the following line to your kernel configuration file: options SC_MOUSE_CHAR=0x03 For the FreeBSD versions 4.4 and up insert the following line into /etc/rc.conf: mousechar_start=3 Use following settings in /etc/rc.conf: keymap="ru.koi8-r" scrnmap="koi8-r2cp866" font8x16="cp866b-8x16" font8x14="cp866-8x14" font8x8="cp866-8x8" For each ttyv* entry in /etc/ttys, use cons25r as the terminal type. See earlier in this chapter for examples of setting up the console. Printer Setup printers Since most printers with Russian characters come with hardware code page CP866, a special output filter is needed to convert from KOI8-R to CP866. Such a filter is installed by default as /usr/libexec/lpr/ru/koi2alt. A Russian printer /etc/printcap entry should look like: lp|Russian local line printer:\ :sh:of=/usr/libexec/lpr/ru/koi2alt:\ :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs: See &man.printcap.5; for a detailed description. MS-DOS FS and Russian Filenames The following example &man.fstab.5; entry enables support for Russian filenames in mounted MS-DOS filesystems: /dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0 See &man.mount.msdos.8; for a detailed description of the and options. X11 Setup Do non-X locale setup first as described. The Russian KOI8-R locale may not work with old XFree86 releases (lower than 3.3). XFree86 4.X is now the default version of the X Window System on FreeBSD. This should not be an issue unless you are using an old version of FreeBSD. Go to the russian/X.language directory and issue the following command: &prompt.root; make install The above port installs the latest version of the KOI8-R fonts. XFree86 3.3 already has some KOI8-R fonts, but these are scaled better. Check the "Files" section in your /etc/XF86Config file. The following lines must be added before any other FontPath entries: FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/misc" FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/75dpi" FontPath "/usr/X11R6/lib/X11/fonts/cyrillic/100dpi" If you use a high resolution video mode, swap the 75 dpi and 100 dpi lines. To activate a Russian keyboard, add the following to the "Keyboard" section of your XF86Config file. For XFree86 3.X: XkbLayout "ru" XkbOptions "grp:caps_toggle" For XFree86 4.X: Option "XkbLayout" "ru" Option "XkbOptions" "grp:caps_toggle" Also make sure that XkbDisable is turned off (commented out) there. The RUS/LAT switch will be CapsLock. The old CapsLock function is still available via ShiftCapsLock (in LAT mode only). If you have Windows keys on your keyboard, and notice that some non-alphabetical keys are mapped incorrectly in RUS mode, add the following line in your XF86Config file. For XFree86 3.X: XkbVariant "winkeys" For XFree86 4.X: Option "XkbVariant" "winkeys" The Russian XKB keyboard may not work with old XFree86 versions, see the above note for more information. The Russian XKB keyboard may also not work with non-localized applications as well. Minimally localized applications should call a XtSetLanguageProc (NULL, NULL, NULL); function early in the program. See KOI8-R for X Window for more instructions on localizing X11 applications. Traditional Chinese Localization for Taiwan localization Traditional Chinese The FreeBSD-Taiwan Project has an I18N/L10N tutorial for FreeBSD at using many Chinese ports. The editor for the zh-L10N-tut is Clive Lin Clive@CirX.org. You can also cvsup the following collections at freebsd.sinica.edu.tw: Collection Description outta-port tag=. Beta-quality ports collection for Chinese zh-L10N-tut tag=. Localizing FreeBSD Tutorial in BIG-5 Traditional Chinese zh-doc tag=. FreeBSD Documentation Translation to BIG-5 Traditional Chinese Chuan-Hsing Shen s874070@mail.yzu.edu.tw has created the Chinese FreeBSD Collection (CFC) using FreeBSD-Taiwan's zh-L10N-tut. The packages and the script files are available at . - German Language Localization (For All ISO 8859-1 + <title>German Language Localization (for All ISO 8859-1 Languages) localization German Slaven Rezic eserte@cs.tu-berlin.de wrote a tutorial how to use umlauts on a FreeBSD machine. The tutorial is written in German and available at . Japanese and Korean Language Localization localization Japanese localization Korean For Japanese, refer to , and for Korean, refer to . Non-English FreeBSD Documentation Some FreeBSD contributors have translated parts of FreeBSD to other languages. They are available through links on the main site or in /usr/share/doc. diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml index 3b5099a70d..680210b4df 100644 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml @@ -1,3097 +1,3097 @@ Jim Mock Restructured and parts updated by Brian N. Handy Originally contributed by Rich Murphey Linux Binary Compatibility Synopsis Linux binary compatibility binary compatibility Linux FreeBSD provides binary compatibility with several other Unix-like operating systems, including Linux. At this point, you may be asking yourself why exactly, does FreeBSD need to be able to run Linux binaries? The answer to that question is quite simple. Many companies and developers develop only for Linux, since it is the latest hot thing in the computing world. That leaves the rest of us FreeBSD users bugging these same companies and developers to put out native FreeBSD versions of their applications. The problem is, that most of these companies do not really realize how many people would use their product if there were FreeBSD versions too, and most continue to only develop for Linux. So what is a FreeBSD user to do? This is where the Linux binary compatibility of FreeBSD comes into play. In a nutshell, the compatibility allows FreeBSD users to run about 90% of all Linux applications without modification. This includes applications such as Star Office, the Linux version of Netscape, Adobe Acrobat, RealPlayer 5 and 7, VMWare, Oracle, WordPerfect, Doom, Quake, and more. It is also reported that in some situations, Linux binaries perform better on FreeBSD than they do under Linux. Linux /proc file system There are, however, some Linux-specific operating system features that are not supported under FreeBSD. Linux binaries will not work on FreeBSD if they overly use the Linux /proc file system (which is different from FreeBSD's /proc file system), or i386-specific calls, such as enabling virtual 8086 mode. After reading this chapter, you will know: How to enable Linux binary compatibility on your system. How to install additional Linux shared libraries. How to install Linux applications on your FreeBSD system. The implementation details of Linux compatibility in FreeBSD. Before reading this chapter, you should: Know how to install additional third-party software (). Installation KLD (kernel loadable object) Linux binary compatibility is not turned on by default. The easiest way to enable this functionality is to load the linux KLD object (Kernel LoaDable object). You can load this module by simply typing linux at the command prompt. If you would like Linux compatibility to always be enabled, then you should add the following line to /etc/rc.conf: linux_enable="YES" The &man.kldstat.8; command can be used to verify that the KLD is loaded: &prompt.user; kldstat Id Refs Address Size Name 1 2 0xc0100000 16bdb8 kernel 7 1 0xc24db000 d000 linux.ko kernel options LINUX If for some reason you do not want to or cannot load the KLD, then you may statically link Linux binary compatibility into the kernel by adding options LINUX to your kernel configuration file. Then install your new kernel as described in . Installing Linux Runtime Libraries Linux installing Linux libraries This can be done one of two ways, either by using the linux_base port, or by installing them manually. Installing Using the linux_base Port ports collection This is by far the easiest method to use when installing the runtime libraries. It is just like installing any other port from the ports collection. Simply do the following: &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make install distclean You should now have working Linux binary compatibility. Some programs may complain about incorrect minor versions of the system libraries. In general, however, this does not seem to be a problem. Installing Libraries Manually If you do not have the ports collection installed, you can install the libraries by hand instead. You will need the Linux shared libraries that the program depends on and the runtime linker. Also, you will need to create a shadow root directory, /compat/linux, for Linux libraries on your FreeBSD system. Any shared libraries opened by Linux programs run under FreeBSD will look in this tree first. So, if a Linux program loads, for example, /lib/libc.so, FreeBSD will first try to open /compat/linux/lib/libc.so, and if that does not exist, it will then try /lib/libc.so. Shared libraries should be installed in the shadow tree /compat/linux/lib rather than the paths that the Linux ld.so reports. Generally, you will need to look for the shared libraries that Linux binaries depend on only the first few times that you install a Linux program on your FreeBSD system. After a while, you will have a sufficient set of Linux shared libraries on your system to be able to run newly imported Linux binaries without any extra work. How to Install Additional Shared Libraries shared libraries What if you install the linux_base port and your application still complains about missing shared libraries? How do you know which shared libraries Linux binaries need, and where to get them? Basically, there are 2 possibilities (when following these instructions you will need to be root on your FreeBSD system). If you have access to a Linux system, see what shared libraries the application needs, and copy them to your FreeBSD system. Look at the following example: Let us assume you used FTP to get the Linux binary of Doom, and put it on a Linux system you have access to. You then can check which shared libraries it needs by running ldd linuxdoom, like so: &prompt.user; ldd linuxdoom libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29 symbolic links You would need to get all the files from the last column, and put them under /compat/linux, with the names in the first column as symbolic links pointing to them. This means you eventually have these files on your FreeBSD system: /compat/linux/usr/X11/lib/libXt.so.3.1.0 /compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3.1.0 /compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
Note that if you already have a Linux shared library with a matching major revision number to the first column of the ldd output, you will not need to copy the file named in the last column to your system, the one you already have should work. It is advisable to copy the shared library anyway if it is a newer version, though. You can remove the old one, as long as you make the symbolic link point to the new one. So, if you have these libraries on your system: /compat/linux/lib/libc.so.4.6.27 /compat/linux/lib/libc.so.4 -> libc.so.4.6.27 and you find a new binary that claims to require a later version according to the output of ldd: libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29 If it is only one or two versions out of date in the in the trailing digit then do not worry about copying /lib/libc.so.4.6.29 too, because the program should work fine with the slightly older version. However, if you like, you can decide to replace the libc.so anyway, and that should leave you with: /compat/linux/lib/libc.so.4.6.29 /compat/linux/lib/libc.so.4 -> libc.so.4.6.29
The symbolic link mechanism is only needed for Linux binaries. The FreeBSD runtime linker takes care of looking for matching major revision numbers itself and you do not need to worry about it.
Installing Linux ELF Binaries Linux ELF binaries ELF binaries sometimes require an extra step of branding. If you attempt to run an unbranded ELF binary, you will get an error message like the following: &prompt.user; ./my-linux-elf-binary ELF binary type not known Abort To help the FreeBSD kernel distinguish between a FreeBSD ELF binary from a Linux binary, use the &man.brandelf.1; utility. &prompt.user; brandelf -t Linux my-linux-elf-binary GNU toolchain The GNU toolchain now places the appropriate branding information into ELF binaries automatically, so this step should become increasingly more rare in the future. Configuring the Hostname Resolver If DNS does not work or you get this message: resolv+: "bind" is an invalid keyword resolv+: "hosts" is an invalid keyword You will need to configure a /compat/linux/etc/host.conf file containing: order hosts, bind multi on The order here specifies that /etc/hosts is searched first and DNS is searched second. When /compat/linux/etc/host.conf is not installed, Linux applications find FreeBSD's /etc/host.conf and complain about the incompatible FreeBSD syntax. You should remove bind if you have not configured a name server using the /etc/resolv.conf file. Murray Stokely Updated for Mathematica 4.X by Bojan Bistrovic Merged with work by Installing Mathematica applications Mathematica This document describes the process of installing the Linux version of Mathematica 4.X onto a FreeBSD system. The Linux version of Mathematica runs perfectly under FreeBSD however the binaries shipped by Wolfram need to be branded so that FreeBSD knows to use the Linux ABI to execute them. The Linux version of Mathematica or Mathematica for Students can be ordered directly from Wolfram at . Branding the Linux Binaries The Linux binaries are located in the Unix directory of the Mathematica CDROM distributed by Wolfram. You need to copy this directory tree to your local hard drive so that you can brand the Linux binaries with &man.brandelf.1; before running the installer: &prompt.root; mount /cdrom &prompt.root; cp -rp /cdrom/Unix/ /localdir/ &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Kernel/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/FrontEnd/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Installation/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Graphics/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/Converters/Binaries/Linux/* &prompt.root; brandelf -t Linux /localdir/Files/SystemFiles/LicenseManager/Binaries/Linux/mathlm &prompt.root; cd /localdir/Installers/Linux/ &prompt.root; ./MathInstaller Alternatively, you can simply set the default ELF brand to Linux for all unbranded binaries with the command: &prompt.root; sysctl kern.fallback_elf_brand=3 This will make FreeBSD assume that unbranded ELF binaries use the Linux ABI and so you should be able to run the installer straight from the CDROM. Obtaining Your Mathematica Password Before you can run Mathematica you will have to obtain a password from Wolfram that corresponds to your machine ID. Ethernet MAC address Once you have installed the Linux compatibility runtime libraries and unpacked Mathematica you can obtain the machine ID by running the program mathinfo in the Install directory. This machine ID is based solely on the MAC address of your first Ethernet card. &prompt.root; cd /localdir/Files/SystemFiles/Installation/Binaries/Linux &prompt.root; mathinfo disco.example.com 7115-70839-20412 When you register with Wolfram, either by email, phone or fax, you will give them the machine ID and they will respond with a corresponding password consisting of groups of numbers. You can then enter this information when you attempt to run Mathematica for the first time exactly as you would for any other Mathematica platform. Running the Mathematica Frontend over a Network Mathematica uses some special fonts to display characters not present in any of the standard font sets (integrals, sums, Greek letters, etc.). The X protocol requires these fonts to be install locally. This means you will have to copy these fonts from the CDROM or from a host with Mathematica installed to your local machine. These fonts are normally stored in /cdrom/Unix/Files/SystemFiles/Fonts on the CDROM, or /usr/local/mathematica/SystemFiles/Fonts on your hard drive. The actual fonts are in the subdirectories Type1 and X. There are several ways to use them, as described below. The first way is to copy them into one of the existing font directories in /usr/X11R6/lib/X11/fonts. This will require editing the fonts.dir file, adding the font names to it, and changing the number of fonts on the first line. Alternatively, you should also just be able to run mkfontdir in the directory you have copied them to. The second way to do this is to copy the directories to /usr/X11R6/lib/X11/fonts: &prompt.root; cd /usr/X11R6/lib/X11/fonts &prompt.root; mkdir X &prompt.root; mkdir MathType1 &prompt.root; cd /cdrom/Unix/Files/SystemFiles/Fonts &prompt.root; cp X/* /usr/X11R6/lib/X11/fonts/X &prompt.root; cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; cd /usr/X11R6/lib/X11/fonts/X &prompt.root; mkfontdir &prompt.root; cd ../MathType1 &prompt.root; mkfontdir Now add the new font directories to your font path: &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/X &prompt.root; xset fp+ /usr/X11R6/lib/X11/fonts/MathType1 &prompt.root; xset fp rehash If you are using the XFree86 server, you can have these font directories loaded automatically by adding them to your XF86Config file. fonts If you do not already have a directory called /usr/X11R6/lib/X11/fonts/Type1, you can change the name of the MathType1 directory in the example above to Type1. Aaron Kaplan Contributed by Robert Getschmann Thanks to Installing Maple applications Maple Maple is a commercial mathematics program similar to Mathematica. You must purchase this software from and then register there for a license file. To install this software on FreeBSD, please follow these simple steps. Execute the INSTALL shell script from the product distribution. Choose the RedHat option when prompted by the installation program. A typical installation directory might be /usr/local/maple. If you have not done so, order a license for Maple from Maple Waterloo Software (http://register.maplesoft.com) and copy it to /usr/local/maple/license/license.dat. Install the FLEXlm license manager by running the INSTALL_LIC install shell script that comes with Maple. Specify the primary hostname for your machine for the license server. Patch the usr/local/maple/bin/maple.system.type file with the following: ----- snip ------------------ *** maple.system.type.orig Sun Jul 8 16:35:33 2001 --- maple.system.type Sun Jul 8 16:35:51 2001 *************** *** 72,77 **** --- 72,78 ---- # the IBM RS/6000 AIX case MAPLE_BIN="bin.IBM_RISC_UNIX" ;; + "FreeBSD"|\ "Linux") # the Linux/x86 case # We have two Linux implementations, one for Red Hat and ----- snip end of patch ----- Please note that after the "FreeBSD"|\ no other whitespace should be present. This patch instructs Maple to recognize FreeBSD as a type of Linux system. The bin/maple shell script calls the bin/maple.system.type shell script which in turn calls uname -a to find out the operating system name. Depending on the OS name it will find out which binaries to use. Start the license server. The following script, installed as /usr/local/etc/rc.d/lmgrd.sh is a convenient way to start up lmgrd: ----- snip ------------ #! /bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX export PATH LICENSE_FILE=/usr/local/maple/license/license.dat LOG=/var/log/lmgrd.log case "$1" in start) lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2 echo -n " lmgrd" ;; stop) lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2 ;; *) echo "Usage: `basename $0` {start|stop}" 1>&2 exit 64 ;; esac exit 0 ----- snip ------------ Test-start maple: &prompt.user; cd /usr/local/maple/bin &prompt.user; ./xmaple You should be up and running. Make sure to write Maplesoft to let them know you would like a native FreeBSD version! Common Pitfalls The FLEXlm license manager can be a difficult tool to work with. Additional documentation on the subject can be found at . lmgrd is known to be very picky about the license file and to core dump if there are any problems. A correct license file should look like this: # ======================================================= # License File for UNIX Installations ("Pointer File") # ======================================================= SERVER chillig ANY #USE_SERVER VENDOR maplelmg FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \ ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \ SN=XXXXXXXXX Serial number and key 'X''ed out. chillig is a hostname. Editing the license file works as long as you do not touch the FEATURE line (which is protected by the license key). Marcel Moolenaar Contributed by Installing Oracle applications Oracle Preface This document describes the process of installing Oracle 8.0.5 and Oracle 8.0.5.1 Enterprise Edition for Linux onto a FreeBSD machine. Installing the Linux Environment Make sure you have both linux_base and linux_devtools from the ports collection installed. These ports are added to the collection after the release of FreeBSD 3.2. If you are using FreeBSD 3.2 or an older version for that matter, update your ports collection. You may want to consider updating your FreeBSD version too. If you run into difficulties with linux_base-6.1 or linux_devtools-6.1 you may have to use version 5.2 of these packages. If you want to run the intelligent agent, you will also need to install the Red Hat Tcl package: tcl-8.0.3-20.i386.rpm. The general command for installing packages with the official RPM port is: &prompt.root; rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm package Installation of the package should not generate any errors. Creating the Oracle Environment Before you can install Oracle, you need to set up a proper environment. This document only describes what to do specially to run Oracle for Linux on FreeBSD, not what has been described in the Oracle installation guide. Kernel Tuning kernel tuning As described in the Oracle installation guide, you need to set the maximum size of shared memory. Do not use SHMMAX under FreeBSD. SHMMAX is merely calculated out of SHMMAXPGS and PGSIZE. Therefore define SHMMAXPGS. All other options can be used as described in the guide. For example: options SHMMAXPGS=10000 options SHMMNI=100 options SHMSEG=10 options SEMMNS=200 options SEMMNI=70 options SEMMSL=61 Set these options to suit your intended use of Oracle. Also, make sure you have the following options in your kernel config-file: options SYSVSHM #SysV shared memory options SYSVSEM #SysV semaphores options SYSVMSG #SysV interprocess communication Oracle Account Create an Oracle account just as you would create any other account. The Oracle account is special only that you need to give it a Linux shell. Add /compat/linux/bin/bash to /etc/shells and set the shell for the Oracle account to /compat/linux/bin/bash. Environment Besides the normal Oracle variables, such as ORACLE_HOME and ORACLE_SID you must set the following environment variables: Variable Value LD_LIBRARY_PATH $ORACLE_HOME/lib CLASSPATH $ORACLE_HOME/jdbc/lib/classes111.zip PATH /compat/linux/bin /compat/linux/sbin /compat/linux/usr/bin /compat/linux/usr/sbin /bin /sbin /usr/bin /usr/sbin /usr/local/bin $ORACLE_HOME/bin It is advised to set all the environment variables in .profile. A complete example is: ORACLE_BASE=/oracle; export ORACLE_BASE ORACLE_HOME=/oracle; export ORACLE_HOME LD_LIBRARY_PATH=$ORACLE_HOME/lib export LD_LIBRARY_PATH ORACLE_SID=ORCL; export ORACLE_SID ORACLE_TERM=386x; export ORACLE_TERM CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip export CLASSPATH PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin export PATH Installing Oracle Due to a slight inconsistency in the Linux emulator, you need to create a directory named .oracle in /var/tmp before you start the installer. Either make it world writable or let it be owner by the oracle user. You should be able to install Oracle without any problems. If you have problems, check your Oracle distribution and/or configuration first! After you have installed Oracle, apply the patches described in the next two subsections. A frequent problem is that the TCP protocol adapter is not installed right. As a consequence, you cannot start any TCP listeners. The following actions help solve this problem: &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk ntcontab.o &prompt.root; cd $ORACLE_HOME/lib &prompt.root; ar r libnetwork.a ntcontab.o &prompt.root; cd $ORACLE_HOME/network/lib &prompt.root; make -f ins_network.mk install Do not forget to run root.sh again! Patching root.sh When installing Oracle, some actions, which need to be performed as root, are recorded in a shell script called root.sh. root.sh is written in the orainst directory. Apply the following patch to root.sh, to have it use to proper location of chown or alternatively run the script under a Linux native shell. *** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 --- orainst/root.sh Mon Dec 28 15:58:53 1998 *************** *** 31,37 **** # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/bin/chown # # Define variables to be used in this script --- 31,37 ---- # This is the default value for CHOWN # It will redefined later in this script for those ports # which have it conditionally defined in ss_install.h ! CHOWN=/usr/sbin/chown # # Define variables to be used in this script When you do not install Oracle from CD, you can patch the source for root.sh. It is called rthd.sh and is located in the orainst directory in the source tree. Patching genclntsh The script genclntsh is used to create a single shared client library. It is used when building the demos. Apply the following patch to comment out the definition of PATH: *** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 --- bin/genclntsh Tue Dec 22 15:36:49 1998 *************** *** 32,38 **** # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst --- 32,38 ---- # # Explicit path to ensure that we're using the correct commands #PATH=/usr/bin:/usr/ccs/bin export PATH ! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH # # each product MUST provide a $PRODUCT/admin/shrept.lst Running Oracle When you have followed the instructions, you should be able to run Oracle as if it was run on Linux itself. Holger Kipp Contributed by Valentino Vaschetto Original version converted to SGML by Installing SAP R/3 applications SAP R/3 Installations of SAP Systems using FreeBSD will not be supported by the SAP support team — they only offer support for certified platforms. Preface This document describes a possible way of installing a SAP R/3-System with Oracle Database for Linux onto a FreeBSD machine, including the installation of FreeBSD and Oracle. Two different configurations will be described: SAP R/3 4.6B (IDES) with Oracle 8.0.5 on FreeBSD 4.3-STABLE SAP R/3 4.6C with Oracle 8.1.7 on FreeBSD 4.5-STABLE Even though this document tries to describe all important steps in a greater detail, it is not intended as a replacement for the Oracle and SAP R/3 installation guides. Please see the documentation that comes with the SAP R/3 Linux edition for SAP- and Oracle-specific questions, as well as resources from Oracle and SAP OSS. Software The following CD-ROMs have been used for SAP-installations: SAP R/3 4.6B, Oracle 8.0.5 Name Number Description KERNEL 51009113 SAP Kernel Oracle / Installation / AIX, Linux, Solaris RDBMS 51007558 Oracle / RDBMS 8.0.5.X / Linux EXPORT1 51010208 IDES / DB-Export / Disc 1 of 6 EXPORT2 51010209 IDES / DB-Export / Disc 2 of 6 EXPORT3 51010210 IDES / DB-Export / Disc 3 of 6 EXPORT4 51010211 IDES / DB-Export / Disc 4 of 6 EXPORT5 51010212 IDES / DB-Export / Disc 5 of 6 EXPORT6 51010213 IDES / DB-Export / Disc 6 of 6 Additionally, I used the Oracle 8 Server (Pre-production version 8.0.5 for Linux, Kernel Version 2.0.33) CD which is not really necessary, and of course FreeBSD 4.3-STABLE (it was only a few days past 4.3 RELEASE). SAP R/3 4.6C SR2, Oracle 8.1.7 Name Number Description KERNEL 51014004 SAP Kernel Oracle / SAP Kernel Version 4.6D / DEC, Linux RDBMS 51012930 Oracle 8.1.7/ RDBMS / Linux EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 1 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 2 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 3 of 4 EXPORT1 51013953 Release 4.6C SR2 / Export / Disc 4 of 4 LANG1 51013954 Release 4.6C SR2 / Language / DE, EN, FR / Disc 1 of 3 Depending on the languages you would like to install, additional language CDs might be necessary. Here we're just using DE and EN, so the first Language-CD is the only one needed. As a little note, the numbers for all four export CDs are identical. All three language CDs also have the same number (this is different from the 4.6B IDES release CD numbering). At the time of writing this installation is running on FreeBSD 4.5-STABLE (20.03.2002). - SAP-Notes + SAP Notes The following notes should be read before installing SAP R/3 or proved to be useful during installation: SAP R/3 4.6B, Oracle 8.0.5 Number Title 0171356 SAP Software on Linux: Essential Comments 0201147 INST: 4.6C R/3 Inst. on UNIX - Oracle 0373203 Update / Migration Oracle 8.0.5 --> 8.0.6/8.1.6 LINUX 0072984 Release of Digital UNIX 4.0B for Oracle 0130581 R3SETUP step DIPGNTAB terminates 0144978 Your system has not been installed correctly 0162266 Questions and tips for R3SETUP on Windows NT / W2K SAP R/3 4.6C, Oracle 8.1.7 Number Title 0015023 Initializing table TCPDB (RSXP0004) (EBCDIC) 0045619 R/3 with several languages or typefaces 0171356 SAP Software on Linux: Essential Comments 0195603 RedHat 6.1 Enterprise version: Known problems 0212876 The new archiving tool SAPCAR 0300900 Linux: Released DELL Hardware 0377187 RedHat 6.2: important remarks 0387074 INST: R/3 4.6C SR2 Installation on UNIX 0387077 INST: R/3 4.6C SR2 Inst. on UNIX - Oracle 0387078 SAP Software on UNIX: OS Dependencies 4.6C SR2 - Hardware-Requirements + Hardware Requirements The following equipment is sufficient for the installation of a SAP R/3 System. For production use, a more exact sizing is of course needed: Component 4.6B 4.6C Processor 2 x 800MHz Pentium III 2 x 800MHz Pentium III Memory 1GB ECC 2GB ECC Hard Disk Space 50-60GB (IDES) 50-60GB (IDES) For use in production, Xeon-Processors with large cache, high-speed disk access (SCSI, RAID hardware controller), USV and ECC-RAM is recommended. The large amount of hard disk space is due to the preconfigured IDES System, which creates 27 GB of database files during installation. This space is also sufficient for initial production systems and application data. SAP R/3 4.6B, Oracle 8.0.5 The following off-the-shelf hardware was used: a dual processor board with 2 800 MHz Pentium III processors, Adaptec 29160 Ultra160 SCSI adapter (for accessing a 40/80 GB DLT tape drive and CDROM), Mylex AcceleRAID (2 channels, firmware 6.00-1-00 with 32 MB RAM). To the Mylex Raid-controller are attached two 17 GB hard disks (mirrored) and four 36 GB hard disks (RAID level 5). SAP R/3 4.6C, Oracle 8.1.7 For this installation a DELL PowerEdge 2500 was used: a dual processor board with two 1000 MHz Pentium III processors (256 kB Cache), 2 GB PC133 ECC SDRAM, PERC/3 DC PCI Raid Controller with 128 MB, and an EIDE DVD-ROM drive. To the RAID-controller are attached two 18 GB hard disks (mirrored) and four 36 GB hard disks (RAID level 5). Installation of FreeBSD First you have to install FreeBSD. There are several ways to do this (FreeBSD 4.3 was installed via FTP, FreeBSD 4.5 directly from release-CD). Disk Layout To keep it simple, the same disk layout both for the SAP R/3 46B- and SAP R/3 46C SR2-installation was used. Only the device names changed, as the installations were on different hardware (/dev/da and /dev/amr respectively, so if using an AMI MegaRAID, one will see /dev/amr0s1a instead of /dev/da0s1a): File system Size (1k-blocks) Size (GB) Mounted on /dev/da0s1a 1.016.303 1 / /dev/da0s1b 6 swap /dev/da0s1e 2.032.623 2 /var /dev/da0s1f 8.205.339 8 /usr /dev/da1s1e 45.734.361 45 /compat/linux/oracle /dev/da1s1f 2.032.623 2 /compat/linux/sapmnt /dev/da1s1g 2.032.623 2 /compat/linux/usr/sap Configure and initialize the two logical drives with the Mylex- or PERC/3 RAID software beforehand. The software can be started during the bios boot phase. Please note that this disk layout differs slightly from the SAP recommendations, as SAP suggests mounting the oracle-subdirectories (and some others) separately - I decided to just create them as real subdirectories for simplicity. <command>make world</command> and a New Kernel Download the latest stable-sources. Rebuild world and your custom kernel after configuring your kernel configuration file. Here you should also include the kernel parameters which are required for both SAP R/3 and Oracle. Installing the Linux Environment During the first installation with FreeBSD 4.3-STABLE I had some trouble downloading the required RPM-files (for 4.3 stable, 2nd May 2001), but with FreeBSD 4.5-STABLE, everything went very smooth. Should you encounter some problems, try to download those files by hand. For a list of RPM-Mirrors and required files, see the corresponding makefile. - Installing Linux Base-system + Installing the Linux Base System First the linux_base port needs to be installed (as root). This is currently linux_base-6. &prompt.root; cd /usr/ports/emulators/linux_base &prompt.root; make package Installing Linux Development The Linux development is needed, if you want to install Oracle on FreeBSD according to the corresponding description in the handbook: &prompt.root; cd /usr/ports/devel/linux_devtools &prompt.root; make package Linux Development has only been installed for the SAP R/3 46B IDES-installation. It is not needed, if the Oracle DB is not relinked on the FreeBSD system. This is the case if you are using the Oracle tarball from a Linux system. - Installing Necessary RPMs + Installing the Necessary RPMs RPMs To start the R3SETUP-Program, PAM support is needed. During the first SAP-Installation on FreeBSD 4.3-STABLE I tried to install PAM with all the required packages and finally forced the installation of the PAM package, which worked. For SAP R/3 4.6C SR2 I directly forced the installation of the PAM-RPM, which also works, so it seems the dependent packages are not needed: &prompt.root; rpm -i --ignoreos --nodeps --root /compat/linux --dbpath /var/lib/rpm \ pam-0.68-7.i386.rpm For Oracle 8.0.5 to run the intelligent agent, I also had to install the RedHat Tcl package tcl-8.0.5-30.i386.rpm (otherwise the relinking during Oracle install will not work). There are some other issues regarding relinking of Oracle, but that is a Oracle-Linux issue, not FreeBSD specific. - Some additional hints + Some Additional Hints It might also be a good idea to add linprocfs to /etc/fstab. See man linprocfs. Another parameter to set is kern.fallback_elf_brand=3 which is done in file /etc/sysctl.conf. Creating the SAP/R3 Environment Creating the Necessary File Systems and Mountpoints For a simple installation, it is sufficient to create the following file systems: mount point size in GB /compat/linux/oracle 45 GB /compat/linux/sapmnt 2 GB /compat/linux/usr/sap 2 GB It is also necessary to created some links. Otherwise the SAP-Installer will complain, as it is checking the created links: &prompt.root; ln -s /compat/linux/oracle /oracle &prompt.root; ln -s /compat/linux/sapmnt /sapmnt &prompt.root; ln -s /compat/linux/usr/sap /usr/sap Possible error message during installation (here with System PRD and the SAP R/3 4.6C SR2 installation): INFO 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:200 Checking existence of symbolic link /usr/sap/PRD/SYS/exe/dbg to /sapmnt/PRD/exe. Creating if it does not exist... WARNING 2002-03-19 16:45:36 R3LINKS_IND_IND SyLinkCreate:400 Link /usr/sap/PRD/SYS/exe/dbg exists but it points to file /compat/linux/sapmnt/PRD/exe instead of /sapmnt/PRD/exe. The program cannot go on as long as this link exists at this location. Move the link to another location. ERROR 2002-03-19 16:45:36 R3LINKS_IND_IND Ins_SetupLinks:0 can not setup link '/usr/sap/PRD/SYS/exe/dbg' with content '/sapmnt/PRD/exe' Creating Users and Directories SAP R/3 needs two users and three groups. The user names depend on the SAP system id (SID) which consists of three letters. Some of these SIDs are reserved by SAP (for example SAP and NIX. For a complete list please see the SAP documentation). For the IDES installation I used IDS, for the 4.6C SR2 installation PRD, as that system is intended for production use. We have therefore the following groups (group ids might differ, these are just the values I used with my installation): group id group name description 100 dba Data Base Administrator 101 sapsys SAP System 102 oper Data Base Operator For a default Oracle-Installation, only group dba is used. As oper-group, one also uses group dba (see Oracle- and SAP-documentation for further information). We also need the following users: user id user name generic name group additional groups description 1000 idsadm/prdadm sidadm sapsys oper SAP Administrator 1002 oraids/oraprd orasid dba oper DB Administrator Adding the users with adduser requires the following (please note shell and home directory) entries for SAP-Administrator: Name: sidadm Password: ****** Fullname: SAP Administrator SID Uid: 1000 Gid: 101 (sapsys) Class: Groups: sapsys dba HOME: /home/sidadm Shell: bash (/compat/linux/bin/bash) and for Database-Administrator: Name: orasid Password: ****** Fullname: Oracle Administrator SID Uid: 1002 Gid: 100 (dba) Class: Groups: dba HOME: /oracle/sid Shell: bash (/compat/linux/bin/bash) This should also include group oper in case you are using both groups dba and oper. Creating Directories These directories are usually created as separate file systems. This depends entirely on your requirements. I choose to create them as simple directories, as they are all located on the same RAID 5 anyway: First we will set owners and rights of some directories (as user root): &prompt.root; chmod 775 /oracle &prompt.root; chmod 777 /sapmnt &prompt.root; chown root:dba /oracle &prompt.root; chown sidadm:sapsys /compat/linux/usr/sap &prompt.root; chmod 775 /compat/linux/usr/sap Second we will create directories as user orasid. These will all be subdirectories of /oracle/SID: &prompt.root; su - orasid &prompt.root; cd /oracle/SID &prompt.root; mkdir mirrlogA mirrlogB origlogA origlogB &prompt.root; mkdir sapdata1 sapdata2 sapdata3 sapdata4 sapdata5 sapdata6 &prompt.root; mkdir saparch sapreorg &prompt.root; exit For the Oracle 8.1.7-installation some additional directories are needed: &prompt.root; su - orasid &prompt.root; cd /oracle &prompt.root; mkdir 805_32 &prompt.root; mkdir client stage &prompt.root; mkdir client/80x_32 &prompt.root; mkdir stage/817_32 &prompt.root; cd /oracle/SID &prompt.root; mkdir 817_32 The directory client/80x_32 is used with exactly this name. Don't replace the x with some number or anything. In the third step we create directories as user sidadm: &prompt.root; su - sidadm &prompt.root; cd /usr/sap &prompt.root; mkdir SID &prompt.root; mkdir trans &prompt.root; exit Entries in /etc/services SAP R/3 requires some entries in file /etc/services, which will not be set correctly during installation under FreeBSD. Please add the following entries (you need at least those entries corresponding to the instance number - in this case, 00. It will do no harm adding all entries from 00 to 99 for dp, gw, sp and ms). If you are going to use a saprouter or need to access SAP OSS, you also need 99, as port 3299 is usually used for the saprouter process on the target system: sapdp00 3200/tcp # SAP Dispatcher. 3200 + Instance-Number sapgw00 3300/tcp # SAP Gateway. 3300 + Instance-Number sapsp00 3400/tcp # 3400 + Instance-Number sapms00 3500/tcp # 3500 + Instance-Number sapmsSID 3600/tcp # SAP Message Server. 3600 + Instance-Number sapgw00s 4800/tcp # SAP Secure Gateway 4800 + Instance-Number Necessary Locales locale SAP requires at least two locales that are not part of the default RedHat installation. SAP offers the required RPMs as download from their FTP-server (which is only accessible if you are a customer with OSS-access). See note 0171356 for a list of RPMs you need. It is also possible to just create appropriate links (for example from de_DE and en_US ), but I would not recommend this for a production system (so far it worked with the IDES system without any problems, though). The following locales are needed: de_DE.ISO-8859-1 en_US.ISO-8859-1 Create the links like this: &prompt.root; cd /compat/linux/usr/share/locale &prompt.root; ln -s de_DE de_DE.ISO-8859-1 &prompt.root; ln -s en_US en_US.ISO-8859-1 If they are not present, there will be some problems during the installation. If these are then subsequently ignored (by setting the status of the offending steps to OK in file CENTRDB.R3S), it will be impossible to log onto the SAP-system without some additional effort. Kernel Tuning kernel tuning SAP R/3 Systems need a lot of resources. I therefore added the following parameters to my kernel config-file: # Set these for memory pigs (SAP and Oracle): options MAXDSIZ="(1024*1024*1024)" options DFLDSIZ="(1024*1024*1024)" # System V options needed. options SYSVSHM #SYSV-style shared memory options SHMMAXPGS=262144 #max amount of shared mem. pages #options SHMMAXPGS=393216 #use this for the 46C inst.parameters options SHMMNI=256 #max number of shared memory ident if. options SHMSEG=100 #max shared mem.segs per process options SYSVMSG #SYSV-style message queues options MSGSEG=32767 #max num. of mes.segments in system options MSGSSZ=32 #size of msg-seg. MUST be power of 2 options MSGMNB=65535 #max char. per message queue options MSGTQL=2046 #max amount of msgs in system options SYSVSEM #SYSV-style semaphores options SEMMNU=256 #number of semaphore UNDO structures options SEMMNS=1024 #number of semaphores in system options SEMMNI=520 #number of semaphore identifiers options SEMUME=100 #number of UNDO keys The minimum values are specified in the documentation that comes from SAP. As there is no description for Linux, see the HP-UX-section (32-bit) for further information. As the system for the 4.6C SR2 installation has more main memory, the shared segments can be larger both for SAP and Oracle, therefore choose a larger number of shared memory pages. With the default installation of FreeBSD 4.5 on x386, leave MAXDSIZ and DFLDSIZ at 1 GB maximum. Otherwise, strange errors like ORA-27102: out of memory and Linux Error: 12: Cannot allocate memory might happen. Installing SAP R/3 Preparing SAP CDROMs There are many CDROMs to mount and unmount during the installation. Assuming you have enough CDROM-drives, you can just mount them all. I decided to copy the CDROM contents to corresponding directories: /oracle/SID/sapreorg/cd-name where cd-name was one of KERNEL, RDBMS, EXPORT1, EXPORT2, EXPORT3, EXPORT4, EXPORT5 and EXPORT6 for the 4.6B/IDES-installation, and KERNEL, RDBMS, DISK1, DISK2, DISK3, DISK4 and LANG for the 4.6C SR2-installation. All the filenames on the mounted CDs should be in capital letters, otherwise use the option for mounting. So use the following commands: &prompt.root; mount_cd9660 -g /dev/cd0a /mnt &prompt.root; cp -R /mnt/* /oracle/SID/sapreorg/cd-name &prompt.root; umount /mnt - Running the install-script + Running the Install Script First you have to prepare an install-directory: &prompt.root; cd /oracle/SID/sapreorg &prompt.root; mkdir install &prompt.root; cd install Then the install-script is started, which will copy nearly all the relevant files into the install-directory: &prompt.root; /oracle/SID/sapreorg/KERNEL/UNIX/INSTTOOL.SH The IDES-Installation (4.6B) comes with a fully customized SAP R/3 Demo-System, so there are six instead of just three EXPORT-CDs. At this point the installation template CENTRDB.R3S is for installing a standard central instance (R/3 and Database), not the IDES central instance, so one needs to copy the corresponding CENTRDB.R3S from the EXPORT1 directory, otherwise R3SETUP will only ask for three EXPORT-CDs. The newer SAP 4.6C SR2-release comes with four EXPORT-CDs. The parameter-file that controls the installation-steps is CENTRAL.R3S. Contrary to earlier releases there are no separate installation templates for a central instance with or without database. SAP is using a separate template for DB-installation. To restart the installation later it is however sufficient to restart with the original file. During and after installation, SAP requires hostname to return the computer name only, not the fully qualified domain name. So either set the hostname accordingly, or set an alias with alias hostname='hostname -s' for both orasid and sidadm (and for root at least during installation steps performed as root). It is also possible to adjust the installed profile- and login-scripts of both users that are installed during SAP-installation. Start R3SETUP 4.6B Make sure LD_LIBRARY_PATH is set correctly: &prompt.root; export LD_LIBRARY_PATH=/oracle/IDS/lib:/sapmnt/IDS/exe:/oracle/805_32/lib Start R3SETUP as root from installation directory: &prompt.root; cd /oracle/IDS/sapreorg/install &prompt.root; ./R3SETUP -f CENTRDB.R3S The script then asks some questions (defaults in brackets, followed by actual input): Question Default Input Enter SAP System ID [C11] IDSEnter Enter SAP Instance Number [00] Enter Enter SAPMOUNT Directory [/sapmnt] Enter Enter name of SAP central host [troubadix.domain.de] Enter Enter name of SAP db host [troubadix] Enter Select character set [1] (WE8DEC) Enter Enter Oracle server version (1) Oracle 8.0.5, (2) Oracle 8.0.6, (3) Oracle 8.1.5, (4) Oracle 8.1.6 1Enter Extract Oracle Client archive [1] (Yes, extract) Enter Enter path to KERNEL CD [/sapcd] /oracle/IDS/sapreorg/KERNEL Enter path to RDBMS CD [/sapcd] /oracle/IDS/sapreorg/RDBMS Enter path to EXPORT1 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT1 Directory to copy EXPORT1 CD [/oracle/IDS/sapreorg/CD4_DIR] Enter Enter path to EXPORT2 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT2 Directory to copy EXPORT2 CD [/oracle/IDS/sapreorg/CD5_DIR] Enter Enter path to EXPORT3 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT3 Directory to copy EXPORT3 CD [/oracle/IDS/sapreorg/CD6_DIR] Enter Enter path to EXPORT4 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT4 Directory to copy EXPORT4 CD [/oracle/IDS/sapreorg/CD7_DIR] Enter Enter path to EXPORT5 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT5 Directory to copy EXPORT5 CD [/oracle/IDS/sapreorg/CD8_DIR] Enter Enter path to EXPORT6 CD [/sapcd] /oracle/IDS/sapreorg/EXPORT6 Directory to copy EXPORT6 CD [/oracle/IDS/sapreorg/CD9_DIR] Enter Enter amount of RAM for SAP + DB 850Enter (in Megabytes) Service Entry Message Server [3600] Enter Enter Group-ID of sapsys [101] Enter Enter Group-ID of oper [102] Enter Enter Group-ID of dba [100] Enter Enter User-ID of sidadm [1000] Enter Enter User-ID of orasid [1002] Enter Number of parallel procs [2] Enter If you had not copied the CDs to the different locations, then the SAP-Installer cannot find the CD needed (identified by the LABEL.ASC-File on CD) and would then ask you to insert and mount the CD and confirm or enter the mount path. The CENTRDB.R3S might not be error-free. In my case, it requested EXPORT4 again (but indicated the correct key (6_LOCATION, then 7_LOCATION etc.), so one can just continue with entering the correct values. Do not get irritated. Apart from some problems mentioned below, everything should go straight through up to the point where the Oracle database software needs to be installed. Start R3SETUP 4.6C SR2 Make sure LD_LIBRARY_PATH is set correctly. This is a different value from the 4.6B installation with Oracle 8.0.5: &prompt.root; export LD_LIBRARY_PATH=/sapmnt/PRD/exe:/oracle/PRD/817_32/lib Start R3SETUP as user root from installation directory: &prompt.root; cd /oracle/PRD/sapreorg/install &prompt.root; ./R3SETUP -f CENTRAL.R3S The script then asks some questions (defaults in brackets, followed by actual input): Question Default Input Enter SAP System ID [C11] PRDEnter Enter SAP Instance Number [00] Enter Enter SAPMOUNT Directory [/sapmnt] Enter Enter name of SAP central host [majestix] Enter Enter Database System ID [PRD] PRDEnter Enter name of SAP db host [majestix] Enter Select character set [1] (WE8DEC) Enter Enter Oracle server version (2) Oracle 8.1.7 2Enter Extract Oracle Client archive [1] (Yes, extract) Enter Enter path to KERNEL CD [/sapcd] /oracle/PRD/sapreorg/KERNEL Enter amount of RAM for SAP + DB 2044 1800Enter (in Megabytes) Service Entry Message Server [3600] Enter Enter Group-ID of sapsys [100] Enter Enter Group-ID of oper [101] Enter Enter Group-ID of dba [102] Enter Enter User-ID of oraprd [1002] Enter Enter User-ID of prdadm [1000] Enter LDAP support 3Enter (no support) Installation step completed [1] (continue) Enter Choose installation service [1] (DB inst,file) Enter So far, creation of users gives an error during installation in phases OSUSERDBSID_IND_ORA (for creating user orasid) and OSUSERSIDADM_IND_ORA (creating user sidadm). Apart from some problems mentioned below, everything should go straight through up to the point where the Oracle database software needs to be installed. Installing Oracle 8.0.5 Please see the corresponding SAP-Notes and Oracle Readmes regarding Linux and Oracle DB for possible problems. Most if not all problems stem from incompatible libraries. For more information on installing Oracle, refer to the Installing Oracle chapter. Installing the Oracle 8.0.5 with orainst If Oracle 8.0.5 is to be used, some additional libraries are needed for successfully relinking, as Oracle 8.0.5 was linked with an old glibc (RedHat 6.0), but RedHat 6.1 already uses a new glibc. So you have to install the following additional packages to ensure that linking will work: compat-libs-5.2-2.i386.rpm compat-glibc-5.2-2.0.7.2.i386.rpm compat-egcs-5.2-1.0.3a.1.i386.rpm compat-egcs-c++-5.2-1.0.3a.1.i386.rpm compat-binutils-5.2-2.9.1.0.23.1.i386.rpm See the corresponding SAP-Notes or Oracle Readmes for further information. If this is no option (at the time of installation I did not have enough time to check this), one could use the original binaries, or use the relinked binaries from an original RedHat System. For compiling the intelligent agent, the RedHat Tcl package must be installed. If you cannot get tcl-8.0.3-20.i386.rpm, a newer one like tcl-8.0.5-30.i386.rpm for RedHat 6.1 should also do. Apart from relinking, the installation is straightforward: &prompt.root; su - oraids &prompt.root; export TERM=xterm &prompt.root; export ORACLE_TERM=xterm &prompt.root; export ORACLE_HOME=/oracle/IDS &prompt.root; cd /ORACLE_HOME/orainst_sap &prompt.root; ./orainst Confirm all Screens with Enter until the software is installed, except that one has to deselect the Oracle On-Line Text Viewer, as this is not currently available for Linux. Oracle then wants to relink with i386-glibc20-linux-gcc instead of the available gcc, egcs or i386-redhat-linux-gcc . Due to time constrains I decided to use the binaries from an Oracle 8.0.5 PreProduction release, after the first attempt at getting the version from the RDBMS-CD working, failed, and finding and accessing the correct RPMs was a nightmare at that time. - Installing the Oracle 8.0.5 Pre-Production release for + <title>Installing the Oracle 8.0.5 Pre-production Release for Linux (Kernel 2.0.33) This installation is quite easy. Mount the CD, start the installer. It will then ask for the location of the Oracle home directory, and copy all binaries there. I did not delete the remains of my previous RDBMS-installation tries, though. Afterwards, Oracle Database could be started with no problems. - Installing the Oracle 8.1.7 linux tarball + Installing the Oracle 8.1.7 Linux Tarball Take the tarball oracle81732.tgz you produced from the installation directory on a Linux system and untar it to /oracle/SID/817_32/. Continue with SAP R/3 Installation First check the environment settings of users idsamd (sidadm) and oraids (orasid). They should now both have the files .profile, .login and .cshrc which are all using hostname. In case the system's hostname is the fully qualified name, you need to change hostname to hostname -s within all three files. Database Load Afterwards, R3SETUP can either be restarted or continued (depending on whether exit was chosen or not). R3SETUP then creates the tablespaces and loads the data (for 46B IDES, from EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) with R3load into the database. When the database load is finished (might take a few hours), some passwords are requested. For test installations, one can use the well known default passwords (use different ones if security is an issue!): Question Input Enter Password for sapr3 sapEnter Confirum Password for sapr3 sapEnter Enter Password for sys change_on_installEnter Confirm Password for sys change_on_installEnter Enter Password for system managerEnter Confirm Password for system managerEnter At this point I had a few problems with dipgntab during the 4.6B installation. Listener Start the Oracle-Listener as user orasid as follows: &prompt.user; umask 0; lsnrctl start Otherwise you might get ORA-12546 as the sockets will not have the correct permissions. See SAP note 072984. Updating MNLS Tables If you plan to import non-Latin-1 languages into the SAP-System, you have to update the Multi National Language Support tables. This is described in the SAP OSS-Notes 15023 and 45619. Otherwise, you can skip this question during SAP installation. If you don't need MNLS, it is still necessary to check table TCPDB and initializing it if this hasn't been done. See SAP note 0015023 and 0045619 for further information. Post-installation Steps Request SAP R/3 License Key You have to request your SAP R/3 License Key. This is needed, as the temporary license that was installed during installation is only valid for four weeks. First get the hardware key. Log on as user idsadm and call saplicense: &prompt.root; /sapmnt/IDS/exe/saplicense -get Calling saplicense without options gives a list of options. Upon receiving the license key, it can be installed using: &prompt.root; /sapmnt/IDS/exe/saplicense -install You are then required to enter the following values: SAP SYSTEM ID = SID, 3 chars CUSTOMER KEY = hardware key, 11 chars INSTALLATION NO = installation, 10 digits EXPIRATION DATE = yyyymmdd, usually "99991231" LICENSE KEY = license key, 24 chars Creating Users Create a user within client 000 (for some tasks required to be done within client 000, but with a user different from users sap* and ddic). As a user name, I usually choose wartung (or service in English). Profiles required are sap_new and sap_all. For additional safety the passwords of default users within all clients should be changed (this includes users sap* and ddic). Configure Transport System, Profile, Operation Modes, Etc. Within client 000, user different from ddic and sap*, do at least the following: Task Transaction Configure Transport System, eg as Stand-Alone Transport Domain Entity STMS Create / Edit Profile for System RZ10 Maintain Operation Modes and Instances RZ04 These and all the other post-installation steps are thoroughly described in SAP installation guides. Edit init<replaceable>sid</replaceable>.sap (initIDS.sap) The file /oracle/IDS/dbs/initIDS.sap contains the SAP backup profile. Here the size of the tape to be used, type of compression and so on need to be defined. To get this running with sapdba / brbackup, I changed the following values: compress = hardware archive_function = copy_delete_save cpio_flags = "-ov --format=newc --block-size=128 --quiet" cpio_in_flags = "-iuv --block-size=128 --quiet" tape_size = 38000M tape_address = /dev/nsa0 tape_address_rew = /dev/sa0 Explanations: compress The tape I use is a HP DLT1 which does hardware compression. archive_function This defines the default behavior for saving Oracle archive logs: New logfiles are saved to tape, already saved logfiles are saved again and are then deleted. This prevents lots of trouble if you need to recover the database, and one of the archive-tapes has gone bad. cpio_flags Default is to use -B which sets block size to 5120 Bytes. For DLT-Tapes, HP recommends at least 32 K block size, so I used --block-size=128 for 64 K. --format=newc is needed I have inode numbers greater than 65535. The last option --quiet is needed as otherwise brbackup complains as soon as cpio outputs the numbers of blocks saved. cpio_in_flags Flags needed for loading data back from tape. Format is recognized automatically. tape_size This usually gives the raw storage capability of the tape. For security reason (we use hardware compression), the value is slightly lower than the actual value. tape_address The non-rewindable device to be used with cpio. tape_address_rew The rewindable device to be used with cpio. Configuration Issues after Installation The following SAP-parameters should be tuned after installation (examples for IDES 46B, 1 GB memory): Name Value ztta/roll_extension 250000000 abap/heap_area_dia 300000000 abap/heap_area_nondia 400000000 em/initial_size_MB 256 em/blocksize_kB 1024 ipc/shm_psize_40 70000000 SAP-Note 0013026: Name Value ztta/dynpro_area 2500000 SAP-Note 0157246: Name Value rdisp/ROLL_MAXFS 16000 rdisp/PG_MAXFS 30000 With the above parameters, on a system with 1 gigabyte of memory, one may find memory consumption similar to: Mem: 547M Active, 305M Inact, 109M Wired, 40M Cache, 112M Buf, 3492K Free - Problems During Installation + Problems during Installation - Restart R3SETUP after fixing a problem + Restart R3SETUP after Fixing a Problem R3SETUP stops if it encounters an error. If you have looked at the corresponding logfiles and fixed the error, you have to start R3SETUP again, usually selecting REPEAT as option for the last step R3SETUP complained about. To restart R3SETUP, just start it with the corresponding R3S-file: &prompt.root; ./R3SETUP -f CENTRDB.R3S for 4.6B, or with &prompt.root; ./R3SETUP -f CENTRAL.R3S for 4.6C, no matter whether the error occurred with CENTRAL.R3S or DATABASE.R3S. At some stages, R3SETUP assumes that both database- and SAP-processes are up and running (as those were steps it already completed). Should errors occur and for example the database could not be started, you have to start both database and SAP by hand after you fixed the errors and before starting R3SETUP again. Don't forget to also start the oracle listener again (as orasid with umask 0; lsnrctl start) if it was also stopped (for example due to a necessary reboot of the system). - OSUSERSIDADM_IND_ORA During R3SETUP + OSUSERSIDADM_IND_ORA during R3SETUP If R3SETUP complains at this stage, edit the template file R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S (4.6C)). Locate [OSUSERSIDADM_IND_ORA] or search for the only STATUS=ERROR-entry and edit the following values: HOME=/home/sidadm (was empty) STATUS=OK (had status ERROR) Then you can restart R3SETUP again. - OSUSERDBSID_IND_ORA During R3SETUP + OSUSERDBSID_IND_ORA during R3SETUP Possibly R3SETUP also complains at this stage. The error here is similar to the one in phase OSUSERSIDADM_IND_ORA. Just edit the template file R3SETUP used at that time (CENTRDB.R3S (4.6B) or either CENTRAL.R3S or DATABASE.R3S (4.6C)). Locate [OSUSERDBSID_IND_ORA] or search for the only STATUS=ERROR-entry and edit the following value in that section: STATUS=OK Then restart R3SETUP. - <errorname>oraview.vrf FILE NOT FOUND</errorname> During Oracle Installation + <errorname>oraview.vrf FILE NOT FOUND</errorname> during Oracle Installation You have not deselected Oracle On-Line Text Viewer before starting the installation. This is marked for installation even though this option is currently not available for Linux. Deselect this product inside the Oracle installation menu and restart installation. - <errorname>TEXTENV_INVALID</errorname> During R3SETUP, RFC or SAPGUI Start + <errorname>TEXTENV_INVALID</errorname> during R3SETUP, RFC or SAPGUI Start If this error is encountered, the correct locale is missing. SAP note 0171356 lists the necessary RPMs that need be installed (eg saplocales-1.0-3, saposcheck-1.0-1 for RedHat 6.1). In case you ignored all the related errors and set the corresponding status from ERROR to OK (in CENTRDB.R3S) every time R3SETUP complained and just restarted R3SETUP, the SAP-System will not be properly configured and you will then not be able to connect to the system with a sapgui, even though the system can be started. Trying to connect with the old Linux sapgui gave the following messages: Sat May 5 14:23:14 2001 *** ERROR => no valid userarea given [trgmsgo. 0401] Sat May 5 14:23:22 2001 *** ERROR => ERROR NR 24 occured [trgmsgi. 0410] *** ERROR => Error when generating text environment. [trgmsgi. 0435] *** ERROR => function failed [trgmsgi. 0447] *** ERROR => no socket operation allowed [trxio.c 3363] Speicherzugriffsfehler This behavior is due to SAP R/3 being unable to correctly assign a locale and also not being properly configured itself (missing entries in some database tables). To be able to connect to SAP, add the following entries to file DEFAULT.PFL (see note 0043288): abap/set_etct_env_at_new_mode = 0 install/collate/active = 0 rscp/TCP0B = TCP0B Restart the SAP system. Now you can connect to the system, even though country-specific language settings might not work as expected. After correcting country-settings (and providing the correct locales), these entries can be removed from DEFAULT.PFL and the SAP system can be restarted. <errorcode>ORA-00001</errorcode> This error only happened with Oracle 8.1.7 on FreeBSD 4.5. The reason was that the Oracle database could not initialize itself properly and crashed, leaving semaphores and shared memory on the system. The next try to start the database then returned ORA-00001. Find them with ipcs -a and remove them with ipcrm. - <errorcode>ORA-00445</errorcode> (background process PMON did not start) + <errorcode>ORA-00445</errorcode> (Background Process PMON Did Not Start) This error happened with Oracle 8.1.7. This error is reported if the Database is started with the usual startsap-script (for example startsap_majestix_00) as user prdadm. A possible workaround is to start the database as user oraprd instead with svrmgrl: &prompt.user; svrmgrl SVRMGR> connect internal; SVRMGR> startup; SVRMGR> exit - <errorcode>ORA-12546</errorcode> (start Listener with Correct Permissions) + <errorcode>ORA-12546</errorcode> (Start Listener with Correct Permissions) Start the Oracle Listener as user oraids with the following commands: &prompt.root; umask 0; lsnrctl start Otherwise you might get ORA-12546 as the sockets will not have the correct permissions. See SAP note 0072984. - <errorcode>ORA-27102</errorcode> (out of memory) + <errorcode>ORA-27102</errorcode> (Out of Memory) This error happened whilst trying to use values for MAXDSIZ and DFLDSIZ greater than 1 GB (1024x1024x1024). Additionally, I got Linux Error 12: Cannot allocate memory. - [DIPGNTAB_IND_IND] During R3SETUP + [DIPGNTAB_IND_IND] during R3SETUP In general, see SAP note 0130581 (R3SETUP step DIPGNTAB terminates). During the IDES-specific installation, for some reasons the installation process was not using the proper SAP system name IDS, but the empty string "" instead. This lead to some minor problems with accessing directories, as the paths are generated dynamically using SID (in this case IDS). So instead of accessing: /usr/sap/IDS/SYS/... /usr/sap/IDS/DVMGS00 the following paths were used: /usr/sap//SYS/... /usr/sap/D00 To continue with the installation, I created a link and an additional directory: &prompt.root; pwd /compat/linux/usr/sap &prompt.root; ls -l total 4 drwxr-xr-x 3 idsadm sapsys 512 May 5 11:20 D00 drwxr-x--x 5 idsadm sapsys 512 May 5 11:35 IDS lrwxr-xr-x 1 root sapsys 7 May 5 11:35 SYS -> IDS/SYS drwxrwxr-x 2 idsadm sapsys 512 May 5 13:00 tmp drwxrwxr-x 11 idsadm sapsys 512 May 4 14:20 trans I also found SAP notes (0029227 and 0008401) describing this behavior. I did not encounter any of these problems with the SAP 4.6C-installation. - [RFCRSWBOINI_IND_IND] During R3SETUP + [RFCRSWBOINI_IND_IND] during R3SETUP During installation of SAP 4.6C, this error was just the result of another error happening earlier during installation. In this case, you have to look through the corresponding logfiles and correct the real problem. If after looking through the logfiles this error is indeed the correct one (check the SAP-notes), you can set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RSWBOINS from transaction SE38. See SAP note 0162266 for additional information about phase RFCRSWBOINI and RFCRADDBDIF. - [RFCRADDBDIF_IND_IND] During R3SETUP + [RFCRADDBDIF_IND_IND] during R3SETUP Here the same restrictions apply: Make sure by looking through the logfiles, that this error is not caused by some previous problems. If you can confirm that SAP-Note 0162266 applies, just set STATUS of the offending step from ERROR to OK (file CENTRDB.R3S) and restart R3SETUP. After installation, you have to execute the report RADDBDIF from transaction SE38. - sigaction sig31: File size limit exceeded + <errorcode>sigaction sig31: File size limit exceeded</errorcode> This error occurred during start of SAP-processes disp+work. If starting SAP with the startsap-script, subprocesses are then started which detach and do the dirty work of starting all other SAP processes. As a result, the script itself won't notice if something goes wrong. To check whether the SAP processes did start properly, have a look at the process status with ps ax | grep SID, which will give you a list of all Oracle- and SAP-processes. If it looks like some processes are missing or if you can't connect to the SAP-System, look at the corresponding logfiles which can be found at /usr/sap/SID/DVEBMGSnr/work/. The files to look at are dev_ms and dev_disp. Signal 31 happens here if the amount of shared memory used by Oracle and SAP exceed the one defined within the kernel configuration file and could be resolved by using a larger value: # larger value for 46C production systems: options SHMMAXPGS=393216 # smaller value sufficient for 46B: #options SHMMAXPGS=262144 - Start of saposcol failed + Start of saposcol Failed There are some problems with Program saposcol (version 4.6D). The SAP-System is using saposcol to collect data about the system performance. This program is not needed to use the SAP-System, so this problem can be considered a minor one. The older versions (4.6B) does work, but doesn't collect all the data (many calls will just return 0, for example for CPU usage). Advanced Topics If you are curious as to how the Linux binary compatibility works, this is the section you want to read. Most of what follows is based heavily on an email written to &a.chat; by Terry Lambert tlambert@primenet.com (Message ID: <199906020108.SAA07001@usr09.primenet.com>). How Does It Work? execution class loader FreeBSD has an abstraction called an execution class loader. This is a wedge into the &man.execve.2; system call. What happens is that FreeBSD has a list of loaders, instead of a single loader with a fallback to the #! loader for running any shell interpreters or shell scripts. Historically, the only loader on the Unix platform examined the magic number (generally the first 4 or 8 bytes of the file) to see if it was a binary known to the system, and if so, invoked the binary loader. If it was not the binary type for the system, the &man.execve.2; call returned a failure, and the shell attempted to start executing it as shell commands. The assumption was a default of whatever the current shell is. Later, a hack was made for &man.sh.1; to examine the first two characters, and if they were :\n, then it invoked the &man.csh.1; shell instead (we believe SCO first made this hack). What FreeBSD does now is go through a list of loaders, with a generic #! loader that knows about interpreters as the characters which follow to the next whitespace next to last, followed by a fallback to /bin/sh. ELF For the Linux ABI support, FreeBSD sees the magic number as an ELF binary (it makes no distinction between FreeBSD, Solaris, Linux, or any other OS which has an ELF image type, at this point). Solaris The ELF loader looks for a specialized brand, which is a comment section in the ELF image, and which is not present on SVR4/Solaris ELF binaries. For Linux binaries to function, they must be branded as type Linux; from &man.brandelf.1;: &prompt.root; brandelf -t Linux file When this is done, the ELF loader will see the Linux brand on the file. ELF branding When the ELF loader sees the Linux brand, the loader replaces a pointer in the proc structure. All system calls are indexed through this pointer (in a traditional Unix system, this would be the sysent[] structure array, containing the system calls). In addition, the process is flagged for special handling of the trap vector for the signal trampoline code, and several other (minor) fix-ups that are handled by the Linux kernel module. The Linux system call vector contains, among other things, a list of sysent[] entries whose addresses reside in the kernel module. When a system call is called by the Linux binary, the trap code dereferences the system call function pointer off the proc structure, and gets the Linux, not the FreeBSD, system call entry points. In addition, the Linux mode dynamically reroots lookups; this is, in effect, what the union option to FS mounts (not the unionfs!) does. First, an attempt is made to lookup the file in the /compat/linux/original-path directory, then only if that fails, the lookup is done in the /original-path directory. This makes sure that binaries that require other binaries can run (e.g., the Linux toolchain can all run under Linux ABI support). It also means that the Linux binaries can load and exec FreeBSD binaries, if there are no corresponding Linux binaries present, and that you could place a &man.uname.1; command in the /compat/linux directory tree to ensure that the Linux binaries could not tell they were not running on Linux. In effect, there is a Linux kernel in the FreeBSD kernel; the various underlying functions that implement all of the services provided by the kernel are identical to both the FreeBSD system call table entries, and the Linux system call table entries: file system operations, virtual memory operations, signal delivery, System V IPC, etc… The only difference is that FreeBSD binaries get the FreeBSD glue functions, and Linux binaries get the Linux glue functions (most older OS's only had their own glue functions: addresses of functions in a static global sysent[] structure array, instead of addresses of functions dereferenced off a dynamically initialized pointer in the proc structure of the process making the call). Which one is the native FreeBSD ABI? It does not matter. Basically the only difference is that (currently; this could easily be changed in a future release, and probably will be after this) the FreeBSD glue functions are statically linked into the kernel, and the Linux glue functions can be statically linked, or they can be accessed via a kernel module. Yeah, but is this really emulation? No. It is an ABI implementation, not an emulation. There is no emulator (or simulator, to cut off the next question) involved. So why is it sometimes called Linux emulation? To make it hard to sell FreeBSD! Really, it is because the historical implementation was done at a time when there was really no word other than that to describe what was going on; saying that FreeBSD ran Linux binaries was not true, if you did not compile the code in or load a module, and there needed to be a word to describe what was being loaded—hence the Linux emulator.