Unity IP Fax Inbound Gateway Configuration Example

Introduction

Cisco Unity inbound fax is supported with the Unity IP Fax Configuration Wizard starting with Cisco Unity 3.1(5) and Cisco IOS^® Software Release 12.2(8)T. This service allows users to receive faxes as attachments in their inbox and they can be alerted of new fax messages from the Cisco Unity Telephony User Interface (TUI).

Inbound faxes are initially received by a fax gateway (Cisco IOS router in this case). This gateway converts the fax into an e-mail with the fax information attached as a TIFF file. The gateway also appends the Automatic Number Identification (ANI) (or calling party number) and DNIS (or called party number) to the "Subject:" portion of the fax e-mail. An SMTP session is then used to send this fax e-mail to the Cisco Unity server, where, in conjunction with Microsoft Exchange, the e-mail is received and processed. The DNIS in the subject line is parsed and the correct destination inbox is determined based on the previous configuration of the Unity IP Fax Configuration Wizard.

This document focuses on the configuration of the Cisco IOS gateway and what is necessary to get the gateway to work with the Cisco Unity IP Fax feature. For more information on configuration for Cisco Unity for inbound fax, refer to the Unity IP Fax Inbound Gateway Configuration Example. For off-ramp or outbound gateway configuration assistance, refer to the Unity IP Fax Outbound Gateway Configuration Example.

Prerequisites

Requirements

Readers of this document should have a basic knowledge of SMTP and be familiar with a Cisco IOS VoIP configuration. A working Cisco Unity server with Unity IP Fax Configuration Wizard installed needs to be used in conjunction with the gateway configuration defined in this document in order to have a complete working system. On the IOS gateway side, a Cisco IOS router that supports T.37 on-ramp functionality and Cisco IOS Software Release 12.2(8)T or later are required along with Cisco Unity version 3.1(1) or later with Microsoft Exchange 2000 or 2003 as the partner message store. For more information on the Cisco Unity portion of the IP Fax configuration, refer to the Unity IP Fax Configuration Wizard.

Note: T.37 on-ramp is not supported on Media Gateway Control Protocol (MGCP) networks. Refer to the T.37 Store and Forward Fax configuration guide for more information about platform and other restrictions when you use T.37.

Components Used

The information in this document is based on these software and hardware versions:

• Cisco 3725 as the IOS gateway

• Cisco IOS Software Release 12.3(8)T4

Note: The gateway is not restricted to the Cisco 37xx platform. Any voice gateway with IP PLUS and Cisco IOS Software Release 12.2(8)T should work. For more information about support by specific Cisco gateway models in Cisco IOS Software Release 12.2T, refer to Table 5.1 in Configuring T.37 Store and Forward Fax.

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, make sure that you understand the potential impact of any command.

Conventions

For more information on document conventions, refer to the Cisco Technical Tips Conventions.

Background Information

It is very easy for a user to initiate the inbound fax call. The fax is sent like any normal fax. However, it is not received on another fax machine. Instead, the fax is terminated on a Cisco IOS gateway. The gateway that acts like a typical device to terminate fax receives the fax. The gateway converts the fax into a TIFF file. The gateway then forms an e-mail addressed to the configured mail server with the TIFF image as an attachment. The ANI and DNIS are inserted into the "Subject:" field of the e-mail. The gateway then uses an SMTP session to transfer the e-mail to the Cisco Unity server. From the Cisco Unity IP Fax feature perspective, these are the functions of the Cisco on-ramp gateway:

• Act as a standards based G3 fax machine in order to receive the fax successfully.

• Convert all received fax page information into the appropriate TIFF file.

• Use SMTP to relay the fax TIFF file as an e-mail to the configured mail server. The e-mail must be addressed to the fax inbox that was created on the Cisco Unity server.

• Make sure that a DNIS number is entered in the e-mail "Subject:" field in the proper format of [DNIS=####], where #### is the DNIS of the inbound fax call.

• Cisco Unity IP Fax Service will not be able to deliver messages to a hidden mail box.

On the Cisco Unity side of things a fax inbox is created using the IP Fax Configuration Wizard.  All fax e-mails must be sent to this inbox.  These e-mails are then parsed based on the DNIS in the e-mail "Subject:" field according to user-defined rules.  The Cisco Unity fax service is then responsible for moving the fax e-mail from the Cisco Unity fax inbox to the appropriate user's inbox based on the DNIS parsing.  It is important to remember that the user sees the actual fax as an e-mail TIFF attachment.  The user can be alerted of new fax messages from the Cisco Unity TUI.

Also, it is technically possible to configure the same number for voice and fax calls.  However, Cisco does not support this officially because in order to do this, the IOS router must listen for fax tones in order to separate fax calls from voice calls. Typically, for voice calls the call is supposed to go to an auto attendant, or ring a user's phone and possibly forward to voicemail.  If the router is already answering the call, then you need to use the router to play an auto attendant.  This is undesirable in an environment where you usually want Cisco Unity to provide the auto attendant functionality.

Gateway Configuration

There are a few commands that you must have in the Cisco IOS configuration for this application to work. Some of these may overlap with the configuration commands required for outbound fax ("off-ramp") functionality.

• fax interface-type fax-mail needs to be configured on the gateway. This tells the gateway to process T.37 store and forward fax calls. Without this command the received fax calls fail since they are not correctly routed via SMTP. T.37 router debugs are also unavailable until this command is added. It is important to remember that after this command is configured, you need to reload the router.

  vnt-3725-51(config)#fax interface-type fax-mail 
  You must reload the router

• The Cisco gateway requires additional software in order to run T.37 fax onramp. This software is a TCL script that is run by the gateway when it needs to process the received fax calls. This script software can be loaded on the router's internal Flash or loaded off of a TFTP server. The software is downloadable from Cisco.com and it is located in the Access section of Downloads under TCLware. The file that is needed for fax onramp is app_faxmail_onramp.2.0.1.3.tcl. This file needs to be accessible by the gateway. In this case the file is loaded into the routers internal Flash:

  vnt-3725-51#copy tftp flash
  Address or name of remote host []? 172.18.106.4
  Source filename []? app_faxmail_onramp.2.0.1.3.tcl
  Destination filename [app_faxmail_onramp.2.0.1.3.tcl]? 
  Accessing tftp://172.18.106.4/app_faxmail_onramp.2.0.1.3.tcl...
  Loading app_faxmail_onramp.2.0.1.3.tcl from 172.18.106.4 (via FastEthernet0/0): !!!
  [OK - 12262 bytes]
  
  12262 bytes copied in 0.116 secs (105707 bytes/sec)
  vnt-3725-51#

  The router must be told about this file and where it resides. This is done with the help of this global configuration command:

  vnt-3725-51(config)#call application voice onramp flash:app_faxmail_onramp.2.0.1.3.tcl 
  vnt-3725-51(config)#
  *Nov 19 15:28:40.094: //-1//HIFS:/hifs_ifs_cb: hifs ifs file read 
     succeeded. size=12262, url=flash:app_faxmail_onramp.2.0.1.3.tcl
  *Nov 19 15:28:40.094: //-1//HIFS:/hifs_free_idata: hifs_free_idata: 0x64FFAF70
  vnt-3725-51(config)# 

  Note the confirmation console message from the router that the file was successfully read. If the file is located on a TFTP server instead of Flash, then the command is:

  call application voice onramp tftp://172.18.106.4/app_faxmail_onramp.2.0.1.3.tcl
  

  For more information on how to download the T.37 scripts, refer to Configuring T.37 Store and Forward Fax.

• The ip domain-name command is used by the router at the time of the SMTP communication with Exchange. Without this command, the initial SMTP connection from the router to Exchange contains "EHLO <hostname>." This causes Exchange to terminate the session (invalid address). For the example in this document, the gateway uses the domain gateway.com. The command looks like this:

  ip domain name gateway.com
  

• The mta send server <IP address or DNSname> port <number> command is used to point the router to the mail server that receives the inbound fax e-mails. Without this command, the router does not know where to send the received faxes and the fax calls fail. It is possible to configure multiple instances of this command. However, only the first instance in the configuration is used. Other instances are only used when an SMTP transaction fails (such as invalid rcpt to:) to the first listed server. Then the next configured server is moved to the top of the list. This server is then used for subsequent onramp fax calls. This is important to remember when you troubleshoot if there are multiple mail servers configured.

  In this example, 14.80.113.13 is always used until there is an SMTP transaction failure to this server. After the failure, 14.84.31.12 is moved to the top position by the router so that it is used for all subsequent onramp fax calls.

  mta send server 14.80.113.13 port 25
  mta send server 14.84.31.12 port 25

• The mta send with-subject both command instructs the gateway to include the calling and called party number in the "Subject:" line of the e-mail. This is important to the Cisco Unity IP Fax feature since this is used to route the fax e-mail to the appropriate mailbox. While Cisco Unity can use the called number to route the call (mta send with-subject $d$) it is still recommended to use the mta send with-subject both command.

  mta send with-subject both

• The mta send mail-from hostname <name> and mta send mail-from username <name> commands are needed to prevent the SMTP transaction failure. A valid "From" e-mail address in the form "username@hostname" has to be seen by the mail server. Otherwise the SMTP transaction is disconnected and the fax e-mail is never sent. What is configured with the help of these commands is what the end user sees in the "From:" field of the fax e-mail. For a "From:" address of "fax-mail@vnt-3725-51.gateway.com", the commands look like:

  mta send mail-from hostname vnt-3725-51.gateway.com
  mta send mail-from username fax-mail

  If you want the calling number to appear as the username, use the command mta send mail-from username $s$.

• Dial peers need to be configured in order to route the fax call through the gateway. The pots dial-peer configuration is very simple. The incoming called-number command allows this dial-peer to match any inbound called number that comes into the gateway. Most real world scenarios usually have a specific fax number configured. The direct-inward-dial command takes the received call number as the number that is to be used when it makes an mmoip dial-peer match. The port command associates this pots dial-peer with a physical port on the gateway. The important command from a T.37 on-ramp perspective is the application <name> command. This command associates the on-ramp fax application with a specific pots dial peer. The <name> field is defined by the user in the call application voice <name> <file location> command. In this example, the pots dial peer uses application onramp since that is the name that were previously defined with the command call application voice onramp flash:app_faxmail_onramp.2.0.1.3.tcl.

  For the outbound VoIP side, a multimedia or mmoip dial-peer is necessary instead of the usual VoIP dial peer. Like the pots dial-peer, the mmoip dial-peer also needs the application command application fax_on_vfc_onramp_app out-bound. This application command references a script that can be seen when you look at the command show call application voice summary. The script that is needed is fax_on_vfc_onramp_app. It is also important to remember the outbound keyword so that this application is only used on outbound calls through the mmoip dial-peer.

  The destination-pattern command is used to match the inbound call number to a specific outbound mmoip dial-peer. In most circumstances, this dial-peer matches with a user's inbound fax number. The information-type fax command associates the outbound mmoip peer with T.37 fax . Without this command in the dial-peer, the gateway does not use the mmoip peers and the onramp fax call fails.

  The session target mailto:<email address> command identifies who the end user is from an e-mail perspective. While many T.37 on-ramp implementations use this command to address the fax e-mail to a specific mail user, the Cisco Unity IP Fax feature requires that the e-mail be addressed to a user configured fax inbox. All fax e-mails are sent to this one mailbox. Cisco Unity then uses the DNIS number in the "Subject:" field of the e-mail to route the fax e-mail to the appropriate end user mailbox.

  dial-peer voice 9995590 pots
   application onramp
   incoming called-number .
   direct-inward-dial
   port 2/0:23
  !
  dial-peer voice 1 mmoip
   application fax_on_vfc_onramp_app out-bound
   destination-pattern 9995590
   information-type fax
  session target mailto:fax-in@vnt-dhanes.com

For more information on product documentation and command details, refer to the Configuring T.37 Store and Forward Fax section of the Cisco Fax Services over IP Application Guide. For a full configuration of an active T.37 gateway connected to a Cisco Unity server, see the Complete Sample Configuration. Inbound fax calls are received on ISDN T1 PRI 2/0:23. Then the SMTP outbound fax e-mail to the Cisco Unity server leaves the router through interface fast Ethernet 0/0.

Complete Sample Configuration

This configuration is an example of a minimal Cisco IOS configuration for Cisco Unity inbound fax capability. The most important configuration commands are in bold font.

vnt-3725-51#show run
Building configuration...
 
Current configuration : 1808 bytes
!
version 12.3
service timestamps debug datetime msec
service timestamps log datetime msec
no service password-encryption
!
hostname vnt-3725-51
!
boot-start-marker
boot-end-marker
!
!
no network-clock-participate slot 2 
no network-clock-participate aim 0 
no network-clock-participate aim 1 
voice-card 2
 dspfarm
!
no aaa new-model
ip subnet-zero
ip cef
!         
!
ip domain name gateway.com
ip name-server 14.80.113.13
no ftp-server write-enable
isdn switch-type primary-ni
!
!
fax interface-type fax-mail
mta send server 14.80.113.13 port 25
mta send subject this is a test fax inbound to unity
mta send with-subject both
mta send mail-from hostname vnt-3725-51.gateway.com
mta send mail-from username fax-mail
 
!
!
controller T1 2/0
 framing esf
 linecode b8zs
 pri-group timeslots 1-24
!
controller T1 2/1
 framing sf
 linecode ami
!
!
interface FastEthernet0/0
 ip address 14.80.51.14 255.255.255.0
 duplex auto
 speed auto
!
interface FastEthernet0/1
 no ip address
 shutdown 
 duplex auto
 speed auto
!
interface Serial2/0:23
 no ip address
 isdn switch-type primary-ni
 isdn incoming-voice voice
 no cdp enable
!
ip default-gateway 14.80.51.1
ip classless
ip route 0.0.0.0 0.0.0.0 14.80.51.1
ip http server
!
!
control-plane
!
!
call application voice onramp flash:app_faxmail_onramp.2.0.1.3.tcl
!         
!
voice-port 1/0/0
!
voice-port 1/0/1
!
voice-port 2/0:23
!
!
dial-peer voice 9995590 pots
 application onramp
 incoming called-number .
 direct-inward-dial
 port 2/0:23
!
dial-peer voice 1 mmoip
 application fax_on_vfc_onramp_app out-bound
 destination-pattern 9995590
 information-type fax
 session target mailto:fax-in@vnt-unity.com
!
!
line con 0
 exec-timeout 0 0
line aux 0
line vty 0 4
 login
!
end

Verify

There is currently no verification procedure available for this configuration.

Troubleshoot

There is currently no specific troubleshoot information available for this configuration.

Related Information

• Cisco Unity Supported Third-party Fax Integrations
• Unity IP Fax Outbound Troubleshooting
• Voice Technology Support
• Voice and Unified Communications Product Support
• Troubleshooting Cisco IP Telephony
• Technical Support & Documentation - Cisco Systems