Reference10:Concept Faxserver
The innovaphone Fax application provides an email-to-fax and fax-to-email gateway.
The application polls an internal mailbox for arriving emails which are converted to a fax document and sent by an innovaphone FAX interface. Content in the email can be plain text, HTML, PDF files and all other files which can be converted by LibreOffice to PDF. The sent document includes a cover page if configured. The recipient's fax number is taken from the email address and defined as fax number@fax server domain. To send an email to the internal mailbox, authenticated SMTP with the configured user and password must be used.
Incoming fax documents are converted to a PDF file and forwarded to the first email address configured for the user in the PBX.
Requirements
- It is needed to have the innovaphone Linux Application Platform installed and running.
- Each user which is allowed to send and receive fax documents has got at least one email address and the fax license in the PBX.
- If multiple emails are set in the User Object the first email of the list will be used to receive incoming Fax and User it's allowed to do outgoing Fax from any of his emails that are listed in the User Object.
- A mail server which supports authenticated SMTP or version V10 SR13 or later of the Fax server application.
- Fax destinations must support T.38 (or there must be an interconnect gateway supporting T.38 in-between) or the device with the FAX interface is V11r1 or later and supports the Audio Fax feature.
Installation
Download the latest version of the innovaphone Fax application.
Log into the Linux Application Platform, go to the Applications tag, click on Upload/Update and upload the downloaded file. The installation will start automatically and the page will refresh every two seconds showing the installation process. If there is no error during the installation you will see at the end "Installation was successful". Otherwise, you will get "installation failed" and the reason why it went wrong.
Hotfix
If you have already installed the latest version of the fax application, simply download the install_incremental_faxserver_xxxx.tar.gz file for your platform (VM or IPxx10) or if you have missed some hotfixes, download the install_cumulative_faxserver_xxxx.tar.gz archive which contains all hotfixes since the final version.
Upload this hotfix archive here.
Configuration
The innovaphone fax solution consists of the Linux application and several parts of an innovaphone device: a PBX SOAP login, a PBX gateway object, the gateway FAX interface and an route to an external line.
Configuration of the PBX
The following configuration changes are done in the gateway running innovaphone PBX.
License
Following licenses are required:
- one port license:
- Necessary to register the fax interface towards below described gateway object
- n user fax license(s):
- Necessary for each PBX user with fax rights. Check under Reference10:General/License if you already have one. Set the Fax license flag for each PBX user object on the objects properties page which should be allowed to send or receive fax documents.
PBX TAPI Login
It is required to have a PBX object which can be used for SOAP login. This object must have at least group CF rights and a set password. It and the fax gateway object must be in the same group and the group active flag must be set for this object.
PBX Gateway Object
It is required to have a PBX gateway object the FAX interface can register to. The prefix option should be enabled. The object must be a member of the tapi group.
Configuration of the Gateway with FAX Interface
The following configuration changes are done in the gateway hosting the FAX Interface (could be on the same Gateway running the PBX).
FAX Interface
Register the FAX interface to the PBX gateway object with the enabled T.38 option.
WebDAV Access
If the fax server WebDAV path should not have public access or force HTTPS is enabled, the authentication of the fax server WebDAV URL must be configured for the device HTTP Client and the innovaphone-linux certificate must be trusted. The innovaphone-linux certificate is in the untrusted certificates list not before the first access to the WebDAV server by the FAX interface if a fax document should be sent.
innovaphone Linux Application Platform
The following configurations are part of the innovaphone Linux Application Platform.
Public Webdav access
If the fax server URL/user/password is not configured in your device as authenticated URL, configure faxserver/ as public Webdav path with write access on the innovaphone application platform Public Webdav Paths.
Server Configuration
- Active: Tick if this server should be started.
- Server Name: A freely selectable name for this new server instance.
- Description: A freely selectable description for this new server instance.
- Language: The default language for this fax server.
- Cover: The cover file which is used to send a cover page by this fax server.
- Trace: If ticked, the FAX interface trace on the innovaphone device is enabled.
- For an other user language or cover file of a specific slave PBX such a configuration can be added with a PBX name configuration line.
Mail Configuration
The fax server includes an email server. To send emails to the fax server SMTP authorization must be used with the configurable user and password.
- User: The user for the SMTP authorization. It must be unique for all fax servers.
- Password: The password for the SMTP authorization.
- Fax Server Domain: Incoming mails are checked against this domain and outgoing mails use it for the sender domain.
- Administrator Mail Address: The administrator mail address for error notification mails.
- SAP support: If ticked, a SAP compatible result code is appended in the response mail which can be interpreted by external applications.
If a SMTP relay host should be used for the outgoing fax server mails, the relay host can be configured with the relay hosts configuration. If the same fax server domain is shared by several fax server configurations, only one relay host can be configured for it. Each fax server configuration with a different fax server domain needs an own relay host entry in the Linux AP relay host configuration and the fax server domain must match with the sender domain field of the relay host entry.
PBX Configuration
It is necessary to add a normal PBX user with at least CF/group rights and set password to use it for the SOAP login. The user must be in the same group as the fax gateway object and the group active flag must be set. To check the Fax license for users in slave PBX it is also required the SOAP login is available in all slave PBX.
- PBX IP address: The PBX IP address for the SOAP connection.
- Port: The port for the SOAP connection.
- Dyn-PBX-Id: An Id if a dyn-PBX is used.
- User: The user name for the SOAP login.
- Password: The user password for the SOAP login.
- HTTPS: Tick if HTTPS instead of HTTP is to use.
- Fax User: The long name of the PBX gateway object.
- Linux NAT IP address: The IP address of a NAT router between the Linux AP and the PBX if a NAT is present.
- Linux NAT port: The forwarded port of a NAT router between the Linux AP and the PBX if the default port isn't used.
- WebDAV URL: This WebDAV URL must be used as authenticated URL in the PBX HTTP client.
If you want to connect to a V13 PBX, consider starting from V13 a DNS name instead of the IP (if configured in the PBX) is given back. The Linux AP has to be able to resolve the DNS name of the PBX. Otherwise you get the error message "user error: license check failed".
Fax Configuration
- Subscriber Id: The subscriber Id of the T.30 protocol, which will be sent with a fax.
- Add User Number: If ticked, the user number is appended to the subscriber id. See also Howto:Faxserver Number Plan.
- User Number Prefix: If all user numbers begin with a common prefix and the personal fax numbers are to be shortened with this prefix, it's to be configured here. This feature doesn't work with node numbers.
- Subscriber Name: The subscriber name which will be printed within the header line of each fax page.
- Alternative Subscriber Id: An alternative subscriber Id of the T.30 protocol, which will be used with a Number Map PBX object. See also Howto:Faxserver Number Plan.
- Max Call Tries: The maximum number a call tries, if a call is not successful.
- Resend Delay: Delay in minutes after which a fax is resend.
- Response Timeout: The timeout in seconds within the remote party has to response.
- Retry Timeout: The timeout in minutes within it's tried to get a free channel for the call.
- File format of forwarded fax document: The file format of the forwarded incoming fax document.
- Cover page includes user's text: If ticked, the content of the user mail is included in the cover page. Otherwise the complete content is ignored.
- Confirmation with sent document: If ticked, the response about a successful delivered fax includes the complete sent fax as PDF document.
- Modem speed: The supported modem class can be changed if necessary.
Texts
Customer specific texts can be configured language dependently here. The texts are used for the email correspondence with the users. The defined variables in the user texts are described in Howto: Faxserver User Text Variables.
Covers
Own cover files can be uploaded, downloaded or deleted here. Once uploaded the cover file can be chosen within the server configuration. Only unused files can be deleted. See Howto:Create Faxserver Cover Sheets for how to create your own cover.
Authorized Hosts
The fax server accepts mails with authenticated SMTP. If SMTP Auth isn't available, it is also possible to authorize a host with his IP address configured here. Normally an incoming mail is delivered by the SMTP Auth login. If SMTP Auth isn't used, the mail is delivered by the domain. So it isn't possible to use the same fax server domain in more than one fax server configuration.
Database
The Fax application creates the innovaphone-faxserver database to store the configuration and the fax job data. PostgreSQL is also available for other applications and any of them could create its own database. The default password is faxserver. It may be changed at the innovaphone Fax page under Config/Database.
There are tools that allow to connect to application databases remotely. It is first needed to configure the IP you are connecting from under Config/Database at the innovaphone Fax page. For the PgAdmin III it is important to use innovaphone-faxserver as service DB. The default login credentials are for the user innovaphone-faxserver with the password faxserver.
Backup and Restore
You can both manually and automatically backup the database and configuration files for the Fax application under Administration/Backup in the application platform.
Configuration details for the update server can be found here.
Configuration Files
saveinnovaphone-faxservercfgs is the command used to automatically save the cover page files with the Command File. Other configuration files needn't not be saved because the configuration of the innovaphone Fax is in the fax database.
Data
saveinnovaphone-faxserverdb is the command to automatically backup the whole fax database with the Command File. The fax database also includes the fax configuration, but not the cover page files.
Logs
saveinnovaphone-faxserverlogs to save log files with the Command File.
Appendix
Tools
NetDrive
NetDrive is a useful webdav client which can be used to access webdav of the innovaphone Linux Application Platform.
PGAdmin
PGAdmin is an administration tool for PostgreSQL databases.
Putty
Putty is SSH client to connect to the Linux Application Platform.
Known Limitations
Concurrent fax calls
The number of simultaneous fax calls is limited by different factors.
FAX Interface Channels
The number of supported fax channels on the gateway is the first of them, that will limit the calls.
Refer to the wiki article about implement large PBXs to find out the number of FAX Interface channels available on a particular innovaphone Gateway.
The number of FAX Interface channels on an IPVA is not limited by the software, but by the amount of RAM assigned to the virtual machine with IPVA. E.g. the default RAM value of 64 MB will allow to serve up to 60 fax channels on a single IPVA instance. More Fax channels could cause unexpected out of memory restart (trap) of the IPVA. To increase the number Fax channels on the IPVA, increase the RAM assigned to the VM, but consider the CPU load (e.g. on a 2,6 GHz CPU ca. 200 calls will cause 100% CPU load).
Faxserver Application
The number of simultaneous Fax calls that can be handled by the Faxserver Application are limited by 90. This number of calls can be reached on an IP-Linux instance hosted on VMWare VM with at least with 1,5 GB RAM and a 2,6 GHz CPU.
Documents with large number of pages
- Sending fax documents with large number of pages requires more memory, this could lead to problems if the maximum memory it's reached. The PHP5 configuration have a limitation of 128MB by default that can be found under etc/php5/cgi/php.ini File there is a line saying:
; Maximum amount of memory a script may consume (128MB) ; http://php.net/memory-limit [^] memory_limit = 128M
Sending fax with 200 pages or more can be enough to reach this limit, in such case we should increase the memory_limit value. Also the RAM of the Linux machine in case we are using Vmware Virtual Machine.
Incoming Fax received with many pages
- Large incoming faxes are split in files with maximum 30 pages to prevent mail sending errors (ie: attachment too large), this feature it was implemented on fax10sr14.
maximum page size can be adapted on own responsability at innovaphone.fax.mail.forward.php, Line 188: $maxPages = 30;
Issues when many Server Instances are defined
If you define more than 90 Server instances (i.e. PBXs in Config/Server/Add) you may run into several limitations imposed by the system configuration. See below for how to overcome those.
When you intend to run such a number of instances on a single LAP, please make sure that your system still performs well (e.g. by closely monitoring the Diagnostics/Status page)!
Database Access
You may run out of database connections eventually. You will see messages such as
FATAL: remaining connection slots are reserved for non-replication superuser connections
in the postgresql log file. Also, faxes will not be sent or received sometimes and the Fax server's administration user interface may be unavailable.
To fix this situation, carefully edit /etc/postgresql/9.1/main/postgresql.conf
and change
max_connections = 100 # (change requires restart)
in to e.g.
max_connections = 200 # (change requires restart)
and restart the LAP. The value of max_connections
shall be set to at least the number of fax server instances defined plus ten.
See Concept:Linux Application Platform: Database Performance Issues for more information.
Kernel Semaphores
You may run out of semaphores. You will see messages such as
20171024-101104 - Attaching to shared memory... ERROR: Could not attach to the SHM.
in the fax server log files in this case. To fix this situation, you need to
- login to your LAP with putty
- run the command
sysctl -a | grep sem
You will see something like kernel.sem = 250 32000 32 128
. This indicates that the system provides for 128 semaphores.
- edit the file
/etc/sysctl.conf
- add the following 2 lines
# shared memory config
kernel.sem = 250 128000 32 512
- save the file
- run the
sysctl -p
command sysctl -a | grep sem
should now show the updated values
The system should now provide for 512 semaphores. If you choose different values for the last value (the number of semaphores 512 in the example), make sure the second value (128000 in the example) is at least the last value multiplied with the first value (128000 = 512 * 250).
Exchange user specific "Out of Office" will be ignored
OOF (OutOfOffice) rules inside a Mailbox will be ignored by the Faxserver. (X-Auto-Response-Suppress: DR,RN,NRN,OOF,AutoReply
)
For further information and manual changes check the forum thread
Resolution
The Fax Server only supports a resolution of 200dpi. The Fax Interface expects SFF documents with a vertical resolution of 200dpi.
Known Issues
The Faxserver won't find the call in the PBX
The query User(tapi-login) and the faxserver gateway object have to be in the same PBX group. Don't use an already existing group with multiple user objects, please create a new group for only those two objects. At one point, if the group is getting too big, the faxserver will fail in finding the call in the PBX.
Failing document conversion
Conversion of documents fails. Error log shows something like
Ihr Anhang 'Mappe1.xlsx' konnte nicht konvertiert werden. Befehl: Unoconv Rückgabewert: 8 Befehlsausgabe: Input file: /var/www/innovaphone/apps/innovaphone-faxserver/tmp/1-outgoing-20171113-134139-5a099303-39d1-cfa1-c0a87a16-0101-0.xlsx UNO IllegalArgument during import phase: Source file cannot be read. Unsupported URL <file:///var/www/innovaphone/apps/innovaphone-faxserver/tmp/1-outgoing-20171113-134139-5a099303-39d1-cfa1-c0a87a16-0101-0.xlsx>:
This may be caused by an incompatibilities or unavailability of the conversion service due to performance issues
Solution: convert attachments manually to PDF before sending email2fax.
Troubleshooting
Faxserver Database
- Part of the diagnostics of the Faxserver application at Diagnostics->Calls Section we can list the calls that were done List Database Calls and the ongoing calls List Running Calls with a time/date filter. This information it's useful to check the failed fax calls (incoming or outgoing) and check the Error cause.
- Some Error Codes:
- user error: no fax recipients - Incoming email message was not providing the destination address for sending the fax. This could happen if fax server domain is missing or wrong. Also if no To: header was used to provide the destination number was used.
- user error: user not found - Error on the application/config.
- bad connection: error correction aborted, max. tries - Error on the call, bad quality signal.
- timeout during connection: training, max. tries - Error on the call, failure to sync.
- timeout during connection: no response, busy line - Error on the call, failure to connect.
- no fax device - On incoming call, no communication with a fax-device could be established - connection was discarded from opposite site.
- no response - On incoming call, no communication with a fax-device could be established - connection was terminated due to internal timeout.
- protocol error: unexpected event (...) in state (...) - various combinations indicating discard of connection due to an asynchronous communication (different states are just for internal debugging).
- file open error: authentication required - missing or wrong credentials for WebDAV Server configured on Reference9:Services/HTTP/Client
Deleting mails from the faxserver inbox
You can access the faxservers inbox by creating a POP3 account at a mail client. This is necessary if an outgoing faxcall is hanging. You need to use the same access credentials as you used in the mail configuration dialog.
Setting a fax job to closed manually
If a fax job is hanging (it remains in progress or created state) you can use the tool PGAdmin to access the database directly. Before you can connect to the database your PC needs to be granted access. Therefore you need to add you PC's IP address at Config->Database->Configure innovaphone-faxserver database access.
Afterwards use the Tool PGAdmin to connect to the Database as shown in the screenshot. The default password is 'faxserver' but you can change it at Config->Database->Change innovaphone-faxserver database password. Search the Database for fax_jobs which aren't closed. You can use the query tool if you right-click at the fax_jobs table and enter the statement from the screenshot.
SELECT * FROM public.fax_jobs WHERE progress!='closed'
You can click at the progress of this fax_job and type in closed manually. Afterwards don't forget to save it.
Related Articles
- Reference: Linux Application Platform
- Howto: Step-by-step faxserver installation
- Howto: Faxserver Number Plan
- Howto: Faxserver User Text Variables
- Howto: Create Faxserver Cover Sheets
- Howto: Printer driver solution for innovaphone faxserver
- Howto: Faxserver with Exchange
- Howto: Configure Faxserver to accept SMTP without authentication
- Howto: Department fax with Faxserver application and MS Exchange
- Howto: Multiple faxserver instances sharing a FAX interface
- Support: Quality settings for contrast adjustment