Problems configuring hylafax server on Ubuntu 12.04, 14.04

It feels wrong, writing an article about faxing in 2014 but here goes…

Getting HylaFAX to work on Ubuntu always seems to be a pain in the ass and today I’ve finally found out why. See the following bug reports:

https://bugs.launchpad.net/ubuntu/+source/uucp/+bug/255200

https://bugs.launchpad.net/ubuntu/+source/uucp/+bug/584787

All of my past attempts at getting HylaFAX to work with Ubuntu have always failed, causing me to have to switch to a different distro (usually CentOS) for HylaFAX servers. These two bug reports contain the answers.

The problem is twofold:

  1. First, permissions on /dev/ttyS* are incorrect by default (as far as HylaFAX is concerned, anyway — see the first bug report above.)
  2. Second, cu doesn’t seem to work correctly when trying to troubleshoot the problems caused by #1 (see the second bug report above.)

So here’s what you need to do in order to get a functioning HylaFAX installation [n1]:

  1. Install the necessary software:
    apt-get install cu hylafax-server
    
  2. Figure out which device node your modem is on:
    root@localhost:~# dmesg | grep ttyS
    [    0.684804] 0000:02:00.0: ttyS4 at I/O 0xda00 (irq = 21, base_baud = 115200) is a 16550A
    

You can see from the above that my modem is on /dev/ttyS4. Now before configuring HylaFAX you will need to know the class capabilities of your modem. To find that out, do the following [n2]:

  1. Create a new file: /etc/uucp/port that contains the following lines:
    #
    # Description for the TCP port - pretty trivial. DON'T DELETE.
    #
    port TCP
    type tcp
    
  2. Change the permissions on that file:
    chmod 644 /etc/uucp/port
    chown root.uucp /etc/uucp/port
    
  3. Make sure that the modem has the correct permissions on it’s device node [n3]:
    chmod 666 /dev/ttyS4
    
  4. Connect to your modem and query its capabilities [n4]:
    root@localhost:~# cu -l /dev/ttyS4
    Connected.
    at+fclass=?
    0,1,1.0,2,2.0,2.1
    OK
    ~[localhost].
    Disconnected.
    

    We see from the above output our modem supports all available classes, 0 – 2.1.

  5. Now all you need to do is run faxsetup and then faxaddmodem. I won’t cover that here (see links below) [r1] but a word of advice: when faxaddmodem asks for the “class” of your modem, make sure you have read, and you understand the characteristics of each available class before choosing [r3].

After you’ve run faxsetup and faxaddmodem [r1], you may want to configure HylaFAX to send all incoming faxes to an e-mail address as PDF attachments. You’ll need to install an MTA for this (I use postfix) and configure it as a satellite system so that your fax server will route mail through your mail server (did I mention that this assumes you already have access to a production mail server?) This is pretty trivial on Ubuntu; after running apt-get install postfix you are prompted for the type of configuration you want — satellite in this case, and once you’ve selected that option, you are prompted for the hostname/IP address of the mail server you plan on using to relay your faxes (i.e., the IP address of your production mail server.) You’ll need to ensure that that mail server is configured to relay mail coming from your fax server [r2]. Then, there are some HylaFAX specific things you’ll need to configure after you have a functioning MTA:

  1. Find out where your aliases are stored:
    root@localhost:~# postconf alias_database
    alias_database = hash:/etc/aliases
    
  2. Add the following line to that file:
    FaxDispatch:	fax@domain.tld
    
  3. Update the aliases hash:
    root@localhost:~# newaliases
    
  4. Create a file; /var/spool/hylafax/etc/FaxDispatch, that contains the following lines:
    FILETYPE=pdf;
    TEMPLATE=en;
    SENDTO="fax@domain.tld";
    
  5. Restart hylafax [n5]:
    root@localhost:~# /etc/init.d/hylafax restart
     * Stopping HylaFAX faxq                                                                                                [ OK ] 
     * Starting HylaFAX syncing directories...
    

Now go cable up your fax server and send some faxes to it!

Notes:

[1.]Installing cu is optional; you should only need it if you do not know the capabilities of your modem.

[2.] This also involves addressing the problems caused by the two bug reports mentioned at the beginning of this article.

[3.]If these permissions do not seem to work, try rebooting. If that does not work, try the following permissions:

chmod 600 /dev/ttyS4
chown uucp.dialout /dev/ttyS4

[4.] You may not see your typing echo back to the terminal; just continue typing -or- copy and paste the following in its entirety:

cu -l /dev/ttyS4
at+fclass=?
~~

Then at the [hostname] prompt, just hit the period “.” key and wait a second or two.

Make sure you are not in /var/spool/hylafax/etc when you restart HylaFAX! Part of the start/stop/restart process involves unmounting /etc/hylafax from /var/spool/hylafax/etc and then remounting it. You’ll know if you mess this up because you’ll see the following output, repeated until you hit CTRL+C:

umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))
umount: /var/spool/hylafax/etc: device is busy.
        (In some cases useful info about processes that use
         the device is found by lsof(8) or fuser(1))

Resources:

[1.] Using faxsetup and faxaddmodem:
http://www.hylafax.org/content/Handbook:Basic_Server_Configuration:Faxsetup
http://www.hylafax.org/content/Handbook:Basic_Server_Configuration:Faxaddmodem

[2.] Configure postfix to relay mail from other clients:
http://www.postfix.org/BASIC_CONFIGURATION_README.html#relay_from

[3.] Fax Classes:
http://en.wikipedia.org/wiki/Fax#Class