diff --git a/README.md b/README.md new file mode 100644 index 0000000..1af174d --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# GOfax.IP + +GOfax.IP is a Hylafax backend/connector providing Fax over IP support for HylaFAX using FreeSWITCH and SpanDSP through FreeSWITCH's mod_spandsp. + +In contrast to solutions like t38modem, iaxmodem and mod_spandsp's softmodem feature, GOfax.IP does not emulate fax modem devices but replaces HylaFAX's `faxgetty` and `faxsend` processes to communicate directly with FreeSWITCH using FreeSWITCH's Event Socket interface. + +GOfax.IP is designed to provide a standalone fax server together with HylaFAX and a minimal FreeSWITCH setup; the necessary FreeSWITCH configuration is provided. + +## Features + +* SIP connectivity to PBXes, Media Gateways/SBCs and SIP Providers with or without registration +* Failover using multiple gateways +* Support for Fax over IP using T.38 **and/or** T.30 audio over G.711 +* Native SIP endpoint, no modem emulation +* Support for an arbitrary number of lines (depending on the used hardware) +* Extensive logging and reporting: Writing `xferfaxlog` for sent/received faxes; Writing session log files for all sent/received faxes +* Support for modem status reporting/querying using HylaFAX native tools and clients: `faxstat` etc. +* Call screening using HylaFax' `DynamicConfig` + +## Components + +GOfax.IP consists of two commands that replace their native HylaFAX conterparts +* `gofaxsend` is used instead of HylaFAX' `faxsend ` +* `gofaxd` is used instead of HylaFAX' `faxgetty`. Only one instance of `gofaxd` is necessary regardless of the number of receiving channels. + +## Building + +GOfax.IP is implemented in Go/golang. It was developed and tested with go go version go1.2.1. As GO binaries are (almost) statically linked, they can be built on any system and just placed on the target system. + +``` +export GOPATH=$(pwd) +go install gofaxd gofaxsend +``` + +The resulting binaries `gofaxd` and `gofaxsend` are located in the `bin` directory. + +## Installation + +GOfax.IP was tested and developed on Debian 7 ("Wheezy"), so these instructions cover Debian in detail. Of course it is possible to install and use GOfax.IP on other Linux distributions and possibly other Unixes supported by golang, FreeSWITCH and HylaFAX. + +### Dependencies + +The official FreeSWITCH Debian repository can be used to obtain and install all required FreeSWITCH packages. + +Adding the repository: + +``` +echo 'deb http://files.freeswitch.org/repo/deb/debian/ wheezy main' >> /etc/apt/sources.list.d/freeswitch.list +curl http://files.freeswitch.org/repo/deb/debian/freeswitch_archive_g0.pub | apt-key add - +``` + +### Installing packages + +``` +apt-get update +apt-get install hylafax-server freeswitch freeswitch-mod-commands freeswitch-mod-dptools freeswitch-mod-event-socket freeswitch-mod-logfile freeswitch-mod-sofia freeswitch-mod-spandsp freeswitch-mod-timerfd freeswitch-mod-tone-stream freeswitch-sysvinit +``` + +It is recommended to run gofaxd using a process management system as it doesn't daemonize by itself. A configuration file for the supervisor process control system is provided in the GOfax.IP repository. To use it, the supervisor packae has to be installed: + +``` +sudo apt-get install supervisor +sudo cp config/supervisor/conf.d/gofaxd.conf /etc/supervisor/conf.d/ +``` + +### GOfax.IP + +We do not provide packages (yet), so for now the two binaries have to be installed manually. + +``` +sudo cp bin/* /usr/local/sbin/ +``` + +## Configuration + +### FreeSWITCH + +FreeSWITCH has to be able to place received faxes in HylaFAX' `recvq` spool. The simplest way to achieve this is to run FreeSWICH as the `uucp` user. + +``` +sudo chown -R uucp.uucp /var/log/freeswitch +sudo chown -R uucp.uucp /var/lib/freeswitch +sudo cp config/default/freeswitch /etc/default/ +``` + +A very minimal FreeSWITCH configuration for GOfax.IP is provided in the repository. + +``` +sudo cp -r config/freeswitch /etc/freeswitch/ +``` + +The SIP gateway to use has to be configured in `/etc/freeswitch/gateways/default.xml`. It is possible to configure multiple gateways for GOfax.IP. + +**You have to edit `/etc/freeswitch/vars.xml` and adapt the IP address FreeSWITCH should use for SIP/RTP.** + +### GOfax.IP + +Currently GOfax.IP does not use HylaFAX configuration files *at all*. All configuration for both `gofaxd` and `gofaxsend` is done in the INI-style configuration file `/etc/gofax.conf`. A sample config file is provided and has to be customized. + +``` +sudo cp config/gofax.conf /etc/ +``` + +### HylaFAX + +To make HylaFAX use `gofaxsend` for sending, the `SendFaxCmd` option has to be added to `/etc/hylafax/config`: + +``` +SendFaxCmd: "/usr/local/sbin/gofaxsend" +``` + +A sample `FaxDispatch` script is included in `config/hylafax/FaxDispatch`, the available `CALLID` values set by `gofaxd` are documented there. + +To have `faxstat` show modem/channel usage in it's status output, a modem configuration file has to exist. Note that GOfax.IP currently does not use HylaFAX' modem configuration files, so they can be empty, but they have to exist for `faxstat` to show the modem. + +If `/etc/gofax.conf` is configured to manage 5 (virtual) modems, you have to create the (empty) configuration files manually: + +``` +sudo touch /var/spool/hylafax/etc/config.freeswitch[0-4] +``` + +## Operation + +### Starting + +``` +sudo /etc/init.d/freeswitch start +sudo /etc/init.d/supervisor restart +sudo /etc/init.d/hylafax restart +``` + +### Logging + +GOfax.IP logs everything it does to syslog. diff --git a/config/gofax.conf b/config/gofax.conf index 824ea21..8a287ba 100644 --- a/config/gofax.conf +++ b/config/gofax.conf @@ -2,7 +2,8 @@ socket = 127.0.0.1:8021 password = ClueCon gateway = default -ident = +49 2932 916 230 + +ident = +1 337 header = "GONICUS LABS" ; Enable to get excessive SpanDSP debug messages in FreeSWITCH @@ -10,11 +11,20 @@ verbose = false [hylafax] spooldir = /var/spool/hylafax + +; Limit number of outbound channels modems = 5 +; Enable to make GOfax.IP write xferfaxlog +; xferfaxlog = /var/spool/hylafax/etc/xferfaxlog + [gofaxd] socket = :8022 + +; Wait before answering a incoming call (ms) answerafter = 2000 + +; Wait after answering before starting fax negotiation waittime = 1000 ; Support for rejecting calls, script has to diff --git a/config/hylafax/FaxDispatch b/config/hylafax/FaxDispatch index 49f87b3..ac7ec13 100755 --- a/config/hylafax/FaxDispatch +++ b/config/hylafax/FaxDispatch @@ -9,6 +9,6 @@ # $CALLID3 -> Recipent (SIP To-User) # -SENDTO=lindenberg@gonicus.de +SENDTO=someone@example.com NOTIFY_FAXMASTER=never FILETYPE=pdf diff --git a/src/gofaxlib/config.go b/src/gofaxlib/config.go index 9e38596..7d2df1f 100644 --- a/src/gofaxlib/config.go +++ b/src/gofaxlib/config.go @@ -35,7 +35,6 @@ type config struct { Ident string Header string Verbose bool - Cidname string } Hylafax struct { Spooldir string