BESUserAdminClient - User and Device Management.

Read the earlier blog http://insidebes.blogspot.com/2010/05/besuseradminclient-key-to-automation.html to get into the basics of this tool.

BESUserAdminClient ( BlackBerry Enterprise Server User Administration  Tool ) can be a great tool for the BlackBerry Administrator to automate or script their daily tasks, but for the difficult and incoherent command line options and switches. Starting from the (-?) help switches to the almost 100 page document, nothing is logical and harmonious. 

Anyways, here is my humble effort to organize the power of BESUserAdminClient  into specific group of tasks. In today's blog I will only concentrate on the tasks that an administrator performs to do user and device management. This tool also has limited support to perform these operations on multiple users, but let's keep it for another blog.

First things first. Let's start by making sure that BESUserAdminClient is up and working.
BESUserAdminClient.exe -n my_BASServer -username my_BESadmin -password my_password -ad_auth -domain Galaxy.Lab -status

if you are using BAS authentication use it as below

BESUserAdminClient.exe -n my_BASServer -username my_BESadmin -password my_password -bas_auth -status

User provisioning and de-provisioning.

Let us go through some of the user provisioning and removal process using this tool.

• Adding a user User1@galaxy.lab to the BES Server.BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u user1@galaxy.lab -b my_Server_instance -add 
  Note: -b parameter is the name of the BlackBerry Enterprise Server instance. If you get an error message "Cannot find Dispatcher Instance:" then surely the issue is with the -b parameter. For more information read the following blog http://insidebes.blogspot.com/2010/06/besuseradminclient-cannot-find.html
  
• Add a user that sets a random password for Enterprise Activation and emails it to the user.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -add -wrandom
  You can also use -w password -wt 48 to set a specific password  and expiration hime in hours
• Add a user and add it to a group as well as an IT Policy.BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -group grp1 -it_policy "new IT Policy" 
  
• Delete a user.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -delete
  You can also use -force to delete a user even if user mailbox is not found.

User maintenance tasks.

Under this section I will try to introduce some basic administrative tasks performed on a BES user, that could also be accomplished with this too.

• Find a user
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -find
• Move a user
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -move -b my_Source_Server_instance -t my_target_Server_instance
  To find the instance name of source and target server follow this link 

• Resend Service Book.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -resend_service_book
• Set Redirection on a specific folder.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -set_folder_redirection -foldername my_Folder -er
• Enable redirection.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -change -er
  use -dr for disable

• Resend Service Book.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -resend_service_book
• Set Redirection on a specific folder.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -set_folder_redirection -foldername my_Folder -er
• Enable redirection.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -change -er
  use -dr for disable
• Assign Static Agent 299 to the user
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -assign_static_mailbox_agent  299
  
  You can also use -clear_static_mailbox_agent to remove the user from static agent.
• Delete pending messages
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -purge_pending_message
• Adding the user to a group named grp1
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -change -group grp1
  using -Cgroup deletes the user from the group
• List the groups in the BlackBerry domain
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -list -groups
• List all the folders on the user's mailbox and their redirection state.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u user1@galaxy.lab -folders  
• List the Enterprise Activation Status of the user.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u User1@galaxy.lab -eastatus
  you can also use -from and -to sub parameter to filter the result based on date.

Device management tasks.

• Set Password "my_password" on the device for user User1@galaxy.labBESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -u user1@galaxy.lab -b my_Server_instance -set password my_password
  
• Set the owner info on the device.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -set_owner_info -info "InsideBES Administrator"
  You can also use -infofile file.txt where file.txt has the user information.
• Kill the device - Delete all the data on the handheld.BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -add -u User1@galaxy.lab -kill_handheld 
  
• Send an Email or PIN to the device.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u user1@galaxy.lab -send_email -subject "Message from InsideBES Admin" -body "Welcome to my blog"
  You can also use -send_PIN. Very helpful when email infrastructure is having issues. 
• List applications on device.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -handheld_info -apps
  This is a powerful command that gets the details of all the applications installed on the device.
  You can also use -appname and -appsfull. Refer to RIM documentation for more detail.
• Retrieving the device statistics.
  BESUserAdminClient.exe -n my_BASServer -username admin -password my_password -ad_auth -domain galaxy.lab -b my_Server_instance -u User1@galaxy.lab -handheld_info -hhstats

I have personally used all of these commands sucessfully, however there is always a possibility of a human error. If so please leave your thoughts in the comment. I will confimr and update this document. 

In the next blog I will try to organize my thoughts on Server Management and bulk management.

Looking forward for your comments.

BESUserAdminClient - "Cannot find Dispatcher Instance:"

BESUserAdminClient requires -b parameter with some of its switches. As per the document -b is the name of the BlackBerry Server Instance that appears in the BlackBerry Administration Service.

There are many ways to find it, that includes BlackBerry Administration Service, BES SQL Server, Registry and the BESUserAdminClient itself. 

If you get an error message "Cannot find Dispatcher Instance:" when using BESUserAdminClient,then surely the issue is with the -b parameter.

How to get the Dispatcher Instance from BlackBerry Administration Service

Under the section Servers and Computers -> Click BlackBerry Solution topology -> Click BlackBerry Domain -> Click Component View -> Click BlackBerry Enterprise Server . On the right side of the screen, Click on View component list. On the Components Page note the Name under BlackBerry Enterprise Server Section. You can use the Name as the Dispatcher Instance name for the -b parameter used in the BESUserAdminClient.

Hope this helps. Enjoy the automation.

BlackBerry Administration Service Session Timeout.

The new web based BlackBerry Administration Service time-out does become annoying at times. And here is the way to increase the session time-out.
Login to the BAS Server as an administrator, and browse to the following directory - 

C:\Program Files\Research In Motion\BlackBerry Enterprise Server\BAS\jboss\ejb\server\default\deploy\jboss-web.deployer\conf


Open Web.XML file in Notepad and search for Session-timeout. Change the default value to the value (in red) of your choice.

Save the file. Restart BlackBerry Administration Service - Application Server. And enjoy.

P.S - The BAS Server version was 5.0.1 running on Windows 2008 SP1 (32 Bit). I had issues saving the Web.XML file even though the BESAdmin account is a local administrator. So I ran "cmd" as an administrator, navigated to the desired folder and typed "notepad Web.XML". I changed the value to 600 minutes i.e 10 hours. My first test after 9 hours was successful. I am sure there is more to it. If time permits I will explore further.

If you encounter any issues, or have an update, please feel free to comment.
Thanks
-InsideAdministrator


P.S - This may be of great benefit in a lab environment. However, check your corporate policy before making these sort of changes.

How to find the MAC address of a BlackBerry device

To find the MAC address of a BlackBerry device.
- Click Options.
- Click Status.
- MAC address is displayed here.


Note - this option is available only for WIFI enabled devices.

Impact of BlackBerry Enterprise Server on Exchange.

RIM has published a new performance benchmarking guide  that should help remove the misconception about the BES's impact on performance of Exchange. But before I deal with the numbers, let me go through some historical facts on Exchange.

Background.
Few years back during Exchange 2003, an average Exchange user would generate 0.5 IOPS. There were few large clients I worked that had an average IOPS of about 1.0. During this time period, it was a common assumption to profile a BES user to be 3 to 5 times a normal outlook user. The number was cooked and mashed up by RIM's old performance benchmark guide and chatter in the BESAdmin community. I am sure SAN vendors just loved this multiplying factor and adapted their marketing materials to sell larger systems. Personally, I cannot confirm the IOPS generated by BES during Exchange 2003 days, but I do remember seeing Exchange Server drives churning heavily after every BES restarts and every few minutes (probably rescans). This made designing of Exchange Systems really complex taking into account the IOPS that would be generated for each exchange user. Adding to it were factors like Mailbox size and the number of items in the most common folders like Inbox. SAN was becoming the norm to host Exchange Server databases, mainly to handle the increased IOPS.
With the release of Exchange 2007, Microsoft was successfully able to tweak the Jet Database schema and along with other technology factors like 64 bit OS, increased RAM, increased page size from 4k to 32K helped reduce the IOPS by 70%. In Exchange 2010 it was further reduced further by 70%. This means the IOPS has reduced to 90% in Exchange 2010 as compared to Exchange 2003.
Let me illustrate it by giving an example of an organization with 1000 Exchange and BlackBerry Users. 



Users    Avg                 IOPS/User Total IOPS for   Exchange Total IOPS with BES Users



EX2003  1000   0.5                     500                                2500


EX2007  1000   0.15                   150                                750


EX2010  1000   0.045                 45                                  225


As shown in above table, it would have taken a about 2500 IOPS disk system to support 1000 users on Exchange 2003 Server. While today it would require only 225 IOPS on Exchange 2010 Server. A reduction of 90% just due to Exchange 2010.



RIM's new magical number for BES impact.
As per the recent performance benchmark guide from RIM, the new magical number is equal to the load generated by an outlook client. This means an average user with with BES on Exchange would generate .045X2 = .09 IOPS. For 1000 users this equates to only 90 IOPS.
1000 BES Users on Exchange 2003(5X factor)          2500 IOPS
1000 BES Users on Exchange 2010(2X factor)          90 IOPS
This is a huge reduction of IOPS requirement.

I think that the reduction of IOPS due to BES may primarily be due to the architectural changes made in the BES in terms of how the rescan, reconciliation, MAPI property updates etc is performed. But a part of it may also be due to the advances in Exchange 2010 and the amount of memory cache available to it. Another factor that could come into play is the way lab tests are conducted, the way data can be massaged and sweetened etc.

What else could be done to reduce the impact of BES on Exchange.
Some of the possible steps that could reduce impact of BES on Exchange can be 
- Remove all non active users from BES.
- Increase the checkpoint depth on Exchange Server. (Understand it well before doing this)
- Spread the BES users across multiple transactional logs - more storage groups in Exchange 2007 and more databases in Exchange 2010.
- Training users to exit outlook when not in use. This reduces one client load on Exchange Server.
- Reduce the number of items in the Mailbox commonly used folders like Inbox, Sent Items, Calendar etc.
- Avoid unnecessary shutdown and restarting of BES Server or Services. 

BESUserAdminClient - The Key to automation.

A sign of a great System Administrator is his ability to automate the daily tasks. After great success with Powershell, I turned my attention towards BlackBerry Server. In BES 5.0 RIM released API's to automate and script BlackBerry Administrative Tasks. I peeked and poked around the BAS API documentation, and finally said good bye. Though I agree that framework is solid and useful, but as an administrator who has to wear multiple hats, it was too much of an investment in time to save those GUI clicks. Real low return of investment. But for developers and companies developing BlackBerry products, this surely is a framework to look for.

I had read somewhere that the new BlackBerry Enterprise Server User Administration Tool version (BESUserAdminClient) is designed to use BAS API, so I focussed my attention to this tool one more time. Earlier, I had limited success before but the tool was never my favorite. 

Features

For those of you new to this tool, BESUserAdminClient can be used to perform user account operations like find, add, remove, move and change user configurations. It can also be used to perform BlackBerry Enterprise Server administration to gather management and monitoring information. An interesting note in the document mentions that new server options introduced in the later versions of BES will work without any update of BESUserAdminClient. But new client options will be only be available with the latest version of BESUserAdminClient.

Installation
Installation of BlackBerry Enterprise Server User Administration Tool version 5.0 Service pack 1, on Windows 7 machine was a breeze. The one and only prompt was to enter the name of BAS Server. I used the DNS name of the machine itself instead of the BAS Pool name in the DNS, so as to minimize the troubleshooting elements by excluding the BAS pool as well as any SSL certificate issues I may have. The target BlackBerry Server was also 5.0 SP1.

Earlier versions of BESUserAdminClient required a server component (running as service) and a client component. I tried to run this tool against BES 5.0 MR1 with no success.

Results

For instant gratification, I used BESAdmin Account (will all its powers) instead of following the documentation for complex role assignments. The tool also provides an option to store an encrypted set of authentication credentials, but again I used it in the command line itself. The first success after trial and error was when I typed

BESUserAdminClient.exe -n BESSERVER1 -username admin -password ZZZZZZZ -bas_auth -status
BlackBerry(R) Enterprise Server User Administration Tool Version 5.0.1.7
Copyright (c) Research In Motion, Ltd. 2009. All rights reserved.


(05/06 16:08:11) Running command...
(05/06 16:08:12) ...Done
(05/06 16:08:12) Command Results:
Property,Value
BAS Version,5.0.1.58
BAA Version,5.0.1.24

(Note - if you are using Active Directory authentication use the it as below ) 

BESUserAdminClient.exe -n 172.29.3.142 -username BESadmin -password ZZZZZZZ - domain Galaxy.LAB -ad_auth -status)

Here are other few commands that can help you .

• Get user information
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -find -u neptune@galaxy.lab
• Get handheld statistics
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -handheld_info -hhstats -u neptune@galaxy.lab
• Get Server Statistics
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -handheld_info -stats -service -b BES01_instance_name
• Get the list of applications installed on devices.
  BESUserAdminClient.exe -n 172.29.3.142 -username admin -password ZZZZZZZ -bas_auth -handheld_info -hhstats -apps -u neptune@galaxy.lab
  

Coming up

In my next blog I plan to write about following group of operations that could be performed by this tool.

• User and Device Management 
• Server Management
• Bulk Operations

Enjoy the blog. Hope this will serve as a good start.