Index of /server/DOC

Icon  Name                    Last modified      Size  Description
[DIR] Parent Directory                             -   
[   ] change-rootdir          18-Oct-2003 23:04  1.4K  
[   ] cover.templ             18-Oct-2003 23:04   23K  
[IMG] ringbuch.jpg            18-Oct-2003 23:04  1.6K  
[   ] single-page.ps          18-Oct-2003 23:04   23K  

Please read everything carefully. If you don't, don't bother me with mail!!!

Michael Hasenstein
http://www.tu-chemnitz.de/~mha/
http://www.csn.tu-chemnitz.de/~mha/
(soon(??): http://www.debis-sfi.de/~mha/)

mail: mha@informatik.tu-chemnitz.de
      (mha@debis.c.eunet.de; soon (hopefully) mha@debis-sfi.de, mha@chemnitz.debis-sfi.de 
                             or webmaster@debis-sfi.de)
#######################################################################################

First of all: installation of this messy code should be done by experienced users
only who understand the code. Absolutely no warranty of any kind; all I can say
is that it works well here, you will have to adjust some code for your particular
setup first. It was just an experiment that went quite well, however, I 
didn't write the scripts with clarity or portability in mind. You've been
warned!
Especially the user-admin cgi's need careful adaptation!

I'm sorry, currently everything is in German. I'm trying to translate
it, so please be patient.

- System-Security:
THERE IS NO SECURITY.
Never ever even think of using this stuff on the internet (except, like I do,
in a non-working demo) unless you _want_ hackers on your system. It is very
easy to misuse all these scripts, since I don't check the variables for
malicious code. Result: everybody may send arbitrary pieces of (perl)code instead
of the expected return values, that than get executed with the same rights your http
daemon runs with. I use it on an Intranet, so I don't care.
- Fax-Security:
In each user directory there's a file '.htaccess' containing "require user <name>".
Access to the user directories (./fax/) is only possible using a password, so users
can't see each others directories unless they know the password. I recommend
using SSL-servers, so that all these passwords crossing the net are encrypted.
You don't need to spend lots of money on a Netscape server, apache-SSL is just as
good and has the additional advantage for non-US users that it supports 128bit encryption
outside the US (this is mostly senseless, however, since you're Netscape browser is 
an export version and therefore only supports 48 bit...). I run both an encrypting
and a non-encrypting apache here using the same config files (except httpd.conf, but
you hardly ever have to change this one after installation; the only difference here
is that you must tell the SSL-server what certificate file to use). For intranets
you can sign your certificates yourself, instructions on how to do that are
included with SSLeay (did I forget to mention that you need that too?).
BTW, the patches to apache for making it use SSL are very small, they just exchange
the write/read calls with SSL_write/SSL_read calls and do some connection setup (key exchange,
blablabla).
All directories are owner and group=httpd, so only the httpd can read it (and root, of course),
rights: others=none.
In my setup (remember, 2 machines) I had to make ./fax/admin/ owner=uucp (uucp-id
of the Linux-Machine!!!), since the hylafax process on that machine that writes the files
into the mounted directories runs with uucp-rights.


Copying/Redistribution and the like:
Do whatever you like with this stuff, but don't forget to mention where you have
it from. (That means, if you delete it immediately after downloading because you
realized that it's unusable, don't forget to delete this message too! ;-))
That's all there is, it's absolutely free in all other respects. (It's your fault
if you plan using or even extending this code ...)

#######################################################################################

./DOC/
README:          this file
change-rootdir:  shell script, that helps you to adjust the hardcoded paths in the cgi's to your needs. You need to edit the variable 'NEWROOT' and run it.
single-page.ps:  coverpage template for hylafax, used for sending one-page messages in our firm
cover.templ:     default coverpage template used by hylafax; this one's added to all our fax messages that aren't generated by 'send-message.cgi' (for this one see above)
ringbuch.jpg:    the background picture. I copied it from a website, so it might be copyrighted. To change or remove it from the scripts, use the shell script 'change-rootdir' in this directory, for instructions see the script. Usually I prefer the default (grey) background, but this one time I played a bit...

./bin/
adduser:    user administration; adds a user to the system (/etc/passwd, homedir)
deluser:    vice versa
change_pw:  changes /etc/passwd-password from commandline (no prompting!)
www-passwd: changes httpd-style passwd file password (like the above program); difference between the two formats: /etc/passwd has more entries. change_pw used on httpd-password files adds a ':' at the end of the line, which is wrong (line should end there). Making these two programs one is fairly easy, just change one/two lines in change_pw.c
faxconvert: converts fax files created by the fax receiving program into gif's (two per page: an additional one turned by 180 degrees, doing that 'on the fly' when the user wants it takes too much time, and I use HP 715/64 with 128MB RAM)
mv-passwd:  user administration, moves /etc/passwd.tmp -> /etc/passwd (cgi's cant do that, no rights, and I don't want to make the entire cgi-script suid root)
server:     I use one machine for sending/receiving faxes, another one for the entire Web interface. 'server' listens on a port, when a connection comes in, it starts faxconvert. It doesn't include any protocol with the other side, it shuts down the connection immediately. 
smbprint:   print to a printer on a windows network (Samba's 'smbclient' required). This way the FaxServer http-daemon can print to locally attached printers!

./cgi-bin/
cgi's for the users, accesible only for users who are in the group 'faxuser' (see below for web-server config)

./cgi-fax/
cgi's for the fax-admin, accessible only for users who are in the group 'faxadmin' (see web-server config file section below)

./conf/
srm.conf, httpd.conf, access.conf: my config files for apache

./fax/
the user directories
the admin/ directory gets all new fax files

./html/
the html pages for the web interface

./hylafax/
faxrcvd:     comes with hylafax v3.1, lives in /var/spool/fax/bin and is called by hylafax each time a fax has been received. I added some lines, that's why it's here.

./src/
change_pw.c: sources for two of the programs mentioned above
server.c:


Scenario:
I use two machines: an old 486DX33/16MB VL (Linux) with faxmodem for sending/receiving
faxes and an HP 715/64 128MB, that's already our (intranet) web/nis/ftp/and so on-server,
for managing the rest (interface, files).
The PC is too weak for the tiff->gif conversion, unfortunately. In the beginning I had
everything running on the PC, but when there was modem activity while a fax was being
converted into gif's in most cases the modem transfer (incoming or outgoing) was
interrupted, because the machine couldn't handle the signal timing while there was
heavy activity. My conversion looks a bit odd, because I don't convert directly from tiff->gif,
but there are reasons: first, the only program I know that does this is ImageMagic, and
it really uses a lot of memory. The 128 MB of my HP weren't enough ;-).
In addition, I have to split the fax first into single pages, and I also need to flip each
page by 180 degrees. I tried to save disk space and flip a page only when a user wants
it, but that takes a loooooong time... (even on my not too small HP).
To summarize, the weakest point of a web interface for fax is the conversion of the fax files.
(If you know a better program, please let me know!)

Because I use two machines I had to invent some workarounds: 
Normally conversion is started after a fax has been received. That's no problem
wit hylafax, it calls 'faxrcvd' after receiving a fax and saving it to a file.
If the conversion took place on the same machine that runs hylafax, I would
simply start the conversion there ('faxconvert', it also updates the database file
in the admin directory, 'incoming.db'; only files listed there are visible on the web!).
Since my conversion has to run on another machine (the HP) I mounted $ROOT/admin/ 
on /var/spool/fax/recvq on the PC, so that hylafax' working directory for 
received faxes is indeed the admin's directory on the HP. After having received a fax
hylafax calls 'faxrcvd' which informs the faxadmin(s) of the new fax, and moves the files
to a new name (old name + date) and creates a file newfax-$NAME. If everything would 
be on a single machine this wouldn't be necessary. So my 'faxconvert' extracts
the name of new faxes from newfax-$NAME (and knows that there aren't new files if
there's no 'newfax-*').
Why do I change the name of received faxes (hylafax already uses unamigous names!)?
Hylafax only creates unique names as long as it sees all files there are. When I forward 
a fax to a user it is copied into this users directory, and when the admin than 
deletes its copy of the fax it is no longer visible to hylafax, i.e. it starts creating
new files with the same name. It might happen that there are more faxes for that
user that already has the other fax with the same name, so what happens?
I solved this by adding a timestamp to the filename. Quite clever, wouldn't
you say?


 Some special users get admin rights by putting them into the group 'faxadmin'.
Note that they are also in the group 'faxuser', i.e. they are regular users like 
all others, but with additional rights.
Hylafax sends mail to FaxAdmin (address can be changed in 'faxrcvd'). This address
is an alias in the sendmail alias-database that points to all users who have admin
rights. Those users can see the new fax when they enter the admin-area of the web 
interface. Now they can view,forward,print,delete the received fax.
Other (non-admin) users can see that there's a fax, but can't access it. That is because
the admin might not look immediately at new faxes, so if someone expects a certain fax
they can look if it's already there and tell the admin to forward it immediately.

Faxes that are being processed (converted into gifs) appear red (and blinking, yes; you 
may switch that off ;-)), deleting and forwarding is disabled for them (since they 
aren't complete yet, some files (gifs) are still missing, and forwarding is nothing
but copying all files from the admin directory into the users directory(ies).
You can. however, print them, since for that the original fax-file is used, not the gifs.
That's only important for the admin(s), all other users won't ever see this.

User admin is the weekest part of the interface, but it works.

Everything is quite independent of the underlying faxpackage used, so it won't be
difficult at all to use it with something else but Hylafax. 
In fact, the only interface fax-software <-> received-fax-webinterface is 'faxconvert',
that converts files from fax format (TIFF CCITT G3) into gifs (two per page).

For sending messages you only need to adapt the two calls to 'sendfax' in
cgi-bin/send-message.cgi and cgi-bin/sendfax.cgi.

I made two changes to some hylafax programs:
 - users, that send faxes from a windows machine (using the program 'winflex')
   can't tell the faxserver to always send them a message if their fax couldn't
   be sent for some reason (e.g. busy signal detected). That's why I changed
   a single line in the code, so that they now _always_ get a message.
   This problem only exists for winflex users, since commandline users
   of the unix-version can set a flag... (which is used in the cgi-scripts)

 - 'faxcover' and 'sendfax' didn't have commandline flags for some coverpage
   items. I added some flags (2 or 3, I think) in order to fully support coverpage
   generation. It was fairly easy, I really don't understand why the author left
   out. My versions of faxcover/sendfax aren't included (like the rest of hylyfax)
   since the new hylafax (v4.01) might have that already; I didn't have the time
   to upgrade my fax server, so I don't know (it's a running system after all, 
   you know what that means ;-) ["never touch a ..."]).

If you're interested in the changes I made, tell me.

I don't know how other fax packages than hylafax work (e.g mgetty+sendfax is
quite popular), but I really like the first one. Very important is a working email
system. Hylafax informs the fax admin(s) by mail of new faxes, and so do
my perl scripts when a fax gets forwarded to a user (or users, respectively).
You will have to change the lines responsible for sending mail (./fax-usr/form-mail.cgi
and forward.cgi in both cgi-dirs).
In fact, mailing will work since it's directed to local users (so the scripts don't use
any domain names), but maybe you want the From:-line adjusted and the like.

##################################
If there are important questions that I forgot to answer
please let me know (as long as your questions don't result
from not reading this file entirely; sorry, I've made
bad experiences with my Java-applet (http://www.csn.tu-chemnitz.de/~mha/international/).


MH