Installation of HylaFAX

Installing Hylafax on Ubuntu 10.04 (and also some things to do on Ubuntu 10.10 and 11.04...).

As I'm installing Hylafax I'm writing the steps I'm taking in case I need to do it twice...

First, install the client and server on your server, and the client application on all other machines that needs access to the Hylafax server.

    sudo apt-get install hylafax-client hylafax-server

The server will be started automatically on installation. However, it won't be setup for your modem...

Modem Setup for HylaFAX to use

You want to add the modem with the faxaddmodem command. To see the list of modems installed, use the faxstat command. This will tell you about the state of the server and then the TTYs used as modems and when the modem is in use, the actual job being sent.

    sudo faxaddmodem

The faxaddmodem is an interactive command form that will ask you details about your modem. Enter the data as required. In most cases, the defaults will work as is, assuming that you have a /dev/modem softlink to your modem serial port. (Note that even with a PCI card, it will be shown as a serial port.)

To test your modem you can use minicom. To test each port, use the -s option as in:

    sudo minicom -s

Minicom is a curses application. Move the cursor to "Serial port setup", hit enter and select one of you serial port. To do so, hit A and enter the /dev/ttyS# where # is 0, 1, 2, 3... You can see your available serial ports using:

    ls /dev/ttyS*

Once connected with minicom, you can test your modem by sending AT commands. Simply typing AT + enter should return OK. If not, then you're not connected. If you have multiple modems, good luck to determine which one is which...

Ctrl-A Z will open a menu that you can use to quit cleanly (you can also kill the app.)

IMPORTANT NOTE

If you upgrade your Operating System (i.e. Ubuntu 10.04 to Ubuntu 10.10) it is more than likely that you will have to rerun the faxaddmodem. I'm not too sure why, but at least in my case I had to do that and the configuration file for the TTY was completely different...

When upgrading to 11.04, I ran in yet another problem. The internal modem was always recognized as being on ttyS0. This time, it shows on ttyS4 and ttyS5. Not too sure why... At first, I was wondering why, and I looked around and found out that I could easily find the terminals using dmesg. Run this command:

    sudo dmesg | less

And then search for ttyS in the list of messages.

Authorize Users to Access HylaFAX

Once the modem is defined, you also need to authorize users. There are different ways to do that. If you are just a user centric system, where users have an account and can log in to access the fax system, then you should use the faxadduser function (WARNING: on 10.04 and 9.10 that function doesn't work right!)

   faxadduser -f host.hylafax -a blah -p blah -h localhost -u 1001 faxuser

The comment saves the result in host.hylafax (and in 10.10 it also saves it in /etc/hylafax/hosts.hfaxd even though it is not supposed to!)

To authorize anyone, or if you need to avoid having to log in with a password (i.e. you have a server and want to disable hylafax password) then you may want to enter something like this instead in the hosts.hfaxd file:

   127.0.0.1:::

This tells HylaFAX to accept any connection from the localhost (note that the name 'localhost' may not work, so using the IP is certainly a good idea here.) In effect you remove the password prompt of hylafax.

It may be that you should use backslashes in front of the periods (127\.0\.0\.1) because the period would be viewed as "any character" (i.e. regex character.) Although the 127 network is pretty safe anyway and if your fax server port is blocked by your firewall (don't tell me it isn't!!!) then it won't matter much.

Test Sending a Fax with HylaFAX

Next, you want to test sending a text fax:

    sendfax -n -d 5551212 /tmp/fax.txt

Font for Text Files for HylaFAX

You may get an error when trying to send a text file. By default HylaFAX expects TIFF files. It has the capability to convert files for you, but it may not be automatically setup. For text files, you need some Ghostscript fonts to be accessible and that will be used to convert the text file in a Postscript file which later can be transform in a TIFF image.

    textfmt: No font metric information found for "Courier-Bold".
    Usage: textfmt [-1] [-2] [-B] [-c] [-D] [-f fontname] [-F fontdir(s)] [-m N] [-o #]
       [-p #] [-r] [-U] [-Ml=#,r=#,t=#,b=#] [-V #] files... >out.ps
    Default options: -f Courier -1 -p 11bp -o 0
    Error converting document; command was "textfmt -B -f Courier-Bold -Ml=0.4in -p 11
       -s default >'/tmp//sndfaxYWticF' <'/tmp/a.txt'"

To fix this problem, you need to specify the folder where the Fontmap are located. To find them, use the locate command:

    locate Fontmap

Add the folder where Fontmap was found to the /etc/hylafax/hyla.conf file as follow:

    FontMap: /var/lib/defoma/gs.d/dirs/fonts

The map has changed in Ubuntu version 10.10. Or more precisely the folder shown here was removed. The actual font files are now in:

    FontMap:  /usr/share/fonts/type1/gsfonts

This is nice, but there is another small problem. Somehow, it does not automatically generate the Fontmap file. So even with the right path, it won't find the actual font (since it's not defined.)

Personally, I just copied the Fontmap I had on 10.04 and it worked.

The default size for the font on a fax is 11 points. You can change it by editing the /etc/hylafax/typerules file and replacing the number 11 after the -p option on the textfmt command line. For instance, for 13 points you would end up with this command line:

    textfmt -B -f Courier-Bold -Ml=0.4in -p 13 -s %s >%o <%i

Similarly, you may change the font name, margins, etc. (try man textfmt for documentation about all the options.)

HylaFAX Statistics

The sendfax command adds a fax to the Hylafax queue. To see that it is in the queue, use the faxstat command with the -s flag:

    faxstat -s

Note that the queue may already be empty if the fax was already sent by the time you run faxstat. In that case, try the -d flag instead.

At that point, your system should be ready to send faxes.

If you're interested, you can use the Gnome graphical interface gfax to handle sending faxes. Note that you will have to create a gfax user in /var/spool/gfax/user-name for that to work. So if your user name is alexis, do something like this:

    sudo mkdir -p /var/spool/gfax/alexis
    sudo chown alexis:alexis /var/spool/gfax/alexis

Then starts gfax. It may crash the first time because it will try to run Efax which is probably not available if you are using Hylafax. Restart a second time and it will be okay. Note that's a Perl script so you'll see an error on the screen when it crashes instead of... nothing.

Ah! And the first time it may show you a window and next time nothing. That's because it only adds an icon to your toolbar. Also I have problems using it to send faxes, but it's neat to look at the different spools with just a mouse click.

Modems Compatible with HylaFAX

The modem I have gives me this info on ATI0 and ATI3:

   Agere OCM V.92 MT9234ZPX-UPCI Internal Data/Fax Modem Version 1.02d

That Agere OCM modem has worked really well for me. It's an internal PCI card.

Before that I tried a Robotics (USR) and that failed miserably. I even contact USR to ask them for the AT commands to control the Fax operations and they gave me the AT commands of the modem. I stopped right there and moved on.

Update: Since then someone pointed out the Fax AT commands from Robotics.

Actually, the documentation starts here.

Upgrading

There are several problems with upgrading our system and still have hylafax working.

When I upgrading from 10.04 to 10.10 and then from 10.10 to 11.04 I had to reestablish the modem settings. Somehow it would completely reset my settings to the defaults which did not work at all with my modem.

Also, since 10.04, at each upgrade I have had to reestablish the user permissions. These are in:

/etc/hylafax/hosts.hfaxd

What I do is keep a copy of my version so when I upgrade I can restore the copy. Without that, it would instead prevent the users I have setup from connecting to Hylafax (because by default it asks for a password!)