
This is FileArchiveSearch (FAS), version 0.6 - November 2004




ABOUT / FEATURES

What is FileArchiveSearch (FAS)?

FAS is a PHP script that lets you search for files on your CD-ROM collection,
conveniently through a web interface. Think of it as a web-based "WhereIsIt".

FAS provides the following basic features: Searching (with support for
wildcards), adding CDs to the archive (you mount the CD, select a name for
the list file, and press "Add new CD" in the web interface), and deleting
CDs. For security reasons, the Add/Delete features are only available when
accessing FAS from localhost (or from specific IP address specified by the
admin).

Apart from being able to search CD list files, FAS can also include local
directories in the search. For example, it is useful to include the directory
you're usually downloading files to in the search - this way you can find
files both on your CD archive and in the fresh, not-yet-burned downloads in
a single search.

FAS is also useful for people who run a private software/music/film
distribution FTP, to allow users to search the FTP conveniently through
a web interface - geat for dupechecks before uploading. For a detailed
documentation of these features, see the "ADVANCED CONFIGURATION" section
below.

FAS is easy to set up and does NOT require any database like MySQL. The
list files are in a standard format (simply the output of ls -lR saved
in a file - so you can create FAS-compatible list files on any UNIX
system, without having to install FAS).

For performance and flexibility reasons, searching is done using GNU grep,
and is blazingly fast.


REQUIREMENTS

You need a running http server with PHP 4.X. The PHP system() command
must be available. Typically, this is the case if you install PHP on your
own Linux box. Webhosting providers offering PHP scripting usually do not
make this command available to the PHP users. Also, you need to have GNU
grep installed on you system (which is the case for virtually all Linux
installations).

FAS should run on all Linux versions and also on other UNIX-style
operating systems (although this was not tested). It is unlikely that it
will run on a Windows platform; however it could be adapted to work on
Windows as well (provided that the GNU grep port is installed).


INSTALLATION


Installation is easy; however you need some very basic knowledge about
how to get a PHP script to run, how to set permissions correctly, and how
to edit files.

1. Edit the file fas.php

Go to the section marked by "*** Edit the following variables ***".
There, set the directory where your list files will be located, for example
to /home/myusername/cd-listing or /var/cd-list. There should NOT be a / at
the end.

Also, you can set the "admin IP" address. If FAS is accessed from this IP,
additional features such as adding new list files or deleting list
files are available. If you run FAS on your local machine, leave it at
the default setting "127.0.0.1". 

Additinally, you may adjust the number of hits that should be displayed
in a single search.

There are detailed comments in the source code that help you to understand
the options.

2. Create the directory for the list files

Create the directory you've set in step 1. Set the permissions correctly,
so that shell scripts invoked by the fas.php have both read and write
permissions.

3. Copy the six shell scripts to an appropriate place.

Copy the six shell scripts "fas", "fas-add-alt", "fas-add-default",
"fas-del", "fas-get", and "fas-list" to a directory where they can be
found by the php "system" command - e.g. /usr/local/bin or /usr/bin.

4. Edit the files fas-add-default and fas-add-alt

These files are used for adding new list files to the archive. In these files,
you can specify which directory is used for generating the list files.

Usually, this will be "/cdrom" (or the dir where your CD-ROM drive is mounted)
for fas-add-default.

Typically, most users have both a CD-ROM/DVD drive and a CD/DVD writer.
Therefore, there are two different scripts, and you can specify a different
dir in each one - e.g. /cdrom in fas-add-default, and /writer in fas-add-alt.
By default, FAS will invoke fas-add-default to add a CD; if the "use alternative
drive" checkbox is checked in the "Add new CD" page, FAS will invoke fas-add-alt
instead.

5. Copy fas.php to any directory from where php scripts may be executed.

That's it! Access the PHP script from your web browser.

If something doesn't work, this is most likely due to incorrectly
set permissions. Check the permissions of the list file dir and of
the script itself.

Also, when accessing FAS from the local machine, make sure to access it as
http://localhost/.... and not as http://my.hostname.somewhere.edu/... if you
have set the admin IP to 127.0.0.1.

If you think you've found a bug or an incompability with some PHP version,
email mail@tillmann-steinbrecher.de

USING FAS

If you access FAS from your browser, you'll get an entry field where
you can enter a search term. However, when you start it the first time,
there are no list files available that could be searched.

If you're accessing FAS from the machine with the IP address set under
Step 1 of the installation (typically 127.0.0.1 if you're accessing FAS
from the local machine), then you should see a link "[Add/List CDs]".
Click on it. Now, think of a nice name for your CD, put it in the drive,
mount it, and click on "Add new CD". You should now see the content of
your new CD in the browser.

Hints: If you're going to give numbers to you CDs, it is a good idea to
       start with "001" instead of just "1", since FAS displays lists in
       alphabetical (or reverse alphabetical) order.
       You may use spaces and local characters like . The & and +
       signs are not allowed and will automatically be replaced by the word
       "and".

Add as many CDs as you want, and experiment with the search and browse
features.

Note that if you're configured your http server to be accessible by
everyone, you might want to use a .htaccess password for FAS. Otherwise
anybody can access FAS on your machine and browse your CD collection.


ADVANCED CONFIGURATION

FAS is designed to isolate the functionality for searching and
adding list files in separate shell scripts. Therefore, it can easily
be extended, even without any knowledge of PHP.

The list files are in a "standard" format - they simply consist of the
output of 'ls -lR'. They can be generated manually through the fas.php
script, or automatically in regular intervals through cron. This is useful
for searching list files of CDs or large directories on the HD that aren't
often updated.

List files can also be regenerated automatically before _each_ search.
This is slower, but useful for directories with a content that changes
frequently - e.g. upload directories of an FTP, or your own download
directory.

In order to get this feature, you need to edit the shell script "fas".
It is well commented and you only need to uncomment two lines and
specify the directory to be included in the search.

Example: To include your latest downloads to /home/myusername/downloads
in the search, uncomment the following lines in 'fas':

cd /home/myusername/downloads
LANG=C ls -lR >$1/downloads

In the first line, change the directory to the dir you'd like to have
included in all searches. In the second line, replace "downloads" by
the name of the list file you'd like to see for this dir.

This way the list file for this subdir will be recreated before each
search, so that the search results always represent the current state

Note that if the directory /home/myusername/downloads is very large,
then searches will get very slow. For running FAS on a large FTP,
I'd recommend the following configuration: A manually created list file
for the main site, and a dynamically generated list file for the upload
dir.

SECURITY

Obviously, it is not a good idea to make the content of your CD
collection accessible to everyone, especially if it contains copyrighted
material (you know, the w-word...). Therefore, it makes sense to make
FAS accessible only with a password, and/or limit access to certain IPs or
IP ranges. This can be done using the .htaccess file - for details, see
http://www.bruce-hamilton.com/tutorials/password.shtml

FAS takes user input from the web, and executes a shell command based
on this input. This is insecure by concept. Reasonable care was taken
to prevent abuse; nevertheless, you should make FAS accessible only
to trusted users.

PROBLEMS?

The most common source of problems are incorrectly set permissions.
If you cannot create a listfile, make sure the list file dir has write
permissions for the script. If in doubt, do 'chmod 777 listfiledir'.

Also make sure that the shell scripts fas and fas-* can by found by
the system. On some setups, /usr/local/bin (which is typically a good
place to put the FAS scripts) is not in the path of the user under
which apache runs. In this case, put the scripts in /usr/bin.

If you think you've found a bug, or if you've got any questions, suggestions,
or other things to tell me, don't hesitate to email me:

mail@tillmann-steinbrecher.de

Any feedback is appreciated.

I get lots of email and I sometimes don't reply all of it, but I read
every single message.

LEGAL STUFF

FAS may be used and distributed according to the terms of the GNU General
Public License, version 2. Note that this means that FAS comes without any
warranty, of any kind. If you misconfigure FAS, therefore accidentally make
your MP3 collection searchable on Google, and get busted by the RIAA, then
it's really your fault, not mine.

		    -- Till
