wIQ

For Software Release 1.7

User Manual

wIQ
For Software Release 1.7

User Manual

UserManualVersion1.6forSoftwareRelease1.7

Copyright2005byORGASystemsenablingservicesGmbH Thesoftware,hardwareandmanualsdescribedhereandalltheirconstituentpartsareprotectedbycopyright.WithouttheexpresspermissionofORGASystemsenablingservicesGmbH,anyformofusewhichgoesbeyondthenarrowboundsprescribedbycopyrightlegislation isprohibitedandliabletoprosecution.Thisparticularlyappliestoduplication,copying,translation,processing,evaluation,publishing,andstoringand/orprocessinginanelectronicsystem. Specificationsanddatamaybechangedwithoutnotice.Weoffernoguaranteethatthisdocumentationiscorrectand/orcomplete.Thecompanyassumesnoliabilityfordamages,direct orconsequential,whichmayresultfromtheuseofthedescribedand/orsuppliedprogram material. Mostofthenamesofhardwareandsoftwareproductsmentionedinthisdocumentationare registeredtrademarksandassucharesubjecttotheusualstatutoryprovisions. TheZendEngineLicense,version0.92 Copyright1998-2000ZendTechnologiesLtd. ThisproductincludessoftwaredevelopedbytheApacheSoftwareFoundation (http://www.apache.org/). Copyright2000TheApacheSoftwareFoundation.Allrightsreserved. Copyright2000ThePHPDevelopmentTeam.Allrightsreserved. Copyright1994-2000WorldWideWebConsortium,(MassachusettsInstituteofTechnology,InstitutNationaldeRechercheenInformatiqueetenAutomatique,KeioUniversity).All RightsReserved.ThisprogramisdistributedunderW3CsSoftwareIntellectualPropertyLicense.Thisprogramisdistributedinthehopethatitwillbeuseful,butWITHOUTANYWARRANTY;withouteventheimpliedwarrantyofMERCHANTABILITYorFITNESSFORA PARTICULARPURPOSE.SeeW3CLicensehttp://www.w3org/Consortium/Legal/formoredetails. Copyright1995CERN.ThisproductincludescomputersoftwarecreatedandmadeavailablebyCERN.Thisacknowledgementshallbementionedinfullinanyproductwhichincludes theCERNcomputersoftwareincludedhereinorpartsthereof. libxml2License,Version2.4.21:Copyright(C)1998-2002DanielVeillard.AllRightsReserved.

wIQ
Introduction System Description Databases Configuration The Router Additional Features SNMP Appendix Index

1 2 3 4 5 6 7 A I

Contents

Introduction ..................................................................... 1
1.1 Conventions .................................................................................1 1.2 AbbreviationList ...........................................................................3

System Description .......................................................... 7

2.1 SystemOverview ..........................................................................7 2.2 DescriptionofthewIQProcess....................................................11 2.3 ExternalRequirements ................................................................11 2.4 HTMLtoUSSD/SMSConversion..................................................12
2.4.1 wIQ-specificTags ................................................................... 15 2.4.1.1 Values/Attributes .......................................................... 15

2.5 UsingUSSD ................................................................................18

2.5.1 SubscribersInputInterface.................................................... 18 2.5.1.1 SubscribersFirstLogin(Self-registration)......................... 18 2.5.1.2 CallawIQService ........................................................... 21 2.5.1.3 BrowsinginanOpenSession .......................................... 25 2.5.1.4 ControlledPreinputProcessing........................................ 28 2.5.1.5 SessionEnd..................................................................... 29

2.6 UsingSMS ..................................................................................30

2.6.1 SubscribersFirstLogin........................................................... 30 2.6.1.1 CallawIQService ........................................................... 30 2.6.2 SupportedTypesofSMS ........................................................ 32

Contents 2.7 Push ...........................................................................................33 2.8 HTMLInputFormats ...................................................................33 2.9 SubscribersIdentityDirectlytoURLs ...........................................33 2.10 FastAccesstoURLwithDirectParameterPassing........................34 2.11 HTMLConversiontoMobilePhone-SpecificCharacterSet ..........34 2.12 Constraints .................................................................................34 2.13 MultipleLanguageReport...........................................................35
2.13.1 PreferredLanguageSetintheSubscriberDatabase ................ 35

Databases ...................................................................... 37
3.1 SubscriberDatabase ..................................................................37
3.1.1 Interfaces............................................................................... 37 3.1.1 PHP-Interfaces................................................................. 37 3.1.1 CommandlineInterfacesandDatabaseTools .................. 41

3.2 Group-SpecificUSSDtoURLMappingandValidURL ..................46

3.2.1 3.2.2 BriefDescription .................................................................... 46 HowtoAssignaSubscribertoaGroup.................................. 46

Configuration................................................................. 49
4.1 StartandStopProcedure ............................................................49
4.1.1 4.1.2 4.1.3 4.1.4 4.1.5 wIQd..................................................................................... 49 wIQdProcessTable ................................................................ 50 wIQd.cfg ............................................................................... 51 Failover.................................................................................. 53 Processtable........................................................................... 60

4.2 Logging ......................................................................................61 4.3 wIQInternal................................................................................64

4.3.1 4.3.2 CommandlineOptions........................................................... 64 SignalHandling ..................................................................... 65

4.4 EnvironmentVariables ................................................................65

ii

Contents 4.5 wIQ:ConfigurationFiles .............................................................65

4.5.1 Interface_{processname}.cfg:wIQConfigurationFile Variables 66 4.5.2 wIQ.cfg:wIQConfigurationFileVariables .............................. 67 4.5.2.1 License........................................................................... 67

4.6 ConfigurationFiles......................................................................76
4.6.1 4.6.2 4.6.3 Ussd2URL.cfg*: USSDtoURLMappingTable ..................... 78 Solution................................................................................. 80 ValidURL.cfg*: ValidURLandVariableInclusionTable......... 84

4.7 SMS2Service.cfg*:SMStoServiceMappingTable .....................90 4.8 URL2SMS.cfg*:URLtoSMSInterfaceMapping.........................93

4.8.1 USSDSessionActionafteraSMSisRequested....................... 96

4.9 DBDefaults.cfg:MSISDN-DependentDatabaseDefaultsTable ...97 4.10 ProviderMap.cfg .......................................................................100 4.11 wIQ2opsc_in.cfg.......................................................................100 4.12 LicenseFile ...............................................................................100 4.13 HotKeySet.cfg: ConfigurationFileforCharacterSets................102

The Router.................................................................... 105

5.1 DriverTypes,Services,andRoutingAlgorithm ...........................106
5.1.1 5.1.2 5.1.3 5.2.1 5.2.2 5.2.3 5.2.4 5.2.5 DriverType........................................................................... 106 Service................................................................................. 107 RoutingAlgorithm ............................................................... 107 ProgramName .................................................................... 107 CommandLineOptions ....................................................... 108 RegularTermination............................................................. 108 Enable/DisableDEBUGInformation ...................................... 108 License ............................................................................... 108

5.2 GeneralInformation .................................................................107

5.3 ConfigurationData...................................................................108
5.3.1 OverviewoftheConfigurationFiles: .................................... 109 5.3.1.1 ConfiguringtheConnections ........................................ 109

iii

Contents
5.3.1.2 ConfiguringtheRoutingAlgorithms.............................. 109 5.3.2 FileRouter.cfg...................................................................... 110 5.3.3 FileDriver_<PATTERN>.cfg ................................................... 112 5.3.4 FilewIQ_<PATTERN>.cfg...................................................... 114 5.3.5 FilewIQRoutingAlgorithm.cfg .............................................. 115 5.3.6 FilesDriver<Pattern>_RoutingAlgorithm.cfg......................... 116

Additional Features ..................................................... 119

6.1 Billing ......................................................................................119
6.1.1 Introduction......................................................................... 119 6.1.1.1 BillingMechanism ......................................................... 120 6.1.2 Modules .............................................................................. 121 6.1.2.1 SecureHTTP.................................................................. 121 6.1.2.2 PriceTag ....................................................................... 121 6.1.2.3 ProviderList/ProviderMap.cfg ........................................ 121 6.1.2.4 INBillingConfiguration/wIQ2opsc_in.cfg ...................... 122 6.1.2.5 Billing ........................................................................... 123 6.1.2.6 BillingScenariosforPush............................................... 127 6.1.2.7 BillingofRegularESMS ................................................. 128 6.1.2.8 BillingofLongESMS ..................................................... 129 6.1.2.9 DifferentBillingTypes ................................................... 129 6.1.3 Licensing ............................................................................. 138 6.1.4 Example............................................................................... 138

6.2 PushInterface..........................................................................140
6.2.1 GeneralArchitecture............................................................ 140 6.2.2 Push-requestandResponse ................................................. 141 6.2.2.1 Push-request ................................................................. 142 6.2.2.2 Push-response............................................................... 143 6.2.3 wIQpushProcess.................................................................. 146 6.2.3.1 License.......................................................................... 146 6.2.3.2 ConfigurationFile ......................................................... 146 6.2.3.3 Startup ......................................................................... 150 6.2.3.4 Signals .......................................................................... 151 6.2.3.5 ConfigurationReload .................................................... 151 6.2.3.6 Termination .................................................................. 151 6.2.3.7 ExitCodes..................................................................... 152

iv

Contents
6.2.3.8 Logging ........................................................................ 152 6.2.4 UseCases ............................................................................ 153 6.2.4.1 ClientAbortsRequest ................................................... 153 6.2.4.2 ConnectionFailure ........................................................ 153 6.2.4.3 WebServerTimeout...................................................... 153 6.2.4.4 RequestTimeout ........................................................... 153 6.2.4.5 wIQCoreReportsStatus ............................................... 153 6.2.5 RemarkonBilling................................................................. 154

6.3 SMSCenterInterfaces ..............................................................155

6.3.1 General ............................................................................... 155 6.3.1.1 CURRYProtocol ............................................................ 156 6.3.1.2 OMBmanager ............................................................... 157 6.3.1.3 ProgramName.............................................................. 157 6.3.1.4 General......................................................................... 157 6.3.1.5 Signals .......................................................................... 157 6.3.1.6 CommandLineOptions ............................................... 158 6.3.2 DriverConfiguration ............................................................ 158 6.3.2.1 OMBmgrConfiguration ............................................... 161 6.3.3 SMSCClient ........................................................................ 162 6.3.3.1 ProcessInvocation......................................................... 162 6.3.3.2 Signals .......................................................................... 163 6.3.3.3 Configuration ............................................................... 164

6.4 SMSServices.............................................................................177
6.4.1 SessionSettingsfromHTMLContent ................................... 177 6.4.2 UseCases ............................................................................ 177 6.4.2.1 PushtoUSSDDisplay .................................................... 177 6.4.2.2 PushtoUSSDPromptwithImmediateAnswer .............. 178 6.4.2.3 PushtoUSSDPromptwithLateAnswer ........................ 178 6.4.2.4 PushtoSMS ................................................................. 180 6.4.2.5 PushtoFINISH-SMS ...................................................... 181 6.4.2.6 LicenseAdditions .......................................................... 182 6.4.3 LoadDistribution(Push/SMS/USSD)................................. 182

6.5 wIQEnhancedSMS ..................................................................183

6.5.1 Overview ............................................................................. 185 6.5.1.1 FirstOctetofaSUBMIT-TPDU........................................ 185 6.5.2 wIQHTMLLanguageExtension............................................ 189 6.5.2.1 UserData-specificTags ................................................. 196 6.5.2.2 ESMSHTMLTagProcessingRules.................................. 198

Contents
6.5.3 wIQPush .............................................................................. 199 6.5.3.1 HTTPInterfaceExtension ............................................... 199 6.5.4 Examples ............................................................................. 201 6.5.4.1 ExampleofaRingtoneESMS......................................... 201 6.5.4.2 ExampleofaTextESMS ................................................ 203 6.5.4.3 ExampleofaBinarySMS............................................... 204 6.5.4.4 ExampleofaPictureSMS.............................................. 205

6.6 ORGANSGDriver .....................................................................207

6.6.1 6.6.2 6.6.3 Signals................................................................................. 207 CommandLineOptions ....................................................... 208 DriverConfiguration ............................................................ 208

SNMP ............................................................................ 211

7.1 SNMPTrapConfiguration .........................................................212
7.1.1 7.1.2 7.2.1 7.2.2 7.2.3 OLSTRAP ............................................................................ 212 ConfigurationoftheSNMPAgent ....................................... 213 wIQd/wIQguard ................................................................. 218 wIQ ..................................................................................... 221 Router ................................................................................. 223

7.2 SNMPSupportinwIQProcesses................................................218

Appendix ...................................................................... 225

A.1 SupportedCharactersfromtheGSM-DefaultAlphabet.............225 A.2 MappingfromHTML3.2toUSSD/SMS .....................................226 A.3 Changes ...................................................................................230
A.3.1 A.3.2 A.3.3 A.3.4 A.3.5 A.3.6 A.3.7 NewFeaturesforwIQ1.0 .................................................... 230 NewFeaturesforwIQ1.1 .................................................... 231 NewFeaturesforwIQ1.2 .................................................... 231 NewFeaturesforwIQ1.3 .................................................... 231 NewFeaturesforwIQ1.4 .................................................... 232 NewFeaturesforwIQ1.5 .................................................... 232 NewFeaturesforwIQ1.6 .................................................... 232

vi

Contents
A.3.8 NewFeaturesforwIQ1.7 .................................................... 232

A.4 HTMLPagesforKeytableConfiguration....................................232 A.5 UseofthewIQWebInterface ...................................................234

A.5.1 wIQAdministrationInterface ............................................... 235 A.5.1.1 LimitedSubscriberDatabaseInterface ........................... 235 A.5.1.2 CompleteSubscriberDatabaseInterface ....................... 235 A.5.1.3 IncoreInterface ............................................................. 235 A.5.1.4 IncoreManualPage ...................................................... 236 A.5.2 Read-OnlySubscriberDatabaseInterface ............................. 236 A.5.3 PHPInformation .................................................................. 236

A.6 SystemActivityReporter ...........................................................236 A.7 BackupandRestoreoftheSunSolarisOperatingSystem ..........237

A.7.1 IntroductiontoBackupandRestore ..................................... 238 A.7.2 InstallingandUsingaTapeDrive.......................................... 239 A.7.2.1 InstallingaSunStorEdgeTapeDrive.............................. 239 A.7.2.2 UsingaTapeDrive ........................................................ 240 A.7.3 Usingufsdumpandufsrestore ............................................. 241 A.7.3.1 IntroductiontotheufsdumpCommand ........................ 241 A.7.3.2 IntroductiontotheufsrestoreCommand ...................... 241 A.7.3.3 BackingupSeveralFileSystemsonaSingleTape .......... 242 A.7.4 SavingandRestoringPartitioningInformation...................... 244 A.7.5 RestoringtheWorldWideNumber(WWN) .......................... 245 A.7.6 CreatingaBackupoftheSystemsRoot(/)Partition ............. 246 A.7.7 RestoringtheSystemsRootPartition ................................... 247 A.7.8 Restoringotherimportantsystempartitions(/usr,/var/,...) ... 249 A.7.9 Restoringnormal(User)Partitions ...................................... 249 A.7.10 ANoteConcerning/tmp...................................................... 249 A.7.11 BackingUpandRestoringofRAIDMetadevices ................... 249 A.7.11.1 TroubleshootingMetadevices........................................ 250 A.7.11.2 RecoveringtheDiskSuiteConfiguration......................... 250 A.7.11.3 HowtoUsethemd.cfFiletoRecoveraDiskSuite Configuration251 A.7.12 BackingupandRestoringaSystemStepbyStep ................. 252 A.7.13 Requirements ...................................................................... 252 A.7.14 CreatingaFullSystemBackupIncludingtheRootFileSystem253 A.7.15 RestoringthePrimaryHardDrive ......................................... 255

vii

Contents
A.7.16 RestoringtheMirror ............................................................ 257 A.7.17 RestoringtheSysteminGeneral .......................................... 260

A.8 HowtoShutDownorRebootaSystemProperly.......................260 A.9 ApacheWebServer ..................................................................261 A.10 RegularExpression ....................................................................262 A.11 Settingof$RANDFILE .............................................................262 A.12 ORGAAlarmDefinitions ...........................................................263
A.12.1 ORGASNMPMIBDefinitions ............................................... 263 A.12.1.1 OLS-CommonAlarmTrap.mib ........................................ 263 A.12.1.2 OLS-CommonAlarmDefinitions.mib............................... 265 A.12.2 ListOfEventIds ................................................................... 270 A.12.2.1 TrapDefinitions ............................................................ 270

A.13 Bibliography .............................................................................272

Index............................................................................. 273

viii

Introduction

1
1 2 3 4 5 6 7 A I

ThewIQ makesWebcontent(HTML)availabletoUSSD-capablemobile phones.USSDisafeatureoftheGSMnetwork. wIQmakesevenHTMLcontentavailableviaSMSandoffersaWebinterface forinitiatingmessages(overUSSDorSMS)fromthewIQtoasubscriber. WithwIQ,networkoperatorscanofferservicestotheirsubscribers,whichallowstogainaccesstoWebcontentvianon-WAP(WirelessApplicationProtocol)andnon-SAT(SIMApplicationToolkit)capablephonesinaneasy,fast andconvenientway. ThemainadvantagesoftheUSSDserviceagainstWAPandSATare: Veryfastconnectionsetup NoWAPorSIMToolkitcapabilitiesofthephonesrequired Easywayofimplementationofthenewservicesforthenetworkoperator

1.1

Conventions
Thefollowingnotationalconventionsareusedinthismanual: Textsprecededbythissymbolarepartsofalist. Textsenclosedbyquotationmarksarereferencestootherchaptersorsections. 1.) Textsprecededbyanumberdescribeactivitiesthatyoumustperformin theorderindicated.

Introduction Textfollowingthismarkershouldbeheededinordertoavoiderrors. Textfollowingthismarkerrepresentsgeneralinformationthat shouldsimplifytheinstallationprocessandavoidincorrectinstallation.

BUTTON <...> File Process

Pushbuttonsandcontrolboxes Stringwildcard Directorystructureorfile Processesandcommands

1 2 3 4 5 6 7 A I

Formats ...;* Wildcard*permittedasanentry Telephonekey Telephonekey SendbuttonoftheMS DateandtimeinISOformat(YYYYMMDDhhmmss) Theentryisoptional Entryfieldsinthemenudescriptionswithoutthisformatdefinitionaremandatory. Listofalternativeoptions Regularexpression . standsforanycharacter .* standsforanynumberofcharacter ^ muststartwiththefollowingcharacter $ indicatestheend [n-m] specificationofrange

* # S
d/t [...]

{...} ...;RE

Introduction Example: ^013.* ^018[1-3]$ ^019[2-4]5$ BCD[...] boolean n[...] c[...] h[...] ...[n...m] i l Binarycodeddigit trueorfalse,onoroff,1or0 Numberstring Characterstring Hexadecimalnumber Stringwithvariablelengthfromntom 2Byteintegernumber 4Byteintegernumber

numbersofanylength,startingwith013 correspondsto0181,0182and0183 correspondsto01925,01935and01945

1 2 3 4 5 6 7 A I

1.2

Abbreviation List
CDR Dest e.g. EMS ESMS GSM GUI HTML HTTP HTTPS Id i.e. CallDataRecord Destination forexample EnhancedMessagingService EnhancedShortMessageService GlobalSystemforMobileCommunication GraphicalUserInterface HypertextMarkupLanguage HypertextTransferProtocol SecureHTTP Identity thismeans

Introduction IMEI IMSI IN IN-OPSC IOWIQ IP ISDN LOC MAP MIB MS MSISDN MTWIQ NSG NMS OLS OPSC OUM PDU RAID RSC SAT SC SIM SM InternationalMobileEquipmentIdentity InternationalMobileSubscriberIdentity IntelligentNetworks OPSCwithIntelligentNetworkssupport InternetOriginatedwIQticket InternetProtocol IntegratedServicesDigitalNetworks Locationofthecellularnetwork MobileApplicationPart ManagementInformationBase(forSNMP) MobileStation MobileStationISDNNumber MobileterminatedwIQticket NetworkServiceGateway NetworkManagementSystem ORGALoggingSystem ORGABillingSystem ORGAUnifiedMessaging ProtocolDataUnit, RedundantArrayofInexpensiveDisks RemoteSystemControl SIMApplicationToolkit ServiceCenter SubscriberIdentityModule ShortMessage

1 2 3 4 5 6 7 A I

Introduction SNMP Src tcp TPDU TRID UDH UDP URL USSD VTOC WAP WWN wIQ SimpleNetworkManagementProtocol Source transmissioncontrolprotocol TransferProtocolDataUnit TransactionId UserDataHeader UserDatagramProtocol UniformResourceLocator UnstructuredSupplementaryServiceData VirtualTableofContents WirelessApplicationProtocol WorldWideNumber wirelessInformationQuery

1 2 3 4 5 6 7 A I

Introduction

1 2 3 4 5 6 7 A I

System Description

2
1 2 3 4 5 6 7 A I

2.1

System Overview
ThewIQsystemmakesHTMLcontentaccessibleformobilestations(MS)via USSDserviceorSMS.ItactsasagatewaybetweentheMSandHTMLcontent servers. FortheMS,theUSSDandSMSserviceisused.Toaccessthecontentserver, HTTPprotocolistaken. BecauseofthelimitationsofUSSD/SMSintermsofdisplayandUSSDdialog capabilities,onlyalimitedsubsetofHTMLissupported.Sophisticatedfeatureslikepreinputandhotkeyfunctionssimplifythehandlingandincrease thecomfort. ThepossibilitytopassonsubscriberidentityinformationtoURLswillalsosupportwIQoperatorstorealizesubscriber-specificaccesscontrolorpersonalized information. 1. USSD SubscriberscanrequestHTMLcontentwiththeirMSbydialingaUSSDstring (like*101#or*105*7110815#)andbypressingthe Sbutton. ThismessageissenttothenetworkandroutedtowIQ.ThewIQmapsthis USSDstringtoanHTMLhyperlinkandsendsanHTTPrequesttothecontent servertorequesttheHTMLpage.

System Description TheHTMLpageisthenconvertedintoaUSSDmessageandsenttotheMS. IncasetheHTMLpagecontainshyperlinksorinputforms,whichmeansthat additionaluserinteractionisrequired,aUSSDrequestmessageispassedto theMSwhichwaitsforfurtherinputfromthesubscriber. 2. SMS YouwillhavethepossibilitytosendandreceiveSMSsviawIQ. SubscriberscanrequestHTMLcontentwiththeirMSbyenteringanSMS. ThismessageissenttothenetworkandroutedtowIQ.ThewIQmapsthis SMStoanHTMLhyperlinkandsendsanHTTPrequesttothecontentserver torequesttheHTMLpage. Youcanenter aURLor ashortcutor aUSSDstring,e.g.*100# (seealsothesectionCallawIQServiceonpage 30) ThetypeofentryhastobeconfiguredinwIQ,seesections4.7-4.13. TheSMScanbeinternatialized.AdifferentcharsetthanGSM7bitcanalso beused. YoucanalsorequestHTMLcontentviaSMSbysendingaURLoranabbreviation(dependingontheconfiguration)asacontent. ParsingrespectivelyprocessingcandependonthereceiveroftheSMS.FordifferentSMSreceivers,differentURLsforthesamecontentcanberequested. UnlikeUSSD,nobrowsingispossible.

1 2 3 4 5 6 7 A I

3. SMS/USSD AninteractionSMS/USSDcanbeperformedwhichmeansthatthatyoucan startwithaUSSDsessionandgetanSMSback,oryoustartaUSSDsession

System Description bysendinganSMS. Thefollowinggraphicshowsthisinteraction:

IfitisdefinedinHotKeySet.cfgtosendthecurrentUSSDpageasanSMS (0),youhavetoenter0. AnotherinteractionbetweenUSSDandSMSisperformedwhenanSMSis sent.AnUSSDsessionisstartedbytheSMS. Thefollowinggraphicshowsthisinteraction:

1 2 3 4 5 6 7

4. Push wIQoffersaninterfacewhichallowstoinitiatemessagesfromthewIQtoa subscriber;seealsothesectionPushInterfaceonpage 140.

A I

System Description

Internet

wIQ

Mobile Subscriber

HTTPrequest USSD/SMS

Acknowledgement HTTPresponse

1 2 3 4 5 6 7 A I

10

System Description

2.2

Description of the wIQ Process

ThewIQprocessispartoftheinterfacebetweenthemobilesubscriberand theintranet/internet.ThefollowingdiagramshowsthepurposeofthewIQ process:

1 2 3 4
wIQ system ThewiqdreceivesrequeststoloadURLsviatheORGAUSSD-GWInterface andservestheserequestsbyconnectingtotheappropriatesitesontheInternet.ThewiqdlistensonaconfigurableportforUSSD-GWrequests,translates theserequeststoURLsandtriestogettheseURLsfromtheinternet.Thewiqd thentranslatesthecontentsoftheURLtotheUSSD-GWprotocolandsends theanswertotheappropriateclient.

5 6 7 A I

2.3

External Requirements
wIQisdesignedtocooperatewithUSSDimplementationaccordingto:

11

System Description ETSITS100974V7.1.0(1999-08) TechnicalSpecificationDigitalcellulartelecommunicationssystem (Phase2+) MobileApplicationPart(MAP)specification(GSM09.02version7.1.0 Release1998)

2.4

HTML to USSD/SMS Conversion

OneofthebasicfunctionsofwIQisconvertingHTMLcontentenrichedby specialtagsintoUSSD/SMStext.ForUSSD,thisalsoincludesaveryconvenient wayofbrowsingthroughcontent. HTMLlinksarenumberedwithconfigurablecharactersontheMS.Thecorrespondinglinktextfollowsaside.Laterinputcharactersarematchedtothe correspondinglink(ifitapplies). Thefollowingtablegivesabrieflistofpossibletags: Supported HTML Tags Tag Start Tag End </HTML> </HEAD> </TITLE> Description DefinestheHTMLcontentinadocument onaWebserver,noattributes. DefinestheheadsectioninanHTMLdocument,noattributes. Indicatesthedocumentstitle.Itisdisplayedasfirstlineinthedisplay.Noattributes. DefinesthebodysectioninanHTMLdocument,noattributescanbeconverted. Newparagraph.ItisconvertedtoNEWLINE.

1 2 3 4 5 6 7 A I

<HTML> <HEAD> <TITLE>

<BODY> <P>

</BODY>

12

System Description Supported HTML Tags Tag Start <BR> <A HREF=URL> </A> Tag End Description Insertsalinebreakatthecurrentposition. IsconvertedtoNEWLINE. Indicatesadocumentanchor,usedtocreatelinkstootherresourcesortodefinea locationthatcanbelinkedto.Eachlinkis convertedtoalinkID,whichiseithera numberorcharacteraccordingtomobile capability.Atextderivedfromthelink descriptioninthecontentisprintedafter thislinkID.Amaximumnumberof9links issupported. FORMinputrequestsaretranslatedinto requestswhicharesentonebyonetothe MS. Ifinputtypeishidden,valuehastobe specified.Forinputtypetext,avalueis notsupported.

1 2 3 4 5 6 7 A I

<FORM ACTION=URL METHOD=[GET|POST]> <INPUT type=["text/hidden"] name=varname, value="value"forhidden> <metahttp-equiv= "Content-Type" content="text/html"; charset=<charset>"

</FORM>

AHTMLtagindicatesthecharactersetthe HTMLpageuses.Thisisdoneusingthetag <meta>whichcanbeusedinsidethe <head>tag.

13

System Description

Itisrecommendedthatthetag<meta>appearsasearlyaspossible intheheadelement. Evenalltextbefore<meta>withattributecontent="text/htmlcharset="isconsideredtobecodedasdefinedinthe<meta>tag. Onlyone<meta>tagwithattributecontent="text/htmlcharset=" canbedefinedonaHTMLpage.Allother<meta>tagswiththat attributewillbeignored.Awarningwillbeprinted.

Importantfor<input>: IfthemessageisUCS2,thevalueisURLencodedUCS2UTF-8. Example: <HTML> <HEAD> <meta http-equiv = "Content-Type" content = "text/html"; charset=iso-8859-1"> <TITLE> ORGA MENU</TITLE> </HEAD> <BODY> <A HREF="http://www.orga.com/news.html">News</A> <BR> <A HREF="http://www.orga.com/banking.html">Banking</A> <BR> </BODY> </HTML>

1 2 3 4 5 6 7 A I

14

System Description ThisexampleisconvertedbythewIQtothefollowingUSSDoutputonthe MSdisplay;seealsosectionHotKeySet.cfg:ConfigurationFileforCharacter Setsonpage 102:

1
Example menu on MS display

2 3 4 5 6 7 A I

2.4.1

wIQ-specific Tags
SomespecialtagswhichallowtosetoroverridewIQparameters: <wIQ [provider="{provider_string}"coins="{coin_value}"] [bearer="{bearer_string}"] [aparty="{msisdn}"] [smsinterface="{interface_string}"] [ussdmode="{ussd_string}"] [forcedisplay="{0,1}"] />

2.4.1.1

Values / Attributes
TherearedifferentsessionattributeswhichmayberesetbyHTMLwIQattributes. Alltheseattributesareoptional.Exceptforforcedisplay,theyonlyoverride thesessionattributesifthevalueisvalidandtheHTMLpagehasthepermis-

15

System Description sionstooverridethesettings(seethetableValidURL:PermissionstoOverrideSessionConfigurationfromHTMLContentsonpage 89). Additional wIQ Tag Attribute Description Attribute bearer (seesectionSMSto ServiceMapping Table:Fieldson page 90) Values {FINISH, BROWSE, SMS,FINISH-SMS} Description Setthesessionmode andbearer. Overrides: eitherUSSDtoURL Mappingfield SessionType or SMStoService Mapping fieldBearer. Interruptsthe processingof preinput.

1 2 3 4 5 6 7 A I

forcedisplay

{0,1}

ThefollowingattributesareonlyusediftheresponseissentoverSMS: aparty (seesectionURLto SMSInterface MappingTable: Fieldsonpage 95) BCD[1..20] TheMSISDNwhichis usedasA-Party. Overrides: URLtoSMSInterface Mapping fieldA-Party

16

System Description Additional wIQ Tag Attribute Description Attribute smsinterface (seesectionURLto SMSInterface MappingTable: Fieldsonpage 95) ussdmode (sectionURLtoSMS InterfaceMapping Table:Fieldson page 95) Values {MAPSMS0, MAPSMS1(optional), MAPSMS2} Description Themodeforsending SMS. Overrides: URLtoSMSInterface Mapping fieldSMSInterface TheactiononUSSD aftersendinganSMS. Overrides: URLtoSMSInterface Mapping fieldUSSDMODE

{FINISH,BROWSE, REDISPLAY}

1 2 3 4 5 6 7 A I

Example HTML Page <HTML> <HEAD> <WIQ PROVIDER="ORGA" COINS="50" BEARER="SMS" USSDMODE="REDISPLAY" SMSINTERFACE="MAPSMS0" APARTY="99999999999999" /> <TITLE>ORGASMSPAGE</TITLE> </HEAD> <BODY>

17

System Description Thispagemakesitsownsessionsettings </BODY> </HTML>

2.5
2.5.1

Using USSD
Subscribers Input Interface
Therearedifferentinputscenarios,dependingonthecurrentstateofinteraction.

2.5.1.1

Subscribers First Login (Self-registration)

Duetothedifferentimplementationsoftheprompt(USSDinput)modeon varioustypesofhandsets,akindofconfigurationprocessisneededwhilethe subscriberlogsinforthefirsttime. Therearedifferentpossibilitiestoperformthisconfiguration: BeforethesubscribersfirstuseofthewIQ,theconfigurationissetupby theoperator. Whilethesubscriberislogginginforthefirsttimebyusingdefaultvalues whichareconfiguredbytheoperator. WhilethesubscriberislogginginforthefirsttimebyredirectiontoaspecialHTMLpagewhichisdesignedforsubscriberself-configuration. Theoperatorcandesignthisconfigurationdialoghimself,evenifthereis adefaultgiveninwIQ. ThisdialogisdesignedinstandardHTMLwithHTMLinputformandthe useoftheWebinterfaceofthesubscriber-specificdatabase. Alltheseconfigurationsequencesperformaninsertionofadatabaserecord forthesubscribersMSISDNwithsubscriber-specificconfigurationdataasexplainedinsectionSubscriberDatabaseonpage 37. InsidewIQ,threebasiccomponentswillcompletetheimplementation: Theconfigurationdialog ThisisthetaskofthewIQoperator,evenifwIQgivesadefault.

1 2 3 4 5 6 7 A I

18

System Description PHPInterfacetoasubscriber-specificprofiledata Thisistheinterfacewheretoputsubscriber-specificprofiledataaftera Web-basedconfigurationdialog. Runtimeaccesstosubscriber-specificprofiledata. Bymeansofthis,wIQdetectsnotconfiguredMSISDNs,findstheURL mappingtable,andpicksuptheHTTP-accesstable. Itistheinterfacewheretoputthestatisticsessiondata. Example for a simple subscribers self-configuration: (ForHTML-sources,cf.sectionHTMLPagesforKeytableConfigurationon page 232).

1 2 3 4 5 6 7 A

Subscribers redirection to a special HTML-page

Toallowasubscribertochangehis/herdatabaseentries,wesuggesttodesign asecondconfigurationpageandtoreserveaservicenumberforit. Thisisneededeitherifthesubscriberdoessomethingunexpectedduringthe

19

System Description firstconfigurationprocessorifthesubscriberchangeshishandsettoanother type.

1 2 3 4 5 6 7 A I

20

System Description

2.5.1.2

Call a wIQ Service

TocallawIQservice,asubscriberhastotypeaservicenumberwhichisdefinedbythecustomer.AccordingtoUSSD-specification,thisnumbermustfollowoneoftheseformats: 1,2or3digitsfromtheset(*,#)followedbyanumericservicenumber, andfinishedwitha#S. Aseriesof*digitscanfollowthisservicenumber.Itwillbetreatedaspreinputforaserviceidentifiedbytheservicenumber.Thisfeatureisusedfor RAPIDURLaccessasdescribedinthesectionRapidURLAccessonpage 23 orfordirectparameterpassing(seethesectionFastAccesstoURLwithDirectParameterPassingonpage 34). 7YS,whereY=anynumberfrom0-9 IfawIQserviceneedingfurtherinputiscalledforthefirsttime,asession starts.Thismeansthatfurtherinputneedsnoservicenumberinfront.Input willbepasseddirectlytothesession.Typically,thisisbrowsingthroughthe definedWebpages. Commands to Start a wIQ Service EntryFormat:<service prefix><service number>[*<preinput>]#S

1 2 3 4 5 6 7 A I

serviceprefix

1,2,or3digits fromtheset(*, #) NNN

hastobedefinedbythecustomerintheUSSDtoURL Mappingtable(seepage 78). hastobedefinedbythecustomerintheUSSDtoURL Mappingtable(seepage 78). Thiscouldbealinknumber, inputtoaform,inputtoa script,orcouldbeusedforthe USSDtoURLMappingtable.

servicenumber

preinput

Amaximumof19 *digitsisusedas aninputtothe desiredservice

21

System Description oralternatively EntryFormat:7<service number>S1

servicenumber

hastobedefinedbythecustomerintheUSSDtoURL Mappingtable(seepage 78).

Example:

*100#S
callthewIQservice*100# http://www.orga.com

#100*1#S callthewIQservice#100*1#
http://www.orga.com/news.html

1 2 3 4 5 6 7 A I

Thepreinputs2and3arepassedasparameterstotheservice#101#;see alsothetable"USSDtoURLMappingTable"onpage 78.

#101*2*3#S callthewIQservice#101#.

*130*100#S
isdirectlymappedtoanURL.Thepreinput100isusedforthemappingand notaspreinputforthepage.

ProcessingpreinputcanbeinterruptedbyusingthewIQ-HTMLtag attributeforcedisplay. Access URL by Service Number AlistofspecificnumberswillbemappedtoURLs.Forasubscriber,theseare allpossibleentryURLstostartbrowsing.

1 It seems that this can not be handled by all mobiles correctly, e.g. a Siemens C25 or Nokia 8210 makes a call when entering such a code. Only newer mobiles seem to handle this right.

22

System Description ThetableUssd2URL.cfg*:USSDtoURLMappingTableonpage 78definesthecoherencebetweenURLandservicenumber.Ithastobemaintained bythewIQoperator.AtleastoneisnecessarytoactasapointertoanURL. Thedecisiontouselotsofservicenumbers,toreducethedepthofthebrowsingtree,ortolimitthequantityofservicenumbersandmoveselectiondecisionsdownintoHTMLcontextisuptothecustomer. Rapid URL Access TospeedupaccesstoURLforroutinesubscribers,preinputisusedtowindup theaffectedWebpagetree. Aservicenumberextendedwithaselectionnumberseparatedby*(e.g. *105*1#S)whichisnotmatchedintotalbythemappingtable causesautomatedbrowsingthroughthehyperlinkstothedestinationURLby skippingthepagesinbetween. PreinputisnotaffectedbyHotKeySet.cfgandHandSetID. Apreinput1willalwaysselectthefirstlink! ItmaybeaffectedbyUssd2URL.cfg*?ife.g.theservice *105*1#isconfigured. Thefollowingexamplegivesanillustration: AsubscriberwantstohaverapidaccesstotheWeatherNewsofSantiago. InsteadofinvokingtheindexURLwith*105#Sandselectingthe weatherlinkbyentering2SandafterwardsgoingtoSantiagowith3S, hejusttypes*105*2*3#StodirectlyaccesstheSantiagoweather page.Thiswillresultinskippingthefollowingpages:

1 2 3 4 5 6 7 A I

23

System Description

1 2 3 4 5 6
Thefollowingpageisdisplayeddirectly:

7 A I

24

System Description

ThisallowsadirectjumptoURLwhichshortensthebrowsingtimeandwill alsoreducenetworkload.

1 2 3 4 5 6 7 A I

2.5.1.3

Browsing in an Open Session

ThesubscribercancallawIQservice(seesectionCallawIQServiceon page 21)orusehotkeyfunctionalityinanopensession. Subscriberswillbeabletogobackwards,forwardand"Home"duringtheir session.Afterfinishingasession,nohistoryisstored.Amaximumcontextof 10pagesisstoredforeachsessioninafirst-in-first-outmanner. Inaddition,ausermaygobackwardsbyentering*Sandforward(aftergoingbackward)byentering#Sandjumptothecarrier-definedhomepage/startpagebyentering*#S. EntryFormat: <hotkey>[*<preinput>]S Inthefollowingtable,someexamplesareshown:

25

System Description

ID 1 2

Input Character Set 123456789*0# abcdefghij*0#

Output Character Set 123456789 abcdefghij;seealsosectionHotKeySet.cfg:ConfigurationFilefor CharacterSetsonpage 102.

Examples for HandSetID 1:

*S #S *2*3S 1*2*3S *#S ##S *100#S

gobackonepageinhistory goforwardonepageinhistory gobackonepageandpassthepreinput2and3to thenewservice chooselink1oftheactualpageandpassthepreinput 2and3tothenewservice. jumptothecarrierdefinedhomepage endofasession jumptoservicenumber*100#

1 2 3 4 5 6 7 A I

26

System Description Handsetwhich switchesto alphamode2: HandSetID=2 Otherhandset:

HandSetID=1

1 2 3 4 5 6 7 A
Subscriber-specific input interpretation

2 The first character you get by pressing a key is a letter

27

System Description

Bothsubscriberswillhavetoenter*105*2#togetrapidaccesstothispage.Theinterpretationofinputonlydiffersinthe browsingmodeandonlyaffectsthehotkeyfunctionality.

2.5.1.4

Controlled Preinput Processing

Controlledpreinputprocessingallowstostopautomaticprocessingofapreinputchainifoneormorepagesinthischainshallbeforcedtobedisplayed. ThisisdonebyusinganattributetothewIQ-HTMLtagcalledforcedisplay. Ifthisattributeissetto"1"onaHTMLpage,nofurtherpreinputisprocessed andthecurrentpageisdisplayed. Example: Theoperatoroffersaservicewherethesubscriberhastoagreethelicense termsforthatspecialserviceeverytime.Itshallnotbepossibletoskipthis pagebypreinput.Thesubscriberhastorequesttheservice*100#,andthen followlink1andthen2togettothiscertainlicenseagreementpage. Linkoneonthatlicenseagreementpagewillbe"Yes,Iagreetothelicense termsandwanttocontinue".Sobyentering*100*1*2*1#thesubscriber wouldnormallyskipthelicenseagreementpageanddirectlyagree. Nowbywriting <wIQ forcedisplay="1"/> onthelicenseagreementpage,theoperatorcanforcetoshowthispageand discardpossibleremainingpreinput. Thesubscriberentersthescenariodescribedhere: *100*1*2*1# Becauseoftheforcedisplayattributesetto"1"onthelicenseagreement page,theresultof *100*1*2# isnowdisplayedandtheremainingpreinput*1isdiscarded.

1 2 3 4 5 6 7 A I

28

System Description

2.5.1.5

Session End
Therearethreedifferentmethodstoendasession: SubscriberEndCommand Timeout Thesubscriberendsasessionwith##Sas ananswertoaprompt. Ifthesubscriberdoesnotrespondtoaprompt foraperiodgreaterthanwIQ.TimeOutorthe HTML-pagecannotbeloadedduringthis period,thewIQendsthesession. Ifthesessionstartswithaservicenumber whichisconfiguredas"FINISH"inthe Ussd2URL.cfg*file(seesection Ussd2URL.cfg*:USSDtoURLMapping Tableonpage 78)thenthesessionends afterdisplayingthefirstpagewithoutlinksor forms.IfBROWSEisdefinded,thesession staysuntilatimeoutoccursorthesubscriber sends##S.

SpecialServiceNumbers

1 2 3 4 5 6 7 A I

29

System Description

2.6

Using SMS
Therearedifferentinputscenarios,dependingonthecurrentstateofinteraction.

2.6.1

Subscribers First Login

Thereisnoself-registrationwhenusingSMSforthefirsttime(andUSSDhas neverbeenusedbefore).IfUSSDwasusedbefore,thesettingwillbeused andanentryfromtheDBDefaults.cfgistakeninstead(seesectionDBDefaults.cfg:MSISDN-DependentDatabaseDefaultsTableonpage 97).

2.6.1.1

Call a wIQ Service

SMS TouseSMSwithwIQ,thesubscriberhastosendanSMStoatelephonenumber.ThisnumberisconfigurableandcanbeconfiguredinsidewIQ. Thecontentcancontain: 1. an URL, e.g. http://www.orga.com 2. a short cut, e.g. LH 10.10.2001 DUS FRA Dep 3. a USSD string, e.g. *1001*1# dependingontheconfiguration. (seealsopage 8). URLbyservicenumberandrapidURLaccessaresupported(seepage 22).

1 2 3 4 5 6 7 A I

Thefollowingexamplesaretobeseenascustomer-dependentconfigurations andareonlytoserveasanexample.

30

System Description SMS/USSD Interaction

USSD

Thefollowingpageisdisplayed:

1 2 3

USSD (Browsing)

4 5 6

0isconfiguredasSendalsoasSMS(seesectionHotKeySet.cfg:ConfigurationFileforCharacterSetsonpage 102).

7 A I

31

System Description Thefollowingpageisdisplayeddirectly:

USSD

TheUSSDsessionisendednow(itmaycontinueforotherconfigurations). TheSMSarrives:

1 2 3 4 5 6 7 A I

SMS

TheSMScannowbesaved.

2.6.2

Supported Types of SMS

wIQsupportstosendshortmessagesastextmessageswith7-bitcoding.As anormalshortmessagehasamaximumlengthof160characters,largermessageswillbetruncatedatthisborder. ForUCS2messagesthemaximumlengthis70characters.

32

System Description

2.7

Push
wIQoffersanewinterfacewhichallowsapplicationstoinitiatemessages fromthewIQtoasubscriber.

2.8

HTML Input Formats

wIQsupportstheaccesstoHTMLpageswhichneedtogetinput(HTML forms)whichisvalidforUSSD. ThesecouldbeusedtopollforPINsoraccountnumbersforexample(seealso sectionHTMLtoUSSD/SMSConversiononpage 12).

1 2 3 4 5 6 7 A I

2.9

Subscribers Identity Directly to URLs

Thesubscriberparameters(seetableValidURLVariablesonpage 86),e.g. MSISDNandLOC(Location)canbepasseddirectlytoURLs.Theoperatoris freetoconfigurewhocanuseitandhowtouseit. Forexample:topermitorrestrictaccesstocertainURLs. Configurationisdoneinavariableinclusiontable(seepage 84). AllvalidURLsaredefinedinthistable.Thereforeregularexpressionsareallowedtominimizethetablesize. ThewIQputsthesevariablesandtheirvalue(ifavailable)intotheHTMLcontextenvironmentas e.g. HTTP_MSISDN and HTTP_LOC (seealsothetableValidURLVariablesonpage 86).

33

System Description

2.10 Fast Access to URL with Direct Parameter Passing

DependingontheURLtreedefinedintheUSSDtoURLMappingtable(see alsothetableUssd2URL.cfg*:USSDtoURLMappingTableonpage 78), thesubscriberspreinputwillbepasseddirectlytoURLsasaninput. PleasenotethattherealizationofURLpagesdefineswhichinput valueisusedasaselectionofaURLorispassedinasaninputvalue toanHTMLinputform.

2.11 HTML Conversion to Mobile Phone-Specific Character Set

ThepossibilitytoprintspecificcharactersinGSMstandardalphabet(forexample:$)dependshighlyonthehandsetproductandtheMAPversionofnetworkandhandset. BecauseofthelimitedcharactersinGSMstandardalphabet(seealso page 225),thewIQusesaninternalmappingtabletohandlespecialcharactersfromISO-LATIN-1,whicharenotsupportedinGSMstandardalphabet. Thesecharactersareeitherdisplayedasa?ormappedtoasimilarlooking character(seealsosectionSupportedCharactersfromtheGSM-DefaultAlphabetonpage 225andsectionMappingfromHTML3.2toUSSD/SMS onpage 226. wIQispreparedtousehandset-specificconfigurationtablesinfuturereleases, butthecurrentreleaseisdeliveredwithonedefaultcharactermappingtable only;seealsopage 225. wIQisabletoreceiveUCS2messagesandthereforeanothercharacterset.

1 2 3 4 5 6 7 A I

2.12 Constraints
USSDPhase1doesnotsupportdialogcapabilities. ForPhase1phones,onlydirectpageaccessispossiblewithout browsingfunctionalityorinputdialogs.

34

System Description WithSMS,thereisnobrowsingpossible.

2.13 Multiple Language Report

Thesystemsupportstheuseofmultiplelanguageswhencommunicatingwith subscribers. Thelanguagetobeusedforthecommunicationwiththesubscriberissetusingthe'Accept-Language'headerofaHTTPrequest,seesectionXintheappendixofthismanual.AWebserverinterpretsthisheaderinformationand returnstheappropriateHTMLdocumentinitsresponse,thereforesupporting multiplelanguages'automatically'.

2.13.1 Preferred Language Set in the Subscriber Database

IfthepreferredlanguagehasbeensetandisavailableinthewIQSubscriberDatabaserecordofthesubscriber,wIQsetsthe'Accept-Language' headerofeachHTTPrequestaccordingtothesettinginthewIQSubscriberDatabase. Asaresult,allpagesrequestedbythesubscriber(eitherinternalwIQpagesor externalpagesfromtheCRM)aredisplayedusingthesubscriber'spreferred language.

1 2 3 4 5 6 7 A I

35

System Description

1 2 3 4 5 6 7 A I

36

Databases

3
1 2 3 4 5 6 7 A I

3.1

Subscriber Database
Duetotheveryhighperformancerequirements,theORGAIncoreDatabase isusedtostorethesubscriber-specificdata.

ThedatabaseisautomaticallysetupandrestoredfromthelatestDumpand JournalFilebythestartscriptwIQd. Allchangesareloggedinto$ORGADATA/IncoreJournal/ Subscriber_jnl.<number>. Normallythecontentsofthedatabasearedumpedto$ORGADATA/IncoreDump/Subscriber_dmp.<number> onceaday.

3.1.1

Interfaces PHP-Interfaces
wIQprovidesaPHP-basedinterfacetoaccessthedatabase.Viathisinterface itispossiblefortheoperatortosetuparegistrationscenarioforthesubscriber.Inaddition,theoperatorcanusethesameinterfacetoaccesssubscriberrelateddataviaastandardWebbrowser. ThisfunctionmaybeusedinPHPpagesonthewIQsWebserver. The$DOCUMENTROOToftheWebserveris$ORGAROOT/apache/htdocs.

37

Databases USAGE: TousethePHPfunctionthefollowinglineisneededtoloadtheIncoreinterface: <?php dl("libphp_incore.so"); ... ?>

Function: Arguments:

$return_array=incore_action($Databasename,$CommandLine); $Databasename $CommandLine Thenameofthedatabase ("Subscriber") TheCommandLine

1 2 3 4 5 6 7 A I

Result:

Thereturnofthefunctionisanassociatedarraywhich containsatleastoneentry. Ifanerroroccurs,thefunctionwillreturn onearrayentry["result",<ERROR_CODE>]and anotherentrywiththedescriptionoftheerror ["ERROR",<Description>] ERROR_CODEisalways<0!

incore_action()allowsnearlythesamefunctionalitywhichispossible withtheunixcommandlineinterfaceopsc_adbexceptselectloops.For completeinformationaboutthecommandlinesyntax,pleasereadtheonline manualpagesIncoreDatabaseandopcs_adb.

38

Databases Commandline Syntax: #d <Search Condition> Deletesasubsetofdatabaserows. Thereturnedarraycontainstheentry ["result",<number of deleted lines>] ifthecommandwassuccessful. #s <Fields> <Search Condition> Selectonedatabaserowwhichmatchesthesearchcondition. Thereturnedarraywillcontainallgivenfieldswiththerelatingdatabase entry.IfthePHPinterfacedoesnotallowtoselectloops,theresultofa searchwillalwaysbeA,ifatleastoneentryisfoundthatmatchesthe searchconditions. #i <Fields> <Search Condition> <Host Variables> Insertanewdatabaserowandsetthespecifiedfields. Thereturnedarrayofsuccessfulinsertionwouldbe ["result",1] #I <Fields> Queryaboutthetypeoffieldsinthedatabaseanddatabaseusage. Thereturnedarraywillcontainallgivenfieldswiththeinformation. #u <Fields> <Search Condition> <Host Variables> Updateasubsetoffieldsinrowsofthedatabase. Onsuccessfulexecutionthereturnedarraywillcontainexactlyoneentry ["result",<number of updated rows>]. <Fields> Toidentifyasetoffields,eachfieldnamemustbeprefacedwitha leadingcolon(:).Toseparatefieldnames,atleastoneblankmustterminatethefieldname.Ifafieldnamewasnotfound,anerrorisreturned. <Search Condition> $ <comparison type> <field> '<value>'

1 2 3 4 5 6 7 A I

39

Databases Thesearchconditionalwaysstartswitha'$'andisfollowedbyoneof thefollowingcomparetypes: > Greaterthan >= Greaterorequal

< Less <= Lessorequal = ~= ~<= ~>= Equal Caseinsensitiveequal(forstringsonly) Caseinsensitivelessorequal(forstringsonly) Caseinsensitivegreaterorequal(forstringsonly)

1 2 3 4 5 6 7 A I

~< Caseinsensitiveless(forstringsonly) ~> Caseinsensitivegreater(forstringsonly) = Equal != Notequal true alwaystrue false alwaysfalse Tocombinetwoormorecomparefunctions,thefollowingfunctions whichacceptonlytrue/falsevaluescanbeused:

Function and or

Description combinetwotrue/falsevaluesusingthelogicaland. combinetwotrue/falsevaluesusingthelogicalor.

40

Databases <Host Variables> Thispartalwaysbeginswitha'&'andisfollowedbythedescriptionfrom whichdatabasefieldshavetobeupdated. Examples: DeleteallMSISDNswithlastdateofusebefore1March2000andTariffGroup=1: #d $ < and :LastUseDate '20000101000000' = :TariffGroup '1' Insertadatabaserow: #i :MSISDN :InstallationDate :HandsetId :UssdGroup\ :TariffGroup :Phase1 & '6763274' '20010101235959' '1' '1' '1' '0' GettheentriesforsubscriberwithMSISDN'6763274': #s :MSISDN :InstallationDate :HandsetId :UssdGroup\ :TariffGroup :Phase1 $ = :MSISDN '6763274' ChangetheHandSetIdforsubscriberwithMSISDN'6763274': #u :HandSetId $ = :MSISDN '6763274' & '5'

1 2 3 4 5 6 7 A I

Commandline Interfaces and Database Tools

Therearealsoanumberofunixcommandlinetoolsformanagingthedatabase. opsc_adb opsc_createdb opsc_destroydb opsc_dumpdb Commandlineinterfacetothedatabase. Createsthedatabasememorysegments Destroysthedatabaseandfreesallsystem resources. Readsthewholedatabaseandwritesittoareadable fileDumpFileorrestoresthedatabasefrom DumpFile. Displaysinformationaboutthestructureofthe databaseoraboutthecontaineddata.

opsc_showdb

41

Databases opsc_exadb opsc_recoverdb ExaminestheOPSCdatabasejournalanddumpfiles. RecoverstheIncoredatabaseDatabaseNamefrom thedumpfileDumpFileandoptionallythejournal filesJournalFile.Thedumpfileandthejournal filesarenormallygeneratedbyopsc_svrdb. CollectschangestotheOPSCIncoredatabase DatabaseNameandrecordstheminthecurrent journalfile.opsc_svrdbcanalsodumptheIncore databasewhilenotaffectingapplicationaccessto thedatabase.

opsc_svrdb

Forfurtherinformationreadtheunixmanualpageslocatedin $ORGAROOT/run/man. Thedatabasecontainstwodifferentkindsofdatarelatingtoasubscribers MSISDN: User-specificconfigurationdata handset-specific logical wIQcontrolswhichsubscriberisallowedtousewhatservices.Thisisusedfor allkindofwIQrequests(SMSandUSSD)andwillbelookedupevenifSMS servicesarenotenabledwithinthewIQlicense. USSD/SMSMessagesfromortosubscriberswhoarenotallowedtousethis wIQservicewillbeignored.Thisaresubscriberswhichhavenoentryinthe fieldAllowedServicesornotbeingallowedforaspecialservice. User-specificstatistics Thefirstoneisuser-specificconfigurationdata.Thiskindofdataisusedby thewIQforthepersonalizationofthewIQbehavior,e.g.thedefinitionofinputinterpretationorthedefinitionofoutputstyle. AnotherpossibilityisthepersonalizationofUSSD-codetoURLmapping. Withthis,theoperator(orthesubscriberhimself/herselfviaanoperatordevelopedinterface)isabletoassignaspecialgroupwitharelatingUSSDtoURL Mappingtable.Thesetableswillbeimplementedasdifferentfilesin$ORGADATA/cnf.

1 2 3 4 5 6 7 A I

42

Databases Thedataaresetifthesubscriberusestheservicefortheveryfirsttimebyredirectinghim/hertoaspecialpageorusingpossiblegivendefaults. Inthefollowingtable,someimportantentriesareshown: Entry MSISDN HandSetId Type BCD[20] l Description Subscriberidentification. Handsetidentificationnumber. Thisoneisusedtodetermine thecharactersetwhichshould beusedforthissubscriber. AssignsthesubscribertoaspecialUSSDtoURLMapping. Determinesthemapversion, supportedbytheMS. Thisfieldcancontainacombinationofthefollowingvalues: NONE:subscriberisnotallowed touseanyservices. ALL:allservicesareallowedfor thissubscriber. SMStoSMS:PureSMSservices areallowedforthissubscriber. SMStoUSSD:AnSMSrequest withUSSDanswerisallowedfor thissubscriber. USSDtoSMS:SMSinitiatedbya USSDsessionisallowedforthis subscriber.

UssdGroup Phase1 Services ==>AllowedServices

c[1..63] 0,1,2 i bit1 bit2 bit3 bit4

1 2 3 4 5 6 7 A I

bit5

43

Databases

Entry

Type bit6

Description USSDtoUSSD:PureUSSDservicesareallowedforthissubscriber. Subscriberisallowedtoinitiate anSMStohimself. Subscriberisallowedtoinitiate anUSSDmessagetohimself. Subscriberisallowedtoinitiate anSMStohimselfandother subscribers. Subscriberisallowedtoinitiate anUSSDmessagetohimselfand othersubscribers. SeesectionSubscriberInformationonpage 125. SubscriberPushprivacysettings: 0:NoPushallowedtothe subscriber 1:Pushallowedifsenderis recipient 2:Pushallowedfromanyone Countrycodeofthesubscribers preferredlanguage,e.g.enor ro.

bit7 bit8 bit9

1 2 3 4 5 6 7 A I

bit10

CostInfo PushCtl

0,1,2,3, 4,5 0,1,2

language

c[2]

44

Databases

Entry PrefCharSet

Type 0,1,3,5, 7

Description Valuesarecodedasbits. Validvaluesare: 0-ignorelanguageselection 1-SMSlocale,USSDlocale 3-SMSISO, USSDlocale 5-SMSlocale, USSDISO 7-SMSISO, USSDISO locale=asspecifiedin wIQ.localeCharSet ISO=ISO-LATIN1 TheIMSIisstoredinthe databaseasBCDvalueandcan havealengthofupto20digits. Notethatthereisnofieldforthe IMSIinDBDefaults.cfg, becauseitmakesnosensetoset adefaultfortheIMSI.

1 2 3 4 5 6 7 A I

IMSI

BCD[20]

IMEIRequestMethodIMEIKeyThesecondkindofdataissubscriber-statistic dataproducedbythewIQwhichisshowninthefollowingtable: Entry PIN InstallationDate FirstUseDate Type BCD[4] d/t d/t Description Thepersonalidentificationnumber(forfutureuse). Thedateofdatabaseentrycreation. Thedateofthefirstservice usage.

45

Databases

Entry LastUseDate SessionNum SessionTimeLast SessionTimeTotal RequestNumTotal RequestsNumSession d/t l l l l l

Type

Description Thedateofthelastservice usage. Totalnumberofsessions. Timeinsecondsoflastsession. Totaltimeinsecondsofallsessions. Totalnumberofrequests. Numberofrequestsinlastsession.

1 2 3 4 5 6 7 A I

3.2
3.2.1

Group-Specific USSD to URL Mapping and Valid URL

Brief Description
InordertomaketheUSSDtoURLMappingmoreflexibleandcomfortable, theoperatorisabletoassignsubscriberstospecialgroupsofsubscribers.This canbeforexample,agroupofsubscriberswiththesametariffgrouporwith thesameinterests.Thisallowsanoperatoralsotorestricttheaccesstospecial services. EachgroupwillhaveitsownUSSDtoURLMappingtablein$ORGADATA/ cnf. ThisfeatureallowstheoperatortohavedifferentURLmappingsforoneservicenumber.

3.2.2

How to Assign a Subscriber to a Group

Therearedifferentpossibilitiestoassignasubscribertoaspecialgroup. Onlytheoperatorisabletoassignasubscribertoaspecialgroup. Thesubscriberisabletoassignhimself/herselftoapublicgroup.

46

Databases Thesubscriberisabletojoinintopublicgroups,butonlytheoperatoris abletoassignthesubscribertospecialprivategroups. Theconfigurationdataaresavedinthesubscriber-specificdatabase.Sothe interfaceisthesameasintheexample"Subscriber-specificinputinterpretation"onpage 27. Example: Theoperatordefinestwodifferentgroupsofsubscribers.Thefirstgroupof subscribersisassignedtoID1andthesecondgroupisagroupofsubscribers whichisassignedtoagroupwithID2.Athirdgroupofusersisunassigned. Unassignedsubscribersorsubscriberswithinvalidgroupnumberareassigned theglobalUSSDtoURLMappingtable. TheoperatornowhasthepossibilitytoreservespecialUSSDnumbersforspecialuseonlyforaspecialgroupofusers. Configuration: TherehavetobethreeUssd2URLfiles: Ussd2URL.cfg.1 *110# www.tabacco.xyz Ussd2URL.cfg.2 *110# www.food.xyz *120# www.banana.xyz Ussd2URL.cfg *100# www.orga.com *110# www.weather.cl *120# www.news.cl Ifnowasubscriberwhoisassignedtogroup1requeststheservicenumber *110#,he/shewillgetthepagewww.tabacco.xyz.Ifthesamesubscriber requeststheservice*120#he/shewillgetanerrormessage,astheUSSD service120isnotmappedtoanyURLforsubscribergroup1.

1 2 3 4 5 6 7 A I

47

Databases

1 2 3 4 5 6 7 A I

48

Configuration

4
1 2 3 4 5 6 7 A I

ThewIQdaemon(wIQd process)isconfigurableviathecommandline,aconfigurationfile,anddependsonthelicensestring.

4.1
4.1.1

Start and Stop Procedure

wIQd
TheprocesswIQdsetsupthewholeenviromentforwIQincludingthesubscriberdatabaseandtheWebserver. Options: start [-F][-A][-W] Setsupandrestoressubscriberdatabase, startsthedatabasedumperandloggerand startsanumberofwIQmainprocesses. -F: Forcesdatabasestartwithoutexistingdumps -A: Leavesthedatabaseuntouched -W: AlsostartstheWebserver Reportsthestateofthestartedprocesses,thedatabase. [-A][-W] Stopsallstartedprocessesanddestroysthedatabase. -A: Leavethedatabaseuntouched -W: AlsostopstheWebserver

check stop

49

Configuration reconfigure ThiswillsendallwIQprocessesaSIGUSR2whichcausesareread ofallconfigurationfiles(seealsosectionSignalHandlingon page 65). restart [-F][-A][-W] Restartmissingprocessesiftheprocesseshavebeenstarted withwIQd startandhavenotbeenstoppedwithwIQd stop. Ifnoexistingdatabaseisfound,thedatabasewillberestored fromthelatestdatabasedumpandjournalfiles. Ifthereisnorunningserver,theWebserverisrestarted. -F: Allowadatabaserestartevenifnodumpsarefound. -A: Donotrestartthedatabase. -W:RestartWebserverifnotrunning. ForceafailoverifenteredatwIQguardlocalmodemachine(recommended:use-w). -V: EditthewIQdprocesstablewithvi.

1 2 3 4 5 6 7 A I

failover

FlagsthatareusedbywIQ,butarealsopassedthroughtowIQguardare: -D: Switchondebuggingoutput. -W: StartorstoptheWebserver(dependingoncommandgiven). AlladditionalflagswillbepasseddirectlytowIQ,e.g. -F: Forcedatabasestartwithoutdumps. -U: Dumpdatabaseonstart. -A: Leavethedatabaseuntouched.

4.1.2

wIQd Process Table

TheprocessesstartedbywIQdhavetobelistedinthewIQdsprocesstable $ORGA-ROOT/run/etc/wIQd_proc_tableinthefollowingformat: Identifier Command-line TheIdentifierisauniqueidentifierfortheinstance(e.g.wIQguard).Thisparametermustnotcontainanynon-printablecharactersorwhitespace.The Commandlineparametercontainsthecompletecommandlineneededfor thisinstancetowork.Thiscommandlinemaycontainspaces.

50

Configuration Example: wIQguard

wIQguard -t

4.1.3

wIQd.cfg
Thefollowingconfigurationvariables(in$ORGADATA/cnf/wIQd.cfg)definewIQdsbehaviorifset,otherwisedefaultvaluesareused: Variable wIQd.Alarming Description 0-Alarmingisdisabled 1-Writealarmfile.ThiswillconfiguretheAlarmLoggeraccordingly. 2-SNMPsupportwillbeenabled Default:0 TheLoggercommand.Usuallythisshouldbethe AlarmLogger. Default:AlarmLogger AlarmfilethatiswrittenfromAlarmLogger. Default: $ORGADATA/log/Alarm Unixpipetheloggerreadsitsinputfromandall processesareredirectedtowritetheiroutputto. Normallythereisnoneedtochangethisvalue. Default:$ORGADATA/.logger Thetimeoutperiodthathastopassbeforethe loggeritselfiskilledafterawIQd stopisdone. Theloggermustlivelongerthanallotherprocesses! Default:5 ThecommandstartedtogenerateSNMP-Traps Default:stsc_snmp

1 2 3 4 5 6 7 A I

wIQd.Logger

wIQd.AlarmFile wIQd.LoggerPipe

wIQd.LoggerTimeout

wIQd.Snmp

51

Configuration

Variable wIQd.HttpdPidfile

Description PidfileoftheWebserver.Thishastomatchthe definitioninthehttpd.conffile. Default: $ORGAROOT/apache/logs/httpd.pid ShouldtheWebserverbeincludedinstartingand stopping(1)ornot(0).Thishasthesameeffect thantheWflag. Default:1 Ifyouwanttousenetcat,defineitscommandline here*. Netcatisnotusedbydefault.

wIQd.StartWebserver

wIQd.Netcat

1 2 3 4 5 6 7 A I

* You then should also add the script watch_netcat to wIQguards proc table (see
4.1.4) in order to guard netcat (wIQd simply starts and stops netcat).

Linesstartingwitha#aretreatedasacomment.Allpathnamescanbeabsoluteorrelativeto$ORGADATA. SamplewIQdconfigurationfile: #wIQd Configuration file #Values are shared with wIQguard

#SNMP(2), AlarmFile (1) or no alarming,(0). Default is 0 wIQd.Alarming=1

#Logger command. Default is AlarmLogger wIQd.Logger=AlarmLogger

#Logger kill timeout

52

Configuration wIQd.LoggerTimeout=2

#Alarm File. Defaults to $ORGADATA/log/Alarm wIQd.AlarmFile=log/Alarm

#Logger pipe. Defaults to $ORGADATA/.logger #wIQd.LoggerPipe=.logger

#Pid file of httpd according to httpd configuration. #Defaults to $ORGAROOT/apache/logs/httpd.pid wIQd.HttpdPidfile=/tmp/apache.pid

1 2 3 4 5 6 7 A I

#Start webserver (1) or not (0). Default is 1 wIQd.StartWebserver=1

#If you want to use netcat, set the follwoing line to send #alarms there. wIQd.Netcat="netcat od-scp-1 7334"

4.1.4

Failover
Foraworkingfailover,thewIQguardmustbestartedoneachserver. OnewIQguardisstartedasactive,oneasremote.Whentheactiveprocess detectsthatitswIQprocessesarenotworkingproperly,itexitsandstopsall wIQprocesses.ThestandbywIQguarddetectsthisandstarts.Incaseofan hardwareornetworkproblem,thestandbywIQguardwilldetectthis,too. ThestandbywIQguardwillbetheactivefromnowon.Whenboth(activeand

53

Configuration standbywIQserver)IPaddressesareconfiguredattheNSG,theNSGwill switchautomaticallytothenewserverinanfailovercase. -TheactivewIQguardsupervisestherunningwIQprocesses. -ThestandbywIQguardsynchronizesthedatabaseandchecksif theactivewIQguardisstillrunning. -Theconfigurationfilesaresynchronized. -ThewIQguardisstartedautomaticallywhenanINITscriptexists. (infact,wIQdisstartedwhichwillcallthewIQguard). -wIQguardmaynotbestarted/stoppeddirectly.Itwillbestarted/ stoppedbyusingwIQd(whichwillcallwIQguard). ThewIQguardcanbecalledwiththefollowingparameters: Parameter -lor--local -tor--test-remote Description StartwIQguardinlocalmode(thismachineisthe activeserver). Ifthismachineshouldstartinlocalmode: Firsttrytocheckiftheothersideisrunningin localmode.Ifitisso,startinremotemode;otherwisestartinlocalmode. StartwIQguardinremotemode(thismachineis thestandbyserverandmightbecometheactive one). Thehostnameoftheother(activeorstandby) host. Name(relativeto$ORGADATA)ofthewIQguard configurationfile.Defaultfilenameis: cnf/wIQguard.cfg

1 2 3 4 5 6 7 A I

-ror--remote

-hor--remotehost -cor--config <config.file>

54

Configuration

Parameter -sor--syncconfig <filename>

Description Name(relativeto$ORGADATA)ofthefilewhich containsthefilesordirectories(oneperline)to syncfromtheactive/runningsystemtothe standbysystem.Defaultfilenameis: cnf/wIQguard-sync.cfg Name(relativeto$ORGADATA)ofthefilewhich containsthefiles(oneperline)toexcludefrom sync.Defaultfilenameis: cnf/wIQguard-exclude.cfg Dumpdatabasestartup Turnondebugging. Startevenifnodatabasedumpisavailable. Attachtoalreadyexistingdatabase. ReadenvironmentvariableNODUMPDBSwhich defineswhichdatabasesdonotneedadumpto start(seealso-F). StartWebserver(WebserverwillNOTbestopped bywIQguard!) Checkthestatusofallprocesseslaunchedby wIQguardandtheremotesystem.

-eor--sync-exclude <filename>

-Uor--dump -Dor--debug -For--force -Aor--attach -Nor--nodumps

1 2 3 4 5 6 7 A I

-Wor--webserver checkor--check

55

Configuration

Parameter -fsor--force-sync

Description Forcesynconstartup.Allfilesarereplicatedfrom remotehostonstartup,eveniflocalmodeisconfigured.Ifremotemodeisconfiguredandan wIQguarderrorortoooldalivefileisreplicated fromtheotherhost,animmediatefailovertakes place. Note:Usuallythisoptionshouldnotbeset,itis usedwhenforcingafailover. Printsusagemessage.

--help

ThewIQguardcanbeconfiguredwiththefollowingfile: $ORGADATA/cnf/wIQguard.cfg Variable wIQguard.MaxStart Description NumberofprocessstartsbeforewIQguard assumesthatwIQandotherprocesseshavea problem. Default:10 ThenumberofsecondstosleepbetweenwIQguardslocalmonitoringchecks. Default:30 Timetowaitbetweenkill-Termandkill-KILL. Default:5 ThenumberofsecondstosleepbetweenwIQguardsremotemonitoringchecks. Default:60 Thehostnameoftheguardedserver. Default:mandatory,ifnotsetviacommandline

1 2 3 4 5 6 7 A I

wIQguard.LocalSleepTime wIQguard.KillWaitTime wIQguard.RemoteSleepTime wIQguard.RemoteHost

56

Configuration

Variable wIQguard.Mode

Description ThemodethewIQguardshallstartin(localor remote).Localmodecanbeoverriddenwith the-tflag.Thisvariablewillonlybereadfrom theconfigfileifwIQguardisstartedwithout-local,--remote,lorrparameterset! Default:mandatory,ifnotsetviacommandline Thenumberoftimesapingistried. Default:3 Thenumberofsecondstowaitbetweenping tries. Default:10 ThefilenameoftheOKfile. Default:$ORGADATA/wIQGuardStatus.OK Thefilenameoftheerrorfile. Default: $ORGADATA/wIQGuardStatus.Error Optionstobepassedtoopsc_svrdb Default:-d1h2b Optionstobepassedtoopsc_destroydb.It mightbeusefultopass-ftoforcedestruction whenprocessesarestillconnected,e.g.CGI scripts. Maximumageofthelocalalivefile(inseconds) beforeitisbelievedtobeoutdated. Default:90 Maximumageinsecondsoftheremotealive file(wIQguard.OkFile)beforeitisbelievedtobe outdated. Default:120

wIQguard.PingNum wIQguard.PingWait

1 2 3 4 5 6 7 A I

wIQguard.OkFile wIQguard.ErrorFile

wIQguard.Svrdb Options wIQguard.Destroy dbOptions

wIQguard.wIQTimeout wIQguard.Remote Timeout

57

Configuration

Variable wIQguard.RsyncTimeout

Description ThissetstheIOtimeout(inseconds)forrsync syncingafileinseconds.Thistimeoutmight interrupttransmissionsofbigfiles,sobecareful! Note:0meansforeverwhatisabout3minutes, butwillnotreturnifthenetworkfailsduring thersyncworking. Default:180 Thissetsthetimeout(inseconds)forfetching thestatusfromtheothermachine.Thisvalueis onlyusedwhenwIQguardiscalledwiththe checkoption,e.g.fromwIQd check. Default:15 IsthewIQconfigurationsplitupintwofiles (interface_.cfg&wIQ.cfg)(1)ornot (0)?Theconfigurationissplitupintotwofiles forwIQversion1.3orhigher. Default:1 WherecanwIQguardfindtheglobalwIQconfigurationifconfigurationissplit? Default:$ORGADATA/cnf/wIQ.cfg Name(s)ofdatabase(s)touse.Canbemore thanonevalueseparatedbyspaces. Default:Subscriber Size(s)ofdatabase(s)touse.Canbemorethan onevalueseparatedbyspaces.Shouldmatch thelicense. Default:100000

wIQguard.CheckTimeout

1 2 3 4 5 6 7 A I

wIQguard.wIQSplitConfig

wIQguard.wIQConfigFile wIQguard.DBNames

wIQguard.DBSizes

58

Configuration

Variable wIQguard.Local ModeName wIQguard.Remote ModeName

Description Thenameofthelocalmodeusedinoutputto commandlineandprotocol. Default:local Thenameoftheremotemodeusedinoutput tocommandlineandprotocol. Default:remote

Linesstartingwitha#aretreatedasacomment.Allpathnamescanbeabsoluteorrelativeto$ORGADATA. Example $ORGADATA/cnf/wIQguard.cfg: wIQguard.RemoteHost=wiq2 wIQguard.Mode =local wIQguard.PingNum=10 wIQguard.MaxStart=10 wIQguard.LocalModeName=active wIQguard.RemoteModeName=standby

1 2 3 4 5 6 7 A I

Youcansetmodeandremotehostwiththecommandlineoptions (-l,-r,-h)inthewIQdprocesstable.ThisallowsyoutosyncthewIQguard.cfgtotheotherhost,too.

Note:OneachserverforeachwIQguard,thepathandfilenamefor wIQguard.OkFileandwIQguard.ErrorFilemustbethe same!

59

Configuration

4.1.5

Processtable
ThewIQprocessesguardedbywIQguardhavetobelistedinthewIQguards processtable$ORGAROOT/run/etc/wIQguard_proc_tableinthefollowingform: Flag Identifier Command-line

TheIdentifierisauniqueidentifierfortheinstance(e.g.wIQ_a).Thisparametermustnotcontainanynon-printablecharactersorwhitespace.The Command lineparametercontainsthecompletecommandlineneededfor thisinstancetowork.Thiscommandlinemaycontainspaces.Flagcanhave thesevalues: W ifthislineisusedforawIQ.ThewIQ'sconfigfileisread.Theprocessischeckedifitisstillrunning.Theprocessisexpectedtowrite analivefile. ifthislineisusedforarouter.Theprocessischeckedifitisstillrunning.Theprocessisexpectedtowriteanalivefile.Ifatleastoneline ofthetypeRispresent,noconnectionprobingisdone. ifthislineisusedforotherprocesseswritinganalivefile.Thisisthe sameasRwiththedifferenceofnotinfluencingifconnectionprobingisdone. ifthislineisusedformiscprocesseswritingnoalivefile.Theprocess isonlycheckedifitisstillrunning.

1 2 3 4 5 6 7 A I

Thesevaluesforflagsshallbeused: wIQ: OMBmgr: SMSCClient: router: DriverCurry: W M M R M

Example $ORGAROOT/run/etc/wIQguard_proc_table:

60

Configuration W W R wIQ_a wIQ_b wIQ_a -c cnf/wIQ_a.cfg wIQ_b -c cnf/wIQ_b.cfg

router router -c Router.cfg

ThewIQdprocesstableisusedtostartupallprocesseswhichare notmonitoredbywIQguardandthewIQguarditself. ThewIQguardprocesstablecontainsallprocessesmonitoredbythe wIQguard.

4.2

Logging
InthefilewIQ.cfg,theoutputfortheprotocolfilecanbeconfiguredfreely. ThisisdonewiththevariablewIQ.LogInfoMessage(seepage 71). ThevariablewIQ.LogInfoMessagecancontainthefollowingvalues: Variable $(STATUS) $(METHOD) $(TYPE) Status Method Thestatustypeofthesession: Mnewmobileinitiatedrequest Nnewnetwork(wIQ)initiatedrequest Crequestcontinued Erequestended AAbortrequest RSMSreceived SSMSsent PreceivedPushrequest MSISDN Location Description

1 2 3 4 5 6 7 A I

$(MSISDN) $(LOC)

61

Configuration

Variable $(COINS) $(URL) $(TrAction) $(SeAction) $(ApAction) $(SessionID) $(TEXT) $(Phase) $(Alert) $(Error) $(CODE) $(LastOutType) $(Charset) $(Parameter) $(BrowseMode) $(ISODATE) $(CREATEDBENTRY) $(:REQUESTSNUMSESSION) $(:REQUESTSNUMTOTAL) $(:HandsetID) Create Amount

Description

RequestedURL TR(internaluse) Se(internaluse) Ap(internaluse) ID Text Phase1request Alert Err Language LastOut Charactersetofmessage Parameter BrowseorFinish

1 2 3 4 5 6 7 A I

Numberofrequestsinthissession Totalnumberofrequests ID

62

Configuration

Variable $(:TARIFFGROUP) $(:USSDGROUP) $(:INSTALLATIONDATE) $(HTTPREQTIME) Example: Tariff Grp IDate

Description

TimeusedfortheHTTPrequest

wIQ.LogInfoMessage=$(TYPE)$(STATUS):$(MSISDN):$(PARAMETER)=>$(URL)$(METHOD)$(:REQUESTSNUMSESSION)/$(:SESSIONNUM)/ $(HTTPREQTIME) mayhavethefollowingoutputasaresult: I:HT_LOADED:94763577:*100#=>http://servint2/wiq/ussd100.phpGet1/54/ 0.006

1 2 3 4 5 6 7 A I

Theloggingoutputfromallprocessesispipedto $ORGADATA/log/Protocol. Therearedifferenttypesoflogmessages. :D: :I: :W: :E: :P: Debug-Messages Information Warning Error Panic mayproducesimpleprogramerrors mayproducebadprogramflowerrors unabletocontinue--exiting

TheloggingofthePHPIncoreinterfacecanbefoundin $ORGADATA/log/PHPIncore.log.

63

Configuration

4.3

wIQ Internal
Theseinterfacesshouldnotbeused,wIQd(seesectionwIQdonpage 49) istheadministrationcommandinterface. Itismentionedhereforreasonsofcompleteness.

4.3.1

Commandline Options
ThewIQprocesssupportsthefollowingcommandlineoptions: Option -D -cConfigFile Description Turnsondebugging. Specifiestheconfigurationfile(relativeto other$ORGADATA)forthisinstanceofthe wIQdprocess. Ifthisoptionisnotgiven,thefile $ORGADATA/cnf/wIQ.cfgisused. Displaystheusagemessage.

1 2 3 4 5 6 7 A I

-h

Toreloadnewconfigurationfiles,thewIQhastobestoppedandstarted again. ThiscanbedonebywIQd stop -Atoleavethedatabaseuntouched,and thenstartitagainwithwIQd start -A. AnothermethodistosendaTERMsignaltothewIQprocessesandwaitfor theautomaticrestart,ifyouhavemadeacrontabentryforrestartinghanging processes. Databaseentriesarereadoncepersession.

64

Configuration

4.3.2

Signal Handling
Thefollowingunixsignalsarehandled: SIGTERM,SIGINT SIGUSR1 SIGUSR2 ControlledterminationofthewIQ Toggledebugginginfos Configurationreload.Allconfigurationfileswillbe readagainandwillbecomeimmediatelyactivefor allnewsessions.Allopensessionswillbelongto theoldconfiguration. Acorruptconfigurationfilecausesthe wIQtoexit! The Interface_wIQ.cfgisnot loaded!Iftheportorthehosthavebeen changed,thewIQmustberestarted again(wIQstop/start).

1 2 3 4 5 6 7 A I

4.4

Environment Variables
$ORGAROOT:Thisvariablesetsthebasedirectoryofinstalledsoftware. $ORGADATA:Thisvariablesetsthebasedirectoryofthesoftwaredataarea.

4.5

wIQ: Configuration Files

ThewIQmainprocesswhichisalsocalledwIQusesdifferentkindsofconfigurationdata. Toavoidconfusion,thisprocessiscalledwIQcoreinthefollowing. BecauseyoumaystartmorethanonewIQcoreprocess,itisusefultodifferentiatebetween localconfigurationdatawhichmustbedifferentforeachcoreprocess(for exampletoconfiguretheportonwhichtheprocesswaitsforatcpconnection) and

65

Configuration globalconfigurationdata,whichshouldbethesameforallwIQcoreprocesses.

4.5.1

Interface_{processname}.cfg: wIQ Configuration File Variables

Thefollowingfieldsarereadfromaprocess-specificconfigurationfile.Thedefaultnameandlocationforthisfileis: $ORGADATA/cnf/Interface_{processname}.cfg ThismeansthataprocesswhichiscalledwIQ_aalwaystriestoread Interface_wIQ_a.cfg Thisfileishostdependent! Thereforeismustnotbesynchronizedfromanyotherhosts! Thisfilemustcontainthefollowingfields: Variable wIQ.Port i Type Description Portonwhichthe USSDgatewaysystem connectstothiswiqd instance mandatory nodefaultvalue TheIPaddressorhostnameofthelocal hostsinterfaceon whichtheUSSDgatewaysystemconnects tothiswiqdinstance mandatory nodefaultvalue

1 2 3 4 5 6 7 A I

wIQ.Interface

IPaddress: n[1..3].n[1..3]. n[1..3].n[1..3]. hostname: c[1..256]

66

Configuration Example Interface_wIQ.cfg: #Example Interface_wIQ.cfg wIQ.Interface =wiq21 wIQ.Port =5834

4.5.2 4.5.2.1

wIQ.cfg: wIQ Configuration File Variables License

AllPush-relateditemshavetocheckthelicenseentryandare ignoredifthereisnoPushlicense(seesection6.2onpage140). Theconfigurationfile$ORGADATA/cnf/wIQ.cfg containsthefollowing variables: Variable Type c[0..256] Description Filenamerelativeto$ORGADATA. ThisfileisrefreshedifwIQreceives anymessagewithinthelast AliveTimeinterval. optional Default: $ORGADATA/tmp/{processname}.alive Intervalinseconds. wIQexpectsatleastonereceived messageduringthisinterval. 0meansthatnomessageis expected. mandatory nodefault

1 2 3 4 5 6 7 A I

wIQ.AliveFile

wIQ.AliveTime

0..3600

67

Configuration

Variable wIQ.maxPushRequestsPerHour

Type 0..MaxReq PerHour

Description NumberofmaximumPushrequests perhour optional Default:MaxReqPerHour Determinesthebehavioronamissingping. 1=Panic 0=close/opensockets optional Default:0 Determinestheonewhoisbilledfor negativecontent optional Default:dest MaximumnumberofPushrequests perhourindependencyfromoverall optional Default:100 TimeinsecondsthePushsession waitsforaresultofSMSorUSSD interaction.Ifnoresultisreceived duringthistime,theresultofthe Pushrequestis SUCCESS. TheHTTP-addressofthedatabase configurationpage.Ifitisset,the subscriberisredirectedtothispage ifthedatabasecontainsnoentryfor his/herMSISDNoritcontainsinvalid entriesrelatingtohis/herMSISDN.

wIQ.MissingPingPanic

{0,1}

1 2 3 4 5 6 7 A I

wIQ.PushBillNegativeCoins

{"source", "dest"}

wIQ.PushQuota

0..100

wIQ.PushSessionTimeout

n[0..60]

wIQ.ConfigurationUrl

c[1..256]

68

Configuration

Variable wIQ.DefaultLanguage

Type c[2]

Description Countrycodeofthedefaultlanguagetobeusedifnotspecifiedby asubscriber.Examples:en,de, ro. Default:nodefault HandsetIDforautomaticcreationof databaseentries.Itisusedifredirectionisdisabled. optional Default:1 Thismessagewillbesenttothe subscribertoconfirmtheinputtoa form. Themaximumnumberoftemporary entriesinthehistorylistforonesession optional Default:10 OnallHTMLpagescontainingsyntaxerrors,thismessageissentto themobilestation. mandatory nodefault OnallHttpErrorsandonallinvalid htmlpages,thismessageissentto themobilestation. mandatory nodefault

wIQ.DefHandsetID

1 2 3 4 5 6 7 A I

wIQ.FormConfirmationMessage wIQ.HistoryEntries

c[1..256]

WIQ.HttpSyntaxError

c[1..256]

wIQ.HttpError

c[1..256]

69

Configuration

Variable wIQ.IMSIrequired

Type TRUE/ FALSE

Description IfTRUE,theIMSIhastobestoredin thedatabaseorsentwiththe request. optional (necessaryifIMSIisusedforbilling) nodefault Default:FALSE Thisvariabledefinesthevalidvalue forthecharacterset(tag<meta>, attributecontent,valueofcharset)ontheHTMLpage.Onlyon valueisallowed.Ifthelineismissing,thepageisconsideredtobe ISO-LATIN1.Italsodefinesthecharactersetwhichisusedfortheconversionifthecustomersetshis preferredcharset. localeCharSet PrefCharSet iso local notset ucs2 ucs2

wIQ.localeCharSet

c[0..256]

1 2 3 4 5 6 7 A I

Windows-1251 iso

ISO-LATIN 1

iso

iso

iso

optional wIQ.LicenseWarn i Iftherequestsperminuteare greaterthanorequal LicenseWarn/100*maxrequests,a warningappears.

70

Configuration

Variable wIQ.LogInfoMessage

Type c[1..]

Description Configurationoftheoutputofthe protocolfile(seesectionLogging onpage 61) Numberof(7bit)characterswhich canbesenttothehandsetasa maximum(validforSMSandUSSD) optional Default:160 IfthewIQexpectstogetnpreinput andgetlessthannpreinput,this messageissenttotheMS. mandatory nodefault Themessagedisplayedatthehandsetifthelicenselimitisreached.The sessionisalwaysclosedifthismessageissent. mandatory nodefault ThemessagedisplayedattheMSif aURLwasnotfound mandatory nodefault ThemessagedisplayedattheMSif WIQhasaninternalproblem,e.g.a SessionobjectisnotintheSessionListobject. mandatory nodefault

wIQ.MessageLength

[1..182]

wIQ.MissingInput

c[1..256]

1 2 3 4 5 6 7 A I

wIQ.NoServiceMessage

c[1..256]

wIQ.NotFoundMessage

c[1..182]

wIQ.PanicMessage

c[1..182]

71

Configuration

Variable wIQ.SMSBrowseError

Type c[1..182]

Description ThemessagewillbesenttoasubscriberwhorequestedaSMSthat couldnotbedeliveredandthe modefortheUSSDsessionis BROWSE,e.g.SMScouldnotbe delivered!Press*togoback!. mandatory nodefault Themessagewhichwillbesenttoa subscriberwhenherequestsaSMS serviceandthemodefortheUSSD sessionistocontinuethesession, e.g.AnSMShasbeensenttoyou, press*togoback. mandatory nodefault ThemessagewillbesenttoasubscriberwhorequestedaSMSthat couldnotbedeliveredandthe modefortheUSSDsessionisFINISH,e.g.SMScouldnotbedelivered! mandatory nodefault Themessagewhichwillbesenttoa subscriberwhenherequestsaSMS serviceandthemodefortheUSSD sessionisFINISH,e.g.AnSMShas beensenttoyou. optional

wIQ.SMSBrowseMessage

c[1..182]

1 2 3 4 5 6 7 A I

wIQ.SMSFinishError

c[1..182]

wIQ.SMSFinishMessage

c[0..182]

72

Configuration

Variable wIQ.StatisticBilling

Type on/off

Description Activatesstatisticbilling. optional Default:off Thetimeoutforasessioninseconds. mandatory nodefault IfwIQreceivessomeunexpected inputandthismessageisdefined,it issenttothesubscriber.Otherwise ifthemessageisnotdefined,the lastvalidHTMLpageinthehistoryis sentagain. optional default:notset

wIQ.Timeout

wIQ.UnexpectedInput

c[1..256]

1 2 3 4 5 6 7 A I

IftheparameterswIQ.maxPushRequestsPerHourandwIQ.PushQuotaare bothset,wIQwilltakethehigherrestriction,whichmeansthesmallervalue forRequestsPerHourforPush. Thisisaglobalconfigurationfilewhichshouldbethesameonall hosts!(ShouldbesynchronizedfromeverywIQhost!!)

ExampleforwIQ.cfg:
#Example wIQ.cfg

#### Time after the session is canceled wIQ.Timeout wIQ.LicenseWarn =30 =80

73

Configuration

wIQ.HistoryEntries

=10

#The entry is optional, default is 160 and the entry could be 0..182. #For SMS only 160 chars are allowed! wIQ.MaxMessageLength = 160

### Push specfic configuration wIQ.PushSessionTimeout wIQ.PushBillNegativeCoins wIQ.PushQuota wIQ.PushMaxRequestsPerHour =10 =dest =75 =1000

1 2 3 4 5 6 7 A I

#### Process supervision wIQ.AliveTime wIQ.MissingPingPanic =60 =0

#### billing specific configuration wIQ.Billing wIQ.CoinPrecision wIQ.StatisticBilling =on =3 =off

### Some Message if something goes wrong wIQ.NotFoundMessage wIQ.TimeoutMessage wIQ.PanicMessage wIQ.NoServiceMessage wIQ.UnexpectedInput wIQ.MissingInput =Requested service not found =Request timed out; try again =Internal error; try again =Service currently not available; try again =Unexpected Input =Missing Input

74

Configuration
wIQ.HttpError wIQ.HttpSyntaxError wIQ.PostpaidInfo =Http Error =Http Syntax Error =That will cost you something; proceed?

#The following messages are only relevant if SMS is licensed wIQ.SMSFinishMessage wIQ.SMSBrowseMessage back! wIQ.SMSFinishError wIQ.SMSBrowseError back! =An SMS has been sent to you! =An SMS has been sent to you! Press '*' to go =Unable to deliver page as SMS! =Unable to deliver page as SMS!Press '*' to go

# Please comment the next line if you want config with defaults # If subscriber has no entry in the database and the ConfigurationUrl # is set, he is redirected to it. # If it is not set the entries are created with defaults.

1 2 3 4 5 6 7 A I

#wIQ.ConfigurationUrl wIQ.DefHandSetID

=http://od-scp-1:8080/wiq_handset.html =1

# The following Value will be returned by the UrlConversion and # can be found in $(URLCONV) if the Url was not matched in the # URLconversion.(pre|post).cfg "<url>" stands for the special # case that the entire Url shall be inserted if it could not be # converted. wIQ.UrlConvUnkPre wIQ.UrlConvUnkPost =<url> =<url>

#Information log message format wIQ.LogInfoMessage =$(TYPE) $(STATUS):$(MSISDN):$(PARAMETER)=>$(URL) $(METHOD) $(:REQUESTSNUMSESSION)/$(:SESSIONNUM)/$(HTTPREQTIME)

#IMEI stuff, only valid if IMEI is licensed

75

Configuration
wIQ.IMEI=0 wIQ.IMEINetworkQuery=0 wIQ.MapNetworkTimeout=10 wIQ.IMEIValidityTime=1d wIQ.IMEIBlacklist=0 wIQ.IMEIBlacklistURL=http://localhost:8080/blacklisted.html

#local charset #wIQ.localeCharSet=WINDOWS-1251

##EOF

1 2 3 4 5 6 7 A I

4.6

Configuration Files
wIQusesthefollowingconfigurationfiles: Interface_{processname}.cfg Thisfilecontainslocalconfigurationdata. wIQ.cfg Thisfilecontainsglobalconfigurationdata. Ussd2URL.cfg* ThisfileexplainstheconfigurationandhandlingoftheincomingUSSD string. ValidURL.cfg* ThisfiledescribeswhichURLcanbeaccessed. SMS2Service.cfg* ThisfileisusedformappingfromSMScontenttoURLs. URL2SMS.cfg* Inthisfile,itisdefinedhowanSMSissent. DBDefaults.cfg Thisfiledeterminesthedefaultsfordatabasecreationindependenceon theMSISDNpatternofthesubscriber.

76

Configuration HotKeySet.cfg Thisfilegivesthemappingtableaccordingtowhichthecharactersare enteredbythesubscriber. wIQ2opsc_in.cfg ThisfiledefinestheconnectiontotheOPSCin_tm process(INbillingsystem Allthesefilesacceptthe";"charactertospecifycommentsinthefiles. Group-specific Files: Ussd2URL.cfg* ValidUrl.cfg* SMS2Service.cfg* Url2SMS.cfg* SMS-specific Files: SMS2Service.cfg* Url2SMS.cfg* General Files (i.e. used for SMS and USSD): wIQ.cfg DBDefaults.cfg HotKeySet.cfg IN Billing-specific Files wIQ2opsc_in.cfg

1 2 3 4 5 6 7 A I

77

Configuration

4.6.1

Ussd2URL.cfg*: USSD to URL Mapping Table

Thewiqdusesgroup-specificmappingtablestoconverttheservicenumbers enteredbythesubscribertoInternetURLs.Thesetablesarelocatedin $ORGADATA/cnf/Ussd2URL.cfg*] andconsistsoflines-separatedby NEWLINE-ofthefollowingfieldsseparatedby<TAB>: SERVICE METHOD URL SESSIONTYPE TheydescribehowtheincomingUSSDrequestisprocessedinwIQ. Thefieldshavethefollowingformat:

USSD to URL Mapping Table: Fields

Field SERVICE Type 1,2or3digitsfromthe set(*,#)followedbya numericservicenumber, andfinishedwitha#. Aseriesof*digitscan followthisservicenumberaswellas*variable whereavariablehasto startwithaletter OR 7YwhereY=any numberfrom0-9 {"GET","POST"} onlyoneofthesestrings isallowed Description TheUSSDservicenumber

1 2 3 4 5 6 7 A I

METHOD

TheHTTPrequesttype (GET/POST)

78

Configuration

USSD to URL Mapping Table: Fields

Field URL SessionType c[1-256] {"FINISH","BROWSE", "SMS"} onlyoneofthesestrings isallowed Type Description TherequestedURL Ifaserviceisrequested byservicenumber,the SessionTypeis"FINISH" andthepagecontains nolinksorforms,the sessionendsafterdisplayingthispage.Ifthe SessionTypeis "BROWSE",thesession continues.Thisfieldhas noinfluenceonUSSD phase1handsets. Ifthesessiontypeis "SMS",anSMSwillbe selectedasthebearer fortheselectedservice.

1 2 3 4 5 6 7 A I

Toenableagroupspecifichomepage,itispossibletodefinethehomepage intheUssd2Urlmappingtable. Thedescriptorforthehomepageis*#. Thedescriptorfordefaultserviceis*default#. Thisentrywillbeusedifnoservicedefinitionmapstotherequestedone.This hastobethelastlineinthefile. Example:

*100# <TAB> <TAB> GET BROWSE <TAB> http://www\.orga\.com/ussdtest/index\.htm

*101*par1*par2# <TAB> GET <TAB> BROWSE *102 <TAB> <TAB> FINISH GET

<TAB> http://www\.orga\.com/input\.cgi?var1=par1&var2=par2 <TAB> http://www\.orga\.com/end\.html

79

Configuration
*120# <TAB> *# <TAB> #100# <TAB>BROWSE *#100*1*2# <TAB>BROWSE *default# <TAB>BROWSE <TAB> SMS GET <TAB> http://www.orga.com/index3.html <TAB> http://www.orga.com/homepage.html

<TAB> GET BROWSE <TAB> GET

<TAB> http://www.orga.com/indexHash.html

<TAB> GET <TAB> http://www.orga.com/indexExtended.html <TAB> GET <TAB> http://www.orga.com/default.html

4.6.2

Solution
ItisallowedtodefineoneUSSDservicenumberinmultiplewayswithdifferenttypesofpreinput.Inadditiontothis,adefaultrulemaybedefinedwhich isusedifnomappingisfoundforthecurrentinput. TheformatoftheconfigurableUSSDstringis *ussd_service_number[anumberof"*numerical_constant"][anumberof "*variable_name]# 1,2,or3digitsfromtheset(*,#) 100..149 isasequenceofnumbers isauniquenameforavariablewhich mustbeusedintheURLdefinition, too. Themaximumnumberof*perlineis20.Thismeansthatthenumberof numericalconstantsplusthenumberofvariablenamesmustbesmallerthan orequalto19. where ussd_prefix ussd_service_number numerical_constant variable_Name

1 2 3 4 5 6 7 A I

80

Configuration Example for a USSD to URL Mapping Table: USSD *100# *100*1# *100*1*10# *100*var1# *100*var1*var2# *101# *101*1# *101*1*var1# *101*1*var1*var2# URL http://www.orga.com http://www.orga.com/ index_100_1.html http://www.orga.com/ index100_1_10.html http://www.orga.com/ script.cgi?par1=var1 http://www.orga.com/ script.cgi?par1=var1&par2=var2 http://www.orga.com/index101.html http://www.orga.com/ index101_1.html http://www.orga.com/ script2?par1=var1 http://www.orga.com/ script2?par1=var1&par2=var2 Mode BROWSE BROWSE BROWSE BROWSE BROWSE BROWSE BROWSE BROWSE BROWSE

1 2 3 4 5 6 7 A I

Description of the Matching Algorithm: a)Searchforthehighestexactmatchofservicenumberandnumericalpreinput(highestmeansthehighestnumberof*). b)Ifthereareanymatchesfroma),searchtheresultsforthehighestnumber ofmatchingvariableinput.

81

Configuration Example: Theinput*101*1*#ismappedthefollowingway: Theresultsofa)arethefollowinglines: *101*1*# *101*1*var1# *101*1*var1*var2# Nowtaketheresultsfroma)andsearchforthehighestmatch: Result:Theline*101*1*var1#istakenforUSSDmapping. ThiswillhavethefollowingeffectonaUSSDsessionusingthemappingtable example: USSD *100# *100*1# *100*1*10# *100*2# *100*2*10# *100*1*10*4# URL http://www.orga.com http://www.orga.com/index_100_1.html http://www.orga.com/index100_1_10.html http://www.orga.com/script.cgi?par1=2 http://www.orga.com/script.cgi?par1=2&par2=10 http://www.orga.com/index100_1_10.html andthe4isusedasapreinputfortheresultof therequest. http://www.orga.com/script.cgi?par1=2&par2=10 andthe4isusedaspreinputfortheresultofthe request. http://www.orga.com/index101.html http://www.orga.com/index101_1.html

1 2 3 4 5 6 7 A I

*100*2*10*4#

*101# *101*1#

82

Configuration

USSD *101*1*1# *101*1*1*1#

URL http://www.orga.com/script2.cgi?par1=1 http://www.orga.com/script2.cgi?par1=1&par2=2

Thisnewmappingalgorithmallowstheoperatortoperformaverycomplex configurationofhisservices.

1 2 3 4 5 6 7 A I

83

Configuration

4.6.3

ValidURL.cfg*: Valid URL and Variable Inclusion Table

ThewiqdsearchesthelistofvalidURLsbeforerequestingaURLfromtheinternet.Thislistcanbefoundin $ORGADATA/cnf/ValidURL.cfg* witheachline-separatedbyNEWLINEcontainingthefollowingfieldsseparatedby<TAB>: <URL><TAB><VARIABLES><TAB><MECAPS><TAB><BillingFlag><TAB><OverridePermissions> TheValidURLtablemustincludeatleastthe<TAB>characterforthebilling flag,evenifnobillingisused: Valid URL Table: Fields Field URL VARIABLES Type RE[1..256] Comma-separatedstringsas definedinthe followingtable ValidURLVariableson page 86 Description AvalidURLasregular expression AllowtheURLtoaccessthe givenvariables

1 2 3 4 5 6 7 A I

84

Configuration Valid URL Table: Fields Field BillingFlag n[1] Type Description 0=Nobillingisperformed forthisURL,nopricetags areallowed. 1=Billingisperformed,but nopricetagsareallowedin HTMLcontent. 2=Billingisperformed, pricetagsareallowedin HTMLcontent. Thisfieldistakentoproveif thispageisallowedto overridethesession settings. Onlysession-related settingsarecontrolledby thisfield.Thecontentcostspecificsettingsarelocated intheBillingFlag! Ifnodescriptorisgivenin thisfield,thepermissions aresettoNONE.

OverridePermissions

comma-separatedstring

1 2 3 4 5 6 7 A I

85

Configuration Inthefollowingtable,thecolumnVARIABLESliststhosevariableswhichcan beusedinthefieldVARIABLESinthetableabove: Valid URL Variables VARIABLES MSISDN (alwaysavailable) LANG SRC* MS DB Description ThesubscribersMSISDN. TransmittheAccept-Language headerinHTTPrequestsformultiple languagesupport. SeethesectionMultipleLanguage Reportonpage 35 ThelocationoftheMS. Languagecodeorucs2(ifmessage wascodedinUCS2). IfthedatabaseentryofPHASE1is equalto0,theMAPPhasecapabilitiesofhandsetornetworkareused. Elsethedatabaseentryisused. ThesubscribersPIN. HandsetIDfromsubscriberdatabase. USSDGroupfromsubscriberdatabase TariffGroupfromSubscriberdatabase Anonymousanduniqueidentityfor oneMSISDN.

1 2 3 4 5 6 7 A I

LOC (optional) CODE (optional) PHASE (alwaysavailable)

MS MS DB/MS

PIN HANDSETID (alwaysavailable) USSDGROUP (alwaysavailable) TARIFF (alwaysavailable) WIQUSERID (alwaysavailable)

DB DB DB DB

86

Configuration Valid URL Variables VARIABLES INSTALLDATE FIRSTUSEDATE LASTUSEDATE SESSIONNUM SESSIONTIMELAST SESSIONTIMETOTAL REQNUMTOTAL REQNUMSESSION PREFCHARSET REQCONTENT SRC* DB DB DB DB DB DB DB DB DB MS Description Thecreationdateofthesubscribers databaseentry. Thesubscribersfirstdateofuseof thewIQ. Thesubscriberslastdateofuseof thewIQ. Thetotalnumberofasubscribers sessions. Thetimeinsecondsofthesubscriberslastsession. Thetimeinsecondsofallsubscriberssessions. Totalnumberofasubscribers requests. Thenumberofrequestsduringthe lastsession. Thesubscriberspreferredcharset settings. ThecontentofthelastUSSDorSMS request.Ifmessagewascodedin UCS2(sseCODE),thecontentof therequestisencodedasURL encodedULF-8UCS2. Thetypeoftherequest:"SMS"or "USSD"

1 2 3 4 5 6 7 A I

REQTYPE

MS

* SRC: The source of information

87

Configuration
MS: Mobile station DB: Subscriber database

Inthefollowingtable,thecolumnBillingFlagliststhosevalueswhichcanbe usedinthefieldBillingFlagintheURLvariablestableonpage 84: Valid URL BillingFlag BillingFlag 0 1 2 Description NobillingisperformedforthisURL,nopricetagsare allowed. Billingisperformed,butnopricetagsareallowedin HTMLcontent. Billingisperformed,pricetagsareallowedinHTMLcontent.

1 2 3 4 5 6 7 A I

Ifthefieldisleftempty,wIQuses0asdefaultvalue.Inthiscase,a<TAB>is neededattheendoftheentry. IftheHTMLcontentcontainsapricetagbutthevalueofthebillingflagfor thisURLisnot2,wIQissuesanerrormessagetothesubscriberaswellasto thewIQoperator. Inthefollowingtable,thecolumnDescriptorliststhosevalueswhichcanbe usedinthefieldOverridePermissionsintheURLvariablestableonpage 84.

88

Configuration Thefieldcontainsacomma-separatedlistofoneormoreofthefollowingdescriptors.IfthereisnovaluegivenforOverridePermissions,thepermissions aresettoNONE. Valid URL : Permissions to Override Session Configuration from HTML Contents Descriptor NONE BEARER APARTY SMSINTERFACE USSDMODE ALL Description Nopermissionstooverridesessionattribute. Permissionstooverridethebearer. PermissionstooverridetheA-Party. Permissionstooverridethesmsinterface. Permissionstooverridetheussdmode. Permissionstooverrideall.

1 2 3 4 5 6 7 A I

Sessionsettingsfrompageswhicharenotallowedtooverridethesettingsare ignored. Example:

http://www.orga.com/all.* http://www.orga.com/sms.* MSISDN MSISDN 2 2 ALL SMSINTERFACE, BEARER

DifferentValidURLtablesmightbeconfiguredfordifferentsubscribergroups. Itisrecommendedtodefineexplicitlythepageswhichincludepricetagsto beaccessedviaHTTPS(secureHTTP)topreventmisuse(e.g.bypaybacksniffers)ofthepricetags.

89

Configuration

ToaccessthevariableontherequestedWebpage,youhaveto enterhttp_<variable>;seealsothesectionSubscribersIdentityDirectlytoURLsonpage 33. Example:

http://www\.orga\.com/ussdtest/index\.html<TAB> 0 http://www\.orga\.com/ussdtest/banking/.* <TAB> http://www\.orga\.com/ussdinputtest\.cgi <TAB> <TAB> 0 http://www.orga.com/index1.html <TAB> <TAB> 0 MSISDN <TAB> 0

MSISDN,IMSI,LOC REQCONTENT,WIQID

1 2 3 4 5 6 7 A I

4.7

SMS2Service.cfg*: SMS to Service Mapping Table

ThisfileisusedformappingfromSMScontenttoURLs. InthisfileitisdefinedhowanincomingSMShastobedealtwith. ThegrouprelatedSMS2Servicefilesarelocatedin$ORGADATA/cnf/. ThefilenamesareSMS2Service.cfg*. IfSMSservicesareenabledwithinthewIQlicense,atleastthedefaulttable SMS2Service.cfg*ismandatory.Thedefaulttableistakenifthefilefora specialgroupdoesnotexist. SMS to Service Mapping Table: Fields Field B-Party ...;RE Type Description UsedtomaptheMSISDNofthe recipient(wIQcouldreceiveSMS fordifferentnumbers). Usedtomapthecontentofa receivedSMStoanURL

Content

...;RE

90

Configuration SMS to Service Mapping Table: Fields Field Method URL Type {"GET","POST"} c[1..256]or "USSD_MAPPING" Description TheHTTPrequesttype,i.e.the contentoftheSMS. string[1..256]:AvalidURL;i.e. http://www.orga.com USSD_MAPPING:UsetheUSSD mappingtableofthegroupin whichthesubscribersendingthe SMSis. Ifthisvariableisdefined,the Ussd2URL.cfgofthegroupis takeninwhichtheuserwho madetherequestisin. Ifthecontentcannotbefoundin Ussd2URL.cfg,nothinghappens. IfUSE_AS_URLisfound,thecontentistakenasURL,butthecontentmustbefoundinValidURL (seepage 86). USE_AS_URL:Usethecontentas URL.Itwillbevalidatedwiththe ValidURLtableofthegroupin whichthesubscribersendingthe SMSis.

1 2 3 4 5 6 7 A I

"USE_AS_URL"

91

Configuration SMS to Service Mapping Table: Fields Field Bearer { Type Description Thisfielddefines -whethertheURLissentbackas SMSor -whetheraUSSDsessionis opened(BROWSE)or -whetherthemessageissentas USSDwithoutsession(FINISH), -whetherthemessageissentas USSDorasSMSifUSSDisnot possible IftheURLis URL=USSD_MAPPING,thebearer andthemethodaredefinedin anothertableandthusignored here. USSDPushisnotpossiblewitha Phase1handsetorinaPhase1 Network.Forthisreason,nothing happensifBROWSEorFINISHare definedasBEARER, BROWSE:USSDwithBROWSE mode FINISH:USSDwithFINISHmode FINISH-SMS:Ifanerroroccurs whilesendingadisplaymessage tothesubscriber,themessagewill besentasanSMS(ifthisispossible).

1 2 3 4 5 6 7 A I

"BROWSE", "FINISH", "FINISH-SMS

92

Configuration SMS to Service Mapping Table: Fields Field Type "SMS", "" } Description SMS:SMSisused. empty:Thebearershouldbe emptyifUSSD_MAPPINGisused, becausethebearerisalready definedinanothertable.Ifitis neverthelessdefined,itwillbe ignored.

Example:
124873264 12.* .* <TAB> OG1.* <TAB> GET <TAB> http://www.orga.com/index1.html <TAB> BROWSE

1 2 3 4 5 6 7 A I

<TAB> SMSNEWS.* <TAB> GET <TAB> http://www.orga.com/sms/new.html <TAB> SMS <TAB> .* <TAB> GET <TAB> http://www.operator.com/howto.html <TAB> SMS

TheBearerfieldisofspecialuseifthesubscriberisinaphase1networkor hasaphase1handset.InthiscasethesubscriberisnotabletoinitiateaUSSD sessionwithanSMSrequest.IfFINISH-SMSisusedasBEARER,inanerrorcase (whichwillhappeninthephase1case)themessagewillbesentasSMStothe subscriber.IfFINISHisused,themessagewillbethrownaway.IfanerroroccurswhileinitiatingaUSSDBROWSEsession,thereisnochancetoestablish thisviaSMS,sothemessagesarethrownaway.

4.8

URL2SMS.cfg*: URL to SMS Interface Mapping

Anothersubscribergroup-dependentconfigurationisusedtodeterminethe usedSMSinterfacethroughwhichashortmessagewillbesenttothesubscriber.TheA-PartyoftheSMSandtheUSSDMODEarealsoconfiguredin thesefiles. Inthisfile,itisdefinedhowanSMSissent. WheneveranSMSissent,thesystemlooksthroughthisfile.IfanSMSisre-

93

Configuration questedwithinaUSSDsession,thebehavioroftheUSSDsessionisdefinedin thisfile. USSDMODEisonlyrelevantwhenyouareinaUSSDsession! Thefilesarelocatedin$ORGADATA/cnf/. ThefilenamesareURL2SMS.cfg*. IfSMSservicesareenabledwithinthewIQlicense,thedefaultfile URL2SMS.cfg*ismandatoryandallothersareoptional.Ifafileforthegivengroupdoesnotexist,thedefaultfileistaken.

1 2 3 4 5 6 7 A I

94

Configuration IfanURLdoesnotmatchanylineofthefile,theSMScannotbesent.Adda linewiththeURLpattern.*asthelastlinetoavoidthisbehaviour. URL to SMS Interface Mapping Table: Fields Field URL Type ...;RE or "TEXT" TheURL. Reservedvalueforpushingtext messages. ToenableamappingforTEXT Pushmessages,thedescriptor TEXTmaybeaddedinthe URLfieldofthemappingtable. Thelinewiththisdescriptoris takenforPushtextmessages whichshouldbesentover SMS. Thisfielddeterminestheused SMSinterfacetosendanSMS ofthisURL. MAPSMS0:fireandforget MAPSMS1(optional):passto SMSConerror MAPSMS2:passdirectlyto SMSC TheMSISDNwhichisusedas theA-Party. FINISH:Thesessionisclosed immediatelyandanacknowledgementmessage(wIQ.SMSFinish-Message)issentifnot empty. Description

1 2 3 4 5 6 7 A I

SMSInterface

{"MAPSMS[0,1,2]"}

A-Party USSDMODE

number {"FINISH",

95

Configuration URL to SMS Interface Mapping Table: Fields Field Type "BROWSE" Description BROWSE:Thesessionstays openandanacknowledgementmessage(wIQ.SMSBrowse-Message)issent. REDISPLAY:Thesessionstays openandtheactualpageis displayedagain.

"REDISPLAY" }

USSDMODEisonlylookedupifaSMSisrequestedfromwithinanUSSDsession,otherwiseitwillbeignored. Example: http://www.orga.com/news.* <TAB> MAPSMS0 <TAB> 123456789 <TAB> FINISH .* <TAB> REDISPLAY TEXT <TAB> FINISH <TAB> MAPSMS2 <TAB> 123456789 <TAB> 7777 <TAB> MAPSMS0

1 2 3 4 5 6 7 A I

4.8.1

USSD Session Action after a SMS is Requested

IfanSMSisrequestedfromwithinaUSSDsession,somethinghastohappen withthealreadyestablishedUSSDsession.Tohandlethiscase,theUSSDMODEinthefileURL2SMS.cfg*hasbeenadded.Itdeterminesthebehavior onUSSDlayeraftertheSMSisdeliveredcorrectlywithoneofthevaluesFINISH,BROWSEorREDISPLAY(seesectionURL2SMS.cfg*:URLtoSMSInterfaceMappingonpage 93). IfsendingoftheSMSwassuccessful,amessagedependingontheUSSDMODEwillbesenttothesubscriber.ThiswillbewIQ.SMSFinishMessagein caseofFINISHandwIQ.SMSBrowseMessageincaseofBROWSE.Ifanerror occurredwhilesendingtheSMS,anerrormessagedependingontheUSSD-

96

Configuration MODEwillbesendtothesubscriber.ThiswillbewIQ.SMSFinishErrorincase ofFINISHandwIQ.SMSBrowseErrorincaseofBROWSE. IfUSSDMODEisREDISPLAYandtherewasnoUSSDmessagesenttothesubscriberbefore,theUSSDsessionisclosedwiththeacknowledgementmessagewIQ.SMSFinshMessage(ifnotempty)aftertheSMSissentsuccessfully (orwIQ.SMSFinishErrorelse).Thiscasemighthappeniftheresponseofthe firstUSSDrequest(e.g.*100#)isanSMS. IfUSSDMODEisREDISPLAYandtherewasanUSSDmessagesenttothesubscriberbefore,theUSSDsessionstaysopenandtheactualpageisdisplayed againaftertheSMSissentsuccessfully(orwIQ.SMSBrowseErrorisdisplayed incaseofanerror).

4.9

DBDefaults.cfg: MSISDN-Dependent Database Defaults Table

Thisconfigurationisusedtodeterminethedefaultsfordatabasecreationin dependencyoftheMSISDNpatternoftheuser.Itisusefultosortforexample MSISDNsbelongingtodifferentoperatorstodifferentsubscribergroups.FurtherfieldsfordatabasecreationdefaultsaredefinedinwIQ.cfgbecauseit makesnosensetodefinethesedefaultsindependencyofMSISDNpatterns. ThefieldSERVICESsetsthevalueofAllowedServicesintroducedon page 43. Thefileislocatedin$ORGADATA/cnf/. ThefilenameisDBDefaults.cfg. Theformatofthefileis <MSISDN><TAB><GROUP><TAB><TARIFF><TAB><PHASE1><TAB><SERVICES><TAB><PREPOST><TAB><COSTINFO><TAB><PUSHCTL><TAB><PREFCHARSET><TAB><CREATEDB> ThisfileismandatoryevenifthereisnoSMSlicense!

1 2 3 4 5 6 7 A I

97

Configuration Atleastonelineismandatoryinthisfile. NotethatifaMSISDNdoesnotmatchanentryinthisfile,noservice atallisallowedforthisMSISDN.Soitisagoodideatoaddaline withadefaultforallMSISDNsaslastoronlyline. MSISDN Dependent Database Defaults Table: Fields Field MSISDN Group TARIFF PHASE1 ...;RE {1..63} number {0,1,2} Type Description PatternforthesubscribersMSISDN. Thedefaultvalueforthesubscribergroup. Thedefaultvaluefortariffclass. 0=automaticmapphase 1=alwaysassumemapphase1 2=alwaysassumemapphase>1 SMStoSMS:pureSMSservicesareallowed forthissubscriber. SMStoUSSD:ASMSrequestwithUSSD answerisallowedforthissubscriber. USSDtoSMS:SMSinitiatedbyaUSSDsessionisallowed. USSDtoUSSD:pureUSSDservicesare allowedforthissubscriber. SubscriberisallowedtoinitiateanUSSD messagetohimself. SubscriberisallowedtoinitiateanSMSto himself. SubscriberisallowedtoinitiateanUSSD messagetohimselfandothersubscribers.

1 2 3 4 5 6 7 A I

SERVICES

["SMS2SMS", "SMS2USSD", "USSD2SMS", "USSD2USSD"], "PUSH2USSD" "PUSH2SMS" "PUSHALL2USSD"

98

Configuration MSISDN Dependent Database Defaults Table: Fields Field Type "PUSHALL2SMS"] or [...],[...]... or "ALL" or "NONE" PREPOST COSTINFO PUSHCTL {0,1,2} {0,1,2,3,4,5} l[0,1,2] Description SubscriberisallowedtoinitiateanSMSto himselfandothersubscribers. Notethatitisallowedtocombineseveraloftheabovevalues separatedbycommas. ALL:Allservicesareallowed. NONE:Subscriberisnotallowedtouseany services. BillingPre-/Postpaiddifferentiation. Billingsubscriberinformation;seesection SubscriberInformationonpage 125. SubscriberPushprivacysettings: 0=NoPushallowedtothesubscriber 1=Pushallowedifsenderisrecipient 2=Pushallowedfromanyone. Charactersetofmessage(seesectionPrefCharSetonpage 45) IfCreateDBissetto1("YES")adatabase entrywiththegivendefaultsisinsertedfor theMSISDN. IfCreateDBissetto0("NO")thegiven defaultfordatabaseinsertionisused,but nodatabaseentryisinserted.

1 2 3 4 5 6 7 A I

PREFCHARSET CREATEDB

{0,1,3,5,7} {0,1}

99

Configuration ThefieldCREATEDBoffersthenewfeaturetojustusethedefaultvaluesfor asubscriber,butnottosavethemintothedatabase.Thismeansthatthisvalueshavethesamelifetimeasthesubscriberssession. Example: 4916.* <TAB> 1 <TAB> 1 <TAB> 1 <TAB> 1 <TAB> 0 <TAB> 1 <TAB>1 0 <TAB> 2 <TAB> 0 <TAB> 0 <TAB> 1 <TAB> 1 <TAB> 1 <TAB> 1 <TAB> ALL<TAB> SMS2USSD, 1 SMS2SMS 0

4917.* <TAB> 2 <TAB> SMS2SMS<TAB> 2 <TAB> .* <TAB> <TAB>0 3 <TAB> <TAB>

1 2 3 4 5 6 7 A I

4.10 ProviderMap.cfg
Thisconfigurationfileisusedforbilling(seesectionProviderList/ProviderMap.cfgonpage 121).

4.11 wIQ2opsc_in.cfg
ThisconfigurationfileisusedforINbilling(seethesectionINBillingConfiguration/wIQ2opsc_in.cfgonpage 122).

4.12 License File

$ORGAROOT/run/lib/License Theexpirationdateofthislicense,thecustomer,andthemaximumnumber ofsubscribersinthedatabaseandthemaximumnumberofrequestsperhour aredefinedinthelicensefile. YouneedanextralicenseforSMS,CDR,andINBilling!

100

Configuration

Ifthemaximumnumberoftransactionsperminuteisreached,all requestswillbeabortedfortherestoftheminute.

YouneedanextralicenseforPush!

YouneedanextralicenseforSMSclient!

1 2 3 4 5 6 7 A I

YouneedanextralicenseforCurryDriver!

YouneedanextralicenseforRouter!

YouneedanextralicenseforbinaryESMS!

Youneedanextralicenseifyouwanttousebothbinaryandtextual ESMS!

101

Configuration

4.13 HotKeySet.cfg: Configuration File for Character Sets

ThewIQusesamappingtabletoconvertthecharactersenteredbythesubscribertolinknumbersonthepreviousmenupageandthenumberinginformationfordisplayinglinks.Thetablemustcontainatleastoneline. Thistableislocatedin$ORGADATA/cnf/HotKeySet.cfgandconsistsof lines(separatedbyNEWLINE)ofthefollowingfieldsseparatedby<TAB>: id inputcharset outputcharset

Thefieldshavethefollowingformat: Configuration File for Character Sets Table: Fields Field ID InputCharSet OutputCharSet i c[12] c[9] Type ID Theinputinterpretationcharset Theoutputnumberingstylecharset Description

1 2 3 4 5 6 7 A I

Inthefollowingtable,someexamplesareshown: Hand SetId 1 2

Input Character Set 123456789*0# abcdefghij*0#

Output Character Set 123456789 abcdefghij

Thenexttableshowstherelationshipbetweenthecharactersandtheirfunctionality:

102

Configuration

Input Set c[1..9] c[10] c[11]

Functionality followlink1..9 freeforfuture implementation Thisisaspecialcharacterwhichis usedtosendthecurrentUSSDpage asanSMS.Ifthiskeyispressed,a SMSrequestforthecurrentpage hastobeinitiated(onlyduringa USSDsession). Thischaractercanbeconfigured independentlyofthehandset. Youshouldpayattentiontothefact thatthecharactershouldnotcorrespondtooneofthecharactersrepresentingalinkasotherwise,this linkisfollowed.Itisrecommended tousethecharacter0.

Output Set c[1..9]

Functionality Displaynumber forlink1..9

1 2 3 4 5 6 7 A I

c[12]

freeforfuture implementation

103

Configuration

1 2 3 4 5 6 7 A I

104

The Router

5
1 2 3 4 5 6 7 A I

Therouterdistributesthemessagefromtheconnecteddriverstothe connectedwIQsandviceversa. Adrivercanbee.g.theNSGortheSMSCclient.Itactsasaserverforthe driversandasaclientinthedirectionofthewIQs.Inbothdirections,the messagescanbedirectedMSISDN-dependent.Messagesofthedriverscan alsobedirectedservice-dependent.MessagesforunavailablewIQs/drivers canbedirectedfromtheroutertoavailableones. ItispossibleforawIQtosendmessagesoptionallyviaaNSGoraSMSCor thatmessagescanbetriggeredsothatwIQsendsthem. Forthedifferentprotocols(SMPP,CIMD,CMG/UCP),clientscanalsobe connectedviatheroutersothatmessagescanbesentviathecorresponding SMSCs.

105

The Router

1 2 3
5.1
5.1.1

Driver Types, Services, and Routing Algorithm

Driver Type
Adrivertypecanbedt_PUSH,dt_SMSC,dt_SMSordt_USSD(onlyvalidfor PushandSCMessages). dt_PUSH: dt_SMS: dt_USSD: dt_SMSC: PushMessage SMSmessage. USSDmessage. SMSmessagewhichshouldbesentdirectlytoanSMSC(ifconnected)

4 5 6 7 A I

106

The Router

5.1.2

Service
Eachdriverisassignedtoaservice. AserviceisPush,NSG,USSD,CURRY(USSDnotsupportedatthemoment). AdriverwhichisassignedtoPushcanhandledt_PUSHmessages. AdriverwhichisassignedtoUSSDcanhandledt_USSDmessages. AdriverwhichisassignedtoNSGcanhandledt_USSDanddt_SMSmessages. AdriverwhichisassignedtoCURRYcanhandledt_SMSanddt_SMSC messages.

5.1.3

Routing Algorithm
FormessagesinthedirectionofwIQs,aroutingalgorithmcanbedefined. Ifso,thereisexactlyonealgorithmwhichisMSISDN-based. Ifthereisnoroutingalgorithm,themessageissentroundrobin(whenmore thanonewIQofthisserviceisavailable). Formessagesinthedirectionofthedrivers,aroutingalgorithmcanbe definedforeachdrivertype(dt_SMS,dt_SMSC,dt_USSD,dt_PUSH).The routingalgorithmisalsoMSISDN-based.Ifthereisaroutingalgorithmforthe drivertype,themessageissentaccordingtotheroutingalgorithmofthis service.Ifthereisnoroutingalgorithm,themessageissentroundrobin (whenmorethanonedriverofthisserviceisavailable).

1 2 3 4 5 6 7 A I

5.2
5.2.1

General Information
Program Name
Theexecutableprogramnameisrouter. Itislocatedin$ORGAROOT/run/bin.

107

The Router

5.2.2

Command Line Options

-c<filename> Usefilename(relativeto$ORGADATA)asconfigurationfilefortherouter(insteadofthestandard nameRouter.cfg). Enabledebug SetDebugLevel Showusage

-D -V<NUMBER> -h

5.2.3

Regular Termination
TheroutercanbeterminatedbysendingaKILLsignaloraTERMsignal. WhenterminatedbyaKILLsignal,nofurtheractioncanbeperformed. WhenterminatedbyaTERMsignal,therouterwillcleanup.Sessionsare aborted.

1 2 3 4 5 6 7 A I

5.2.4

Enable/Disable DEBUG Information

WhentherouterreceivesaUSR1signal,itswitchesthedebuginformationon.

5.2.5

License
YouneedalicenceforRouter!

5.3

Configuration Data
TheconfigurationdataisstoredinUNIXASCIIfiles.Thefilesarereadbythe routertogetthenecessaryconfigurationdata.

-EachwIQmusthaveauniquename(uniqueforthisrouter) -Eachdrivermusthaveauniquename(uniqueforthisrouter)

108

The Router

5.3.1

Overview of the Configuration Files:

ThemainconfigurationfileisRouter.cfg.Thisfileconfigurestherouter. TheFileRouter.cfgislocatedin$ORAGADATA/cnf/Router. Otherfilenamesmaybeused(see-coption). OtherconfigurationfilesconfiguretheconnectiontothewIQsandthe drivers.

5.3.1.1

Configuring the Connections

ThefilenameforthewIQanddriverconfigurationfilesisaconcatenationof {wIQ,Driver},<_>,apattern(characters)and<.cfg>. Foreachrouter,thesefilesarelocatedinaseparatedirectorycalled $ORGADATA/cnf/Router/<RouterName>/Connections. TheremustbeonefileforeachconnectablewIQ.Toconfiguretheconnection tothewIQs,therouterreadsallfileswhichmatchthepatternwIQ_*.cfg. Theremustbeonefileforeachdriver.Toconfiguretheconnectiontothe drivers,therouterreadsallfileswhichmatchthepatternDriver_*.cfg. Therecanbeonlyonefileforeachdriver.

1 2 3 4 5 6 7 A I

5.3.1.2

Configuring the Routing Algorithms

TherecanbeonefilefortheroutingalgorithmofthewIQs.Toconfigurethe wIQroutingalgorithm,therouterreadsthefile wIQRoutingAlgorithm.cfg. Thisfileislocatedin $ORGADATA/cnf/Router/<RouterName>/Algorithms. Therecanbefilesfortheroutingalgorithmofthedrivers.Toconfigurethe driverroutingalgorithm,therouterreadsthefile Driver<PATTERN>RoutingAlgorithm.cfg,where<PATTERN>isfor thedrivertype.Thesefilesarealsolocatedin $ORGADATA/cnf/Router/<RouterName>/Algorithms.

109

The Router

5.3.2

File Router.cfg
Thisfileconfigurestherouter. ThefileRouter.cfgislocatedin$ORGADATA/cnf/Router. Theformatoftheconfigurationfileis Router.<VARIABLENAME>=<CONTENT><NEWLINE>.

VARIABLE NAME RouterName Mandatory Nodefault c[1..80]

Description Thenameoftherouter.Itis thenameofadirectoryforall otherconfigurationfiles. (Oneword,nowhitespaces allowed,charactersmustbe in[a-z,A-Z,1-9],_) Timeinseconds. 0meansnocheck.Whenthe routerhaslosttheconnection toawIQ,ittriestoconnectto thiswIQagain.Thispa-rametersetsthetimebetween twotries. Timeinseconds.Maximum timeperiodbetweentwo PINGssenttothewIQ(when nomessagearrivesforthat wIQ).0meansnoPING. Usedtodetectiftheother sideisdownoralive.Setsthe numberofunanswered PINGSsenttotheotherside.

1 2 3 4 5 6 7 A I

CheckOpenAgain

Optional. Default5 n[0...]

PingTimeWIQ

Optional Default25 n[0...]

MaxPongWaitCount

Optional Default3 n[1...]

110

The Router

VARIABLE NAME PingTimeDriver Optional Default25 n[0...]

Description Timeinseconds.IfnoPING oranyothermessagearrives fromadriverwithin PingTimeDriverseconds,the routermustsendaPINGto thisdriverandwaitfora PONG.0meansnoPING. IfTRUE,anSMSmessage whichhasthetag</smsc> willbedeliveredaccordingto theroutingalgorithmof dt_SMSC.IfsettoFALSE,it willbedeliveredaccordingto theroutingalgorithmof dt_SMS. Sizeoftheinternalbufferfor messagestothewIQ:The routerstores(foreachwIQ separately)allmessagesifthe wIQisbusy.Ifthebuffersize reachesthislimit(0=no limit),therouterwillblockall newconnections.

DeliverToSMSC

Optional DefaultFALSE TRUE,FALSE

1 2 3 4 5 6 7 A I

wIQsendBufferSize

Optional Default:0 n[0..]

Example for Router.cfg Router.RouterName=router_1 Router.CheckOpenAgain=5 Router.PingTimeWIQ=25 Router.PingTimeDriver=25

111

The Router

5.3.3

File Driver_<PATTERN>.cfg
Thesefilescontaintheconfigurationdataforeachdriver. Theyarelocatedin $ORGADATA/cnf/Router/<RouterName>/Connections. Theyconfigurethename,theportonwhichthedrivercanconnect,andthe serviceusedforthedefinedport. Itisrecommendedthatthe<Pattern>containstheuniquedrivername. WhennoDriver_*.cfgfileexists,aPANICmessageisprintedandthe routerisstopped. Theformatfortheconfigurationfilesis Driver.VARIABLENAME=<CONTENT><NEWLINE> Allvariablesaremandatory. VARIABLE NAME Name Service Port Interface

1 2 3 4 5 6 7 A I

Type c[1..80] {NSG|Push|CURRY} n c[1..250]

Description Uniquename. Servicehandledbydriver. Portnumberforthisdriver. Hostname(realnameorIP address)onwhichthe driverisstarted.

112

The Router

Oneachport,notmorethanonedrivercanconnect!Soeachdriver mustconnecttoanotherport. -Thenamemustbeuniqueforeachdriver. -IfaportisconfiguredtohandleCURRY,newNetworkInitiated (NI)SMSwillbesenttoit. -IfaportisconfiguredtohandleNSG,newNetworkInitiated (NI)USSDandSMSwillbesenttoit. -IfaportisconfiguredtohandlePush,newNetworkInitiated (NI)Pushwillbesenttoit.

1 2 3 4 5 6 7 A I

113

The Router Example for Driver_<PATTERN>.cfg FileDriver_GW_1.cfg: Driver.Name=USSSGW_1 Driver.Service=NSG Driver.Port=5321 Driver.Interface=od-scp-1.orga.com

5.3.4

File wIQ_<PATTERN>.cfg
ThesefilescontaintheconfigurationdataforeachwIQ.Theyarelocatedin $ORGADATA/cnf/Router/<RouterName>/Connections. WhennowIQ_*.cfgfileexists,aPANICmessageisprintedandtherouter isstopped. Theformatfortheconfigurationfilesis wIQ.VARIABLENAME=<CONTENT><NEWLINE> Allvariablesaremandatory. VARIABLE NAME Name Active Port Host Type c[1..80] {TRUE} n[1..1024] c[1..250] Description UniqueName. Active(TRUE) Portnumber. Hostname(realnameorIP-address).

1 2 3 4 5 6 7 A I

-IfthevaluesforthefieldNameexistmorethanonceforall wIQ_*.cfgfiles,anerrormessageisprinted.ThewIQ_*.cfg filefortheduplicatewIQisignored.

114

The Router Example for wIQ_<PATTERN>.cfg FilewIQ_wiq1.cfg: wIQ.Name=WIQ1 wIQ.Active=TRUE wIQ.Port=5444 wIQ.Host=wiq.orga.com

5.3.5

File wIQRoutingAlgorithm.cfg
ThefilewIQRoutingAlgorithm.cfgcontainsthecompletedataforthe routingalgorithminthedirectionofthewIQs.Thisfileismandatory.Itis locatedin$ORGADATA/cnf/Router/<RouterName>/Algorithms. Withthisfile,theoperatorcandefineMSISDN-basedroutinginthedirection ofthewIQs. Theformatfortheconfigurationfilesis EXPR<TAB>NAME<NEWLINE>(TABisTabulator)

1 2 3 4 5 6 7 A I

Tag EXPR NAME

Value {*,anyotherRE} c[1..80]

Description Regularexpressiondefiningthe MSDISDN. DefinedaswIQ.Namein {wIQ_*.cfg.,...,}.

Foreachline,aMSISDNwhichfitsEXPRisdirectedtothewIQcalledNAME. -Onelinewith"*"mustbedefined(theDEFAULT,shouldbethe lastline). -Whenmorethanonelinefits,firstlinefits.

115

The Router Example: AllmessagesfromaMSISDNstartingwith1andanoddnumberaredirected toWIQ1,theevenonestoWIQ2.AllotherMSISDNsaredirectedtoWIQ3(this means,WIQ3istheDEFAULT). RegularExpression 1*[13579]$ 1*[24680]$ * DirectedtoWIQ...(definedinfieldNAME) WIQ1 WIQ2 WIQ3(thisistheDEFAULTWIQ)

TheFilewIQRoutingAlgorithm.cfgmaylooklikethis: 1*[13579]$<TAB>WIQ1<NEWLINE> 1*[24680]$]$<TAB>WIQ2<NEWLINE> *<TAB>WIQ3<NEWLINE>

1 2 3 4 5 6 7 A I

5.3.6

Files Driver<Pattern>_RoutingAlgorithm.cfg
ThefilesDriver<Pattern>_RoutingAlgorithm.cfgcontainthe completedatafortheroutingalgorithminthedirectionofthedrivers. Theyarelocatedin $ORGADATA/cnf/Router/<RouterName>/Algorithms. Withthesefiles,theoperatorcandefineMSISDN-basedroutingforadrivertypeseparately.Aroutingalgorithmcanbedefinedforeachdrivertype. Whennofileforadrivertypeisavailable,thedriversareselectedroundrobin. Thepatternforthefilenamemustbeselectedaccordingtothistable: Driver-Type dt_SMS dt_SMSC Pattern SMS SMSC

116

The Router

Driver-Type dt_USSD dt_PUSH

Pattern USSD Push

(e.g.fordriver-typedt_SMSDriverSMS_RoutingAlgorithm.cfg) Theformatfortheconfigurationfilesis EXPR<TAB>NAME<NEWLINE>(<TAB>isTabulator)

Tag EXPR NAME

Value {*,anyotherRE} c[1..80]

Description RegularexpressiondefiningtheMSDISDN. DefinedasDriver.Nameinany {Driver_*.cfg.,...,}.

1 2 3 4 5 6 7 A I

Foreachline,aMSISDNwhichfitsEXPRisdirectedtothedrivercalledNAME. -Onelinewith"*"mustbedefined(theDEFAULT,shouldbethe lastline). -Itisbestwhenthedrivercanhandletheassigneddrivertype. -Whenmorethanonelinefits,thefirstlinefits. Example: File DriverSMS_RoutingAlgorithm.cfg 1*[13579]$<TAB>CURRY1<NEWLINE> 1*[24680]$<TAB>SMSSD1<NEWLINE> *<TAB>SMSSD2<NEWLINE>

117

The Router

1 2 3 4 5 6 7 A I

118

Additional Features

6
1 2 3 4

For all features described in this chapter, an extra license must be available. These features are not included in the wIQ standard license.

6.1

Billing
YouneedanextralicenseforSMSandBilling!

5 6 7 A I

6.1.1

Introduction
wIQbillsthesubscriberforthegeneralusageofthewIQsystemandtheoperatorsGSMinfrastructure.Thisiscalledusagebilling. Additionally,thewIQsystemisabletomovemoneyfromthesubscribersaccounttothecontentprovidersaccountforaccesstotheproviderscontent. Thisiscalledcontent-basedbilling. Tocalculatethecostofinformation,apricetaghastobeaddedtotheHTML pagethecontentprovidercreates. TheaccesstothiscontentshouldbeperformedinanencryptedwayviaHTTPS (secureHTTP)topreventmisuse.

119

Additional Features

6.1.1.1

Billing Mechanism
Therearethetwotypesofaccountsforsubscribersaswellasforcontentproviders: 1.) Prepaid 2.) Postpaid Prepaidaccountsholdtheownersaccountbalancewhichisdecreasedwith atransaction,whileforpostpaidaccountsthebillingsystemwritese.g.a monthlybillforalltransactionswhichthesubscriberhastopay. Thefollowingsectionshowstheimpactofprepaidversuspostpaidbillingon thewIQ. Prepaid Billing Prepaidbillingisonlysupportedforsubscribers,notforproviders.Forthese subscribers,wIQchecksthesubscribersaccountbalancebeforethedelivery ofanycontentanddeliversthecontentonlyifthesubscribersaccountissufficientforthecostofthistransaction. Afterthedeliveryofthisinformation,thecostisdebitedfromthesubscribers account. Forcontent-basedbilling,wIQtransfersthepartofthecostwhichiscalculatedbasedonapricetagintheHTMLpagefromthesubscribersaccountto thecontentprovidersprepaidaccount. Incaseofnegativepricetags(e.g.asabonus),wIQwillnotcontacttheIN billingsystem.Itwillonlywritepre-/postpaidCDRs. IfthesubscriberisunknowntotheINbillingsystem,aprepaidCDRiswritten forthesubscriber. Postpaid Billing Incaseofapostpaidsubscriber,wIQcreatesstandardwIQCDRticketsfor eachtransaction.Itisthetaskoftheoperatorspostpaidbillingsystemtobill thesubscriberforthesetransactionsappropriately. Iftheaccountofacontentproviderisapostpaidaccount,standardwIQCDR ticketsaregeneratedforthecontentprovidersaccountforeachtransaction whichincludesaHTMLpagethathasdefinedcontent-basedbilling.

1 2 3 4 5 6 7 A I

120

Additional Features

6.1.2

Modules
ThissectiondescribesallmodulesinvolvedinthewIQbilling.

6.1.2.1

Secure HTTP
Toe.g.accesspageswhichcontainpricetagsinasecureway,theoperator canusethesecureHTTP(https://)protocolintheValidURLtable(seesectionValidURL.cfg*: ValidURLandVariableInclusionTableonpage 84). PreviousversionsofwIQwereonlycapableofhandlingHTTPaccess. ItishighlyrecommendedtouseHTTPSforallpageswhichmight containpricetagsandwhicharenotreachedthroughasecureconnection.

1 2 3 4 5 6 7 A I

6.1.2.2

Price Tag
Toallowacontentprovidertoassociateapricewithhiscontent,awIQprice tagmightbeincludedintheheaderoftheseHTMLpages. ThefollowingexampleshowsthepricetagsXMLformat: <wIQ coins="100" provider="ORGA"/>

6.1.2.3

Provider List/ProviderMap.cfg
wIQaccessesthenewtabletomaptheprovidersname(includedintheprice tag)toanaccounttobechargedto. Thistableincludestheprovidersname(exactlyasinthepricetag)andthe providers(pseudo)MSISDN(eitherpre-orpostpaid),theIMSIaswellasaflag thatdefineswhetherthisaccountishandledbytheprepaidorbythepostpaid billingsystem(PrePostFlag,seealsosectionPrepaid/PostpaidDifferentiationonpage 129). Toallowthehandlingof(very)differentURLsbyonecontentprovideraccount,thelinesinthistablecontainfieldswithregularexpressionsforthe URLsvalidforthisproviderspricetags.wIQinterpretsallfieldsbehindthePrePostFlagasregularexpressionsdefiningtheURLswhichareallowedtocontainthepricetagofthecontentproviderbelongingtothisconfigurationline. IfnoURLsarementionedintheproviderlistes,allURLsareallowedtohave thisproviderspricetag.

121

Additional Features Thistab-separatedlist,withoneproviderperline,hasthereforethefollowing format: <provider> <TAB> <MSISDN> <TAB> <IMSI> <TAB> <PrePostFlag> <TAB> <reURL1> <TAB> ... <reURLn> Thefile$ORGADATA/cnf/ProviderMap.cfgcontainsthistable. Inthefollowing,youwillfindanexampleforalineinthisfilethatdefinesthe contentproviderORGAwiththeprepaidMSISDN1092387456. Forthiscontentprovider,pricetagsareallowedontheserverwww.orga.com andwww.agro.com.Onorga.com,thesecurehttpmightbeused. ORGA 1092387456 454612425879615 1 https?://www\.orga\.com/.*http://www\.agro\.com/.* Whenapricetagoccursinthecontent,wIQcheckswiththislistiftheprovider tagisvalidandifthisURLisvalidforthesubscriber.wIQrejectsthedelivery ofthecontent-withaconfigurableerrormessagetothesubscriber-ifthe providerortheURLisinvalid.ThisfilemustexistifthewIQbillingisswitched onintheconfiguration Therecanonlybeonelineforeachprovider,butitispossiblethat thereareseveralURLsforoneprovider. ForpushingtextorESMSsdirectly,therearepseudo-URLstobill these:"TEXT"and"ESMS".PleaseseethesectionPushInterface onpage 140forPushfeaturesandthesectionwIQEnhanced SMSonpage 183forESMSfeatures.

1 2 3 4 5 6 7 A I

6.1.2.4

IN Billing Configuration/wIQ2opsc_in.cfg
IfprepaidbillingviaanINbillingsystemisactivated(bylicenseandconfiguration),wIQreadsthefile$ORGADATA/cnf/wIQ2opsc_in.cfgatstartup toconnecttotheOPSCin_tmprocess.Thefilecontainsonlyonelinewiththe following(tab-separated)columns:
MSISDNmask <tab> hostname <tab> portnumber <tab> timeout

122

Additional Features MSISDNmask hostname portnumber timeout Notusedatthemoment Thehostnametoconnecttothe in_tm Theporttoconnecttothein_tm Thetime(inseconds)untilacommunicationtothein_tmproces runsintoatimeout(whenthereis noresponsefromin_tm)

1 2 3 4 5 6 7 A I

6.1.2.5

Billing
EverywIQtransactionthatincludesaURLforwhichbillingisswitchedoncreatesabillingeventtothesubscribersaccount,eitherprepaidorpostpaid.If content-basedbillingisallowedandthecontenttobedeliveredcontainsa pricetag(wIQcoins),wIQalsocreatesabillingeventtothecontentprovidersaccount.Again,thiscaneitherbeprepaidorpostpaid. TheprepaidaccountsareimplementedusingtheINfunctionalityoftheOPSC. Forpostpaidaccounts,wIQcreatesgenericwIQCDRtickets. Ifasubscriberrequestsabillablecontentandheisprepaid(orunknown)subscriber,wIQreservesthecostsintheINbillingsystemandevaluatestheanswer. IftheconnectiontotheINbillingsystembreaksdown,wIQtriestoreconnect beforeeachnewrequest.Thefollowingtabledescribesthereactionofthe wIQtotheresponsesoftheINbillingsystem: debitOK asksubscriberforcosts(ifconfiguredbysubscriber) andevaluateanswer OR sendcontentandsubmitreservedcosts send(configurable)messagetosubscriber

notenoughdebit

123

Additional Features

unknownsubscriber

send(configurable)errormessagetosubscriber andclosesession OR sendcontentandwriteaprepaidCDR send(configurable)errormessagetosubscriber andclosesession OR sendcontentandwriteaprepaidCDR writeHTTP-Errormessagetosubscriber writeHTTP-Errormessagetosubscriber

timeout

connectionerror misc.error

1 2 3 4 5 6 7 A I

IfthesubscriberanswersYEStothecosts,wIQsubmitsthecoststotheIN billingsystemandsendstherequestedcontenttothesubscriber.IfthesubscriberanswersNO,wIQcancelsthereservedcosts. Thissectiondescribeshowthebillingofthedifferentaccountsisperformed andwhichadditionalentitiesareneededtoaccomplishthis. Valid URL TheValidURLtable($ORGADATA/cnf/ValidURL.cfg*,seesection ValidURL.cfg*: ValidURLandVariableInclusionTableonpage 84)isextendedtocontainanadditionalbillingflag.Thenewformatofthelinesinthis filethereforeis <URL> <TAB> <PARAMETERS> <TAB> <BillingFlag>

124

Additional Features ThisflagdefineswhichtypeofbillingwIQusesforthisURL.Thefollowingtableshowsthevaluesvalidforthisflag: Value 0 1 2 Description NobillingisperformedforthisURL,nopricetagsare allowed. Billingisperformed,butnopricetagsareallowedinHTML content. Billingisperformed,pricetagsareallowedinHTMLcontent.

Ifthefieldisleftempty,wIQuses0asdefaultvalue. IftheHTMLcontentcotainsapricetagbutthevalueofthebillingflagforthis URLisnot2,wIQissuesawarningmessagetothewIQoperatorandtheinformationisdeliveredwithoutcontentbilling.Thispreventsaservicefrombeingstoppedifaserviceprovideraccidentallyinsertsapricetag. NotethatdifferentValidURLtablesmightbeconfiguredfordifferentsubscribergroups. Itisrecommendedtodefineexplicitlythepageswhichincludepricetagsto beaccessedviaHTTPS(secureHTTP)topreventmisuse(e.g.bypacketsniffers) ofthepricetags. Subscriber Information Thesubscribersmightwanttobeinformedabouttransactionsthatwillcost somethingandtheymightwanttocancelthetransactiondependingonthis information.Toaccomplishthis,thesubscriberdatabaseofthewIQincludes anewfieldCostInfo,andthewIQinformsthesubscriberdependingonthis valuewithaconfigurablemessage.

1 2 3 4 5 6 7 A I

125

Additional Features Thefollowingtableshowsallvalidvaluesforthisflag: Value 0 1 2 3 4 5 Description Askforeverytransactionwhichassociatescost. Askifadditionalcontentbillingwillbedone.Thesubscriber acceptstheoperatorscost,butnotthecontentproviders. Donotaskanything.Thesubscriberisawareofthecostand acceptsit. NeveraskforPush,otherwisealways.... ....askforPushandforadditionalcosts ....askanddonotacceptcontentcostifthereisnopossibility toaskfor

1 2 3 4 5 6 7 A I

URL Conversion IfabillingsystemisnotcapableofhandlingcompleteURLsinthebillingtickets,thewIQcanmaptheseURLstoothervaluesbymeansofthetableURLconv.Thetableconsistsoflineswiththeformat <URL regular expression> <TAB> <Billing value> wIQchecksthistablestartingatthetopforthefirstlinematchingtheURLof theactualtransactionandusesthe<Billing value>forthecommunicationwiththebillingsysteminsteadofthewholeURL.Ifthe<Billing value>fieldisleftempty,noconversionisdone,thebillingsystemmustthenbe capableofhandlingURLsinthetickets. Thistableexiststwice,onetablefortheusewiththeprepaidbillingsystemin thefile$ORGADATA/cnf/URLconversion.pre.cfg,oneforthepostpaidbillingsysteminthefile $ORGADATA/cnf/URLconversion.post.cfg. ThisenablestheoperatortohandletheURLconversiondifferentlyforthedifferentbillingsystemsinuse.

126

Additional Features IfwIQbillingisswitchedonintheconfiguration,bothtablesmustexist.wIQ issuesanerrormessageifatransactionoccurswhichneedsaconversiontable whichdoesnotexist. Thepseudo-URLs"TEXT"and"ESMS"arealsovalidforURLconversion.

6.1.2.6

Billing Scenarios for Push

Thebillingmechanismdependsondifferentvalues: DestinationMSISDN Theonewhoshouldreceiveamessageandnormallywouldnotpayfor anything. SourceMSISDN Theonewhoorderedtheserviceandnormallywouldpayforeverything Provider Theonewhoearnsmoneyforthepage-requestandisdefinedinside thewIQtagoftheHTMLpage. Coins ThedefinitionofcostinsidetheHTMLheader(maybenegative) alsocalledcontentcost TransportCosts Thedefinitionofcostsforthedatatransmission(alwaysgreaterthan or equallingzero)

1 2 3 4 5 6 7 A I

127

Additional Features Inthefollowingtable,youfindanexamplefordifferentbillingscenarios. Billing Example

Src MSISDN Dest MSISDN Povider Coins Transport Account SrcMSISDN Account Dest MSISDN Account Provider

PushBillNegativeCoins=source 11111 11111 22222 22222 33333 33333 15 -15 5 5 -5 -15 -5 +15 +15 -15

1 2 3 4 5 6 7 A I

PushBillNegativeCoins=dest 11111 11111 22222 22222 33333 33333 15 -15 5 5 -5 -15 -5 +15 +15 -15

Thisexampleshowswhoiswhenbilledforwhat. PleasebecarefulbysettingupabrowseUSSDsession.Thebilling willusethesettingsfromthefirstPushforthecompletesession!! Thismeansthesource-MSISDNhastopayforeverytransactionthe subscriberwillperformduringthissession!!

6.1.2.7

Billing of Regular ESMS

ARegular(sized)ESMSintegratesseamlesslyintheexistingbillingprocess flow.ItisbilledforTransportandcontentasconfiguredintherespective source(HTMLorPush)withintheregularwIQworkflow.

128

Additional Features

6.1.2.8

Billing of Long ESMS

TheLongESMSprocessingisslightlydifferent.TheLongESMSissplitintoa setofconcatenatedSMSsbytheLongESMSProcessormodule.Thecontent andtransportcostforthewholeSMSwillbebilledwiththelastoutgoingconcatenatedSMS.

6.1.2.9

Different Billing Types

General Remark: Itisuptotheoperatorsbillingsystem(s)tocomputetheactualcostassociated withatransactionforbothaccounts. ThewIQbillingticketsincludeinformationwhichisneccessary,especiallythe wIQcoinsdefinedintheHTMLcontent.Thebillingsystemshavetobeaware thatevennegativeamountsforwIQcoinsarepossibletopaythesubscriber, e.g.whenviewingthecontentprovidersadvertisements. Prepaid / Postpaid Differentiation Todistinguishbetweenpre-andpostpaidsubscribers,wIQaddsanotherfield Pre-Posttothesubscriberdatabasewhichmightholdthefollowinginformation: Value 0 1 2 Description Unknown. Prepaidsubscriber. Postpaidsubscriber.

1 2 3 4 5 6 7 A I

Subscribersunknowntotheprepaidbillingsystemaretreatedaspostpaid subscribersorpostpaidcontentproviders. AfterthesuccessfuldeliveryofthecontentaCDRiswritten. Thissecond"ticket"targetingthecontentprovidersaccountisofthetype IOWIQ(InternetOriginatedwIQticket)incontrasttothetickettargeting thesubscribersaccountwhichisofthetype"MTWIQ"(MobileTerminated wIQticket).

129

Additional Features TheIOWIQticketmightbeviewedasaninversionoftheMTWIQticket,asthe contentprovidershouldbedebitedifthesubscriberiscreditedandviceversa. Itisuptothebillingsystemtocomputetheactualcostofthetransaction. IN-based Billing ThewIQusesanOUM-basedquerytocheckifanaccounthassufficientfunds forthetransactiontobemade.Forthischeck,afirstqueryisused.Thecost ofthetransactionisreservedbythisqueryiftheaccountisfoundandthebalanceissufficient. Afterthesuccessfuldeliveryofthecontent,thewIQissuesaCallComplete messagetodebittheaccountwiththecostalreadyreservedbythefirstquery. Incaseofcontentwhichincludesapricetag,aqueryisnotonlymadeforthe subscribersaccount,butalsofortheaccountofthecontentprovider(read fromtheProviderMap). ThissecondtickettargetingthecontentprovidersaccountisofthetypeIOWIQ(InternetOriginatedwIQticket)incontrasttothe"ticket"targetingthe subscribersaccountwhichisofthetypeMTWIQ(MobileTerminatedwIQ ticket). TheIOWIQticketmightbeviewedasaninversionoftheMTWIQticket,asthe contentprovidershouldbedebitedifthesubscriberiscreditedandviceversa. Itisuptothebillingsystemtocomputetheactualcostofthetransaction. Postpaid Billing Asintheprepaidcase,thewIQcreatesforeachtransactionaMTWIQticket withtargetsthesubscribersaccount.Iftherewasapricetaginthecontent, wIQalsocreatesaIOWIQticketthattargetsthecontentprovidersaccount. Again,itisuptothebillingsystemtocomputetheactualcostofthetransaction.

1 2 3 4 5 6 7 A I

130

Additional Features BillingConfiguration FortheconfigurationofthewIQbillingsubsystem,thefollowingvariablesare addedtothewIQconfigurationfile$ORGADATA/cnf/wIQ.cfg: Variable wIQ.Billing Type c[1..5] Description Generalswitchtoswitchthe billingon/off. True,False,On,Off,1, 0,INarevalidvalues. Ifthevariableisnotfound,no billingisperformed. Ifbillingisswitchedoff,the otherbillingvariables(see below)arenotread. INactivatestheINbilling. Thenumberofdigitsinthefractionalpartofcoins(inoutput). ThisisthemessagewIQusesto informthepostpaid(ifINbilling isenabled)/all(ifINbillingisnot enabled)subscribersthata transactionwillcostsomething. ThisisthemessagewIQusesto informtheprepaidsubscribers thatatransactionwillcost something. (A)* ThisisthemessagewIQsendsif acontentwithanunknown providershouldbesent. optional Default:"" (A)*

1 2 3 4 5 6 7 A I

wIQ.CoinPrecision wIQ.PostpaidInfo

i c[1..256]

wIQ.PrePaidInfo

c[1.256]

wIQ.ProviderError

c[1..256]

131

Additional Features

Variable wIQ.INbillingUnknownSubscriberMsg

Type c[1..256]

Description ThisisthemessagewIQsendsif asubscriberisunknowntothe INbillingsystem.Ifnotdefined (defaultvalue),thecontentwill besentandsubscribergetsa prepaidCDR. (A)* ThisisthemessagewIQsendsif atimeoutwhilethecommunicationtotheINbillingsystem occurred.Ifnotdefined,the contentwillbesentandthe subscribergetsaprepaidCDR. Default:"" (A)* DecideifText-Pushmessages should 0-neverbebilled(default) 1-contentbillingshouldbe done 2-usagebillingshouldbedone Thisconfigurationvariabledoes onlyaffectText-Pushmessages billedviaIN. Thisvaluedefineshowtohandlenegativecoinsforaprepaid subscriber(willreceivemoney): 0:justwriteanINFOmessage intoprotocol 1:writeanprepaidCDR Default:0 (A)*

wIQ.INbillingTimeoutMesg

c[1..256]

1 2 3 4 5 6 7 A I

wIQ.INTextPushBillingType

wIQ.negativeINbilling

132

Additional Features

Variable wIQ.INnotEnoughDebit

Type c[1..256]

Description ThisisthemessagewIQusesto informprepaidsubscribersthat theyhavenotenoughcreditfor thiscontent. (A)* Maximumnumberofopenconnectionstoahost:portcombination.IfthequeuedHTTP requestsreachthislimit,wIQ rejectsmoreUSSDrequestswith anerrormessage. Default:0(nolimit) (A)* Messagesent(tosubscriber)if theinternalbuffer(see wIQ.maxHostConections)with queuedHTTPrequestsexceed thelimit. Default:"Thesystemisbusy, pleasetryagainlater." (A) Thisstringisusedforprepaid subscribersasconvertedURLif noexpressionintheURLconversiontablematches. Ifthestringis<url>,theoriginal URLwillbeused.Thisisthe default.

wIQ.maxHostConnections

1 2 3 4 5 6 7 A I

wIQ.BusyMessage

c[1..256]

wIQ.UrlConvUnkPre

c[1..256]

133

Additional Features

Variable wIQ.UrlConvUnkPost

Type c[1..256]

Description Thisstringisusedforpostpaid subscribersasconvertedURLif noexpressionintheURLconversiontablematches. Ifthestringis<url>,theoriginal URLwillbeused.Thisisthe default. Ifthebillingtypeofthe requestedpageisusagebilling (seeValidUrl.cfg)andthis parameterissetto1,thedebit ofthesubscriberischecked beforewIQloadstherequested Webpage. Ifthesubscriberdoesnothave sufficientdebitfortheWeb pageorifthesubscriberdoes notconfirmthecost,wIQdoes notloadtherequestedWeb page. 0-loadpagebeforeINreservation 1-firstdoINreservation/askfor confirmationandthenloadthe page

wIQ.INbillingNoLoad

1 2 3 4 5 6 7 A I

134

Additional Features

Variable wIQ.INbillingNoLoad cont.

Type

Description Iftherequestedpageisconfiguredforcontentbilling,wIQ mustloadthepagebeforethe INreservationtocheckthecost configuredinthepage. Thereforethisconfiguration variablehasnomeaningfor contentbilling. Thisvariabledoesonlytake effectifINbillingisused. Default:0 (A)*

1 2 3 4 5 6 7 A I

* This variable will only be read if IN billing is enabled.

TheconfigurationofwhatiswrittentotheCDRfilesisconfiguredinaseparateconfigurationfile$ORGADATA/cnf/Notifications.cfg. Eachconfigurationlineinthefilehasthefollowingsyntax: <class>.<number>.<variable> = <value> Value class number variable Description Notificationclass.Atthemoment,Postpaid,Prepaid, andStatisticaresupported. Consecutivenumberoftheentrystartingwith'1'. Thenameofaconfigurationvariable.

135

Additional Features Generalconfigurationvariables: Variable Type Address Format Description Theoutputtype.Currently'FILE'and'FIFO'aresupported. Thetargetdirectoryfortheoutput. Theformatoftheoutputstring(seebelow).

File-specificconfigurationvariables: File Filename WorkExtension FlushTime Description Filename-patternfortheoutputfile(withoutpath name).Seebelowforthetagsallowedhere. Fileextensionthatisusedwhilethefileisopen. Maximumtime(inseconds)afileisusedbeforea newoneiscreated.

1 2 3 4 5 6 7 A I

Fifo-specificconfigurationvariables: Fifo FlushSize FlushTime Description MaximumnumberofentriesthatarewrittentoaFIFO file. Maximumtime(inseconds)afileisusedbeforeanew oneiscreated.

136

Additional Features Theformatconfigurationstringmightincludethefollowingvariables: Value $(MSISDN) $(URL) $(URLCONV) $(LOCATION) $(COINS) $(DATE) $(TIME) $(IMSI) $(PREPAIDFLAG) Description MSISDNofthebilledparty(subscriberwithMTWIQ ticket,contentproviderwithIOWIQticket). TheoriginalURL. TheconvertedURL. Thesubscriberslocation(emptyforthecontentprovider). ThecoinsfromtheHTMLcontent(ifany). Thedatetheticketwascaused(Format:YYYYMMDD). Thetimetheticketwascaused(Format:HHMMSS). ThebilledpartiesifIMSIispresent. Thebilledpartiesprepaidflag.1meansprepaid; anythingelseistreatedaspostpaid.

1 2 3 4 5 6 7 A I

Thefilenameconfigurationstringmightincludethefollowingtags: Variable %H %M %S %d %m Description Hour Minute Seconds Dayofmonth Month Range 00-23 00-59 00-59 1-31 1-12

137

Additional Features

Variable %y %Y %s %% %t

Description Year(lasttwodigitsofyear) Year(fourdigits) Daylightsavingtime Thecharacter% unixtimestamp(thenumber ofsecondssince00:00:00 UTC,January1,1970)

Range 00-99 1900-... 0(no),1(yes),x (unknown) -

1 2 3 4 5 6 7 A I

6.1.3

Licensing
wIQusesalicensestringtoverifywhethertheoperatorisallowedtousethe productonaparticularmachine. ThislicensingmechanismisextendedtoallowextralicensingforthewIQbilling/INbillingmechanism.LicensingofINbillingwillalwaysinclude(normal= CDR-based)billing. Itisonlyallowedforanoperatortoswitchonthebilling(wIQ.Billing=Yes)or INbilling(wIQ.Billing=IN)ifthelicensestringissuedbyORGAincludesthebillinglicense.

6.1.4

Example
ThissectiondescribesatypicalwIQsessionwithonetransactionwhichalso involvescontent-basedbilling. 1.) ThesubscriberwiththeMSISDN1029384756choosesaservicenumber, e.g.*108#whichismappedbytheUSSDtoURLMappingtabletoa URLwhichusestheHTTPSprotocol. 2.) ThisURLisdefinedintheValidURLtableasvalidandhasthebilling definedas2(Billingisdone,pricetagsareallowedinHTMLcontent). 3.) wIQfetchestheURLfromtheinternetandlooksforapricetag.Theprice taginthispageis<wIQ coins=100 provider=ORGA>

138

Additional Features 4.) wIQnowlooksuptheproviderORGAintheProviderMapandgetsthe providersMSISDN,e.g.5647382910. 5.) Beforecommunicatingwiththebillingsystem,wIQchecksintheURLconvtablewhetheraconversionoftheURLshouldtakeplace. Inourcase,theURLisconvertedtothevalue357. 6.) wIQthenchecksthesubscriberdatabasesfieldPrePostforthebilling typeofthissubscriber,inthiscaseitis0(unknown) 7.) wIQnowcheckswiththeIN-OPSCwhetherthesubscriberisaprepaid oneandhassufficientdebitforthistransaction. 8.) ThisisthecaseandthewIQinreturntothisquerygetsthetotalamount thatthistransactioncosts. 9.) ThenthissubscribersdatabasefieldPrePostisupdatedtothevalue1 (Prepaid). 10.)wIQnowcheckswiththeIN-OPSCwhetherthecontentproviderisprepaidandhassufficientfundsforthistransaction. 11.)Thisisnotthecase,thecontentproviderhasapostpaidaccount. 12.)Thissubscriberhasconfiguredhispersonalconfigurationtoinformhim thatatransactionwithcontent-basedbillingistakingplace(CostInfoFlag 1,Askifadditionalcontentbillingwillbedone.),sowIQcreatesaMessagelikeThistransactionwillcost1.02Euros.Ok? 13.)ThesubscriberanswersthisquerywithaY 14.)ThewIQthenreturnsthevaluableinformationitretrievedfromthecontentprovidersHTMLpageand 15.)wIQrequeststheIN-OPSCtoperformthebillingforthesubscriber. 16.)Forthecontentprovidersaccount,awIQCDRiscreatedwhichtheoperatorspostpaidbillingsystemusestocreditthecontentprovider.

1 2 3 4 5 6 7 A I

139

Additional Features

6.2

Push Interface
YouneedanextralicenseforPush!

ThePushinterfaceofwIQinitiatesPushesbysendingHTTP-requests.Youdo nothavetodealwithwithprotocolinternalsofwIQortherouter.Thisallows youtocarryouteasilyyourownservicesontopofthisone.

6.2.1

General Architecture
TheWebinterfaceforPushisrunningasaFCGIonthewIQWebserver(oron anotherFCGI-enabledapacheserver).ClientscanconnecttotheFCGIviaHTTP.ToinitiateaPush,theclientsendsanHTTP-request(seethesection6.2.2.1 onpage 142fortheparameters)toitandreceivestheresultofthePushoperation(e.g.SUCCESSFULL)inthecorrespondingHTTP-response. BecausethewIQcorehastoprocesstheserequests,therehastobeaninterfacebetweenwIQandtheFCGIPushinterface.Thisisdonewiththehelpof therouterwhichconnectsthem. ThewIQcoregeneratesaUSSDPushoranSMS(dependingonthebearer) fromthedata,whichisthensenttothecorrespondingdriverviatherouter. ThedriverfinallydeliversthePushtothedestinationmobilephone.

1 2 3 4 5 6 7 A I

140

Additional Features

1 2 3 4
ForperformanceissuesitmaybeusefultoruntheFCGIPushinterfaceonanothermachinethanthewIQcore.Thismachinemustrun anFCGI-enabledapacheserver.

5 6 7 A I

6.2.2

Push-request and Response

ThePushFCGIexpectsitsinputparametersinaHTTP-requestaspostparametersorquerystring.Theformatforeveryparameterhastobename=value. TheanswercontainingastatusvalueforthePushoperationwillbesentback inthebodyofaHTTP-responseofthetypetext/html.

141

Additional Features

6.2.2.1

Push-request
ThefollowingtableliststhepossibleparametersforaPush-request: Parameters for the FCGI Push Interface Name dest src data Value TheMSISDNoftherecipient. TheMSISDNofthePushinitiator. snr:textcontainsaUSSDServicenumberwithoptionalpreinputandleading/ trailingstarandhashcharacters. url:textcontainsaURL. txt:textcontainsaplaintextmessage. seedataforthepossiblecontentsof text none,finish,finish-sms,browse,orsms Mandatory/ Optional Mandatory Mandatory Mandatory

1 2 3 4 5 6 7 A I

text sessiontype

Mandatory Optional. Default: finish. Optional

provider

Fordata=txtitispossibletosetaproviderwhogetsorpaysthenumberof coinswhicharedefined. Thedefinitionofcostfordata=txt messages. Needstobeincombinationwithprovider. Forsessiontype=smsitispossibleto definethesenderMSISDNofanoutgoingshortmessage.

coins

Optional

aparty

Optional

142

Additional Features Parameters for the FCGI Push Interface Name smsinterface Value Forsessiontype=smsitispossibleto definetheusedmethodorinterfaceto sendtheSMS (MAPSMS0,MAPSMS1(optional), MAPSMS2). Thisparameteroverridestheparameter wIQpush.awaitResponseintheconfigurationfileandcantakethevalues0 and1aslistedinsection6.2.3.2on page 146. Mandatory/ Optional Optional

response

Optional

1 2 3 4 5 6 7 A I

URLencodinghastobeusedforallspecialcharactersinthevaluefield,e.g. space,hash,... Example URL with query string: http://od-scp-1:8888/fcgi-bin/wIQpush?dest=1234567& src=1234567&data=txt&text=Hello%20world&sessiontype=finish NotethatURLencodingisusedintheexampleforthespacecharacter(%20).

6.2.2.2

Push-response
TheHTTP-responseoftheFCGIPushinterfaceincludesthestatusofthePush inthebodyofthereturnedpage.Thelayoutofthereturnedpagecanbeset withtemplates. Therearetwotypesoftemplates: 1.)Oneforstatusvaluesreturnedbytherouter/wIQcore. Therearestatusvaluesforsuccessandseveraltypesofpossiblefailures.

143

Additional Features 2.)OneforerrorsgeneratedbythePushFCGIitself. TherearesituationsforthePushFCGItogeneratetheansweronitsownwithoutcommunicatingwiththewIQcore: thePushFCGIrecognizesthatthemaximumnumberoftransactionsper minutegivenintheconfigurationfileisreached.Thenaresponse (PUSH_LIMIT_REACHED)isimmediatelysentback. AconnectionerrorbetweenthePushFCGIandtherouter/wIQcorehas happened,e.g.noconnectionpossible.Thenaresponse (CONNECTION_ERROR)issentback. ArequestfromtheFCGItotherouter/wIQcorehasbeentimedout,i.e. noanswerhascomebackduringthetimeoutperiodgivenintheconfigurationfile.Thenaresponse(REQUEST_TIMEOUT)issentback. NotethataclientusingthePushFCGIshouldbepreparedtohandle thecasethatthemaximumnumberoftransactionsperminuteis reached.Heshouldcancelsendingrequestsinthiscaseandtry againaminutelater. Thetemplatesareconfiguredintheconfigurationfile(seesection6.2.3.2on page 146). Duringstartup,thetemplatesfromthetemplatedirectoryarereadintointernalmemory.Ifyouchangethem,youmustsendaconfigurationreloadsignal tothewIQpushprocessforthemtobereread. TemplatesareHTMLfileswithavariable$(status)placedinthedirectory givenbywIQpush.TemplateDirectory.Beforeprintingthetemplate,thevariableisreplaced.

1 2 3 4 5 6 7 A I

144

Additional Features Example: Status Template

<HTML> <TITLE>Status</TITLE> <BODY> wIQ returned $(status)! </BODY> </HTML>

Result: wIQ core returned SUCCESS

1 2 3 4 5 6 7 A I

<HTML> <TITLE>Status</TITLE> <BODY> wIQ returned SUCCESS! </BODY> </HTML>

Notethatitwouldbealsopossibletowritejust$(status)inthe templateifyoudonotwantsurroundingHTML-tags.Ifyouwant thereasonforanerrortobehidden,youdonotinclude$(status)intheerrortemplate.

145

Additional Features

6.2.3

wIQpush Process
TheprocessnamedwIQpushisnormallylocatedin $ORGAROOT/apache/fcgi-bin/.

6.2.3.1

License
wIQPushservicesmusthaveanextralicenseentryinthewIQ licensefile.AsthePushFCGImustnotrunonthesamemachineas thewIQcoredoes,itmaynotbeabletocheckthelicensefile directly. Inafirststep,theFCGIitselfwillnotcheckthelicenseatall.Ifitsendsrequests tothewIQcoreandthewIQPushinterfaceisnotlicensed,theywillnotbe answeredandthePushFCGIwillsendanerrorafteratimeoutperiod. Infurtherversions,thecorrectlicenseentrywillbecheckedonstartupwitha specialrequestthatissenttothewIQcore.ItwillbeansweredwiththePush licenseentryifavailable.

1 2 3 4 5 6 7 A I

6.2.3.2

Configuration File
ThePushFCGIhasitsownconfigurationfile.Normallyitislocatedin $ORGADATA/cnf/wIQpush.cfg. Ifyouwanttouseadifferentconfigurationfile,youhavetosetitwiththe AppClassdirectiveinthehttpd.conf(seesection6.2.3.3onpage 150).

146

Additional Features Theconfigurationfilehasthefollowingentries: Push FCGI Configuration File Entries Name wIQpush.Port Type Default:Mandatory Type:i wIQpush.Interface Default:Mandatory Type:IPadressor hostname wIQpush.Pushes-PerMinute Default:Mandatory Type:1 Description PortonwhichthePushFCGI triestoconnecttotherouter/ wIQcore. InterfaceonwhichthePush FCGItriestoconnecttothe router/wIQcore. MaximumnumberofPushes thatwillbeperformedper minute.Ifthisentryissetto zero,thePushFCGIisdisabled. Notethattheoverallmaximumvalueisdefinedbythe limitfortransactionsper minuteinthewIQlicensefile. Switchesdebugoutputon whensetto1,otherwiseoff. Setsthelevelofdebbuging information. Numberofthreadsspawnedby theFCGIwhichwillaccept requests. Theperiodinsecondsuntilthe answertoarequestfromthe FCGItotherouter/wIQcore musthavearrived.

1 2 3 4 5 6 7 A I

wIQpush.Debug

Default:0(off) Type:i{0,1}

wIQpush.DebugLevel

Default:1 Type:i{0..9} Default:20 Type:i

wIQpush.NumberOfThreads

wIQpush.Request-Timeout

Default.25 Type:i

147

Additional Features Push FCGI Configuration File Entries Name wIQpush.Logfile Type Default:$ORGADATA/log/wIQpush.log Type:filename wIQpush.TemplateDir Default:$ORGADATA/templates Type:pathname wIQpush.ErrorTemplate Default:error Type:filename wIQpush.StatusTemplate Default:status Type:filename wIQpush.await Response Default:1(on) Type:i{0,1} Nameforthetemplateusedto reportstatus-responses. Ifsetto0,thePushFCGIwill generatea"SUCCESS"statusresponseonitsownwithout waitingfortheanswerofthe router/wIQcore.Therouter/ wIQcoreanswerwillonlybe writtentothelogfile! Ifsetto1,thePushFCGIwill waitfortheanswerofthe router/wIQcore. Namefortheerrortemplate. Pathtothedirectorycontaining thetemplates. Description Pathandfilenameofthelog file.Thismightalsobeapipe!

1 2 3 4 5 6 7 A I

NotethatwIQpush.RequestTimeoutshouldbeshorterthanthe HTTP-timeoutoftheclient-requestingthePush.Iftheclientisa browser,theHTTP-timeoutisnormally30seconds.

148

Additional Features Linesstartingwith#willbetreatedascomments.Lineswithunknownvariableswillbeignored.

1 2 3 4 5 6 7 A I

149

Additional Features Example: #wIQpush example config file wIQpush.Port=5838 wIQpush.Interface=od-scp-1 wIQpush.Pushes-PerMinute=100 wIQpush.Number-OfThreads=20 wIQpush.RequestTimeout=25 wIQpush.Logfile=/tmp/wIQpush.log wIQpush.TemplateDir=/tmp/templates wIQpush.ErrorTemplate=error_template wIQpush.StatusTemplate=status_template wIQpush.awaitResponse=1

6.2.3.3

Startup
FCGIprogramswillbestartedautomaticallyfromtheapacheserverinitsstartupprocedure.Inordertoachievethis,youhavetoaddlinessimilartothe followingtotheapacheconfigurationfilehttpd.confinthemoduleconfiguration,e.g.aftertheCGIconfiguration.Thisexampleassumesthatthe FCGIwillbeplacedinapache/fcgi-bin/:
PassEnv ORGADATA ORGAROOT FastCgiIpcDir /tmp/fcgi Alias /fcgi-bin/ "/home/wiq/WIQUSSD/apache/fcgi-bin/" <Location /fcgi-bin> Options -Indexes +ExecCGI SetHandler fastcgi-script </Location> FastCgiServer "/home/wiq/WIQUSSD/apache/fcgi-bin/wIQpush\" -initial-env ORGADATA\ -initial-env ORGAROOT

1 2 3 4 5 6 7 A I

TheFastCgiServerdirectivecantaketheparameter -initial-env ConfigFile=filename whichwilloverridethevaluefortheconfigurationfile,e.g.

FastCgiServer "/SCMbd/AGrote/SCMws/WIQUSSD/apache/fcgi-bin/ wIQpush"

150

Additional Features
-initial-env ConfigFile=/tmp/wIQpush.cfg

willsettheconfigurationfileto/tmp/wIQpush.cfg. Apachecanbestartedwiththecommandapachectl startorbythewIQ startupsequence.

6.2.3.4

Signals
Thefollowingsignalswillbehandled: TERM:Thisisconsideredarequestfor"clean"shutdown,i.e.finishanythingyouareinthemiddleof,freeresources,andexit.Apacheusesthis signaltorequesta"graceful"processshutdown(e.g.itisusedby apachectlrestartorapachectlstop). USR1:Togglesdebugoutputonoroff. USR2:Thissignalwilltriggeraconfigurationreload MakesurethatthePIDofthewIQpushprocessgetsused.

1 2 3 4 5 6 7 A I

6.2.3.5

Configuration Reload
Theportandinterfacesettingswillnotbechangedbyaconfigurationreload. Ifyouwanttochangethesevalues,youhavetoterminatetheprocess.All othervalues(includingthetemplates)willbereloadedfromtheconfiguration filewhenreceivingthesignalforreconfiguration.

6.2.3.6

Termination
Whentheprocessisterminatedbyreceivingasignal,itwillbeimmediately restartedbytheapacheserver.Inordertoterminatewithoutautomaticrestart,youhavetostopthewholeapacheserver(apachectlstop).

151

Additional Features

6.2.3.7

Exit Codes
IfacriticalerroroccursandwIQpushhasnotyetaccesstothelogfile,itexits withthefollowingexitcodes: Exit Code 11 12 13 14 Reason Cannotreadconfigurationfile. Configfilehaswrongformat. Cannotwritetologfile. Miscellaneousinternalerrors.

1 2 3 4 5 6 7 A I

Ifpossible,errorswillbereportedtothelogfile.Inthiscase,theexitcodeis 1andthereasonisreportedtothelogfile. Notethattheexitcodewillbeloggedintheapacheerrorlogfile.

6.2.3.8

Logging
Thelogfiledefaultsto$ORGADATA/log/wIQpush.log. IfyouwantittobesharedwiththewIQlogfile,changeitto $ORGADATA/.logger Notethatyouhavetoexpandthe$ORGADATAvariabletoitsactual path,writing$ORGADATAisnotpossible ThisisthepipecreatedbythewIQdwhichismovedtoanewfiledaily. Informationaboutprocessingtherequests,errors,warningsetc.arelogged intothisfile.Dataisalwaysappended.

152

Additional Features

6.2.4

Use Cases
TheseusecasesregardaclientsendingaHTTP-requesttothePushFCGI.The PushFCGIrequestsananswerfromthewIQcoreviatherouter.Ifthisone comesin,thePushFCGIgeneratesaHTTP-responseandsendsitbacktothe client.

6.2.4.1

Client Aborts Request

TheclientofthePushFCGIabortstherequest.AstheFCGIlibrarydoesnot signalthistothePushFCGI,itwillcompletethewholerequestandtrytogive theresponsebacktotheclient.Thisisthepointwhereitwillrecognizethat theconnectionwasabortedandcanceltherequest.

6.2.4.2

Connection Failure
IftheconnectionbetweenthePushFCGIandtherouter/wIQcoreisbroken, thePushFCGIwillgenerateanerror-responseonitsown(seethesection 6.2.2.2onpage 143).Theresponsewillbegeneratedoutoftheerrortemplateandsentbacktotheclient.

1 2 3 4 5 6 7 A I

6.2.4.3

Web Server Timeout

IftheWebservertimesouttheconnectionfromtheclienttothePushFCGI (e.g.HTTP-timeout)whilethePushFCGIisstillinprogressgettingtheanswer, thereisthesamesituationaswithaclientabort.

6.2.4.4

Request Timeout
Iftheresponsefromtherouter/wIQcoretoanrequestofthePushFCGItakes toolong,thePushFCGIwillgenerateanerror-response(seethesection 6.2.2.2onpage 143).Theresponsewillbegeneratedoutoftheerrortemplateandsentbacktotheclient.

6.2.4.5

wIQ Core Reports Status

IfarequestofthePushFCGIisansweredwitharesponsefromtherouter/wIQ core,thePushFCGIwillgeneratearesponse(seethesection6.2.2.2on

153

Additional Features page 143)fortheclient.Theresponsewillbegeneratedoutofthestatustemplateandsentbacktotheclient.

6.2.5

Remark on Billing
Ifyouwanttousebillinginconjunctionwithpushingtext(data=txt),theURL youhavetousefortheprovidermap(seesection6.1.2.3onpage 121)and URLconversion(seethesectionURLConversiononpage 126)isTEXT. IfyouwanttobilladirectlypushedESMS,theURLtouseinthesefilesis ESMS.

1 2 3 4 5 6 7 A I

154

Additional Features

6.3

SMS Center Interfaces

YouneedanextralicenseforSMS!

6.3.1

General
AdriverisusedforthecommunicationbetweentheSMSCclientandthe router.TheSMSCclientcommunicatesonCURRYviaOMB,therouterover TCP/IP.

1 2 3 4 5 6 7 A I

155

Additional Features

1 2 3 4 5 6 7
TheOMBprovidessingleandmultipleconsumerandproducerqueues.

A I

6.3.1.1

CURRY Protocol
TheCURRYprotocolwrapstheformerSMSCclientprotocols SMPP EMI

156

Additional Features CIMD. ItisadaptedfromCIMD. TheCURRYprotocolisconnectionoriented.Nearlyeverymessageisansweredwitharesponse.

6.3.1.2

OMBmanager
TheOMBmanagerisusedtohandlethemessagesentviaOMB.

6.3.1.3

Program Name
TheexecutableprogramnameisDriverCurry.Itislocatedin $ORGAROOT/run/bin.

1 2 3 4 5 6 7 A I

6.3.1.4

General
Whenstarted,theDriverCurrytriestoconnecttotheOMBmanager.Ifitis notpossible,itprintsanerrormessageandretriestoconnecteveryDrv.ConnectAgainseconds. WhenithasaconnectiontotheOMBmanager,ittriestoconnecttherouter. Ifitgetsnoconnectiontotherouter,itprintsanerrormessageandtriesagain everyDrv.ConnectAgainseconds. Whenconnectedtotherouter,theroutercansendmessages. Whentheconnectiontotherouterislost,itprintsanerrormessageandtries toconnecteveryDrv.ConnectAgainseconds. WhentheconnectiontotheOMBmanagerislost,itprintsanerrormessage. TherouterwillnotsendmessagesandtriestoreconnecttotheOMBmanager everyDrv.ConnectAgainseconds.Theconnectiontotherouterstaysopen. Whenreconnected,theroutercansendmessages.

6.3.1.5

Signals
WhentherouterreceivesaUSR1signal,itswitchesthedebuginformationon. IfthedriverreceivesaUSR2signal,ithastorereadtheconfigurationdataand maybecloseitsoldconnectionsandopennewones.

157

Additional Features Thestatusofallmessagesthathadnotbeensentarenotchanged. Themessagesmustbesentoverthenewconnections.

6.3.1.6

Command Line Options

Option -c<pattern> Meaning Usepattern(relativeto$ORGADATA)asconfiguration filefortherouter(insteadofthestandardname $ORGADATA/DriverCurry.cfg). Enabledebug. Setdebuglevel. Showusage.

-D -V<number> -h

1 2 3 4 5 6 7 A I

6.3.2

Driver Configuration
TheconfigurationfileforDriverCurryisnormallylocatedin$ORGADATA. TheFilenameisDriverCurry.cfg. Ifapatternispassedwiththe-coption(forexampleDriverCurry/ Conf.cfg),thedriversearchesforconfigurationfile $ORGADATA/DriverCurry/Conf.cfg. Theformatfortheconfigurationfilesis Drv.<VARIABLENAME>=<CONTENT><NEWLINE>

158

Additional Features Ifthevalueforaparameterisinvalid,thedefaultvalueistaken(ifitapplies, sothisisonlypossibleforoptionalparameters).Otherwisetheprogramterminateswithapanic. Variable Name Drv.RouterPort Type Mandatory Default:Type: n[1024... 65535] Drv.RouterPing Default:25 Type:n[0...] Drv.RtPingTout Default:25 Type:n[0...] Drv.RouterHost Mandatory Default:Type:c[...] Drv.OmbMgrPort Mandatory Default:Type: n[1024... 65535]] Drv.OmbMgrHost Mandatory Default:Type:c[...] Ombmanagerhost PortnumberofOmbmanager Pingtimeinsecondstorouter/ wIQ Timegapinsecondsbetween checksformissingPONGs HostofwIQ/router Description PortnumbertowIQ/router

1 2 3 4 5 6 7 A I

159

Additional Features

Variable Name Drv.OmbMgrPing

Type Default:25 Type:n[0...]

Description PingtimeinsecondstoOMBmgr

Drv.ConnectAgain

Optional Default:5 Type:n[1...]

Mustbegreaterthan0. IftheconnectiontotheOMBmgrortherouterislost,the drivertriestoconnecttothat deviceeveryDrv.ConnectAgain seconds. NameofOMBqueueforincomingmessages(messagesfrom SMSCclient).

Drv.SMSCQueueIn

Mandatory Default:Type:c[...]

1 2 3 4 5 6 7 A I

Drv.SMSCQueueOut

Mandatory Default:Type:c[...]

NameofOMBqueueforoutgoingmessages(messagesto SMSCclient).

Drv.SessionIdStart

Optional Default:1 Type:n[1...]

StartnumberforTRIDonsession layer.

Drv.SessionIdDelta

Optional Default:1 Type:n[1...]

IncrementofTRIDonsession layerforeachmessage.

160

Additional Features

Variable Name Drv.ValidityPeriod

Type Default: 1200 Type:n[...]

Description TimeinSeconds. Thisvalueisaddedtotheactual timeonthehosttogetthe VALIDITY_PERIOD_ABSOLUTE (ifthemessageisnotdelivered totheMSatthisdate,themessageexpires)

Example file DriverCurry.cfg: Drv.RouterPort=9999 Drv.RouterPing=10 Drv.RouterHost=223.255.255.2orxxx.orga.com Drv.OmbMgrPort=8888 Drv.OmbMgrPing=0 Drv.OmbMgrHost=223.255.255.1orxxx.orga.com

1 2 3 4 5 6 7 A I

APingtimewith0meansnoPING.

6.3.2.1

OMBmgr Configuration
TheOMBmgristobestartedwith: OMBmgr -DCM -p<port>-S TheportnumberistobethesameasDrv.OmbMgrPort. Whennotstartedwith-DCMtheSMCSclientwillnotstart! TheOMBmgrusesaconfigurationfilecalled$ORGADATA/Omb/Config.It containsthequeues.

161

Additional Features Configfilesyntax: # Queue1 QUEUE queueIn TCP # Queue2 QUEUE queueOut TCP InthiscasetheOMBmgrwouldcreatetwoqueuesonewithnamequeueIn theothernamedqueueOut.

6.3.3

SMSC Client
TheSMSCclientprovidesmechanismsforcommunicationwithalldifferent SMSCsandtheirprotocols.TheSMSCandtherefortheusedprotocolcanbe definedasaparameter. InthedirectionofCurryDriver,theclientcommunicateontheCURRYprotocol overOMB.Intheotherdirectiononthegivenprotocol(dependingonthe connectedSMSC). EachSMSCclienthasasetofconfigurationparameterswhichcontaintheIP addressandtheportnumberofthecorrespondingSMSC. Itispossibletoestablish1receiverconnectionandntransmitterconnections.

1 2 3 4 5 6 7 A I

6.3.3.1

Process Invocation
TheSMSCClientprocessisnamedstsc_smscandinvokedbythefollowing commandlinesyntax: stsc_smsc[-l][-h] [-S] [-D] [-v level] [-q] [-p port] [-o hostname]

where -S -h SelectAldiscon/LogicaSMPPprotocol,defaultCMGEMI3.5 Displayusage

162

Additional Features -D -DCM -Iid Startindebugmode,turnsonfullverbosemode Use$ORGADATA/Configfile(standard) Setclientidentifier(i.e.queuenumber)toid

-ohostname UseOMBmanageronhostname,overwritesconfiguration -pport -q -vlevel UseportforOMBcommunications,overwrites configuration Setquietemode,overwritestracelevel(*) Settraceleveltolevel,restrictsverbosemode(*) levelsdefinedpermodule(maybeORed): OMB_VERBOSE_BIT 0x80,128 SMSC_VERBOSE_BIT 0x40,64 SMPP_VERBOSE_BIT 0x20,32 EMI_VERBOSE_BIT 0x10,16 CIMD_VERBOSE_BIT 0x08,8 MPX_VERBOSE_BIT 0x04,4 NW_VERBOSE_BIT 0x01,1

1 2 3 4 5 6 7 A I

Allstandarddebuggingoptionsmaybeusedaswell. Theprocessexitswithanexitcodeof0,ifnormallyterminated,or1,ifafatal erroroccurred.Inthelattercaseapanicmessageiswrittentotheprotocolfile explainingthereason.

6.3.3.2

Signals
TheSMSCClientimplementsaspecialbehaviouratthetimeofreceivingthe followingsignals:

USR1:

Toggledebugmodeon/off; hasnoeffectonrunningconnections

USR2:

Re-readconfiguration; runningconnectionsaredropped.

SIGINT:

Theprocessisterminated;

163

Additional Features runningconnectionsaredropped. SIGTERM: SameasSIGINT.

6.3.3.3

Configuration
TheSMSCClientsupportstheSTCConfigurationManagementandtheold fashioned$ORGADATA/Configconfigurationfilethroughthe-DCMoption onprocessinvocation.Almostallconfigurationparametersaredescribedby meansofthestsc_smsc.cmtCMTfile.Somesharedconfigurationparametersarecoveredbyetc.cmt. Sinceadefaultvalueisassignedtoeachconfigurationparameter,allparametersareoptional.IftheSMSCClientcannotfindaconfigurationparameter (i.e.theparameterismissingfromtheCMTdatabaseortheConfigfilerespectively),itsdefaultvalueisusedinstead.Otherwisearangecheckisperformed.Iftheparametervaluelieswithinthedefinedboundaries,thevalue isaccepted,otherwiseanerrormessageisthrown.Itisuptothemainmodule topanicinthissituation. Charactervaluesmaybesurroundedbydoublequotes.Asingledashwithout leadingortrailingblanksisassumedtobeaNullvalue(CMTkludge).Asingle dashindoublequotes("-")isnotaNullvalue,butistakenliterally. Inthefollowingtablesthe<xxx>replacementdefinestheClientIdentifier(or QueueNumber)withintheallowedrangeof0-999. General Parameters Parameter Meaning Type:i range1024-9999 optional Default:8000 OMBManagerPortnumber

1 2 3 4 5 6 7 A I

STSC.OmbPort

164

Additional Features General Parameters Parameter STSC.OmbHost Type:c[0..64] optional Default:"localhost" Meaning OMBhostnameorIPaddress

Common Protocol Parameters Parameter STSC.SMCLT<xxx> SMSCAddressRX Protocol:SMPP EMI Type:c[0..64] optional Default:"localhost:7600" EMIsettoasingle dash STSC.SMCLT<xxx> SMSCAddressTX Protocol:SMPP EMI Type:c[0..64] optional Default:"localhost:7600" SMSChostnameorIPaddressand portnumber(formathost:port)for transmitterconnections Meaning SMSChostnameorIPaddressand portnumber(formathost:port)for receiverconnections

1 2 3 4 5 6 7 A I

165

Additional Features Common Protocol Parameters Parameter STSC.SMCLT<xxx> Timeout Protocol:SMPP EMI Type:i, range0-9999[sec] optional Default:0 recommended10secs STSC.SMCLT<xxx> PingTime Protocol:SMPP EMI Type:i, range0-9999[sec] optional Default:0 recommended30secs, shouldbegreaterthan theResponseTimer STSC.SMCLT<xxx> InactivityTout Protocol:SMPP EMI Type:i, range0-9999[sec] optional Default:0 recommended600 secs,shouldbegreater thantheAliveTimer InactivityTimer Thecorrespondingnetworkconnectionisdroppedifnoactivityis detectedwithinthetimeoutinterval AliveTimer. Thelifeofthecorrespondingnetworkconnectionischeckedbya protocol-dependentmechanism (example:sendingpingoralive PDUs) Meaning ResponseTimer,i.e.maximum allowedtimelapsbetweena requestandcorresponding responsefromotherparty

1 2 3 4 5 6 7 A I

166

Additional Features Common Protocol Parameters Parameter STSC.SMCLT<xxx> RetryTime Protocol:SMPP EMI Type:i range0-9999[sec] optional Default:10 Ifsetto0,nore-connectattemptismade STSC.SMCLT<xxx> MaxTries STSC.SMCLT<xxx> NumRetries Protocol:SMPP EMI Type:i range0-9999 optional Default:0 (noretransmission) notimplementedyet,obsolete Numberofretransmission attemptsbeforerequestisaborted Meaning ConnectTimer

1 2 3 4 5 6 7 A I

167

Additional Features Common Protocol Parameters Parameter STSC.SMCLT<xxx> Fanin Protocol:SMPP EMI Type:i range0-(OPEN_MAX10)** optional Default:1 Mustbesetto0for EMI STSC.SMCLT<xxx> Fanout Protocol:SMPP EMI Type:i range0-(OPEN_MAX10)** optional Default1 STSC.SMCLT<xxx> Backlog Protocol:SMPP* Type:i range0-(OPEN_MAX10)** optional Default:0(rejectall attempts) Numberofincomingconnections Numberoftransmitterconnections Meaning Numberofreceiverconnections

1 2 3 4 5 6 7 A I

168

Additional Features Common Protocol Parameters Parameter STSC.SMCLT<xxx> BindAddress Protocol:SMPP Type:c[0..64] optional Default":0",whichis boundtoanyinterface STSC.SMCLT<xxx> ServerAddress Protocol:SMPP* Type:c[0..64] optional Default:":7500", whichislisteningon port7500 STSC.SMCLT<xxx> Password Protocol:SMPP EMI Type:c[0..16] (8afterdecrypting) ThepasswordisusedbytheSMSC toauthenticatetheidentityofthe bindingESME(i.e.theSMSCClient).Thepasswordisencrypted (cf.manstsc_encrypt). LocalhostnameorIPaddressand portnumber(formathost:port)for incomingconnectionsinserver mode Meaning LocalhostnameorIPaddressand portnumber(formathost:port)for outgoingconnectionsinclient mode

1 2 3 4 5 6 7 A I

Defaultleftempty (sameasasingledash) STSC.SMCLT<xxx> CongestionDelay Protocol:All Type:i range10..9999 optional Default:20 Timeinsecondstheretransmission ofrejectedsubmitrequestsis delayedifcongestionisreported bytheSMSC.Theerrorclassofthe reportederrorcodemustbesetto Cinthecorrespondingeclassfile.

169

Additional Features Common Protocol Parameters Parameter STSC.SMCLT<xxx> ProtoWindow Protocol:SMPP EMI Type:i range10..9999 optional Default:20
* Supported in SMPP V3.4 and above (outbind operation), not implemented yet **The number of open file descriptors per process (OPEN_MAX) is a system constant and at least 16 in the POSIX environment, otherwise 64. The sum of all connections (RX, TX and incoming) cannot exceed the maximum as well. Additionally, if incoming connections are configured, one file descriptor is reserved for the listener. Ten file descriptors are reserved for OLS, stdin, stdout and stderr and other library functions. ***The SMSC Client monitors the traffic for SMSC connections. Optionally, the corresponding connection is dropped auomatically if no traffic was detected within the time interval in seconds defined by InactivityTout. The connection to the SMSC is established again after waiting another time interval defined by RetryTime. If InactivityTout is set to 0, the connection remains active. RetryTime must be set to a none zero value to enable the re-connect attempt. PingTime may be used to hold the connection in online state. For this reason the value of PingTime must always be less than the value of InactivityTout.

Meaning Protocolwindowi.e.numberof outstandingunacknowledged messages

1 2 3 4 5 6 7 A I

170

Additional Features

SMPP-related Parameters Parameter STSC.SMCLT<xxx> SMPP.SourceTON Type:i range0-255 optional Default0, cf.tablebelow STSC.SMCLT<xxx> SMPP.SourceNPI Type:i range0-255 optional Default0, cf.tablebelow STSC.SMCLT<xxx> SMPP.DestTON Type:i range0-255 optional Default1, cf.tablebelow STSC.SMCLT<xxx> SMPP.DestNPI Type:i range0-255 optional Default1, cf.tablebelow STSC.SMCLT<xxx> SMPP.NetworkType Type:i fixed0(TCP/IP), cannotbechanged Typeofnetwork, fixed0(TCP/IP), cannotbechanged NumberPlanIndicator (DestinationAddress), cf.GSM03.40 TypeofNumber (DestinationAddress), cf.GSM03.40 NumberPlanIndicator (SourceAddress), cf.GSM03.40 Meaning TypeofNumber (SourceAddress), cf.GSM03.40

1 2 3 4 5 6 7 A I

171

Additional Features SMPP-related Parameters Parameter STSC.SMCLT<xxx> SMPP.SystemID STSC.SMCLT<xxx> SMPP.SystemType STSC.SMCLT<xxx> SMPP.ProtocolVersion Type:c[0..15] Defaultleftempty Type:c[0..12] Defaultleftempty Type:c, range2characters. Fixed"33"whichis SMPPversion3.3, cannotbechanged Type:i range0-255 optional Default:0 STSC.SMCLT<xxx> SMPP.Priority Type:i, range0-3 optional Default:0 STSC.SMCLT<xxx> SMPP.ServiceType Type:i[0..6] optional Defaultleftempty Priority 0==nonpriority 1==priority(normal) 2==priority(urgent) 3==priority(veryurgent) Theservicetypecanbeusedto indicatetheSMSCapplicationserviceassociatedwiththemessage. Meaning Thesystemidentifierisusedto identifyanESMEatbindtimeto theSMSC. ThesystemtypeisusedtocategorizethetypeofESMEthatisbindingtotheSMSC. Protocolversioninuse.

1 2 3 4 5 6 7 A I

STSC.SMCLT<xxx> SMPP.EsmClass

ESMClass (cf.tablebelow)

172

Additional Features ThefollowingTypeofNumber(TON)valuesaredefined: TON Unknown International National NetworkSpecific SubscriberNumber Alphanumeric Abbreviated Value 00000000 00000001 00000010 00000011 00000100 00000101 00000110

1 2 3 4 5 6 7 A I

ThefollowingNumberPlanIndicators(NPI)valuesaredefined: NPI Unknown ISDN(E163/E164) Data(X.121) Telex(F.69) LandMobile(E.212) National Private ERMES Internet(IP) WAPClientID Value 00000000 00000001 00000011 00000100 00000110 00001000 00001001 00001010 00001110 00010010

173

Additional Features TheEsmClassparameterisusedtoindicatespecialmessageattributesassociatedwiththeshortmessage.TheEsmClassparameterisencodedasfollows inthesubmit_smPDUs: Esm Class Bits 76543210 xxxxxx00 xxxxxx01 xxxxxx10 xxxxxx11

Meaning DefaultSMSCmode(e.g.StoreandForward) Datagrammode Forward(i.e.transaction)modemessaging mode(bits1-0) StoreandForwardmode(usedtoselectStore andForwardmodeifdefaultSMSCmodeis nonStoreandForward) Defaultmessagetype(i.e.normalmessage) ShortMessagecontainsSMSCdeliveryreceipt messagetype(bits2and5) ShortMessagecontainsIntermediatedelivery notification ShortMessagecontainsESMEdelivery acknowledgement ShortMessagecontainsESMEmanualuser acknowledgementANSI-41specific(bits5-2) ShortMessagecontainsconversationabort (KoreanCDMA) Nospecificfeaturesselected UDHIIndicator(onlyrelevantforMTshortmessages)

1 2 3 4 5 6 7 A I

xx0000xx xx0001xx xx1000xx xx0010xx xx0100xx xx0110xx 00xxxxxx 01xxxxxx

174

Additional Features

Esm Class Bits 76543210 10xxxxxx 11xxxxxx

Meaning SetReplyPath(onlyrelevantforGSMnetwork) GSMspecific(bits7-6) SetUDHIandReplyPath(onlyrelevantforGSM network)

EMI-related Parameters Parameter STSC.SMCLT<xxx> EMIOADC Type:c optional Default:"72567" STSC.SMCLT<xxx> OTOA Type:c optional Default:"1139"in CMT ?????incodeleft empty???? STSC.SMCLT<xxx> NotifyAddr Type:c[0..64] optional Default: "192.168.1.1:5000" Meaning LargeAccountID (OADC)usedforlogin procedure(OT60, SessionManangement), OptionalOriginator TypeofAddress,used whentheOriginating Addressstartswitha pluscharacter

1 2 3 4 5 6 7 A I

IPaddressandportof NAdC(notifyaddress) ofoutgoingmessages (formatn.n.n.n:port orhostname:port). TheSMSCwilluse thisaddressfordeliverynotifications

175

Additional Features EMI-related Parameters Parameter STSC.SMCLT<xxx> PingAdC Type:c[0..15] optional Default: "1234567890" Meaning Ifpingsareusedthis parametermustbe settoAdCaddressfor thealertmessage,i.e. theaddressorphone numberofthisSMSC connection. Ifpingsareusedthis parametercanbeset tothe4digitprotocol identifierPID.

STSC.SMCLT<xxx> PingPID

Type:c optional Default:"0539"(i.e. PCoverTCP/IP)

1 2 3 4 5 6 7 A I

STSC.SMCLT<xxx> Priority

Type:c optional Default:5

Setsthepriorityofa request,ifnotsuppliedbyexternal entity.

176

Additional Features

6.4
6.4.1 6.4.2

SMS Services
Session Settings from HTML Content Use Cases
ThefollowingusecasesshouldshowaschematicflowofmessagesforPush/ USSD/SMSinteraction. FortheexactsyntaxoftheHTTPrequest/response,seesection6.2.

6.4.2.1

Push to USSD Display

1 2 3 4 5 6 7 A I

177

Additional Features

6.4.2.2

Push to USSD Prompt with Immediate Answer

1 2 3 4 5 6 7
6.4.2.3 Push to USSD Prompt with Late Answer
ThisisaspecialcaseforUSSDpromptmessages.AfterwIQhassenttheUSSD messagetoasubscriber,hemightgetnoresponseuntilatimeoutonthe USSDsessionappears.ThereforethePushsessionhasanextratimewhich shouldavoidwaitingforresponse.IfwIQreceivesnoerrorduringthe wIQ.PushSessionTimeout,itexpectseverythingisfineandsendsasuccess backtothePushclient.ThewIQ.PushSessionTimeouthastobesetupvery carefullytoavoidunnecessarywaitingforanswersanddonotmisspossible

A I

178

Additional Features errorUSSDorSMSerrormessages.Thevariableshouldbesetupindependencyfromthenormalnetworkerrorreactiontime.ToensurethatwIQgets errormessagesfromthenetwork,thetimeouthastobesetupgreaterasthe normalnetworkreactiontime.IfthewIQ.PushSessionTimeoutissetto0, thewIQwillconfirmacorrectPush-requestimmediatelywithoutwaitingfor anyresponsesoftheUSSDorSMSsession.ThereturnedstatusofthePushrequestisthenDELIVERED_UNCONFIRMED.Thisstatusmeansthattherequestisinprogressbutnotconfirmedyet.

1 2 3 4 5 6 7 A I

179

Additional Features

6.4.2.4

Push to SMS

1 2 3 4 5
<wiqsetting>:takethevaluesdefinedinURLtoSMSInterfaceMappingtable.

6 7 A I

180

Additional Features

6.4.2.5

Push to FINISH-SMS

1 2 3 4 5 6 7 A I

181

Additional Features

6.4.2.6

License Additions
ThePushinterfacecontainsalsothemaximumnumberoflicensed Push-requestsperminute.Thetotalnumberofrequestsperminute isnotincreasedbythePushlimit!

6.4.3

Load Distribution (Push / SMS / USSD )

Itisnotpossibletosetpriorities(insidethewIQcore)forthedifferentkinds ofrequests(USSD,SMS,Push).ToensurethatPushservicesdonotblockthe otherservicesatall,itispossibletodefineanotherlimitforPushservices.This limitmaybedefinedinthewIQmainconfigurationfile(seesectionwIQ.cfg: wIQConfigurationFileVariablesonpage 67)andiscalled

1 2 3 4 5 6 7 A I

wIQ.MaxPushQuota={0..100}default:100 or wIQ.MaxPushRequests={0..maxPushRequestsPerHours} default:maxPushRequestsPerHours Bothparametersareoptional.Theabsolutelowestlimitisalwaystaken. Thismeans,ife.g.MaxPushQuotais50,only50percentofmaxrequestper minutemightbetakenfromPush-requests. Example 1: max_requests_per_minute=300 max_push_requests_per_minute=200 wIQ.MaxPushQuota=50 (oralternatively wIQ.MaxPushRequest=150 (operatorsetting) License License (operatorsetting)

Amaximumnumberof150Push-requestsperminuteareallowed.

182

Additional Features IfthemaximumnumberofPush-requestsisreached,thereare150requests leftforotherrequests. Example 2: max_requests_per_minute=300 max_push_requests_per_minute=300 MaxPushQuota=100 If300requestsperminuteareperformed,norequestforanykindofrequest isallowedfortherestoftheminute. Thereareseveralnewandextendedfieldsofthesubscriberdatabase.Default ValuesNeededforPush ForPushtextmessages,youneedsomedefaultvaluestodeterminesession settings. wIQ.PushBillNegativeCoinsisaddedtowIQ.cfgtoconfigurewhichisbilled fornegativecoinswithinPush. SMSconfigurationforPushtextmessagesisperformedbyanewentryin Url2SMS.cfg.

1 2 3 4 5 6 7 A I

6.5

wIQ Enhanced SMS

YouneedanextralicenseforbinaryESMS!

Youneedanextralicenseifyouwanttousebothbinaryandtextual ESMS! ThischapterdescribesthesysteminterfaceforthewIQEnhancedSMS. ThesystemwillenablewIQtoprocessEnhancedSMSincludingthemajority oftheSMSparametersspecifiedin/GSM_03.40/and/GSM_03.38/asattributes.

183

Additional Features EnhancedSMSsareexpressedasstructureddatainformofwIQHTMLora setofHTTPparametersonthewIQPushinterface(seesectionPushInterfaceonpage 140). ThetermESMSisusedforEnhancedSMSinthefollowingsections. wIQprocessesanESMSviaitsstandardHTMLinterfaceandsendsittothe mobilephoneviatheNSGand/ortheSMSCinterface. ESMSarespecifiedbyawIQserviceproviderandincludedasplaintextina wIQHTMLfileviaanextensionofthewIQspecificHTMLlanguage. Additionally,ESMSwillbeprocessedbythewIQPushinterfacetoprovide pushedESMSservices. ThebenefitsofESMSforthewIQOperatororServiceProviderare: RingtoneSMSscanbeprocessedbythesystem LongSMSscanbeprocessedbythesystem TPDUparameters(accordingto/GSM_03.40/,/GSM_03.38/)canbeutilizedwithinanESMS.Theseare: ImmediatedisplayofanSMSonthereceivingmobilephone ReplacementofSMSsonthemobileSIMcardstorage,enablingthe updateofanexistingSMS,e.g.forSMSnewstickerservices Modificationofmessageindicators(FAX,VOICE,EMAIL)onthereceiving mobilephone TherearetwotypesofESMSthesystemwillprocess.Theyaredescribedinthe following: 1.RegularESMS ARegularESMScancontainamaximumof153characters(valuedepending onthealphabet)intheuserdatasection,usingtheGSMdefault7bitalphabet.TheoperatororserviceprovidercanspecifytheESMSuserdatasection inbinaryortextformat(dependingonthelicense).TheESMSallowsthedeclarationofadditionalUserDataHeaderelementsandasetofTPDUparametersasESMSattributeswithinthewIQHTMLlanguageandtheHTTPinterface ofthewIQPushFCGIcomponent.Theuserdatasectionisencodedaccording

1 2 3 4 5 6 7 A I

184

Additional Features tothealphabetattributesetting.wIQtranslatesitintothewIQSCXMLprotocolcommands. 2.LongESMS LongESMSshaveauserdatasectioncontainingmorethan153characters (valuedependingtothealphabet).BinarySMSssuchasringtonesorpicture SMSsforthemobilephoneareoftenlongerthanthevalid153characters.In ordertosendthemthough,suchSMSsneedtobesplitintomultipleSMSs thatareconcatenated.ThesystemwillimplementthesplittingoflongESMSs andbuildconcatenatedESMScontaininglessorexactly153charactersuser datalengtheach,whicharethensentsequentially. TheESMSsupportfeatureappliesonlytothesendingofESMS.It doesnotspecifywIQcapabilitiesforreceivingbothtypesofESMS.

1 2 3 4 5 6 7 A I

6.5.1

Overview
RingtoneandpictureSMSsarebinarySMSsthathavetobeprovidedinbinary format(hexadecimalformat)towIQ. ThestructureofaTPDUandhowtomodelitasawIQHTMLpagewillbedescribedinthefollowingbutthisisonlyanoverviewofthetopics. TheSMS-SUBMITtypeofTPDUistheTPDUthatwillbegeneratedbywIQ whensendinganSMSviaanSMSC.

6.5.1.1

First Octet of a SUBMIT-TPDU

ThefirstoctetoftheTPDU(SMS-SUBMIT)hasthefollowinglayout: Structure of the First Octet of a SUBMIT-TPDU

Bit no Name

7 TP-RP

6 TP-UDHI

5 TP-SRR

4 TP-VPF

3 TP-VPF

2 TP-RD

1 TP-MTI

0 TP-MTI

185

Additional Features

Flags of the First Octet of a SUBMIT-TPDU Fieldname TP-RP TP-UDHI Meaning Replypath. Parameterindicatingthatreplypathexists. UserDataHeaderindicator. Thisbitissetto1iftheUserDatafieldstarts withaheader. Statusreportrequest. Thisbitissetto1ifastatusreportisrequested. ValidityPeriodFormat. Bit4andBit3specifytheTP-VPfieldaccording tothistable: bit4bit3 00:TP-VPfieldnotpresent 10:TP-VPfieldpresent.Relativeformat(one octet) 01:TP-VPfieldpresent.Enhancedformat(7 octets) 11:TP-VPfieldpresent.Absoluteformat(7 octets) Rejectduplicates. ParameterindicatingwhetherornottheSC shallacceptanSMS-SUBMITforanSMstillheld intheSCwhichhasthesameTP-MRandthe sameTP-DAasapreviouslysubmittedSMfrom thesameOA. Messagetypeindicator. Bitsno1and0aresetto0and1respectively toindicatethatthisPDUisanSMS-SUBMIT.

TP-SRR TP-VPF

1 2 3 4 5 6 7 A I

TP-RD

TP-MIT

186

Additional Features Example Afirstoctetof"11"(hex)hasthefollowingmeaning: Sample of a First Octet of a SUBMIT-TPDU

Bit no Name Value 7 TP-RP 0 6 TP-UDHI 0 5 TP-SRR 0 4 TP-VPF 1 3 TP-VPF 0 2 TP-RD 0 1 TP-MTI 0 0 TP-MTI 1

Protocol Identifier (TP-PID) TheTP-Protocol-Identifierparameterconsistsofoneoctet.wIQESMscanconfigureonlyasubsetofthepossibleProtocolIdentifieroctet'sbinaryvalues. Wehavefixval-uesforbit7=0,bit6=1,bits5..0areusedasdefinedbelow. Protocol Identifier Values Valid for wIQ ESMS Bits 5..0 000000 000001 000010 000011 000100 000101 000110 000111 Description ShortMessageType0 ReplaceShortMessageType1 ReplaceShortMessageType2 ReplaceShortMessageType3 ReplaceShortMessageType4 ReplaceShortMessageType5 ReplaceShortMessageType6 ReplaceShortMessageType7

1 2 3 4 5 6 7 A I

Ashortmessagetype0indicatesthatthemobilephonemustacknowledge receiptoftheshortmessagebutmaydiscarditscontents.TheReplaceShort MessagefeatureisoptionalforthemobilephoneandtheSIMbutifimplemented,itshallbeperformedasdescribedhere.

187

Additional Features Formobilestationshortmessages,onreceiptofashortmessagefromfrom theSC,themobilestationshallchecktoseeiftheassociatedProtocolIdentifiercontainsaReplaceShortMessageTypecode.Ifsuchacodeispresent,the themobilestationwillchecktheoriginatingaddressandreplaceanyexisting storedmessagehavingthesameProtocolIdentifiercodeandoriginatingaddresswiththenewshortmessageandotherparametervalues.Ifthereisno messagetobereplaced,themobilestationshallstorethemessageinthenormalway.ThemobilestationmayalsochecktheSCaddressaswellasthe OriginatingAddress.However,inanetworkwhichhasmultipleSCs,itispossibleforaReplaceMessagetypeforaSMtobesentviadifferentSCsandso itisrecommendedthattheSCaddressshouldnotbecheckedbythemobile stationunlesstheapplicationspecificallyrequiressuchacheck. IfaReplaceShortMessageTypecodeisnotpresentthentheMSwillwillstore themessageinthenormalway. Data Coding Scheme (TP-DCS) TheTP-Data-Coding-Schemefield,definedinGSM03.40,indicatesthedata codingschemeoftheTP-UDfield,andmayindicateamessageclass. Theoctetisusedaccordingtoacodinggroupwhichisindicatedinbits7..4. Validity Period (TP-VP) ValidityperiodspecifiesthetimewhenSMexpires.IfSMisnotdeliveredbeforethatmoment,itisdiscardedbySC.Validity-Periodcanbeinthreedifferentformats:Relative,Absolute,andEnhanced. Relative: TheTP-Validity-Periodcomprises1octetinintegerrepresentation,givingthe lengthofthevalidityperiod,countedfromwhentheSMS-SUBMITisreceived bytheSC.Therepresentationoftimeisasfollows:

1 2 3 4 5 6 7 A I

188

Additional Features Values of the TP-VP field of a SUBMIT-TPDU TP-VP Value 0to143 144to167 168to196 197to255 Absolute TP-VPfieldis7octetslong,containingTP-SCTSformattedtimewhenSMexpires.See/GSM03.40/formoreinformation. Enhanced See/GSM03.40/formoreinformation. Validity period value (TP-VP+1)*5minutes(i.e.5minute-intervalsupto 12hours) 12hours+((TP-VP-143)*30minutes) (TP-VP-166)*1day (TP-VP-192)*1week

1 2 3 4 5 6 7 A I

6.5.2

wIQ HTML Language Extension

Withinthissection,theextensionstothewIQHTMLlanguageregardingthe ESMSsupportforwIQaredescribed. Wewillintroducethefollowingnewtags: dcs msginddcs pid msgindudh udhie smshead vp

189

Additional Features

Tag Name: smshead Presence Synopsis Optional,unique(0..1) <smshead rp=v1 srr=v2 mms=v3 > Thesmsheadtagdefinesthefirstoctetofa TPDU.

Description

1 2 3 4 5 6 7 A I

Thepresencepolicyforallattributesofthistagisoptional. Attributes Attribute rp Values 0,1 Description SpecifieswhetherthereplypathfortheESMS isset(0)ornot(1).Whentheattributeissetto 1,thereplypathinformationwillbedelivered tothereceivingMSaspartoftheDELIVERTPDU(TP-Reply-Pathparameter) See/GSM03.40/,9.2.3.17 Defaultsto0

190

Additional Features Attributes Attribute srr Values 0,1 Description Indicatesthatastatusreportforthedeliveryof thisESMSwillberequestedfromtheSME.If theattributeissetto1,aStatus-ReportSMS willbereturnedtotheSMSgatewaysystem whentheESMShasbeensuccessfullydelivered. Defaultsto0 Indicatesthatmoremessagesarewaitingin theSC.Theattributeissetwhenconcatenated ESMSaresent. Note:Thisoptionwillonlybeevaluatedbythe SMEinwIQmodeMAPSMS0(fire-and-forget). See/GSM03.40/,9.2.3.2 Defaultsto0

mms

0,1

1 2 3 4 5

Tag Name: dcs Presence Synopsis Optional,unique(0..1) <dcs alphabet=v1 class=v2 > Thedcs(data-coding-scheme)tagdefinesthe alphabetusedforhexadecimalencodingofthe User-DatasectionofanESMS.Additionally,it definesthemessageclass(ofparticularfunctionalinterestmaybeimmediate(class0)which indicatesthereceivingmobilestationshall immediatelydisplaytheESMS).

6 7 A I

Description

191

Additional Features Thepresencepolicyforallattributesofthistagisoptional. Attributes Attribute alphabet Values default, 8bit, UCS2 Description Specifiesthealphabetusedforencodingthe userdatapartoftheESMS. Notesthatdependingonthelicense,only partofthevaluesmaybeusable. Defaultstodefault SpecifiestheclassoftheESMS.immediate indicatestheESMSshallbeimmediatelydisplayedbythereceivingmobilestation(if supportedbythemobilestation). Iftheclassattributeisnotpresent,itmeans thecasemessagehasnomessageclass.

class

immediate, ME, SIM, TE

1 2 3 4 5 6 7 A I

Tag Name: msginddcs Presence Optional,unique(0..1). Whenpresent,apotentiallyalsopresentdcs tagisignored.

192

Additional Features Tag Name: msginddcs Synopsis <msginddcs type=v1 action=v2 store=v3 > Themsginddcs(data-coding-schememessageindicator)tagdefinesthealphabetusedfor hexadecimalencodingoftheUser-Datasection ofanESMS. Additionally,itdefinesthemessageclass(of particularfunctionalinterestmaybeimmediate (class0)whichindicatesthereceivingMSshall immediatelydisplaytheESMS).

Description

1 2 3 4 5 6 7 A I

Thepresencepolicyforallattributesofthistagisoptional. Attributes Attribute type Values voice, fax, email, other activate, deactivate 0,1 Description Indicatesamessageoftypevoice,fax,email orotheriswaitingforthereceivingmobole stationontheSME. Specifieswhetherthemessageindicator definedbythemsg-wait-typeshouldbeactivatedordeactivated. Specifies,whetherthereceivingmobilestationshallstorethemessageaftersettingthe messageindicatorordiscardit.

action

store

193

Additional Features

Tag Name: pid Presence Synopsis Optional,unique(0..1) <pid value=v1 > Thepid(protocol-identifier)tagcontainsaone bytevalueindecimalform.ItdeterminesvariouspropertiesofanESMSsuchasthemessagetype.ThemessagetypeindicatesapositionwithintheSMSstoreontheSIMcardof thereceivingMS.TheSMSsstoredonthatpositionwillbereplaced(overwritten)bythis ESMS.

Description

1 2 3 4 5 6 7 A

Thepresencepolicyforallattributesofthistagisoptional. Attributes Attribute value Values 0..255 Description Specifiestheprotocilidentifier(1bytein decimalrepresentation)oftheESMS.

Tag Name: vp Presence Optional,unique(0..1)

194

Additional Features Tag Name: vp Synopsis <pid vpf=v1 value=v2 > Thevp(validity-period)tagdefinestheValidity-PeriodTPDUparameter.TheValidity-Period definestheperiodwithintheESMSisvalid.If thattimeperiodexceeds,theSME/SMSCshall notdelivertheESMStothetargetMS.Thevpf attributedefinestheformatinwhichthevalue fieldisprovided. Note:Thevptagwillonlybeevaluatedwhen theESMSissentviaSMSC(whenthewIQsend modeisMAPSMS2).Inothersendmodesthe vptagdefinitionisignored. Thepresencepolicyforallattributesofthistagismandatory.Ifthetagisnot present,novalidity-periodisassumed. Attributes Attribute vpf Values rel, enh, abs string Description Specifiestheformatofthevalueattribute.

Description

1 2 3 4 5 6 7 A I

value

SpecifiestheValidity-PeriodoftheESMS, formatoftheStringdependsonthesetting ofthevpfattribute.

195

Additional Features

6.5.2.1

User Data-specific Tags

Withinthissection,HTMLtagsspecifyingtheUserDatasectionofanESMS aredefined,includingtheInformationElementsoftheUserDataHeaderand theUserDatasectionitself.

Tag Name: msgindudh Presence Synopsis Optional,multiple(0..*) <msgindudh type=v1 count=v2 store=v3 > Themsgindudh(user-data-headermessageindicator)tagdefinesthemessageindicators forFAX,VOICE,E-MAILandOTHERmessage types.Attributesdefinethenumberofmessageswaitingandwhetherthecontentofthis ESMSshallbestoredornot.

1 2 3 4 5 6 7 A I

Description

196

Additional Features Thepresencepolicyforallattributesofthistagisoptional. Attributes Attribute type Values Fax, voice, email, other 0..255 Description Specifiesthetypeofthemessageindicator definedbythismsg-indicatortag.

count

Definesthevalueofthemessageindicator counterforthemessagetypespecifiedby theindicator-typeattribute.Thecounter denotesthenumberofwaitingmessagesof thattype.Thevalue0denotesthedeactivationofthatindicator. SpecifieswhethertheESMSshallbestored bythereceivingMS(1)ornot(0).

1 2 3 4 5

store

0,1

Tag Name: udhie Presence Synopsis Optional,multiple(0..*) <udhie id=v1 value=v2 > Theudhie(user-data-headerinformation-element)tagdefinesagenericUser-Data-Header Information-Element. AttributesdefinetheIE-IdentifierandtheIEData.

6 7 A I

Description

197

Additional Features Thepresencepolicyforallattributesofthistagisoptional. Attributes Attribute id Values hexadecimaloctet Description Definesthetypeofthemessageindicator definedbythisInformation-Elementtag.The valuemustbeonebyteinhexadecimalformat(2characters,.e.g.B6). DefinestheIE-Datasectionoftheinformationelement.TheIE-Datasectionisa8bit hexadecimalencodedstring.

value

hexadecimalstring

1 2 3 4 5 6 7 A I

6.5.2.2

ESMS HTML Tag Processing Rules

Withinthissection,theruleswIQapplieswillbeexplainedwhenparsingthe ESMSHTMLtags,e.g.whathappendwhenatagattributevalueisfaultyor missing. Tag Attribute/Value Is Missing Iftheattributeismandatoryandthereisnodefaultfortheattribute,the tagisig-nored.Ifthetagismandatory,therequestwillberejected. Iftheattributeisnotmandatory,thetagisprocessed Tag Attribute Value Is Invalid Ifatagattributevalueisinvalid,therequestwillberejected.Neither defaultswillbeappliednortagwillbeignoreds. Tag Attribute Parsing Tagattributesthathavevaluesoutofachoiceofstringsarealwaysparsed caseinsensitive,e.g. <dcs alphabet= "default" class="ME"> isthesameas

198

Additional Features <dcs alphabet= "DEFAULT" class="me"> ESMS HTML Page Validity Rules Besidesofthebasictag/attributevalidityrulestorejectaHTMLpageexplainedabove,thereareothercasesinwhichanHTMLpagewilllnotbesent totherequestingsubscriber.Theseareasfollows: IftheDCStagspecifiesthe8bitalphabetbutthecontentisnotprovided inhexa-decimalformat,therequestwillberejected. IftheHTMLpagecontainsnocontentinthebodytagandnoUserData Headerinformationelements(UDHIEtags)ormessageindicatorUserData Headerinformationelements(MSGINDUDHtags),meaningboththeuser dataandtheUserDataHeaderpartsoftheESMSwillbeempty,the requestwillberejected.NoticethatthismeansprovidingaMSGINDDCS tagassoleinformationinanHTMLpagewillresultintherejectionofthat HTMLpage(althoughitmightmakeasense).Itisrecommendedtouse themsgindudhtagformessageindicatormanipulationwithemptycontentpages. Valuesexpectedtobeinhexadecimalformatmusthaveanevenlength also,otherwisetheyarerejected.wIQdoesnotapplypaddingoftrailing 0stoahexstringbecausethisislikelynotleadingtothehexadecimal valuetheauthorintended

1 2 3 4 5 6 7

6.5.3

wIQPush

YouneedanextralicenseforthePushinterface! TheimplementationoftheextensionstothewIQPushinterfaceregardingthe processingofESMSinvolvesthefollowingimplementationissues.

A I

6.5.3.1

HTTP Interface Extension

Inthissection,theparametersetextensionsforthewIQPushInterfacearedefined.EachtagattributeoftheEnhancedSMSadditionswillbemirroredby

199

Additional Features itsownHTTPparameter.ThefollowingtablelistsallnewwIQPushHTTPGET/ POSTparameters.(Inthetable,ParamstandsforParameter,Predenotesthe presence(O=Optional,M=Manadatory)oftheparameter)

TheProtocolExtensionwillacceptallHTTPGET/POSTparametersdescribed above. Param data Pre M Values sms-enh Description IndicatesthattheEnhancedSMS FeaturesofwIQandthePushProtocolVersion1.01willbeused.

1 2 3 4 5 6 7 A I

wIQPush HTTP GET/POST Parameters for ESMS Support (Push Protocol V1.01) Param srr rp mms dcs pid vpf O O O O 0 O Pre Values 0,1 0,1 0,1 int int rel, enh, abs char* 0,1 Description Forthedescription,seepage 191. Forthedescription,seepage 190. Forthedescription,seepage 191. Forthedescription,seepage 191. Forthedescription,seepage 194. Forthedescription,seepage 195.

vp udhi

O O

Forthedescription,seepage 194. Forthedescription,seepage 197.

200

Additional Features wIQPush HTTP GET/POST Parameters for ESMS Support (Push Protocol V1.01) Param ud udh Pre M O Values char* Char* Description TheUser-Datasectionofthemessage. TheUserDataHeader,mandatory ifudhiissetto1.Ifudhiissetto 0,udhattributemustnotbe present.

URLencodinghastobeusedforallspecialcharactersinthevaluefield,e.g. space,hash,...

1 2 3 4 5 6 7 A I

6.5.4

Examples
Withinthischapter,examplesforthetranslationofanESMSinputfroma HTMLpageareprovided.ThistranslationtakesplaceinthewIQcore. NotethatbinaryandtextESMSexamplesneedasuitableESMSlicense!

6.5.4.1

Example of a Ringtone ESMS

Inthefollowing,adescriptionofaRingtoneESMSforNokia33xxhandsets isgiven.TheexamplewasderivedfromthefollowingoriginalTPDU: Example: 0791947122723033440C9194719215142100F5205022211315806A 06050415810000024A3A7531A59DA1D081B5E48199A5C99404008F 1ECAE938C498824D412718A26C511624E312698930C49A624B4126 A0A22C5166289C144609370498824CB12618930C499624C4126A09 38C512624E4126A09310496824AB12598934049A40009B9B9A

201

Additional Features Translation into wIQ HTML: <html>

<head> <sms_head > <dcs alphabet="8bit" > <pid type="0" > <udh_ie id="05" value="15810000" > </head>

1 2 3 4 5 6 7 A I

<body> 024A3A7531A59DA1D081B5E48199A5C99404008F1ECAE938C49882 4D412718A26C511624E312698930C49A624B4126A0A22C5166289C 144609370498824CB12618930C499624C4126A0938C512624E4126 A09310496824AB12598934049A40009B9B9A </body> </html>

202

Additional Features

6.5.4.2

Example of a Text ESMS

ThefollowingwIQHTMLdocumentsdescribesatextESMSwiththefollowing properties: Adeliverystatusreportisrequested Replypathisset Thedefaultalphabetisused Messageclass0(Immediatedisplay)isspecified(example1) Validityperiodissetto25.05.0112:30:0000,GMT+00timezone NoUserDataHeaderispresent Example: <html> <head> <sms_head srr="1" rp="1" > <dcs alphabet="default" class="immediate" > <vp format="abs" value="02250512300000" > <pid value="64" > </head>

1 2 3 4 5 6 7 A I

203

Additional Features <body> This is a text ESMS </body> </html>

6.5.4.3

Example of a Binary SMS

ThefollowingwIQHTMLstatementdescribesanbinaryESMSwiththefollowingproperties: Nodeliverystatusreportisrequested Replypathisnotset The8bitalphabetisused Messageclass0(ImmediateDisplay)isspecified Validityperiodissetto10.07.0215:10:0000,GMT+00timezone NoUserDataHeaderispresent

1 2 3 4 5 6 7 A I

<html> <head> <smshead > <dcs alphabet="8bit" msgclass="immediate" > <vp format="abs" value="02100715100000" > <pid value="0" > </head>

204

Additional Features

<body> 50D1E939283D078541C2B43B2CCF838A6E74D </body> </html> TheuserdatastringdecodedisThisisaBinaryESMS(8bithexadecimalencoding).

6.5.4.4

Example of a Picture SMS

ThefollowingwIQHTMLpagedescribesapictureESMSforNokia33xxhandsets.

1 2 3 4 5 6 7 A I

<html> <head> <sms_head rp="0" srr="0" > <dcs alphabet="8bit" class="ME" > <pid value="0" > <udh_ie id="05" value="158A0000" > </head> <body>

205

Additional Features 300000045465737402010000481C01FED6A2444200AAB6FFD7BB00 32101E455B5BFAD49C81453F1061EDFF5B3E00103F00007FB7D53E 18021F87041BEAB53E1C880F9F820F7FAA3E1C2003FFC123EADD3C 1C0003FEE095BD601C3C11C7F87097EBA1FFF801FFFC3895FEC3FF F881FEFE3817D547FFE0003C7F0025FDCF3E0000003F8047B00E3E 1C2000FFC40DD80C3F7E0003FFC2BFF20C1FFE010FF7CDD7AA401F E7000F8F8CB5F2408F83B00E1F06DFDA200783F0073C1B75F11C63 C1F00738255FD08021E0C003BCB5ABF86100F800039C16FEAC0000 F000078E0357FD4001E0000F0E00DBEF800FC0000E0700EFBAC01F 0000000F017DDFD00E0000001E02D7ED59070000001C5B7F </body> </html> ThispictureSMSistoolongtobesentasone.Itwillbesplitintopartial(concatenatedSMSs)whensenttotheSMSC.Therewillbe3resultingpartial SMSsreceivedbytheMobile.ThesearethefollowingTPDUs: Partial SMS TPDU No.1 0791947122723033400C9194719215142100F5205022213375808C 0B0504158A00000003030301300000045465737402010000481C01 FED6A2444200AAB6FFD7BB0032101E455B5BFAD49C81453F1061ED FF5B3E00103F00007FB7D53E18021F87041BEAB53E1C880F9F820F 7FAA3E1C2003FFC123EADD3C1C0003FEE095BD601C3C11C7F87097 EBA1FFF801FFFC3895FEC3FFF881FEFE3817D547FFE0003C7F 0025FDCF3E0000 Partial SMS TPDU No.2 0791947122723033400C9194719215142100F5205022214310808C 0B0504158A00000003030302003F8047B00E3E1C2000FFC40DD80C 3F7E0003FFC2BFF20C1FFE010FF7CDD7AA401FE7000F8F8CB5F240 8F83B00E1F06DFDA200783F0073C1B75F11C63C1F00738255FD080 21E0C003BCB5ABF86100F800039C16FEAC0000F000078E0357FD40 01E0000F0E00DBEF800FC0000E0700EFBAC01F0000000F017D DFD00E0000001E Partial SMS TPDU No.3

1 2 3 4 5 6 7 A I

206

Additional Features 0791947122723033440C9194719215142100F52050222143308017 0B0504158A0000000303030302D7ED59070000001C5B7F

6.6

ORGA NSG Driver

TheNSGdriverisusedforcommunicationbetweenwIQ/routerandtheNSG whichdoestheSS7connection. TheNSGdriverisusedforUSSDtraffic(MOandMT)aswellasforDirectSMS. TheDirectSMSfeatureisusedtosendSMSmessagesdirectlytothesubscriberviatheSS7networkbypassingexistingSMSCs. AnSMSissentdirectlytotheSS7networkonlywhenconfiguredaccordingly inwIQandrouter(seepage 95)! TheusageofDirectSMSonlyworkswithglobaltitletranslation capabilityoftheconnectedSCP,asanSMSisaddressedtosubsystemMSISDN+SSN6. TheNSGdriverprocessisnamedtedriver.

1 2 3 4 5 6 7 A I

6.6.1

Signals
ThetedriverprocesshandlesthefollowingUNIXsignals: tedriver Signal Handling Switch SIGUSR1 SIGUSR2 SIGPIPE SIGINT,SIGTERM Description Toggledebuggingon/off Configurationreload Ignoresignal Closeallsessions,thenterminateprocess

207

Additional Features

6.6.2

Command Line Options

Thedriversupportsthefollowingcommandlineswitches
>tedriver [-D][-C Classlist][-V DebugLevel][-c ConfigFile]

tedriver Command Line Switches Switch -D -V<debuglevel> Debuglevel={1..9} Values Description toggledebuggingon/ off Setthelevelof debug. 1meansonlybasic debuginformation. 9isalldebuginformation. Onlyhaveeffectif debuggingis enabled. Useconfigurationfile insteadof $ORGADATA/cnf/ tedriver.cfg

1 2 3 4 5 6 7 A I

-c <configfile>

configfile=Filename oftheconfiguration filetobeused.

6.6.3

Driver Configuration
Thedriverusestheconfigurationfile$ORGADATA/cnf/tedriver.cfgby default. Theformatofonelineofthisfileis tedriver.<variablename>=<value><NEWLINE> Thelinesareseparatedbyanewline.Astarting#marksthelineasacomment.

208

Additional Features Consultthemanualpages(enterman tedriver.cfgonthewIQhost)for possibleconfigurablevariables. Ifnodefaultvalueisdefined,thedefinitionofthevariableismandatoryinthe file.Otherwiseitisanoptionalvariable.(BCD=astringofdigits) Example configuration:

# # Sample file for the configuration of the driver-- tedriver # tedriver.localSSN=8 tedriver.localGT=1234567890 tedriver.UserID=40 tedriver.DlgIdMin=1 tedriver.DlgIdMax=10000 tedriver.wIQHost=localhost tedriver.wIQPort=5348 tedriver.wIQGuardtime=3600 tedriver.AliveFilePeriod=30 tedriver.FailureMessage=Temporary out of service tedriver.EmptyReplaceMessage=Empty message tedriver.SessionTimeout=35

1 2 3 4 5 6 7 A I

209

Additional Features

1 2 3 4 5 6 7 A I

210

SNMP

7
ThismanualdescribestheintegrationofSNMP(trap)supportintowIQ. wIQmakesuseofSNMP(SimpleNetworkManagementProtocol)inorderto integratethesystemintoaNMS(NetworkManagementSystem)ata customersite. TheSNMPAlarmSubsystemimplementedforwIQismeanttodeliveralarm messages,clearalarmmessages,andheartbeatmessagetoaNMS. wIQwilluseSNMPtraps. SNMPtrapsarespontaneousmessagessentbyanSNMPagenttotheNMS. Thesemessagescontaininformationaboutthestatusandhealthofthe(wIQ) system,e.g.theytelltheNMSifconnectionshavebeenlostorreestablished, iftheSubscriberdatabaseisavailable,inwhatkindofmode(local/remote) thewIQsystemcurrentlyoperates,etc.,andhowcriticalthecurrentstatusof thesystemis(severity). TheSNMPAlarmSystemtrapshavetoincludecertainfieldswhicharedefined intheMIB(ManagementInformationBase)datastructure,andare transportedinUDPpackets. Thesystemwillonlybeabletogenerate/sendSNMPalarmtraps whichareusedtosendstatus/alarmmessagestotheNetwork ManagementConsoleoftheoperator. TheuseofSNMPget-request,get-next-request,get-response,and set-requestPDUs(ProtocolDataUnits)whichareusedtoqueryor setspecificdatawillnotbesupportedbythisimplementation.

1 2 3 4 5 6 7 A I

211

SNMP TheSNMPdatawhichissentoutbythisimplementationcanonlybeusedto monitorthewIQsystemanditscomponents.Itcannotbeusedasatoolto supervisetheoperatingsystem,e.g.memoryordiskusage,CPUload,etc. Thatkindofdataneedstobemonitoredusingavendor/OS-specificSNMP daemonwhichiscompletelyseparatefromwIQ.

7.1
7.1.1

SNMP Trap Configuration

OLS TRAP
ThedefinitionoftrapsisdonewiththehelpoftheORGAloggingsystem (OLS). Foreveryprocess,thereisafiledefiningtheloggingandtrapmessages. TheTRAPprocessingactionstatementhasthefollowingsyntax: TRAP <severity> <alarmtype> <clearmsgid> Thefieldsareseparatedbywhitespaceandexplainedinthefollowingtable: OLS TRAP Field TRAP Type c[...] Description Keywordtoindicateprocessing actionSNMPalarmtrap.

1 2 3 4 5 6 7 A I

212

SNMP OLS TRAP Field <severity> Type n[1] Description ASCIIdigitdenotingseverity: '0'-indeterminate, '1'-critical, '2'-major, '3'-minor, '4'-warning, '5'-clear, '6'-informational. ASCIIstringidentifyingthebasic typeofalarm;suggestedkeywords (fromISO/IECDIS10164-4)are COMMUNICATION,ENVIRONMENTAL,EQUIPMENT,PROCESSING,QUALITYOFSERVICE

<alarmtype>

c[20]

1 2 3 4 5 6 7 A I

7.1.2

Configuration of the SNMP Agent

TheSNMPagentprocessisresponsibleforsendingoutalltrapstotheNMS.. Thefollowingconfigurationparametersaredefinedin $ORGADATA/cnf/stsc_snmp.cfg: Variable ORGA.SNMPAlarmAddress Type c[...] Description IPaddressandUDPportofthe SNMPAlarmSystemreceivingthe SNMPalarmtraps (n.n.n.n:port or hostname:port). SNMPCommunitystring,default public.

ORGA.SNMPCommunity

c[...]

213

SNMP

Variable ORGA.SNMPVersion

Type n[1]

Description SNMPtrapformattobeused: 1=SNMPv1, 2=SNMPv2,default1 NameoftheSNMPpipe. Ifthenamestartswitha/,an absolutepathisassumedotherwise arelativepathunder$ORGADATAis used. Default.snmppipein$ORGADATA

ORGA.SnmpPipe

c[...]

Iftheprocessisstartedwiththe-DCMswitch,theoldconfigurationfile mechanism($ORGADATA/Config)isalsosupported. TheSNMPAlarmProcesstransformseacheventrecordintothepayloadof SNMPtrapPDUsandnotifiestheexternalAlarmManagementSystemviaa TCP/IPconnectionasynchronously. Eachnewlyreceivedeventrecordsignalsoneofthedefinedevents: Alarmset Alarmclear Heartbeat ThetrappayloadisconstructedfromaMIB-definedvariableset. ThefollowingdataiscontainedinaSNMPalarmtrap:

1 2 3 4 5 6 7 A I

214

SNMP

MIB Variable caSeverity

Type n[1]

Description Integerdenotingseverity: '0'-indeterminate, '1'-critical, '2'-major, '3'-minor, '4'-warning, '5'-clear, '6'-informational. Integeridentifyingthebasic typeofalarm;suggested keywords(fromISO/IECDIS 10164-4)are: UNKNOWN=0, COMMUNICATION=1, ENVIRONMENTAL=2, EQUIPMENT=3, PROCESSING=4, QUALITYOFSERVICE=5. Callingprogramname. YYYYMMDDhhmmsstime stampofthealarmmessage. ASCIIstringwiththe dynamicpartoftheclear alarmmessage. Integereventnumber. ASCIIstringwiththemessagetext.

caEventType

n[1]

1 2 3 4 5 6 7 A I

caOriginatingEquipment caEventDate

c[100] d[15]

caAdditionalData

c[64]

caEventNumber caEventText

n[4] c[64]

215

SNMP

MIB Variable caNotificationID

Type n

Description Integernumberuniquely identifyinginstanceoffault givingrisetotheevent. Unsignedintegernumber whichisincrementedby oneforeachtrapsent.

caTrapID

The<caNotificationID>isanumberthatuniquelyidentifiesaninstance ofagiveneventcondition.ThenotificationIDcanbeusedtocorrelateaset andcleareventsothattheexternalAlarmManagementSystemmaymarkthe eventasdisappeared. When<caNotificationID>achievesthemaximumvalue(0x7FFFFFFF), thevariablewillwrapbacktovalue1whensendingthenextnewalarmset trap. The<caTrapID>isincrementedbyoneineachtrapsent.TheAlarm ManagementSystemmayusethisvariabletodetectiftrapsarelost.When <caTrapID>achievesthemaximumvalue(0x7FFFFFFF),thevariablewill wrapbacktovalue1whensendingthenexttrap. Theseverityvariablelistedaboveissetto'clear'incasethetraprepresentsan alarmclearevent.

1 2 3 4 5 6 7 A I

Incaseofanheartbeateventgeneratedtrapthe<caEventText>variable mustcontainthestringHeartbeat'. ThefollowingobjectidentifiersaredefinedinthecorrespondingMIB:

enterprises company_ORGA companyProducts product_OLS

OBJECT IDENTIFIER ::= {1.3.6.1.4.1} OBJECT IDENTIFIER ::= {enterprises 3688} OBJECT IDENTIFIER ::= {company_ORGA 1} OBJECT IDENTIFIER ::= {companyProducts 1}

216

SNMP
alarmTraps ca caVars OBJECT IDENTIFIER ::= {product_OLS 1} OBJECT IDENTIFIER ::= {alarmtraps 2} OBJECT IDENTIFIER ::= {ca 1}

MIB Variable caSeverity caEventType caOriginatingEquipment caEventDate caAdditionalData caEventNumber caEventText caNotificationID caTrapID

Object Identifier 1.3.6.1.4.1.3688.1.1.1.2.1 1.3.6.1.4.1.3688.1.1.1.2.2 1.3.6.1.4.1.3688.1.1.1.2.3 1.3.6.1.4.1.3688.1.1.1.2.4 1.3.6.1.4.1.3688.1.1.1.2.5 1.3.6.1.4.1.3688.1.1.1.2.6 1.3.6.1.4.1.3688.1.1.1.2.7 1.3.6.1.4.1.3688.1.1.1.2.8 1.3.6.1.4.1.3688.1.1.1.2.9

1 2 3 4 5 6 7 A I

217

SNMP

7.2
7.2.1

SNMP Support in wIQ Processes

wIQd / wIQguard
ToenableSNMPsupport,youhavetosettheconfigurationparameter(see page 51)wIQd.Alarmingto2. ThenanadditionalSNMPagentprocessisstartedandstoppedbywIQd. wIQguardwillgenerateatrapfor everymonitoredprocessthatisstopped.Wheneverthisprocessiscoming upagain,thetrapiscleared.Amonitoredprocessiseitherthedatabase, theWebserveroraprocessonthewIQguardprocesstable. awIQguardstop.ThisisclearedbyastartofthewIQguard(withno regardsifitcomesupinlocalorremotemode). awIQguardthatiscomingupinremotemode.Ifthistrapisset,younow thatthereisawIQguardinstancemonitoringthelocalmodewIQguard runningelsewhere.Thisiscleareduponstoporswitchingtolocalmode heartbeats.TheseheartbeatsaregeneratedbyawIQguardrunningin localmodethatincludesthescriptwatch_snmponitsprocesstable. Pleasenote:AremotemodewIQguarddoesNOTsendheartbeats! Soifasystemisrunninginoperationalstate,youwillseeatrapforasystem runninginremotemode,andyouwillreceiveheartbeatsfromtheother systemrunninginlocalmode. IfyouhaveSNMPsupportenabled,thefileSnmpRestartshould bepartoftheexcludefile.

1 2 3 4 5 6 7 A I

218

SNMP Thefollowingtrapsaregenerated:: Event-ID 0000 OLS-Name HEARTBEAT Description Heartbeatmessage(not cleared),dynamicpartis empty wIQguardhasstarteda process(e.g.wIQ_a)-> clears6002,dynamicpart containsprocessname wIQguardrecognized processstop->raise, dynamicpartcontains processname wIQguardiscomingup (nomatteriflocalor remotemode)->clears 6004,dynamicpartcontainshostname wIQguardisterminated (nomatteriflocalor remotemode)->raise, dynamicpartcontains hostname wIQguardisstartedin remotemode->raise, dynamicpartcontains hostname wIQguardremotemode isquit->clears6005, dynamicpartcontains hostname

6001

WIQGUARD.PROCESSUP

6002

WIQGUARD.PROCESSDOWN

1 2 3 4 5 6 7 A I

6003

WIQGUARD.UP

6004

WIQGUARD.DOWN

6005

WIQGUARD.REMOTEUP

6006

WIQGUARD.REMOTEDOWN

219

SNMP Exampletrapsgeneratedfromthis:
AdditionalData (Dynamic mes-sage part)

OriginatingEquipment

6003

CancelEvent AlarmEvent CancelEvent AlarmEvent AlarmEvent

COMMUNICATION COMMUNICATION COMMUNICATION COMMUNICATION COMMUNICATION

wIQguard

wIQguard.odscp-1 wIQguard.odscp-1 wIQ_a

STARTED:wIQ-guard onhostod-scp-1 STOPPED:wIQguard onhostod-scp-1 STARTED:wIQ_a

6004

wIQguard

EventText (Mes-sage)

EventType

Specific *

Event-ID

Severity

6001

wIQguard

1 2 3 4 5 6 7 A I

6002

wIQguard

wIQ_a

STOPPED:wIQ_a

6005

wIQguard

wIQguard.odscp-2

STARTED:wIQguard inremoteguard modeonhostodscp-2 STOPPED:wIQguard inremoteguard modeonhostodscp-2 Heartbeat

6006

CancelEvent

COMMUNICATION

wIQguard

wIQguard.odscp-2

0000

AlarmEvent

COMMUNICATION

wIQguard

* The ORGA MIB defines CancelEvent for all clear messages and AlarmEvent for all alarm raise.

Alsoatimestampisincludedineverytrap(EventTime)whichisnotincluded inthistable.

220

SNMP

7.2.2

wIQ
ThewIQprocessitselfwillbeSNMPenabledbyusingOLS.TherewillbeSNMP trapswheneverthewIQwaitsfororgetsaconnectiononitsTCP/IPports.This meanswhenwIQstartsup,itwillraiseanalarmthatitwaitsforaconnection andclearthisassoonasaconnectionwillbeestablished.WhenwIQshuts down,allraisedalarmswillbecleared. ThefollowingtrapsaregeneratedviaOLS: Event-ID 6196 6253 6255 OLS-Name MAIN.INFO.WAITING USSD.I.SOCKETCLOSED USSD.I.NEWCONNECTION Description Waitingfornewconnectionofaclient->raise Socketconnectionwas closed->raise Anewconnectionhasbeen establishedorwIQisterminating->Clearsallabove

1 2 3 4 5 6 7 A I

Thedynamicpartwillalwayscontainhost:portofthewIQhandlingthe trap.

221

SNMP Exampletrapsgeneratedfromthis:
AdditionalData (Dynamic mes-sage part)

OriginatingEquipment

6196

AlarmEvent CancelEvent

COMMUNICATION COMMUNICATION

wIQ_a

localhost:3364

Mainthreadnow waiting Gotnewconnection orprocessterminating Clienthasclosedthe socketconnection

6255

wIQ_a

localhost:3364

EventText (Mes-sage)

EventType

Specific *

Event-ID

Severity

1 2 3 4 5 6 7 A I

6253

AlarmEvent

COMMUNICATION

wIQ_a

localhost:3364

* The ORGA MIB defines CancelEvent for all clear messages and AlarmEvent for all alarm raise.

Optionallicenselimittrap(thisisdisabledbydefault): Event-ID 6524 OLS-Name SC_STREAM.I.LICENSELIMIT Description Licenselimitreached-> raise

ThedynamicpartwillcontaintheprocessnameofthewIQhandlingthetrap. Pleasenotethatthistrapwillneverbeclearedifenabled!

222

SNMP

7.2.3

Router
TherouterwillbeSNMP-enabledbyusingOLS. TherewillbeSNMPtrapswhenevertherouterwaitsfororgetsaconnection onitsports. Thismeanswhentherouterstartsup,itwillraiseanalarmthatitwaitsfora connectionforeverydriverandwIQconfiguredtoconnecttotherouter,and clearthisassoonasaconnectionwillbeestablishedtothisspecificdriveror wIQ.Whentheroutershutsdown,allraisedalarmswillbecleared. ThefollowingtrapsaregeneratedviaOLSfordriverconnections: Event-ID 6900 OLS-Name CONFIG.I.LISTENING Description Therouterislisteningona socketforadrivertoconnect->raise Therouterisconnectedtoa driver,ortherouterisshuttingdown->Clearsabove trap

1 2 3 4 5 6 7 A I

6917

CONN.I.CONNECTED

Thedynamicpartwillalwayscontainthedrivernamethetrapisrelatedto,so thistrapscanberaisedandclearedseparatelyforalldrivers. ThefollowingtrapsaregeneratedviaOLSforwIQconnections: Event-ID 6921 6920 OLS-Name CONN.I.NOTCONNECTEDWIQ CONN.I.CONNECTEDWIQ Description TherouterisnotconnectedtoawIQ->raise Therouterisconnected toawIQ,ortherouteris shuttingdown->Clears abovetrap

223

SNMP ThedynamicpartwillalwayscontainthewIQnamethetrapisrelatedto,so thistrapscanberaisedandclearedseparatelyforallwIQ's. Exampletrapsgeneratedfromthis:

AdditionalData (Dynamic mes-sage part)

OriginatingEquipment

6921

AlarmEvent

COMMUNICATION

router

WIQ1

WaitingforwIQ [WIQ1]toconnecton localhost:3364 wIQ[WIQ1]connectedon localhost:3364or routerterminating Listeningfor driver[SMSC1] toconnecton localhost:6825 Driver[SMSC1] connectedon port 6825or routerterminating

EventText (Mes-sage)

EventType

Specific *

Event-ID

Severity

1 2 3 4 5 6 7 A I

6920

CancelEvent

COMMUNICATION

router

WIQ1

6900

AlarmEvent

COMMUNICATION

router

SMSC1

6917

CancelEvent

COMMUNICATION

router

SMSC1

* The ORGA MIB defines CancelEvent for all clear messages and AlarmEvent for all alarm raise.

224

Appendix

A
1 2 3 4
A B C D E F G H P Q R S T U V W X a b c d e f g h p q r s t u v w x 7

A.1

Supported Characters from the GSM-Default Alphabet

Bitspercharacter: SMSUserDataLengthmeaning:Numberofcharacters CBS/USSDpadcharacter: CR

@ $

D _

SP ! " # % & (

0 1 2 3 4 5 6 7 8

5 6 7 A I

225

Appendix

LF CR

) * + , . /

9 : ; < = > ?

I J K L M N O

Y Z

i j k l m n o

y z

FortheGSMalphabetseeGSM03.38version7.2.0Release1998.

1 2 3 4

A.2

Mapping from HTML 3.2 to USSD/SMS

Mapped ASCII characters (displayed as ?) Character [ \ ] ^ { | } ~ HTML name ? ? ? ? ? ? ? ? ? Display

5 6 7 A I

226

Appendix Mapped ASCII characters (displayed as ?) Character HTML name &cent; &brvbar; &uml; &copy; &ordf; &laquo; &not; &shy; &reg; &macr; &deg; &plusmn; &sup2; &sup3; &acute; &micro; &para; &middot; &cedil; &sup1; ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? Display

1 2 3 4 5 6 7 A I

227

Appendix Mapped ASCII characters (displayed as ?) Character HTML name &ordm; &raquo &frac14; &frac12; &frac34; &ETH; &times; &THORN; &divide; ? ? ? ? ? ? ? ? ? Display

1 2 3 4 5 6 7 A I

ThecharactersinthefollowingtableareconvertedintocharacterswithasimilarappearancebecausetheyarenotdefinedintheGSM-alphabet.

Character

HTML name &Agrave; &Aacute &Acirc &Atilde; &Egrave; &Ecirc; A A A A E E

Similar character

228

Appendix

&Euml; &Igrave; &Iacute; &Icirc; &Iuml; &Ograve; &Oacute; &Ocirc; &Otilde; &Ugrave; &Uacute; &Ucirc; &Yacute &aacute; &acirc; &atilde; &ccedil; &ecirc; &euml; &iacute; &icirc;

E I I I I O O O O U U U Y a

1 2 3 4 5 6 7 A I

a c e e i i

229

Appendix

&iuml; &oacute; &ocirc; &otilde; &uacute; &ucirc; &yacute;

i o o o u u y

A.3
A.3.1

Changes
New Features for wIQ 1.0
1. Subscriber Subscriberscangetamobilephone-specificconfigurationdata. Dependingontheoperatorstrategy,thesubscriberwillbenefitfroma subscriber-specificservicenumberlist 2. Operator Theoperatorisabletosetuptheconfiguration: a)Dialogtoselectahandset-specificcharactermappingusedforinputduring wIQdialoginputonly b)AutomaticcalloftheMSconfigurationdialog c)CallbyservicenumberoftheMSconfigurationdialog Inaddition,anindividualsubscriberprofilekeycanbeconfigured.This profiletypewillidentifytheservicenumber-URLmappingtablewhich willbeusedforthissubscriber. Varioussubscriber-specificprofiledatawillprovidesmartoverallinformation.

1 2 3 4 5 6 7 A I

230

Appendix 3. Configuration Data Charactersetsfordifferenthandsets. NowtwosetsoffileswhichcontainUSSDtoURLMappingandValid URLtablesforupto62differentgroups MainconfigurationfileofthewIQisextendedbysomeentriestoconfigurethesenewfeatures.

A.3.2

New Features for wIQ 1.1

limitofmaximumallowedinputsincreasedto20 AlldatabasefieldscouldbepassedtotheURL CharacterswhichareunknownintheGSMalphabetmaybemappedto similarlookingcharacters Newerrormessageissenttothesubscriber Optimizedperformance IncreasesupportofincomingGSMcharacters Allowreconfigurationduringruntime Terminationforcesan"abort"ofallopensessions ForminputissentURL-form-encoded Configurationofmulti-levelservicenumber Billing httpssupport

1 2 3 4 5 6 7 A I

A.3.3

New Features for wIQ 1.2

SMSsupport

A.3.4

New Features for wIQ 1.3

Pushinterface Supportofhiddeninputfields ExtendedwIQHTMLtagsforsessionsettingsfromanHTMLpage

231

Appendix Splittedmainconfigurationfile SMSclient SMPP Router

A.3.5

New Features for wIQ 1.4

ESMSsupport IMEIsupport

A.3.6

New Features for wIQ 1.5

SupportofSMPP SupportofEMIUCP NewORGANSG

1 2 3 4 5 6 7 A I

A.3.7

New Features for wIQ 1.6

SNMPsupport LDAPsupport Arabiclanguagesupport

A.3.8

New Features for wIQ 1.7

Multiplelanguagesupport

A.4

HTML Pages for Keytable Configuration

<HTML> <HEAD><TITLE>ORGA Net</TITLE></HEAD> <BODY> Mobile selection<BR> <FORM method="get"

232

Appendix action="http://wIQ.orga.com/cgi-bin/keymap1.pl"> 1 NOKIA<br> 2 ERICSSON<br> 3 OTHER<br> <input type="text" name="type"> </FORM> </BODY> </HTML> IfthesubscriberselectsOTHER,aseconddialogmightfollow: <HTML> <HTML> <HEAD><TITLE>ORGA Net</TITLE></HEAD> <BODY> Keytable config<BR> <FORM method="get" action="http://wIQ.orga.com/cgi-bin/keymap2.pl"> Please press the key 2 once! <input type="text" name="key"> </FORM> </BODY> </HTML>

1 2 3 4 5 6 7 A I

233

Appendix

A.5

Use of the wIQ Web Interface

Toregister,youhavetoaccessthefollowingentrypagethroughaninternet browserwith http://<name of the wIQ Server>:<port>/index.php Example: http://wiq21:8080/index.php

1 2 3 4 5 6 7 A I

Start screen

234

Appendix YoucanselectoneofthelinkswIQ Administration Interface,Read-Only Subscriber Database Interface,andPHP Information.

A.5.1

wIQ Administration Interface

ThewIQAdministrationInterfaceareacanbeprotectedbyusernameand passwordifthisisincludedintheinstallationofyoursystem. WhenyouhaveselectedthewIQ Administration Interfacelink,youcanselectoneofthefollowinglinks: LimitedSubscriberDatabaseInterface CompleteSubscriberDatabaseInterface IncoreInterface IncoreManualPage

1 2 3 4 5 6 7 A I

A.5.1.1

Limited Subscriber Database Interface

Usingthisinterface,youcancreateanewsubscriberorsearchforasubscriber intheSubscriberdatabase.Thesubcribersdatacanbeedited,butonlyasubsetofthesubscribersattributescanbechanged. Afterclickingthislink,youarefirstaskedtoenterthesubscribersMSISDN.If hedoesnotyetexistinthedatabase,anewdatabaseentrywillbecreated. IfyouclicktheSUBMITbutton,theresultofyourqueryisdisplayed.Itisspecifiedwhichentriesmaybeedited.

A.5.1.2

Complete Subscriber Database Interface

Usingthisinterface,youcancreateanewsubscriberorsearchforasubscriber intheSubscriberdatabase.Allthesubcribersdatacanbeedited. IfyouclicktheSUBMITbutton,theresultofyourqueryisdisplayed.

A.5.1.3

Incore Interface
Usingthisinterface,youcanadminstertheInCore(SubscriberData)database.

235

Appendix Itallowsyoutoexecuteanydatabasecommandsoyouhavetobecareful withthecommandsyouenterandyouhavetobefamiliarwiththeIncoredatabasecommandlinesyntax. IfyouclicktheSUBMITbutton,theresultofyourqueryisdisplayed.

A.5.1.4

Incore Manual Page

ThisistheIncoredatabasehelppageinthestyleofthePHPHTMLmanual.

A.5.2

Read-Only Subscriber Database Interface

TheRead-OnlySubscriberDatabaseInterfaceareacanbeprotectedbyuser nameandpasswordifthisisincludedintheinstallationofyoursystem. UsingthislinkinthewIQAdministrationInterface,youcanquerytheSubscriberDatabase,butyouarenotallowedtochangeanydata.

1 2 3 4 5 6 7 A I

A.5.3

PHP Information
UsingthislinkinthewIQAdministrationInterface,youareinformedabout thePHPversioncurrentlyinstalledonthissystem.

A.6

System Activity Reporter

Tomaintainsystemresourcesandperformance,thesystemactivityreporter shouldbeactivated.Thisactivationisdonewiththestart-upscriptin /ect/rc2.d/S21perf. Example:
# Copyright (c) 1997 by Sun Microsystems, Inc. # All rights reserved. # #ident "@(#)perf.sh 1.7 97/12/08 SMI"

# Uncomment the following lines to enable system activity data gathering.

236

Appendix
# You will also need to uncomment the sa entries in the system crontab # /var/spool/cron/crontabs/sys. Refer to the sar(1) and sadc(1m) man pages for more information.

if [ -z "$_INIT_RUN_LEVEL" ]; then set -- `/usr/bin/who -r` _INIT_RUN_LEVEL="$7" _INIT_RUN_NPREV="$8" _INIT_PREV_LEVEL="$9" fi

if [ $_INIT_RUN_LEVEL -ge 2 -a $_INIT_RUN_LEVEL -le 4 -a \ $_INIT_RUN_NPREV -eq 0 -a \( $_INIT_PREV_LEVEL = -o \ $_INIT_PREV_LEVEL = S \) ]; then

1 2 3 4 5 6 7 A I

/usr/bin/su sys -c "/usr/lib/sa/sadc /var/adm/sa/sa`date +%d`" fi

Anadditionalcrontab -e sysisnecessaryaswell: #crontab-esys

0 * * * 0-6 /usr/lib/sa/sa1 20,40 8-17 * * 1-5 /usr/lib/sa/sa1 5 18 * * 1-5 /usr/lib/sa/sa2 -s 8:00 -e 18:01 -i 1200 -A

A.7

Backup and Restore of the Sun Solaris Operating System

IncaseofasystemfailureyouneedtorestoretheSunSolarisOperatingSystemfromabackup,usuallystoredontape.However,whenyouhavetoreplaceaharddrivebyanewone,afullrestoreofthesystemrequiresmore

237

Appendix than"just"thedataresidingontheroot(/)partition,meaningespeciallythe partitioninginformation(VTOC-VirtualTableofContents)ofthesystems harddriveanditsWorldWideNumber(WWN). ThemainfocusofthischapteristhebackupandrestoreoftheSunSolarisOS usingstandardtoolslikeufsdumpandufsrestoreingeneralwithouttaking RAIDconfigurationintoconsideration.Theconfiguration,backup,andrestoreofRAIDdevicesiscoveredinsectionA.7.11includingastep-by-stepdescriptionofhowtorestoreyoursystemandyourRAID(mirror)configuration. Ifyoujustwanttorestoreyoursystemfromabackuptapeyoumightaswell skipthefollowingdetailedintroductionsandusethemjustforreferencepurposes.Thestep-by-stepdescriptionisbasicallyallyouneedtoknowwhenit comestorestoringasystem"fromscratch". Forallthefollowingbackupandrestoretasksyouhavetohave super-userprivileges,meaningthatyouhavetobeloggedinasuser root.Someofthetasksbelowalsorequirethesystemtobe bootedinsingle-usermode,interruptingnormalsystemoperation. Thesesymbolsareusedinthefollowingsections: % ok rsc> indicatesashellprompt(whenthesystemisbootedupproperly) indicatestheBootPROMminishellenvironment indicatestheRemoteSystemControl(RSC)mode

1 2 3 4 5 6 7 A I

A.7.1

Introduction to Backup and Restore

Tobackupafilesystemithastobeinactive,meaningthatiteitherhastobe unmounted,orthesystemhastobeinsingle-usermodesothatnowritings tothefilesystemwilloccur.Themostimportantconsequenceofthisfactis thatthesystemwillnotbeabletoperformnormaloperations,e.g.running services,whileabackupisbeingperformed. Therefore,itisrecommendedtoperformabackupofthesystemsroot(/)partitionandotherimportantdatabeforeitgoesintoproduction. However,keepinmindthatthisbackupwillonlyenableyoutorestorethesystemsstateasitwasupondelivery. Allchangesthathavebeenmadetothesystemsconfigurationafterithas beenputintoproductionwillbelost.

238

Appendix

A.7.2 A.7.2.1

Installing and Using a Tape Drive Installing a Sun StorEdge Tape Drive
BackupsareusuallystoredontapeusingtapedrivessuchastheSunStorEdge system.ThissectionbrieflydescribeshowtoinstallanduseaSunStorEdge DDS-4tapedriveconnectedtotheSCSIcontroller.Foramoredetaileddescriptionseethemanualofyourtapedrive. Toconnectatapedrivetoyourserverithastobeshutdownandpowerto boththeserverandthetapedrivehastobeswitchedoff.Toshutdownthe serverproperly,issuesomethingsimilartothefollowingcommand(asroot): % shutdown -i0 -g0 -y AfterthesystemisproperlyshutdownyouwillautomaticallyentertheBoot PROM"shell",indicatedbyanokprompt.WithintheBootPROM,issuethe followingcommandsequence: ok setenv auto-boot? false ok reset ok probe-scsi (thesystemwillresetitself) (enteredafterthesystemhasbeenrestarted reset)

1 2 3 4 5 6 7 A I

Theprobe-scsi commandwillprovidedetailsaboutotherSCSIcomponents andtargetIdsusedwithinthesystem,makingitpossibletoselectaSCSIID forthetapedrivetobeconnectedthatisnotinuse.Afterwritingdownthe usedSCSIIdsandconfiguringthetapedrivesSCSIID,poweroffthesystem toconnectthetapedrive: ok power-off Whentheserverispoweredoff,youcanconnectthetapedrivetotheexternalSCSIport.MakesurethatitsSCSIdeviceIDisproperlyconfiguredandnot usedbyanothersystemcomponent. AfterconnectingthetapedrivetotheSCSIbus,firstpoweronthetapedrive andthentheserver.UponenteringtheBootPROMoftheserverissuethefollowingcommands: ok setenv auto-boot? true

239

Appendix ok boot -r Theboot -rcommandisimportant.Thiswaythesystementersareconfigurationmodetoscanfornewdevices,thetapedriveinthiscase.Oncethesystemisbooted,thetapedriveshouldbereadytobeused.Checkthisbyusing thefollowingcommand: % mt -f /dev/rmt/0 status ThisshouldresultinamessagesayingthataSunStorEdgeDDS-4tapedrive iscorrectlyrecognized: DAT tape drive... ThespecificSenseKeyreturnedisusuallynotanissue.Makesurethatnoothererrormessagesarereported.Thecommandaboveassumesthatthenew tapedriveistheonlyoneknowntothesystem.

1 2 3 4 5 6 7 A I

A.7.2.2

Using a Tape Drive

InSolaris,tapedrivesarerecognizedandusedbylogicaldevicenamesstarting with /dev/rmt/ followedbyalogicaltapenumberandpossiblyadditionalparameters.Alogicaltapedrivenamecouldbeoneofthefollowing: /dev/rmt/0 (referringtodrivenumber"0"withnoadditionalparameters) /dev/rmt/0n (referringtodrivenumber"0"withthenorewindoption) Additionalparametersareusedtoindicatedthetapedensity: l(low), m(medium), h(high), c(compressed), u(ultracompressed).

240

Appendix Thenoption(norewind)indicatesthatthetapeshallnotrewindaftersome datahasbeenwrittenontoit.Thisisespeciallyimportantifyouwanttostore severaldifferentbackups(e.g.differentfilesystems)ononetape.Ifyoudo notspecifythisoption,asubsequentufsdumpcommandwillsimplyoverwrite anotherbackupyouhavejustmade. Asindicatedabove,youusetheufsdumpandufsrestorecommandstocreate dumps(backups)offilesorfilesystems.

A.7.3

Using ufsdump and ufsrestore

TheSunSolaristoolsusedforbackupandrestoreoffilesandfilesystemsare ufsdumpandufsrestore.Thissectionprovidesashortintroductiontobothof thesecommands.Foradditionalinformationandusagepleaserefertothe manualpagesofbothcommands.

1 2 3 4 5 6 7 A I

A.7.3.1

Introduction to the ufsdump Command

Thecommandufsdumpisusedtocreatebackupsoffilesorcompletefilesystems,preferablyontapedrives. Itcanbefoundin/usr/sbin/. Youcanspecifybackuplevelsaswellasotherparametersinthecommand line.Pleaserefertothemanualpageofufsdumpforafulllistofoptions.The usualcallofufsdumplookslikethis: % ufsdump 0uf /dev/rmt/0 /dev/rdsk/c0t0d0s5 Thiscreatesalevel0dump(backup)oftheUFSfilesystemresidingonslice5, andalsoupdatesthelistofupdatesthathavebeenperformed,storedin /etc/dumpdates.

A.7.3.2

Introduction to the ufsrestore Command

Thecommandufsrestoreisusedtorestorefilesorfilesystemsfromapreviouslymadebackuptape.Atypicalcallofufsrestorelookslikethis: % cd /dir/to/be/restored

241

Appendix % ufsrestore rvf /dev/rmt/0 Pleasenotethatufsrestorealwayswritestherestoreddataintothe currentdirectory,meaningthatyouusuallyhavetoissueacdcommandbeforerestoringcertainfilesorfilesystems!Incaseofafile system,thisalsohastobemountedatacertainpointtoallowthe cdcommandtoworkproperly.Pleaserefertothemanualpageof theufsrestorecommandforacompletelistofoptions,parameters, andusage.

A.7.3.3

Backing up Several File Systems on a Single Tape

Ifyoudonotwanttostoreeachfilesystemonaseparatetape,e.g.toreduce thenumberoftapesrequiredforacompletesystembackup,youhaveto specifytheno-rewindoption(n)alongwiththelogicalnameofthetapedrive. Herearesomeessentialstepsnecessarytobackupmorethanonefilesystem onasingletape: Insertthetapeintothetapedrive Rewindthetapetogetitintothe"startingposition"usingthemt command: % mt -f /dev/rmt/0n rewind Useufsdumptobackupthefilesystem(s),forexample: % ufsdump 0uf /dev/rmt/0n /dev/rdsk/c0t0d0s0 % ufsdump 0uf /dev/rmt/0n /dev/rdsk/c0t0d0s7 Thisdumpsslices0and7ononetapewithoutrewindingthetape(and thereforeoverwritingpreviouslymadebackups). Rewindthetapeandpossiblymakeitoffline(toejectthetape): % mt -f /dev/rmt/0n rewoffl Thefollowingshellscriptismeanttosupportyourtaskofbackingupseveral filesystems(diskslices)onasingletape.Keepinmindthatyouhavetoadjust theslicenamestoyoursystemconfiguration.Youmayalsoneedtoremove oraddsomeoftheslices.ItmaybeprovidedbyORGAas /backup.sh.

1 2 3 4 5 6 7 A I

242

Appendix

#!/sbin/sh # Run this in single user mode as root partition is backed up! #use tape with options (c)ompressing and (n)orewind TAPEDRIVE="/dev/rmt/0cn" #save rawdevices PREFIX="/dev/rdsk/" #root and home filesys FILESYS="c1t0d0s0 c1t0d0s7" #Add flag u for writing /etc/dumpdates FLAGS="0f" echo "Using tape drive $TAPEDRIVE" echo "Backing up filesystems $FILESYS with prefix $PREFIX" echo "" echo "Rewinding tape..." mt -f $TAPEDRIVE rewind echo "Saving vtoc to tape..." prtvtoc /dev/rdsk/c1t0d0s2 > $TAPEDRIVE echo "Dumping filesystems..." for X in $FILESYS do FS=$PREFIX$X /usr/sbin/ufsdump $FLAGS $TAPEDRIVE $FS done echo "Rewinding tape..." mt -f $TAPEDRIVE rewoffl

1 2 3 4 5 6 7 A I

Thescriptmentionedabovecreateslevel0dumpsofthefollowingfilesystems(diskslices): /dev/rdsk/c1t0d0s0(sequence number for mt: 0) /dev/rdsk/c1t0d0s7(sequence number for mt: 1) whichwillbestoredonasingletape. Tocheckthatallthesebackupshavebeensuccessfullyperformedplease checkthefile

243

Appendix /etc/dumpdates whichindicateswhichbackupshavebeensuccessfullyperformed(when theuoptionoftheufsdumpcommandhasbeenspecified).Afterasuccessfulbackupthefileshouldlooksimilartothis: % cat /etc/dumpdates /dev/rdsk/c1t0d0s0 0 Fri Feb /dev/rdsk/c1t0d0s7 0 Fri Feb Torestoreanyofthesefilesystems makesurethatyoupositionthetapecorrectlyusingeithermtor ufsrestoreoptions.Forexample,ifyouwanttorestorethefilesystem storedinslice/dev/rdsk/c1t0d0s7youhavetomakesurethatthe correctstartingpointofthetapeisbeingused: % mt -f /dev/rmt/0n asf1 (sequence#formtis"1",seeabove) thenissuetheufsrestorecommand,ordirectlyuse % ufsrestore rvfs /dev/rmt/0n 2 Attention!Add1tomtssequence#! Foradditionaldetailsseethemanualpagesofmtandufsrestore. 8 15:59:08 2002 8 16:04:05 2002

1 2 3 4 5 6 7 A I

A.7.4

Saving and Restoring Partitioning Information

Inordertosavethepartitioningdata(VTOC)ofthesystemsharddrive,use theprtvtoccommand.Theoutputofthiscommandcanbeusedtorestore theoriginalpartitioning(sliceconfiguration)ofthesystemafterasystemfailureusingthefmthardcommand.Togetalistingofpartitioninginformation foradisk,usetheprtvtoccommandasshownintheexamplebelow: % prtvtoc /dev/rdsk/c1t0d0s2 >/vtoc Thisexampleassumesthat/dev/rdsk/c1t0d0s2isyoursystemsprimary harddrive.TheVTOCinformationisstoredinafilenamed/vtoc(residing

244

Appendix ontheroot(/)partition).Savethisdata,e.g.onafloppydiskorbytransferring ittoanothercomputerusingFTP,andalsomakeahardcopyofthisfileby printingit.Placethisprintoutnexttothemachinetohaveitathandincase ofarestore! AfteradiskreplacementyoucanusethisfilecontainingtheVTOCdatatorestoretheoriginalpartitions(slices)byusingthefmthardcommandasinthe followingexample: % fmthard -s /vtoc /dev/rdsk/c2t0d0s2 Thisexampleassumesthatyouhaverestoredthefile/vtocusingabackup andthat/dev/rdsk/c2t0d0s2isyournewsystemsprimaryharddrive.If youcannotaccessthisVTOCdatafile,youwouldhavetocreateitwithan editorusingyourprintout.

1 2 3 4 5 6 7 A I

A.7.5

Restoring the World Wide Number (WWN)

TheFC-ALdiskdrivesusedintheSun280Rservershaveaso-calledWorld WideNumber.Thisnumberuniquelyidentifieseachdrive.Afterasystem/ drivecrash,thisnumberhastoberestored.ThefollowingbasicstepsarerequiredtorestoreaWWN.ThesearealltakenoutoftheSunSolvedocument ID"SRDB17643",pleaseseethisdocumentforadditionaldetailsandreferencedocumentation. ThebootdiskfailsandisreplacedbyanotherdiskwithadifferentWWN. BootthesystemintosingleuserfromtheCDROMornetwork. Labelthereplacementdisktomatchtheslicesfromthefailedone(see fmthard) Createfilesystemsonalltheslicestoberestored(usingnewfs). Mounttherootfilesystemandrestorethedatafrombackups(seebelow). Installthebootblockontotherecoveredrootsliceusingtheinstallboot command Withrootmountedunder/arunthefollowingcommandstorebuildthe devicestree: % drvconfig -r /a/devices -p /a/etc/path_to_inst

245

Appendix % cd /devices % find . -print | cpio -pduVm /a/devices % disks -r /a % devlinks -r /a Note:Allthecommandsdescribedabovearemandatory!Donot skipanyofthesesteps! Configurethe"boot-device"parameterintheEEPROMusingthe followingcommand(assumingthatc1t0d0s0isyourrootslice): ok luxadm set_boot_dev /dev/dsk/c1t0d0s0. Restoretheotherfilesystemsonthatdisk,orcommentouttheentriesfor themfrom/a/etc/vfstab.AtleastyoumusthavealltheSolarisfile systems(ROOT,/var,/usr,/opt,etc.)recovered. Rebootthesystemfromtherecovereddisk.

1 2 3 4 5 6 7 A I

A.7.6

Creating a Backup of the Systems Root (/) Partition

Specialproceduresarerequiredtocreateabackupofthesystemsrootpartition.Sincetheroot(/)partitioncannotbeunmounted,thesystemhastobe bootedintosingle-usermodetopreventdatacorruption.Thefollowingsteps illustratehowyoucanperformabackupoftherootpartition: Loginasuser"root"andmakesurethesystemisnotinproduction,i.e.it doesnotrunanycriticalsystem/userprocesseswhichwillotherwisebe interrupted. Bringthesystemtoahalt(runlevel0)andbootitintosingle-usermode: % init 0 (shutdownmessages,followedbythe"ok"BootPROMshellprompt) ok boot -s Insertan(empty)tapeintothetapedrive Usetheufsdumpcommandtocreateabackupoftherootfilesystem: % ufsdump 0uf /dev/rmt/0 /dev/rdsk/c0t0d0s0 Thisexampleassumesthatyourrootpartitionresideson

246

Appendix /dev/rdsk/c0t0d0s0. Yoursystemconfigurationmaybedifferent.Itisalsoassumedthatyoudo notusethistapetostoreadditionalbackupsonitnexttothisroot partition.Ifyouintendtostoreadditionalfilesystemsonthesametape, pleaseusethenoption(norewind)whenspecifyingthetapedrivesname (seeabove). Checkwhethertherootfilesystemhasbeenproperlybackedup: % ufsrestore tvf /dev/rmt/0 Allowthesystemtobootintorunlevel3toresumenormaloperations: % exit (or press CONTROL-D)

A.7.7

Restoring the Systems Root Partition

Restoringthesystemsroot(/)partitionisadelicateprocedure.Firstofall,the systemwillnotbeabletobootwithoutaproperrootpartition.Therefore,you wouldhavetobootthesystemusingabootCDROMorfromthenetwork. Afterrestoringtherootpartitionyoualsohavetomakesuretowriteasuitablebootblockontothenewlyrestoredrootpartition.Thissectionincludes thenecessarystepstorestoreasystemsrootpartition. 1.) Sincethesystemcannotbootwithoutarootpartitionyouwillendupin thesystemsBootPROMminishell,indicatedbythe"ok"prompt.When bootingfromtheSunSolarisCDROMpleasemakesuretoinserttheCD named"Solaris8CD1of2"intoyourCDROMdrive.Thenbootthesystemintosingle-usermodeusingtheCDROM: ok boot cdrom -s 2.) Ifnecessary,recreatethepartitioninginformation(VTOCdata)ofthehard drivebyusingthefmthardcommandwiththepreviouslysavedVTOC data.Pleaserefertothefmthardandformatmanualpagesforadditional information.Acalloffmthardmaylooklikethis: % fmthard -s /tmp/vtoc /dev/rdsk/c0t0d0s2 3.) Createanewfilesystemonthesystem'srootslice, e.g. /dev/rdsk/c0t0d0s0 % newfs /dev/rdsk/c0t0d0s0 4.) Mountthenewlycreatedfilesystemonan"empty"mountpoint, e.g./a,andchangeintothatdirectory(seethesectiononufsrestoreon whyyoushoulddothis):

1 2 3 4 5 6 7 A I

247

Appendix % mount /dev/dsk/c0t0d0s0 /a % cd /a 5.) Usetheufsrestorecommandtorestoretherootfilesystemfromtape: % ufsrestore rvf /dev/rmt/0 Ifyouhavestoredseveraldifferentfilesystemsonasingletape(see above)makesurethatyourtapeispositionedatthecorrectstartingpoint oftherootfilesystemdata,eitherusingthemtcommandorappropriate optionsforufsrestore! 6.) Deletethefilerestoresymtablethatufsrestorecreatedinthecurrent directory: % rm restoresymtable Ifyoucannotfindthisfile(beforeissuingthermcommand),thisindicatesthatsomethingwentwrongduringtherestoreofthefilesystem. 7.) Restoretherootfilesystemsbootblock!Thisisanimportantstepand alsodependentonyoursystem.Issuethefollowingsequenceofcommandstorestoreaproperbootblock: % cd /usr/platform/`uname -i`/lib/fs/ufs % installboot bootblk /dev/rdsk/c0t0d0s0 TherequiredbootblockinformationisstoredontheCDROMandmade availableinthedirectorymentionedaboveafterbootingfromit.Inthe exampleabove,youmighthavetouseuname -minsteadof uname -i Unmountthenewlycreatedfilesystem: % cd /; umount /a 8.) Checkthefilesystemagaintomakesureitisinaproperstate: % fsck /dev/rdsk/c0t0d0s0 9.) Rebootthesystem: % init 6 10.)Forsecurityreason,syoushouldperformanotherlevel0backupofthe newlycreatedrootfilesystem(onanothertape)onceyouhaveverified thatthesystemisworkingproperly. % ufsdump 0uf /dev/rmt/0 /dev/rdsk/c0t0d0s0

1 2 3 4 5 6 7 A I

248

Appendix

A.7.8

Restoring other important system partitions (/usr, /var/, ...)

Torestoreotherimportantsystempartitionslike/usr,/var,etc.youcanuse basicallythesameprocedureasfortheroot(/)partition.However,therestore ofabootblockis,ofcourse,notnecessaryforthesepartitions.Therefore,you skipstep7inthescenariodescribedaboveforrestoringtherootpartition.

A.7.9

Restoring normal (User) Partitions

Torestorefilesystemsofnormal(user)partitionslike/exportor/opt,the systemcanbebootednormally(intorunlevel3),assumingthatthesepartitionswillnotbemountedautomatically.Youcanthereforeskipsteps1,2,7, and10inthescenariodescribedaboveforrestoringtherootpartition.You stillneedtocreatethenewfilesystem(s)andmountthemmanuallytorestore thedatafromtapeusingufsrestore.

1 2 3 4 5 6 7 A I

A.7.10 A Note Concerning /tmp

Ifyouhaveadirectoryorfilesystemnamed/tmponyoursystem,youusually donotneedtobackupandrestorethisdata.Itissufficienttorecreatethepartitioningdataasdescribedearlierinthisdocumentandcreateanewfilesystemusingnewfsonthepartitionwhere /tmpissupposedtoresideon.The reasonisthat/tmpisonlyusedasatemporarystoragewhichwillbedeleted anyhowduringarebootofthesystem. Theonlyimportantthingregarding/tmpisthatyouneedtorestoretheappropriateaccessrightstothisfilesystemaftercreatingitwithnewfs: chmod 777 /tmp willdothisforyou.

A.7.11 Backing Up and Restoring of RAID Metadevices

WhenyouareusingSolsticeDiskSuitetocreateRAIDmetadevices,thebackupandrestorestrategyisdifferentfromtheproceduredescribedabove.The majordifferenceisthedevicenamesthatareusedbythesystem.Forexample, youwoulduse/dev/md/rdsk/d11insteadof /dev/rdsk/c0t0d0s0wheremdindicatestheuseofaso-calledmetadevice.

249

Appendix ForadditionalinformationconcerningmetadevicesandtheSolsticeDiskSuite softwareingeneral,pleaserefertotheSolsticeDiskSuiteUserManual.This manualcanonlycoversmallportionsofwhatispossiblewithmetadevices. Thestep-by-stepdescriptionofbackupandrestore,however,containsfurther informationonmetadevices. Runningthemetastatcommandprovidesyouwithmoredetailsaboutthesetupofthemetadevices.Pleaserefertothemanualpageofthiscommandfor additionalinformation.

A.7.11.1 Troubleshooting Metadevices

ThissectionbasicallyrepeatsinformationthatispartoftheSolsticeDiskSuite UserManual,pleaserefertothatmanualforalldetails! Forpropertroubleshootingyouhavetomeetthefollowingprerequisites: Youmusthavesuper-user(root)privileges Youmusthaveacurrentbackupofthesystemdata

1 2 3 4 5 6 7 A I

Youwillneedthefollowingathandforasuccessfultroubleshootingprocess: Contentsofthe/etc/vfstabfile Statusofstatedatabasereplicas,metadevices,andhotspares,eitherfrom Disk-SuiteToolorfromtheoutputofthemetadbandmetastatcommands Diskpartitioninginformation,eitherfromtheprtvtoccommandorStorageManager

A.7.11.2 Recovering the DiskSuite Configuration

From the Solstice DiskSuite User Manual: The/etc/lvm/md.cffileisabackupfileoftheDiskSuiteconfigurationfor alocaldisk-set.Wheneveryoumakeaconfigurationchange,themd.cffile isautomaticallyupdated(exceptforhotsparing).Younevereditthemd.cf filedirectly.

250

Appendix Ifyoursystemlosestheinformationmaintainedinthemetadevicestatedatabase,andaslongasnometadeviceswerecreatedorchangedinthemeantime,youcanusethemd.cffiletorecoveryourDiskSuiteconfiguration. Themd.cf filedoesnotmaintaininformationonactivehotspares. Thus,ifhotspareswereinusewhentheDiskSuiteconfiguration waslost,thosemetadevicesthatwerehot-sparedwilllikelybecorrupted.

A.7.11.3 How to Use the md.cf File to Recover a DiskSuite Configuration

ThefollowingprocedureshouldonlybeusedifyouhaveexperiencedacompletelossofyourDiskSuiteconfiguration.Thisisusuallythecaseifyourroot filesystem(onbothmirroreddrives)hasbeendestroyedandyouhavetoreconstructthewholesystem.Ifonlyonesubmirrorisdestroyed,youcanuse theremainingsubmirrortobootthesystemandrepairit.Pleaserefertothe SolsticeDiskSuiteUserManualforadditionaldetails!FromtheSolstice DiskSuiteUserManual:RecoveraDiskSuiteConfiguration 1.) Recreatethestatedatabasereplicas.Astatedatabasereplicastores DiskSuiteconfigurationandstateinformation.Beforeyoucanuse DiskSuite,youmustcreatestatedatabasereplicas.Usemetadbtocreate thesedatabasereplicas.Forexample: % metadb -a -f -c 2 c0t1d0s5 c0t2d0s5 2.) Makeabackupcopyofthe/etc/lvm/md.tabfile. 3.) Copytheinformationfromthemd.cffiletothemd.tabfile. 4.) Editthe"new"md.tabfilesothat: -Allmirrorsareone-waymirrors.Ifamirrorssubmirrorsarenotofthe samesize,besuretousethesmallestsubmirrorforthisone-waymirror. Otherwisedatacouldbelost. -RAID5metadevicesarerecreatedwiththe-koption,topreventreinitializationofthedevice.(Refertothemetainitmanpageformoreinformationonthisoption.) 5.) Runthemetainitcommandtocheckthesyntaxofthemd.tabfileentries. % metainit -n -a

1 2 3 4 5 6 7 A I

251

Appendix 6.) Afterverifyingthatthesyntaxofthemd.tabfileentriesiscorrect,run themetainitcommandtorecreatethemetadevicesandhotsparepools fromthemd.tabfile. % metainit -a 7.) Runthemetattachcommandtomaketheone-waymirrorsintomultiwaymirrors. 8.) Validatethedataonthemetadevices. Thereisanalternativetothemethoddescribedabovewhichisusingthedd commandtowritetheMetaDBtofile(s)ontherootpartition.Thesefilesare thenstoredontapeduringabackupoftherootpartition.Pleaseseethestepby-stepdescriptioninthefollowingsectionsforallthedetails.

1 2 3 4 5 6 7 A I

A.7.12 Backing up and Restoring a System Step by Step

Theprevioussectionsprovideyouwithadetailedintroductiontothebacking upandrestoringoftheSunSolarisOperatingSystem.Thissectiongivesyou alistoftasksandcommandsthatyouwouldhavetoperformorenterinorder tobackupandrestoresuccessfullyaSunSolarisOperatingSystemincluding RAIDmirrordevices(metadevices).Ifanythinginthisstep-by-stepdescription isuncleartoyou,pleasehavealookatthepreviouschapterformoredetailed descriptionsofwhatthecommandsdoandhowtheyareworking.

A.7.13 Requirements
Forthefollowingstep-by-stepdescriptiontobesuccessfullycompletedweassumethatyourSunSolarisserverhasthefollowingbasicconfiguration: SunSolaris8OperatingSysteminstalled SolsticeDiskSuiteinstalled ARAIDsystemusingtwoidenticalmirroreddisks ItisalsorequiredthatyouhavetheSolarisOSbootCD-ROMsavailableand thatyoucanconnecttothesystemusingeitherRSC(RemoteSystemControl) oraserialconsole.

252

Appendix

A.7.14 Creating a Full System Backup Including the Root File System
Tocreateafullbackupofthesystemincludingtheroot(/)filesystemfollow thestepsprovidedinthissection. 1.) Attachatapedrivetothesystem.Additionaldetailsonhowtodothisare providedinthesectionInstallingandUsingaTapeDriveonpage 239. Youmightalsowanttouseatapedrivethatisconnectedtoaremote machine.PleaserefertotheSunSolarismanualstofindouthowtodo this. 2.) SavethepartitioninginformationandtheMetaDB.Thepartitioning informationisneededtorestorethepartitionsonaharddriveinexactly thesamewayasithasbeenbefore.TheMetaDB(metadevicedatabase) isusedbySolsticeDiskSuiteandcontainsvitalinformationaboutthe RAIDmirrorconfiguration. 2.1. Useprtvtoctoprintthepartitioninginformation(VTOC)ofthesystem's harddrivetoafilenamedvtocresidingontheroot(/)partition.Itis onlynecessarytodothisforoneoftheharddrivesbecausethesecond oneissupposedtobeanexactmirrorofthefirst. % prtvtoc /dev/rdsk/c1t0d0s2 >/vtoc Thecommandmentionedaboveservesasa"precaution"sinceyou wouldusuallysavethepartitioninginformationalsoasthefirstfileon thebackuptape,seestep(3)below.However,itisessentialthatyou printoutthisdataandkeepitnexttoyourmachine! 2.2. UsethemetadbcommandtofindoutwheretheMetaDBisstored,for exampleonslices/dev/dsk/c1t0d0s5and/dev/dsk/c1t1d0s5. Ittakesupexactly2084bytes(offset_first_block(=16)+1034+1034= 2084blocks).

1 2 3 4 5 6 7 A I

253

Appendix Example:

% metadb flags a m p [...] lu first blk 16 block count 1034 /dev/dsk/c1t0d0s5

2.3. UseddtosavetheMetaDBtotherootpartitioninordertobackitup alongwiththerestofthedataresidingonthesystemsrootpartition lateron.Makesureyouusetherdskdevicesinsteadofthedskdevices!

% dd if=/dev/rdsk/c1t0d0s5 of=/metadb_c1t0d0s5 bs=512 count=2084 % dd if=/dev/rdsk/c1t1d0s5 of=/metadb_c1t1d0s5 bs=512 count=2084

1 2 3 4 5 6 7 A I

Thiscreatestwofilesontherootpartition,namedaftertheMetaDBslice theycontain:metadb_c1t0d0s5andmetadb_c1t1d0s5. 3.) Back up everything on tape.Thisincludesallpartitions,especiallythe rootpartition.Youcanusethescript/backup.shprovidedinthesectionBackingupSeveralFileSystemsonaSingleTapeonpage 242in ordertobackupallpartitionsonasingletape.Makesurethatyousave thepartitioninginformationatthestartingpositionofanewtape.The provided/backup.shshellscriptdoesthisautomatically. 3.1. Bringthesystemdownintosingleusermodeusingthefollowingtwo commands.Thesefirstcleanlyshutdownthesystemwhichyoulater bootinsingleusermore: % shutdown -i0 -g0 -y ok boot -s (shutsdownthesystem) (bootsthesystemintosingleuser mode)

3.2. Startthebackupscript/backup.shandwaituntilitisfinished.

254

Appendix 3.3. Bringthesystembackintonormalmulti-usermodeandresumenormal operations. Notethatthissortofafullbackupdoesnotneedtobeperformedregularlyunlessyouupdatetheoperatingsystemor changethesystem'sconfigurationsinceitisas-sumedthatthe data,especiallystoredontherootpartition,willnotchange signifi-cantlyovertime.

A.7.15 Restoring the Primary Hard Drive

Afterasystemcrashoraharddrivefailuretherootpartition,whichisessential forbootingthesystem,mayhavebeendestroyed.Thissectionexplainstoyou howtorestorethisrootpartitionontheprimaryharddrive. Note:Incaseyouhadtoreplacetheprimary(boot)harddriveby anotheroneyouhavetomakesuretoconfiguretheWorldWide Numbercorrectly.ThesectionA.7.5explainsinmoredetailwhat theWWNisandhowtoconfigurethesystem. Hereisastep-by-stepdescriptiontellingyouhowtorestorethesystemafter acrash,usingthesameharddrive(withouttheneedtoconfigureanew WWN): 1.) BootthesystemfromCDROM.UsetheSunSolarisOSCDROMnamed "Solaris8SoftwareCD1of2"(Version7/01)tobootthesystemintosingleusermode. rsc> console ok boot cdrom -s 2.) Restorethepartitioninginformationfromtape.Makesurethatyouinsert thecorrecttapeforthemachineyouarerestoring!SincethisVTOCdata isstoredatthestartingpositionofthetape,ithastoberewound:
% mt -f /dev/rmt/0cn rewind % cat /dev/rmt/0cn | fmthard -s - /dev/rdsk/c1t0d0s2

1 2 3 4 5 6 7 A I

Noticetheuseofthefmthardcommandwhichisdescribedin moredetailinthepreviouschapter. Theoutputoffmthardshouldbesomethinglikethefollowing:

fmthard: New volume table of contents now in place.

255

Appendix
fmthard can not write a disk label on an unlabeled disk. Use format in advance for this purpose.

NewharddrivescomingdirectlyfromSunarealreadylabeled. 3.) Createnewfilesystems.Thefollowingcommandscreatefilesystemson slicesfortheroot,tmp,andhomefilesystems: % newfs /dev/rdsk/c1t0d0s0 % newfs /dev/rdsk/c1t0d0s6 % newfs /dev/rdsk/c1t0d0s7 4.) Mountthenewfilesystemsandrestoretheircontentsoneafterthe other.Thiscanbedonebythefollowingsequenceofcommands:
% % % % % % mount /dev/dsk/c1t0d0s0 /a cd /a ufsrestore rvf /dev/rmt/0cn(use "rf" for no output) rm restoresymtable cd / umount /a

1 2 3 4 5 6 7 A I

% fsck /dev/rdsk/c1t0d0s0 Repeatthesestepsforslicec1t0d0s7whichholdsthe/homeslice.As mentionedinthepreviouschapterthereisnoneedtorestorethe contentsofthe/tmpslice. 5.) RestoretheBootBlock.Thebootblockresidesontherootpartitionof theprimaryharddriveandisrequiredforproperbootingofthesystem. Enterthefollowingcommandstorestoreit: % cd /usr/platform/`uname -i`/lib/fs/ufs % installboot bootblk /dev/rdsk/c1t0d0s0 6.) RestoretheMetaDBreplicas.IfyouareusingRAIDmirrordevicesyou needtorestoretheMetaDB.Thisdatahasbeenpreviouslystoredonthe root(/)partitioninafile(metadb_c1t0d0s5)thathasbeenrestoredin thepreviousstep.Usethefollowingsequenceofcommandstodorestore theMetaDBreplicas:
% mount /dev/dsk/c1t0d0s0 /a

256

Appendix
% dd if=/a/metadb_c1t0d0s5 of=/dev/rdsk/c1t0d0s5 bs=512

% umount /a 7.) IfyouareusingaRAIDmirror,continuewithsection2.4.Otherwiseyou canrebootyoursystemandassignproperaccessrightstothe/tmppartition: % reboot % chmod 777 /tmp

A.7.16 Restoring the Mirror

Restoringthemirrordevice(s)involvessomeSolsticeDiskSuitecommands. Thesecommands,andthesequenceofthecommandsisdescribedinthissection. 1.) Restorethepartitioninginformationonthemirrordrive.Thiscanbedone usingthepartitioninginformationoftheprimaryharddrivesinceboth drivesaremeanttoholdtheexactsamedata:
% prtvtoc /dev/rdsk/c1t0d0s2| fmthard -s - /dev/rdsk/c1t1d0s2

1 2 3 4 5 6 7 A I

2.) Removethemirrordrivefromthesystem.Thisisnecessarytoreinitiate thesynchronizationofthemirror. % shutdown -i0 -g0 -y ok set auto-boot? false ok power-off (shutsdownthesystem)

Nowyoucansafelyremovethemirrordiskfromthesystem. 3.) Poweronthesystem(withoutthemirrordisk)andbootintosingleuser mode.Afterbooting,enterthemaintenancemode. ok boot -s Thesystemwillpromptyouwiththefollowing:Insufficientmetadevice databasereplicaslocatedandyoumustentermaintenancemode.In maintenancemodeyoushouldlookforunknownreplicas,indicatedby auinthefollowinglist(example):

257

Appendix

% metadb flags a m p a M M p p p lu l first blk 16 1050 unknown unknown block count 1034 1034 unknown unknown /dev/dsk/c1t0d0s5 /dev/dsk/c1t0d0s5 /dev/dsk/c1t1d0s5 /dev/dsk/c1t1dos5

4.) Removetheunknowndatabasereplicas.Youcansafelyignorewarning messageslikewiq22:/etc/lvm/mddb.cf.new:Read-onlyfilesystem.Issue thefollowingcommandtoremovethedatabasereplicas: % metadb -d /dev/dsk/c1t1d0s5 5.) Performacompleterebootofthesystem. Attention!Donotleavethemaintenancemodebylogging out! % shutdown -i6 -g0 -y (or % reboot)

1 2 3 4 5 6 7 A I

6.) SavetheMetaDBstatusfile.Youmayneedthisfilelateron. % metastat >/metastat.error Thiscreatesafilenamedmetastat.erroronyourrootpartition. 7.) Locateanysubmirrorsusingtheremoveddiskanddetachthem.Seethe metastatoutputandlookforlinessimilartothefollowingexample: d8: Mirror Submirror 0: d6 State Okay : Submirror 1: d7 State: Needs maintenance

Youshouldissueametadetachcommandforeachsubmirrorthat indicatesaproblem(Needsmaintenance).Whiledoingsomakesureto writedownallthemetadetachcommandsyouentered.Thesyntaxfor

258

Appendix themetadetachcommandisasfollows:metadetach <mirror> <submirror>. Example: % metadetach -f d11 d0 Theoutputshouldbe:d11:submirrord0isdetached % metadetach -f d8 d7 % metadetach -f d9 d5 % metadetach -f d10 d3 8.) Haltthesystemto(re-)attachthemirrordisk. % shutdown -i5 -g0 -y Afterthesystemhasbeenhalted(re-)attachthemirrordiskandbootintosingleusermode: ok boot -s 9.) AddtworeplicasoftheMetaDBtothebrokenslice.Forexample,ifslice c1t1d0s5isaffected,enterthefollowingcommandtodoso: % metadb -a -c 2 c1t1d0s5 10.)Reattachthesubmirrors.Youhavetouseexactlythesamemirrors(numbers)youusedduringthedetachmentinstep7. % metattach d11 d0 Theoutputshouldbe:d11:submirrord0isattached % metattach d8 d7 % metattach d9 d5 % metattach d10 d3 Usethemetastatcommandafterwardstomakesurethattheresyncing ofthemirrorisinprogress. 11.)Youcanentermultiusermode.Useinit2whileresyncingofthemirror isinprogress. 12.)Enableautoboot.Usethefollowingcommandstoenableauto-booting again: % eeprom "auto-boot?=true"

1 2 3 4 5 6 7 A I

259

Appendix % eject /cdrom 13.)Finally,settheappropriaterightsto/tmp. % chmod 777 /tmp

A.7.17 Restoring the System in General

Thissectionassumesthattherootpartitionofthesystemisnotaffectedbya crashandyouthereforedonotneedtorestoreit.Herearethestepsrequired torestorethesystem: 1.) Bootthesystemfromharddrive.Sincetherootpartitionisnotdefective, youcanuseittobootthesysteminsteadofusingaCDROM. 2.) Restoreanycorruptedpartitionsfromtape.Followthestepsintheprevioussection(s)torestoreanycorruptedpartitionsfromtapeandskipthe stepsrequiredtorestoretherootpartition,e.g.thecreationoftheboot block,etc. Usethemtcommandtofastforwardthetapetothecorrectposition(s) ofthebackups.Forexample,ifyouwanttorestorethe/homepartition locatedonslicec1t0d0s7-storedatthe3rdpositiononthebackuptape bythebackupscript-youissuethefollowingcommand: % mt -f /dev/rmt/0cn asf 2 Thenfollowtheremainingstepslistedintheprevioussection(s)torestore thepartitionusingufsrestore.

1 2 3 4 5 6 7 A I

A.8

How to Shut Down or Reboot a System Properly

1.) Attachtothemachinewithtelnetorrsc a.telnet: telnet<hostname> EnterusernameandpasswordforwIQuser Getroot: wiq>su -

260

Appendix b.rsc: telnet<hostname-rsc> Enterusernameandpasswordforrscuser Starttheconsole: rsc> console Loginasroot

2.) Shutdownorreboot: a.Shutdownandturnoffpowerautomatically: % shutdown -i5 -g0 -y b.Reboot: % reboot or % shutdown -i6 -g0 -y c.Shutdownintobootprompt(youwillonlyneedthisforbackup/ restore): % shutdown -i0 -g0 -y Inanycase,youshouldgivethemachineabout2minutestoshut down!Ifyouusersc,youcanwatchtheconsolemessagesandsee whentheshutdownorreboothasfinished.

1 2 3 4 5 6 7 A I

A.9

Apache Web Server

ThewIQ1.3isdeliveredwiththeapacheWebserverversion1.3.14andPHP version4.0.4pl1. TheWebserverislocatedin$ORGAROOT/apacheandthePHPin$ORGAROOT/php.IftheWebserverisstartedmanually,itmusthavethesame$ORGADATAand$ORGAROOTenvironmentsaswIQd!

261

Appendix Apachelogfilescanbefoundin$ORGAROOT/apache/logs. Important Configurations: MaxRequestsPerChild 200 # needed on Solaris to avoid mem leaks LoadModule php4_module libexec/libphp4.so AddModule mod_php4.c AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps

A.10 Regular Expression

Indatabasetables,youwillfind...;REwhichstandsforRegularexpression. Aregularexpressioncancontainthefollowinginformation: . .* ^ $ [n-m] Example: ^013.* ^018[1-3]$ ^019[2-4]5$ numbersofanylength,startingwith013 correspondsto0181,0182and0183 correspondsto01925,01935and01945 standsforanycharacter standsforanynumberofcharacter muststartwiththefollowingcharacter indicatestheend specificationofrange

1 2 3 4 5 6 7 A I

A.11 Setting of $RANDFILE

Theenvironmentvariable$RANDFILEmustbesetto $ORGAROOT/run/bin/wIQ

262

Appendix forHTTPSaccess.

A.12 ORGA Alarm Definitions

A.12.1 ORGA SNMP MIB Definitions A.12.1.1 OLS-CommonAlarmTrap.mib
e COMPANY-ORGA-ALARM-TRAP-MIB DEFINITIONS ::= BEGIN

-- =============================================================== -Copyright (C) ORGA Kartensysteme GmbH 2000

1 2 3 4 5 6 7 A I

-- =============================================================== -- This MIB Module defines common alarm traps More detailed -- description of the variables and tables is provided in other -- related documentation. --- Format: -- version -- 1.0 --- =============================================================== -- Author -- Version : Michael Brandenburg : 1.0 : First version. SNMP v1 MIB

-- Last Update : 15-11-2000 --================================================================

IMPORTS caSeverity, caEventType, caOriginatingEquipment, caEventTime, caAdditionalData, caEventNumber, caEventText, caNotificationID, caTrapId FROM COMPANY-ORGA-ALARM-DEFINITIONS-MIB

263

Appendix
enterprises FROM RFC1155-SMI TRAP-TYPE FROM RFC-1215;

--============================================================= -- Definitions --=============================================================

-- OID for ORGA company_ORGA OBJECT IDENTIFIER ::= {enterprises 3688}

1 2 3 4 5 6 7 A I

-- OIDs sorted by ORGA products companyProducts OBJECT IDENTIFIER ::= {company_ORGA 1}

-- OID for Orga Logging System (OLS) product_OLS OBJECT IDENTIFIER ::= {companyProducts 1}

-- starting point for the "common alarm trap" MIB alarmTraps OBJECT IDENTIFIER ::= {product_OLS 1}

--============================================================= -- Common trap definition for alarm events --=============================================================

caAlarmEvent TRAP-TYPE ENTERPRISE -- STATUS VARIABLES alarmTraps

-- Severity : warning,minor,major or critical

mandatory {caSeverity, caEventType, caOriginatingEquipment, caEventTime, caAdditionalData, caEventNumber,

caEventText, caNotificationID, caTrapId}

264

Appendix

DESCRIPTION "This is common alarm event trap." ::= 1

--============================================================= -- Common trap definition for cancel events --=============================================================

caCancelEvent TRAP-TYPE ENTERPRISE -- STATUS VARIABLES alarmTraps mandatory

-- Severity : cancel

{caSeverity, caEventType, caOriginatingEquipment, caEventTime, caAdditionalData, caEventNumber,

1 2 3 4 5 6 7 A I

caEventText, caNotificationID, caTrapId} DESCRIPTION "This is common cancel event trap." ::= 2

END

A.12.1.2 OLS-CommonAlarmDefinitions.mib
e COMPANY-ORGA-ALARM-DEFINITIONS-MIB DEFINITIONS ::= BEGIN

-- =============================================================== -Copyright (C) ORGA Kartensysteme GmbH 2000

-- =============================================================== -- This MIB Module defines common alarm definitions. The -- alarm traps are defined in other MIB Module. More detailed -- description of the variables and tables is provided in other -- related documentation. --

265

Appendix
-- Format: --- =============================================================== -- Author -- Version : Michael Brandenburg : 1.2 SNMP v1 MIB

-- Last Update : 31-07-2002

--================================================================

IMPORTS enterprises FROM RFC1155-SMI DisplayString FROM RFC1213-MIB OBJECT-TYPE FROM RFC-1212;

1 2 3 4 5 6
OBJECT IDENTIFIER ::= {enterprises 3688}

--============================================================= -- Definitions --=============================================================

-- OID for ORGA company_ORGA

-- OIDs sorted by ORGA products companyProducts OBJECT IDENTIFIER ::= {company_ORGA 1}

7 A I

-- OID for Orga Logging System (OLS) product_OLS OBJECT IDENTIFIER ::= {companyProducts 1}

--============================================================= -- OID registration subtrees for this MIB module --=============================================================

266

Appendix
-- starting point for the "common alarm trap" MIB alarmTraps OBJECT IDENTIFIER ::= {product_OLS 1}

-- starting point for the "common alarm definitions" MIB ca caVars OBJECT IDENTIFIER ::= {alarmTraps 2} -- common alarms OBJECT IDENTIFIER ::= {ca 1} -- common alarms variables

--============================================================= -- Payload of the ORGA Common Alarm Traps -- ca == Common Alarm --=============================================================

1 2 3 4 5 6 7 A I

caSeverity OBJECT-TYPE SYNTAX ACCESS STATUS INTEGER read-only mandatory

DESCRIPTION "Severity of alarm trap: indeterminate(0), critical(1), major(2), minor(3), warning(4), clear(5), informational(6)" ::= {caVars 1}

caEventType OBJECT-TYPE SYNTAX ACCESS STATUS INTEGER (0..5) read-only mandatory

DESCRIPTION "The event type : unknown(0),communication(1),environmental(2), equipment(3),processing(4),quality of service(5)" ::= {caVars 2}

caOriginatingEquipment SYNTAX

OBJECT-TYPE

DisplayString (SIZE (0..100))

267

Appendix
ACCESS STATUS read-only mandatory

DESCRIPTION "Object identifier is used to distinguish the process sending the alarm." ::= {caVars 3}

caEventTime SYNTAX ACCESS STATUS

OBJECT-TYPE DisplayString (SIZE (0..15)) read-only mandatory

DESCRIPTION "This variable contains date and time in format JJJJMMDDHHMMSS" ::= {caVars 4}

1 2 3 4 5 6 7 A I

caAdditionalData OBJECT-TYPE SYNTAX ACCESS STATUS OCTET STRING(SIZE (0..64)) read-only mandatory

DESCRIPTION "Additional information" ::= {caVars 5}

caEventNumber OBJECT-TYPE SYNTAX ACCESS STATUS INTEGER (0..9999) read-only mandatory

DESCRIPTION "Event number tells the specific reason of the problem. The value of this variable also uniquely identifies an alarm." ::= {caVars 6}

268

Appendix

caEventText SYNTAX ACCESS STATUS

OBJECT-TYPE DisplayString (SIZE (0..64)) read-only mandatory

DESCRIPTION "Event text of the trap." ::= {caVars 7}

caNotificationID OBJECT-TYPE SYNTAX ACCESS STATUS INTEGER (0..'7fffffff'h) read-only mandatory

1 2 3 4 5 6 7 A I

DESCRIPTION "This variable is used as a unique alarm identifier." ::= {caVars 8}

caTrapId OBJECT-TYPE SYNTAX ACCESS STATUS INTEGER (0..'7fffffff'h) read-only mandatory

DESCRIPTION "caTrapId will be incremented by one in each trap sent by NE to a NMS. When caTrapId achieves the maximum value, the variable will wrap back to value 1 when sending the next trap. caTrapId is used by NMS to detect if traps are lost." ::= {caVars 9}

END

269

Appendix

A.12.2 List Of Event Ids A.12.2.1 Trap Definitions

Thissectionwillsummarizethetrapsdefinedinthismanual: Component Description Waitingfornewconnectionof aclient->raise Socketconnectionwasclosed>raise Anewconnectionhasbeen establishedorwIQisterminating->clear Therouterislisteningona socketforadrivertoconnect-> raise Therouterisconnectedtoa driver,ortherouterisshutting down->clear Therouterisnotconnectedtoa wIQ->raise Therouterisconnectedtoa wIQ,ortherouterisshutting down->clearsthetrapmentionedabove Heartbeatmessage(not cleared),dynamicpartisempty OLS-Name MAIN.INFO.WAITING USSD.I.SOCKETCLOSED USSD.I.NEWCONNECTION

wIQ wIQ wIQ

6196 6253 6255

Event-ID

1 2 3 4 5 6 7 A I

Router

6900

CONFIG.I.LISTENING

Router

6917

CONN.I.CONNECTED

Router Router

6921 6920

CONN.I.NOTCONNECTEDWIQ CONN.I.CONNECTEDWIQ

wIQguard

0000

HEARTBEAT

270

Appendix

Component

wIQguard wIQguard wIQguard wIQguard wIQguard wIQguard

*

6001 6002 6003 6004 6005 6006 6524 7343

WIQGUARD.PROCESSUP WIQGUARD.PROCESSDOWN WIQGUARD.UP WIQGUARD.DOWN WIQGUARD.REMOTEUP WIQGUARD.REMOTEDOWN SC_STREAM.I.LICENSELIMIT ROUTER.INFO.WAITING

wIQguardhasstartedaprocess (e.g.wIQ_a)->clears6002 wIQguardrecognizedprocess stop->raise wIQguardiscomingup-> clears6004 wIQguardishalted->raise wIQguardisstartedinremote mode->raise wIQguardremotemodeisquit>clears6005 License limit reached -> raise Waitingfornewconnection-> raise Anewconnectionhasbeen establishedorprocessisterminating->clear Connectionhasbeenclosed-> raise

Description

OLS-Name

Event-ID

1 2 3 4 5 6 7 A I

wIQ

extUSSDwebservice extUSSD- webservice extUSSD- webservice

7339

ROUTER.INFO.CONNECTED

7341

ROUTER.INFO.CLOSE

271

Appendix

Component

extUSSD- webservice extUSSD- webservice

7260

EXT.STARTUP

Processisstartingup->clear

7259

EXTUSSD.I.SHUTDOWN

Processisexiting->set

Description

OLS-Name

Event-ID

* Traps listed in italic font are disabled by default

1 2 3 4 5 6 7 A I

A.13 Bibliography
GSM 03.40 Title: TechnicalrealizationoftheShortMessageService(GSM03.40)

Identification:ETSITS100901 Version: Date: Publisher: V7.4.0 1998 EuropeanTelecommunicationStandard

GSM 03.38 Title: Alphabetsandlanguage-specificinformation(GSM03.38)

Identification:ETSITS100900 Version: Date: Publisher: V7.2.0 1998 EuropeanTelecommunicationStandard

272

Index

I
Comparison types ...............................40 Configuration ......................................49 Configuration billing Variables ....................................131 Configuration file Variables ......................................67 Configuration tables ....................76, 131 Constraints .........................................34 Conventions ..........................................1 Conversion .........................................12 Conversion URL ...............................126

A
Abbreviation list .................................... 3 Apache Web server ......................... 261 Assignment to group .......................... 46

1 2 3 4 5 6 7 A I

B
Backup ............................................. 237 Billing ....................................... 119, 123 Configuration variables .............. 131 IN billing ............................... 77, 120 Modules ..................................... 121 Postpaid ............................ 120, 129 Prepaid .............................. 120, 129 Types ......................................... 129 Billing mechanism ............................ 120 Browsing ............................................ 25

D
Data Coding Scheme .......................188 Database Incore ...........................................37 Subscriber ....................................37 Tools .............................................41 Database defaults ...............................97 Databases ..........................................37 Default table .......................................97 Direct parameter passing ...................34 Direct SMS .......................................207

C
Call wIQ service ........................... 21, 30 Commandline interfaces .................... 41 Commandline options ........................ 64

273

Index

E
End of Session ................................... 29 Enhanced SMS ................................ 183 Environment variables ....................... 65 ESMS ............................................... 183 Examples Binary SMS ............................... 204 Picture SMS .............................. 205 Ringtone ESMS ......................... 201 Text ESMS ................................. 203 External requirements ........................ 11

262

I
IN billing ..............................77, 120, 123 configuration ..............................100 Inclusion table ...............................33, 84 Incore Database .................................37 Information subscriber ......................125 Input Character set ...............................26 Formats ........................................33 Interfaces .....................................18 Install tape drive ...............................239 Interface_wIQ.cfg ...............................65 Interfaces ............................................37 Commandline ...............................41 PHP ..............................................37 Subscribers input ........................18

F
First login ........................................... 18 Formats HTML input formats ..................... 33

1 2 3 4 5 6 7 A I

H
Handling signals ................................. 65 Hotkey Functionality .......................... 25, 28 Functions ....................................... 7 Preinput ....................................... 23 Hotkeys ............................................ 102 HotKeySet table ............................... 102 HotKeySet.cfg .................................. 102 HTML Input formats ............................... 33 Tags ............................................. 12 HTTP header ..................................... 86 HTTP interface extension ................ 199 HTTPS environment variables .... 33, 90,

L
Language extension .........................189 License file ........................................100 Long ESMS ......................................185 Long SMS .........................................184

M
MAP ....................................................12 Mapping table .....................................78 Modules (Billing) ...............................121

274

Index

N
Notification.cfg ................................. 135

O
ORGA NSG driver ............................ 207

P
Parameter passing ............................. 34 PHP-Interfaces ................................... 37 Postpaid billing ......................... 120, 129 Preinput processing ........................... 28 Prepaid billing .......................... 120, 129 Price tag ........................................... 121 Protocol identifier ............................. 187 Provider list ...................................... 121 ProviderMap.cfg ............................... 121

R
Rapid access to URL ......................... 23 Reboot system ................................. 260 Regular ESMS ................................. 184 Regular expression .......................... 262 Requirements, external ...................... 11 Restore ............................................ 237 Ringtone SMS .................................. 184

S
Secure HTTP ................................... 121 Self-registration .................................. 18

Service Commands ...................................21 Start a ~ ........................................21 Service Number ..................................22 Session Browsing ......................................25 End ...............................................29 Shutdown system .............................260 Signal handling ...................................65 SMS ..............................................30, 77 Supported types ...........................32 SMS Conversion .................................12 SMS request .......................................96 SMS to Service Mapping table ...........90 SMS2Service.cfg* ...............................90 SNMP ...............................................211 SNMP support ..................................218 Special characters ..............................34 Start wIQ .............................................49 Start wIQ service ................................21 Stop wIQ .............................................49 SUBMIT-TPDU .................................185 Subscriber Assignment to group ....................46 Direct parameter passing .............34 First login .....................................18 Identity to URLs ...........................33 IMSI ..............................................33 Information .................................125 Input interface ..............................18 MSISDN .......................................33 Self-registration ............................18 Subscriber database ...........................37 System description ...............................7 System overview ..................................7 System reboot ..................................260 System shutdown .............................260

1 2 3 4 5 6 7 A I

275

Index

T
Tag attribute missing ........................ 198 Tag attribute parsing ........................ 198 Tag processing rules ........................ 198 Tags ................................................... 12 dcs ..................................... 189, 191 msginddcs ......................... 189, 192 msgindudh ......................... 189, 196 pid ...................................... 189, 194 smshead ............................ 189, 190 udhie .................................. 189, 197 User-specific .............................. 196 vp ....................................... 189, 194 Tape drive ........................................ 239 tedriver process ............................... 207 TP-DCS ............................................ 188 TPDU parameters ............................ 184 TP-PID ............................................. 187 TP-VP .............................................. 188

USSD to URL Mapping Configuration table .......................47 Group ...........................................43 Group-specific mapping ...............46 table .............................................78

V
Valid URL ....................................84, 124 Validity Period ...................................188 Validity rules .....................................199 Variables Configuration file ..........................67 Environment .................................65 HTTP header ...............................86 Inclusion table ........................33, 84

1 2 3 4 5 6 7 A I

W
wIQ .......................................................7 Call a service .........................21, 30 Internal .........................................64 Process ........................................11 wIQ.cfg ...............................................67 wIQd.cfg .............................................51 wIQPush ...........................................199

U
URL Access ......................................... 22 Conversion ................................ 126 Rapid access ............................... 23 Valid ~ .................................. 84, 124 Using SMS ......................................... 30 Using USSD ....................................... 18 USSD ................................................. 18 USSD conversion ............................... 12

276