The BlackBerry Mobile Data System : Configuring MDS

To modify the MDS configuration, you make changes to a text file called rimpublic.properties installed with MDS. Settings can be modified using the administrator tools RIM provides, or it can be manually edited. Ask an administrator for help making any changes.

To edit the file, look for it in the config folder underneath the folder where MDS is installed. The location of this folder varies, depending on whether you’re looking at MDS running on a server or an instance of MDS installed on your development workstation. Figure 1 shows the location of the folder when the Email and MDS simulator package was installed. If you are working with MDS running on a server, the BES/MDS installation places the config folder in C:\Program Files\Research In Motion\BlackBerry Enterprise Server\MDS\servers\[BlackBerry Enterprise Server Name]\Config, where [BlackBerry Enterprise Server Name] refers to the BES name.

Figure 1. MDS config folder

The rimpublic.properties file is a simple text file that can be modified using any standard text editor. Be sure that your text editor doesn’t add a txt to the filename when writing your changes back out to the file. A sample rimpublic.properties is shown here for your reference. In the file, section titles are delimited by square brackets ([ and ]) and comment lines begin with the pound (#) sign:

[Logging]
Logging.level=4
Logging.console.log.level=4

[WebServer]
WebServer.Tomcat.transcoding=false
WebServer.listen.host=localhost
WebServer.listen.port=8080
WebServer.listen.sslport=8443
WebServer.servlet.push.port=81
WebServer.servlet.push.host=localhost
WebServer.servlet.sb.ssl=false
WebServer.servlet.sb.authentication=false

[IPPP]
IPPP.push.listen.tcp.port=81
IPPP.connection.MaxNumberOfKBytesToSend=256
IPPP.queue.flowcontrol.window.size=-1
IPPP.queue.flowcontrol.timeout=600000
IPPP.logging=true

[UDP]
UDP.receive.port=19781
UDP.send.default=19780
UDP.send.host=localhost
UDP.logging=false

[HTTP HANDLER]
application.handler.http.logging=true
application.handler.http.logging.verbose=true
application.handler.http.CookieSupport=true
application.handler.http.AuthenticationSupport=true
application.handler.http.AuthenticationTimeout=3600000
application.handler.http.device.connection.timeout=120000
application.handler.http.server.connection.timeout=120000

[HTTPS HANDLER]
application.handler.https.allowUntrustedServer=false

[TLS HANDLER]
application.handler.tls.allowUntrustedServer=false
application.handler.tls.logging=true
[OCSP HANDLER]
application.handler.ocsp.StatusProviders=
net.rim.protocol.iplayer.connection.handler.device.ocsp.
OCSPProvider
application.handler.StatusProviders.OCSP.PrimaryResponderRank=
Default
application.handler.StatusProviders.OCSP.Responder.Default=
http://somemachine.rim.net/ocsp
application.handler.StatusProviders.OCSP.UseDeviceResponders
=yes
application.handler.StatusProviders.OCSP.UseCertResponders
=yes
application.handler.ocsp.DebugLogging=no

[LDAP HANDLER]
application.handler.ldap.DEFAULT_SERVER=dhobbs-wnt
application.handler.ldap.DEFAULT_PORT=389
application.handler.ldap.DEFAULT_QUERY=ou=people, o=rim.net
application.handler.ldap.DEFAULT_LIMIT=20
application.handler.ldap.COMPRESSION=true
application.handler.ldap.logging =false

[Database]
MDSName=MDS

[Simulator]
#[CDK_MODIFICATIONS for Running Multiple Simulators]
#Each simulator instance must have a unique IPPP port assignment
#ie. Simulator fledge.exe command lines must have:
#      /ignore-data-port-conflicts /app-param=IPPPSourcePort:
<port>
Simulator.2100000a=MDS,[email protected]
Simulator.2100000b=MDS,[email protected]
Simulator.2100000c=MDS,[email protected]
Simulator.2100000d=MDS,[email protected]
Simulator.2100000e=MDS,[email protected]
Simulator.2100000f=MDS,[email protected]

[ACL]
ACL.Authorization.Datastore=net.rim.shared.service.
authorization.JDBCAuthorizationDatastore

[Java Security Property]
networkaddress.cache.ttl=0

[Email]
#Email.mode=standalone
#Email.mode=connect
Email.mode=none
#Common settings for both standalone and connect mode
Email.personal=Test User
[email protected]
Email.deviceId=2100000a

#Connect mode settings
Email.pop3Server=popServer
Email.smtpServer=smtpServer
Email.smtpPort=25
Email.pop3Port=110
Email.userId=popUser
Email.password=popPassword
Email.pollInterval=30

[SRPH]
SRPH.AuthenticationString=lsfjdnflownenlgfnp
SRPH.UID=S 00005
SRPH.listen.port=3200

#FS.sourceDir=mobitex_simulator
#FSLayer.logging=true
#push.application.reliable.ports=100

					  

1. Logging HTTP Requests

When debugging a web application or a JME application that uses HTTP, you can increase the amount of information MDS logs as it processes the requests from the device application. This allows the application developer to see everything that transpires as MDS receives requests, connects to the server to retrieve the data, and optimizes the results before sending them to the device. This enhanced logging is enabled by enabling HTTP logging and setting verbose mode.

To enable HTTP verbose logging, locate the [HTTP HANDLER] section in the rimpublic.properties file and add the following two lines to the section:

application.handler.http.logging=true
application.handler.http.logging.verbose=true

When you enable application.handler.http.logging, HTTP transactions appear in the MDS logs. When you enable application.handler.http.logging.verbose, MDS logs the contents of web pages accessed by the BlackBerry Browser. This generates a large amount of data, so be sure to disable this setting when it is no longer needed.

2. Adding PIN or Email to the HTTP Request Headers

There are times when a developer needs to validate the identity of a mobile user without prompting them to provide a username and password. You can do this by configuring MDS to include a BlackBerry smartphone PIN and/or email address in the HTTP header for all requests originating from MDS. When your application receives the request, it can perform a reverse lookup against the SQL tables maintained by the BES or against LDAP, Active Directory, or some other up-to-date source of user information. Although this is not a secure option, because all requests from a BlackBerry device activated against a BES and MDS look like they come from inside the firewall, it might be acceptable for some situations.

To enable these options, locate the [HTTP HANDLER] section of the rimpublic.properties file and add the appropriate value listed here:

• application.handler.http.header=pin. Adds the header value Rim-device-id: <PIN> to the HTTP header for the request

• application.handler.http.header=email. Adds the header value Rim-device-email: <user_name>@acme.com to the HTTP header for the request

• application.handler.http.header=email,pin. Adds both Rim-device-id: <PIN> and Rim-device-email: <user_name>@acme.com to the HTTP header for the request

You can also restrict the addition of these header values to specific domains by adding the following to the [HTTP HANDLER] section of the rimpublic.properties file:

application.handler.http.header.domain=

This option allows you to keep the PIN and email address private except for the domain(s) listed.

When you add this line, you must include the domains for which you want the header values included. To add header values for only the somecompany.com domain, the rimpublic.properties line looks like this:

application.handler.http.header.domain= somecompany\.com;.+\.
somecompany\.com

The entry somecompany\.com covers the root domain while .+\.somecompany \.com covers any subdomain name that ends with somecompany.com (i.e. server1.somecompany.com).

To add additional domains, append the domain designators to the end of the line by using the same format shown for each additional domain.

Note