7409 SW Tech Center Drive, Suite 100 Tigard, OR 97223 USA http://www.faxback.com Port Server RADIUS Support (RFC 2865, 2866) Version 1.0 Last edited September 2, 2010 All rights reserved. No part of this document may be copied, duplicated or reproduced without written consent from FaxBack, Inc. Copyright © 2008-2010 FaxBack, Inc.
Table of Contents Overview ....................................................................................................................................5 Account Management ...............................................................................................................6 Configuration.............................................................................................................................6 Fax ATA Call-Ahead ............................................................
FB-Rule-Group .................................................................................................................38 FB-Save-CDR...................................................................................................................39 FB-Snd-ANI ......................................................................................................................39 FB-Snd-Email ............................................................................................................
FB-V21-Frame-Error-Count...............................................................................................53 User-Name .......................................................................................................................53 UUID Mode...............................................................................................................................54 RADIUS Dictionary .....................................................................................................
Overview For account management and billing, the port server supports a flexible architecture for retrieving database objects and saving CDRs (Call Detail Records), by performing all database operations through an external module that it loads during startup. The core port server functionality of reliably sending and receiving real-time fax over HTTP remains unaffected by the type of external database module that is used.
To support “Accounting-Requests”, a RADIUS server must properly save and/or process the FaxBack vendor-specific attributes contained in RADIUS Accounting-Request packets. The port server sends Accounting Start, Alive (Interim Update), and Stop packets for every session. The text file “Port Server RADIUS Dictionary.txt” contains the RADIUS definition for all FaxBack vendor-specific attributes used by the port server.
RADIUS is an optional interface type that can be enabled for some of the databases that the port server uses. RADIUS can only be enabled for the AccountsDb (account database), RcvRoutingDb (inbound routing DID database), and BillingDb (billing database). To enable RADIUS support after the port server has been installed, run the “Fax Hardware Setup” application and select the “Databases…” button in the “Port Server” tab. A window will appear that lists all of the port server database types.
Fax ATA Call-Ahead Call-ahead support in the RADIUS server is optional. If the port server call-ahead feature is intentionally disabled, or the CalledNumbersDb database is configured to use SQL, or if only realtime fax clients will be using the port server, then the RADIUS server does not need to implement support for call-ahead. Background The port server fax ATA supports the ability to make a VoIP call directly to a fax number through a SIP media gateway in order to verify the accuracy of the fax number.
• For a fax number that resulted in a voice error, future queries of the called numbers database should return 1 (true) to flag the ATA to call-ahead directly to the fax number. Because the fax number might be a shared voice/fax line that will later be used to send a fax, it is suggested that the database records the fact that a voice error had occurred, so that future queries to the database can detect that a voice might answer the call and thus return 1 (true) to always flag the ATA to call-ahead.
Session Diagrams Send Fax Outbound faxes require one RADIUS packet exchange for real-time fax clients to retrieve information for the sending account. For fax ATAs, one or two additional calls are made to retrieve more information. The caller-id from the fax session from an ATA is used to query for a matching DID, allowing for information to be retrieved that is regarded as specific to sending line on the ATA. If a matching DID is not found, the session still proceeds without any error.
Receive Fax Inbound faxes are routed using two RADIUS packets exchanges, the first of which identifies the account associated with a DID, and the second retrieves information for that account.
Example Access Request Packets Get-Account / Account-Login Sent when a client logs in, or later validates its login credentials which it might do at any time. The port server includes a Client-Info attribute in this packet, which contains a string value from the client software. The RADIUS server must respond with an Access-Accept packet if the account and password are valid, or an Access-Reject packet if not valid.
the account is a real-time fax account, or fax ATA account. If the port server will host fax ATA accounts, then this attribute is required in the response packet. Account-Login-Group Specifies the group of Connection Servers that the client should consider for failover. If no group is specified, the client will be considered a member of the “Default Account-login Group”.
Len=18, Type=User-Password(2) Value=4D FA EA C5 A0 1A 6B FF D6 95 5E A3 FA 4A EF D9 End ◄── RESPONSE TO PORT SERVER ─── Required RADIUS Code Optional Account-Type Purpose Access-Accept or Access-Reject Purpose Determines if the account is type “Private Send/Receive” or “Shared SendOnly”, which affects how the client behaves. Also determines if the account is a real-time fax account, or fax ATA account. If the port server will host fax ATA accounts, then this attribute is required in the response packet.
Length=113 Authenticator B3 7E 5D 1C 63 6E 96 4C A3 0B E8 3D 40 61 7B 42 Attributes: Len=18, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Command(1) Value=Get-Account(1) Len=6, Type=FB-Context(2) Value=Pre-Send-Session(3) Len=9, Type=User-Name(1) Value=account Len=34, Type=Acct-Session-Id(44) Value=ea7a820446d54db8a98f42be08e65b23 Len=20, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=14, Type=FB-Dial-Number(34) Value=5551112345 Len=12, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=
FB-Save-CDR Determines if a CDR will be saved for this session. FB-Snd-ANI Specifies an ANI to use for the telephony session. FB-Snd-TSID Specifies a TSID to use for the T.30 session. FB-Rule-Group Specifies the rule group that will be used by Send Routing processing that will be performed by the port server when the RADIUS request returns. If no group is specified, the account will be considered a member of the “Default Rule Group”.
Len=34, Type=Acct-Session-Id(44) Value=03bb96b4af2d41f08dd0e46c250c274f Len=18, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=12, Type=FB-Dial-Number(34) Value=5551112345 Len=12, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Transfer-Type(58) Value=1 End ◄── RESPONSE TO PORT SERVER ─── Required Purpose RADIUS code Optional Access-Accept or Access-Reject Purpose FB-Rcv-To-Account FB-CDR-Info, FB-Customer, FB-Source Determines if the known/valid account is allowed to receive.
User-Name The account requesting to receive a fax.
FB-Command Get-Account-From-DID (2) FB-Context Pre-Receive-Session (4) User-Name The DID to match to an account Acct-Session-Id The session id of the new receive fax session.
The RADIUS server must respond with an Access-Accept packet that includes an e-mail address in the “FB-Rcv-Email” attribute for the recipient of the e-mail message, or an Access-Reject packet if routing to the DID was not possible.
Sent in response to an external component, such as a fax ATA provisioning server, requesting information about an account where only the MAC address associated with the account is known. The response from the RADIUS server can provide information that will be used to create a configuration for a fax ATA during the provisioning process. ─── SENT FROM PORT SERVER ──► Attribute FB-Command Value Get-Account-From-MAC-Address (7) FB-Context For-External-Module (5) User-Name The MAC address.
Value=account Len=76, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=70, Type=FB-Queue-Profile(57) Value= End Get-Account-From-Serial-Number / For-External-Module Sent in response to an external component, such as a fax ATA provisioning server, requesting information about an account where only the serial number associated with the account is known.
Response Packet Code=Access-Accept(2) Packet identifier=11 Length=105 Authenticator 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 Attributes: Len=9, Type=User-Name(1) Value=account Len=76, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=70, Type=FB-Queue-Profile(57) Value= End Get-Call-Ahead-Mode / Pre-Send-Session Sent at the beginning of a Send session, when all of the following criteria are met: • The FB-Transfer-Type for the sessio
Attributes: Len=18, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Command(1) Value=Get-Call-Ahead-Mode(5) Len=6, Type=FB-Context(2) Value=Pre-Send-Session(3) Len=12, Type=User-Name(1) Value=5551231234 Len=18, Type=Acct-Session-Id(44) Value=1249336279265000 End ◄── RESPONSE TO PORT SERVER ─── Required RADIUS code Optional FB-Call-Ahead-Mode Purpose Access-Accept or Access-Reject Purpose Specifies whether the fax ATA should call-ahead to verify the fax number, or whether it should immediately b
Attribute FB-Command Value Get-Account-From-Sender-Email-Address (3) FB-Context For-External-Module (5) User-Name The sender e-mail address to match to an account Request Packet Code=Access-Request(1) Packet identifier=49 Length=63 Authenticator E6 64 28 E2 03 8D 36 41 8A 2B 8F E1 79 51 08 79 Attributes: Len=18, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Command(1) Value=Get-Account-From-Sender-Email-Address(3) Len=6, Type=FB-Context(2) Value=For-External-Module(5) Len=25, Type=User-N
A response that includes additional account information is not required. To prevent the port server from detecting this situation as an error, the RADIUS server must return an Access-Accept packet that has no attributes, so that the port server can quickly advance the send session to the next stage. If the RADIUS server returns an Access-Reject packet, the port server will terminate fax session.
Language and time zone information do not need to be included, as these values are specified at the account level. If there are included in the XML returned from a Get-DID request, they will be ignored. FB-Snd-ANI An optional override of the ANI (caller Id) for later processing of the send fax.
◄── RESPONSE TO PORT SERVER ─── Required Purpose RADIUS code Optional Access-Accept or Access-Reject Purpose User-Name Specifies the name of the account that the input ANI (caller Id) from the request packet mapped to. FB-Queue-Profile An optional Queue Profile to be used for later processing of the send fax. The returned queue profile XML must include the attribute Op=”1”, to cause the DID-level queue profile to override the accountlevel queue profile.
Request Packet Code=Access-Request(1) Packet identifier=3 Length=44 Authenticator C9 EC 4F 8D AA 6D 6B 43 A2 54 E3 AE 5E B9 E6 0A Attributes: Len=18, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Command(1) Value=Get-DIDs-For-Account(9) Len=6, Type=FB-Context(2) Value=For-External-Module(5) Len=6, Type=User-Name(1) Value=TEST End ◄── RESPONSE TO PORT SERVER ─── Required Purpose RADIUS code FB-DID Access-Accept or Access-Reject One FB-DID attribute for each DID mapped to the requested accou
User-Name Acct-Session-Id Load-balance group account The session id of the new receive fax session.
Access-Request Attributes The following attributes appear in Accounting-Request and Accounting-Response packets. Acct-Session-Id Attribute Type Data Type Length RADIUS defined String (ASCII) 0-32 chars The port server will include the Acct-Session-Id attribute in Get-Account commands that precede the start of send or receive sessions. Sessions Ids are unique ASCII strings. Session Id comparisons are case-sensitive, i.e., a Session Id of “abc” is different from “ABC”.
1 The account is “Shared Send-Only”, allowing other clients to login using the same account/password. Unlimited clients can login using this account, with clients being completely independent of each other. Clients can only send faxes. 4 The account is type “Private Send/Receive”, with the same behavior as value 0 listed above, but for a client that uses the queue transfer protocol, such as a fax ATA.
FaxBack vendor-specific String (UTF-8) 0-128 chars The port server will include the FB-Client-Info attribute in the Get-Account command for the Account-Login context. The string value is created by the client, and contains information that might help identify the type of client. The string is formatted as “;=;=;” to simplify parsing individual values, for example, “;FV=1.0.0.0;MN=NICKDUO;IP=10.0.0.84”.
0 The DID is disabled for routing. When this attribute is omitted in a RADIUS response packet, the default value is 1. FB-Last-Modified-Time Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes Optional response to the Get-Account command, in both the Pre-Receive-Session and ForExternal-Module contexts, for accounts that are load-balance groups.
When this attribute is omitted in a RADIUS response packet, the default value is an empty queue profile, . An empty queue profile triggers default behavior, which includes sending fax notifications to a sender, using the local time zone and default language of the port server.
E. Africa Standard Time Georgian Standard Time Iran Standard Time Arabian Standard Time Azerbaijan Standard Time Caucasus Standard Time Mauritius Standard Time Armenian Standard Time Afghanistan Standard Time Ekaterinburg Standard Time Pakistan Standard Time West Asia Standard Time India Standard Time Sri Lanka Standard Time Nepal Standard Time N.
The port server e-mail gateway will use the value from the FB-Rcv-Email attribute as the target recipient for an e-mail message that it sends when processing received faxes. When this attribute is omitted in a RADIUS response packet, the default value is an empty string. FB-Rcv-Failover-Account-Id Attribute Type Data Type Length FaxBack vendor-specific String (UTF-8) 0-64 chars Optional response to Get-Account commands that precede the start of a receive session.
When this attribute is omitted in a RADIUS response packet, the default value is 0. FB-Rcv-Time-Expired Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes Optional response to Get-Account commands that precede the start of a receive session. This attribute determines if the account has time remaining for receiving faxes. This attribute provides a way to generate a more concise error at the port server, to better understand why an account should not receive a fax.
When this attribute is omitted in a RADIUS response packet, the default value is an empty string. FB-Save-CDR Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes Optional response to Get-Account commands that precede the start of a send or receive session.
be able to log the send failure as “sending is disabled”. If a session cannot be started, no CDR will be created. Value Meaning 0 The account has send disabled 1 The account has send enabled When this attribute is omitted in a RADIUS response packet, the default value is 1. FB-Snd-Time-Expired Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes Optional response to Get-Account commands that precede the start of a send session.
The port server will include the FB-Transfer-Type attribute in the Get-Account command for the Pre-Send-Session and Pre-Receive-Session contexts. This attribute specifies the type of connection, Real-time or Queue, that is being established. Value Meaning 1 Real-time 2 Queue FB-Upload-Logs Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes Optional response to Get-Account commands.
Accounting-Requests Session Lifecycle When the port server billing database (BillingDb) is configured to use the RADIUS interface, the port server will send RADIUS Accounting packets at three significant stages during the lifecycle of a session: • When a send or receive session for a client is authorized (Acct-Status-Type = Start) • When the client makes first contact with the port session server (Acct-Status-Type = Alive-Interim-Update) • When the session has ended (Acct-Status-Type = Stop) For every
An Accounting Start packet (Acct-Status-Type=Start) is sent after a client has been approved to send a fax. This means that the client has sent a “send request” to the connection server, and the connection server has successfully contacted a port session server that accepted the new session. The client is provided with the Url of the port session server, and the client is expected contact this server to perform the fax session.
Len=6, Type=FB-Is-Send(32) Value=1 Len=12, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Start-Time(33) Value=11/19/2008 8:29:28 PM UTC (0x49247728) Len=34, Type=Acct-Session-Id(44) Value=443291238e274109be990cf1ccd3d4b2 End Alive ─── SENT FROM PORT SERVER ──► Code=Accounting-Request(4) Packet identifier=2 Length=113 Authenticator 1B 31 8E FD DB 6E 0D 64 6F 47 88 B3 38 17 97 AF Attributes: Len=6, Type=Acct-Status-Type(40) Value=Alive-Interim-Update(3) Len=9, Type=User-Name(1) Value=account Le
Len=2, Type=FB-CDR-Info(11) Value= Len=8, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=2, Type=FB-Per-Fax-CDR-Info(31) Value= Len=41, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=35, Type=FB-Connection-Server(44) Value=Connection Server on NETSATTESTER Len=15, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=9, Type=FB-Client-Account-Id(30) Value=account Len=12, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Is-Send(32) Value=0 Len=12, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type
Len=12, Type=FB-Dial-Number(34) Value=5552223333 Len=10, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=4, Type=FB-Local-CSID(36) Value=NT Len=10, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=4, Type=FB-Remote-CSID(37) Value=NT Len=8, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=2, Type=FB-Caller-Id(35) Value= Len=12, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Start-Time(33) Value=8/5/2009 10:55:21 AM, 8/5/2009 5:55:21 PM UTC (0x4A79C789) Len=34, Type=Acct-Session-Id(44) Value=7da0c02
Len=6, Type=FB-Total-Seconds(39) Value=17 Len=12, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=6, Type=FB-Page-Count(41) Value=1 Len=35, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=29, Type=FB-Port-Server(42) Value=Port Server on NETSATTESTER Len=18, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=12, Type=FB-Dial-Prefix-Used(49) Value=@localhost Len=55, Type=Vendor-Specific(26), Id=FaxBack(30694) Len=49, Type=FB-SIP-Call-Id(50) Value=92c9b84c-3470-4662-b3c3-f4547d9ef5a3@10.0.0.
Value=0 End Accounting-Request Attributes The following attributes appear in Accounting-Request packets sent from the port server. Acct-Session-Id Attribute Type Data Type Length RADIUS defined String (ASCII) 0-48 chars A unique ASCII string that identifies the session. An example Session Id string: 78967f9a89164bb1b43132dec73d45fe.
FaxBack vendor-specific Integer 4 bytes The FB-CDR-Type attribute categorizes the CDR according to the following table. A value of 0 represents a completed real-time send or receive fax delivery. Other values relate to the processing of faxes sent to/from fax ATAs. The FB-Description attribute in the CDR will provide additional detail.
FB-Dial-Number Attribute Type Data Type Length FaxBack vendor-specific String (UTF-8) 0-64 chars For a Send, this was the send fax number. For a Receive, this is the inbound DID. FB-Dial-Prefix-Used Attribute Type Data Type Length FaxBack vendor-specific String (UTF-8) 0-60 chars For a Send, …. FB-ECM-Frame-Error-Count Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes The ECM frame error count for the fax session.
If 1 fax was a Send, of 0 fax was a Receive. FB-Local-CSID Attribute Type Data Type Length FaxBack vendor-specific String (UTF-8) 0-32 chars For sent and received faxes, the TSI for a send, the CSI for a receive. FB-Msg-Type Attribute Type Data Type Length FaxBack vendor-specific String (ASCII) 0-32 chars Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes The category of fax message.
The account that actually received the fax. This field is set only for received faxes where the primary account associated with a DID was busy or unavailable, and instead the “failover receive account” received the fax.
FB-Total-Seconds Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes The total duration of a fax session, including the dial duration and the fax session duration. FB-V21-Frame-Error-Count Attribute Type Data Type Length FaxBack vendor-specific Integer 4 bytes The V21 frame error count from the fax session. User-Name Attribute Type Data Type Length RADIUS defined String (UTF-8) 1-16 or 1-64 chars The account to be billed for the sent or received fax.
UUID Mode To simplify the RADIUS server implementation, accounts are managed by exchanging account names with the RADIUS server, even though the port server internally uses a UUID (Universally Unique Identifier) to identify each account. In general, the port server manages this distinction by converting account names into UUIDs when RADIUS responses are returned to the port server, and by converting UUIDs into account names when certain requests are sent to the RADIUS server.
RADIUS Dictionary This following RADIUS dictionary contains all port server RADIUS attributes. This information can be found in the file “Port Server RADIUS Dictionary.txt”.
ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE ATTRIBUTE FB-RTP-Count FB-Snd-On-Behalf-Of FB-Queue-Profile FB-Transfer-Type FB-Account-UUID FB-Rcv-Failover-Account-UUID FB-Call-Ahead-Mode FB-Called-Number-Result FB-Fax-Capabilities FB-Serial-Number FB-MAC-Address FB-Fax-ATA-Type FB-Provisioning-Arg FB-Upload-Logs FB-Msg-Type FB-CDR-Type FB-Description FB-R
# Values for FB-Rcv-Format VALUE FB-Rcv-Format TIFF 0 VALUE FB-Rcv-Format PDF 1 # Values for FB-Save-CDR VALUE FB-Save-CDR False 0 VALUE FB-Save-CDR True 1 # Values for FB-Snd-From-Account VALUE FB-Snd-From-Account False 0 VALUE FB-Snd-From-Account True 1 # Values for FB-Rcv-To-Account VALUE FB-Rcv-To-Account False 0 VALUE FB-Rcv-To-Account True 1 # Values for FB-Rcv-Failover-Mode VALUE FB-Rcv-Failover-Mode As-Needed 0 VALUE FB-Rcv-Failover-Mode Always 1 VALUE FB-Rcv-Failover-Mode Load-Balance-Group-Member
VALUE FB-Upload-Logs After-All-Sessions 2 # Values for FB-Msg-Type VALUE FB-Msg-Type Message 0 VALUE FB-Msg-Type SuccessNotification 1 VALUE FB-Msg-Type FailureNotification 2 # Values for FB-CDR-Type VALUE VALUE VALUE VALUE VALUE VALUE VALUE FB-CDR-Type FB-CDR-Type FB-CDR-Type FB-CDR-Type FB-CDR-Type FB-CDR-Type FB-CDR-Type Realtime Status SendFromClient ReceiveToClient Deleted Copied SendStageCompleted 0 1 2 3 4 5 6 FaxBack Proprietary and Confidential Page 58 of 58
