diff --git a/LDP/howto/linuxdoc/Boot+Root+Raid+LILO.sgml b/LDP/howto/linuxdoc/Boot+Root+Raid+LILO.sgml new file mode 100644 index 00000000..e993e04e --- /dev/null +++ b/LDP/howto/linuxdoc/Boot+Root+Raid+LILO.sgml @@ -0,0 +1,1212 @@ + + +
+ + +Boot + Root + Raid + Lilo : Software Raid HOWTO + +<author>Michael Robinton, <url url="mailto:michael@bizsystems.com" + name="Michael@BizSystems.com"> +<date>v1.03, May 4, 2000 +<!-- + 5-4-00 update links to reflect document name on LINUX DOC PROJECT + +--> +<abstract> +This document provides a cookbook for setting up root raid using the +0.90 raidtools for bootable raid mounted on root using standard LILO. + +Also covered is the conversion of a conventional disk to a raid1 or raid5 +mirror set without the loss of data on the original disk. +</abstract> +<!-- Table of contents --> +<toc> + +<sect>Introduction + +<p> +<sect1>Acknowledgements + +<p> +The essence of the information I've put together here was originally provided by +Harald Nordgård-Hansen <tt/</<url url="mailto:hnh@bukharin.hiof.no" + name="hnh@bukharin.hiof.no"><tt/>/ and posted to the raid +mail list in a lilo.conf file with commentary by Martin Bene <tt/</<url +url="mailto:mb@sime.com" +name="mb@sime.com"><tt/>/. Many thanks for your contribution. I've tried to +put this information and the helpful work of many others who contribute to +the raid mail list and linux raid project into a <bf/COOKBOOK/ form, +including many examples from real systems so that bootable +root raid is easy to set up and understand. One section is devoted to the +conversion of a standard single drive system to RAID. The key to the +conversion, in my humble opinion, is the understanding of bootable root +raid. + +<sect1>Bugs +<p> +Yes, I'm sure there are some. If you'd be good enough to report them, I will +correct the document. ;-) + +<sect1>Copyright Notice + +<p> +This document is GNU copyleft by Michael Robinton +<url url="mailto:michael@bizsystems.com" name="Michael@BizSystems.com">. +<p> + Permission to use, copy, distribute this document for any + purpose is hereby granted, provided that the author's / editor's + name and this notice appear in all copies and/or supporting + documents; and that an unmodified version of this document is + made freely available. This document is distributed in the hope + that it will be useful, but WITHOUT ANY WARRANTY, either + expressed or implied. While every effort has been taken to + ensure the accuracy of the information documented herein, the + author / editor / maintainer assumes NO RESPONSIBILITY for any + errors, or for any damages, direct or consequential, as a result + of the use of the information documented herein. + + +<sect>What you need BEFORE YOU START + +<p> +The packages you need and the documentation that answers the most common +questions about setting up and running raid are listed below. Please review +them throughly. + +<sect1>Required Packages + +<p> +You need to obtain the most recent versions of these packages. +<itemize> +<item>a linux kernel that supports raid, initrd +<quote> I used <url name="linux-2.2.14" + url="ftp://ftp.kernel.org/pub/linux/kernel/v2.2/"> + from kernel.org</quote> +<item><url name="ftp://ftp.kernel.org/pub/linux/daemons/raid/alpha/" + url="ftp://ftp.kernel.org/pub/linux/daemons/raid/alpha/"> + the most recent tools and patch that adds support for modern raid1/4/5 +<quote> I used <url name="http://people.redhat.com/mingo/raid-patches/" +url="http://people.redhat.com/mingo/raid-patches/raid-2.2.14-B1"></quote> +</itemize> + +<sect1>Where to get Up-to-date copies of this document. +<p> +Click here to browse the <url +url="ftp://ftp.bizsystems.com/pub/raid/Boot+Root+Raid+LILO.html" +name="author's latest version"> of +this document. Corrections and suggestions welcome! +<p> +Boot Root Raid minihowto +<p> +Available in LaTeX (for DVI and PostScript), plain text, and HTML. +<quote> <url +url="http://www.linuxdoc.org/HOWTO/mini/Boot+Root+Raid+LILO.html" + name=" http://www.linuxdoc.org/HOWTO/mini/Boot+Root+Raid+LILO.html"> +</quote> +Available in SGML and HTML. +<quote> <url url="ftp://ftp.bizsystems.net/pub/raid/" + name="ftp.bizsystems.net/pub/raid/"> +</quote> + +<sect1>Documentation -- Recommended Reading + +<p> +<bf>If you plan on using raid1/5 over raid0, please read:</bf> +<quote><bf>/usr/src/linux/Documentation/initrd.txt</bf></quote> + +<p> +as well as the documentation and man pages that accompany +the raidtools set. + +<p> +and..... <url name="Software-RAID-HOWTO.html" + url="http://metalab.unc.edu/mdw/HOWTO/Software-RAID-HOWTO.html"> + +<sect1>RAID resources + +<p> +Mailing lists can be joined at: +<itemize> +<item>This one seems quiet: <url name="majordomo@nuclecu.unam.mx" + url="mailto:majordomo@nuclecu.unam.mx"><it> send a message to</it> + <bf/subscribe raiddev/<p> + send mail to: <url name="raiddev@nuclecu.unam.mx" + url="mailto:raiddev@nuclecu.unam.mx"> +<p>  +<item>Raid development: <url name="majordomo@vger.rutgers.edu" + url="mailto:majordomo@vger.rutgers.edu"><it> send a message to</it> + <bf/subscribe linux-raid/<p> + send mail to: <url name="linux-raid@vger.rutgers.edu" + url="mailto:linux-raid@vger.rutgers.edu"> + <it>(this seems to be the most active list)</it> +</itemize> + + +<sect>Bootable Raid + +<p> +I'm not going to cover the fundamentals of setting up raid0/1/5 on +Linux, that is covered in detail elsewhere. The problem I will address is +setting up raid on root and making it bootable with <bf/standard/ LILO. The +documentation that comes with the LILO sources (not the man pages) and with +the raidtools-0.90, covers the details of booting and boot parameters as +well as general raid setup - respectively. + +<p> +There are two scenarios which are covered here. Set up of bootable root raid +and the conversion of an existing non-raid system to bootable root raid +without data loss. + +<sect1>Booting RAID 1 with standard LILO + +<p> +To make the boot information redundant and easy to maintain, set up a small +RAID1 and mount it on the <bf>/boot</bf> directory of your +system disk. LILO does not know about device 0x9?? and can not find the +information at boot time because the raid sub system is not active +then. As a simple work around, you can pass LILO the geometry information of +the drive(s) and from that, LILO can determine the position of the information +needed to load the kernel even though it is on the RAID1 partition. This is +because the RAID1 partition is the same as a standard partition but with a +raid super-block written at the end. The boot raid set should fall with +the first 1024 +mbytes of the disk drive. In theory the start of the raid partition could +fall anywhere in the 1024 megs, but in practice I was unable to get it to +work unless the boot-raid started at the first block of the set. This is +probably because of something dumb that I did, but it was not worth +following up at the time. Since then I've simply set up all my systems with +the boot-raid set as the first partition. I have root raid system configurations +with bootable RAID1 mounted on <bf>/boot</bf> with root raid sets as +follows: RAID1, RAID5, RAID10 & RAID1-10 ( 1 mirror + 1 raid0 set). +The last has a very peculiar lilo file pair since none of the disk geometries +are the same, however, the principals are the same for the initial boot +process. The RAID10 and RAID1-10 root mounts require the use of +<it>initrd</it> to mount root after the boot process has taken place. +See the appendices for the configuration files for all of these example +systems. + +<p> +A conventional LILO config file stripped down looks like this: + +<verb> +# lilo.conf - assumes drive less than 1024 + boot = /dev/hda + delay = 40 # extra, but nice + vga = normal # not normally needed + image = /bzImage + root = /dev/hda1 + read-only + label = Linux +</verb> + +<p> +A raid LILO config file pair would look like this: + +<verb> +# lilo.conf.hda - primary ide master + disk=/dev/md0 + bios=0x80 + sectors=63 + heads=16 + cylinders=39770 + partition=/dev/md1 + start=63 + boot=/dev/hda + map=/boot/map + install=/boot/boot.b + image=/boot/bzImage + root=/dev/md0 + read-only + label=LinuxRaid + +# --------------------- + +# lilo.conf.hdc - secondary ide master + disk=/dev/md0 + bios=0x80 # see note below + sectors=63 + heads=16 + cylinders=39770 + partition=/dev/md1 + start=63 + boot=/dev/hdc # this is the other disk + map=/boot/map + install=/boot/boot.b + image=/boot/bzImage + root=/dev/md0 + read-only + label=LinuxRaid +</verb> + +# BIOS=line -- if your bios is smart enough (most are not) to detect that +that the first disk is missing or failed and will automatically boot from the second disk, +then <bf>bios=81</bf> would be the appropriate entry here. This is more +common with SCSI bios than IDE bios. I simply plan on relocating the drive +so it will replace the dead drive C: in the event of failure of the primary +boot drive. + +<p> +The geometry information for the drive can be obtained from fdisk with the +command: + +<verb> +fdisk -ul (little L) +fdisk -ul /dev/hda + +Disk /dev/hda: 16 heads, 63 sectors, 39770 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hda1 63 33263 16600+ fd Linux raid autodetect +/dev/hda2 33264 443519 205128 82 Linux swap +/dev/hda3 443520 40088159 19822320 fd Linux raid autodetect + +* note the listing of the START of each partition +</verb> + +<sect1>Detailed explaination of lilo.conf for raid boot + +<p> +The raid lilo.conf file above, commented in detail for each entry. + +<verb> +# lilo.conf.hda - primary ide master +# the location of the /boot directory that will be +# designated below as containing the kernel, map, etc... +# note that this is NOT the actual partition containing +# the boot image and info, but rather the device +# that logically contains this directory. +# in this example, /dev/md1 is mounted on /dev/md0/boot + disk=/dev/md0 + +# tell LILO which bios device to use for boot, i.e. C: drive + bios=0x80 + +# tell LILO the geometry of the device +# this is usually but not always the "logical" +# geometry. Check the /proc file system or watch +# the boot messages when the kernel probes for the drive +# + sectors=63 + heads=16 + cylinders=39770 + +# this is a dummy entry to make LILO happy so it +# will recognize the raid set 0x9?? and then find +# the START of the boot sector. To really see +# what this was for, read the documentation +# that comes with the LILO source distribution. +# This parameter "must" be different than the +# disk= entry above. It can be any other mdx +# device, used or unused and need not be the one +# that contains the /boot information +# + partition=/dev/md1 + +# the first sector of the partition containing /boot information + start=63 + +# the real device that LILO will write the boot information to + boot=/dev/hda + +# logically where LILO will put the boot information + map=/boot/map + install=/boot/boot.b + +# logically where lilo will find the kernel image + image=/boot/bzImage + +# standard stuff after this +# root may be a raid1/4/5 device + root=/dev/md0 + read-only + label=LinuxRaid +</verb> + +<sect>Upgrading from non-raid to RAID1/4/5 + +<p> +Upgrading a non-raid system to raid is fairly east and consists +of several discrete steps described below. The description is for a system +with a boot partition, root partition and swap partition. +<verb> +OLD disk in the existing system: + + /dev/hda1 boot, may be dos+lodlin or lilo + /dev/hda2 root + /dev/hda3 swap +</verb> +We will add an additional disk and convert the entire system to RAID1. You +could easily add several disks and make a RAID5 set instead using the same +procedure. + +<sect1>Step 1 - prepare a new kernel + +<p> +Download a clean kernel, raidtools-0.90 (or the most recent version), and +the kernel patch to upgrade the kernel to 0.90 raid. +<p> +Compile and install the raidtools and READ the documentation. +<p> +Compile and install the +kernel to support all the flavors (0/1/4/5 ?) of raid that you will be using. +Make sure to specify autostart of raid devices in the kernel configuration. +Test that the kernel boots properly and examine /proc/mdstat to see +that the raid flavors you will use are supported by the new kernel. + +<sect1>Step 2 - set up raidtab for your new raid. + +<p> +The new disk will be added to an additional IDE controller as the master +device, thus becomming /dev/hdc + +<verb> + /dev/hdc1 16megs -- more than enough for several kernel images + /dev/hdc2 most of the disk + /dev/hdc3 some more swap space, if needed. otherwise add to hdc2 +</verb> + +Change the partition types for /dev/hdc1 and /dev/hdc2 to "fd" for +raid-autostart. +<p> +Using the <bf/failed-disk/ parameter, create a raidtab for +the desired RAID1 configuration. The failed disk must be the last +entry in the table. +<p> +<verb> +# example raidtab +# md0 is the root array +raiddev /dev/md0 +raid-level 1 +nr-raid-disks 2 +chunk-size 32 +# Spare disks for hot reconstruction +nr-spare-disks 0 +persistent-superblock 1 +device /dev/hdc2 +raid-disk 0 +# this is our old disk, mark as failed for now +device /dev/hda2 +failed-disk 1 + +# md1 is the /boot array +raiddev /dev/md1 +raid-level 1 +nr-raid-disks 2 +chunk-size 32 +# Spare disks for hot reconstruction +nr-spare-disks 0 +persistent-superblock 1 +device /dev/hdc1 +raid-disk 0 +# boot is marked failed as well +device /dev/hda1 +failed-disk 1 +</verb> + +<sect1>Create, format, and configure RAID + +<p> +Create the md devices with the commands: +<verb> + mkraid /dev/md0 + mkraid /dev/md1 +</verb> + +The raid devices should be created and start. Examination of /proc/mdstat +should show the raid personalities in the kernel and the raid devices +running. +<p> +Format the boot and root devices with: +<verb> + mke2fs /dev/md0 + mke2fs /dev/md1 +</verb> +Mount the new root device somewhere handy and create the /boot directory and +mount the boot partition. +<verb> + mount /dev/md0 /mnt + mkdir /mnt/boot + mount /dev/md1 /mnt/boot +</verb> + +<sect1>Copy the current OS to the new raid device + +<p> +This is pretty straightforward. +<verb> + cd / + # set up a batch file to do this + cp -a /bin /mnt + cp -a /dev /mnt + cp -a /etc /mnt + cp -a (all directories except /mnt, /proc, and nsf mounts) /mnt +</verb> +This operation can be tricky if you have mounted or linked other disks to +your root file system. The example above assumes a very simple system, you +may have to modify the procedure somewhat. + +<sect1>Test your new RAID + +<p> +Make a boot floppy and rdev the kernel. + +<verb> + dd if=kernal.image of=/dev/fd0 bs=2k + rdev /dev/fd0 /dev/md0 + rdev -r /dev/fd0 0 + rdev -R /dev/fd0 1 +</verb> + +Modify the fstab on the RAID device to reflect the new mount points as +follows: +<verb> + /dev/md0 / ext2 defaults 1 1 + /dev/md1 /boot ext2 defaults 1 1 +</verb> + +Dismount the raid devices and boot the new file system to see that all works +correctly. + +<verb> + umount /mnt/boot + umount /mnt + raidstop /dev/md0 + raidstop /dev/md1 + shutdown -r now +</verb> + +Your RAID system should now be up and running in degraded mode with a floppy +boot disk. Carefully check that you transferred everything to the new raid +system. If you mess up here without a backup, YOU ARE DEAD! +<p> +If something did not work, reboot your old system and go back and fix things +up until your successfully complete this step. + +<sect1>Integrate old disk into raid array + +<p> +Success in the previous step means that the raid array is now operational, +but without redundancy. We must now re-partition the old drive(s) to fit +into the new raid array. Remember that if the geometries are not the same, +the the partition size on the old drive must be the same or larger than the +raid partitions or they can not be added to the raid set. +<p> +Re-partition the old drive as required. Example: +<verb> + /dev/hda1 same or larger than /dev/hdc1 + /dev/hda2 same or larger than /dev/hdc2 + /dev/hda3 anything left over for swap or whatever... +</verb> + +Change the <bf/failed-disk/ parameter in the raidtab to <bf/raid-disk/ and +hot add the new (old) disk partitions to the raid array. +<verb> + raidhotadd /dev/md1 /dev/hda1 + raidhotadd /dev/md0 /dev/hda2 +</verb> +Examining /proc/mdstat should show one or more of the raid devices +reconstructing the data for the new partitions. After a minute or two... +or so, the raid arrays should be fully synchronized +(this could take a while for a large +partition). + +<p> +Using the procedure described in the first sections of this document, set up +bootable raid on the new raid pair. Hang on to that boot floppy while +setting up and testing this last step. + +<sect>Appendix A. - example raidtab + +<p> +RAID1 example described in the first sections of this document + +<verb> + df +Filesystem 1k-blocks Used Available Use% Mounted on +/dev/md0 19510780 1763188 16756484 10% / +/dev/md1 15860 984 14051 7% /boot + +# -------------------------- + + fdisk -ul /dev/hda + +Disk /dev/hda: 16 heads, 63 sectors, 39770 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hda1 63 33263 16600+ fd Linux raid autodetect +/dev/hda2 33264 443519 205128 83 Linux native +/dev/hda3 443520 40088159 19822320 fd Linux raid autodetect + +# -------------------------- + + fdisk -ul /dev/hdc + +Disk /dev/hdc: 16 heads, 63 sectors, 39770 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hdc1 63 33263 16600+ fd Linux raid autodetect +/dev/hdc2 33264 443519 205128 82 Linux swap +/dev/hdc3 443520 40088159 19822320 fd Linux raid autodetect + +# -------------------------- + +# md0 is the root array, about 20 gigs +raiddev /dev/md0 +raid-level 1 +nr-raid-disks 2 +chunk-size 32 +# Spare disks for hot reconstruction +nr-spare-disks 0 +persistent-superblock 1 +device /dev/hda3 +raid-disk 0 +device /dev/hdc3 +raid-disk 1 + +# md1 is the /boot array, about 16 megs +raiddev /dev/md1 +raid-level 1 +nr-raid-disks 2 +chunk-size 32 +# Spare disks for hot reconstruction +nr-spare-disks 0 +persistent-superblock 1 +device /dev/hda1 +raid-disk 0 +device /dev/hdc1 +raid-disk 1 + +# -------------------------- + +# GLOBAL SECTION +# device containing /boot directory +disk=/dev/md0 +# geometry + bios=0x80 + sectors=63 + heads=16 + cylinders=39770 +# dummy + partition=/dev/md1 +# start of device "disk" above + start=63 + +boot=/dev/hda +map=/boot/map +install=/boot/boot.b + +image=/boot/bzImage +root=/dev/md0 +label=LinuxRaid +read-only + +# ------------------------- + +# GLOBAL SECTION +# device containing /boot directory +disk=/dev/md0 +# geometry + bios=0x80 + sectors=63 + heads=16 + cylinders=39770 +# dummy + partition=/dev/md1 +# start of device "disk" above + start=63 + +boot=/dev/hdc +map=/boot/map +install=/boot/boot.b + +image=/boot/bzImage +root=/dev/md0 +label=LinuxRaid +read-only +</verb> + +<sect>Appendix B. - SCSI reference implementation RAID5 + +<p> +4 disk SCSI RAID5 +<verb> + df +Filesystem 1k-blocks Used Available Use% Mounted on +/dev/md0 11753770 2146076 9000678 19% / +/dev/md1 15739 885 14042 6% /boot + +# -------------------------- + + fdisk -ul /dev/sda + +Disk /dev/sda: 64 heads, 32 sectors, 4095 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/sda1 32 32767 16368 fd Linux raid autodetect +/dev/sda2 32768 292863 130048 5 Extended +/dev/sda3 292864 8386559 4046848 fd Linux raid autodetect +/dev/sda5 32800 260095 113648 82 Linux swap +/dev/sda6 260128 292863 16368 83 Linux native - test + +# ------------------------ + + fdisk -ul /dev/sdb + +Disk /dev/sdb: 64 heads, 32 sectors, 4095 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/sdb1 32 32767 16368 fd Linux raid autodetect +/dev/sdb2 32768 292863 130048 5 Extended +/dev/sdb3 292864 8386559 4046848 fd Linux raid autodetect +/dev/sdb5 32800 260095 113648 82 Linux swap +/dev/sdb6 260128 292863 16368 83 Linux native - test + +# ------------------------ + +# fdisk -ul /dev/sdc + +Disk /dev/sdc: 64 heads, 32 sectors, 4095 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/sdc2 32 292863 146416 5 Extended +/dev/sdc3 292864 8386559 4046848 fd Linux raid autodetect +/dev/sdc5 64 260095 130016 83 Linux native - development +/dev/sdc6 260128 292863 16368 83 Linux native - test + +# ------------------------ + + fdisk -ul /dev/sdd + +Disk /dev/sdd: 64 heads, 32 sectors, 4095 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/sdd2 32 292863 146416 5 Extended +/dev/sdd3 292864 8386559 4046848 fd Linux raid autodetect +/dev/sdd5 64 260095 130016 83 Linux native - development +/dev/sdd6 260128 292863 16368 83 Linux native - test + +# -------------------------- + +# raidtab +# +raiddev /dev/md0 + raid-level 5 + nr-raid-disks 4 + persistent-superblock 1 + chunk-size 32 + +# Spare disks for hot reconstruction + nr-spare-disks 0 + device /dev/sda3 + raid-disk 0 + device /dev/sdb3 + raid-disk 1 + device /dev/sdc3 + raid-disk 2 + device /dev/sdd3 + raid-disk 3 + +# boot partition +# +raiddev /dev/md1 + raid-level 1 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 32 + +# Spare disks for hot reconstruction + nr-spare-disks 0 + device /dev/sda1 + raid-disk 0 + device /dev/sdb1 + raid-disk 1 + +# -------------------------- + +# cat lilo.conf.sda +# GLOBAL SECTION +# device containing /boot directory +disk=/dev/md0 +# geometry + bios=0x80 + sectors=32 + heads=64 + cylinders=4095 +# dummy + partition=/dev/md1 +# start of device "disk" above + start=32 + +boot=/dev/sda +map=/boot/map +install=/boot/boot.b + +image=/boot/bzImage +root=/dev/md0 +label=LinuxRaid +read-only + +# ------------------------ +# cat lilo.conf.sdb +# GLOBAL SECTION +# device containing /boot directory +disk=/dev/md0 +# geometry + bios=0x80 + sectors=32 + heads=64 + cylinders=4095 +# dummy + partition=/dev/md1 +# start of device "disk" above + start=32 + +boot=/dev/sdb +map=/boot/map +install=/boot/boot.b + +image=/boot/bzImage +root=/dev/md0 +label=LinuxRaid +read-only +</verb> + +<sect>Appendix C. - ide RAID10 with initrd + +<p> +RAID1 over striped RAID0 pair.... the disks in the RAID0 sets are not +quite the same size, but close enough. + +<verb> +/dev/md0 is the /boot partition and is autostarted by the kernel +/dev/md1 and /dev/md3 are the two RAID0 sets autostarted by the kernel +/dev/md2 is the root partition and is started by initrd + +df +Filesystem 1k-blocks Used Available Use% Mounted on +/dev/md2 118531 76485 35925 68% / +/dev/md0 1917 1361 457 75% /boot + +# ---------------------------- + + fdisk -ul /dev/hda + +Disk /dev/hda: 4 heads, 46 sectors, 903 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hda1 46 4231 2093 fd Linux raid autodetect +/dev/hda2 4232 166151 80960 fd Linux raid autodetect + +# ---------------------------- + + fdisk -ul /dev/hdb + +Disk /dev/hdb: 5 heads, 17 sectors, 981 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hdb1 17 83384 41684 fd Linux raid autodetect + +# ---------------------------- + + fdisk -ul /dev/hdc + +Disk /dev/hdc: 7 heads, 17 sectors, 1024 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hdc1 17 84013 41998+ fd Linux raid autodetect +/dev/hdc2 84014 121855 18921 82 Linux swap + +# ---------------------------- + + fdisk -ul /dev/hdd + +Disk /dev/hdd: 4 heads, 46 sectors, 903 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hdd1 46 4231 2093 fd Linux raid autodetect +/dev/hdd2 4232 166151 80960 fd Linux raid autodetect + +# ---------------------------- + +# raidtab +# +raiddev /dev/md0 + raid-level 1 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 8 + device /dev/hda1 + raid-disk 0 + device /dev/hdd1 + raid-disk 1 + +raiddev /dev/md1 + raid-level 0 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 8 + device /dev/hdd2 + raid-disk 0 + device /dev/hdb1 + raid-disk 1 + +raiddev /dev/md2 + raid-level 1 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 8 + device /dev/md1 + raid-disk 0 + device /dev/md3 + raid-disk 1 + +raiddev /dev/md3 + raid-level 0 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 8 + device /dev/hda2 + raid-disk 0 + device /dev/hdc1 + raid-disk 1 + +# ---------------------------- + +contents of linuxrc + + cat linuxrc +#!/bin/sh +# ver 1.02 2-22-00 +# +############# really BEGIN 'linuxrc' ############### +# +# mount the proc file system +/bin/mount /proc + +# start raid 1 made of raid 0's +/bin/raidstart /dev/md2 + +# tell the console what's happening +/bin/cat /proc/mdstat + +# Everything is fine, let the kernel mount /dev/md2 +# tell the kernel to switch to /dev/md2 as the /root device +# The 0x900 value is the device number calculated by: +# 256*major_device_number + minor_device number +echo "/dev/md2 mounted on root" +echo 0x902>/proc/sys/kernel/real-root-dev + +# umount /proc to deallocate initrd device ram space +/bin/umount /proc +exit + +# ---------------------------- + +contents of initrd + +./bin/ash +./bin/echo +./bin/raidstart +./bin/mount +./bin/umount +./bin/cat +./bin/sh +./dev/tty1 +./dev/md0 +./dev/md1 +./dev/md2 +./dev/md3 +./dev/md4 +./dev/console +./dev/hda +./dev/hda1 +./dev/hda2 +./dev/hda3 +./dev/hdb +./dev/hdb1 +./dev/hdb2 +./dev/hdb3 +./dev/hdc +./dev/hdc1 +./dev/hdc2 +./dev/hdc3 +./dev/hdd +./dev/hdd1 +./dev/hdd2 +./dev/hdd3 +./dev/initrd +./dev/ram0 +./dev/ram1 +./dev/ram2 +./dev/ram3 +./dev/ram4 +./dev/ram5 +./dev/ram6 +./dev/ram7 +./etc/raidtab +./etc/fstab +./lib/ld-2.1.2.so +./lib/ld-linux.so.1 +./lib/ld-linux.so.1.9.9 +./lib/ld-linux.so.2 +./lib/ld.so +./lib/libc-2.1.2.so +./lib/libc.so.6 +./linuxrc +./proc +</verb> +<sect>Appendix D. - ide RAID1-10 with initrd + +<p> +This is a system made up of an assortment of odds and ends. The root mounted +raid device is comprised of a RAID1 made up of one RAID0 array from odd +sized disks and a larger regular disk partition. +Examination of the lilo.conf files may give you better insight +into the reasoning behind the various parameters. + +<verb> +/dev/md0 is the /boot partition and is autostarted by the kernel +/dev/md1 is one half of the mirror set for md2, autostarted by kernel +/dev/hda3 is the other half of the mirror set for md2 +/dev/md2 is the RAID1 /dev/md1 + /dev/hda3, started by initrd + +df +Filesystem 1k-blocks Used Available Use% Mounted on +/dev/md2 138381 74421 56815 57% / +/dev/md0 2011 1360 549 71% /boot + +# ---------------------------- + + fdisk -ul /dev/hda + +Disk /dev/hda: 8 heads, 46 sectors, 903 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hda1 46 4415 2185 fd Linux raid autodetect +/dev/hda2 4416 43423 19504 82 Linux swap +/dev/hda3 43424 332303 144440 83 Linux native + +# ---------------------------- + + fdisk -ul /dev/hdc + +Disk /dev/hdc: 8 heads, 39 sectors, 762 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hdc1 39 4367 2164+ fd Linux raid autodetect +/dev/hdc2 4368 70199 32916 82 Linux swap +/dev/hdc3 70200 237743 83772 fd Linux raid autodetect + +# ---------------------------- + + fdisk -ul /dev/hdd + +Disk /dev/hdd: 4 heads, 39 sectors, 762 cylinders +Units = sectors of 1 * 512 bytes + + Device Boot Start End Blocks Id System +/dev/hdd1 39 118871 59416+ fd Linux raid autodetect + +# ---------------------------- + +# raidtab +# +raiddev /dev/md0 + raid-level 1 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 8 + device /dev/hdc1 + raid-disk 1 + device /dev/hda1 + raid-disk 0 + +raiddev /dev/md1 + raid-level 0 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 8 + device /dev/hdc3 + raid-disk 0 + device /dev/hdd1 + raid-disk 1 + +raiddev /dev/md2 + raid-level 1 + nr-raid-disks 2 + persistent-superblock 1 + chunk-size 8 + device /dev/md1 + raid-disk 1 + device /dev/hda3 + raid-disk 0 + +# ---------------------------- + + cat linuxrc +#!/bin/sh +# ver 1.02 2-22-00 +# +############# really BEGIN 'linuxrc' ############### +# +# mount the proc file system +/bin/mount /proc + +# autostart /boot partition and raid0 +/bin/raidstart /dev/md2 + +# tell the console what's happening +/bin/cat /proc/mdstat + +# Everything is fine, let the kernel mount /dev/md2 +# tell the kernel to switch to /dev/md2 as the /root device +# The 0x900 value is the device number calculated by: +# 256*major_device_number + minor_device number +echo "/dev/md2 mounted on root" +echo 0x902>/proc/sys/kernel/real-root-dev + +# umount /proc to deallocate initrd device ram space +/bin/umount /proc +exit + +# ---------------------------- + +contents of initrd.gz + +./bin +./bin/ash +./bin/echo +./bin/raidstart +./bin/mount +./bin/umount +./bin/cat +./bin/sh +./dev/tty1 +./dev/md0 +./dev/md1 +./dev/md2 +./dev/md3 +./dev/console +./dev/hda +./dev/hda1 +./dev/hda2 +./dev/hda3 +./dev/hdc +./dev/hdc1 +./dev/hdc2 +./dev/hdc3 +./dev/hdd +./dev/hdd1 +./dev/hdd2 +./dev/hdd3 +./dev/initrd +./dev/ram0 +./dev/ram1 +./dev/ram2 +./dev/ram3 +./dev/ram4 +./dev/ram5 +./dev/ram6 +./dev/ram7 +./etc/raidtab +./etc/fstab +./lib/ld-2.1.2.so +./lib/ld-linux.so.1 +./lib/ld-linux.so.1.9.9 +./lib/ld-linux.so.2 +./lib/ld.so +./lib/libc-2.1.2.so +./lib/libc.so.6 +./linuxrc +./proc + +# ---------------------------- + + cat lilo.conf.hda +# GLOBAL SECTION +# device containing /boot directory +disk=/dev/md2 +# geometry + bios=0x80 + cylinders=903 + heads=8 + sectors=46 +# geometry for 2nd disk +# bios will be the same because it will have to be moved to hda +# cylinders=762 +# heads=8 +# sectors=39 + +# dummy + partition=/dev/md0 +# start of device "disk" above + start=46 +# second device +# start=39 + +# seem to have some trouble with 2.2.14 recognizing the right IRQ + append = "ide1=0x170,0x376,12 ether=10,0x300,eth0 ether=5,0x320,eth1" + +boot=/dev/hda +map=/boot/map +install=/boot/boot.b + +initrd=/boot/initrd.gz + +image=/boot/zImage +root=/dev/md2 +label=LinuxRaid +read-only + +# ---------------------------- + + cat lilo.conf.hdc +# GLOBAL SECTION +# device containing /boot directory +disk=/dev/md2 +# geometry + bios=0x80 +# cylinders=903 +# heads=8 +# sectors=46 +# geometry for 2nd disk +# bios will be the same because it will have to be moved to hda + cylinders=762 + heads=8 + sectors=39 + +# dummy + partition=/dev/md0 +# start of device "disk" above +# start=46 +# second device + start=39 + +# seem to have some trouble with 2.2.14 recognizing the right IRQ + append = "ide1=0x170,0x376,12 ether=10,0x300,eth0 ether=5,0x320,eth1" + +boot=/dev/hdc +map=/boot/map +install=/boot/boot.b + +initrd=/boot/initrd.gz + +image=/boot/zImage +root=/dev/md2 +label=LinuxRaid +read-only +</verb> +</article> diff --git a/LDP/howto/linuxdoc/Tango-HOWTO.sgml b/LDP/howto/linuxdoc/Tango-HOWTO.sgml new file mode 100644 index 00000000..affe2aef --- /dev/null +++ b/LDP/howto/linuxdoc/Tango-HOWTO.sgml @@ -0,0 +1,852 @@ +<!-- LinuxDoc file was created by LyX 0.12 (C) 1995-1998 by <root> Sun Aug 6 16:51:48 2000 + --> +<!-- Export filter v0.6 by Pascal Andre/Bernhard Iselborn--> + +<!doctype linuxdoc system> + +<article> + +<title>Tango 2000 HOWTO +<author>Shayne Lebrun +<date>July 2000 +<abstract>This document describes the installation, configuration, and basic troubleshooting + of Pervasive Software's Tango Application Server on Sun Solaris and various + flavours of Linux. +<toc> +<sect>Introduction +<p> + +This is the Tango for Linux and Solaris HOWTO, designed to be a quick reference + to the installation and configuration of various versions of Tango on supported + UNIX and UNIX-like platforms. This guide is valid for Solaris 2.6 and 7 on + the SPARC architecture, and for Red Hat 5.2 and 6, S.U.S.E 6.2+ and Caldera + OpenLinux 2.2+, all running on Intel. +<sect1>Contributors and Contacts +<p> + +This HOWTO was created by +<url url="mailto:slebrun@home.com" name="Shayne Lebrun"> and is currently + maintained by the same. Pervasive Software technical support can be reached + at 1-800-287-4383 or +<url url="mailto:techsupport@pervasive.com" name="techsupport@pervasive.com"> +<sect1>Acknowledgements +<p> + +Many thanks to the fine HOWTO HOWTO by Mark F. Komarinski. You should be + able to find it at the LDP homepage at +<url url="http://www.linuxdoc.org" name="http://www.linuxdoc.org"> + +The Tango Documentation Team makes a damn fine set of manuals; don't let + your MTCV book out of sight! +<sect1>Revision History +<p> + +This is the first attempt at laying this all down. +<sect1>New Versions +<p> + +The latest version is always available at +<htmlurl url="http://www.members.home.net/slebrun/howto/TangoHOWTO.html" name="http://www.members.home.net/slebrun/howto/TangoHOWTO.html"> +<sect1>Copyrights and Trademarks +<p> + +(c) 2000 Shayne Lebrun + +This manual may be reproduced in whole or in part, without fee, subject + to the following restrictions: +<itemize> +<item>The copyright notice above and this permission notice, and the trademark + notice below, must be preserved complete on all complete or partial copies +<item>Any translation or derived work must be approved by the author in writing + before distribution +<item>If you distribute this work in part, instructions for obtaining the complete + version of this manual must be included, and a means for obtaining a complete + version provided +<item>Small portions may be reproduced as illustrations for reviews or quotes + in other works without this permission notice if proper citation is given +</itemize> + +Exceptions to these rules may be granted for academic purposes: Write to + the author and ask. These restrictions are here to protect us as authors, not + to restrict you as learners and educators. +<sect1>Feedback +<p> + +Suggestions, flames, corrections, requests for a dinner date, etc etc, + should be sent to +<url url="mailto:slebrun@home.com?subject=HOWTO" name="slebrun@home.com with a subject of 'HOWTO'"> and + they'll be looked at. Remember, it's you who knows what needs to be in that + document that currently isn't. And it won't get there if you don't tell me + about it. +<sect>The Basics +<p> +<sect1>Tango Application Sever +<p> + +Tango Application Server, aka TAS, runs as a daemon process. Tango 3.x + is 'tangod' and Tango 2000 is 'tango4d'. Tango 2000 also runs a seperate Server + Watcher process. Tango is a 'green threaded' application; it spawns a series + of threads, but manages the threads itself. This means that a single TAS will + not take advantage of multiple processors. However, Tango 3.6 and Tango 2000 + include load splitting capabilities which allow you to run multiple TAS daemons + on one box. +<sect1>TAS, Web Server and Web Client +<p> + +The Tango Application Server is never contacted directly by the web browser; + nor does it ever send information directly to the web browser. The browser + only ever makes requests of the web server, which then forwards the request + to the TAS through either a CGI or a web-server specific plugin. There are + several advantages to this scheme. First, nothing on the browser side needs + to be updated; no plugins, Active-X objects, client side Java, or anything + are required. Second, the CGI/Plugin allows the Tango Server to be on a machine + other than the web server, or indeed on several machines other than the webserver. +<sect1>TAS Life Cycle +<p> +<descrip> +<tag>Born</tag>Tango Server is instanced, and loads it's configuration files + and what not. No user requests are accepted. +<tag>Startup</tag>Tango Server first looks for a StartupURL. If one is specified, + a request is generated. A successful return will allow Tango to move to the + next stage. If the request cannot be sent, or if there is no URL specified, + Tango Server moves on to the 'Running' stage. +<tag>StartupURL-Response</tag>Tango Server stays in this stage until a response + is received from the StartupURL, or until the request times out. +<tag>Running</tag>This is the normal operating state for Tango Server; user + requests are accepted, Tango Cron jobs are run, and so on. +<tag>Shutdown</tag>When a shutdown request is received, or generated by Tango + itself on a fatal exception, a ShutdownURL is looked for, and run if it exists. + Otherwise, it moves on to the Waiting for Running Threads stage. +<tag>ShutdownURL-Response</tag>Tango stays in this stage until either a response + is received from the URL requested, or it times out. +<tag>Waiting</tag>Tango Server waits for threads already running to finish, + but no longer than the specified waiting period. +<tag>Dead</tag>Tango Server kills all still running threads, cleans up, and + exits. +</descrip> +<sect>System Configuration / Requirements +<p> +<sect1>Solaris +<p> +<sect2>System Requirements +<p> + +Tango for Solaris requires Solaris 2.6 or Solaris 7, SPARC architecture, + approximately 30 megabytes of disk space, and approximately 2 megabytes of + memory per user, given what Pervasive considers to be 'average' memory use. + +Tango 2000 requires Solaris system patches. 105591 for Solaris 2.6. 106300 + and 106327 on Solaris 7. Note that 105591 revision 08 causes Tango to core + dump, as does 106327 revision 07. Not all the crashes are Tango's fault. :-) + Solaris patches are available at +<url url="http://access1.sun.com" name="http://access1.sun.com"> +<sect2>System Configuration +<p> + +There are a series of changes which can be made to your /etc/system file + to increase various resources. These changes will often increase Tango performance, + as well as preventing resource related crashes. The changes will require a + reboot. Be very careful when making such changes. + +These are generic values which are nevertheless better than defaults. +<verb>*** New Settings +set shmsys:shminfo_shmmax=4294967295 +set shmsys:shminfo_shmmin=1 +set + shmsys:shminfo_shmmni=100 +set shmsys:shminfo_shmseg=10 +set semsys:seminfo_semmni=100 +set + semsys:seminfo_semmsl=100 +set semsys:seminfo_semmns=200 +set semsys:seminfo_semopm=100 +set + semsys:seminfo_semvmx=32767 +*** New Settings End +</verb> + +Take a look at your Solaris documentation, or +<url url="http://docs.sun.com" name="http://docs.sun.com"> for further information. + +Also, add the following line to the login script of the Tango user after + installation: +<verb>ulimit -n 1024 +</verb> + + +<sect1>Linux +<p> + +Tango for Linux requires the appropriate flavour for the version you downloaded + or purchased. Pervasive will NOT support running a version of Tango for Linux + on a different Linux flavour; Tango for Red Hat Linux might not run on Caldera + 2.2, let alone on Debian. + +Tango for Linux currently only supports the x86 architecture. + +If you're using Red Hat 5.2, you'll need to upgrade your kernel. The Tango + for Linux documentation has the details. +<sect>Tango Installation and Configuration +<p> +<sect1>Installation - Tango 3.x +<p> +<sect2>Solaris +<p> +<sect3>Installing the Files +<p> + +The current version of Tango 3.x for Solaris is Tango 3.62. There is not + expected to be any further updates to the 3.x codebase. The installation path + is designed for incremental upgrades, so is a bit tricky. + +First, you'll need the +<htmlurl url="http://www.pervasive.com/support/updates/tango36.html" name="Tango 3.6"> version. + This is a compressed tarball, and will untar itself into /var/opt/EDI/. You'll + need to be superuser to install this. +<code>$su - +Password: ******** +# uncompress tango36sol.tar.Z +# tar -xvf tango36sol.tar +</code> + +Next, you'll need to grab the +<htmlurl url="http://www.pervasive.com/support/updates/tango362.html" name="Tango 3.62 patch"> file. + This too is a compressed tarball. This one will uncompress to whatever directory + it's in, so make a temp directory somewhere and use that. +<code>$su - +Password: ******** +# mkdir Tango362 +# cp ./tangoSol362.tar.Z ./Tango362/ +# cd Tango362 +# uncompress tangoSol362.tar.Z +# tar -xvf tangoSol362.tar +</code> + +What you'll wind up with are three binary files, a Readme.txt, and an 'odbc' + directory. Move the TangoNS_ep3.so to /var/opt/EDI/lib and the t3.cgi and tangod + files to /var/opt/EDI/bin. Finally, remove your /var/opt/EDI/odbc directory + and replace it with this one. +<code># mv./TangoNS_ep3.so /var/opt/EDI/lib/TangoNS_ep3.so +#mv ./t3.cgi /var/opt/EDI/bin/t3.cgi +#mv ./tangod /var/opt/EDI/bin/tangod +# rm -rf /var/opt/EDI/odbc +#mv ./odbc /var/opt/EDI/ +</code> +<sect3>Setting up the Tango user account +<p> + +Next, you'll need to use your favourite method to create a user account + to run Tango. You can use the graphical 'admintool' program, or command line + programs such as 'adduser' or 'useradd' depending on your installation. + +Generally, you'll want to call the account 'tango' and also perhaps make + a group called 'pvsw'. The user should be given ownership of everything in + the /var/opt/EDI directory tree. If deploying in a production environment, + especially on something outside of a firewall or the like, set the account + to have no password, no login capabilities. +<sect2>Linux +<p> + +There is no version of Tango 3.x for Linux. Had you going, though. +<sect1>Tango 2000 +<p> +<sect2>Solaris +<p> + +Tango 2000 is shipped in the form of a Solaris Package Archive. You'll + need to login as root, and using either the 'admintool' graphical utility, + or run the pkgadd command. If you have a CD-ROM copy,mount the CD. The automounter + will generally mount it in /cdrom. Copy the /cdrom/tango_as-2000/tango2000/T2000Install.tar + file to a temporary directory. If you downloaded Tango 2000, it will be a compressed + tar file, and you'll need to uncompress it first. If it's already uncompressed, + skip the first step below. +<code># uncompress T2000Install.tar.Z +# tar -xvf T2000Install.tar +# cd T2000Install +# pkgadd -d. PVSWtango +</code> + +and follow the prompts. +<quote>Warning: the shipping Tango 2000 installer sometimes rejects valid CD-keys + as being invalid. If this occurs, leave the CD-Key blank, and manually add + your key later (see section x.x). +</quote> +<sect2>Linux +<p> + +Tango 2000 for Linux is distributed as an RPM. On a distribution CD, you'll + find the file in the tango2000 directory. Copy the appropriate file to a temp + directory; Tango2000-server-4-Linux_i386.rpm if you're using Red Hat 6, Caldera + 2.2 or S.U.S.E 6.2 or later. Tango2000-server-4-RedHat52_i386.rpm if you're + using Red Hat 5.2. Either way, you'll need to be root. +<quote>Note that to use Red Hat 5.2, you'll need to manually upgrade your kernel + to version 2.2 or higher. +</quote> +<code>#rpm -Uvh Tango2000-server-4-Linux_i386.rpm +</code> +<sect1>Tango 2000 Service Pack 1 +<p> +<sect2>Solaris +<p> + +Tango 2000 SP1 for Solaris is a Solaris Package Archive, designed to replace/update + the existing installation. It is, however, a full install, so if you don't + have Tango installed already, you'll get a working install. Otherwise, the + procedure to install is the same as Tango 2000, only the archive is T2000InstallSP1.tar.Z + +You'll probably want to back up your t4client.ini and t4server.ini files, + as well as your web server configuration files. +<sect2>Linux +<p> + +Tango 2000 SP1 for Linux is an RPM designed to replace/update the existing + installation. It is, however, a full install, so if you don't have Tango installed + already, you'll get a working install. Otherwise, the procedure to install + is the same as Tango 2000, only the RPM is Tango2000-server-4.05.i386.rpm, + or Tango2000-server-4.05.RedHat52.i386.rpm if you're using Red Hat 5.2. +<sect1>tXserver.ini - TAS Settings +<p> + +Tango uses a file called 't3server.ini' or 't4server.ini' to control many + of it's behaviors and functions. For Tango 3.x, this file is /var/opt/EDI/t3server.ini + and for Tango 2000, it's $TANGO_HOME/configuration/t4server.ini. You + can find a complete description of all entries in your Metatags and Configuration + Variables book, but the most important/commonly used ones are listed here. +<sect2>Cache +<p> + +Possible entries: TRUE, FALSE + +This controls weather or not Tango caches TAF files. Caching will reduce + disk access, speeding up TAF execution. +<sect2>CacheIncludeFiles +<p> + +Possible entries: TRUE, FALSE + +This controls weather or not Tango caches included files. Caching will + prevent repeated disk access, speeding up TAF execution. +<sect3>CacheSize +<p> + +Possible entries: Numeric, measured in bytes + +This measures the size of the cache for TAFs and included files. If cache + grows to near this size, older documents will be flushed. +<sect2>ConfigPasswd +<p> + +Possible entries: text + +This is the password of the config.taf online configuration application. +<sect2>DataSourceLife +<p> + +Possible entries: numeric, measured in minutes. + +This controls how long an unused datasource connection will live. A setting + of 0 will cause a datasource connection to be closed as soon as it's query + is finished. +<sect2>DebugMode +<p> + +Possible entries: ForceOn, ForceOff, appFileSetting + +This controls how the TAS handles placing debug information on the bottom + of each page created; always, never, or per file settings. +<sect2>DSConfigFile +<p> + +Possible entries: path to file + +This points to the Data Source configuration file, which gives you some + finer control over how Tango uses data sources. See the Data Sources section + for more details. +<sect2>ItemBufferSize +<p> + +Possible entires: numeric, measured in bytes + +This is the maximum size of any given field that can be returned in a database + action. It's main function is to prevent Tango from becoming bogged down while + downloading an unusually large piece of data from a database. +<sect2>License +<p> + +Possible entries: alphanumeric CD-Key + +This is the Tango license. The CD-Key contains the licensing information + which tells Tango how to configure itself in terms of licenses and behavior. +<sect2>ListenerPort +<p> + +Possible entries: TCP/IP Port number + +This tells Tango what port to monitor for incoming connections from the + Tango CGI or Plugins. Ports cannot be shared between server software, so multiple + servers running on one machine will need their own ports. +<sect2>LoggingLevel +<p> + +Possible entries: NoLogging, LogLevel1, LogLevel2, LogLevel3, LogLevel4 + +This controls how much logging Tango does. The log, "Tango.log", is written + to the location specified in the LOGDIR config variable. LogLevel 3 is the + best to use if you're trying to debug a Tango problem, but will slow Tango + down, and will eat disk space. +<sect2>MaxActions +<p> + +Possible entires: numeric, 0 for no limit + +This controls how many actions Tango will allow in a TAF file. This guards + against things like infinite loops and overly large programs; most often used + in development environments. +<sect2>MaxHeapSize +<p> + +Possible entries: numeric, measured in bytes + +This controls how much memory the Tango Daemon process will allow itself + to consume. Memory is consumed by variables, datasource connections, and cache. + If Tango exceeds this number, it will shut itself down with a 'process size + exceeded' message and attempt to restart itself normally. This number should + be changed to provide 20% more than what you record Tango as generally + using during peak use. +<sect2>QueryTimeOut +<p> + +Possible entries: numeric, measured in seconds + +This controls how long Tango will wait for a response from a database call + before timing out. Note that not all databases and drivers support this functionality. +<sect2>RequestQueueLimit +<p> + +Possible entries: numeric + +This controls how many requests from a CGI Tango will allow to 'queue'. + A very busy site can sometimes have so many CGIs stacked, waiting for Tango + to service them, that some will get lost and orphaned. This helps prevent that + situation. +<sect2>ThreadPoolSize +<p> + +Possible entries: numeric + +This controls how many simultaneous threads Tango will run with. On Solaris, + it is generally better to have several Tango servers running a few threads + apiece than to have one Tango server running the same number of threads. +<sect2>ValidHosts +<p> + +Possible entries: TCP/IP addresses, colon delimited. + +This is a list of what IP addresses Tango will allow incoming requests + from. On a machine where the web server and Tango server are both running, + this should be set to 127.0.0.1, the localhost. +<sect>TAS and Web Servers +<p> + +The Tango Application Server runs as it's own process, where it services + requests from a web server. This allows for some functionality such as load + splitting and direction, as well as freedom of choice in web server and platform. + The TAS need not be on the same machine as the web server, nor is it limited + to being even on one machine. + +The preferred way of having a web server talk to Tango is through a plugin. + The plugin is written in the web server's API, or Application Programming Interface, + to take advantage of specific features of that web server, as well as the advantage + of having the code execute as part of the web server, instead of as a separate + CGI process. On Solaris, Tango has a plugin for Netscape Server and for Apache + in later versions of Tango 2000. Tango for Linux has a plugin for Apache. +<sect1>Netscape Server Configuration +<p> +<sect2>Tango 3.x +<p> + +Locate your Netscape configuration files in /whatever/netscape/suitespot/https-MYSERVER/config + generally. To the mime.types file, add this line: +<verb>type=magnus-internal/taf exts=taf +</verb> + +Add these two lines to the top of the obj.conf file (no line breaks; each + line which starts with 'init' is a full line. Thus, there are two lines total) +<verb>Init fn=load-modules shlib=/var/opt/EDI/lib/TangoNS_ep3.so funcs="Tango_main,Tango_main_init" +</verb> +<verb>Init fn=Tango_main_init stanza="TangoNS_ep3.so" +</verb> + +Add this line to the obj.conf file inside of the <Object name=default> + area, with the other services. +<verb>Service fn="Tango_main" method="(GET|HEAD|POST)" type="magnus-internal/taf" +</verb> + +You'll then need to use your Netscape Administration Server to restart + the server, telling it to load the configuration files when it informs you + that they've been hand-edited. Then, try hitting a TAF file. If it works, great! + If not, go through your configuration file again. Most of the time, a misconfiguration + is the reason for it not working. One space or quotation mark out of place + will destroy the entire setup. +<sect2>Tango 2000 +<p> + +Locate your Netscape configuration files in /whatever/netscape/suitespot/https-MYSERVER/config, + generally. To the mime.types file, add this line: +<verb>type=magnus-internal/taf exts=taf,tcf +</verb> + +Then, add these two lines to the beginning of the obj.conf file. Note that + there are no line breaks in each line. +<verb>Init fn=load-modules shlib=/opt/PVSWtango/lib/libtango4ns.so funcs="Tango_main,Tango_main_init" +</verb> +<verb>Init fn=Tango_main_init stanza="libtango4ap.so" tangoconfigpath=/opt/PVSWtango/configuration +</verb> + +Add this line to the obj.conf file inside of the <Object name=default> + area, with the other services. +<verb>Service fn="Tango_main" method="(GET|HEAD|POST)" type="magnus-internal/taf" +</verb> + +You'll then need to use your Netscape Administration Server to restart + the server, telling it to load the configuration files when it informs you + that they've been hand-edited. Then, try hitting a TAF file. If it works, great! + If not, go through your configuration file again. Most of the time, a misconfiguration + is the reason for it not working. One space or quotation mark out of place + will destroy the entire setup. +<sect2>Tango 2000 Service Pack 1 +<p> + +Installation is the same as for Tango 2000, but with this extra line added + to the services in the <Object name=default> area of the obj.conf file: +<verb>Service fn="Tango_main" method="(GET|HEAD|POST)" type="magnus-internal/tml" +</verb> + +Also, the mime.types file should have this line used instead of the one + for Tango 2000: +<code>type=magnus-internal/taf exts=taf,tcf,tml +</code> +<sect1>Apache Server Configuration +<p> + +Tango 2000 for Linux, and Tango 2000 Service Pack 1 for Solaris both support + the Apache webserver through an Apache plugin. Apache will require mod_so support + for all of these. The documentation states that you must custom build your + Apache; this is misleading. You must build your Apache only if the pre-built + version you're using doesn't have mod_so support. There are two places to check + for this: + +First, try running your Apache server with a '-l' argument. If mod_so is + listed, you're fine. +<code># httpd -l +Compiled-in modules: +http-core.c +mod_so.c +</code> + +Second, try looking in your httpd.conf file for an 'AddModule mod_so.o' + line. If you don't have mod_so support (also known as DSO support) in some + way, you'll need to compile a version that does. +<sect2>Tango 2000 +<p> + +At the end of your httpd.conf file, add these lines: +<verb>LoadModule t4_module /usr/local/tango/lib/libtango4ap.so +TangoModule t4_module + /usr/local/tango/configuration/t4client.ini +</verb> + +Modify the paths to the .so and .ini files as appropriate on your setup. + +Your t4client.ini will then need a stanza for t4_module. See the t4client.ini + section for examples. +<sect2>Tango 2000 Service Pack 1 +<p> + +At the end of your httpd.conf file, add these lines: +<verb>LoadModule t4_apache /usr/local/tango/lib/libtango4ap.so +TangoModule t4_apache + /usr/local/tango/configuration/t4client.ini +</verb> + +Modify the paths to the files as appropriate; Solaris defaults to /opt/PVSWtango/ + for the Tango home. + +Your t4client.ini will then need a stanza for t4_apache. See the t4client.ini + section for examples. +<sect1>tXclient.ini - CGI/Plugin configuration +<p> + +Tango uses a client configuration file to tell the CGI or Plugins where + to send Tango requests. The file consists of two sections; a declaration section + and an information section. Here is an example for a file controlling a CGI: +<verb>[Tango Client Definitions] +t4.cgi=Put A Description Here +</verb> +<verb>[t4.cgi] +TANGO_SERVER=127.0.0.1,18100 +</verb> + +And an example of a file with both a CGI and an Apache plugin: +<verb>[Tango Client Definitions] +t4.cgi=My Tango CGI +t4_apache=My Apache + Plugin +</verb> +<verb>[t4.cgi] +TANGO_SERVER=127.0.0.1,18100 +</verb> +<verb>[t4_apache] +TANGO_SERVER=127.0.0.1,18100 +</verb> + +Further entries can be made as appropriate. Use this list to find what + 'keyword' to use to reference a CGI/Plugin: +<descrip> +<tag>CGI</tag>Use the name of the CGI. For example, you could have two CGIs, + t4.cgi and t4private.cgi, each pointing to a different Tango server. +<tag>Netscape Plugin (Tango 2000)</tag>Use 'libtango4ns.so' as the name. You + shouldn't try to load multiple plugins. +<tag>Netscape Plugin (Tango 3.x)</tag>Use 'TangoNS_ep3.so' +<tag>Apache Plugin</tag>Use 't4_module' for Tango 2000 and 't4_apache' for + Tango 2000 Service Pack 1. You shouldn't try to load multiple modules. +</descrip> + +Tango 3 versions earlier than 3.6 use a slightly different format. TANGO_SERVER + is broken into two lines; TANGO_HOST and TANGO_PORT. Here's an example: +<verb>[Tango Client Definitions] +t3.cgi +</verb> +<verb>[t3.cgi] +TANGO_HOST=127.0.0.1 +TANGO_PORT=18000 +</verb> +<sect1>Load Splitting/Load Balancing +<p> + +All versions of Tango starting with 3.6 have allowed Load Splitting. You + can define a series of Tango servers that a plugin can use, and it will distribute + new requests between the servers. Users who make subsequent requests are directed + back to the server they were at previously via the UserReference search argument + or cookie. Users cannot move between servers without losing their variables + and what not. Also, what Tango currently does is not load balancing; that is + expected for a future release of Tango. + +Tango does not need to be running on the same machine as the web server + in any event. You need only run configure Tango's VALIDHOST configuration variable + to include the IP address of the web server machine. Then, in the web server + machine's t4client.ini file, put in the IP address and port number as usual. +<sect2>Tango Load Splitting +<p> + +To add multiple Tango servers, add an entry to the t4server.ini file with + the new name of the server, and add a new stanza for it, generally by copying + an existing stanza. Then, change all directory names to be unique, such as + LOGDIR. Make sure that it's running on a unique port. Tango defaults to port + 18100. Here is an abbreviated example of a t4server.ini file with two Tango + Application Server instances: +<verb>[Tango Definitions] +TAS_1=MyFirstServer +TAS_2=MySecondServer +</verb> +<verb>[TAS_1] +... +LISTENERPORT=18100 +... +LOGDIR=/usr/local/tango/log.TAS_1 + +... +</verb> +<verb>[TAS_2] +... +LISTENERPORT=18101 +... +LOGDIR=/usr/local/tango/log.TAS_2 +... +</verb> + +All other configuration variables would be filled in as appropriate. + +To run Tango with a specific configuration definition, use the -c switch. +<code>$ ./tango4d -c TAS_1 +$ ./tango4d -c TAS_2 +</code> + +The -c switch can be used in conjunction with the -k switch to kill servers + as well. + +Note that you'll need the appropriate licenses, either one Corporate or + Professional license, or as many Standard licenses as you want Tango servers. + +In the t4client.ini file, simply add the IP address and port of each server + to the TANGO_SERVER line of the appropriate CGI or Plugin, colon delimited. + Here is an example t4client.ini file, using the CGI, pointing to three separate + Tango servers running on the same machine, on ports 18100, 18101 and 18102. +<verb>[Tango Client Definitions] +t4.cgi=My CGI +</verb> +<verb>[t4.cgi] +TANGO_SERVER=127.0.0.1,18100:127.0.0.1,18101:127.0.0,1,18102 +</verb> +<sect2>Load Balancing - Hardware Load Balancers +<p> + +You can use a hardware load balancing device with Tango so long as your + webserver farm is behind the load splitting device, and each webserver is using + an exact copy of the same t4client.ini file. The t4client.ini file should be + configured to use every Tango machine you want available. The UserReference + based Tango redirection should function normally. +<sect>TAS and Oracle +<p> +<sect1>Oracle Support +<p> + +Tango 3.x for Solaris does not have native Oracle support. Tango 2000 for + Solaris supports Oracle 8 and 8i, and generally works with Oracle 7.3.4 and + above. Tango 2000 Service Pack 1 was not tested with Oracle 7.x however, and + there have been reports of problems. The Oracle 8 client can connect quite + happily to the Oracle 7 server, however, so that is an option. + +To use Oracle with Tango, first you require the Oracle Client to be correctly + installed on the machine. Generally, a good way to check for this is to: +<itemize> +<item>check to see if there is an 'oracle' account on the machine +<item>try to run the Oracle program 'sqlplus' +</itemize> + +If you can successfully run sqlplus, you should be fine. If not, well, + go install Oracle. + +Next, you need to make sure that the client has the appropriate entries + for the datasource in question to your TNS service; generally a tnsnames.ora + file. You accomplish this with your Oracle software; there are programs such + as net8config and what not that do it for you. The thing to remember here is + that the name of the datasource needs to be the same as the name of the datasource + you're using in Tango. + +Finally, to allow Tango to use the Oracle software, you need to add this + path to the LD_LIBRARY_PATH environment variable of the tango user account. +<code>$ORACLE_HOME/lib +</code> + +You'll also need to define what $ORACLE_HOME is; this, of course, + is the root directory of Oracle, and will be some forboding path such as, for + example, /u01/software/products/8.1.5/oracle or something similar. + +If you're using Oracle 7.x or 8.0.x you'll probably need to create a new + client library. Instructions for this are in $TANGO_HOME/odbc/src/oracle + in the readme.ora file. You can check to see if you require this patch by attempting + to load the Oracle ODBC driver (see section 6). If it fails with an 'unresolved + symbol' error, then you need the patch. + +As the readme file says, this newly created library must appear in your + LD_LIBRARY_PATH before the reference to $ORACLE_HOME/lib does. If there + are no other programs running, it's generally easiest to replace the old library + with the new. + +Some shells seem to have trouble with the LD_LIBRARY_PATH ordering; I've + seen ksh fail to correctly load the new library, and switching to sh or bash + solve it. +<sect>TAS and ODBC +<p> +<sect1>Solaris +<p> + +Tango for Solaris includes the Merant ODBC driver pack, which Tango can + use to connect to a wide array of databases, such as Informix, Sybase, Oracle, + and now Microsoft SQL Server. + +The .odbc.ini file (see below) should be located in the home directory + of the Tango user account. It can be stored elsewhere, for centralization or + what not, and located using an environment variable called ODBCINI. +<sect1>Linux +<p> + +Tango 2000 for Linux includes the iODBC driver manager, and a Pervasive.SQL + driver is included with Pervasive.SQL for Linux. It will also work with Postgres + SQL and MySQL drivers. Other drivers are available at +<url url="http://www.unixodbc.com" name="http://www.unixodbc.com"> and +<url url="http://www.iodbc.org" name="http://www.iodbc.org"> + +The .odbc.ini file (see below) should be located in /usr/local/tango/etc/odbc.ini + which can be symlinked to /usr/local/psql/etc/odbc.ini if both are installed. +<sect1>The odbc.ini Configuration File +<p> + +The drivers are controlled by an ini file called .odbc.ini (note the leading + period; it's a hidden file on Solaris.) + +The file contains a list of Data Source Names followed by a definition + section. It is a standard INI file format. So long as the DSN name used by + a TAF is listed in this file, and the database schema is the same as the one + on the development machine, the database access will work transparently. + +Here is an example of a .odbc.ini file containing a single DSN called MyOracleDatabase, + which is pointing to an Oracle database with a TNS name of 'LocalOracleDatabase'. +<verb>[ODBC Data Sources] +MyOracleDatabase= +</verb> +<verb>[MyOracleDatabase] +Driver=/opt/PVSWtango/odbc/lib/VQor815.so +ServerName=LocalOracleDatabase +</verb> + +All entries will have, at minimum, a Driver line; this points to a .so + shared object which is the actual ODBC driver. There will be other lines dependant + on the driver itself; server configuration, special flags, that sort of thing. + Refer to the readmes and to the odbchelp.pdf file (on Solaris) or to specific + driver documentation for those settings, as well as any environment settings + required. + +Note that ODBC drivers still often require database specific Client software; + for example, the ODBC Oracle drivers require the same Oracle OCI client software + that Tango requires for a native Oracle connection. Sybase client software + must be installed for the Sybase ODBC driver to function, and so on. Again, + see the odbchelp.pdf file, or driver documentation for specifics. + +Anybody who would like to write small crib notes on configuring specific + databases to work with Tango for Solaris or Linux through ODBC, feel free and + send them to me and they'll be included in this HOWTO, with full credit of + course. +<sect1>Solaris, ODBC and Oracle +<p> + +Certain versions of the Oracle client are missing key functionality that + the Oracle ODBC drivers require, as well as the Tango native Oracle drivers. + +The easiest way to check for this condition is to use the 'ivtestlib' program + to attempt to load the Oracle ODBC driver. Become the Tango user, and move + to $TANGO_HOME/lib. Look for a driver with 'or7' for Oracle 7, or 'or8' + for Oracle 8. Depending on your version of Tango, the full name might be 'IVor714.so' + or 'VQor714.so'. The last number before the .so is the ODBC version. + +Once you have this file name, move one directory up, and then go into the + 'bin' directory. There, execute the 'ivtestlib' program with the file name + as an argument. +<code>$ cd $TANGO_HOME/odbc/lib +$ ls *or8* +VQor814.so +$ cd ../bin +$ ./ivtestlib ../lib/VQor814.so +Load of ../lib/VQor814.so successful, qehandle is 0xFF24120 +</code> + +If the Oracle drivers need to be patched, you'll see a long message ending + in the fact that there is an 'undefined symbol slpmprodstab'. This will prevent + Tango Oracle Native connections from working as well as ODBC. In the $TANGO_HOME/odbc/src/oracle + directory is a readme.ora file and two scripts, one for Oracle 7 and the other + for Oracle 8. The readme file details the creation of a new 'libclntsh.so' + file, which is the main Oracle client library. In a nutshell, make sure you + have ORACLE_HOME defined, and run the appropriate script for your version of + Oracle. This will create the .so file and place it, by default, into $TANGO_HOME/odbc/lib. + Then, make sure that that path appears in your LD_LIBRARY_PATH before any references + to $ORACLE_HOME/lib does. You can also move the libclntsh.so file to + your $ORACLE_HOME/lib directory, or create a link between $ORACLE_HOME/lib/libclntsh.so + and the one you just created; the preexisting libclntsh.so is a link to another + library anyway. +<sect>Handy TAF Files +<p> +<sect1>CGI_OR_PLUGIN.taf +<p> + +</article>