1. Introduction
Faxing issues are one of the most common issues reported by our customers, and certain steps should be completed when troubleshooting fax in order to determine the root cause and find a proper solution.
Firstly, we can separate faxing issues into a few categories:
Issues with inbound faxes when using the ‘Fax2email’ feature
Issues with inbound fax when using physical ATA device
Issues with outbound faxes sent via the gloCOM/Communicator application
Issues with outbound faxes sent via physical ATA device
Issues with the ‘Email2fax’ service
1.1. Difference between Fax2email and Email2fax
Before speaking of common issues and solutions regarding the fax, let’s make a difference between 2 services Fax2email and Email2fax.
These 2 services and their differences are very often confusing to the engineers that are learning about fax, so in this document we will explain what each service is and how it works.
1.1.1. Email2Fax
‘Email to Fax’ is an application that, as the name says, will be used to send faxes via email.
The application requires the email to have the following structure:
The email subject represents the number to which the fax will be sent to.
The email attachment will be the fax content that will be sent.
NOTE: The attachment must be in PDF format. If the format is not PDF that email will be skipped and deleted from the server.
The email can have multiple files attached, but there is a configurable limit on those files. (Default is max. 5 files per email)
NOTE:
Make sure the emails are arriving in the selected mailbox (they can be sent into the Spam folder or the parent folder)
The emails will be deleted from the server when the fax is sent.
Configuring Email To Fax
IMAP Server
Going to Settings -> Email To Fax you will be able to set the configuration for a server. On Multi Tenant systems this page is available per Tenant.
NOTE: Multiple tenants must not have the same IMAP configuration (imap server, username, and mailbox). This could lead to multiple faxes being sent for one email.
Be careful!
Email To Fax Settings:
Enable: Enable/Disable this feature for a server/tenant.
IMAP Server: Hostname for the server we will be listening to.
IMAP Server Port: Default 993 for TLS, 143 for STARTTLS
Encryption: SSL/TLS or STARTTLS
Username: Email that the faxes will be sent to.
Password: Used for authentication on the server.
Mailbox: Email mailbox that we will be listening to. Default INBOX.
If the mailbox folder has a sub-folder and you want to listen to that sub-folder instead then set this field as FOLDER.SUBFOLDER1 (ex. INBOX.EMAILTOFAX)
Caller ID: Defines the caller id that will be used for fax calls.
Max. Retries: Defines how many times we will try sending the fax before flagging it as failed. Default 3.
Email notifications:
Enable: Enable/Disable email notifications.
Email From: Email that will be set as FROM when sending notification.
If email notifications are enabled then the email (fax) sender will be notified if the fax was successfully sent or not.
If the email has multiple files attached, a notification email will be sent for each of those files.
Notification Email can be defined via templates on Settings -> Email Templates -> Email To Fax.
After the configuration has been saved the user can click on the TEST button to check if the configuration is working. If an error happens it will be printed in a popup window, otherwise, a success message will be displayed
E-mail Templates
Email To Fax Templates are similar to all the other templates. You can define an email Subject an email body. Inside the body you can set the following variable templates:
%STATUS% : Will be replaced with Sent or Failed.
%NUMBER%: Will be replaced with the fax number.
%DATE%: Will be replaced with the when the fax is sent.
%FILE%: Name of the file that was attached.
Max. Concurrent fax channels
Sending faxes takes a big toll on the asterisk and the server in general, so to prevent overloading on the server the number of concurrent fax calls will be limited between 1 and 9.
The number of max. concurrent fax calls can be defined in Servers -> Edit (for Multi Tenant servers in Tenants -> Master Tenant Edit ) in the Channels group. Field name is “Email To Fax”.
This value is global for the application, which means that this is the max number of concurrent fax calls for all tenants combined. The default value is 3.
EMAIL TO FAX
When the app is started it will read the configurations for all servers/tenants. For each tenant, where the Email To Fax is enabled, a process will be started and a connection to the IMAP server will be established.
Then, all the unfinished messages (from the email_to_fax_messages table) will be handled. Next, any new messages will be fetched and handled.
After that, the connection goes into the IDLE state to listen for updates. When we get notified about an update the following process is done:
Stop IDLE state
Delete all messages flagged as deleted (more explained later in the doc)
Fetch all new messages
Restart IDLE state
Handle new messages
Handling new messages includes these operations:
Save the message PDF attachment to the server. If the message does not have a PDF attachment it will be ignored and flagged as “deleted”. If saving was successful then save the message state as SAVED.
Convert the PDF file to TIFF file format. On success save the message state to CONVERTED. On failure retry converting 3 times before flagging the message as FAILED.
Add the message into the queue. The queue works on the FIFO principle.
Once the message is taken from the queue a Fax call will be originated and sending fax will start. We will be notified whether sending was a Success or if it Failed. On Success, save the message state as SUCCESS, otherwise try sending max_retries times (max_retries is defined in the GUI). If it still fails then save the message state as FAILED.
If email notifications are enabled a notification email will be sent to the sender. Message state will be saved as NOTIFIED.
Flag the message as “deleted”. All messages flagged as “deleted” will be removed from the server next time the IDLE state is stopped. This is done like this so we don’t need to stop the IDLE state for every message that needs to be deleted. (The goal is to be in the IDLE state as long as possible so we don’t miss any updates).
If the message is removed successfully then it will also be removed from the email_to_fax_messages table. If it is not removed then its state will be saved as NOTDELETED and we will try deleting it 3 times before finally flagging it as FAILEDDELETE (which should never happen)
Example configurations
Microsoft Outlook
Bicom Systems Mail
Notes for Gmail users
Some things need to be checked first before using the gmail imap server. We need to enable IMAP and the “less secure apps” option because Google needs to allow us to get the data from their servers.
Enabling IMAP
1. On your computer, open Gmail.
2. In the top right, click Settings Settings.
3. Click Settings.
4. Click the Forwarding and POP/IMAP tab.
5. In the "IMAP Access" section, select Enable IMAP.
6. Click Save Changes.
Enabling Less Secure Apps
1. Open Gmail Account
2. Go to Sign-in & security
3. Find the option "Allow less secure apps" and set it to ON
Note: After doing these two steps try testing the connection by clicking the “Test” button.
If the test is successful then disable and re-enable the application using the “Enable” Toggle. This will make the app reconnect to the server and you can start using it.
How to set up Email2fax?
STEP 1:
Create a dedicated email address (with Gmail service).
After we create a new email address, we need to open 'Settings --> See all Settings --> Forwarding and POP/IMAP'
After IMAP is enabled, click on the 'Save Changes'
In order to set up the 'E-mail to Fax' feature, please do the following:
Select a specific Tenant
Navigate to 'Fax'
Navigate to 'E-mail to Fax'
NOTE: It is needed to populate all the required fields after which this feature should be operating successfully on PBXware.
- As an IMAP server, for example, you can use 'imap.gmail.com' and use the required port 993.
- Encryption should be set to SSL/TLS;
- Username is the email address that we have set in STEP 1;
- Password is the same password that we created for our new email address.
- Everything else is configurable by the user which will not affect the email2fax functionality in regards to the service working properly.
- After that, we need to click on the Save button and we can test it out.
If the test is completed successfully, you should see the following message:
In the backend, it should look like this:
Common GUI configuration issues:
If wrong credentials are used, the following message will be displayed:
BACKEND
Also, if the server (imap server) is not responding to our request, a warning message will be shown:
BACKEND
Further, it the IMAP configuration is already used on another tenant for example, the following message is displayed
For more information about the configuration, please refer to the screenshot where all the fields required for the email2fax configuration are populated:
To further understand how 'E-mail to Fax' works and the requirements that need to be fulfilled, please check below:
Everything needs to be set correctly on PBXware (as shown above)
Users have to send an e-mail with a PDF attachment
In the 'Subject' field of the e-mail being sent, users should enter the phone number of the Fax in the same format in which it has to be dialed from PBXware
NOTE: Users should have a dedicated e-mail box for this service.
After the e-mail is sent to the e-mail address stated in the PBXware email2fax configuration, the further procedure takes place:
The 'E-mail to Fax' service is looking for new e-mails and checks whether the requirements are fulfilled.
The received e-mail needs to contain the following:
PDF file
The valid number entered in the 'Subject' field
As soon as the PDF attachment is received, it is further sent to the number that is provided in the 'Subject' of the received e-mail.
In other words, a call is placed from the PBXware to the number stated in the 'Subject' field of the received e-mail.
----------------------
This is a snap from the log when an email containing a pdf attachment and a DID in the subject looks like this:
[2021-07-29 13:42:42] INFO (Server 70): Updates Registered
[2021-07-29 13:42:42] INFO (Server 70): Closing IDLE State
[2021-07-29 13:42:42] INFO (Server 70): IDLE State Stopped
[2021-07-29 13:42:42] INFO (Server 70): Handling updates. New Messages: 1
[2021-07-29 13:42:42] INFO (Server 70): Fetched 1 new messages.
[2021-07-29 13:42:42] INFO (Server 70): Restarting IDLE
[2021-07-29 13:42:42] INFO (Server 70): IDLE Connection Re-Established. Listening for mailbox changes
[2021-07-29 13:42:42] INFO (Server 70): Parsing IMAP Message. Msg=4
[2021-07-29 13:42:42] INFO (Server 70): Found 1 message attachments. Msg=4
[2021-07-29 13:42:42] INFO (Server 70): Found 1 PDF message attachments. Msg=4
[2021-07-29 13:42:42] INFO (Server 70): Saving message state. State=SAVED Uid=4
[2021-07-29 13:42:43] INFO (Server 70): Saving message state. State=CONVERTED Uid=4
[2021-07-29 13:42:43] INFO Message Queued. QueueLen: 1
[2021-07-29 13:42:43] INFO (Server 70): Sending Fax. (tries 1/3) (running 1/3) (queuelen 0) Channel=1627558963.162 Uid=4
[2021-07-29 13:43:06] INFO (Server 70): Saving message state. State=SUCCESS Uid=4
[2021-07-29 13:43:06] INFO (Server 70): Logging Fields. ChannelID=1627558963.162 MsgID=4 Status=SUCCESS
[2021-07-29 13:43:06] INFO (Server 70): Saving message state. State=NOTIFIED Uid=4
[2021-07-29 13:38:22] INFO (Server 69): Timeout occurred. Resetting IDLE state.
[2021-07-29 13:38:22] INFO (Server 69): Closing IDLE State
[2021-07-29 13:38:22] INFO (Server 69): IDLE State Stopped
[2021-07-29 13:38:22] INFO (Server 69): Handling updates. New Messages: 0
[2021-07-29 13:38:22] INFO (Server 69): Restarting IDLE
[2021-07-29 13:38:22] INFO (Server 69): IDLE Connection Re-Established. Listening for mailbox changes
-----------------------------------------
/opt/pbxware/sh/pbxware restart email2fax
mon : shutting down
mon : kill(-61979, 15)
mon : waiting for exit
mon : bye :)
mon : write mon pid to /var/run/email2fax.mon.pid
mon : child 62070
mon : write pid to /var/run/email2fax.pid
mon : sh -c "email2fax -c /etc/pbxware/email2fax.ini"
Connected to websocket successfully, registered email2fax
Email2Fax Issues & Solutions
Common issues:
Non-dedicated e-mail
For example, if a customer is using a non-dedicated e-mail account and configure 'email2fax' service with such e-mail, it is possible that the service will not run properly.
The reason for this is how the email2fax service works, which we have explained above.
To further elaborate, for example, having a mail account with 100K e-mail already and setting such e-mail on the email2fax service.
As how the service is working in the background is that each single e-mail needs to be checked whether one contains a .pdf attachment and then whether such e-mail has a DID (some number) set in the 'Subject'.
As we mentioned above, if that is the case, email2fax service is placing the call to the DID provided faxing the attached .pdf.
The process of checking each e-mail when having 100K e-mail is not practical and can lead to service not running properly.
Other common issues that we did not replicate are related to the SMTP server:
For example, there have been cases where SMTP would close the connection for some reasons/limitations on the SMTP configuration.
One reason for this can be a timeout after which the connection to the SMTP server is closed.
To fix this issue, changes on the SMTP server are needed, for example where the server does not accept the connection from a certain IP address or after X amount of time and so on.
What we can do from the PBXware side is to change the time after which the timeout will occur.
We can do so by editing the 'email2fax.ini' file on the following path → /opt/pbxware/pw/etc/pbxware/email2fax.ini
The timeout configuration is located under '[imap]' context:
[imap]
imap_timeout = 540
tcp_timeout = 15
cmd_timeout = 15
max_attachments = 5
1.1.2. Fax2Email
What are the benefits of fax to email?
Work remotely – access incoming faxes in real-time from anywhere.
Improve productivity – no more paper jams and toner replacements.
Save on costs – no fixed line rental or maintenance costs.
Kinder on the planet – think of all the paper and toner you will save.
Greater security – no prying eyes at the fax machine, and confidential documents are sent directly to your email.
Easily configure PBXware for fax to email.
When using the fax2email feature on PBXware, once the fax is received it is converted and PBXware forwards it to the email address as an attachment. The main advantage of the fax2email feature is that there is no need for installing a fax modem, fax server, or any additional phone lines.
Fax To Email is a PBXware feature that gives users the ability to send received faxes to an email address specified in DID.
For this feature to work properly, you need to correctly complete the Setup Wizard of the system, meaning that Server Details must be correctly set → SMTP configuration must be properly set.
Now, to set the Fax To Email feature, follow these steps:
Log in to the system administration
Navigate to 'DIDs' and add/edit the existing DID
Under 'Trunk', select the trunk over which the fax will be received
Select 'Destination'='Fax to Email'
Provide the extension number or E-mail address under the 'E-mail/Extension' field (If using an Extension number, the email associated with the Extension will be used)
‘Record Call’ set to No
Click on the 'Save' button
NOTES:
When a new fax is received it is saved in'.tif' and '.pdf' format under '/home/servers/pbxware/pw/pbxware/var/fax' directory
Received faxes may also be viewed from 'System: Fax: Received FAX-s'
If the notification email with the attached fax file is not received, but the same fax can be seen under 'System: Fax: Received FAX-s', please check your email server settings
To conclude, Fax2email is a destination that a certain DID can point to on the PBXware. So, if a user sends a fax document to a fax number (which is a DID on the PBXware), and the destination for that DID is ‘Fax2email’, that fax will be forwarded to the e-mail address defined under that destination.
On the other hand, ‘Email2fax’ is a service set on PBXware, that basically handles a dedicated mail Inbox and forwards all e-mails received in that Inbox to the number set in the e-mail subject.
As shown in the picture, the Subject line contains the number to which the received e-mail will be sent, and the e-mail itself contains the PDF attachment which represents the FAX document.
2. Troubleshooting Fax process steps
When you run into the FAX issue, the first step is to determine what kind of issue are you dealing with, as mentioned in the first paragraph.
As a reminder, the possible fax issues are:
Issues with inbound faxes when using ‘Fax2email’ feature
Issues with inbound fax when using physical ATA device
Issues with outbound faxes sent via gloCOM/Communicator application
Issues with outbound faxes sent via physical ATA device
Issues with ‘Email2fax’ service
For some issues, troubleshooting process will be similar, so let’s start from the beginning.
Troubleshooting steps:
Determine the issue type
Check the PBXware GUI setup and make sure that everything is set properly
Check log files depending on the issue (Details will be explained depending on the issue)
Monitor SNGREP or obtain the PCAP depending on the issue
Later, depending on the issue type different steps will be included.
3. Issues with inbound faxes when using ‘Fax2email’ feature
One of the possible fax issues is when inbound fax is not working for a certain reason, but outbound fax works fine.
First step is to confirm with the customer what is the exact issue, and how it is described – details are important.
Questions to ask:
What Tenant (If MT in question) and DID is in question?
How are you testing – is someone sending a fax from fax machine, or you are using gloCOM/Communicator to send fax from other Tenant or other PBXware?
Make a test!
When testing inbound fax, please open SNGREP and filer INVITE with F7 for easier troubleshooting.
Press F3 for RTP.
What can be seen on the previous screenshot s that the INVITE is sent and RTP is exchanged between the PBXware and remote side.
After g711ulaw under the RTP exchange, we can see that the second INVITE is sent. If you scroll to the second INVITE, you can see the following:
After the initial RTP was exchanged, PBXware sent a re-invite that included T.38, and the remote side responded with ‘488 Not Acceptable Here’, which would indicate that we are sending T.38 and the remote side does not accept T.38.
This would lead us to check the T.38 setting on PBXware, under Protocols.
After making T.38 change, a PBXware restart is mandatory in order for changes to apply.
When it comes to inbound faxes, in most cases, the trunk provider is sending a re-invite with a different protocol, which leads to the failed fax. This part should be checked with the trunk provider.
So, if you see that there is a re-invite from the trunk provider with T.38 after the g711 exchange, please instruct the customer to contact their trunk provider.
As ‘Fax2email’ is a destination for DID, one of the possible solutions, when it comes to different protocols between PBXware and the remote side, would be to force a certain codec on DID – g711u or g711a.
The next possible issue is that even though the protocol is properly set, and RTP is matched on both sides, after T.38 negotiation, fax fails.
One of the possibilities is that v17 modem is being used.
V.17 Fax Modem software implements the ITU-T V.17 recommendation for a two-wire modem for facsimile applications with rates up to 14400bps.
The issue with the v17 modem is the fact that regardless of the speed set under the Min/Max rate, it will always use the maximum 14400bps speed.
In some cases, forcing this maximum speed might increase the chances for the fax to fail.
Recommendation: Remove the v17 modem from the list and save.
On the other hand, what happens if everything above is set, but, the fax is still not coming?
As mentioned, we monitor SNGREP, and we are looking for the PBXware → Trunk Provider Request/Response. If we only see that BYE is sent from PBXware (Asterisk), and no other relevant information, the next troubleshooting part is to look into Asterisk output.
One of the possible error outputs while looking at
grep -i fax opt/pbxware/pw/var/log/asterisk/messages is:
[Sep 15 12:54:24] ERROR[44188] res_fax.c: 'modems' setting 'V27,V29' is incompatible with 'maxrate' setting 12000
[Sep 15 12:54:24] ERROR[44188] res_fax.c: failed to load configuration file 'res_fax.conf'
[Sep 15 12:54:27] ERROR[6238] pjproject: sip_transport.c Error processing 740 bytes packet from UDP 109.170.169.208:42052 : PJSIP syntax error exception when parsing 'Authorization' header on line 8 col 22:
[Sep 15 12:54:53] ERROR[44516] res_fax.c: 'modems' setting 'V27,V29' is incompatible with 'maxrate' setting 14400
[Sep 15 12:54:53] ERROR[44516] res_fax.c: failed to load configuration file 'res_fax.conf'
[Sep 15 12:55:43] ERROR[44979][C-00012119] res_fax.c: Could not locate a FAX technology module with capabilities (RECEIVE)
[Sep 15 12:55:43] ERROR[44979][C-00012119] res_fax.c: Unable to reserve FAX session.
What we can see in the output above is that there is a problem with fax module and configuration. In this case, we navigate to the fax configuration file on the path:
/opt/pbxware/pw/etc/asterisk/res_fax.conf
Below is shown the default res_fax.conf. If you notice that something is changed in this file, it should be back to default, as it can impact the fax module functionality.
[general]
; Maximum Transmission Rate
; Possible values are { 2400 | 4800 | 7200 | 9600 | 12000 | 14400 }
; Set this value to the maximum desired transfer rate. Default: 14400
maxrate=14400
; Minimum Transmission Rate
; Possible values are { 2400 | 4800 | 7200 | 9600 | 12000 | 14400 }
; Set this value to the minimum desired transfer rate. Default: 2400
minrate=2400
; Send Progress/Status events to manager session
; Manager events with 'call' class permissions will receive events indicating the
; steps to initiate a fax session. Fax completion events are always sent to manager
; sessions with 'call' class permissions, regardless of the value of this option.
; Default: no
statusevents=yes
; modem capabilities
; Possible values are { v17 | v27 | v29 }
; Set this value to modify the default modem options. Default: v17,v27,v29
modems=v27,v29,v17
; Enable/disable T.30 ECM (error correction mode) by default.
; Default: Enabled
ecm=yes
Once you make sure that configuration is properly set, load fax modules in asterisk with commands:
asterisk -rx ‘module load res_fax_spandsp.so’
asterisk -rx ‘module load res_fax.so’
The next possible problem could be that the fax is sent successfully, however the customer is not receiving e-mail.
If you check the CLIR, and see the following:
13:24:41 | exec ReceiveFax /var/pbxware/fax/620/1631618654.0.tif,df | 200 result=0 |
| get variable FAXSTATUS | 200 result=1 (SUCCESS) |
| Reading Fax, and sending mail ... | 200 result=1 |
| Converting Fax to PDF ... | 200 result=1 |
| Sending e-mail ... | 200 result=1 |
| E-mail sent successfully. | 200 result=1 |
| Saving Fax info to database ... | 200 result=1 |
It indicates that FAX was received and it was processed successfully towards the e-mail address set under destination.
If the e-mail is not received, the issue would be related to the SMTP itself. Some of the steps to be taken are:
Replace the customer’s e-mail address with yours and test;
Check SMTP configuration and log files located under opt/pbxware/pw/var/log/ssmtp/msmtp.log
Run a manual test to check is SMTP properly set on the PBXware side;
Re-save DID, SMTP Configuration;
Reload/Restart PBXware (Helps in most cases)
Further, it is possible that the fax is sent successfully, and the e-mail is received, however it does not contain PDF attachment.
For this kind of issue, you would need to check Fax2email Template located under Master Tenant → Templates → Fax2email template, and check is Template properly enabled and configured.
4. Issues with inbound and outbound fax when using physical ATA device
What is ATA?
ATA (Analog Telephone Adapter) Devices allow standard telephones or fax machines to use VoIP by connecting them to the internet via a router. These devices have a limited feature set available.
ATA devices, along with faxing using fax machines, are quite deprecated and excluded from daily usage. Most of the customers stopped using fax machines and made a transition to the fax2email feature, however there are still customers that are using these old machines (mostly hospitals and medical centers).
As we support only a limited number of ATA devices, firstly you would need to check what ATA is in question and is it a supported device.
In the screenshot below, you can see the list of supported ATAs. Our customers mostly use Grandstream and Cisco ATAs, and as you can see we support some of the Grandstream ATAs, but there is no Cisco ATA that is supported.
If the customer is experiencing an issue with Cisco ATA, we would remind them that in-depth troubleshooting of EOL devices is not supported, however, we can take a look in case of an emergency or if it is a simple configuration issue.
When troubleshooting faxing issues with ATA, we would check the PCAP file in order to see the responses, however, if the call is established but the fax is still failing, the PCAP file could fail to give us enough necessary information.
This is because basically ATA as an analog modem is allowing two fax machines to connect. RTP exchanged here represents the sound of 2 modems communicating.
G.711 is a pulse code modulation (PCM) of voice frequencies on a 64 kbps channel. The main reason why G.711 is used in faxing is that it is an uncompressed codec that has not had any special conditioning applied as with most other voice codecs (adjustments made based on human hearing that faxes do not like).
The main issues that can occur with G.711 are jitter, packet loss, and delay.
On the other hand, T.38 as a de-facto standard was designed specifically for faxing. T.30 data is sent in HDLC frames instead of having to send everything RTP.
The main issue here is that SIP systems were not developed having in mind faxing, and therefore many SIP providers will not support T.38, so the only solution would be to force G.711 which can lead to the issues mentioned above.
If possible, we would force T.38 and advise clients to use SIP providers that do support T.38.
Test FAX with ATA
Even though we mentioned that ATAs with Fax machines are not reliable and mostly not supported, sometimes we will have to troubleshoot issues with ATA devices and failed fax.
In the next section, we will explain how to set up the Fax machine and ATA within the PBXware.
1. Connect Equipment
The fax machine is shown below. In our example, we used Panasonic KX-FP207.
In the image below, you can see the necessary cables for the fax machine which includes a basic phone line (left), and a power supply (right).
In the image below, you can see Grandstream ATA Device (HT701).
In the image below, GS ATA is shown with all the necessary cables – a LAN cable, a phone line that is connected to the Fax machine, and a power supply.
Please make sure that the LAN cable is not powered into POE, as there is already a power supply connected.
2. Factory reset ATA
The marked pinhole represents an ATA restart hole, and you can factory reset ATA by pressing the paper clip and holding it for 7 seconds.
Before any work with ATA, please make sure to factory reset it by following the instructions above.
3. Obtain ATA IP
In order to auto-provision GS ATA, you would need to obtain the ATA IP address. Please dial ‘***’ from the Fax machine, and you will enter the IVR which should tell you the IP address. If you do not hear it immediately, try dialing 0 and then 2.
https://support.stuff-fibre.co.nz/hc/en-us/articles/228908347-Grandstream-ATA-Setup
4. Set auto-provision for ATA on PBXware
As HT701 UAD is not supported, in order to provision this ATA, the HT802 template was used, and it was provisioned successfully.
On PBXware, it was the simple auto-provision procedure:
- Enable Grandstream HT802 UAD for auto-provisioning;
- Create an Extension;
- UAD: HT802, Auto-provisioning = Yes, DHCP = Yes;
- Enter MAC address that is visible on the physical ATA;
5. Auto-provision ATA on Web interface
Once you obtain the IP address of the ATA device, enter the IP address into the browser. You should be presented with the window as shown below:
Default password should be ‘admin’.
After entering the PBXware information as shown above click on ‘Apply’.
https://wiki.bicomsystems.com/en/UADs/Grandstream_HT802
Let’s take a look at the PCAP files generated when trying to test fax with ATA:
Test1
1. INVITE
We can see that the first INVITE media exchanged does not include T.38, but rather I t includes PCMU & PCMA (G.711u & G.711a).
If we scroll down to the last INVITE before ‘488 Not Acceptable Here’ response, we can see the following:
In this INVITE, we can see T.38 information exchanged.
This is the most common issue with faxing, as after the initial invite, the remote side sends a re-invite that contains different information, and we would get a failed fax.
Test2
1. INVITE
If we analyze this PCAP, we can see two call legs: ATA → System1 → System2
After the initial INVITE from ATA to PBXware that includes information with different codecs, there is an INVITE (SDP) sent from PBXware to a remote system that includes the same codecs.
However, in the later INVITE sent from ATA to PBXware, ATA is sending T.38 information, which is sent over to the remote system as well. After that, the remote side sends back an INVITE to PBXware with T.38.The response that we get here is ‘488 Not Acceptable Here’ because the PBXware does not accept T.38.
After a few tests where faxes failed with T.38, the next step would be to force G.711 codec on both sides, remote & PBXware.
Those steps would include:
Disable T.38 under Protocols.
Force G.711 codec under the DID that points to ATA.
Check if are there any additional configurations under Protocols or Extension Additional Configuration such as:
[endpoint]
t38_udptl_nat=yes
[endpoint]
t38_udptl=yes
and remove it.
However, when looking at the PCAP, we see that ATA is still sending T.38 information. This would lead to the conclusion that there is a T.38 setting within the ATA that is still forcing the T.38.
We can log into the ATA GUI and check the settings:
If you check the ‘Fax mode’, you can see that the ATA was set to T.38, which would indicate that regardless of the settings on PBXware or remote side, ATA will force its own mode.
After switching to Pass-Through, and selecting PCMA/PCMU as the primary codec, we can test again.
In the screenshot above, we can see that G.711 is now exchanged between all sides, and the fax was sent successfully.
To conclude, when troubleshooting, it is very important to check what side is sending an INVITE that contains SDP information and what codecs are sent within that SDP.
Generally speaking, as mentioned before, we should force T.38 whenever possible due to stability and reliability when compared to G.711.
Basic troubleshooting steps would be:
Enable T.38 under the Protocols section – Chose one of the ‘Enabled’ options, and the recommended one would be Enabled(FEC, MaxDatagram = 400).
Please make sure that any change under the Protocols would require PBXware restart.
Add the following lines under the Additional Configuration on ATA Extension, or system-wide – under Protocols:
[endpoint]
t38_udptl_nat=yes
[endpoint]
38_udptl=yes
NOTE: We recommend making changes on the specific endpoint (ATA Extension) rather than system-wide under the Protocols section.
Remove the v17 modem due to reasons that were explained in one of the previous chapters.
Check PCAP and see which side is sending which codec.
Enable and check the full Asterisk log by following:
vim opt/pbxware/pw/etc/asterisk/logger.conf
Remove the comment ‘;’ in front of the full.
Run asterisk -rx ‘logger reload’
Navigate to the log path and monitor it via:
tail -f opt/pbxware/pw/var/log/asterisk/full
Information under the full log can contain something like:
[Apr 9 15:14:45] FAX[12104][C-00003877] res_fax.c: FLOW T.30 Status changing to 'Far end cannot receive at the size of image'
[Apr 9 15:14:45] FAX[12104][C-00003877] res_fax.c: FLOW T.30 Image width (2258 pixels) is not an acceptable FAX image width
[Apr 9 15:14:45] FAX[12104][C-00003877] res_fax.c: FLOW T.30 The far end is incompatible
[Sep 22 08:45:18] WARNING[40693]: pjproject: <?>: SSL 6 [SSL_ERROR_ZERO_RETURN] (Read) ret: 0 len: 32000
[Sep 22 08:45:18] WARNING[41851][C-00000039]: res_fax.c:1981 receivefax_t38_init: channel 'PJSIP/Trunkv6CC-00000043' refused to negotiate T.38
Check ATA settings as described in tests.
If you see that regardless of the settings T.38 is refused, the next step would be to switch to G.711.
Disable T.38 under Protocols and restart PBXware.
Force G.711 on DID that points to ATA.
Disable T.38 on ATA itself.
Remove all the additional configuration that forces T.38.
What we observed when testing Fax:
ATA is quite unreliable and it was losing network connection quite often. We had to reconnect the LAN cable a few times to get it back online. Other phones on the same switch were connected properly and did not lose connection. ATA was not responding to the OPTIONS packet being sent.
FAX machine is unstable and not working perfectly. We had to remove the paper a lot of times and put it back again and try many options with the device itself. This part was not related to VoIP but to the Fax machine itself. As this is an old analog device, the mentioned behavior is expected.
The ‘Auto-answer’ button on the Fax machine should be selected as it puts the machine into the ‘Fax-only’ mode which worked better than ‘Tel mode’. Once the call came to the Fax machine, it rang the device, and the machine started printing fax documents.
Fax2email worked almost perfectly while testing, and it was proven a better technology compared to ATA faxing, which is expected.
It was much easier to set G.711 exchange compared to T.38. As mentioned before, G.711 is an uncompressed codec that does not require any specific conditions and it was easy to set it on both sides.
ATA was not working very well with T.38. When used the same T.38 settings that failed with ATA on gloCOM - it was successful.
NOTE: Please note that these observations are constructed as a result of our tests. Our recommendations are based on the experience and performed tests.
An example of successful FAX via gloCOM with T.38 is shown below:
As we can see on the screenshot above, there was an INVITE sent from the remote side to PBXware that included T.38 information.
On the screenshot below, we can see that 200OK was returned on T.38 information, and this fax was successfully sent.
Test 3
As ATA should support T.38, in this test we will try to set and send Fax using T.38 instead of G.711.
The steps we will take:
Set T.38 on both sides under Protocols;
Add additional configuration to enable NAT for T.38 sessions on both sides:
[endpoint]
t38_udptl_nat=yes
Set T.38 on ATA instead of Pass-Through.
Check ATA settings and make sure that UDP is selected.
After selecting UDP, make sure to remove all the codecs except G.711 on ATA Extension (due to issues related to MTU packet size)
If the final destination is Fax2email, please make sure that there is not a forced codec on DID.
Call recording must be disabled.
The image below shows successful FAX with T.38.
Reboot ATA.
5. Outbound fax from gloCOM fails
When you are experiencing issues with outbound fax via gloCOM, the steps to take are:
Remove the v17 modem from Fax settings;
V.17 Fax Modem software implements the ITU-T V.17 recommendation for a two-wire modem for facsimile applications with rates up to 14400bps.
The issue with the v17 modem is the fact that regardless of the speed set under the Min/Max rate, it will always use the maximum 14400bps speed.
In some cases, forcing this maximum speed might increase the chances for the fax to fail.
SNGREP – check what is being sent from PBXware and what is sending from the remote side.
Checking what is being exchanged between PBXware and remote side when trying to send a fax.
Depending on the output in the previous step, check and modify T.38 settings under the Protocols.
Try another FAX file.
A certain fax file might not be supported (too many pages, too high resolution, and similar).
Try another FAX number.
The remote side might not be reachable for some reason causing the fax to fail. If we successfully send a fax to another number, the initial problem would be related to that certain number/provider.
Enable the full Asterisk log and check the output.
A full log might contain more information regarding the issue.
gloCOM usually handles fax pretty well, with G.711 and T.38. When outbound fax fails, it could be due to a file that is not in the proper format or because the remote side does not accept codecs we are sending.
PCAP should give information on whether the remote side is accepting what we are sending, or not. There is not much we can do on our side, except set T.38 or disable it, as we can not impact on the remote side.
If the initial output is ‘Hangup’, that means the number is not dialed properly, or it is a non-existing number. If that happens, try dialing that number first to hear the fax tone → if you do not hear the fax tone, the fax will not be successful.
6. Common FAX questions
Maximum attachments per e-mail? = 5
Maximum pages per FAX attachment? = Recommended number is 10, everything above might pass but there is a possibility that it will fail.
Acceptable fax format? Vertical PDF.
Acceptable fax resolution? Standard fax resolution is 204 x 98 DPI & 1728x1100 pixels. Fax transmission is limited to these two parameters.
Possible resolutions via gloCOM: 204x98, 204x196 i 204x391
Fax page format choices: letter, legal, A4, Auto. The default value is "letter".