:: madsearch 2 :: directory preparation

Preparing A Directory
For MadSearch2 Data Tables

Where Do I Put Stuff?

Before you do anything, you have to create a place to put your MadSearch2 data tables. There are a few things to consider.

MadSearch2 tables may be placed anywhere. As MadSearch2 executes locally when called upon by the web server, your tables need not be placed within a web accessible directory although it's customary to do so.

It is important to understand the ownership permissions under which MadSearch2 operates. The directory in which MadSearch2 tables are stored is owned by the person who created it. MadSearch2 never owns the directory in which its tables are placed. MadSearch2 has access to the directory and the tables within it by virtue of group "www". Thus, when the directory is created, the owner immediately uses a provided utility to set group ownership of the MadSearch2 directory to "www".

What does this all mean? If you require others besides yourself to have access to non-MadSearch2 files within the directory, you must place your MadSearch2 tables in another directory. Other permissions should never be set for MadSearch2 directories. In addition, files generated by MadSearch2 should never be modified or manipulated outside the MadSearch2 environment.

If you're developing a database for an academic department, administrative department, or student group, then you're probably going to create a directory within that organization's ColumbiaWeb space. For example, if you belong to the group "Great Expectations", you might place your membership database in the:

/www/data/cu/expectations/mad2data

If you're developing a personal database, you'll probably place it within your own account space. For example, if user up7 wanted to create a guestbook application for their personal web page, they might place their madsearch2 tables in the directory:

~up7/guestbook/data

where the "guestbook" directory is the directory in which they would place html files related to the guestbook application. The "data" subdirectory would then be used to store the actual madsearch2 data tables.

Creating The Directory
step 1	Login to cunix. At this point it is assumed that you have decided upon a new directory in which to place your madsearch2 tables. For purposes of this example, we will assume that the directory "/wwws/data/cu/ourgroup/" exists and that we wish to create a subdirectory named "data". In order to create this new subdirectory, we type: $ mkdir /wwws/data/cu/ourgroup/data We now have a new directory in which to store our MadSearch2 tables and their associated files.
step 2	We now have to provide madsearch2 access to the directory. madsearch2 is given access through the "www" group. To do this, we use the "setweb" program that ACIS provides: $ setweb /wwws/data/cu/ourgroup/data MadSearch2 now has group read access to the data directory. But let's be sure. Type the following: $ ls -ldF /wwws/data/cu/ourgroup/data You should see something like the following: drwxr-s--- 2 jeanluc www 4096 Jan 26 11:55 /wwws/data/cu/ourgroup/data// The highlighted items are those that are most important to have. If you don't see "www" as the group and the "r-s" group permissions, repeat this step. Ensure that you're specifying the proper directory.
step 3	Setweb is a utility that changes the group to www and gives read-only access. MadSearch2 also needs write access. You should send mail to consultant with the name of your directory and ask them to add write permission to that directory. If you type this command yourself you will lose the g+s bit so it must be done by a system administrator: $ chmod g+w /wwws/data/cu/ourgroup/data MadSearch2 now has full access to the data directory. But again, why not be sure. Type the following at your command prompt: $ ls -ldF /wwws/data/cu/ourgroup/data You should see something like the following: drwxrws--- 2 jeanluc www 4096 Jan 26 11:55 /wwws/data/cu/ourgroup/data// The important thing to check hee is that the "r-s" group permissions have become "rws".

Ok, What Now?

At this point you've provided access to a directory for group "www". However, MadSearch2 is quite demanding. It requires that your perform one more step prior to its using the directory.

"What could this be?", you ask. "What more could MadSearch2 want than a place to put my stuff?"

Well, MadSearch2 is web based. Therfore, it has concerns for the safety and privacy of your directory. You wouldn't want just anyone to have access to your directories and files within them. Would you? (The answer is no.) Therefore, MadSearch2 takes upon itself responsibility for who has access to the directory you have provided.

It does this by way of a simple text file placed within the directory. It is called the ".mad2" file. Unless the .mad2 file exists within the directory, MadSearch2 will flatly refuse to play there. The ".mad2" file contains entity / entity name pairs to specify which entities may have access to the directory.

Oooh, entities! Hold it. What's an entity? MadSearch2 recognizes two types of entities, users and groups. The entity name would then be a person's authentication id or cunix group/university affiliation, respectively. Multiple entities may be specified as having access to a directory.

The structure of the mad2 file is simply:

entity | entityName

where each such pair is placed on a separate line and separated by the "|" character. A ".mad2" file may be a maximum of 4Kb in size (4096 characters). In addition, be sure that the ".mad2" is readable by group "www".

Within the entity field, you may use the word "USER" or "GROUP". White space preceeding or following the elements of this pair is ignored.

The entity name is a slightly more complicated issue. If you wish to restrict access to a user, you must provide their authentication (UNI) id. A person's authentication id does not always correspond to their user id. In fact, a person in some cases can have multiple cunix user ids. But each of these will map to one authentication (UNI) id. For example, if you wanted to provide access to the user with cunix id "jeanluc", you must first identify his authentication id. To determine the authentication id, type the following at the cunix command prompt:

$ cunix2handle jeanluc

You should then see the person's directory information:

jlg10

It is the "jlg10" that should appear as the entity name within the .mad2 file.

To specify an entity name for a cunix group, you must first append the prefix "CUNIX_" to the group's name. For example, if you wish to specify that the members of the cunix group "ourgroup" should have access to the directory, you would specify the entity name as "CUNIX_ourgroup".

Finally, members of the university have various affiliations by which you can restrict access. If you wish to restrict access to the MadSearch2 directory by affiliation, simply specify the affiliation you wish to restrict by. A list of affiliations can be found at http://www.columbia.edu/acis/rad/authmethods/auth-affils/.

A sample file might look as follows:

USER\|jlg10	<----- user
GROUP\|CUNIX_staff	<----- cunix group restriction
GROUP\|CUstudent	<----- university affiliation restriction

Note that the comments appearing in yellow are strictly for explanatory purposes and would not be included within the actual ".mad2" file.

Creating The ".mad2" File
step 1	Login to cunix. For purposes of this example, we will assume that the directory "/wwws/data/cu/ourgroup/data" has been previously created as per the instructions above and is to store MadSearch2 data tables. We need to place ourselved within this directory. To do this, type the following at the cunix command prompt: $ cd /wwws/data/cu/ourgroup/data You should now be within the directory.
step 2	We now need to create the ".mad2" file required by MadSearch2 in order to specify who has access to our directory via MadSearch2's web interface. To do this, simply create a text file named ".mad2" using your favorite text editor. For example, if you use pico, type the following at the command prompt: $ pico .mad2 Note that the filename is case-sensitive and must be ".mad2". Within the text editor, specify the entity/entity name pairs that will determine access to your directory. When finished, save the file and quit the text editor so as to return to the command prompt.
step 3	The ".mad2" file should now exist within the directory "/wwws/data/cu/ourgroup/data". We must now set group permissions on the file such that MadSearch2 can read the file and use it's information. To do this, type the following at your cunix command prompt: $ chmod g+r .mad2 MadSearch2 should now have group read access to the ".mad2" file. But, it never hurts to be sure. Type the following: $ ls -lF .mad2 You should see something like the following: -rw-r----- 1 jeanluc www 67 Jan 26 12:24 mad2 The highlighted items are those that are most important to have. "www" should have group ownership and "r--" read permission to the .mad2 file.