Guest

Cisco Unity

Unity IP Fax Outbound Gateway Configuration Example

Document ID: 62995

Updated: Jan 31, 2006

   Print

Introduction

Outbound faxing is supported with the Unity IP Fax Configuration Wizard and starts with Cisco Unity 4.04 and Cisco IOS® Software Release 12.3(7)T. This service allows users to send outbound faxes through a simple E-mail. The destination fax phone number is included in the Subject line of the E-mail and is sent to a mailbox that the Unity IP Fax service checks. The service re-formats the message, renders all attachments in the proper format, re-addresses, and sends the message. The message is sent via Simple Mail Transfer Protocol (SMTP) to the IOS gateway configured with the T.37 off-ramp feature in order to send the fax to the destination phone number. This document focuses on the configuration steps for the Cisco IOS gateway.

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 version 2.0.0.19 or later 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 off-ramp functionality and Cisco IOS Software Release 12.3(7)T or later is required along with Cisco Unity version 4.04 or later with Microsoft Exchange 2000 or 2003 as the partner message store. More information on the Cisco Unity portion of the IP Fax configuration can be found in the Unity IP Fax Configuration Wizard.

Note: T.37 off-ramp is not supported on MGCP networks. Refer to the T.37 Store and Forward Fax configuration guide for more information about platform and other restrictions for using 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 Cisco 37xx platform. Any voice gateway with IP PLUS and Cisco IOS Software Release 12.3(7)T works.

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

Refer to the Cisco Technical Tips Conventions for more information on document conventions.

Background Information

When the user sends an E-mail to the IP Fax Service mailbox, it contains [FAXPHONE=####] in the subject, where #### is the number of the destination fax machine. The IP Fax service responsibilities are to:

  • Ensure the attachments that are to be sent are valid and are rendered into the TIF type F file format.

  • Address and E-mail with the new TIF attachment to FAX=####@gateway.com.

  • Interpret and take action on any Delivery Status Notification (DSN) received from the gateway. This can include re-sending the message to the gateway (for example, busy signal or no answer), or sending a notification to the end-user (for example, wrong number).

Microsoft Exchange is responsible for:

  • The delivery of the E-mail addressed to gateway.com to the IOS gateway.

  • The delivery of any mail between the end-user to the IP fax mailbox and between the IOS gateway and the IP fax mailbox. No messages are sent either from the end-user to the gateway or vice-versa.

The IOS gateway responsibilities are to:

  • Interpret of FAX=####@gateway.com, the placement of a call to ####, and the relay of the fax using standard G3 fax protocols (T.30 and T.4).

  • Send a Delivery Status Notification (DSN) flagged as a "permanent error" to the IP Fax mailbox for every placed fax call. This allows the IP Fax service to know that the fax was sent correctly, or if there was a problem (such as busy, no-answer, and so forth). The IP Fax service is entirely responsible for handling retries and sending feedback to the sender as opposed to relying on the mail system configuration.

Gateway Configuration

There are a few commands that you must have in the Cisco IOS configuration in order for this application to work. Some of these overlap with the configuration commands required for inbound fax ("on-ramp") functionality. Note that it is easier to understand and troubleshoot if these scenarios are taken separately:

  • fax interface-type fax-mail—Configure this command on the gateway. This tells the gateway to process T.37 store and forward fax calls. The absence of this command causes incoming fax E-mails from the Exchange/Unity server to fail and T.37 router debugs are 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 off-ramp. This software is a TCL script that is run by the gateway when needed for fax off-ramp. This script software can be loaded on the internal Flash of the router or loaded off of a TFTP server. The file to download for fax off-ramp is app-faxmail-offramp.2.0.1.1.zip file located in the Cisco Software Center (registered customers only) . This file needs to be accessible by the gateway. In this sample output, the file is loaded into the internal Flash of the router since there is plenty of space.

    vnt-3725-51#show flash
    System CompactFlash directory:
    File Length Name/status
    1 23454000 c3725-ipvoice-mz.123-8.T4.bin 
    [23454064 bytes used, 104734348 available, 128188412 total]
    125184K bytes of ATA System CompactFlash (Read/Write)
    vnt-3725-51#copy tftp flash:
    Address or name of remote host []? 172.18.106.4
    Source filename []? app_faxmail_offramp.2.0.1.1.tcl
    Destination filename [app_faxmail_offramp.2.0.1.1.tcl]?
    Accessing tftp://172.18.106.4/app_faxmail_offramp.2.0.1.1.tcl...
    Erase flash: before copying? [confirm]n
    Loading app_faxmail_offramp.2.0.1.1.tcl from 172.18.106.4 (via FastEthernet0/0): !
    [OK - 5095 bytes]
    Verifying checksum... OK (0xB729)
    5095 bytes copied in 0.076 secs (67039 bytes/sec)
    vnt-3725-51#show flash
    System CompactFlash directory:
    File Length Name/status
    1 23454000 c3725-ipvoice-mz.123-8.T4.bin 
    2 5095 app_faxmail_offramp.2.0.1.1.tcl 
    [23459224 bytes used, 104729188 available, 128188412 total]
    125184K bytes of ATA System CompactFlash (Read/Write)

    The router must be told about this file and where it resides. Use the call application voice offramp flash:app_faxmail_offramp.2.0.1.1.tcl global configuration command in order to accomplish this.

    If the file is located on a TFTP server instead of Flash, the command looks like this:

    call application voice offramp tftp://172.18.106.4/app_faxmail_offramp.2.0.1.1.tcl
  • mta receive maximum <recipients>—This command specifies the number of simultaneous recipients for SMTP connections on the gateway. This command is used to limit the resource usage of the gateway. It is important to remember that the default value for this command is 0. If this command is not set to a value greater than 0, the gateway does not answer any SMTP requests. This causes all off-ramp transactions to immediately fail.

  • mta receive aliases <string>—This command is important because it identifies a valid host name that is accepted as an SMTP alias for off-ramp faxing. The string in this command can either be an IP address or DNS type host name. This command is very important because all SMTP connections fail if the "rcpt to:" field domain does not match exactly what is configured as an alias using this command. In other words, the gateway only accepts incoming mail if the destination hostname of the inbound mail matches a configured alias. Multiple aliases can be configured (maximum is 10) in order to accommodate different domain names and even IP addresses. For example, when the IP Fax service sends a message to "FAX=####@gateway.com", the command looks like:

    mta receive aliases gateway.com
  • mta receive generate permanent-error—This command is required because without it, not all DSN messages are sent back to the IP Fax service mailbox. Since DSN messages are part of the SMTP specification, the mail server (Microsoft Exchange) is expected to try to handle anything that is not a "permanent" error before it sends the message back to the sender (in this case the IP Fax service mailbox). Messages such as user busy are (by default) flagged as "transient" DSN errors. Exchange attempts to re-send the message by itself for a long period of time. The configuration of the mta receive generate permanent-error command forces the router to flag every DSN message as a permanent error so they are immediately sent back to the sender (the IP Fax service mailbox). The service itself (based on user configuration) can determine how many retries on busy/no answer should be attempted. This command is only in Cisco IOS Software Release 12.3(7)T and later. If this command is not present on your router, chances are you are running a Cisco IOS release that is older than what is required.

  • mta send server <exchange server> port 25—This command specifies the server to be used in order to return messages to the fax mailbox (such as the DSNs). This should be the IP address of the Exchange server or can be the DNS name. If the DNS name is specified, an ip name-server <ip address> command is required so that DNS can resolve the name.

  • Inbound and outbound dial-peers are required to associate the inbound SMTP message with a called fax number as well as to route the call to an outbound Telephony circuit. For example:

    dial-peer voice 5590 pots
    destination-pattern 991....
    port 2/0:23
    forward-digits all
    prefix 9
    !
    dial-peer voice 2 mmoip
    description off-ramp inbound VoiP from Unity
    application offramp
    information-type fax
    incoming called-number 991
    dsn delayed
    dsn success
    dsn failure
    !

    The POTS dial-peer itself is nothing special. This is needed for the router to route a voice call to a circuit. The important item here is the MMOIP dial-peer. It has "application offramp", which is the name associated with the TCL script ("call application voice offramp flash:app_faxmail_offramp.2.0.1.1.tcl"). The "information-type fax" is also needed to let the system know that calls that match this dial-peer are fax calls. Additionally, an incoming called-number statement is needed. This is the easiest way to associate a dialed number with a dial-peer. Note that there is no destination-pattern. It is not required because this dial-peer is only used for calls inbound (from the VoIP side). In this example, the router is allowed to accept fax calls for any number that begins with 991. The SMTP message needs to be addressed to "991XXXX@gateway.com", where XXXX can match any 4-digit number. The POTS dial-peer, because of the "destination-pattern 991....", sends the call to a PRI (port 2/0:23) while prefixing 9. Therefore, a message to "9912345@gateway.com" causes a call to be placed on the PRI in port 2/0 to number 99912345 (because of the prefix 9 command).

    The DSN commands on the MMOIP dial-peer cause delivery status to be sent for every condition (delayed/success/failure). This alone is not sufficient. The mta receive generate permanent-error command is also required so that these DSN messages are all sent with Error status, instead of possibly transient. Transient is not (for a potentially long time) sent back to the IP Fax service mailbox.

    Further product documentation and command details can be found in the Configuring T.37 Store and Forward Fax section of the Cisco Fax Services over IP Application Guide . A full configuration of a working T.37 gateway connected to a Cisco Unity server is located in the Complete Sample Configuration section of this document. SMTP calls from the Cisco Unity server are received on the FastEthernet port of the gateway and then routed out ISDN T1 PRI 2/0:23.

Complete Sample Configuration

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

vnt-3725-51#show run
Building configuration...
Current configuration : 1608 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
! 
no ftp-server write-enable
isdn switch-type primary-ni
!
fax interface-type fax-mail
mta send server 14.84.31.12 port 25
mta receive aliases vnt-3725-51.gateway.com
mta receive maximum-recipients 10
mta receive generate permanent-error
! 
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 offramp flash:app_faxmail_offramp.2.0.1.1.tcl
!
voice-port 1/0/0
!
voice-port 1/0/1
!
voice-port 2/0:23
!
dial-peer voice 5590 pots
destination-pattern 991....
port 2/0:23
forward-digits all
prefix 9
!
dial-peer voice 2 mmoip
description off-ramp inbound SMTP from Unity
application offramp
information-type fax
incoming called-number 991
dsn delayed
dsn success
dsn failure
! 
line con 0
exec-timeout 0 0
line aux 0
line vty 0 4
login
!
end
vnt-3725-51#

Verify

There is currently no verification procedure available for this configuration.

Troubleshoot

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

Related Information

Updated: Jan 31, 2006
Document ID: 62995