Home

Enterprise Messaging Gateway - User's Guide

1. Error code Description 0 No error 1 Unexpected operation 2 Syntax error 3 Unsupported parameter error 9 Requested operation failed 100 Invalid login 102 Too many users with this login id 103 Login refused 300 Incorrect destination address 302 Syntax error in user data parameter 303 Incorrect user data parameter combination D 2 SMPP Error code Description 0 No error 3 Invalid command id 4 Invalid bind status for given command 5 ESME already in bound state 8 System error 10 Invalid source address 11 Invalid destination address 12 Message ID is invalid 13 Bind failed 14 Invalid password 15 Invalid system id 20 Message queue full 21 Invalid system type 88 Throttling error ESME has exceeded allowed message limits 97 Invalid scheduled delivery time 98 Invalid message validity period Enterprise Messaging Gateway User s Guide 3 0 16 124 D 3 UCP EMI Error code Description 1 Checksum error 2 Syntax error 3 Operation not supported by system 4 Operation not allowed 5 Call barring active 6 AdC destination address invalid 7 Authentication failure 22 Time period not valid 23 Message type not supported by system 24 Message too long D 4 OIS Error code Description 0 Success 1
2. Key value Option 1 ID 2 SOURCEADDR 3 SOURCEADDRTON 4 SOURCEADDRNPI 6 SOURCEPORT 8 DESTADDR 9 DESTADDRTON 10 DESTADDRNPI 12 DESTPORT 14 UDH 15 MSGTYPE 16 MESSAGE 17 MESSAGELEN 18 VP 19 DLR 20 DELTIME 21 SCTS 27 MSGCLASS 28 CHARCODE 30 USER 3l REPLYPATH 32 PRIORITY 34 REMOTEIP 38 ROUTE 43 PROTOCOLID 59 CONNECTOR 60 OUTCONNECTOR 61 STATUS 64 SMSCID 73 CONCATSMSREF 74 CONCATSMSSEQ 75 CONCATSMSMAX 79 BILLINGID 81 DLRID 93 STARTSECS 94 STARTMSECS 95 ENDSECS 96 EMDMSECS Enterprise Messaging Gateway User s Guide 3 0 16 115 97 NOTE 106 UDHI 107 REPLACEPID 108 LRADDR 109 LRPID 110 HPLMNADDR 111 SUBJECT 112 OTOA 113 DCS 118 QPRIORITY 119 XUSERNAME C 2 Options reference C 2 1 BILLINGID 79 Billing ID Only used with UCP 4 0 C 2 2 CHARCODE 28 Character code of message Coded into the DCS Data Coding Scheme Values 0 Default GSM 1 IA5 2 8 bit binary 3 ISO 8859 1 Latin 1 4 UCS2 C 2 3 CONCATSMSMAX 75 GSM concatenated messages number of messages Encoded into UDH C 2 4 CONCATSMSREF 73 GSM concatenated messages reference number Encoded into UDH C 2 5 CONCATSMSSEQ 74 GSM concatenated messages sequence number Enterprise Messaging Gateway User s Guide 3 0 16 116 Encoded into UDH C 2 6 CONNECTOR 59
3. Enterprise Messaging Gateway User s Guide 3 0 16 35 Routing 6 Routing There are three different possibilities that determines what connector a message will be routed via They are highest priority first Any routing criteria specified for a message Any routing criteria specified for a connector The routing table The routing table is definitely the preferred method since it provides functional ity for load balancing failover and can be changed for a running server without having to restart the server Delivery reports DLRs are routed a little differently They are routed back the same way as the original message from which the DLR was requested was received unless a ROUTEDLR keyword is defined on the connector where the DLR is received or if there is a ROUTEDLR keyword specified for the user that requested the DLR 6 1 Specifying a routing criteria for a message This can be accomplished by using the ROUTE message option However it can only be used when using the MGP HTTP and SMTP protocol to send a message since CIMD2 SMPP and UCP do not provide mechanisms for setting routing parameters For example from the command line emgsend o ROUTE cimd2 1 109878 Test message 6 2 Specifying a routing criteria for a connector This can be accomplished by using the ROUTE keyword in the server configura tion file for a specific connector ROUTE cimd2 1 Please note that the route only affec
4. cerent ene 95 B 2 107 NOUCS2MAPPING eaten enen nitent ent einen ta ntn nnn 95 B 2 108 NOUSERMESSAGEREFERENCE e 95 B 2 100 OPSENTEXPIRBS 5 oasie Pert ett Peter retineo 95 B 2 110 OPS_MAXINCOMING eere 95 B 2 111 OPS MAXOUTGOING eren ene 95 B 2 112 OP5 MAXOUTSTANDING eerte 96 B 2 113 OPS MAXPERSESSION esee 96 B2414 ORIGIN srira eian Foret Ree Lente denote cee 96 B 2 115 PARSEMESSAGE eee nenatis prede 96 B 2 H6 PASSWORD nete rt tete bateria ea e Hog 96 B 2 117 PEUGIN nii Re peer Pa e RE CE Reto kc HERR e EE eY E HEY 97 Enterprise Messaging Gateway User s Guide 3 0 16 Be2 2118 POLLRECBILIVE ei taber ttn eerte retreat tete red exe 97 B 2 119 PREEIX eene etre i ee pht ice pk be RR RR EE RE HEN 97 B 2 120 PRESERVESAR eee nennen 97 B 2 121 PROMPT etie ee Dee e RE E eie be e dae ede 97 B 2 122 PROTOCOL edite ot Ieri ro ertragen Ig e open ra ctun 97 B 2 123 QUOTEDREPLY SEPARATOR enn 97 B 2 124 QUO TBDSUBJIBCT i rte rotten 98 B2125 RBEDIRBCT iirnecht iiie ines inrer Enersen nna 98 B 2 126 REGEXP_DESTADDR eene eee 98 B 2 127 REGEXP DESTADDR JIN eee 98 B 2 128 REGEXP KEYWORD ceret 98 B 2 129 REGEXP MESSAGE eene 98 B 2 130 REGEXP_SOURCEADDR ecce 98 B 2 131 REGEXP SOURCEADDR JIN
5. een 99 B 2 132 REJECT EMPTY innere ttai th ear ed ede 99 B 2 133 REMOVEPRELFIX 5 5 1 n tei triti ettet eie tee 99 B 2 134 REMOVEPREFIX SOURCEADBDR 99 B 2 135 REPLACEPREFIX 5 teet et Rr ette en et oe 99 B 2 136 REBPLACBPREPIX IN terree rper eie 99 B 2 137 REPLACEPREFIX_SOURCEADDDR 99 B 2 138 REPLACEPREFIX SOURCEADDR JIN 100 B 2 139 REQUIRBPRPBPIX 5 itte rrt tee tees 100 B 2 140 REQUIREPREFIX SOURCEADDR 100 B 2 141 RETRYSCHEME 1 eher hates 100 B 2 142 RETR Y TIME etin rer eto treibt trei a 100 B 2 143 REV DER eerte tacet ra tice ei e eee ka Haeo Ene 100 B 2 44 RENDER IN iier tret rerit tetti ttt enr teda 100 B 2 145 ROUTE dta east tee tie rece bre eb Code Eae 101 B 2 146 ROUTBDLR ettet deret er etas 101 B 2 147 ROUTING tenter tert eie nas 101 B 2 148 SATPOOL CRBATB rte ertet 101 B 2 149 SATPOOL CREATE IN eene 101 B 2 150 SATPOOL LOONRJUD eerie recorte 101 B 2 151 SATPOOL LOOKUP IN eee 101 B 2 152 S CA ADDR irrito eid eie peer Brite Reese aae 102 B 2 153 SCAADDRNDPI iterare dees eine tee risen eder tne 102 B 2 154 SCAADDRTON beni eR Eee hacerla ettet ea edad 102 B 2 155 SENDERADDRESS eese enn 102 B 2 156 SEPARATOR screenide 102 B 2 157 SERVICBETYPDE tette tr rtt ite tienes 102
6. Enterprise Messaging Gateway User s Guide 3 0 16 14 Overview Message is delivered through the connector if possible If the connector fails failover options are checked and the message may be re routed correspond ingly to another connector When a message is deleted or queried first the routing log is checked If the mes sage has been relayed usually to an SMSC the endpoint is queried if possible Message status RELAYED indicates that the message has been relayed but the final result is unknown However status DELIVERED indicates that the mes sage has been delivered to the recipient When a message is sent to an SMSC the message status is RELAYED until further information is available while if for example a HTTP connector delivers the message the status will be DELIV ERED Messages placed in connector queues or orphaned can be made to expire when the validity period if present for the message is reached When running without message persistence option messages are stored in RAM during their life cycle and will be lost if server is stopped ungracefully With the message persistence option messages DLRs and keyword sessions are persisted on file for their life time 2 9 Routing log 2 10 Orphans When a message is processed by EMG it is entered into the routing log The routing log is used to keep track of the most recent messages their state and what connector they were received and sent out at The maximum number of
7. F 14 EMG 3 0 3 6691 Minor release New connector option REJECT_EMPTY for rejecting messages with empty message body CMR Fix for CMR where messages could be routed under high server load Ported from EMG 2 5t DLR Problem with UCP DLR matching when id overflow DLR Fixed problem with DLR matching when FORCE_DESTADDR was used GSM New connector options for protocol GSM SCAADDR SCAAD DRTON and SCAADDRNPI used to set SMSC address in message PDU GSM Always use capital letters when hex encoding in driver for GSM modems HTTP Always URL encode MGP option values sent over HTTP MGP Requesting route log via MQP could cause emgd to crash MIME Do not insert CRLF before boundary attribute in Content Type header MIME Handle when space is missing after in headers MIME Potential buffer overflow in MIME part ids MMS Force connection close when using HTTP 1 0 MMT Various MM7 fixes SAT QUOTEDREPLY did not work properly SAT Subject was not saved properly when using SAT with SMTP ARCOR Added Arcor multimessage packet logging Orphans A small ORPHANSSIZE was used emgd could crash on server star tup Authentication When authenticating from database emguser and useraccess was joined improperly allowing access to server from any IP address Authentication Separate warning message when user has exceeded max number of simultaneous sessions Credits Improved handling of credits charging 1 credit when receiving mes s
8. O none 1 3 1 MGP SMPP O none none 1 2 UCP MGP 0 1 none 0 2 3 1 MGP UCP none 1 2 C 2 29 PROTOCOLID 43 Protocol identifier GSM 3 40 C 2 30 QPRIORITY 118 Specifies the queue priority in EMG A message with a lower value is always processed before a message with a higher value when message queues are pro cessed in EMG Values 1 Highest priority 2 3 Normal 4 5 Lowest priority Default value 3 C 2 31 REMOTEIP 34 IP of the client that sent the message Enterprise Messaging Gateway User s Guide 3 0 16 120 C 2 32 REPLACEPID 107 Replace PID or RPID Applies to UCP Introduced in EMG 1 0h C 2 33 REPLYPATH 31 Reply path C 2 34 ROUTE 38 Message specific route The option value must be a valid connector name The specified connector will be used instead of any routes specified in the routing table or on the incoming connector C 2 35 SCTS 21 Service Center TimeStamp C 2 36 SMSCID 64 Message id assigned by the remote SMSC The exact format and value of this option is protocol and SMSC dependent C 2 37 SOURCEADDR 2 Source or sender address C 2 38 SOURCEADDRNPI 4 Source address number plan indicator For possible values see DESTADDRNPI C 2 39 SOURCEADDRTON 3 Source address type of number For possible values see DESTADDRTON C 2 40 SOURCEPORT 6 Source port Encoded into the UDH C 2 41 STARTMSECS 94 Timestamp when mess
9. tion Applies to HTTP basic auth and SMTP plain login cram md5 Introduced in EMG 2 5 B 2 191 XAUTHPASSWORD Syntax XAUTHPASS WORD lt string gt Specifies a password for protocol authentication Applies to Outgoing HTTP basic auth and SMTP plain login cram md5 Introduced in EMG 2 5 B 2 192 XAUTHUSERNAME Syntax XAUTHUSERNAME lt string gt Specifies a username for protocol authentication Applies to Outgoing HTTP basic auth and SMTP plain login cram md5 Introduced in EMG 2 5 B 2 193 XPASSWORD Syntax XPASSWORD lt string gt External password Used for connector authentication when authentication is done in more than one step B 2 194 XUSERNAME Syntax XUSERNAME lt string gt External username Used for connector authentication when authentication is done in more than one step B 3 DB options Options used when specifying database profiles Example Enterprise Messaging Gateway User s Guide 3 0 16 109 B 3 1 DBNAME B 3 2 HOST DB mysql dbl lt HOST localhost PORT 3306 DBNAME emgdb USERNAME emguser PASSWORD secret gt Syntax DBNAME lt string gt Database name Syntax HOST lt string gt Hostname used when connector to database B 3 3 INSTANCES Syntax INSTANCES lt integer gt Specifies how many instances should be created Each instance represents one static connection to the database server Currently only the values 0 and 1 are al
10. A message is represented as a unique object identified by its unique message id that is assigned a number of properties of which some can be set by the user and some are set by the system Each property is a key value pair where the numeric key identifies the property Usually a message are assigned at least the following user level properties ID unique message id key value 1 DESTADDRESS destination address or recipient 8 MESSAGE message data 16 These properties are referred to as MGP options where MGP stands for the Mes saging Gateway Protocol A list of key values can be found in the chapter MGP options Enterprise Messaging Gateway User s Guide 3 0 16 13 Overview 2 3 Binary messages and User Data Header UDH EMG supports binary or 8 bit messages including User Data Header UDH This enables sending of ringtones logos WAP push OTA and other messages containing other information than plain text When converting from one protocol to another message and optionally splitting messages UDH properties are pre served 2 4 Long messages 2 5 MMS According to the GSM specification one message SMS cannot exceed 160 sep tets or 140 octets in length However sometimes it is necessary to send more information than that in one message This is solved by splitting the message into multiple messages and indicate that they belong together by using the GSM 3 40 UDH feature concatenated message EMG han
11. B 2 49 FORCE DESTADDBDR e eeeeteeee tenente nennen B 2 50 FORCE DESTADDR JIN eere B 2 51 FORCE DESTADDRNPI eere B 2 52 FORCE DESTADDRNPI IN B 2 53 FORCE DESTADDRTON eeeeeeeeeenen nennen B 2 54 FORCE DESTADDRTON IN B 2 55 FORCE DESTPORT IN eere B 2 56 FORCE DLR 4 oriri tente etie de Dp auc B 2 57 FORCE MESSAGE rtr tertie ead B 2 58 FORCE PRIORITY eee ee B 2 59 FORCE PROTOCOLID e eeeeeceneee eerte nhe ttnetn ni B 2 60 FORCE SERVICETYBPE eee B 2 61 FORCE SERVICETYPE IN B 2 62 FORCE SOURCEADDBDR eere B 2 63 FORCE SOURCEADDR IN B 2 64 FORCE SOURCEADDRNPI B 2 65 FORCE SOURCEADDRNPI IN B 2 66 FORCE SOURCEADDRTON B 2 67 FORCE SOURCEADDRTON IN Enterprise Messaging Gateway User s Guide 3 0 16 B 2 68 FORCE SOURCEPORT IN eere 88 B 2 69 FORCE VD dien Gebet eei eo pa R Led eve 89 B 2 70 GSMNOSCA e eeeeseeseeesseee eene enne trennen ea a trente 89 B 2 71 GSMS TORE cro nire ti eer e Ree Eee edo naii 89 B212 HEX ID E 89 B 2 73 HOMBZIMSI iiie dre net tier ine tee 89 B274 HOME VLR iier bend e plo pero ebd se ee E 89 B 2 75 IDEETIMBOUT nr hber retten tti Pere 90 B 2 76 IGNOREMAXTOTALQUEUESIZE 90 B 2 77 INHBRILL niani e nee 90 B 2 78 INITS TRING wis iii esito tees cur pae He phe tat ph te Ehe Eee
12. Connector on which message was received C 2 7 DCS 113 Data Coding Scheme Defined in GSM 3 38 C 2 8 DELTIME 20 Delivery time C 2 9 DESTADDR 8 Destination or recipient address C 2 10 DESTADDRNPI 10 Destination address number plan indicator GSM 3 40 Values Unknown default ISDN Data numbering plan X 121 Telex Private ERMES 15 Reserved for extension Ota A GV c C 2 11 DESTADDRTON 9 Destination or recipient address type of number GSM 3 40 Values 0 Unknown default 1 International number 2 National number 3 Network specific number 4 Subscriber number 5 Alphanumeric 6 Abbreviated number 7 Reserved for extension Enterprise Messaging Gateway User s Guide 3 0 16 117 C 2 12 DESTPORT 12 Destination port Encoded into the UDH Used to send binary messages like ringtones WAP push etc C 2 13 DLR 19 Delivery Receipt C 2 14 DLRID 81 Message id of original message C 2 15 ENDMSECS 96 Timestamp when message finished by EMG millisecs This option only holds the milliseconds part of the time Values 0 999 C 2 16 ENDSECS 95 Timestamp when message finished by EMG seconds The milliseconds of this value is stored in ENDMSECS The value of the option is the time in seconds since 1 January 1970 UTC C 2 17 HPLMNADDR 110 Applies to UCP Introduced in EMG 1 0h C 2 18 ID 1
13. Enterprise Messaging Gateway User s Guide 3 0 16 B248 ee ES B 2 19 DEFAULT CHARCODE eceteeseeete rien bande B 2 20 DEFAULT DESTADDRNPI B 2 21 DEFAULT DESTADDRNPI IN B 2 22 DEFAULT DESTADDRTON B 2 23 DEFAULT DESTADDRTON IN B224 DEFAULT DLR etir arat er reete repetentes B 2 25 DEFAULT DLRADDREBSS 1 2z eene B 2 26 DEFAULT MSGTYBE eere eene teinte B 2 27 DEFAULT PROTOCOLID eere B 2 28 DEFAULT QPRIORITY eene B 2 29 DEFAULT SMSCOP sese B 2 30 DEFAULT SOURCEADDR ren B 2 31 DEFAULT SOURCEADDRNPI B 2 32 DEFAULT SOURCEADDRNPI IN B 2 33 DEFAULT SOURCEADDRTON B 2 34 DEFAULT SOURCEADDRTON IN B239 DEFAULT VP irit teo bo eer teet B 2 36 DELAYFIRSTMESSAGE eee B 2 37 DESTEULEN ANMD 2er tator nat Fonte B 2 385 DER BRR HEX eei eerie eto te eret ee teres B 2 39 DEREXPIRES terre tette dese due B 2 40 DLR EXPIRES STATUS eee B 2 41 DLRIGNOREKEY WORD ete B 2 42 DLRMINMATCHLENGTH eee B 2 43 DOMAIN en pettice etse cbe pe eicere iC ES pd eo ERE ERR eed Ede B244 FAILOVER ertet re ertt tte ree Cete rh rei eaux B 2 45 FIRST IRN nente tee berba ta epe Ee a ed Ee B 2 446 FORCE CHARCODBE 1 2 rrt eerte EENEN B 247 EORCECL ONSE nic nist eee i hee better B248 FORCE DOGS hide teet neret ree ncn idera td ene
14. Handle DLRs with BUFFERD or ACCEPTD status SMPP Optional parameters with a length gt 128 were not handled properly UCP Message body was hex encoded twice when logged HTTP Read to end of file if content length is missing HTTP MGP Handle incoming DLRs HTTP MGP Now it is allowed to set XUSERNAME option if ALLOW ROUTE is specified HTTP EBE New connector keyword USERESPONSE which allows for a message id to be read SMTP Potential null pointer when message body empty which would cause crash on Solaris EBE Improved handling of childs in order to avoid zombie processes MM7 Reordered some fields MMT Fixed memory leak when converting from MIME to MM7 MMT new protocol variant MM7 TMOBILE for interoperability with T Mobile MMC emgstat Display more of connectorname if screen is wider than 80 characters mmscomp Fix potential crash Outgoing messages were counted twice for some protocols Keyword CONNECTORLOGDB can now be used for connectors as well as in general section New connector keyword LOGDB EVENTS for specifying which connector events should be written to connectorlog table in database New connector keyword NODLR to suppress DLRs being generated from HTTP SMTP EBE connectors New connector keyword CHARCODE CONVERT which enables automatic conversion between IA5 and Latin 1 for messages sent over connector ooooo0 9 Oo 9 9 09 6 o 0 Enterprise Messaging Gateway User s Guid
15. The connector log file includes all events for a specifiec connector Specifically all messages sent and received will show up in one of the connector log files A message which passes through EMG will show up at least two times usually in different log files One entry when message was received and one entry when message was sent It is possible for the same message to occur more than twice in log files for example if sending the message first failed and the a retry was made which was successful It is possible to differ between final and non final entries since only the final entries include the ENDSECS 95 and ENDMSECS 96 message options In EMG 2 5 the connector log file format changed slightly to be easy to parse Format is one event per row lt timestamp gt lt instance gt lt event gt lt OK ERR gt lt info gt lt options gt timestamp Mandatory Default format is MMM DD hh mm ss mmm If LOGYEAR is used format is YY Y Y MM DD hh mm ss mmm instance Mandatory Connector instance on which the event occurred event Mandatory Type of event that has occurred Can be of one the following values CONNECT DISCONNECT LOGIN LOGOUT SEND RECEIVE REJECT MAXFAIL EXPIRE OK ERR Mandatory Indicates whether the event was successful or failed info Optional Information related to the event A text string consisting of one or more comma separated fields on a key value format where the value part is optional and
16. To compare with the DEFAULT VP which sets the validity period for the message only if it is missing Introduced in EMG 1 0n as VP changed to FORCE VP in EMG 2 4 See also DEFAULT VP B 2 70 GSMNOSCA Syntax GGMNOSCA SCA Service Center Address should not be included in PDU Needed for some GSM devices B 2 71 GSMSTORE Syntax GSMSTORE lt string gt Specifies what kind of storage should be used for messages Ericsson devices store messages in memory and require GGMSTORE ME B 2 72 HEXID Syntax HEXID lt integer 0 or 1 gt In SMPP 3 3 message ids are returned in submit sm resp operations as a hexa decimal value while in SMPP 3 4 message ids are alphanumeric However some SMSCs do not comply with that or are configurable Using this behavior it is possible to toggle how EMG should treat the message ids Applies to SMPP Introduced in EMG 3 B 2 73 HOME IMSI Syntax HOME_IMSI lt string gt Only used by EMG Roamer B 2 74 HOME VLR Syntax HOME VLR sstring Only used by EMG Roamer Enterprise Messaging Gateway User s Guide 3 0 16 89 B 2 75 IDLETIMEOUT IDLETIMEOUT lt integer gt Idle timeout in seconds When connector has been idle for the specified period of time the connector is disconnected If a value of 0 is specified this feature is disabled and the connector will not timeout Please note however that the con nector will detect if the remote peer is disconnected by for example a network time
17. cesses oeer ie ens nene 112 B 5 2 MAILSPERSESSION eese eee nenne 112 B39 PORT o cette cast ELE 112 B54 RBIRYTIME oem Re bes 112 B 525 SBSSIONS i oeteeccnerh ape deae deese nt necp esee HR ipaa uda 112 I Xo ditur iD E 112 B 6 1 CONFIG eise ii RH ERI t ER CH DURER RN ERR HAE HR 113 B 6 2 INSTANCGES 2 eite ierit Re FERE FE e EH epe Ee ente 113 B 6 3 LIBRARY pede re e RE aaah eae 113 Enterprise Messaging Gateway User s Guide 3 0 16 B 6 4 OEESET iere rete eit rte ERE priate be gk ede retenta 113 C MGP OPON Sieniniai ee ertet tre i rre Ii ree edet pene o ERA Ee iR 114 C 1 Option keys in numeric order eene 115 C 2 Options reference oiii th endete ELE ii aiian 116 C2 T BIEEINGID 9 eiiete eco itt e uendere 116 C22 CHARCODB 28 ito tee enina beare 116 C 2 3 CONCATSMSMAX 75 cesccscccsecssceseseseesseessescessoeescseneasense 116 C 2 4 CONCATSMSREF 73 eese 116 C 2 5 CONCATSMSSEQ 74 esisiini nennen 116 C 2 6 CONNECTOR 59 repe iibri eipig 117 C 2 7 DES CIS esi nineteen eaten 117 2 3 DELTIME 20 4 retient ire ruere Re bee hectare eia 117 C 2 9 DESTADDR 8 inrer tiere trae er treten ter pecd 117 C 2 10 DESTADDRNPI 10 eese teat eenne 117 C 2 11 DESTADDRTON 9 tiet eteo eterne iab ida 117 72 12 DESTPORT 12 tinet Pete reine tent rn ces 118 C213 DER 19 i iiitontonteinenfonaientteniteii ede este 118 C214 D
18. password VALUES userl secret INSERT INTO emguseraccess userid ipaddress ipwidth connector VALUES 1 0 0 0 0 0 This would allow user user1 to connect to any connector from any IP address We assume that the userid assigned by the first insert is 1 EMG will read user information from database for every login so there is no need to refresh or reload the server after adding or modifying account informa tion 12 3 Schema version handling From time to time the EMG database schema is updated This is automatically detected by the server when the server is started and if the database indicates an older schema version than is used by the server the server will refuse to start until the schema has been upgraded A schema upgrade is performed by executing emgd upgradedb Please note that with large tables this can take a considerable amount of time even hours with really large databases The EMG server must NOT be running when the database schema is upgraded or the database will potentially be corrupted The SQL that will be executed in order to perform the upgrade can be displayed with emgd upgradesql EMG reads the current schema version from the emgsystem table which should holds one row with keyname emgschema and value set to the cur rent schema version If the emgsystem table or the row is missing a schema ver sion of 0 is implicated
19. type lt value gt Type of MMS Allowed values get send default from lt text gt Sender fromtype lt text gt Sender type PLMN IPV4 IPV6 EMAIL to lt text gt Recipient totype lt text gt Recipient type PLMN IPV4 IPV6 EMAIL subject lt text gt Message subject headers lt filename gt Specified a file that contains extra message headers to be added protocol lt text gt Output protocol EAIF MM1 MM7 PAP Default MMI transaction lt text gt Transaction o lt filename gt Output file d lt filename gt Decompile the specified MMS file debug Display debug information on stdout debug2 Display even more debug information on stdout Enterprise Messaging Gateway User s Guide 3 0 16 69 A 6 pushtohex Encode a WAP push PDU according to WAP 167 and WAP 168 The output will be hex encoded and can be used with emgsend as shown below Options type lt value gt Type of WAP push Allowed values SI Service Indication SL Service Loading href lt URL gt URL or href to use http will be inserted automatically hrefs lt URL gt URL or href to use https will be inserted automatically id lt si id gt Only used for type SI text lt string gt Push text Only used for type SI created lt Y Y YYMMDD gt Creation date Only used for type SI expires Y YYYMMDD Date for expiration Only used for type SI action value Allowe
20. 2 10 AUTOMATICTONNPL ALPHANUMERIC_TON Syntax AUTOMATICTONNPI_ALPHANUMERIC_TON lt integer gt Introduced in EMG 3 0 B 2 11 AUTOMATICTONNPI DEFAULT NPI Syntax AUTOMATICTONNPI DEFAULT NPlI integer2 Introduced in EMG 3 0 B 2 12 AUTOMATICTONNPI DEFAULT TON Syntax AUTOMATICTONNPI DEFAULT TON integer Introduced in EMG 3 0 B 2 13 AUTOMATICTONNPI SHORTCODE NPI Syntax AUTOMATICTONNPI_SHORTCODE_NPI lt integer gt Introduced in EMG 3 0 B 2 14 AUTOMATICTONNPI SHORTCODE TON Syntax AUTOMATICTONNPI_SHORTCODE_TON lt integer gt Introduced in EMG 3 0 B 2 15 BLACKLIST Syntax BLACKLIST filename Specifies which file contains the connector specific blacklist Format is same as for general keyword BLACKLIST Introduced in EMG 2 0 Enterprise Messaging Gateway User s Guide 3 0 16 81 B 2 16 CDMA Syntax CDMA When specified contatenated message UDH will always be added to binary mes sages even if only one part This is required for correct functionality when using CMDA SMSC B 2 17 CDRFIELDS Syntax CDRFIELDS lt string gt Only used by EMG Roamer B 2 18 CMR Syntax CMR Enables Concatenated Message Routing CMR for connector CMR is used for ensuring that different parts of the same contatenated message is routed via the same connector which is sometimes necessary in order for the receiving phone to be able to reassemble the message correctly B 2 19 DEFAULT_CHARCODE Syntax DEFAULT_CHARCODE lt stri
21. 2 87 LOGPDU Syntax LOGMESSAGE lt integer gt Specifies that the message data or part of the message data should be logged to the connector log file By default only the length of message is logged to the con nector log file not the contents The message data is hex encoded in the log file Syntax LOGPDU At log level DEBUG or DEBUG 2 the protocol data units that are sent and received by the connectors are logged to files with the names pdu lt connector name gt in the log directory Set the LOGPDU option to enable this log at other log levels Introduced in EMG 3 B 2 88 LONGMESSAGE Syntax LONGMESSAGE lt integer 0 255 gt Number of messages a long message gt MESSAGELENGTH default160 sep tets can be split into Default value 4 B 2 89 LONGMODE B 2 90 MAPPING Syntax LONGMODE lt string gt How to handle messages that exceed the maximum message length The maximum length of a message is the value of MESSAGELENGTH x the value of LONGMESSAGE If a message exceeds that length it can either be truncated or rejected Values REJECT TRUNCATE Default value TRUNCATE Syntax MAPPING lt filename gt Enterprise Messaging Gateway User s Guide 3 0 16 92 Specifies a file containing a mapping B 2 91 MASQUERADE Syntax MASQUERADE lt string gt Introduced in EMG 3 B 2 92 MAXFAILEDCONNECTS Syntax MAXFAILEDCONNECTS lt integer gt Number of connection attempts before state ERROR See
22. 3 B 1 19 PERSISTSIZE Syntax PERSISTSIZE lt integer gt Specifies the maximum size in bytes of message body that will be stored in the same persist file as the other message options If the message size exceeds the specified value the message body will be placed in a separate file and will only Enterprise Messaging Gateway User s Guide 3 0 16 75 be loaded when needed This may save considerable amounts of memory when handling many messages with large message bodies Default 1024 Introduced in EMG 3 B 1 20 ROTATELOGS Syntax ROTATELOGS lt integer gt lt integer gt Rotate log files based on size or time When rotation should be performed based on time the specified value should be 6699 66 an integer followed by s m h d or w indicating number of seconds minutes hours days or weeks The log files will be renamed by appending a timestamp to the current file name and a new output file will be created When rotating based on size the format is two fields colon separated where the 6699 first fields indicates the size and the unit The unit can be k m or g for kilobytes megabytes and gigabytes Second field indicates the number of files to save ROTATELOGS 2M 10 indicates that each log file will be rotated out when the file size exceeds 2 MB and that the 10 most recent files would be saved with suffixes 0 9 Introduced in EMG 2 0 Size based rotation introduce
23. 7 2 Using SMTP connector When EMG sends a message using an outgoing SMTP connector this is done via a standard SMTP session using some special mappings for the options associated with the message SOURCEADDR Put into the MAIL FROM address DESTADDR Put into the RCPT TO address MESSAGE Put into the DATA body All other message options are put into the message header as X EMG Option lt option gt user defined headers There are also a few specific connector keywords used by the outgoing SMTP connector Enterprise Messaging Gateway User s Guide 3 0 16 42 Sending messages QUOTEDSUBJECT lt c 1c2 gt This indicates that the message may include a subject and that the subject is enclosed using the characters c1 and c2 respectively Example If the keyword is used as follows QUOTEDSUBJECT and the message body is This is the subject and this is message body the subject of the message will be set to This is the subject and the mes sage body will be and this is the message body Outgoing messages are MIME encoded as text plain using the ISO8859 1 char acter set EMG supports persistent SMTP connections using the RSET command EMG supports SMTP authentication using the XAUTH keywords 7 2 1 Sample outgoing SMTP session Remote SMTP server lines begin with gt gt 220 host domain com ESMTP HELO nordicmessaging se gt 250 Please to meet you MAIL FROM lt 123456 nordicmessag
24. Enterprise Messaging Gateway User s Guide 3 0 16 61 Performance 13 Performance Performance is usually on top of the agenda when discussing product capabili ties We start out by defining high performance in the EMG context as the ability to process more than 100 even up to 5 000 messages per second By processing we mean that a message is received potentially converted and re transmitted EMG is a very efficient platform using several different mechanisms in order to achieve this effectiveness and high performance EMG is multi threaded as opposed to multi processed Threading is a much more efficient way to perform multiple simultaneous tasks than using traditional operating system processes Creation destruction and task switching using threads is at least 100 times more efficient than the same procedures for processes EMG encourages use of persistent connections The amount of overhead introduced by each connect login logout discon nect is huge on a high performance system EMG implements efficient queue algorithms Often a system wide queue or point of synchronization can be a bottleneck and turn out to severely degrade system performance The EMG design and implementation of queue effectively addresses this 13 1 Hardware and operating system 13 1 1 CPU 13 1 2 RAM 13 1 3 Disk First of all we want to make clear that EMG can process 100 messages per sec ond on more or less any hardware that runs the supported
25. Get license key Contact your distributor or Nordic Messaging Technologies in order to get your evaluation license key or to purchase a permanent license When upgrading from earlier versions of EMG EMG 1 2 or 2 5 you need a new license key If there is an active support agreement in place for your license you can get the new license key by sending e mail support infoflexconnect se requesting the new key Include the current license key in the e mail Delivery time for licenses may be up to two workdays 3 4 Install software 3 4 1 Full distribution Extract the components under the root directory This will create a directory tmp emg2 change to the new directory and execute the install script The install script will ask a number of questions regarding your configuration and prompt you for the the license key Enterprise Messaging Gateway User s Guide 3 0 16 18 Installing or upgrading EMG cd gzip d emg30 solaris full tar gz tar xvf emg30 solaris full tar cd tmp emg sh INSTALL de de dE db db During the installation you will be able to choose a directory for the configura tion files By default this directory is etc emg and will be referred to as EMGDIR in this documentation If you choose to install the software using another directory for the configuration files the environment variable EMGDIR needs to be set correspondingly in order for the programs to find the configura tion files Example for sett
26. Hellotworld If successful the message id is returned in the body of the HTTP response If multiple DESTADDR are supplied in the same request multiple message ids will be returned in the same order as the DESTADDR options were supplied EMG supports persistent HTTP 1 1 connections When sending binary messages or UDH the message data must be hex encoded The DESTADDR parameter can occur multiple times in one request and there fore it is possible to perform batch sending with very high throughput more than 5 000 messages per second The ROUTE and ROUTEDLR options all need the ALLOWROUTE keyword to be set on the connector in order to prevent users from setting these options by default There is no limitation in EMG on the size of an incoming HTTP POST request 8 2 Using SMTP connector When receiving a message via an incoming SMTP connector EMG will by default parse incoming message data RFC 822 or MIME messages discard all present non text attachments and convert message data to the GSM character set This is the default behavior if connector is missing DEFAULT MSGTYPE or it is set to NORMAL If DEFAULT MSGTYPE EMAIL is used the e mail mes sage will be parsed but message content will remain intact This should be used when e mail messages should pass transparently through EMG A few message options will be set from SMTP provided information SOURCEADDR Retrieved from MAIL FROM address DESTADDR Retrieved from RCP
27. Invalid data 2 atabase message data store full 3 SME busy 5 Duplicate message 6 Destination unavailable 20 Call barred by user 21 Transmission error 24 Unknown subscriber 25 Call barred by network operator destination 26 Call barred by network operator originator 120 Network failure D 5 HTTP Error code Description 200 Success 400 Bad request 401 Unauthorized 403 Forbidden 404 Not found 500 Internal error 501 Not implemented 301 Moved 304 Not modified Enterprise Messaging Gateway User s Guide 3 0 16 125 D 6 SMTP Error code Description 220 Service ready 250 Requested mail action ok 251 User not local will forward to 421 Service not available 450 Mailbox unavailable 451 Requested action aborted 452 Requested action not taken 500 Syntax error command unrecognized 501 Syntax error in parameter or arguments 502 Command not implemented 503 Bad sequence of commands 504 Command parameter not implemented 550 Requested action not taken Enterprise Messaging Gateway User s Guide 3 0 16 126 E SMSC inter connectivity checklist When interacting with an operator in order to set up a connection to an SMSC the following checklist may be useful E 1 Your requirements E 1 1 Send messages The most common and basic functionality Message price Price differences whether the reci
28. Message id This is the unique message id assigned by EMG C 2 19 LRADDR 108 Last Resort Address Introduced in EMG1 0h C 2 20 LRPID 109 Last Resort Protocol Identifier Introduced in EMG1 0h C 2 21 MESSAGE 16 Message data Enterprise Messaging Gateway User s Guide 3 0 16 118 C 2 22 MESSAGELEN 17 Length of message in characters or bytes C 2 23 MSGCLASS 27 Message class as defined by GSM 3 40 Values 0 Flash SMS message displayed immediately 1 Store message memory or SIM default 2 Store message to SIM 3 TE Terminal Equipment specific C 2 24 MSGTYPE 15 Message type Specifies the type of message Values SMS DLR Email MMS aD Ne Default value 1 C 2 25 NOTE 97 Note A user specified text attached to the message Can for example be used to hold extra information on the message C 2 26 OTOA 112 Syntax OTOA lt string gt Applies to UCP Introduced in EMG 1 0h C 2 27 OUTCONNECTOR 60 Name of connector on which message was sent out C 2 28 PRIORITY 32 Priority of message There are differences in how priority options are implemented in the different SMSCs However in GSM 3 40 there are only priority or non priority messages Enterprise Messaging Gateway User s Guide 3 0 16 119 Values 0 No priority default 1 Priority Protocol specific mappings CIMD2 MGP 1 4 1 5 9 none 0 MGP CIMD2 O none No value 1 1 SMPP MGP
29. Same as FORCE DESTADDRNPI but applies to received messages B 2 53 FORCE DESTADDRTON Syntax FORCE DESTADDRTON integer If present the specified message destination address type of number TON will be set to this value even if already present in the message Introduced in EMG 2 4b B 2 54 FORCE DESTADDRTON IN Syntax FORCE DESTADDRTON IN sstring Same as FORCE DESTADDRTON but applies to received messages B 2 55 FORCE DESTPORT IN Syntax FORCE DESTPORT IN integer2 Set destination port UDH of received messages to the specified value Introduced in EMG 3 0 16 B 2 56 FORCE DLR Syntax FORCE DLR integer Specifies that DLRs should always be requested regardless what is set in the message received B 2 57 FORCE MESSAGE Syntax FORCE MESSAGE sstring Replaces message body with the specified message body B 2 58 FORCE PRIORITY Syntax FORCE PRIORITY integer Replaces message priority with the specified priority B 2 59 FORCE PROTOCOLID Syntax FORCE PROTOCOLID integer Replaces message protocol id GSM 3 40 TP PID with the specified protocol id B 2 60 FORCE SERVICETYPE Syntax FORCE SERVICETYPE integer Enterprise Messaging Gateway User s Guide 3 0 16 87 Replaces message service type with the specified service type on messages sent over the connector B 2 61 FORCE_SERVICETYPE_IN Syntax FORCE_SERVICETYPE_IN lt integer gt Same as FORCE_SERVICETYPE but applies to messages received over th
30. UCP New MQP option XSER EXTRA for handling custom XSER fields DLR Possible memory corruption under high load eliminated DLR Logic rewrite for performance improvement New MySQL driver for Solaris 10 x86 Check for expired DLRs only once per minute Ensure connection is closed if we cannot write F 4 EMG 3 0 13 10913 Minor release o0 O0 o 0 9 New connector keyword OPS_MAXEXPIRED which controls how many outstanding operations are allowed to expire before connection is closed Default is 0 PAP Missing Content type could cause server to crash SMPP Make delivery report parsing a bit more flexible MGP Fail message if UDH is not correctly encoded Enable forwarding of DLRs for temporary status by setting bit 2 for DLR option DLR 2 for temp only or DLR 3 for temp and permanent status Routing files was not checked properly by emgd verify Fix in retry scheme handling which would cause action for one message to be applied to multiple messages Holding a connector which did not exist would cause server to crash Minor memory leak when using PLUGINARG option DB Schema change 19 in routelog npdus now defaults to 1 DB Schema change 20 in routelog new field origid which is set to the id of the original message for DLRs DB Schema change 21 new table monthlysummary for aggregated F 5 EMG 3 0 12 10307 Minor release PAP Fix for respecting SI SL SMSCI Do not u
31. action Messages which contain the wrong keyword is bounced to the user with an error message 6 7 2 Setting up the connectors Outgoing connector where we connect to a Nokia SMSC using CIMD2 and receive messages CONNECTOR nokia cimd2 TYPE OUTGOING PROTOCOL CIMD2 Enterprise Messaging Gateway User s Guide 3 0 16 39 Routing ADDRESS 10 0 0 1 9971 INSTANCES 1 USERNAME user PASSWORD secret STATIC KEEPALIVE 60 IDLETIMEOUT 0 Message format is keyword rest of message gt PARSEMESSAGE KEYWORD MESSAGE gt Outgoing connector that forwards messages to a cgi script that integrates with the application CONNECTOR myapp http lt TYPE OUTGOING PROTOCOL HTTP ADDRESS 10 0 0 1 8080 SUBADDRESS http localhost 8080 cgi bin myapp cgi INSTANCES 1 gt The bouncer connector which sends a message back to the user indicating that an invalid keyword was used CONNECTOR bouncer ebe lt TYPE OUTGOING PROTOCOL EBE ADDRESS usr local bin bouncer sh INSTANCES 1 gt 6 7 3 Setting up the routing table The routing table is processed top to bottom which means that we should include the keyword related entry before any more general entries Route message from everyone incl BALANCE to HTTP connector nokia cimd2 myapp http KEYWORD BALANCE Route other messages
32. can be accomplished in different ways Either all mes sages can be routed to an EBE connector where a shell script or program can parse the message and take action accordingly or EMG can directly parse the message and route it to different connectors depending on the destination address and a keyword in the message The second method is more scalable due to the overhead for EBE connectors when creating new processes In order to use keyword based routing in EMG the following is required Routing is done via the routing table there must be no ROUTE keyword on the connector or in the message since they will take precedence The keyword must contain letters and digits only The option PARSEMESSAGE must be used in the connector configuration where the message is received in order for EMG to be able to extract the key word correctly Please note that after the message has been parsed for the keyword the keyword will still be a part of the message body and is not removed from the message Keywords are case insensitive 6 7 1 Sample scenario In a sample scenario we want to set up a service where customers can request their current account balance by sending an SMS to a specific recipient number and including a keyword BALANCE Incoming messages which are received from a Nokia SMSC via CIMD2 should be routed to a HTTP connector that forwards messages including the keyword to a HTTP server which processes the message and takes proper
33. code etc needs to be determined o o o 9 E 3 3 Receiving a message If relevant messages should be sent from a phone to the application Enterprise Messaging Gateway User s Guide 3 0 16 129 F Change history Changes between EMG releases There are three different types of releases Major release A full distribution including new functionality Migrating from one major version to another will require a new license key Minor release A full distribution primarily including changes and bug fixes Usually does not require a new license key Patch release A binaries only release including changes and bug fixes Applied to an existing installation from a full distribution Does not require a new license key Changes marked with an asterisk includes a fix for a problem which poten tially could cause the server to stop unexpectedly F 1 EMG 3 0 16 14262 Minor release 9 EMG is now available in version without SSL encryption support Database schema change for emguser table build 13555 Import performance for handling of incoming delivery reports New connector keyword FAILOVER for re routing of message when an error is returned in response to submit operation New connector keywords FORCE SOURCEPORT IN and FORCE DESTPORT IN Fix for potential crash when orphaned messages expired PDU log format change for unknown fields previously logged as UNKNOWN lt value gt now logged as lt key
34. eed 128 E 3 1 Account information sese 128 E 3 2 Sending the first message seen 129 E 3 3 Receiving a message sese 129 E Change histOEy iiir iieri ER eere EE a E atre Feo odere 130 E I EMG 3 0 16 14202 in tie Gb etri bet ebrio eb Pere pa a 130 F2 EMG 3 0 15 120950 ict catt e sachs rte Haee exten 130 FES EMG 3 0 14 11720 iianioshiositonntenirieatioeiei eiit roiete ese 131 FA BMG 3 0 13 10913 iiiter ert ee dr teque eod ee oie 131 FS EMG 3 0 12 10307 i dni itt Perret eben eire ss 131 BG BMG 3 0 11 9982 iie serere terree toan o tede ERER E 132 E 7BMGr3 0 10 9505 iiti erede reiecit ip da 132 E S EMG 3 0 0 0284 rites d tere Een ed E ae Dp Pd eode 133 E 9 BMGr 3 0 8 0115 ie ier ente the eR tete PER al vetoes 133 F I0 EMG 3 0 7 8470 i iiiicceiectee teret aed te eb oet eo EY iei 134 F I TEMG 3 0 6 8403 ca enisi pe Gee ernst be P Hate FREE de 134 F 12 EMG 3 035577 19 editiert tt eren hte Dp eaae ide 135 E 13 EMG 3 04 6983 1 nitent rtt ederet E ERR e F eU de 136 E 14 EMG 3 0 3 660 Lica ii aired rette rrr ob eias 137 FIS EMG 3O ctissccestebutivs toddesoluedstelsseassasazcsstuanersncuyees EE N ES 137 Index itin qu a Ea EE E E E OS 138 Enterprise Messaging Gateway User s Guide 3 0 16 Acknowledgements 1 Acknowledgements 1 1 OpenSSL 1 2 LibXML 1 3 PCRE 1 4 PCRS Acknowledgements in accordance with the OpenSSL license This product includes cryptograp
35. gt lt value gt HTTP Two potential buffer overflows eliminated OIS Multiple fixes for sending and receiving message incl UDH support UCP Protocol id is now treated as string and not as numeric value SMPP DLR ERR HEX can now be used for outgoing DLRs SMPP Handle delivery receipts from Huawei SMSC correctly WAP PUSH SI SL in UTF 8 is now handled correctly Validation of values for INTERFACEVERSION added when SMPP is used Signature change 2 new arguments for DB functions db_sendrequest and db readresponse Plugins using these functions must be re compiled to use the new signatures Plus som additional potential minor memory leaks and null pointers fixed F 2 EMG 3 0 15 12050 Minor release o o o ooo0o00 009 O0 Enterprise Messaging Gateway User s Guide 3 0 16 130 Added support for regular expressions in routlist files SMPP New connector keyword DLR ERR HEX which indicates err field in incoming delivery receipts should be treated as hex SMPP Handle delivery receipts from Comverse SMSC correctly UCP Empty messages bodies was not handled Problem with refresh reload with connectors using SSL fixed F 3 EMG 3 0 14 11726 Minor release oooooo0o00 o0 O New general keyword DISABLE CREDITS which disables credit handling SMPP Possible data corruption when parsing invalid pdus fixed SMPP Preserve DCS value when GSM MWI is used PAP Improvements for PAP proxy possibilities
36. is received Both character string and hex codes can be used First line translates all a s into b s Enterprise Messaging Gateway User s Guide 3 0 16 27 Connectors IN lt a wp xyz zyx 03 a a 03 02 gt Then a mapping which will be applied to outgoing messages First line will have no effect as long as ascii char 0x41 is A OUT lt a 41 b aAb 01 02 03 20 20 gt Mappings are processed top to bottom and the following two examples will gen erate different result if applied to the string aabacc Example 1 will generate ddbdcc IN lt a g aa xx gt Example 2 will generate xxbdcc IN lt aa xx a g gt Incoming IN mappings are applied when an incoming message is parsed before it is logged and routed Therefore the EMG server only sees the translated mes sage data Outgoing OUT mappings are applied to the message just before they are sent and leave EMG Therefore the translated message data is never seen in the EMG server 6666 Characters can be removed by using an empty replacement By default mappings are applied to all messages However usually you would not want mappings to be applied to binary or unicode UCS2 messages These mappings can be suppressed by using the connector keywords NOBINARY MAPPING and NOUCSMAPPING 5 8 Address rewriting Both source and destination addresses can be
37. rewritten by EMG after a message has been received or before a message is sent This is particularly useful to make sure that addresses comply with the format requirements of the receiving entity There are four keywords used for destination address rewriting applied in the order they appear below REMOVEPREFIX REQUIREPREFIX REPLACEPREFIX REGEXP_DESTADDR introduced in EMG 3 o o o Enterprise Messaging Gateway User s Guide 3 0 16 28 Connectors There are also four corresponding keywords for source address rewriting REMOVEPREFIX_SOURCEADDR REQUIREPREFIX_SOURCEADDR REPLACEPREFIX_SOURCEADDR REGEXP_SOURCEADDR introduced in EMG 3 These keywords handle outgoing messages via a specific connector while the corresponding keywords ending with _IN handle incoming messages as in REPLACE PREFIX IN and REGEXP_SOURCEADDR_IN 0 REPLACEPREFIX was introduced in EMG 2 5 and can do all that the REMOVE REQUIRE keywords can do and more It takes as argument one or more comma separated pattern replacement pairs where each matched prefix pattern is replaced by the corresponding replacement An empty pattern can be used to add a prefix and an empty replacement to remove a prefix All pairs are applied sequentially in the order they appear An example REPLACEPREFIX 00 0 46 This example could be used in Sweden where we want to handle addresses received in the following formats 46123456 International
38. testing EMG or running benchmarks it can be useful to route message from an outgoing EMG connector to an incoming connector in the same server We call this short circuiting connectors 5 1 Connector types A connector can be one of two types Incoming or outgoing An incoming con nector accepts incoming connections and an outgoing connector initiates connec tions Please note however that whether a connector is incoming or outgoing does not tell anything about the direction of flow of the messages on the connec tor Messages can be received on an outgoing connection for example when connecting to a Nokia SMSC Both incoming and outgoing connectors can exist in 0 or more instances How ever normally an outgoing connector only needs one instance while an incoming connector needs several instances in order to be able to serve several simulta neous connections 5 2 Connector modes Connectors can be defined to be transmit only receive only or both transmit and receive This is not the same as incoming vs outgoing For example when con necting to a Nokia SMSC an outgoing connector can poll for messages which will then be received The connector mode is specified using the MODE keyword By default connec tors can both transmit and receive messages Incoming messages on a transmit only connector will be rejected In SMPP 3 3 however sessions will be used either for transmit or receive depending on the bind operation used This means t
39. to bouncer nokia cimd2 bouncer ebe The keyword KEYWORD takes two arguments destination address which can include wildcards followed by the actual keyword The keyword can also be a which represents any keyword 6 7 4 Keyword sessions It is possible to use what is called keyword sessions meaning that a specific key word starts a session and subsequent messages from the same subscriber need not start with the keyword while the session is active This is particularily useful for chat services and similar Sample configuration nokia cimd2 myapp http KEYWORD CHAT KEYWORDSESSION 3600 Enterprise Messaging Gateway User s Guide 3 0 16 40 Routing The argument to the KEYWORDSESSION keyword is the session lifetime in seconds So the session lifetime in the above example would be 1 hour 3600 seconds 6 8 Concatenated Message Routing CMR Since SMS are restricted to 160 characters 7 bit text longer messages can con sists of multiple messages which are assembled in the phone to one message a concatenated message larger than the 160 character limit For example this can apply to ringtones images and WAP push messages Sometimes it is necessary to make sure that the different parts of a concatenated message is routed via the same connector We refer to this as CMR Concate nated Message Routing CMR is enabled per connector using the CMR connector keyword in the server configuration file Te
40. transmit messages will reject the operation If a message is put in the connector queue for a connector that is only allowed to receive message the message will simply remain in the queue For SMPP 3 3 connectors this keyword determines whether a bind transmitter or bind receiver will be issued during login For TX and TRX bind transmitter will be used for RX bind receiver Values RX TX TRX Default value TRX Introduced in EMG 1 01 B 2 102 MODEM Syntax MODEM lt string gt Modem device Used for outgoing dial up connectors Specifies the tty without the leading dev to use for dialing when making a connection Enterprise Messaging Gateway User s Guide 3 0 16 94 B 2 103 MSGDELAY Syntax MSGDELAY lt integer gt Delay between messages in seconds Used to specify that a delay should be applied after a message has been sent This can be useful or even required for low performance links modem connec tions etc B 2 104 MSGRETRYTIME Syntax MSGRETRYTIME lt integer gt Introduced in EMG 3 B 2 105 MTBILLING Syntax MTBILLING lt string gt Introduced in EMG 3 B 2 106 NOBINARYMAPPING Syntax NOBINARYMAPPING Suppresses messages being applied to binary messages Introduced in EMG 2 5 B 2 107 NOUCS2MAPPING Syntax NOUCS2MAPPING Suppresses messages being applied to UCS2 Unicode 16 bit messages Introduced in EMG 2 5 B 2 108 NOUSERMESSAGEREFERENCE Syntax NOUSERMESSAGEREFERENCE Introduce
41. 3 0 16 99 B 2 138 REPLACEPREFIX SOURCEADDR IN Syntax REPLACEPREFIX_SOURCEADDR_IN lt string gt Introduced in EMG 3 B 2 139 REQUIREPREFIX Syntax REQUIREPREFIX lt string gt Required prefix for destination address DESTADDR If specified this prefix will be added to destination addresses that do not have the prefix For example if REQUIREPREFIX 00 and the destination address is 4612345678 the destination address will be padded with 00 the final destina tion address being 004612345678 B 2 140 REQUIREPREFIX SOURCEADDR Syntax REQUIREPREFIX_SOURCEADDR lt string gt Same as REQUIREPREFIX but applies to source addresses Introduced in EMG 2 5 B 2 141 RETRYSCHEME Syntax RETRYSCHEME lt string gt Introduced in EMG 3 B 2 142 RETRYTIME Syntax RETRYTIME integer Specifies the time in seconds to wait before trying a reconnect after a connect failure Default 30 Applies to All protocols outgoing See also MAXFAILEDCONNECTS MAXFAILEDSLEEP B 2 143 REVDLR Syntax REVDLR Reverse order of source address and destination address for DLRs sent out over the connector Introduced in EMG 3 B 2 144 REVDLR IN Syntax REVDLR IN Enterprise Messaging Gateway User s Guide 3 0 16 100 Reverse order of source address and destination address for DLRs received over the connector This may sometime be necessary for DLR matching to work when remote entity sends addresses in reversed order Introdu
42. 4 THREADED Syntax THREADED TBD B 5 Domain options Options used for domain specific behavior Can be used to minimize risk of being classified as a spammer when delivering large amount of e mails to recipi ents in specific domains Only applies to SMTP MX connectors Example Enterprise Messaging Gateway User s Guide 3 0 16 111 DOMAIN yahoo com lt MATLSPERMINUTE 10 SESSION 1 gt B 5 1 MAILSPERMINUTE Syntax MAILSPERMINUTE lt integer gt Maximum number of e mail to send per minute for domain Default O unlimited B 5 2 MAILSPERSESSION Syntax MAILSPERSESSION lt integer gt Maximum number of e mails to send per SMTP session Default 0 unlimited B 5 3 PORT Syntax PORT lt integer gt Port to use when connecting to SMTP server for domain Default 25 B 5 4 RETRYTIME Syntax RETRYTIME lt integer gt Time in seconds to wait if the DNS lookup does not find any valid MX hosts or if it is not possible to connect to the hosts found Default 300 seconds B 5 5 SESSIONS Syntax SESSIONS lt integer gt Maximum number of simultaneous SMTP sessions for domain Default 1 B 6 Plugin options Options used when defining plugins Example PLUGIN billing LIBRARY etc emg plugins billing so INSTANCES 2 CONFIG etc emg plugins billing cfg gt Enterprise Messaging Gateway User s Guide 3 0 16 112 B 6 1 CONFIG Syntax CONFIG lt string gt The value
43. ARSEMESSAGE DESTADDR MESSAGE When a message is received it will be expected to contain the destination address followed by a space and then the message body In this case the destination address in the message will override any destination address supplied in other ways The special keyword KEYWORD can be used for keyword based routing and will be used together with keywords optionally specified in the routing table Applies to All protocols incoming B 2 116 PASSWORD Syntax PASSWORD lt string gt Used for outgoing connector authentication via the connector protocol Enterprise Messaging Gateway User s Guide 3 0 16 96 Applies to All protocols outgoing B 2 117 PLUGIN Syntax PLUGIN lt string gt Introduced in EMG 3 B 2 118 POLLRECEIVE Syntax POLLRECEIVE lt integer gt Time in seconds between message polls Indicates that the connector should connect periodically to allow for messages to be received over the incoming connector This is used when EMG needs to con nect to the SMSC in order to receive messages and the connection cannot be static Applies to CIMD2 and SMPP outgoing B 2 119 PREFIX Syntax PREFIX lt string gt Introduced in EMG 3 B 2 120 PRESERVESAR Syntax PRESERVESAR Introduced in EMG 3 B 2 121 PROMPT Syntax PROMPT lt string gt Specifies a string to be sent to the client side after connect before the protocol server starts A newline will
44. Agent Default value is EMG Introduced in EMG 2 5 Syntax SHMKEY lt integer gt Each EMG server uses a shared memory segment In order to be able to run mul tiple servers on the same machine each EMG server needs a unique shared mem ory key You can run the command pcs m to see what share memory keys are in use Values are presented in hex Default value is 2555674929 decimal Introduced in EMG 2 3 B 1 27 SPOOLDIR Syntax SPOOLDIR lt directory gt Directory to use for spool files This include queue entries SAT entries and mes sage id file Default SEMGDIR spool Introduced in EMG 3 B 1 28 SSL KEYFILE Syntax SSL KEYFILE filename Specifies the server wide PEM file where key and certificate is stored for use by SSL connectors Introduced in EMG 2 0 See also Connector option SSL_KEYFILE B 1 29 SSL PASSWORD Syntax SSL_PASSWORD lt string gt Specifies the password if any used for the key file Introduced in EMG 2 0 See also SSL_KEYFILE Enterprise Messaging Gateway User s Guide 3 0 16 78 B 1 30 TABLE_PREFIX Syntax TABLE_PREFIX lt string gt Use specified prefix when referencing DB tables If prefix is defined as emg30_ then the connector log table will be referenced as emg30_connectorlog Please note that the schema SQL file needs to be edited and in order for the schema to be created accordingly Introduced in EMG 3 0 B 1 31 TIME OFFSET Syntax TIME OF
45. B 2 158 SIMULATE niei eoe xe ebbe eben 103 B2159 SMPPTZ iia teet eget eet tete tee epe de Pacto de Ond 103 B 2 160 SOURCEADDR_GSM eee 103 B 2 161 SOURCEFULLNAME eren 103 B 2 162 S SL ibas ede iim ete tpe nes des 103 B 2 163 SSE KEYP E ioter ER et p erre 103 B 2 164 SSL PASSWORD esee 103 B 2 165 STATIC ice cc hee Eee eer ee P eed de 104 B 2 166 SUBADDRESS cesses eene tn eene nnn nennen 104 B 2 167 SUBJEGCT i Hebe ete atthe tb ket cb cepa de 104 Enterprise Messaging Gateway User s Guide 3 0 16 B 2 168 SUPPRESS_EMGHEADERS ne 104 B 2 169 SYSTEMTYDBE 5 nee metere elon ci ei Eee 104 B 2 170 TCPSOURCBIPD eerte ten rte t eite hit denen 104 B 2 17 TCPSOURCGBPORT 4 rn nente ette 105 B 2 172 THROUGHPUT htt isese irsin reiissi dean 105 B2 173 TYPE ee etra Rees 105 B 2 174 UDHVIAOPTIONAL essere 105 B 2 175 SEDELTIME rrt erre tienen nt iniit 105 B 2 176 SBPRIORLITY retener tne eere e En 106 B20 77 USERDB ehee eiee adeb edes ds 106 B 2 178 USBRDB FORCE aei eene entertains 106 B 2 179 USERNAME di eitiieeeeninen eterno end ina a nean ee Les oen 106 B 2 180 USERS etico et eer e e ni DR Ru epe eee Ue REA 106 B 2 181 SESENDBR eren teer E EA etel 107 B 2 182 USEBSUBJEGCT eceieiiiee tit ete ee peces tdt cede 107 B 2 183 VASID eere er ettet
46. C493424D112610922C495624C312558922849A224B210718926C4966249N B107109304495420D31249892AC491620D21258892AC496624AB124D8924849N 6424AB1259892AC493620D2124D0924C493624AB124D8926400001 Enterprise Messaging Gateway User s Guide 3 0 16 71 B Configuration options All configuration options that specifies a filename can use absolute paths or rela tive paths which in that case will be relative to EMGDIR default etc emg B 1 General options B 1 1 BLACKLIST Syntax BLACKLIST lt filename gt Specifies which file contains the system wide blacklist The format of the file is one entry per row where each entry consists of two or optionally three tab sepa rated fields The first field is the sender or source address the second field the action and the third optional field is either SOURCEADDR or DESTADDR to specify the type of address to be blacklisted If the type of address is omitted it defaults to SOURCEADDR Possible values for action are REJECT or LOG Lines beginning with are not processed Example 070123456 lt TAB gt REJECT lt TAB gt DESTADDR 070654321 lt TAB gt LOG B 1 2 CMREXPIRE Syntax CMREXPIRE lt integer gt Specifies the number of seconds routing information for concatenated messages should be kept This value should be enough for all parts of a concatenated mes sage to pass through EMG However in order to minimize overhead it should be kept as low as possible
47. Default value 60 Introduced in EMG 2 4 B 1 3 CONNECTORLOGDB Syntax CONNECTORLOGDB Log connectorlog to DB Requires DBPROFILE to be set B 1 4 CONNECTOR_LOGLEVEL Syntax CONNECTOR_LOGLEVEL lt string gt Default log level for connector related messages See also LOGLEVEL LOGPDU Default Same as LOGLEVEL Enterprise Messaging Gateway User s Guide 3 0 16 72 B 1 5 DBPROFILE Syntax DBPROFILE lt string gt Default database profile to use A database profile is defined by a DB lt gt sec tion in the server cfg file B 1 6 DISABLE_CREDITS B 1 7 DLRSSIZE B 1 8 DLRVP Syntax DISABLE_CREDITS Disable credits handling usually enabled when using a database Syntax DLRSSIZE lt value gt Maximum number of DLR entries stored in the system When this limit is reached DLR entries the oldest entries will be discarded and a DLR with DLR_EXPIRES_STATUS will be sent default unknown Default 100 000 Introduced in EMG 3 Syntax DLRVP lt value gt Specifies after how many seconds a DLR will expire if not successfully sent Default 3600 1 hour Introduced in EMG 2 4a B 1 9 DNSTHREADS Syntax DNSTHREADS lt integer gt Maximum number of DNS threads to use for DNS lookups Default value 1 Introduced in EMG 3 B 1 10 LOGFLUSHSIZE Syntax LOGFLUSHSIZE lt integer gt Specifies how many log entries should be present in log queue before they are flushed to file Default value 100 Int
48. ERID 81 itr tite ete t ere Gigs eee 118 C 2 15 ENDMSEGS 96 icit ette i betreibt ditenee 118 C216 ENDSECS 95 tenete esin i nete nite e E ENRERE 118 C 2 17 HPLMNADDR 110 seen 118 C218 DD 10 eiit eire e atus divest reete teens 118 C 2 19 LRADDR 108 inttr trei ette t eta 118 C 2 20 LRPID 109 niii etie tie E eia epe Ce etie de 118 2 21 MESSAGE 10 cicer i nete aaiae 118 C 2 22 MESSAGBLBN 17 iecit biete tbid 119 7 2 23 MSGCLASS 21 ocina 119 C 2 24 MSGTY PE 15 inniti edere eb eb eaa da 119 2 25 NOTE 07 niet tec e Sardo hte ENTENEN 119 2 26 OTOA 112 54i bo ioci hir ndr tech eio eda nes 119 C 2 27 OUTCONNECTOR 60 c eese 119 C228 PRIORITY 32 iiec eee bebes 119 C229 PROTOCOLID 43 lorte etos 120 2 30 OPRIORITY 118 cett ittes 120 C 2 31 REMOTBIP 34 iei stie ern tete eo Ebene Dh ica 120 C 2 32 REPLACEPID 107 tert rre tiet 121 C 2 33 REPLYPATH 31 inves ene eie cirea de 121 C234 ROUTE 38 ie eiteic etie aetati ret dete Ee Re bte ke riae ted 121 GS ROO EAD E i iii iE 121 C2736 SMSCID 64 eei et recs e Fb tre detenta 121 C 2 37 SOURCEADDR 2 nece tt tede bene 121 C 2 38 SOURCEADDRNPI 4 eese 121 C 2 39 SOURCEADDRTON 3 121 6 2 40 SOURGBPONRT 6 crecer eorr tede dene 121 C241 STARTMSEGS 949 rccte ehe beet da see titelee 121 C242 S TARTSECS 93 pecetetiesttee pt eere tne ert denne 122 2243 STA
49. FSET integer Specifies an offset in minutes to be added to the current time Negative values are allowed Useful for example when the server time is in UTC and log files etc should reflect the local time instead Introduced in EMG 3 0 B 1 32 WHITELIST Syntax WHITELIST lt filename gt Specifies which file contains the system wide whitelist The format of the file is one entry per row where each entry consists of two or optionally three tab sepa rated fields The first field is the sender or source address the second field the action and the third optional field is either SOURCEADDR or DESTADDR to specify the type of address to be whitelisted If the type of address is omitted it defaults to SOURCEADDR Possible values for action are OK or LOG Lines beginning with are not processed Example 070123456 lt TAB gt OK lt TAB gt DESTADDR 070654321 lt TAB gt LOG Introduced in EMG 2 0 B 2 Connector options B 2 1 ACCESS Syntax ACCESS lt string gt Access control Only valid for incoming connectors Specifies which host s or subnet s are allowed to make connections to the connector Example Enterprise Messaging Gateway User s Guide 3 0 16 79 B 2 2 ADDRESS Only permit connections from the host 192 168 0 1 ACCESS 192 168 0 1 32 Only permit connections from the subnets 10 2 and 10 3 1 ACCESS 10 2 0 0 16 10 3 1 0 24 Syntax ADDRESS lt string gt For protocol EBE the valu
50. IP No authentication is used for these connections but full support for text binary and messages using UDH is available EMG supports OIS according to the version 5 8 specification 2 12 Performance EMG is licensed based on messages per second Above 200 messages per second the license is unlimited The achieved performance depend on a number of fac Enterprise Messaging Gateway User s Guide 3 0 16 16 Overview 2 13 Support tors Hardware operating system protocol used clients SMSC etc However connectors using the messaging protocols supported CIMD2 SMPP and UCP are capable to process more than 4 000 messages per second in an ideal environ ment In benchmarks where we short circuit SMPP connectors that is we use one server which provides both the outgoing and incoming connectors and a mes sage is looped we achieve 200 messages per second on a low end Sun Sparcs tation 5 with 256 MB RAM running Solaris 8 This indicates that EMG is capable of very high throughput on relatively basic hardware Moreover EMG on Linux generally outperforms EMG on Solaris probably due to the fact that the TCP IP implementation on Linux is very efficient On the other hand we prefer Solaris as a stable and reliable platform for business critical applications Support is available from your reseller and requires a valid support agreement If you are missing information about your reseller please contact Nordic Messag ing Technologie
51. ME 45e ciini rerit eed there i o tea Poe 78 B 1 26 SHMKEY nean hera ete mt ke ERR Eae eur 78 B 1 27 SPOOLDIR ectetur eei te e S Pe ERE 78 B 1 28 SSL KEY FIDE diti rettet ed rhe e erbe Ee ARE 78 B 1 29 SSL PASSWORD ettet inttr tete ep retento tend 78 B 1 30 TABLE PREFIX eid osten aaas 79 B L31 TIME XOBBSBT enn Ho ned rr nte reete 79 B 1 32 WHITELIS aii bee nr e nt hiec 79 B2 Confector OpUOHS eiie ete terrore eere save ore aa eoa e Sea doo dn 79 B2 ACCESS a duse thi meet iteee tore ti thes etie abest one in 79 B 2 2 ADDRESS 5 here pin ee pete L dno ERES ede 80 B 2 3 ADDRESSRANGE essere rennen nennen 80 B 2 44 ALLOWROUTE inet na eere ebrii eL aed 80 B 2 AUTHCODB carrieron eret ei eai i eeke 80 B 2 6 AUTENDIL uie eta i eite eco eee ec 80 B 2 7 AU TELTON etico ttn teoria rere einen ii 80 B 2 8 AUTOMATICTONNPI esee enne 81 B 2 9 AUTOMATICTONNPI ALPHANUMEBERIC NPI 81 B 2 10 AUTOMATICTONNPI ALPHANUMERIC 7TON 81 B 2 11 AUTOMATICTONNPI DEFAULT wNPI 81 B 2 12 AUTOMATICTONNPI DEFAULT TON 81 B 2 13 AUTOMATICTONNPI SHORTCODE wNPI 81 B 2 14 AUTOMATICTONNPI SHORTCODE TON 81 B 2 15 BEACKLIST pice toten ere eth plene deese 81 B 2 16 CDMA cess cte treo eetbeei torret eee e A Feed or diea rese oed 82 B 2 17 CDREFEIBLDS thier ieee E Le PRE Fach Ces EU Boe a EE 82
52. Nordic Messaging Technologies Enterprise Messaging Gateway User s Guide 3 0 16 Nordic Messaging Technologies Sweden http www nordicmessaging se info nordicmessaging se Contents Acknowledgements ae t e eibi cans die eerta 12 1 1 OpenSSL enia nni ene be EP HE ERE DEM ESSE e Eea 12 I2 VAD AMIDE 3 eterne eerte eren ed dex iret ede due tedn in 12 13 PORE P AAEE EARE 12 1 4 PCRS l M M 12 PAS uuu es sstvcs cassie cascede ss tiee EENE ERTEKET KEAT RERET oR 13 2A ETTISUI TL 13 2 2 MESSABES Tm 13 2 3 Binary messages and User Data Header UDH 14 2A Long messag6s eerte tege reprae ope eu E cabs deduc Pete a edo 14 PAN NE 14 26 COMME OI E 14 2 T Routlfg onsec ee i i EE HR FOR Pee ERE ES 14 2 0 Message life Cycle iut dee tie od reri ie pee Erde redo 14 2 9 Routing log iiia eai aei e GM EH pruinis 15 2 10 Orphans eges derniere ede iet bati ia eese oce 15 2 11 Protocol conversion eeseeseeeeeeeeerenenenneen nennen nennen 15 2 11 1 CIMD2 NOKi cei rtt trennt eina ete dias 16 2 11 2 SMPP SMS Forum esros 16 2 11 3 UCP EMI CMQ 5 1 ettet re eee ee pace teet Eee ar edece 16 2 114 OIS Sema oe cesses i nite Pneterea suse FIR reae n 16 2 12 Performance 5 necnon nieafidei d s iin escis 16 213 SUpPPOUt ive iioc ten
53. SWORD Syntax SSL PASSWORD Enterprise Messaging Gateway User s Guide 3 0 16 103 B 2 165 STATIC Syntax STATIC Only valid for outgoing connectors Specifies that the connector should connect on startup and stay connected This will usually require that keepalive packets is sent periodically to avoid connection timeout Also the IDLETIMEOUT should be set to 0 to avoid periodic disconnect reconnects See also IDLETIMEOUT KEEPALIVE B 2 166 SUBADDRESS Syntax SUBADDRESS lt string gt Defines the URL to use for the GET or POST operation This keyword is no longer needed since the ADDRESS parameter understands and parses full URLs for addresses Example ADDRESS localhost 8080 SUBADDRESS http localhost cgi bin report sh Applies to HTTP outgoing B 2 167 SUBJECT Syntax SUBJECT lt string gt Sets the default subject Applies to SMTP outgoing B 2 168 SUPPRESS EMGHEADERS Syntax SUPPRESS EMGHEADERS EMG will add Received headers to incoming SMTP messages unless this key word is specified Applies to SMTP incoming Introduced in EMG 3 B 2 169 SYSTEMTYPE Syntax SYSTEMTYPE lt string gt Identifies the SMPP system type field for a connector May be involved in the authentication process for the connector Applies to SMPP B 2 170 TCPSOURCEIP Syntax TCPSOURCEPORT IP address gt Enterprise Messaging Gateway User s Guide 3 0 16 104 For outgoing connectors the sourc
54. T Syntax USESUBJECT Indicates that the message subject should be used as part of the message The subject will be inserted before the message body but after the sender if used Applies to SMTP incoming Introduced in EMG 2 0 Enterprise Messaging Gateway User s Guide 3 0 16 107 B 2 183 VASID Syntax VASID lt string gt Used for MM7 Senderldentification Applies to MM7 outgoing Introduced in EMG 3 B 2 184 VASPID Syntax VASPID lt string gt Used for MM7 Senderldentification Applies to MM7 outgoing Introduced in EMG 3 B 2 185 VIRTUAL Syntax VIRTUAL Specifies that the connector should not be instantiated in EMG but only used as a template for inheritance See also INHERIT Introduced in EMG 3 B 2 186 WAITBEFORECONNECT Syntax WAITBEFORECONNECT lt integer gt Introduced in EMG 3 B 2 187 WAITDELAY Syntax WAITDELAY lt integer gt Delay after connect in seconds Applies to All protocols outgoing B 2 188 WAITFOR Syntax WAITFOR lt string gt Wait for specified prompt after connect Applies to All protocols outgoing B 2 189 WHITELIST Syntax WHITELIST lt filename gt Specifies which file contains the connector specific whitelist Enterprise Messaging Gateway User s Guide 3 0 16 108 B 2 190 XAUTH Format is same as for general keyword WHITELIST Introduced in EMG 2 0 Syntax XAUTH Specified that the built in protocol mechanisms should be used for authentica
55. T TO address Enterprise Messaging Gateway User s Guide 3 0 16 47 Receiving messages MESSAGE Retrieved from the DATA message body EMG will also look for user defined headers on the format X EMG Option option If present they will be used and override any equivalent information provided in the SMTP session There are also a few specific connector keywords used by the incoming SMTP connector USESUBJECT This indicates that the Subject of the message should be included short message USESENDER This indicates that the sender of the message should be included short message SEPARATOR Specifies which separator should be used between sender subject and message body Default a single space USEPRIORITY This indicates that the X Priority message header if present will be used to set the priority of the short message All message options can be used using the X EMG Option xxx user defined headers The UDH if present in the message will also be sent using a user defined header with the UDH data hex encoded As many messages as possible will be sent in each SMTP session using the RSET command between the messages When sending binary messages or UDH the message data must be hex encoded 8 2 1 Sample incoming SMTP session Remote SMTP client lines begin with gt 220 lt hostname gt ESMTP gt HELO lt client host gt 250 Pleased to meet you gt MAIL FROM lt user domain co
56. TUS 6T eee eere ene rennen erii ntn reete 122 C 2 44 SUBIECT 111 ierit eet tere ipie 122 2 45 UDH TA iiiter reitera Free Feet teras 122 C 2 46 UDHI 106 tiet teet eine etcetera tibt o eiae 122 Enterprise Messaging Gateway User s Guide 3 0 16 DAT USER 30 s in 122 C 2 48 VP 18 iiis iei aa 123 C 2 49 XUSERNAME 119 eese eeeeeennenee ettet 123 DEO CODES e 124 DAW CIMIDD sa CEN 124 D2 SMBD iie bre deb ne diente se dea eta esee estes 124 DS UCP BEMIL tenebo trees eva SEENE ETA pope ERNE ENE 125 DA OIS ania medi ne E EERS bas reside eif tbes 125 b o UM M uie TE 125 D 6 S AD iiie ree re tr he ep d p ere ce bbs 126 E SMSC inter connectivity checklist eere 127 E 1 Your requirements eese 127 E T I Send messages eem ere epe bles 127 E 1 2 Receive messages uec tre rette bee dee detenta 127 E 1 3 Type of messages dii eee ier tete e edge cip desde 127 E 1 4 Performance or message volume eee 127 E 1 5 Support and service e rette nde itte rade 127 Bi2 SMSC COMECON ueniet e cete ridi tab i d e rro tede ene uad 127 B 2 1 Type of connection cete detecte tete 127 B 2 2 PROTO ON et ertet te dea ore de ek eR ego aa 128 B 2 3 Pettorinatice aiios uio enne oeste tired Ea Eees 128 IZA SEON eiieeii nectit rie esa pe eU eret eda e Reed 128 E3 Getting Started iud eode te Cette ara ten Wes
57. add 90 B 2 79 INSTANCES raeino bea eiae teer ea edente dad tek e Edere Re 90 B 2 80 INTERFACEVERSION eese 91 B 2 81 KEEPALIV eerie tete ree bine coethessscaeteces 91 B 2 82 LIBRARY isc iulii de devcetianieieiiie 91 B 2 83 LOCALDOMAINS e eceeeeee retener ntn entente ta tnnt 91 B2 84 LOCALIPS he fedes iile eie eie Tone 9 B 2 85 LOGLBENVEL need i teo it rhe ene tnn 92 B 2 86 LOGMESSAGE iei idbavadecee e E een 92 B287 EOGPDYU iet torre dre de eaaet 92 B 2 88 LONGMESSAGE esee eene enne 92 B 2 89 LONGMODE rettet ett i rhe enin RENE 92 B 2 90 MAPPING ftre teet bee iei na tele oo de 92 B 2 91 MASQUERADE etie aene petebat ba eed 93 B 2 92 MAXFAILEDCONNECTS eee 93 B 2 93 MAXPFPAILEDNSLBBB 2 2 creto eden 93 B 2 94 MAXMESSAGELENGTH eere 93 B 2 95 MAXTRIBS 1 ete debebat iai 93 B 2 96 MESSAGPBLENGIEH titt tete 93 B 2 07 MESSAGBMOBDB 2 p Ere nir otoa ie h enn 94 B 2 98 MESSAGES PER REQUEBST eee 94 B 2 99 MIMEBOUNDARY eren emen 94 B 2 100 MMS TEXT CHARSET eee 94 B210 MODE ient iere hh o Pee sten d 94 B 2 102 MODEM eiii eire ie e Eee be a OR Resa ede d 94 B 2 103 MSGDEDA Y ient rtt ete erbe iot Ea aee hoe 95 B 2 104 MSGRETRYTIME inerenti ete tertie eben da 95 B 2 105 MTBILLING 5 citt tein rro e reb betta etuer 95 B 2 106 NOBINARYMAPPING
58. age and later charge additional credits if message was split into multiple PDUs Refresh Connector hold flag was reset during server refresh reload License On Linux when MAC address of ethO is not available use IP address for license check instead Added reasontext for CIMD2 SMPP and UCP for protocol specific error information Fixed minor memory leak when incoming connections was terminated pre maturely o o o 0 OG F 15 EMG 3 0 First official release of EMG 3 Enterprise Messaging Gateway User s Guide 3 0 16 137 Index Blacklist using 57 C CMG SMSC 16 Connector states overview 26 Connectors incoming 25 outgoing 25 sample configurations 32 short circuit 25 static 25 E EBE exit code 44 emgd refreshing 21 starting 21 stopping 21 EMGDIR defined 19 Exit code when using EBE connector 44 F Failover connectors 38 Enterprise Messaging Gateway User s Guide 3 0 16 G general log file 53 GSM 3 40 User Data Header 14 H HTTP receiving messages 47 sending messages 42 L Load balancing connectors 38 Log files connector files 53 format 54 general 53 security 53 Logging log level 53 performance 53 Logica SMSC 16 Mappings incoming 28 outgoing 28 using 27 Messages binary 14 138 N S Nokia SMSC 16 Security access control 57 blacklist 57 overview 57 o SMTP receiving messages 47 Orphans sending messages 42 overview 15 ORPHANSSIZE 15 OTA exam
59. age is then re routed to the specified connector Applies to All protocols Introduced in EMG 3 0 16 Enterprise Messaging Gateway User s Guide 3 0 16 85 B 2 45 FIRST_TRN Syntax FIRST_TRN lt integer gt Specifies that another transaction number should be used instead of default Applies to SMPP connectors that connect to a remote entity that requires a cer tain transaction number for the first transaction B 2 46 FORCE_CHARCODE Syntax FORCE_CHARCODE lt integer gt Replaces character code on the message with the specified value Values 0 Default 1 IAS 2 8 bit 4 UCS2 B 2 47 FORCECLOSE Syntax FORCECLOSE Specifies that the connection should be closed after the current request Applies to HTTP B 2 48 FORCE DCS Syntax FORCE DCS integer B 2 49 FORCE DESTADDR Syntax FORCE DESTADDR sstring If present the specified message destination address will be set to this value even if already present in the message B 2 50 FORCE DESTADDR IN Syntax FORCE DESTADDR IN sstring Same as FORCE DESTADDR but applies to received messages B 2 51 FORCE DESTADDRNPI Syntax FORCE DESTADDRNPlI integer If present the specified message destination address number plan indicator NPI will be set to this value even if already present in the message Introduced in EMG 2 4b Enterprise Messaging Gateway User s Guide 3 0 16 86 B 2 52 FORCE DESTADDRNPI IN Syntax FORCE DESTADDRNPI IN sstring
60. age received by EMG millis This option only holds the milliseconds part of the time Enterprise Messaging Gateway User s Guide 3 0 16 121 Values 0 999 C 2 42 STARTSECS 93 Timestamp when message received by EMG seconds The milliseconds of this value is stored in STARTMSECS The value of the option is the time in seconds since 1 January 1970 UTC C 2 43 STATUS 61 Message status Values 1 Delivered 2 In process 3 Failed 4 Deleted 3 Expired 6 Rejected 7 Canceled 8 Queued 9 Orphaned 10 Relayed 11 Unknown C 2 44 SUBJECT 111 Default subject Applies to SMTP Introduced in EMG 2 0 C 2 45 UDH 14 User Data Header The User Data Header C 2 46 UDHI 106 User Data Header Indicator Indicates that the message includes a UDH in the message data Introduced in EMG 1 0f C 2 47 USER 30 Username for client that sent the message Enterprise Messaging Gateway User s Guide 3 0 16 C 2 48 VP 18 Validity Period C 2 49 XUSERNAME 119 MQP username Used to route messages not only to a specific connector but to a specific user Applies to MGP Enterprise Messaging Gateway User s Guide 3 0 16 123 D Error codes In the connector log files protocol specific error codes may be displayed within parenthesis when send or receive operations fail The most common of these error codes are specified below per protocol D 1 CIMD2
61. also RETRYTIME MAXFAILEDSLEEP B 2 93 MAXFAILEDSLEEP Syntax MAXFAILEDSLEEP lt integer gt Time in seconds to sleep in state ERROR Default 60 See also RETRYTIME MAXFAILEDCONNECTS B 2 94 MAXMESSAGELENGTH Syntax MAXMESSAGELENGTH lt integer gt Specifies the maximum length of a message that will be accepted Messages longer will be rejected with the SMTP error code 552 Default value 30000 bytes Applies to SMTP incoming B 2 95 MAXTRIES Syntax MAXTRIES lt integer gt Specifies the maximum number of times delivery may fail before message is considered undeliverable Default value 10 Introduced in EMG 2 5 B 2 96 MESSAGELENGTH Syntax MESSAGELENGTH lt integer gt Specifies the length of a message Default value 160 Applies to CIMD2 SMPP UCP EMI Enterprise Messaging Gateway User s Guide 3 0 16 93 See also LONGMESSAGE LONGMODE B 2 97 MESSAGEMODE Syntax MESSAGEMODE lt string gt Introduced in EMG 3 B 2 98 MESSAGES PER REQUEST Syntax MESSAGES PRE REQUEST xcinteger2 Introduced in EMG 3 B 2 99 MIMEBOUNDARY Syntax MIMEBOUNDARY lt string gt Introduced in EMG 3 B 2 100 MMS TEXT CHARSET Syntax MMS TEXT CHARSET sstring Introduced in EMG 3 B 2 101 MODE Syntax MODE lt string gt Specifies whether a connector should be allowed to transmit TX receive RX or both transmit and receive TRX messages A connector that receives a message but is only permitted to
62. an only send messages Querying the SME requests delivery of messages or polls for messages 3 Receiving the SME is always ready to receive a message The querying type setup seems to be quite common and in this case the POLLRECEIVE key word needs to be specified so that the SMSC will deliver messages EMG supports CIMD2 2 0en 2 11 2 SMPP SMS Forum This protocol in version 3 4 is designed to support a variety of different mes saging centers in different network types and hence is the protocol that provides the largest amount of options However for SMS in a GSM network many of the options are not used SMPP has evolved to be the number one messaging stan dard and is getting more and more widely used EMG can be configured to use both the submit sm and the data sm SMPP oper ations depending on protocol version specified by INTERFACEVERSION and the value of DEFAULT SMSCOP The submit multi sm operation is currently not supported SMPP 3 4 is a much more thorough specification than SMPP 3 3 EMG supports SMPP 3 3 and SMPP 3 4 It is implemented by the Logica SMSC and others 2 11 3 UCP EMI CMG There a number of different operations for sending a message that remain from earlier versions of the protocol but which are now obsolete The default opera tion and the operation that should be used is the Submit Short Message 51 operation EMG supports UCP EMI 3 5 and UCP EMI 4 0 2 11 4 OIS Sema OIS is supported over TPC
63. atabase profile see 59 12 1 4 Referencing a database profile esee 60 12 2 Using the datab se cederet itte e e tha ed e 60 12 2 1 Putting the message route log in a database 60 12 2 2 Putting the connector log in a database 60 12 2 3 User authentication from database esse 60 12 3 Schema version handling eee 61 13 subsp 62 13 1 Hardware and operating system esee 62 VS MCR ste ce UE 62 DS VD RAM 62 VS BS DISK qu 62 13 1 4 Operating system sess ne 63 13 2 PrOtOCOlS i i cii eet her piece pae Ie EL erre pae oe Eds eb eue ec 63 13 3 IMStANCES arn Lae dernieres tert e er e distdir rin repe acts 63 13 4 Other ISSUES c ei nthe sect cese Hee Pai S pest eae CH Yr LESER REG 63 13 4 1 Modifying message content esee 63 13 4 2 Server logging and debug mode sess 64 13 5 About benchmarks eiit E ie rete nente tn 64 A Cominand reference eed e Pee bibe dbi ire baee eia 65 AT emecliett nce rene ette P ee E EREE 65 A2 emgd iauiosepoetonee sanae band nifi nii eite 66 Px 3 SIMO SCNG M m 67 AA CINGStAL 5 E 68 ASS TOMS COMP unte aerae ERENER AEE EEN EaR 69 AO PUSHtONER oc sctevds I 70 PWRnilodSe m 71 B Con
64. atabase server must be installed The database must be initialized for EMG A database profile must be created in the configuration file server cfg The database profile must be referenced in EMG 0 12 1 Getting started with a DB 12 1 1 Installing the database server Please visit the website of the database supplier for more information on generic installation configuration and licensing of the database used 12 1 2 Initializing the database Scripts for database initilization is provided in the EMG distribution for exam ple emg schema mysql sql This script does not create the database Also it does not drop the tables if they exist For MySQL there is a script performing these tasks included in the distribution It is named createemgdb mysql sh and is pro vided as reference 12 1 3 Creating a database profile In order to use the database a database profile must be defined in server cfg Sample entry DB emg lt TYPE MYSOL HOST PORT DBNAME USERNAME emg PASSWORD secret INSTANCES 1 gt ocalhost Enterprise Messaging Gateway User s Guide 3 0 16 59 Database support Please note that it is currently not support to set INSTANCES gt 1 for a database profile 12 1 4 Referencing a database profile Use the DBPROFILE keyword in the configuration file server cfg to reference the previously created database profile in this case called emg For EMG Roamer the DBPROFILE keyword
65. be added after the string Applies to All protocols incoming B 2 122 PROTOCOL Syntax PROTOCOL lt string gt Protocol used by the connector Values CIMD2 EBE HTTP MGP MMS OIS SMPP SMTP UCP B 2 123 QUOTEDREPLY SEPARATOR Syntax QUOTEDREPLY SEPARATOR sstring Specifies separator to be used between reply and original message when using quoted reply option Enterprise Messaging Gateway User s Guide 3 0 16 97 Default Original message below Introduced in EMG 3 0 B 2 124 QUOTEDSUBJECT Syntax QUOTEDS UBJECT lt string gt Indicates that when a message is going to be sent out using SMTP the message subject is part of the message The supplied string must consist of 2 characters where the first character indicates Example QUOTEDSUBJECT Message This is the subject And here comes the message body Will extract the string within parenthesis from the message above and use it as the subject of the message Applies to SMTP outgoing Introduced in EMG 2 0 B 2 125 REDIRECT Syntax REDIRECT lt connector gt Introduced in EMG 3 B 2 126 REGEXP_DESTADDR Syntax REGEXP_DESTADDR lt regexp gt Introduced in EMG 3 B 2 127 REGEXP DESTADDR IN Syntax REGEXP DESTADDR IN regexp Introduced in EMG 3 B 2 128 REGEXP KEYWORD Syntax REGEXP_KEYWORD lt regexp gt Introduced in EMG 3 B 2 129 REGEXP MESSAGE Syntax REGEXP_MESSAGE lt regexp gt Introduce
66. been established and before any messages can be sent or received If no encryption is used this infor mation is sent in clear text See USER USERNAME PASSWORD connector keywords 11 3 Blacklists and whitelists Certain source or destination addresses may need to be logged separately or even blocked rejected To enable this blacklists and whitelists can be used per con nector or server wide A blacklist can be used to specifically reject or log an address while a whitelist if present will reject all addresses not in the whitelist If an address is rejected by any blacklist the address will be rejected since whitelists cannot be used to override the behavior from a blacklist Enterprise Messaging Gateway User s Guide 3 0 16 57 Security Processing of blacklists and whitelists is illustrated by the pseudo code below DoLog false DoReject false If connector blacklist exists If entry matches If action LOG gt DoLog true If action REJECT gt DoReject tru If general blacklist exists If entry matches If action LOG gt DoLog true If action REJECT gt DoReject tru If connector whitelist exists If entry matches If action LOG gt DoLog true else DoReject true If general whitelist exists If entry matches If action LOG gt DoLog true else DoReject true If DoReject true Reject message Else If DoLog true Log message and allow Else Al
67. bles upgradesql Print the SQL commands that would be executed to upgrade the database schema without actually executing them V Display version and license information Enterprise Messaging Gateway User s Guide 3 0 16 66 verify Parse the configuration file and report found configuration errors without starting the server Examples emgd emgd debug A 3 emgsend Used to send messages using the MGP protocol By default the newly assigned message id is displayed when the message has been successfully sent to the server Options host host name IP address gt Jse specified hostname when connecting to server C port port number Use specified port when connecting to server username username Username for server authentication password password Password for server authentication b filename Read recipients from the specified file Format of file is one recipient per line file filename Read the message body from the specified file hex Message is hex encoded Specify message options q Do not display message id url URL to use for HTTP based protocols Examples emgsend 101010 Test message emgsend hex 414243 emgsend o ROUTE cimd2 1 101010 Test message Enterprise Messaging Gateway User s Guide 3 0 16 67 A 4 emgstat Display information about connectors and connector states Options host lt host name IP addr
68. c ucp smsc5 ucp LB The first line specifies that incoming messages on connector smpp in1 should be routed to the connector smscl ucp the second line that messages on smpp in2 should be routed to smsc2 smpp and if it is not available or in state ERROR it should route it via smsc3 smpp fail over Finally the third line is similar to the second line with the exception that if both smsc4 ucp and smsc5 ucp are avail able load balancing will take place and outgoing messages will be sent by alter nating between the two connectors specified When using failover load balancing a maximum of 16 outgoing connectors can be specified The routing table also supports routing on source or destination address prefixes This can be specified by in the incoming connector field the first field a character source address or gt character destination address followed by a prefix Multiple destination address prefixes can also be supplied in a file when using the character A character is equivalent to a gt character desti nation address Example gt 4670123456 smscl ucp etc emg smsc2 prefixes smsc2 smpp mgpl smsc ucp smsc5 ucp LB When checking the routing table EMG starts with the first entry and continues down until it finds a matching criteria The following is an example of a bad routing table where line 2 and 3 will have no effect at all since all entries that match line 2 or 3 also matches line 1 and it
69. cation with plain text usernames and password Does the operator provide other kinds of security mechanisms In case of an TCP IP connection access to the service should be restricted based on the ESME source IP address You will probably have to pay the bill if a malicious person gets hold of the username and password and sends unauthorized messages using your account E 3 Getting started E 3 1 Account information After installing EMG you need to set up an outgoing connector to the SMSC in question In order to do this you need your account information For a TCP IP connection this includes SMSC IP address SMS port Protocol used Username Password 00 O6 Using this information you should be able to configure your connector and start the EMG server Enterprise Messaging Gateway User s Guide 3 0 16 128 E 3 2 Sending the first message When both EMG and the SMSC are set up it is time to test the connection The best way to do this is simply to send a message from EMG routed via the outgo ing connector to the SMSC This will verify the connection to the SMSC the authentication process and finally the delivery of a message The behavior in the following situations should also be verified if relevant Sending a message to an invalid destination address recipient Using national characters Sending long messages more than 160 characters Sending messages to foreign recipients destination address format with country
70. ced in EMG 3 B 2 145 ROUTE Syntax ROUTE lt string connector name gt Primary connector to route messages to This option only applies to incoming messages via that connector B 2 146 ROUTEDLR Syntax ROUTEDLR lt string connector name gt Specifies to which connector DLRs should be routed B 2 147 ROUTING Syntax ROUTING lt string gt Introduced in EMG 3 B 2 148 SATPOOL_CREATE Syntax SATPOOL_CREATE lt string gt Create a SAT entry for messages being sent over the connector Introduced in EMG 3 B 2 149 SATPOOL CREATE IN Syntax SATPOOL CREATE IN string Same as SATPOOL CREATE but applies to messages received over the con nector Introduced in EMG 3 B 2 150 SATPOOL LOOKUP Syntax SATPOOL_LOOKUP lt string gt Specifies one or more SAT pools to be used for SAT lookups for messages being sent over the connector Multiple occurances allowed Introduced in EMG 3 B 2 151 SATPOOL LOOKUP IN Syntax SATPOOL LOOKUP INc sstring Enterprise Messaging Gateway User s Guide 3 0 16 101 Same as SATPOOL_LOOKUP but applies to messages received over the con nector Multiple occurances allowed Introduced in EMG 3 B 2 152 SCAADDR Syntax SCAADDR lt msisdn gt Set Service Center SMSC address in message PDU Applies to GSM Introduced in EMG 3 0 3 B 2 153 SCAADDRNPI Syntax SCAADDRNPI lt integer gt Set Service Center SMSC address NPI in message PDU Applies to GSM Int
71. chnically CMR checks the message UDH to see if the mes sage is part of a concatenated message Enterprise Messaging Gateway User s Guide 3 0 16 41 Sending messages 7 Sending messages The messaging protocols including the proprietary MGP all include functional ity to send receive query and delete messages In general messages are kept in the queue for the connector through which it should be sent until successfully sent or until a permanent error has occurred Most errors are considered temporary though and will cause the message to stay in queue for further delivery attempts When a temporary error has occurred for a message it is put in the end of the queue in order for other messages to be deliv ered meanwhile It is possible to specify a maximum number of delivery attempts after which the message will be considered undeliverable and will be removed from the queue 7 1 Using HTTP connector When EMG sends a message to an HTTP server or similar it uses the URL defined by the SUBADDRESS keyword and adds options as HTTP parameters to form a complete GET or POST request depending on the DEFAULT_SMSCOP setting for the connector The response to the request must be 200 OK in order for the message to be con sidered delivered successfully When sending binary messages or UDH the message data will be hex encoded EMG supports persistent HTTP 1 1 connections EMG supports HTTP basic authentication using the XAUTH keywords
72. cknowledged receiving the message Usually when a message passes through EMG and it is successfully delivered to the SMSC the status of the message is RELAYED This means that the message was successfully transferred to and accepted by the SMSC but we still do not know if the message reached its final destination the phone However if a DLR was requested then the SMSC would send a DLR back to EMG when the final status is reached in this case DELIVERED EMG then updates the message status from RELAYED to DELIVERED a final status A DLR basically consists of a message id and a status In EMG the MGP option MGP OPTION MSGTYPE is set MSGTYPE DLR 5 to indicate that a mes sage is in fact a DLR DLRs are propagated through EMG as any other message except that the special ROUTEDLR keyword is used for routing If ROUTEDLR is not specified an DLR is routed to the connector from which the original message was received Also for messages terminated within EMG for any reason DLRs will be gener ated and sent out For example when a message is delivered using an HTTP SMTP MGP or EBE connector EMG sets the final status to DELIVERED and a DLR is generated if requested 9 2 Requesting a DLR A DLR can be requested in several ways 9 2 1 Using emgsend The MGP option DLR can be specified on the command line mgsend o DLR 1 46123456 test message 9 2 2 Using connector keyword If DEFAULT DLR keyword is used the default behavior for m
73. d in EMG 2 5 B 1 21 ROUTEDLR Syntax ROUTEDLR lt string gt Specifies to which connector DLRs should be routed This is the default route which can be overridden by the ROUTEDLR keyword on a specific connector Introduced in EMG 2 4a B 1 22 ROUTELOGDB Syntax ROUTELOGDB Specifies that route log entries should be saved in database The route log con tains status for messages Introduced in EMG 3 B 1 23 ROUTELOGSIZE Syntax ROUTELOGSIZE lt integer gt Maximum number of entries in routing log When using ROUTELOGDB this value is the number of entries to keep in memory and can be left at the default setting Entries are never deleted from the database regardless of this value Enterprise Messaging Gateway User s Guide 3 0 16 76 When the maximum size is exceeded the oldest entry is discarded Default value 10000 B 1 24 ROUTING Syntax ROUTING lt filename gt Specifies which file contains the routing table The format of the file is one entry per row where each entry consists of minimum two and maximum three tab sep arated fields Lines beginning with are not processed The fields are Incoming connector or address If field starts with lt it will be matched to the source sender address if field starts with gt it will be matched to the destination recipient address If field starts with it is taken as a file containing destination address pre fixes If field does n
74. d in EMG 3 B 2 109 OPSENTEXPIRES Syntax OPSENTEXPIRES lt integer gt B 2 110 OPS MAXINCOMING Syntax OPS_MAXINCOMING lt integer gt B 2 111 OPS_ MAXOUTGOING Syntax OPS_MAXOUTGOING lt integer gt Enterprise Messaging Gateway User s Guide 3 0 16 95 B 2 112 OPS MAXOUTSTANDING Syntax OPS_MAXOUTSTANDING lt integer gt Maximum number of operations outstanding Some of the protocols like SMPP can handle that the remote peer sends multiple operations without waiting for a response in between This improves perfor mance but requires that the application keeps track of operations sent but not acknowledged outstanding The actual number of outstanding operations permitted depends on the type of protocol in use the EMG setting and also the setting in the remote application usually the SMSC Default values 1 for all protocols B 2 113 OPS MAXPERSESSION B 2 114 ORIGIN Syntax OPS_MAXPERSESSION lt integer gt Maximum number of operations to send per session When this limit has been reached the connector will disconnect Syntax ORIGIN lt string gt Introduced in EMG 3 B 2 115 PARSEMESSAGE Syntax PARSEMESSAGE lt string gt Used to parse a message for message options The format for the supplied string is message option separator message option gt The message is always expected to be the last option and indicates that the rest of the message contains the message body Example P
75. d in EMG 3 B 2 130 REGEXP SOURCEADDR Syntax REGEXP_SOURCEADDR lt regexp gt Enterprise Messaging Gateway User s Guide 3 0 16 98 Introduced in EMG 3 B 2 131 REGEXP SOURCEADDR IN Syntax REGEXP SOURCEADDR IN regexp Introduced in EMG 3 B 2 132 REJECT EMPTY Syntax REJECT EMPTY Reject messages that contains an empty message body Introduced in EMG 3 0 3 B 2 133 REMOVEPREFIX Syntax REMOVEPREFIX lt string gt Removes prefix for destination address DESTADDR The specified prefix will be removed if it exists in the destination address It can be combined with REQUIREPREFIX and is applied before REQUIREPREFIX For example if REMOVEPREFIX and REQUIREPREFIX 00 and the desti nation address is 44612345678 the will be removed and the destination address will be padded with 00 the final destination address being 004612345678 B 2 134 REMOVEPREFIX_SOURCEADDR Syntax REMOVEPREFIX_SOURCEADDR lt string gt Same as REMOVEPREFIX but applies to source addresses Introduced in EMG 2 5 B 2 135 REPLACEPREFIX Syntax REPLACEPREFIX lt string gt Specifies a sequence of source target address rewrite patterns B 2 136 REPLACEPREFIX IN Syntax REPLACEPREFIX_IN lt string gt Introduced in EMG 3 B 2 137 REPLACEPREFIX SOURCEADDR Syntax REPLACEPREFIX SOURCEADDR sstring Same as REPLACEPREFIX but applies to source addresses Introduced in EMG 2 5 Enterprise Messaging Gateway User s Guide
76. d messages are processed a message with lower priority always is transmitted before messages with higher priority If no priority is spec ified a priority of 3 is assigned B 2 29 DEFAULT SMSCOP Syntax DEFAULT SMSCOPc sstring Default value for SMSC operation Protocol Value Operation used SMPP 1 submit_sm SMPP 2 data_sm default for SMPP 3 4 HTTP 1 GET default HTTP 2 POST B 2 30 DEFAULT SOURCEADDR Syntax DEFAULT SOURCEADDR csstring Enterprise Messaging Gateway User s Guide 3 0 16 83 Default value for source address sender B 2 31 DEFAULT SOURCEADDRNPI Syntax DEFAULT SOURCEADDRNPI integer Default value for source address sender number plan indicator NPI B 2 32 DEFAULT SOURCEADDRNPI IN Syntax DEFAULT SOURCEADDRNPI IN integer Same as DEFAULT SOURCEADDRNPI but applies to received messages B 2 33 DEFAULT SOURCEADDRTON Syntax DEFAULT_SOURCEADDRTON lt integer gt Default value for source address sender type of number TON B 2 34 DEFAULT SOURCEADDRTON IN Syntax DEFAULT SOURCEADDRTON IN integer Same as DEFAULT SOURCEADDRTON but applies to received messages B 2 35 DEFAULT VP Syntax DEFAULT_VP lt integer gt Default value for validity period in seconds See also FORCE VP B 2 36 DELAYFIRSTMESSAGE Syntax DELAYFIRSTMESSAGE lt integer gt Specifies a delay to be imposed before first message is sent over a connection Introduced in EMG 3 0 5 B 2 37 DESTFULLNAME S
77. d values SI signal low signal medium default signal high signal none delete Allowed values SL execute low default execute high cache Example sending a WAP push to MSISDN 012345678 pushtohex type SI href wap domain com text Test link Enterprise Messaging Gateway User s Guide 3 0 16 70 A 7 rttitohex 01060403AE81EA02056A0045C60C037761702E646F6D61696E2E636F6D00010 35465737420646F6D61696E000101 emgsend o DESTPORT 2948 o SOURCEPORT 9200 o CHARCODE 2 hex 012345678 01060403AE81EA02056A0045C60C037761702E646F6D6N 1696E2E636F6D0001035465737420646F6D61696E000101 Encode a RTTL file as a Nokia Smart Message PDU The output will be hex encoded and can be used with emgsend as shown below Please note that the receiving phone must support Nokia Smart Messaging Example sending a ringtone to MSISDN 012345678 rttltohex abdelazer rttl 0C0106050415811581024A3A6505899195B185E995C80400E4D90413220B110 6889268495624B31261892CC4956249B124889348493624B31269892CC49342 4D112610922C495624C312558922849A224B210718926C4966249B107109304 495420D31249892AC491620D21258892AC496624AB124D89248496424AB1259 892AC493620D2124D0924C493624AB124D8926400001 emgsend o DESTPORT 5505 o SOURCEPORT 0 o CHARCODE 2 hex 012345678 0C0106050415811581024A3A6505899195B185E995C80400E4D90N 413220B1106889268495624B31261892CC4956249B124889348493624B31269N 892C
78. der Build date is now included in version information Arcor fixes DB schema change to version 15 F 13 EMG 3 0 4 6983 Minor release oo0o00 0 9 O 0 0000 New connector keyword ROUTING for specifying a connector specific rout ing table New connector keywords REVDLR and REVDLR IN for switching source and destination address for sent and received DLRs respectively New connector keywords used for setting TON and NPI when detecting address types automatically AUTOMATICTONNPI SHORTCODE TON AUTOMATICTONNPI SHORTCODE NPI AUTOMATICTONNPI ALPHANUMERIC TON AUTOMATICTONNPI ALPHANUMERIC NPI AUTOMATICTONNPI DEFAULT TON AUTOMATICTONNPI DEFAULT NPI New connector keyword REGEXP KEYWORD for applying regular expres sions to keywords Added new MGP options for SMPP fields source subaddress dest subaddress and its session info Apply mappings to keywords as well as message body MMS Keyword parsing for MMS messages implemented first check subject and if subject does not exist use first word in first plain text message part MIME Ensure quoted printable lines are CRLF terminated MM 7 Put short codes in ShortCode tag correctly MMT7 Allow empty Subject tag Handle empty SMTP messages Fixed potential crash for invalid formatted HTTP cookies Fixed potential crash when DNS lookup failed 0 0 6 Enterprise Messaging Gateway User s Guide 3 0 16 136 Fixed potential buffer overflow in MM1 parser
79. dles both splitting of messages and setting the corresponding UDH option automatically In EMG one message is translated into one or more Physical Data Units PDUs Each PDU corre sponds to one transferred SMS Starting with EMG 3 EMG also supports sending and receiving multimedia messages MMS Protocols such as MM7 EAIF and PAP are supported Basic convserion functionality is also included for example e mail to MMS and MMS to e mail conversion 2 6 Connectors 2 7 Routing Messages are sent and received through so called connectors in the server Each connector is of type incoming and outgoing exists in one or more instances and implement one of the supported protocols Outgoing connectors support failover and load balancing via the routing table The process of passing a message from one connector to another in order for it to reach its final destination is referred to as routing The routing decision is based on the information in the routing table and message and connector properties 2 8 Message life cycle A message that is relayed through EMG passes a number of stages Message is received via a connector and its attached parameters are parsed A routing decision is made dependant on message information connector information and the routing table An outgoing connector is selected Message is placed in the queue for the selected connector OR if an outgoing connector could not be selected the message is considered an orphan
80. e connector B 2 62 FORCE SOURCEADDR Syntax FORCE SOURCEADDR sstring If present the specified message source address will be set to this value even if already present in the message B 2 63 FORCE SOURCEADDR IN Syntax FORCE SOURCEADDR IN csstring Same as FORCE SOURCEADDR but applies to received messages B 2 64 FORCE SOURCEADDRNPI Syntax FORCE SOURCEADDRNPI integer If present the specified message source address number plan indicator NPI will be set to this value even if already present in the message Introduced in EMG 2 4b B 2 65 FORCE SOURCEADDRNPI IN Syntax FORCE SOURCEADDRNPI IN integer Same as FORCE SOURCEADDRNPI but applies to received messages B 2 66 FORCE SOURCEADDRTON Syntax FORCE_SOURCEADDRTON lt integer gt f present the specified message source address type of number TON will be set to this value even if already present in the message Introduced in EMG 2 4b B 2 67 FORCE SOURCEADDRTON IN Syntax FORCE SOURCEADDRTON IN c integer2 Same as FORCE SOURCEADDRTON but applies to received messages B 2 68 FORCE SOURCEPORT IN Syntax FORCE SOURCEPORT IN integer Enterprise Messaging Gateway User s Guide 3 0 16 88 Set source port UDH of received messages to the specified value Introduced in EMG 3 0 16 B 2 69 FORCE VP Syntax VP lt integer gt Force the validity period to be set to the specified value seconds for all mes sages that passes through the connector
81. e 3 0 16 133 New DB keyword SOCKET for connecting to MySQL databases using a UNIX socket instead of TCP IP As a consequence PORT now must always be specified Automcatic conversion of UCS2 messages which does not use the high byte to Latin 1 added DLRs received with a buffered status are now handled and will update the bufferedstatus field in routelog accordingly Default lifetime for a DLR entry increased to 73 hours Default value for IDLETIMEOUT for outgoing connectors is now KEE PALIVE 10 seconds GSM modems would not work correctly if emgd had more than 64 file descriptors open New column msgtype in routelog table Now routelog can be used for all message statistics without using connectorlog DB Multiple schema changes for routelog DB Warn if INSTANCES 1 for a DB profile since this is not supported Plugin API Added functions plugin thread start and plugin thread stop for thread specific handling when using plugins Plugin API Plugins using more than 1 instance were not thread safe Performance Optimization of allocated buffers has increased performance substantially for this release Performance Switch to mtmalloc routines on Solaris which is much faster for multi threaded applications Solaris 10 x86 is now supported F 10 EMG 3 0 7 8470 Minor release o 0 6 o o0 0 Updated OpenSSL version to 0 9 71 Unnecessary counting of DLRs could cause high load on DLR intensive sys tems Environment
82. e IP address is set to the specified address May be needed on a host with multiple addresses on network interfaces Applies to All protocols Introduced in EMG 3 B 2 171 TCPSOURCEPORT Syntax TCPSOURCEPORT lt integer 0 65535 gt For outgoing connectors the source port is set to the specified port May be needed when for example an SMSC requires a specific source port for authenti cation Applies to All protocols B 2 172 THROUGHPUT B 2 173 TYPE Syntax THROUGHPUT lt integer 1 1000 gt Limits throughput for the connector in question The value specified is the num ber of messages per second A value of 0 means 0 5 messages per second Applies to All protocols Introduced in EMG 2 0 Syntax TYPE lt string INCOMING OUTGOING gt This indicates only whether the connector should accept incoming connections or initiate outgoing connections It does not tell anything about the direction of the message flow A message can be received on a outgoing connector and vice versa This depends on the protocol used B 2 174 UDHVIAOPTIONAL Syntax UDHVIAOPTIONAL Usually UDH parameters for source port destination port and concatenated mes sages is encoded into the UDH and is sent as part of the message data with the UDH indicator UDHI set However when this option is used on a SMPP 3 4 connector these UDH param eters will be sent as optional parameters instead Some applications that imple ment SMPP 3 4 may require th
83. e in EMG is SMS This for example means that when a message is received on an SMTP connector it is automatically parsed and con verted to a format that suits SMS and all attachments that are not text are dis carded In order to preserve the formatting for an incoming e mail message it is therefore necessary to set the message type to EMAIL Then the conversion will not take place until the message is sent out over a connector of another message type The message types in EMG SMS Default message type MMS Multimedia message MMS EMAIL E mail message formatted according to RFC 822 or RFC 1521 MIME WAPPUSH WAP push message DLR Delivery report CDRUPDATE CDRCANCEL CDRs only used with EMG Roamer FAX Reserved for future use In order to translate between different character sets being able to send and receive specific symbols etc it may be necessary to apply mappings to the mes sage data Mappings in EMG are defined per connector using the MAPPING keyword The keyword specifies a filename which contains the mapping or translation table EMG handles one to one one to many many to one and many to many map pings and both text and binary data can be processed The format of a mapping file is the following fields are tab separated left hand column specifies a source data looked for and right hand column the replace ment This is a comment in a sample mapping file First we define a mapping applied when a message
84. e is the program to be executed including the full path to the program For all other protocols the value is the host and port separated with a Example ADDRESS opt emg bin report sh ADDRESS localhost 7186 B 2 3 ADDRESSRANGE Syntax ADDRESSRANGE lt integer gt Specifies the address range parameter for SMPP bind operations Applies to SMPP Outgoing See also AUTHNPI AUTHTON B 2 4 ALLOWROUTE Syntax ALLOWROUTE When specified non admin users will be allowed to specify a message specific route via ROUTE keyword Applies to MGP HTTP SMTP Incoming B 2 5 AUTHCODE B 2 6 AUTHNPI B 2 7 AUTHTON Syntax AUTHCODE lt string gt Sets the field AC authentication code originator in UCP submit operation Applies to UCP Outgoing operation 51 Syntax AUTHTON lt integer gt Number Plan Indicator NPI for authentication operation Applies to SMPP Outgoing UCP Outgoing operation 60 See also AUTHTON Syntax AUTHTON lt integer gt Enterprise Messaging Gateway User s Guide 3 0 16 80 Type Of Number TON for authentication operation Applies to SMPP Outgoing UCP Outgoing operation 60 See also AUTHNPI B 2 8 AUTOMATICTONNPI Syntax AUTOMATICTONNPI When specified EMG will try to determine correct TON and NPI for source address based on the address format B 2 9 AUTOMATICTONNPL ALPHANUMERIC NPI Syntax AUTOMATICTONNPI_ALPHANUMERIC_NPI lt integer gt Introduced in EMG 3 0 B
85. e parenthesis 10 2 3 Sample outgoing connector log file Sep 11 22 35 28 664 4 CONNECT OK Sep 11 22 35 29 071 4 LOGIN OK Sep 11 22 35 30 275 4 SEND OK pdu 1 1 001 71 034 127 0 0 1 022 stenor 059 mgp 093 1031776474 094 393 008 1234 095 1031776530 096 269 017 3 Sep 11 22 35 40 512 4 LOGOUT OK Sep 11 22 37 29 007 4 DISCONNECT OK The log file entry for an outgoing CIMD2 connector above shows that a connec tion has been made with a sessionid of 4 and then one message consisting of one PDU has been sent successfully to the end point A number of message parame ters can also be seen on the format key value When an operation fails it will be indicate by the text ERR accompanied with a protocol specific error code within the parenthesis 10 2 4 PDU log files While the connector log files contains message related events encoded as MGP options the PDU log files contains the actual protocol specific operations being sent and received per connector PDU log files will be created either if the connector log level is DEBUG or DEBUG2 or if the connector keyword LOGPDU is present for the connector in question Enterprise Messaging Gateway User s Guide 3 0 16 55 Logging 10 3 Log file rotation Log files can be rotated based on time or size using the general keyword ROTATELOGS 10 3 1 Log file rotation based on time When log file rotation should be accomplished based on time the log files are rotated w
86. eceseceeceseeeseeeseceaeeeeseneeenees 52 IS EDD ATE c N 53 Enterprise Messaging Gateway User s Guide 3 0 16 10 1 Location Of log files cerent rri 53 10 2 Format of log files 55 5 e dete cesta aee tse aeu va 54 10 2 1 Connector log file nire rnnnnne 54 10 2 2 Sample incoming connector log file sess 55 10 2 3 Sample outgoing connector log file sssss 55 10 24 PDU log files eroi rem bet pe tinea 55 10 3 Los file rotation ete tet beret t rodeo 56 10 3 1 Log file rotation based on time sees 56 10 3 2 Log file rotation based on size sse 56 10 4 Logging to a database seseeeeeeeeeenen rn 56 IB condis 57 TIT ACCESS control n certe im tiet tetendit intere EIER 57 11 2 Authentication eerie itr ie epa co p nt taped 57 11 3 Blacklists and whitelists eee 57 11 4 Using SSL iine te cen eit eree tede pete tpa ee p Pu dd 58 11 4 1 Outgoing SSL without a certificate sss 58 11 4 2 Incoming SSL recited ent etr pens 58 12 Database SUppoOtt enel ecg e tot tr e setup dee 59 12 1 Getting started With a DB seen 59 12 1 1 Installing the database server een 59 12 1 2 Initializing the database esee 59 12 1 3 Creating a d
87. elete operation could delete wrong message Option MAXTOTALQUEUESIZE was not respected for most protocols Added MGP option DESTNETWORK which can be used for MNP routing URLs that starts with https in SUB ADDRESS should give SSL Algorithm for splitting long messages did not always work correctly Now IDLETIMEOUT is used when waiting for HTTP responses Minor memory leak fixed related to using invalid connector keywords Warn if KEEPALIVE is set to a greater value than IDLETIMEOUT Possible deadlock when authentication users from file and using maxsessions Session counter did not always handle disconnecting users correctly Support for multiple RETRYSCHEME keywords per connector Warn if DEFAULT MSGTYPE is supplied with an invalid message type Potential invalid reads on big endian archs Solaris Plugins Implementation of ZMRDB MNP in Germany and T Mobile Ger many billing plugins F 12 EMG 3 0 5 7719 Minor release 09 609 Treat HTTP status 202 accepted as delivery ok SMTP Error 450 is message specific and should not block entire domain for retry SMTP There was a 30 second hard coded idle timeout for incoming con nections Prune dlr and sat directories when using persistence Syntax xx can be used for binary data in keywords MSGTYPE DLR was not sent for DLRs over SMTP EBE connector did not count used instances correctly New connector keyword DELAYFIRSTMESSAGE which causes a delay bef
88. entries in the routing log is defined by the keyword ROUTELOGSIZE When the log exceeds the maximum size the oldest entry will be discarded When an incoming message cannot be routed or is routed to a connector that does not exist it will be added to a special queue for so called orphaned mes sages The maximum size of this queue is defined by the keyword ORPHANS SIZE When the queue exceeds the maximum size the oldest entry will be discarded If the value for this keyword is set to 0 orphaned messages will be dis carded directly When the server is refreshed the queue for orphaned messages will be processed and if for example the routing table has changed orphaned messages may be successfully re routed to a destination connector 2 11 Protocol conversion The different protocols supported by EMG differs somewhat in functionality and possibilities This is especially true when going from an older version of a proto col to a newer version This implies that some kind of conversion must take place Some parameters may need to be added some converted and some maybe even removed Enterprise Messaging Gateway User s Guide 3 0 16 15 Overview 2 11 1 CIMD2 Nokia CIMD2 supports two different types of Message Centers SMSC and USSD Some options are specific for one of the message center types The SMSC distinguishes between three types of SME s Short Message Entities in this case the EMG application 1 Send only the SME c
89. epted or if the mes sage is buffered in the SMSC due to handset being switched off for example 00 6 Such a DLR will not be propagated through EMG but will only update the buff eredstatus field in the routelog table within EMG When using EMG with a database this field can be queried in order to determine if and why a message has been buffered The message status will remain as RELAYED even after a DLR with a buff ered status has been received Enterprise Messaging Gateway User s Guide 3 0 16 52 Logging 10 Logging Logging is performed by the EMG log server which runs in the emgd process but in a separate thread It implements a special log queue in order to minimize impact on EMG performance The log files are located in the EMGDIR log directory and there are different files for different logs general The general log file where server wide information is stored Debug infor mation will also be in this file connector Connector specific log files where connections and messages sent and received will be placed security Security related information such as invalid username password combina tions blacklist whitelist information etc pdu Connector specific log files where all protocol operations will be logged This is the more protocol specific version of the connector log introduced in EMG 3 The log level determines how detailed the logging should be and can be set both for the server wide l
90. er s Guide 3 0 16 90 B 2 80 INTERFACEVERSION Syntax INTERFACEVERSION lt string gt Protocol version for the interface Values SMPP 33 or 34 for SMPP 3 3 and SMPP 3 4 respectively B 2 81 KEEPALIVE B 2 82 LIBRARY Syntax KEEPALIVE lt integer gt Time in seconds between keepalive packets Only valid for outgoing connections Specifies how often keepalive packets should be sent to avoid connection timeout on a static connection See also STATIC Syntax LIBRARY lt filename gt Used for customized connector implementations Applies to Prootcol DLL Introduced in EMG 3 B 2 83 LOCALDOMAINS Syntax LOCALDOMAINS lt string gt Specifies one or more domains handled by EMG and will be used together with keyword LOCALIPS to determine whether relaying is allowed or not Multiple occurances allowed Applies to SMTP incoming Introduced in EMG 3 B 2 84 LOCALIPS Syntax LOCALIPS lt string gt Specifies one or more IP addresses to be considered local and will be used together with keyword LOCALDOMAINS to determine whether relaying is allowed or not Multiple occurances allowed Applies to SMTP incoming Introduced in EMG 3 Enterprise Messaging Gateway User s Guide 3 0 16 91 B 2 85 LOGLEVEL Syntax LOGLEVEL lt string gt Log level for connector specific entries in general log file Values DEBUG2 DEBUG INFO WARNING ERROR CRITICAL See also LOGPDU B 2 86 LOGMESSAGE B
91. esent in UDH New protocol implemented SMSCI CIMD2 variant Loglevel now reset to info during reload if not present Increased buffer size for network communication for improved SMTP perfor mance Memory leak when clearing messages and PERSISTFILES in use Directory structure is now only traversed every minute when using PERSIST FILES pi o F 7 EMG 3 0 10 9505 Minor release O HTTP Validate hex encoded message bodies MMT Namespace added to DeliverRsp SMPP Possible null pointer when receiving invalid data emgclient Invalid pointer problem when running deleteall on server with a lot of activity PARSEMESS AGE did not handle all IA5 characters properly Enterprise Messaging Gateway User s Guide 3 0 16 132 New keyword AUTOWAPPUSH IN for receiving a link via SMTP and con verting it into a WAP Push SI Improved performance of hex encoder decoder Incoming connectors should not be set to hold on message errors F 8 EMG 3 0 9 9284 Minor release MGP Return code from plugin call before receive was not respected SMPP enquire link is not allowed if not logged in Optimizations in DLR handling Optimizations in logging Minor memory leak when database operation aborted unexcpectedly F 9 EMG 3 0 8 9115 Minor release 00 6 SMPP Messaging mode part of parameter esm_class was not respected SMPP Timezone was not handled correctly for validity period SMPP
92. ess gt Use specified hostname when connecting to server port lt port number gt Use specified port when connecting to server username lt username gt Username for server authentication password lt password gt Password for server authentication db Show database instance information Display detailed information Output will be in 11 columns with the following information NAME Connector name INDEX Connector index or position server cfg file TYPE IN for incoming OUT for outgoing connector PROTO Protocol INST Number of instances USED Maximum number of instances that is or has been 1n use since system start STATE Connector state QSIZE Connector queue size AVG IM Number of messages per sec processed during the last minute AVG 5M Number of messages per sec processed during the last 5 minutes AVG 15M Number of messages per sec processed during the last 15 minutes Example emgstat NAME INDEX TYPE PROTO INST USED STATE QSIZE AVG 1M AVG 5M AVG 15M mgp inl 0 IN MGP 1 1 BOUND 0 0 00 0 00 0 00 smpp inl 1 IN SMPP gi 1 BOUND 0 0 00 0 00 0 00 smtpl 2 OUT SMTP 0 0 DEAD 0 0 00 0 00 0 00 ucp andrew 3 OUT UCP 1 0 IDLE 0 0 00 0 00 0 00 ucp d2 4 OUT UCP 1 0 IDLE 0 0 00 0 00 0 00 cimd2 euro 5 OUT CIMD2 1 0 IDLE 0 0 01 0 01 0 00 Enterprise Messaging Gateway User s Guide 3 0 16 A 5 mmscomp Compile decompile a MMS message into from binary form Options
93. essages using the connector is set However a message specific option always supersedes a con nector option CONNECTOR smpp out DEFAULT DLR 1 2 Enterprise Messaging Gateway User s Guide 3 0 16 51 Delivery receipts DLR The keyword FORCE_DLR on the other hand overrides any DLR message option already set When FORCE_DLR 1 is used on a connector where mes sages are received the DLRs received or generated will be forwarded back to the client while if FORCE DLR 1 is used on a connector where messages are sent the received DLRs will only be used to update the message status and then silently dropped Please note that DLRs silently dropped will not appear in the corresponding con nector log but will only show up in the pdu log for the connector 9 3 Routing DLRs For incoming DLRs routing decisions are made a little differently than for nor mal messages It is evaluated in the following order with the highest priority first ROUTEDLR specified for user in users file or in DB who sent the original message for which DLR was requested ROUTEDLR specified on original message ROUTEDLR specified on connector where DLR is received generated ROUTEDLR specified by general keyword in server cfg DLR is routed back to the connector where the original message was received and optionally redirected via connector keyword REDIRECT 9 4 DLRs and buffered status Some SMSCs send a DLR when the message has been acc
94. figuration options sessesseeeseeeeere eren nnne 72 Bil General options adea era Due EL eU a PEE NGC Fe ii 72 Enterprise Messaging Gateway User s Guide 3 0 16 B 1 BEACRKLIST iecit rte tenente arai 72 B 1 2 CMREXPIRE n tet reda eie ec iet bates eiue Eco heaves 72 B 1 3 CONNECTORLOGDDB esee eene 72 B 1 4 CONNECTOR LOQGLENVEBL eere 72 B 1 5 DBPROPILE erede tator tuerit err peer een 73 B 1 6 DISABLE CREDITS eese nintetetnetteetetennte 73 IS NM DIBINNIVAD M 73 B L S DERVD isiteieihteapbiet tos iecit eig cerei PSP ed 73 B 1 9 DNSTHRBEADNS tetro aE E 73 B 1 10 LOGELUSBHS LZE dir eerte o tede rehe 73 B 1 Hl LOGLENVEL EEG ce EHE e teet eire aree ER co DR et ede 74 B L12 LOGY EAR sentier ipe nier n redondo Ren 74 B 1 13 MAXTOTALQUBEUPESIZE eene 74 B 1 14 NOEXPIRE erii etta ertet e eee eaten rideo 74 B 1 15 NOELUNSH 5 Rp deb ee eie erbe rear ved 75 B 1 16 NOLOGSBERV ER nectare niebla mede 75 B 1 17 ORPHANSSIZE cros niedo tette itte 75 B 1 128 PERSIS TEIDBS 4 tertio atra i EE eterne nece 75 B 1 19 PBRSIS DSIZB nein rhetor A 75 B 120 ROTATBLOQGS iiit Ert reote Else tpi etus 76 B 121 ROUTBDLR iiri in peni eere 76 B 1 22 ROUTBLEOGDB riot retento erri e ndn 76 B 1 23 ROUTBLEOQGSIZE in tnit tase habentia tente 76 B 1 24 ROUTING nie etse terae Rhe Fa aiii 77 B 1 25 SERVERNA
95. first verify that the outgoing connector s work s Use the emgsend command line utility to inject messages into EMG and use the server cfg keyword ROUTE or the routing table to make sure incoming messages from emgsend MGP protocol will be routed to the correct outgoing connector Enterprise Messaging Gateway User s Guide 3 0 16 23 Configuration Check the connector logs default EMGDIR connector For each message received and sent on a connector there will be a corresponding entry in the connector log file Use the debug option with emgd to generate complete debug information This information will be appreciated by NMT support engineers when help ing out in troubleshooting an installation The debug information will both be displayed on stdout and stored in the general log file You may need to empty the log file from old information by simply removing the file before starting emgd debug The file will be created if it does not exist when emgd is started Enterprise Messaging Gateway User s Guide 3 0 16 24 Connectors 5 Connectors Connectors provide the interface between Enterprise Messaging Gateway and other systems and applications For example one connector can connect to an operator s SMSC and another connector can accept incoming messages via HTTP Each connector can be available in one or more instances The core func tionality of EMG is to route messages from one connector to another When
96. for writing This will in practice limit the maximum number of instances that can be used in the sys tem Running the command emgd threadcount will count and display the maxi mum number of threads that can be created by a single process 13 4 Other issues 13 4 1 Modifying message content The only way to modify message content in EMG 1 x was to use an intermediate EBE connectors which affects maximum throughput severely In EMG 2 5 this can be done using mappings where even a complex mapping may affect perfor Enterprise Messaging Gateway User s Guide 3 0 16 63 Performance mance only by 15 20 From EMG 3 the EMG Plugin API can used in order to implement advanced functionality in process using a shared library which will impose a minimal overhead 13 4 2 Server logging and debug mode The logging in EMG is handled by a separate thread and therefore is very effi cient However if the queue of log events builds up quicker than it can be flushed to disk it will consume RAM I O and ultimately CPU resources Specif ically when running the EMG server emgd in debug mode emgd debug the impact on performance is severe 13 5 About benchmarks When performing benchmarks and load testing in order to verify that EMG delivers to its promise it is important to first of all make sure that the tools used are designed for the performance they are supposed to measure There are numerous tools freely available that are capab
97. format as prefix 46123456 International format no prefix 0046123456 International format 00 as prefix 070123456 National format When messages are sent out the receiving SMSC expected format is usually an international format without any prefix The above REPLACEPREFIX state ment would perform the wanted rewrite Once again operations are performed in sequence from left to right First any prefix or 00 is removed if present then if a national number was supplied the leading 0 is replaced by the country code 46 If instead a charac ter was required for the connection only a small modification would be needed REPLACEPREFIX 00 0 46 This example performs the same conversion as the earlier and in addition a is added as the final step 5 8 1 Masquerading Address masquerading can be used to hide the real sender of a mobile originated MO message before forwarding the message to a third party This may be required by some operators in order to get permission to handle MO traffic The masquerading is performed using a simple but efficient obfuscation of the address and the algorithm used is reversible and unique for each address An address with 1 9 digits will be translated into a 10 digit address Addresses with 10 18 digits will be translated into a 20 digit address Enterprise Messaging Gateway User s Guide 3 0 16 29 Connectors When using the masquerade keyword on a c
98. hat in order to be able to both send and receive messages at least two connectors must be defined 5 3 Static vs non static An outgoing connector can be defined as static using the STATIC keyword This indicates that the connector should connect to the remote entity immediately even if there are no messages to send The connector will still respect any idle timeout specified to if IDLETIMEOUT is set to a non zero value the connector will disconnect after being idle the specified number of seconds and the immedi ately reconnect since it is configured as static Enterprise Messaging Gateway User s Guide 3 0 16 25 Connectors Usually you would use IDLETIMEOUT 0 and set KEEPALIVE to a value for example 60 seconds This will keep the connection open by sending keepalive operations periodically to ensure the connection up 5 4 Connector states 5 5 Instances A connector can be in exactly one of the following states at a specific time IDLE Connector is just created or has been dynamically disconnected Static connectors should never be in this state during normal operation CONNECTED Connector is connected to remote endpoint but has not been authenticated BOUND Connector is authenticated and allowed to transmit and receive messages TERMINATING Connector will perform a graceful shutdown as soon as possible DEAD Connector is shut down ERROR Connector has failed a repeated number of times and is awaiting a new
99. hic software written by Eric Young eay cryptsoft com This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit http www openssl org Acknowledgements in accordance with the LibXML license Copyright C 1998 2003 Daniel Veillard All Rights Reserved Permission is hereby granted free of charge to any person obtaining a copy of this software and associated documentation files the Software to deal in the Software without restriction including without limitation the rights to use copy modify merge publish distribute sublicense and or sell copies of the Software and to permit persons to whom the Software is furnished to do so subject to the following conditions The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software Regular expression support is provided by the PCRE library package which is open source software written by Philip Hazel and copyright by the University of Cambridge England Perl regular expression support is provided by the PCRS library package Written and Copyright C 2000 2001 by Andreas S Oesterhelt andreas oesterhelt org Enterprise Messaging Gateway User s Guide 3 0 16 12 Overview 2 Overview 2 1 Licensing 2 2 Messages Enterprise Messaging Gateway EMG is a messaging platform that can act as a SMS MMS gateway protocol converter or some other kind of mediation ga
100. imd2user PASSWORD secret Try to connect one time before considered connection failed IAXFAILEDCONNECTS 3 When connection failed sleep for 5 minutes before trying again IAXFAILEDSLEEP 300 If destination address does not start with 00 add it REQUIREPREFIX 00 IDLETIMEOUT defaults to 30 seconds 5 11 5 Outgoing UCP using authentication via operation 60 CONNECTOR smscl ucp lt YPE OUTGOING PROTOCOL UCP Connector to server 10 0 0 1 port 5000 ADDRESS 10 0 0 1 5000 One instance is enough INSTANCES 1 Username password to use when authenticating USERNAME ucpuser PASSWORD secret Type of number short number alias used by auth operation 60 AUTHTON 6 Number plan id private used by auth operation 60 AUTHNPI 5 Do not timeout when idl IDLETIMEOUT 0 Incoming messages should be routed to connector smpp inl ROUTE smpp inl gt 5 11 6 Outgoing UCP via modem CONNECTOR smsc2 ucp lt TYPE OUTGOING PROTOCOL UCP Phone number to operator s modem pool ADDRESS 01122334456 Modem is connected to dev ttyS0 Linux MODEM ttyS0 Enterprise Messaging Gateway User s Guide 3 0 16 33 Connectors Init string to send before dialing INIT STRING AT amp F amp K3 One instance is all a tty can handle INSTANCES 1 Wait 2 seconds after connect WAITDELAY 20 Wait 2 seconds af
101. ing connector that can han dle incoming MMS as well as an outgoing MMS connector to a MMS center It is possible to use an incoming MGP connector to have EMG receive an MMS compiled by the EMG mmscomp utility and then sent using emgsend Sample configuration CONNECTOR mgp mms lt TYPE INCOMING ADDRESS 127 0 0 1 7185 PROTOCOL MGP INSTANCES 5 USERS users DEFAULT_MSGTYPE MMS ROUTE mm7 gt E CONNECTOR mm7 lt TYPE OUTGOING ADDRESS http mmsc 12000 mmshandler INSTANCES 1 VASID myuser VASPID mysecret gt 157 Enterprise Messaging Gateway User s Guide 3 0 16 45 Sending messages You can compile an MMS into binary format util mmscomp mmscomp totype PLMN to 467012345 o sample mms test txt and then send it using emgsend emgsend file sample mms 467012345 Enterprise Messaging Gateway User s Guide 3 0 16 46 Receiving messages 8 Receiving messages The messaging protocols including the proprietary MGP all include functional ity to send receive query and delete messages 8 1 Using HTTP connector Sending a message from a HTTP client to the incoming HTTP connector involves issuing a GET or POST request with the proper message options as arguments The document part of the request must be bin send Sample URL for sending an SMS with the text Hello world http localhost bin send SOURCEADDR 123456 amp DESTADDR 876543 amp MES SAGE
102. ing se gt gt 250 Sender ok RCPT TO lt 987654 domain com gt gt 250 Recipient ok DATA gt 354 Enter mail end with on a line by itself From 123456 nordicmessaging se To 987654 domain com X EMG Option SOURCEADDR 12345 This is the actual message gt 250 Message accepted for delivery QUIT gt 221 Closing connection All message options can be used using the X EMG Option xxx user defined headers The UDH if present in the message will also be sent using a user defined header with the UDH data hex encoded If successful the message id is returned in the SMTP DATA command response When sending binary messages or UDH the message data must be hex encoded 7 3 Using EBE connector The EBE connector does not really send the message but rather forwards it to a script or program which will be executed with message information on standard Enterprise Messaging Gateway User s Guide 3 0 16 43 Sending messages input This enables the user to invoke external programs and facilitates integra tion with third party solutions The format of the message information will be two fields per row where the first field is the message option key a numeric value and the second field is the actual value of the option The fields are tab separated 1 lt TAB gt 1003 34 lt TAB gt 127 0 0 1 30 lt TAB gt emguser 2 lt TAB gt 123456 8 lt TAB gt 56789 16 lt TAB gt 414243 The first row i
103. ing the EMGDIR variable to an alternate directory opt emg etc in Bourne shell or equivalent export EMGDIR EMGDIR opt emg etc After running the installation you should be able to execute emgd v in order to display your license information Sample output from an INSTALL script session on Solaris sh INSTALL x Enterprise Messaging Gateway 2 5 INSTALLATION EMG can be owned by the user root or by another user What user should be the owner of the EMG files root What group should be the group for the EMG files root Where should Enterprise Messaging Gateway configuration configuration files go etc emg Where should EMG executables go usr bin x Make sure this directory is in your PATH Creating directories OK oving programs OK oving data files OK Creating configuration file OK oICENSE INFORMATION Enter your license information EXACTLY as received HOSTID COMPANY DEMO TELNO 123456 SERIAL emgDEMO LICENSEDATA 30 Aug 2003 0 0 1 ACTIVATION I 615H94FafYn4A6 By creating etc init d emg the Enterprise Messaging Gateway server can be automatically started on system boot Should the server be automatically started on system boot y Creating etc init d emg Linking etc init d emg to etc rc2 d S99emg INSTALLATION FINISHED Enterprise Messaging Gateway User s Guide 3 0 16 19 In
104. is Applies to SMPP 3 4 outgoing B 2 175 USEDELTIME Syntax USEDELTIME Enterprise Messaging Gateway User s Guide 3 0 16 105 When specified message delivery times scheduled messages will be enforced within the EMG server rather than passed through to the SMSC That is if a mes sage has a delivery time in the future th message will be kept in the EMG queue until the time for delivery is reached rather than the message being passed to the SMSC with a scheduled delivery time set B 2 176 USEPRIORITY B 2 177 USERDB Syntax USEPRIORITY Indicates that the X Priority message header should be considered for setting the priority of the message Applies to SMTP incoming Introduced in EMG 2 0 Syntax USERDB lt string gt Specifies that user information for authentication incoming connections should be retrieved using the specified database profile B 2 178 USERDB_FORCE Syntax USERDB_FORCE lt string gt B 2 179 USERNAME B 2 180 USERS Syntax USERNAME lt string gt Used for outgoing connector authentication via the connector protocol Applies to All protocols outgoing Syntax USERS lt filename gt The users file is used for authentication of incoming connections If filename starts with a slash it is considered to be absolute otherwise it is relative to EMGDIR The format of the file is one username password combination per row with the fields tab separated plus an extra optional field
105. is is useful for testing purposes as well as for priority connectors MAXTOTALQUEUESIZE does not impose an exact limit It may be exceeded by 10 20 messages depending on current server conditions 5 11 Sample configurations Sample connector configurations 5 11 1 Incoming MGP supporting up to 3 connections CONNECTOR mgp inl TYPE INCOMING PROTOCOL MGP ADDRESS localhost 7185 Up to 10 connections INSTANCES 3 File where we find authentication info for users USERS etc emg mgp users gt 5 11 2 Incoming SMPP supporting up to 10 connections CONNECTOR smpp inl lt TYPE INCOMING PROTOCOL SMPP ADDRESS localhost 9000 Up to 10 connections INSTANCES 10 File where we find authentication info for users USERS etc emg smpp users 5 11 3 Incoming CIMD2 supporting 1 connection CONNECTOR cimd2 inl lt TYPE INCOMING PROTOCOL CIMD2 ADDRESS localhost 9000 One connection only INSTANCES 1 File where we find authentication info for users Enterprise Messaging Gateway User s Guide 3 0 16 32 Connectors USERS etc emg cimd2 users Force messages to be routed to connector ebel ROUTE ebel gt 5 11 4 Outgoing CIMD2 CONNECTOR smscl cimd2 lt YPE OUTGOING PROTOCOL CIMD2 Connector to server 10 0 0 1 port 5000 ADDRESS 10 0 0 1 9000 One instance is enough INSTANCES 1 Username password to use when authenticating USERNAME c
106. isconnect immediately after sending message s If yes should keepalives be sent and if so how often Enterprise Messaging Gateway User s Guide 3 0 16 127 Is an idle timeout allowed that is EMG waits for a specified period of time when the connection is idle before disconnecting E 2 2 Protocol What messaging protocol is used for communicating with the SMSC CIMD2 OIS SMPP and UCP are the common protocols used Protocol version is also of interest There is for example a big difference between SMPP 3 3 and SMPP 3 4 Make sure the type of messages you want to send receive can be transmitted using the protocol in question E 2 3 Performance Are there any restrictions as how many messages per second can be sent Can more than one connection be used Defined by the INSTANCES keyword More than one instance for an outgoing connection is usually not necessary What is the maximum throughput the SMSC can handle The protocol being used may be asynchronous meaning that it may be possible to send an operation without waiting for the response to the previous operation sent This enhances performance but makes the application a bit more complex since it must keep track of outstanding operations However EMG supports this and it makes sense to find out if the SMSC handles outstanding operations and if so how many E 2 4 Security None of the messaging protocol mentioned above provide any means of security apart from basic authenti
107. it and the trailing backslash Enterprise Messaging Gateway User s Guide 3 0 16 44 Sending messages f emgsend hex o SOURCEPORT 0 o DESTPORT 5505 o CHARCODE 2 461234567 N 0C0106050415811581024A3A6505899195B185E995C80400E4D9N 0413220B1106889268495624B31261892CC4 95624 9B124889348 493624B31269892CC493424D112610922C495624C31255892284 9A224B210718926C4966249B107109304495420D31249892AC49 1620D21258892AC4 96624AB124D8 92484 96424AB1259892AC493 620D2124D0924C493624AB124D8 926400001 Example sending Over The Air settings to an Ericsson T68 phone It is addressed to port 49999 in the phone and CHARCODE 2 indicates a binary message The message is more than 160 octets so it will be split and 2 SMS will be sent to the phone f emgsend hex o SOURCEPORT 49154 o DESTPORT 49999 o CHARCODE 2 461234567 01062C1F2A6170706C69636174696F6E2F782D7761702D70726FN 762E62726F777365722D73657474696E67730081EA01016A0045 C6060187124901871311033132332E34352E362E370001871C11 0373 6F 6E6F 66 6F 6E2E636F6D0001872270010186071103687474 703A2F2F7761702E646B0001C6080187151103414243000101C6 7F0187151103576170000187171103687474703A2F2F7761702E 646B00010101 7 5 Using emgclient The utility emgclient can be used to send query and delete messages and a few other administrative tasks Online help is available 7 6 Sending MMS In order to send an MMS message you need an incom
108. ith a specified interval On rotation the current log files are renamed with a timestamp as suffix 10 3 2 Log file rotation based on size Log file rotation based on size is accomplished by renaming the log file when it has exceeded a specified size using an index as suffix The most recently log file rotated out would have 1 as suffix the next most recent 2 and so on up to the specified total number of log files segments to save 10 4 Logging to a database If a database has been prepared for use with EMG it is possible to put the con nector log in the database The connector log files will also be used but it may be convenient to add the information into a database for example for generating sta tistics in an efficient way In order to put the connector log in a database the database must be prepared and a database profile referenced using the general keyword DBPROFILE Also the general keyword CONNECTORLOGDB needs to be added to the server cfg file in order to indicate that the log should be put in the database The connector log will be stored in the table connectorlog which can be found in the schema file included in the EMG distribution The event will given using the numeric event values as indicated below CONNECT 0 DISCONNECT 1 LOGIN 2 LOGOUT 3 SEND 4 5 7 9 RECEIVE REJECT MAXFAIL EXPIRE 10 Enterprise Messaging Gateway User s Guide 3 0 16 56 Secur
109. ity 11 Security Security in the EMG environment is enforced in a number of ways However the mechanisms are available at an application level and the system as a whole including hardware operating system etc should be secured by other means of protection EMG can use SSL for encryption for all protocols However it requires the remote entity to also support SSL for the connection in question If SSL support is not available it is recommended to use VPN or similar for protecting data transmitted over the Internet For HTTP and SMTP EMG also supports the authentication mechanisms avail able in the protocol such as HTTP basic authentication and SMTP login plain cram md5 authentication When creating incoming connectors make sure that the correct IP address is specified by the ADDRESS keyword Multi homed machines with more than one network interface may give several possibilities for the IP address specified make sure to pick the correct one Connectors that will only be accessed locally on the machine should use IP address 127 0 0 1 localhost The localhost inter face can only be accessed internally on the machine 11 1 Access control Incoming connectors can be restricted to only accept connections from specific client IP addresses or subnets See ACCESS connector keyword 11 2 Authentication Incoming connectors usually require authentication in the form of a username and password being supplied after the connection has
110. ke sure they have appropriate owner and permissions we use root in this example chown root usr bin emg chmod 555 usr bin emg chmod 500 usr bin emgd Verify that the new binaries execute ok the command below should not give any error messages emgd help Verify that the server configuration is ok if not make required adjustments Enterprise Messaging Gateway User s Guide 3 0 16 20 Installing or upgrading EMG emgd verify Start the server emgd Verify that the server is running ps ef grep emgd You should now be up and running with your upgraded software 3 5 Configure software Configuring the software usually involves Creating a server cfg that includes configuration for the needed connectors Creating a client cfg with hostname port and possibly authentication infor mation for MGP clients After the installation there will be a sample configuration in EMGDIR 3 6 Starting stopping and refreshing the server The server can be started by simply running emgd It is possible to set the debug level to DEBUG using the debug option It will also send the debug output to stdout emgd debug The server can be stopped using emgd stop To refresh the server use emgd refresh There are 3 different ways to refresh the server Run emgd refresh 2 Run kill 1 lt pid gt where pid is the parent emgd process 3 Useemgclient or another MGP client requires MGP administrator privi
111. l outgoing SMSC connectors CONNECTOR smsc template TYPE OUTGOING INSTANCES 1 NOBINARYMAPPING OGMESSAGE 160 LOGPDU VIRTUAL gt CONNECTOR smscl lt INHERIT smsc templat ADDRESS 10 0 0 1 5000 PROTOCOL SMPP USER userl PASSWORD secret gt CONNECTOR smsc2 lt INHERIT smsc templat ADDRESS 10 0 0 2 5000 PROTOCOL UCP USER userl PASSWORD secret gt A connector can only inherit from one other connector but it is possible to have inheritance chains where connectors inherit in multiple levels If a keyword is specified on both a parent connector as well as the child connector the keyword on the child connector is used Enterprise Messaging Gateway User s Guide 3 0 16 31 Connectors 5 10 Limiting connector queue sizes By using the general keyword MAXTOTALQUEUESIZE it is possible to limit the total number of messages in the connector queues server wide This is useful when EMG is one of several components through which messages will pass and it is preferable not to let queues build in EMG When the queue size limit has been reached EMG will reject further incoming messages using a protocol spe cific temporary error code indicating that the client should check back later for a new try It is possible to use the IGNOREMAXTOTALQUEUESIZE keyword for a con nector in order for it to accept messages even after the limit has been reached Th
112. l the behav ior of EMG In order to use EMG at least two connectors need to be defined in the server cfg file However it is most common that at least three connectors are defined One incoming connector for MGP used by the EMG client programs One incoming connector where messages will be received One outgoing connector which connects to an SMSC or similar For more information on connectors and how to configure them please consult the chapter Connectors 4 2 Refreshing the server After making changes to the server configuration file the changes will not be in effect until the server is either restarted refreshed or reloaded The routing table user files and most options in the configuration file will be refreshed with the fol lowing exceptions Connectors cannot be deleted or added The number of connector instances cannot be changed The connector protocol cannot be changed If any of these options need to be changed you would need to stop and start the server During a refresh all open connections will be closed gracefully while during a reload connections will not be close but only temporarily suspended 4 3 Testing a configuration After installing and configuring EMG consider the following When starting emgd does any messages that indicate a problem with the con figuration file show up in the general log file default EMGDIR log general If EMG is to be used as a converter with both incoming and outgoing connec tors
113. le of measuring perfor mance up to 10 20 mps but not more than that For example an SMTP load tester that do not use persistent connections will not be able to measure the full capabil ities of EMG Enterprise Messaging Gateway User s Guide 3 0 16 64 A Command reference The client utilities described below can be run from the command line prompt in the operating system They check EMGDIR client cfg for information about host port username and password If all or part of this information is missing from the configuration file it has to be specified on the command line All command utilities display help information when executed with help as argument emgsend help The utilities will return exit codes as follows 0 Successful 1 Unknown or unspecified error 3 Invalid login 5 Invalid argument 10 Access denied When using Bourne shell you can display the exit code by running echo after executing a command Example emgsend 12345 Test 758901 echo 0 A 1 emgclient Interactive utility that enables a user to operate on messages display queues and more It uses the MGP protocol to communicate with the server To be able to perform all available tasks and display all queue and orphan entries the user needs to be defined as an administrator in the user file Options host lt host name IP address gt Use specified hostname when connecting to server port l
114. lege EMG 3 also supports reloading which is similar to refresh with the difference that open sessions are not closed as is the case during a refresh Reloading the server is done by running emgd reload 3 7 Persistence When the server is stopped the connector messages queues and the routing log are flushed to disk The entries will be stored in the files queues dat and route Enterprise Messaging Gateway User s Guide 3 0 16 21 Installing or upgrading EMG log dat respectively The format of these files is one MGP option key value pair per row with an extra empty line as message separator If message persistence is enabled in the license flush files are not used Instead all messages DLRs and SAT entries are stored in the file system immediately upon reception and for the whole message life cycle When the message has reached its final status delivered or failed it is also removed from disk This way no messages will ever be lost even if the server terminates unexpectedly or crashes Enterprise Messaging Gateway User s Guide 3 0 16 22 Configuration 4 Configuration 4 1 General Software configuration is done by editing the configuration files For server con figuration the file EMGDIR server cfg is used and for client configuration the file EMGDIR client cfg is used EMGDIR defaults to etc emg as described in the Installation chapter The configuration files contain a number of keywords used to contro
115. low message See BLACKLIST WHITELIST general and connector keywords 11 4 Using SSL EMG supports SSL for all protocols although it is most commonly for HTTP connections SSL provides means for authentication using certificates and encryption with or without a certificate 11 4 1 Outgoing SSL without a certificate An outgoing connector for example HTTP can use SSL without a certificate by just adding the connector keyword SSL to the connector configuration This will encrypt all data sent over the connection protecting it from eavesdropping The type of encryption used will depend on what is negotiated between the client and the server 11 4 2 Incoming SSL Using SSL for an incoming connection requires a certificate which can be defined server wide or per connector The certificate is stored in the form of a so called PEM file Enterprise Messaging Gateway User s Guide 3 0 16 58 Database support 12 Database support A number of EMG components support DB connectivity Currently the sup ported databases are MySQL and PostgreSQL However EMG does not require a database in order to work Some functionality in future releases may depend on the database support but the core functionality does not depend on it Specifically database support may affect Account information Routing log Connector log MGP phonebooks EMG Roamer module In order to use a database a few steps must be accomplished A d
116. lowed B 3 4 PASSWORD B 3 5 PORT B 3 6 TYPE Syntax PASSWORD lt string gt Password used for authentication when connecting to the database Syntax PORT lt integer gt Port used when connecting to database Syntax TYPE lt string gt Type of database Values MYSQL MySQL PGSQL PostgreSQL B 3 7 USERNAME Syntax USERNAME lt string gt Username used for authentication when connecting to the database Enterprise Messaging Gateway User s Guide 3 0 16 110 B 4 SAT pool options Options used when defining SAT pools Example SATPOOL satl lt ADDRESSRANGE 4670001 4670010 THREADED gt B 4 1 ADDRESSRANGE B 4 2 EXPIRE Syntax ADDRESSRANGE lt string gt The addresses to use for the pool You can specify a comma separated list of individual numbers a range of numbers with identical prefixes and lengths or any combination of these When a range is specified the lower and the upper limit must have the exact same number of digits Example ADDRESSRANGE 460001 460010 460015 Syntax EXPIRE lt integer gt The numer of minutes a source address will be reserved for a specific SAT entry After the specified time it can be reused Default 4320 3 days B 4 3 QUOTEDREPLY Syntax QUOTEDREPLY lt integer gt Specifies that original message should be quoted when a reply is received via SAT Values can be 0 off or 1 on Default 0 off B 4
117. m gt 250 ok gt RCPT TO lt 123456 domain com 250 ok gt DATA 354 Enter mail ends gt From User Smith lt user domain com gt gt To lt 123456 domain com gt gt Subject Test SMS gt Date Thu 14 Feb 2002 17 36 00 0100 gt MIME Version 1 0 gt Content Type text plain gt Qqharset iso 8859 1 Content Transfer Encoding quoted printable Enterprise Messaging Gateway User s Guide 3 0 16 48 Receiving messages sxXx Priorirtvs 3 gt Test Ts 250 Messaging accepted id 7398 gt QUIT 221 Closing connection 8 2 2 Preventing SMTP relaying By specifiying which IP addresses are local and trusted and what domains are handled locally EMG can be set up to reject unauthorized relaying Sample configuration CONNECTOR smtp inl lt TYPE INCOMING OCALIPS 127 0 0 1 32 OCALIPS 10 0 0 0 8 jOCALIPS 192 168 0 0 16 OCALDOMAINS example com gt The above would indicate that only clients connector from private networks would be able to send e mail to other domains than example com through EMG If a client connecting from another IP tries to send e mail to a domain other than example com it would receive a Relaying denied error message in the SMTP session 8 3 Receiving WAP push via PAP EMG can act as a PPG Push Proxy Gateway and handle incoming WAP push messages issued via PAP Push Application Protocol a protocol based on XML over HTTP Sam
118. may be surrounded by quotation marks Possible key values are pdu dlr orphaned and info Example SEND ERR pdu 1 1 info 72 This would indicate a SEND event failed The pdu sent was one out of one and the protocol specific error code was 72 Enterprise Messaging Gateway User s Guide 3 0 16 54 Logging options Optional If the event is related to a message the message MGP options would appear here on a key value format 10 2 2 Sample incoming connector log file Sep 11 22 34 34 306 2 CONNECT OK info 127 0 0 1 Sep 11 22 34 34 316 2 LOGIN OK info emguser Sep 11 22 34 34 433 2 RECEIVE OK orphaned 001 71 034 127 0 0 1 022 stenor 059 mgp 093 1031776474 094 393 008 1234 017 3 Sep 11 22 34 34 468 2 LOGOUT OK Sep 11 22 34 34 471 2 DISCONNECT OK The log file entry for an incoming MGP connector above shows that an incoming connection from localhost 127 0 0 1 was received the user emguser logged in successfully and one message was received The message could not be routed and was therefore orphaned All message options are displayed on a key value format for example the recipient MSISDN 1234 is indicated by MGP option 8 MGP OPTION DESTADDR Also the message body is not logged only the message length three characters indicated by MGP option 17 When an operation fails it will be indicate by the text ERR accompanied with a protocol specific error code within th
119. n the general routing table However mes sage specific routes will have the highest priority Sample users file User specific routing table userl secret ROUTING etc emg routing userl User specific route user2 secret ROUTE cimd2 ep For more information check general keyword ROUTING and connector key word USERS in appendix Routing to a specific user When multiple clients connect through the same connector in order to receive messages it is important that each user receives only the messages addressed to that specific user and not any other user messages It is possible to route messages to a specific user by using the USERNAME key word in the routing table 2100 ucp in USERNAME user100 2101 ucp in USERNAME user101 Enterprise Messaging Gateway User s Guide 3 0 16 38 Routing The above will route messages based on destination address prefixes to that mes sages with a destination address startint with 100 will be routed to user user100 while destination addresses starting with 101 will be routed to user user101 Please note that users defined as ADMIN in the users file will receive all mes sages regardless of what user the messages are addressed to 6 7 Keyword based routing When accessing services via SMS from a mobile device Mobile Originated or MO messages it is sometimes useful to make routing decisions based on a key word in the message This
120. ndicates that the message id is 1003 message option 1 The sec ond row that it was received from a client that connected from the IP 127 0 0 1 localhost See MGP options chapter for more information about message options The exit code of the script is used to indicate whether the delivery was successful or not An exit code of 0 indicates success 1 a permanent error and all other exit codes temporary errors message is kept in queue for new retries Sample script bin sh tmpfile tmp ebe Default exit code is 0 OK ret 0 Write message information to file If cat fails set exit code to non zero cat gt Stmpfile ret 1 exit Sret 7 4 Using emgsend The utility emgclient implements the MGP protocol and can be used to send messages from the command line It checks client cfg and command line argu ments for server port and authentication information The assigned message id will be displayed on standard output by default Example sending a plain text message using emgsend emgsend usernam mguser password secret o ROUTE smscl ucp 070123456 This is a test message Example sending a ringtone using to a Nokia phone Nokia Smart Messaging It is addressed to port 5505 in the phone and CHARCODE 2 indicates a binary message The message is more than 160 octets so it will be split and 2 SMS will be sent to the phone The command line is split over multiple lines There is no space between the last dig
121. ng gt Default value for character code B 2 20 DEFAULT DESTADDRNPI Syntax DEFAULT DESTADDRNPI integer Default value for destination address recipient NPI B 2 24 DEFAULT DESTADDRNPI IN Syntax DEFAULT DESTADDRNPI IN integer2 Same as DEFAULT DESTADDRNPI but applies to recieved messages B 2 22 DEFAULT DESTADDRTON Syntax DEFAULT DESTADDRTON c integer Default value for destination address recipient TON B 2 23 DEFAULT DESTADDRTON IN Syntax DEFAULT DESTADDRTON IN integer2 Same as DEFAULT DESTADDRTON but applies to recieved messages B 2 24 DEFAULT DLR Syntax DEFAULT DLR integer Enterprise Messaging Gateway User s Guide 3 0 16 82 Default value for delivery receipt DLR B 2 25 DEFAULT DLRADDRESS Syntax DEFAULT DLRADDRESS sstring Specifies a default address for delivering DLRs Applies to MM7 Introduced in EMG 3 B 2 26 DEFAULT MSGTYPE Syntax DEFAULT MSGTYPE sstring Specifies the default message type for messages received over the connector Values NORMAL SMS EMAIL Email message RFC 822 or RFC 1521 MIME FAX Reserved for future use MMS Reserved for future use Default value is NORMAL B 2 27 DEFAULT PROTOCOLID Syntax DEFAULT PROTOCOLID integer Set default value for protocol id GSM 3 40 TP PID B 2 28 DEFAULT QPRIORITY Syntax DEFAULT QPRIORITY integer 1 5 Default queue priority for messages in EMG The lower the value the higher pri ority When queue
122. nnector where a reply SMS arrives the SATPOOL LOOKUP IN keyword is used in order to perform the lookup for the previously created SAT entry and to rewrite the address back to the original e mail address The SATPOOL CREATE and SATPOOL LOOKUP keywords works the same way but operates on messages being sent out via the connector where they are used Sample configuration parts of configuration omitted SATPOOL sati lt ADDRESSRANGE 10010 10020 THREADED 5 CONNECTOR smtp inl lt PROTOCOL SMTP SATPOOL CREATE IN satli Keep source e mail address intact REGEXP SOURCEADDR IN ROUTE smsc gt Enterprise Messaging Gateway User s Guide 3 0 16 30 Connectors CONNECTOR smsc lt PROTOCOL SMPP SATPOOL LOOKUP IN sati ROUTE smtp outl CONNECTOR smtp outl lt PROTOCOL SMTP INSTANCES 10 ADDRESS MX DOMAIN example com MAPPING mappings hso iso8859 out map DEFAULT MSGTYPE EMAIL 5 9 Inheritance and virtual connectors When having a large configuration with many connectors there will be many connectors with similar configurations In order to minimize configuration and make it more readable it is possible to let connectors inherit attributes from other connectors and also defining virtual connectors which are only used for inherit ance and never instantiated themselves Sample configuration Parent for al
123. ogs and for the connector specific logs using the LOGLEVEL keyword in the general or connector context When the server is started with the debug or debug2 option the log level is set to DEBUG or DEBUG2 and the log messages are also displayed on stdout This can be useful for debugging purposes 10 1 Location of log files Log files are by default put in the directory EMGDIR log The default location of this directory would be etc emg log which normally will be in a root partition with limited disk space There are two ways to change the location of the log files Create a log file directory and make a symbolic link from EMGDIR log to the new log file directory This must be done while the server is stopped Starting with EMG 2 5 it is also possible to set an environment variable EMGLOGDIR before starting the server pointing to the directory where the log files should be placed It is also possible to use log file rotation based on size in order to limit the maxi mum amount of disk space occupied by log files Enterprise Messaging Gateway User s Guide 3 0 16 53 Logging 10 2 Format of log files All log files contain a timestamp with a precision down to one msec It also con tains a message text and if relevant message properties The default format is similar to the syslog format and does not include year The general keyword LOGYEAR changes the date format in the timestamp to YY Y Y MM DD 10 2 1 Connector log file
124. onnector it will be applied to all messages sent and received over that connector See the connector keyword MASQUERADE for more information 5 8 2 Source Address Translation SAT Source Address Translation SAT is the procedure of replacing the source address of a message with another address and is most commonly used for implementing bidirectional e mail to SMS services For an e mail to SMS service an incoming e mail will obviously have an e mail address as source sender address and before forwarding the message to a mobile phone as SMS it is needed to replace the e mail address with a valid GSM number If the user should then be able to reply to the message by simply hitting the reply button the GSM number much be choosen so that the reply mes sage can be routed back to EMG via the SMSC Further if the combination of source and destination address can be made unique for each message a specific mobile phone user receives it will be possible to map a specific reply to a message back to the original message sent to the user We call this threaded messages All this functionality can be implemented using SAT pools in EMG where a SAT pool is a pool of source addresses from which EMG chooses an address for each message going out to a mobile phone via EMG For the connector where the e mail is to be received the connector keyword SATPOOL CREATE IN is used to indicate that SAT entries should be created when messages are received On the co
125. operating systems If you have an EMG server licensed for 10 mps hardware performance is not really an issue This often means that other criteria than performance can be the deter mining factor for the choice of hardware For example in some cases less expen sive low end hardware which can be easily replaced would be preferable while in other cases a high end server with built in redundancy would be a better choice EMG is very CPU intensive when processing many messages per second and a 50 faster CPU will give a close to 50 better result in performance Each message takes up a certain amount of RAM For example 100 000 mes sages in queue would need approx 15 MB of RAM Disk space should be sufficient to handle log files In order to limit disk space used by log files it is possible to use log file rotation based on size See the ROTATELOGS general keyword Enterprise Messaging Gateway User s Guide 3 0 16 62 Performance 13 1 4 Operating system With EMG 3 0 8 and later there is little difference between different OS versions on comparable hardware 13 2 Protocols The different protocols supported by EMG delivers different performance Spe cifically EBE and MGP are not to be used for high performance applications The EBE protocol forwards messages to external programs or shell scripts and for each message a process is forked in the system EBE connectors typically delivers a maximum of 20 200 mps when forking a shell sc
126. ore the first message is sent over a connection Relative SMPP time did not respect days months or years when specified Added concept of weak keywords which has a lower priority than keyword sessions via WEAKKEYWORD in routing file User specific force of source address did not always work as expected Avoid null pointer when emgstat is used immediately after server startup Binary messages should not be parsed for keywords Enterprise Messaging Gateway User s Guide 3 0 16 135 Delivery time was not handled correctly for CIMD2 SMPP and UCP Protocol ID GSM 3 40 TP PID was not handled correctly Keyword sessions could generate high load due to inefficient tree traversal Keyword sessions was only checked for messages containing a keyword SMPP message length was incorrectly set on big endian platforms DLR Expire field was not persisted and therefore lost on server restart UCP Number of sessions was not always decreased on disconnect UCP Message type was not set correctly for UCS2 and 8 bit messages via UCP deliver operation HTTP Fix UDH parse problem for incoming requests HTTP Avoid possible null pointer MM7 Send UTF 8 data without conversion using encoding quoted printable MMS New connector option MMS_TEXT_CHARSET used to set character set for text parts in MMS DCS parameter was not handled correctly for HTTP MM1 Set status in replies Log plugin rejects in connector log Minor perfomance optimization in hex enco
127. orphans should not expire in EMG based on the validity period VP By default if a message has a VP set and EMG can not send it before that period of time has elapsed it will expire and be removed from the queue Enterprise Messaging Gateway User s Guide 3 0 16 74 B 1 15 NOFLUSH Syntax NOFLUSH When used queues are not flushed to disk when emgd is stopped All queue entries are lost In EMG 1 0h the name of the file to which entries are flushed changed name from flush dat to queues dat In EMG 3 when file persistance is used messages are stored in separate files under the directory specified by the SPOOLDIR configuration option Introduced in EMG 1 0h B 1 16 NOLOGSERVER Syntax NOLOGSERVER Usually logging is handled by a separate thread However this means that there is a small delay before the event that triggers a log message occurs until it is really logged When tracking down some problems it is useful to have logging take place synchronously which is done using this keyword Introduced in EMG 2 4b B 1 17 ORPHANSSIZE Syntax ORPHANSSIZE lt integer gt Maximum number of entries in orphans queue When the maximum size is exceeded the oldest entry is discarded Default value 10000 Introduced in EMG 1 0h B 1 18 PERSISTFILES Syntax PERSISTFILES Specifies that file persistence should be used Requires that file persistence is also present in the license key See also SPOOLDIR Introduced in EMG
128. ot start with any of the characters above it is taken as a name of an incoming connector If the value of the field contains any of the characters it is considered a regular expression Outgoing connector s If more than one connector is specified fail over and optionally load balanc ing will take place for the specified connectors Extra options LB KEYWORD KEYWORDSESSION USERNAME URL or PLUGINARG LB is used to specify load balancing between the outgoing connectors KEYWORD is used for keyword based routing and specifies a source address keyword pair combination where source address and keyword can be used as wildcard Example KEYWORD BALANCE KEYWORDSESSION Specifies that keyword sessions should be used enabling routing of subsequent messages from the same sender to the same destination even if they do not contain a valid keyword USERNAME user Specifies that only specified user can receive the message over the connector to which the message is routed URL Specifies that a specific URL should be used when message is routed to a connector that uses a HTTP based protocol PLUGINARG A string that will be set as the PLUGINARG option on the message which can be used by external plugins Enterprise Messaging Gateway User s Guide 3 0 16 77 B 1 25 SERVERNAME B 1 26 SHMKEY Syntax SERVERNAME lt string gt Specifies server name as passed to MGP clients upon login For example used by the EMG SNMP
129. ource Address Translation SAT seessssss 30 5 9 Inheritance and virtual connectors esee 31 5 10 Limiting connector queue sizes essere 32 5 11 Sample configurations eese nennen 32 5 11 1 Incoming MGP supporting up to 3 connections 32 5 11 2 Incoming SMPP supporting up to 10 connections 32 5 11 3 Incoming CIMD2 supporting 1 connection 32 5 11 4 O teomg CIMDDA nain res ente i Poe 33 5 11 5 Outgoing UCP using authentication via operation 60 33 5 11 6 Outgoing UCP via modem seen 33 5 11 7 Outgoing HTTP iui ice eec tace cot broken e end 34 5 11 8 Outgoing EBE si ccs retener me teret Herrin 34 5 11 9 Outgoing GSM ns o ene tiers i tetas ed ega 34 5 11 10 Outgomg OILS neret ter tei enti tte eite 35 6 inpApE E 36 6 1 Specifying a routing criteria for a message see 36 6 2 Specifying a routing criteria for a connector 36 6 2 1 The REDIRECT kKeyword esee 36 6 3 Routing table oie be re set ab tais 37 SS Ms C 38 6 5 Load balancing reed pe rere en ertet dest 38 6 6 User based ro ting 4 ede ea blaster en Hte 38 6 7 Keyword based routing eese nennen 39 6 7 1 Sample scenario ette tee eore ta teta Fe coe baeo 39 6 7 2 Setting up
130. out Default values 10 seconds outgoing 0 no timeout incoming B 2 76 IGNOREMAXTOTALQUEUESIZE B 2 77 INHERIT Syntax IGNOREMAXTOTALQUEUESIZE Syntax INHERIT lt string gt Used to specify that connector options should be inherited from another connec tor parent A connector is only allowed to inherit from one other connector If a connector option is present for the child connector then the parent is ignored for that keyword Introduced in EMG 3 See also VIRTUAL B 2 78 INITSTRING Syntax INITSTRING lt string gt Modem initialization string AT command sequence For dial up connectors using a modem this keyword can be used to specify a command string to be sent to the modem before the AT dial command is sent B 2 79 INSTANCES Syntax INSTANCES lt integer 0 999 gt Number of instances for connector A connector can exist in zero or more instances Zero instances means the con nector is dead When a message is being sent via a connector any of the instances can be used Normally you would specify 1 to get one instance of an outgoing connector until there is a specific reason to change this Incoming connectors need to be available in more than one instance if you want to be able accept mul tiple connections simultaneously Please note that each connector instance will use two threads and that the total number of threads available in the operating system will be limited Enterprise Messaging Gateway Us
131. pient is a subscriber of an other operator domestic or foreign etc E 1 2 Receive messages If you want to receive messages addressing the message to the application EMG and being able to receive messages sent from phones with SIM cards from different operators can be problematic issues Pricing E 1 3 Type of messages Will you send plain text messages max 160 characters or will you need to send binary message with User Data Header ringtones logos etc WAP push mes sages over SMS is another type of message that requires UDH and 8 bit mes sages Possibility to send more complex messages also depends on the protocol being used When sending text messages the character set is also relevant What kind of national characters will be sent and how are they supported and handled E 1 4 Performance or message volume What kind of message volume are you calculating with This is usually mea sured in messages per second or messages per day 1 message per second equals to 86400 messages in 24 hours Pricing usually depends on volume to a high degree E 1 5 Support and service Your operator may have different service and support plans for different types of customers E 2 SMSC connection E 2 1 Type of connection Does your operator provide TCP IP dial up or X 25 connections If relevant how are incoming messages handled Who initiates the connection the ESME or the SMSC or both Are static connections allowed or should ESME d
132. ple configuration NECTOR pap lt TYPE INCOMING ADDRESS 127 0 0 1 8088 PROTOCOL PAP INSTANCES 5 ROUTE smsc R gt EDIRECT pap dlr CONNECTOR pap dlr lt TYPE OUTGOING Dummy address real address will be in DLR ADDRESS http localhost PROTOCOL PAP INSTANCES 1 gt Enterprise Messaging Gateway User s Guide 3 0 16 49 Receiving messages When a WAP push is received via PAP it will be compiled into binary form and for the outgoing SMS message the UDH parameters source port and destination port will be set This allows for the WAP push to be delivered via SMS to the recipient transparently It is possible to request that a delivery confirmation should be delivered back to a specific URL This is handled by the REDIRECT keyword and the pap dlr con nector so that any DLRs routed back to the pap connector will be redirected to the outgoing pap dlr connector and since a URL will be specified in the PAP request that URL will be used instead of the address specified on the pap dlr con nector Enterprise Messaging Gateway User s Guide 3 0 16 50 Delivery receipts DLR 9 Delivery receipts DLR 9 1 Overview Delivery receipts or DLRs as we call them are special status messages gener ated by the SMSC when the final status of a message has been reached For example if a message is sent to a phone successfully the SMSC can generate a DLR when the phone has a
133. ple sending 45 U UDH P long messages 14 PARSEMESSAGE 96 R Ringtone example sending 44 ROUTE connector keyword 36 message option 36 ROUTELOGSIZE 15 Routing concatenated messages 41 keyword based 39 96 on prefix 37 user based 38 107 Routing log defined 15 overview 15 Routing table using 37 using prefixes 37 Enterprise Messaging Gateway User s Guide 3 0 16 139
134. retry period On top of the above a connector can be put on hold which means messages are accepted in the queue but no messages are transmitted A message can be put on hold using the emgclient utility or another implementation using the MGP proto col A connector is available in O or more instances In order for the connector to be active and be able to send or receive messages it must be available in at least one instance Outgoing connectors usually only needs to be available in one instance From EMGs point of view one instance is enough to handle hundreds of messages per second However depending on delays imposed by the remote entity using more than one instance MAY increase performance Incoming connectors must be available in more than one instance in order to allow for several simultaneous connections When an incoming request has been processed and the remote entity logs out and drops the connection the instance can be re used However in some cases if the connection fails due to a network error for example it may take a while before this is detected and the session is cleared and available for use again In this case it would be an advantage to have more instances than the expected number of simultaneous connections If two incoming connections are expected maybe 5 instances would be suitable Enterprise Messaging Gateway User s Guide 3 0 16 26 Connectors 5 6 Message types 5 7 Mappings The default message typ
135. ript 40 400 mps for a Perl script and 80 800 mps for a custom binary The proprietary protocol MGP is designed for ease of use monitoring the EMG server etc and it is not intended to be used for high performance applications All other protocols CIMD2 SMPP OIS UCP EMI HTTP SMTP are capable of handling hundreds or even thousands of messages per second 13 3 Instances Each active connector can be available in one or more instances The number of instances should be kept to a minimum and in an ideal world with one system sending messages to EMG over a persistent connection and one system receiving the message one incoming and one outgoing instance would be enough However for incoming connectors you may have more than one system that needs to connect to EMG The number of instances controls how many simulta neous connections EMG can accept Also if a connection is terminated abnor mally network outage or similar the instance session may not be cleared before a new connection attempt is made Therefore the number of instances for incom ing connectors should be at least the number of expected simultaneous incoming connections plus a few spare ones If you expect one incoming connection you should allocate 5 instances Please note that there will be a limited number of threads available in the operat ing system 1024 is the default value for RedHat Linux 7 Each connector instance will use up to two threads one for reading and one
136. roduced in EMG 3 Enterprise Messaging Gateway User s Guide 3 0 16 73 B 1 11 LOGLEVEL Syntax LOGLEVEL lt string gt Specifies which information should be logged When a level is specified mes sages related to that level or higher more severe is logged INFO is most useful for ordinary production use while DEBUG can be useful to track down prob lems Errors at level WARNING and ERROR may indicate configuration problems badly formatted incoming data etc and usually require some action to be taken Values DEBUG2 Lowest level volume affects performance DEBUG Volume affects performance INFO Default level WARNING ERROR Only errors or more severe information is logged CRITICAL Default value INFO B 1 12 LOGYEAR Syntax LOGYEAR When used format for date part of timestamp in log files will be according to ISO 8601 YY YY MM DD hh mm ss mmm There are two advantages to the standard syslog format It includes year and it is easy to sort Introduced in EMG 2 5 B 1 13 MAXTOTALQUEUESIZE Syntax MAXTOTALQUEUESIZE lt integer gt When the total queue size for all connectors in EMG has exceeded this value EMG will deny further incoming messages temporarily until queue size decrease below the specified value Useful for message throttling avoiding that a large queue builds in EMG Introduced in EMG 2 5 B 1 14 NOEXPIRE Syntax NOEXPIRE Specifies that messages in queue and
137. roduced in EMG 3 0 3 B 2 154 SCAADDRTON Syntax SCAADDRTON lt integer gt Set Service Center SMSC address TON in message PDU Applies to GSM Introduced in EMG 3 0 3 B 2 155 SENDERADDRESS Syntax SENDERADDRESS lt string gt Introduced in EMG 3 B 2 156 SEPARATOR Syntax SEPARATOR lt string gt Introduced in EMG 3 B 2 157 SERVICETYPE Syntax SERVICETY PE lt string gt Defines the servicetype for SMPP submit_sm and data_sm operations Applies to SMPP Enterprise Messaging Gateway User s Guide 3 0 16 102 B 2 158 SIMULATE Syntax SIMULATE Simulate connector operation No operations are actually sent B 2 159 SMPPTZ Syntax SMPPTZ lt string gt If specified overrides any specified timezone for SMPP time fields Applies to SMPP outgoing Introduced in EMG 3 B 2 160 SOURCEADDR_GSM Syntax SOURCEADDR_GSM Indicates that alphanumeric source addresses should be GSM encoded before used in SMPP Applies to SMPP Introduced in EMG 3 B 2 161 SOURCEFULLNAME Syntax SOURCEFULLNAME lt string gt Specifies a full name to be used in From address field for SMTP Applies to SMTP Introduced in EMG 3 B 2 162 SSL Syntax SSL Specifies that Secure Socket Layer SSL should be used for the connector Introduced in EMG 2 0 B 2 163 SSL_KEYFILE Syntax SSL_KEYFILE Specifies the connector specific PEM file where key and certificate is stored for use by SSL connectors B 2 164 SSL PAS
138. s position in the file gives it highest precedence 0 smscl ucp 012 smsc2 smpp 0123 smsc3 ucp Enterprise Messaging Gateway User s Guide 3 0 16 37 Routing 6 4 Failover If more than one connector is specified in the routing table and the first connec tor fails for some reason then the next specified connector is used This mecha nism is called failover Failover occurs when a connector goes into state ERROR or DEAD and more than one connector is specified During the failover the queue for the failing connector is moved to the next working connector If there are no connectors alive at the moment then the queue entries remain in their cur rent connector queue and waits for a connector to come back to life Sample configuration in routing table smpp inl smpp outil smpp out2 6 5 Load balancing When specifying load balancing for a group of connectors the connectors will be used in a round robin manner That is the first message will be sent via the first specified connector next message via connector 2 and so on If a connector is in state ERROR or DEAD it will not be used for the load balancing until it comes back into an active state Sample configuration in routing table smpp inl smpp outl smpp out2 LB 6 6 User based routing Routing can be done based on authenticated user by using the ROUTE or ROUTING keywords in the users file If specified it will override any other routes specified for the connector or i
139. s via e mail support nordicmessaging se Make sure you include a detailed problem description your license or serial number and detailed contact information If you want us to call you make sure you indicate your geographical location and time zone Nordic Messaging Technologies is located in Stockholm Sweden CET Enterprise Messaging Gateway User s Guide 3 0 16 17 Installing or upgrading EMG 3 Installing or upgrading EMG EMG installation upgrade process includes several steps Download software Get license key Install software Configure software Start server oo00 3 1 Before installing EMG We recommend starting out by applying relevant patches to your operating sys tem This particularly applies to Sun Solaris We recommend applying Sun s most current Recommended Patch Clusters for your Solaris version Sun patches are available from http sunsolve sun com To list installed patches in Solaris use showrev p 3 2 Download software Software can be downloaded from http www nordicmessaging se download You can choose either to download a full distribution or a binaries only distribu tion When installing EMG for the first time you need to download the full distri bution However when upgrading the binaries only distribution is enough unless you want new versions of the configuration files New configuration files are not necessary since EMG is backwards compatible with earlier releases 3 3
140. se mod 256 on transaction number Enterprise Messaging Gateway User s Guide 3 0 16 131 Concatenated messages Never convert from UCS2 to IA5 even if one part will fit since this will corrupt message Concatenated messages Ensure we do not split a message in the middle of a multi byte character AUTOWAPPUSH_IN now supports a text in addition to the URL The first URL found in the message will be extracted and the rest of the message used as the text Do not update routelog table with NULL values Bodies for large messages was not removed when using message persistence F 6 EMG 3 0 11 9982 Minor release 0 9 0 O CIMD2 TAB is not allowed in usernames HTTP HTTP status 406 was incorrectly sent for messages with empty mes sage body MGP QPRIORITY can now be set by ADMIN users SMPP Added support for parsing of Comverse DLR format SMPP Field data_coding was not always set correctly SMPP Fix for handling of messages longer than 255 bytes SMTP E mails with leading space in message body was not handled cor rectly SMTP Functionality for compressing a Unicode message into GSM IAS if t fits improved SMTP QUOTEDSUBJECT was not handled correctly UCP is not allowed in usernames UCP Ensure correct length is used for billingid max 20 chars smtpload More than 10 threads was not handled UDH calculation could sometimes be incorrect for long messages if concat attributes already pr
141. stalling or upgrading EMG The configuration file is placed in etc emg and named server cfg he EMG server emgd can be started with emgd Check the file etc emg README for more information 3 4 2 Binaries only The easiest way to upgrade an existing EMG software installation is to use the binaries only distribution Since EMG is backwards compatible with earlier ver sions no configuration changes should be needed unless new functionality needs to be accessed The upgrade procedure is as follows Log on to your system as the system administrator or the EMG user Find your current EMG binaries for example emgd They are usually located in usr bin You can also execute type emgd which will locate the binary if it is in your current path Download the patch release tar archive in this example we use emg25 solaris binaries tar gz and save it in the file system under tmp or similar Uncompress the archive gzip d tmp emg30 solaris binaries tar gz Stop emgd emgd stop and then make sure there are no emgd processes run ning ps ef grep emgd All emgd processes need to be stopped before replac ing the binaries Backup your current binaries in order to be able to revert to these files if needed Sample backup procedure mkdir tmp emg backup 020501 cp usr bin emg tmp emg backup 041030 Extract the new binaries cd usr bin tar xvf tmp emg30 solaris binaries tar Ma
142. t port number gt Use specified port when connecting to server username lt username gt Username for server authentication password lt password gt Password for server authentication Enterprise Messaging Gateway User s Guide 3 0 16 65 A 2 emgd The EMG server When the server is stopped all connector queues are flushed to file In EMG 1 0h and later this file is named EMGDIR queues dat in earlier versions EMGDIR flush dat Also the routing log is flushed to disk as EMGDIR routelog dat In EMG 3 when using the persistence option all messages DLRs and SAT entries are persisted in the spool directory specified by general option SPOOLDIR which defaults to var spool emg Options debug Set log level to DEBUG and display information on stdout debug2 Set log level to DEBUG2 even more debug info and display information on stdout fg Run in foreground do not detach from tty hostid Display hostid as emgd reads it refresh Refresh running server reload Refresh running server without terminating current sessions stop Stop running server threadcount Count the number of threads can can be created This gives a hint on the total maximum number of instances the EMG server can handle since each connector instance requires 1 or 2 threads depending on protocol used upgradedb Upgrade the database schema If the number of records are large this may take several hours when altering existing ta
143. te way Usually the job of EMG is to relay messages performing message conversion and translation depending on the connectors used to receive and send the mes sage Enterprise Messaging Gateway licensing is based on number of messages per second per server More specifically it is the total number of messages that all incoming connectors server wide will accept per second If for example there are two incoming connectors in a system licensed for 30 messages per second and they are fed with 20 messages per second each the EMG server will impose a small delay so that in practice the connectors will process on average 15 mes sages per second each EMG is also licensed per server so that one license permits installation of EMG on one specific server The license is generated for a specific server identity hostid For Solaris systems this equals to the output from the command hostid and for Linux it is the MAC or hardware address for the first network adapter in the system interface eth0 There is no license related limitation as to how many connectors can be defined or how many clients or SMSC connections an EMG server can handle One server can handle multiple client and SMSC connections using different proto cols In order to be able to move a license from one server to another a new license needs to be generated by Nordic Messaging Technologies AB or one of its repre sentatives The message is the most important entity in EMG
144. te tee o e ute TE eo e ET ERR che erras Ugo 17 3 Installing or upgrading EMG esee 18 3 1 Before 1nstallmg BMQ tede eet tr tte ertet 18 3 2 Download software essere nne 18 3 5 Get licetise Key nec ttp I e e eee aee uu e deae 18 3 4 Install sOftWare iier eie e eee ra needed ee iet nee e de 18 3 4 1 Full distribution 5 ice Lett eniti eta 18 3 4 2 Brnaries only is iu i eie ak eee i Peer te eR ee Diener dn 20 3 5 Configure sO LWAare auc iiti eec e ehe ed E ede eee Un aae ena 21 3 6 Starting stopping and refreshing the server sse 21 3 7 PersistenCe LP 21 A COMMPULAU OM X M M 23 4 1 General rene pectet ree ne Padi tm ioris 23 4 2 Retreshimg the Servet eue e aee tete aere sao dpa 23 4 3 Testing a configuration secsec eronneen es naaien 23 De COMMECIONS HT 25 SA Connector types conet bee rot Prieto seio 25 5 2 Connector modes eiecti Ee die ed eR aep Ede 25 2 3 Static VS NOMASLALIC iius veneree aeiaaeeo sd ere terea tee HERR eia verde 25 5 4 Connectot states ainicin Doc He ka eisiaa 26 DD MSTA COS eo deed eee e nete sae eet Role Ho o ir Pee tr s te end debe e pe eeu ve 26 5 6 MESSABE TYPES RT 27 REINIETD DICE 27 5 8 Address rewritimng n niii ene a best deni esi on ecd 28 5 9 1 Masquerading eiie etre otro er e egeo de 29 Enterprise Messaging Gateway User s Guide 3 0 16 5 8 2 S
145. ter message operation is sent MSGDELAY 20 Operator only allows us to send 2 messages per session OPS MAXPERSESSION 2 If message does not contain a source address use this DEFAULT SOURCEADDR 7654321 gt 5 11 7 Outgoing HTTP CONNECTOR httpl lt TYPE OUTGOING PROTOCOL HTTP We use full URL for HTTP ADDRESS http www myhost com cgi bin handlemessage sh One instance is enough INSTANCES 1 Timeout after 5 seconds idle IDLETIMEOUT 5 gt 5 11 8 Outgoing EBE CONNECTOR ebel lt TYPE OUTGOING PROTOCOL EBE Program or script to execute ADDRESS usr local bin ebe handlesms sh One instance is enough if more we need program to be thread safe INSTANCES 1 gt 5 11 9 Outgoing GSM CONNECTOR gsml lt GSM connectors are always outgoing YPE OUTGOING PROTOCOL GSM TTY to which GSM device is attached MODEM cua a Only one instance is allowed INSTANCES 1 Poll for incoming messages every 30 seconds POLLRECEIVE 30 No SCA in PDU needed for some GSM devices GSMNOSCA Memory storage is used Ericsson devices GSMS TORE ME gt Enterprise Messaging Gateway User s Guide 3 0 16 34 Connectors 5 11 10 Outgoing OIS CONNECTOR oisl lt TYPE OUTGOING PROTOCOL OIS ADDRESS 10 0 0 1 5480 Only one instance is allowed INSTANCES 1 gt
146. terre Pe eee RR PAR e Uhr odes 108 B 2 184 V ASPID inet derent ee Pads Peace 108 B 2 185 VIRTUAL iere rette RR rn tae aee x ERE an 108 B 2 186 WAITBEFORECONNECT eee 108 B 2 187 WAITDEBLAY retten tnnt eot 108 B 2 188 WALITPOR erret rre Hr Pte ep ene Ret ERR rt 108 B 2 189 WHITELIST icti trt enne tete e tea en 108 B 2 190 X AU TH Lernen tet ehe n ero ei rehenes 109 B 2 191 XAUTHPASSWORD eeeeeeeeeee ettet netten hene 109 B 2 192 XAUTHUSERNAME cerent eene 109 B 2 193 XPASS WORD tenerte rrt ere tie tiep a ione 109 B 2 194 XUSERNAME eeseeeeeeeenetee etre nnne teeth tnn nen 109 B 3 DB optons eaten ate cesset ettet eoe Cooke ede pe Co eben de 109 B3 BS U 110 B 3 2 HOST seine tiit ten vnde editio ee 110 B 3 3 INSTANCES errijetan ee teo rn epo bo e ip ie abesine 110 B 3 4 PASSWORD rete et ER HER HR EHE eiis 110 BIROR T erronee a a S 110 B30 VY ed EE 110 B37 USERNAME idees eee ln er e ep sdeetpienteteonaae 110 BASAT pool options eeeeceeseee esee nennen ener e oinari 111 B 4 1 ADDRESSRANGE 4 eeeseesseseeeeene treten ennt tn nennen 111 B42 EXPIRE nran repr een hene Fon re ERR Re E REKEN 111 B 4 3 QUOTEDREBEPLY eerte tt t e mid inen eR at 111 BALA THREADED etic ince cascade eie ern et err e madden 111 B S Domain options inii nito a ee en a d en Wee edes 111 B 5 1 MAILSPERMINUTE
147. the connectors 0 0 elec seen 39 6 7 3 Setting up the routing table oo ee eene 40 6 7 4 Keyword sesSiOns eie i eet intrent er hine rerba ees 40 6 8 Concatenated Message Routing CMR sse 41 T7 Sending messages shes sadvessinSutecnssedesaveserelovesssiecasattaredsannuehs desertae eoa dag uda 42 7 Using HTTP connector eseeeeeeeseeeeeeeeeeeeen rennen 42 7 2 Using SM TP COBneGCtOE iecit rete tot te Ir eor erattu 42 7 2 1 Sample outgoing SMTP session eee 43 7 3 Using EBE CORBneCLOE on eet er brote pag eros e pde et ou 43 TA Using emesend aos Siena E dad necp tio Ee RNA 44 7 5 Using empclient uiii eher eer ep aiii 45 fs inp NET 45 8 Receiving messages 4 eee ces back is b st bee aH PUR HER epe b DL HERR ER ud 47 8 1 Using HTTP connector eenoeeee tert nte eet iter iaa 47 8 2 Using SMTP conn ctor eterne eerie tei d the reed ica 47 8 2 1 Sample incoming SMTP session eene 48 8 2 2 Preventing SMTP relaying eee 49 8 3 Receiving WAP push via PAP ene 49 9 Dehivery receipts DER iiaito fitit eei os te eadelinscens 51 PNG au ES 51 9 2 Requesting a DER aede rien hece 51 9 2 1 Using emipsetid 2 erre t pete rte ee eere ran 51 9 2 2 Using connector keyword esee 51 9 3 Routing DERS uite e eae aieiai 52 9 4 DLRs and buffered status eee eeseess
148. to be used for the second argument to create_config Usually it is the name of the configuration file to be used by the plugin B 6 2 INSTANCES Syntax INSTANCES lt integer gt The number of threads to be used If the plugin functions are not thread safe set this to 1 which will make all calls serialized B 6 3 LIBRARY Syntax LIBRARY lt string gt The name of the shared library that implements the plugin B 6 4 OFFSET Syntax OFFSET lt integer gt Offset for numeric result and error codes For result codes the specified value will be added and for error codes 2 x the value will be added Enterprise Messaging Gateway User s Guide 3 0 16 113 C MGP options The following options can be used with messages The option name is given fol lowed by its numeric value The numeric value is used in log files etc Some options only applies to certain protocols These options are simply ignored by protocols which do not support them All numeric key values that are not used are reserved for future use User Data Header UDH options can be supplied in two ways Some can be supplied by setting the corresponding MGP options DESTPORT for example It is also possible to include the UDH in the actual message data and set the User Data Header Indicator UDHD Enterprise Messaging Gateway User s Guide 3 0 16 114 C 1 Option keys in numeric order
149. ts incoming messages via the connector Out going messages are not affected by the ROUTE keyword since a routing decision has already been made prior to the message being sent via the outgoing connec tor 6 2 1 The REDIRECT keyword Some connectors can only send or received messages uni directional such as SMPP 3 3 or HTTP connectors for example Say that a DLR is routed back to a HTTP receive only connector because the original message was received there the DLR would stay in the queue forever or until it expires To solve this prob lem it is possible to specify a REDIRECT keyword on the connector meaning that any message routed to the connector will be redirected to the connector specified by REDIRECT instead Enterprise Messaging Gateway User s Guide 3 0 16 36 Routing 6 3 Routing table The routing table is loaded from the file pointed to by the ROUTING keyword in the server configuration file The format of this file is 2 or 3 tab separated fields per row lt name of incoming connector gt lt TAB gt lt name of outgoing connector s lt TAB gt lt options gt Comma is used to separate entries when there is more than one entry per field The options field is optional and the options currently recognized are LB Load Balancing KEYWORD see Keyword based routing below KEY WORDSESSION USERNAME URL and PLUGINARG Example smpp inl smscl ucp smpp in2 smsc2 smpp smsc3 smpp mgpl sms
150. used as follows For MGP connectors ADMIN User is administrator CLIENTCONFIG lt string gt String will be sent to client and can be used to affect client configuration from the server side The client does not need to respect this field Enterprise Messaging Gateway User s Guide 3 0 16 106 For all connectors FORCE_SOURCEADDR_IN lt string gt Force the source address for all messages to the specified address MAXSESSIONS lt integer gt Limit maximum number of session for the specific user ROUTE lt string connector name gt Specify a connector that is the default route for the user Used for user based routing ROUTEDLR lt string connector name gt Specify a connector to which to route DLRs requested by the user ROUTESAT lt string connector name gt Specify a connector to which to route messages after a successful SAT lookup has been performeda ROUTING lt filename gt Specify a file containing a user specific routing table Used for user based routing SATPOOL_CREATE lt string SAT pool name gt Use specified SAT pool for messages received THROUGHPUT lt integer gt Limit throughput for the specific user Applies to All protocols incoming B 2 181 USESENDER Syntax USESENDER Indicates that the message sender should be used as part of the message The sender will be inserted before the message subject and body Applies to SMTP incoming Introduced in EMG 3 B 2 182 USESUBJEC
151. variable EMGLOGDIR did not work properly Use of MAXSESSIONS in users file could cause deadlock Eliminated potential buffer overflow in UDH parsing Users connecting and then disconnecting without logging in could cause thread to be left hanging DCS value for IA5 message was sometimes set to 1 instead of 0 SMTP FORCE CHARCODE UCS2 would cause server to crash UCP MT ALERT RESP was incorrectly decoded pushtohex WAP opaque data was not correctly encoded F 11 EMG 3 0 6 8403 Minor release 6 MIME Handle UTF 8 in MIME trees properly CIMD2 Protocolid was not respected SMPP Potential buffer overflow when parsing pdu SMPP Send error invalid command length on invalid pdu length Enterprise Messaging Gateway User s Guide 3 0 16 134 oo0000 9 O0 O O000000 0 000000 0909 9 O6 SMPP Reject unsupported operations SMPP Handle generic nack properly SMPP Added support for vendor specific optional parameters UCP Potential buffer overflow when parsing pdu UCP Protocolid was not respected MM1 Potential null pointer problem fixed MM I Use sender timestamp for date field MM1 Force read reply and delivery report to false if message class auto MM7 Handle env Client as a generic client error MMT Duplicate lt Priority gt tags was sometimes sent MM T7 Use transid 0 in reply if transid is missing in request MM T7 5xx responses was not handled correctly emgclient d
152. would be used in the roamer cfg file Example DBPROFILE emg 12 2 Using the database 12 2 1 Putting the message route log in a database By adding the keyword ROUTELOGDB all necessary information about a mes sage will be stored in the routelog table in the database Together with the actual message contents which is stored in the messagebody table all informa tion for tracking as well as billing messages should be readily available Numerous improvements of the routelog table has been made for official release of EMG 3 0 8 which implements EMG schema version 18 12 2 2 Putting the connector log in a database By adding the keyword CONNECTORLOGDB all connector events that are written into the connector log files are also stored in the database For each mes sage received by EMG and sent out there will be two corresponding entries in the connectorlog one for each event receive and send 12 2 3 User authentication from database By using the keyword USERDB instead of USERS on a connector the user infor mation will be read from the specified database profile User information are read from two tables emguser and emguseraccess Sample configuration parts of configuration omitted DBPROFILE emg DB emg gt CONNECTOR smpp inl lt USERDB emg gt Minimum content in database Enterprise Messaging Gateway User s Guide 3 0 16 60 Database support INSERT INTO emguser username
153. yntax DESTFULLNAME lt string gt Specifies a default full name for destination address Applies to SMTP outgoing B 2 38 DLR ERR HEX Syntax DLR ERR HEX Treat the error code err in SMPP delivery receipts as a hex value Applies both sent and received delivery reports Enterprise Messaging Gateway User s Guide 3 0 16 84 B 2 39 DLREXPIRES Syntax DLREXPIRES lt integer gt Specifies the time in seconds before a DLR entry expires Default 86400 24 hours B 2 40 DLR_EXPIRES STATUS Syntax DLR_EXPIRES_STATUS lt string gt Specifies the status to be set for messages when their corresponding DLR entry expires Allowed values UNKNOWN DELIVERED INPROCESS FAILED DELETED EXPIRED REJECTED CANCELED QUEUED ORPHANED RELAYED Default UNKNOWN B 2 41 DLRIGNOREKEYWORD Syntax DLRIGNOREKEYWORD B 2 42 DLRMINMATCHLENGTH Syntax DLRMINMATCHLENGTH lt integer gt Minimum number of characters of address starting from end that must match when matching DLRs Default value 3 Introduced in EMG 2 5b B 2 43 DOMAIN Syntax DOMAIN lt string gt If an address does not contain a domain part when being sent out over an SMTP connector the specified domain name is added Applies to SMTP outgoing B 2 44 FAILOVER Syntax FAILOVER lt string gt Specifies an alternate connector to use if an error is received for a specific mes sage in response to the submit operation The mess

Enterprise Messaging Gateway - User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents