Instructions for setting up INGRES from distribution (LINUX) (386BSD) Brought to you by the folks at Lunar House Software (January 12, 1993) This set of instructions will help you install INGRES version 8.9 for LINUX and 386BSD and get it running on your system. The LINUX and 386BSD version is distributed as a .lzh archive created using lha 1.0. 1. Installing INGRES for the first time. If you already have an INGRES system, go directly to part 1.3. 1.1. Creating a UNIX user called "ingres". The first thing you should do is to create a user named "ingres" on your system and log in as that user. The files you read in from the archive will be owned by "ingres", an actual user on your system. INGRES locates files in the system by looking in the /etc/passwd file for the user "ingres". INGRES will not work unless you create this user. 1.2. Creating parent directory for the INGRES system. The parent directory of the INGRES system at MoonScape is "/home/ingres". It is possible to run INGRES in a parent directory of your own choosing, which must be the parent directory of the user "ingres" as specified in /etc/passwd. For the purpose of this document the parent directory will be denoted by "...". 1.3. Extracting INGRES from the archive. You are now ready to extract files into your system using lha. You should be in the home directory for INGRES and have the archive ingres??.lzh in it and be logged in as INGRES. Type the command: lha x ingres.lzh The system will be fully extracted from the archive. 1.4. User oriented programs In .../bin there is a collection of programs. Several programs are type-I commands associated with INGRES and which should be moved or linked into /usr/local/bin. The other programs are executed only by other INGRES programs and must be left in .../bin. Use the script INSTALL.ME to perform that task. Leave the other files where they are! These are the programs: copydb, creatdb, destroydb, equel, helpr, ingres, printr, purge, restore, sysmod (see INGRES reference manual for an explanation of these commands. demodb creates a new database with a name given as an argument and loads it with sample data rela- tions such as might be used by a department store for employee and sales records. The INGRES tutorial uses the relations in the demo database for its examples. It is imperative that each of these programs be in the correct mode. A sample "ls -l" is given below. Verify that your file modes agree with the listing. -rwx--x--x 1 ingres . . . copydb -rws--x--x 1 ingres . . . creatdb -rwxr-xr-x 1 ingres . . . demodb -rws--x--x 1 ingres . . . destroydb -rwx--x--x 1 ingres . . . equel -rws--x--x 1 ingres . . . helpr -rws--x--x 1 ingres . . . ingres -rws--x--x 1 ingres . . . printr -rws--x--x 1 ingres . . . purge -rws--x--x 1 ingres . . . restore 1.5. EQUEL run time library. The EQUEL run time library should reside in "/usr/local/lib". The library is needed for compiling user EQUEL programs. It is not necessary for compiling INGRES itself. It is preferable although not essential that the owner of the library remain "ingres". The library will be installed by the above INSTALL.ME script. Refer to the INGRES Reference Manual for information about how to use EQUEL and the EQUEL library. There is a tutorial on using EQUEL in ".../doc/other/equeltut.q" and there is a small sample program in ".../doc/other/equeldemo.q". 1.6. Install concurrency device. CONCURRENCY CONTROL REMAINS UNTESTED DUE TO THE BETA NATURE OF LINUX TCP/IP. If you want to use concurrency control, you will have to install the INGRES concurrency program into /etc, add the command to /etc/rc, and add the definition to /etc/inet/services*. You should read the document "Instructions for Installing the INGRES Concurrency Device in UNIX" before proceeding. *Or where-ever 'services' lives. 2. General Information about INGRES. 2.1. Some comments on the INGRES directories The directories (in ...) necessary for a minimal running system are: bin the binary programs comprising INGRES files files used by various parts of INGRES data/base/ user-created databases demo used by the "demodb" command Several additional directories are also created. If space limitations are a problem on your system you may want to delete some or all of the material here. If you need to, delete the files but be sure to keep the directories. The additional directories are: doc documentation lib object file libraries source system source code 3. Getting started using INGRES. 3.1. The Users File. In order to use INGRES a user must be entered into the "users" file. The users file contains information re- garding the status and permissions of each user. This file resembles the /etc/passwd file, and includes the user's name, the user code (used inside INGRES to identi- fy a user), the UNIX id of the user, some status bits, and some other fields. These are described in detail in the document users(files). The users file can be initialized by running the "user- setup" program. This program installs all users in the /etc/passwd file as valid INGRES users. The user code is assigned sequentially from "aa". The status field is in- itialized to 000000 for all normal users and 177777 for the user "ingres". To setup the users file in ingres/files execute: .../bin/usersetup Once created the users file can be edited using "vi" to do the following things: - completely remove all users not authorized to execute INGRES. - restrict a user from using a particular data- base. - set the other status bits for appropriate users. As UNIX users are added or deleted, the users file must be updated appropriately. The usersetup program can be executed only once. A diagnostic is issued if it is exe- cuted a second time. 3.2. Creating a Sample Data Base The "demodb" command provided can be used to construct the sample database on which the examples in the tutorial (located on-line in ".../doc/other/tutorial") are based. In order to execute this command you must be entered into the users file and have permission to create a database. To create the sample database and assign it the name "demo" type the command: demodb demo -c In order to use INGRES with this database you need merely type ingres demo and you will be ready to follow the terminal session described in the tutorial or to formulate your own queries. To create your own copy of the same sample database use some unique database name. demodb mydemo -c N.B. the -c is very important as it bypasses the locking driver. 3.3. Creating Other Data Bases. You will no doubt wish to create other databases of your own and for this you will need to use "creatdb". In ord- er to use this command you must be authorized in the users file. 3.4. Concurrency Control. INGRES is designed to run with either no concurrency con- trol or with full concurrency control. INGRES locks por- tions of a database by using a user level process called /etc/ingreslock. Initially you can use INGRES without this special process. If you want concurrency control (if more than one person will be using INGRES on the same database at the same time, you MUST have it) then print a copy of the instructions on how to install the concurren- cy device: more .../doc/other/lockdev.doc 4. Hints and suggestions. 4.1. Unix Protection Problems. If you encounter problems in creating directories or reading in files from the tape check the protection status of the parent directories involved to make sure that permission to write new files exists. The following summarizes the proper modes for each direc- tory. All directories are owned by INGRES except the in- dividual databases. (The modes in parentheses represent the mode to be used if you wish to restrict access maxi- mally.) bin 755 data 700 data/base 777 demo 755 doc 755 files 755 lib 755 source and all its subdirectories 755 (700) any database 777 (typically owned by the dba) You will need to become super-user to add files in "/usr/local/bin". 5. Source code and system regeneration 5.1. Log on as user "ingres". When doing any system work always log on as "ingres". 5.2. Recompilation. There's a file .../source/Config which contains some important configuration flags. Please read and modify as necessary if you try to compile ingres on platforms other than Linux. All source code for the system is located in ".../source" and various sub-directories therein. Each subdirectory is named for a functional component or sub-component of the system. Makefiles for regenerating the various portions of the system from source are located in the associated directory. To regenerate a particular module (e.g. parser) say: cd .../source/parser make The entire system can be recompiled and installed in /usr/local/bin using the command: cd .../source/conf make allinstall cd ./INSTALL.ME When recompiling for the first time it is strongly ad- vised that you keep a log by doing the following: make allinstall 2>&1 |tee log Libraries of object code are maintained in .../lib. N.B. bison -y chokes on .../source/equel/grammar.y I have no idea why. I use byacc. It works fine. 5.3. Compilation Flags and Funny Flavored UNIXes. (N.B. THIS section is out of date) If you are running any system other than VM/UNIX release 4.2 (4.2BSD), you may have to recompile the INGRES system before it is usable. Examine the file .../source/unix.h closely for correspondence with your version of reality. Major problems include representation of user and group id's and structures returned by various system calls. Four compile flags in unix.h define the type of user id's used on your system. For a vanilla version six system with 8-bit user id's and 8-bit group id's, set the xV6_UNIX compilation flag. For a Berkeley version six system with a single 16-bit user id (and no group id), set the xB_UNIX flag. For a vanilla version seven sys- tem, chocolate version six system, or VM/UNIX system, with 16-bit user id's and 16-bit group id's set xV7_UNIX. Also, define either VAX or PDP11 depending on whether you are on a PDP-11 or a VAX. A large set of flags in ingres.h control compilation of trace information and timing estimates. Flags of the form "x?TM" (where "?" is a letter as described below) turn on timing information. THESE SHOULD ALWAYS BE LEFT OFF, since the system you receive on the distribution tape does not include everything necessary to successful- ly use these flags. Flags of the form "x?TR1", "x?TR2", and "x?TR3" are trace compilation flags. Compiling these in does not automatically make trace information print, but only makes it available. These flags must be proper- ly nested; for example, if xMTR2 is set, xMTR1 must also be set (but xMTR3 is optional). The letter codes for these flags are as follows: A Access Methods M Terminal Monitor P Parser Q Qrymod D Decomposition O One Variable Query Processor Z Data Base Utilities E Equel S Scanner T Standalone Routines A flag named DISTRIB is used in some places in the code. This is used in the yet-to-be-born Distributed INGRES system, and should always be left off. Touching any other defined constants should be considered extremely dangerous and is done strictly at your own risk. 6. Documentation. 6.1. Tutorial on INGRES. (N.B. Docs were formatted by hand and may not be complete) A tutorial on using INGRES can be found in ".../doc/other/tutorial.doc". A copy of the document can be viewed by: more .../doc/other/tutorial.doc The tutorial guides the reader through examples of using QUEL the INGRES database language. A basic familiarity with UNIX is assumed. 6.2. Reference Manual. The reference manual consists of a number of files - one for each command or feature in INGRES. The reference manual can be retrieved by using the help command (see help(quel)). 6.3. Maintenance Manual. A guide to using INGRES has been written and is called "Creating and Maintaining a Database Using INGRES". It includes information about creating databases, storage structures, recovery, copy, indices and other useful in- formation. A copy of the manual can be produced by: more .../doc/other/maintain.doc 6.4. Design of INGRES A draft of the report "The Design and Implementation of INGRES" by Stonebraker, Kreps and Held can be found in ".../doc/other/design.doc". It can be printed by: lp .../doc/other/design.doc The report gives a fairly detailed description of the structure and capabilities of the entire system as it ex- isted over eight years ago, in January 1976. It is out of date in many areas. It gives implementation details and algorithms of important system modules. 6.5. Internal Documentation. We currently do not provide, nor have we written any internal documentation beyond what is mentioned in the "Design and Implementation" paper. 7. Consulting The INGRES project is not set up to supply regular consult- ing. If you do have problems, please reread these instruc- tions carefully; over two thirds of the "bug reports" we re- ceive can be answered by re-reading the documentation. For non-technical questions (e.g., regarding availability of the system or documentation) please call the project secretary at (415) 642-2344. I can also be reached through this number. Joe Kalash Electronics Research Laboratory University of California Berkeley, California 94720 8. Linux and 386BSD port The linux/386BSD port was done by: Zeyd M. Ben-Halim zmbenhal@netcom.com