How to long-term debug with beroNet's tool "PowerDebug"

What is it ?

In many cases problems are not reproducable immediately because they are happening not every time. Or, sometimes audio would be needed inside the trace, and therefore the capacity doesn't reach, or, or, or. Like maybe some of you know, beroNet gateways have not much capacity to store traces, that's why often traces are not complete or overwritten with other data, and the sitiuation which should be examined is not included. For all these cases we made "PowerDebug". This tool consists of a server and a client application. The server is written in Java and can run anywhere where a Java VM (JRE) is installed. The client is an App which can be installed on a beroNet gateway. The trace data will be sent from client to server over TCP/IP, and can be stored onto the server which has normally much more storing capacity as the gateway. Long-term debugging is now possible without big efforts.


Prerequisites


What do you need to run PowerDebug server/client:
Server

  • Java >= 1.7
  • adminstrative user rights to run server as a daemon (Windows service for example)
  • free hdd space to store traces
  • TCP ports 8888 and 2221 should not be assigned by other appliactions

Client

  • App-FS >= 3.0
  • adminstrative user rights to install the App


Install PowerDebug server as Windows Service

You want to run the server under Windows as Windows Service ? No problem, here are the steps you need to do so:

  1. Download PowerDebug-Package from here: powerdebug-0.9.5-windows.zip
  2. Unpack zip-file to a directory you want to run this tool and receive traces
  3. You'll get a new directory named "powerdebug-<version>", in which <version> stands for the installed PowerDebug version.
  4. Open a command line window as administrator
  5. Enter echo %JAVA_HOME% to proove if JAVA_HOME variable is set to the directory of your Java VM.
  6. If the output is not like the installation directory of your Java VM, open install-service.bat with a text editor and change the "JH" variable to the Java home path.
  7. Change to installation directory:

    cd \path\to\pwerdebug

  8. Now execute "install-service.bat" in the command line window (which is running as administrator)

    C:\path\powerdebug> .\install-service.bat <enter>

  9. If everything gone well, you should now have a new entry in the windows "Services" manager named "PowerDebug". If you want to remove the service, just execute "uninstall.bat", as administrator too.
  10. Select this new entry and start the service
  11. Now it's time to check if the server is porperly working. For that you should open a browser and enter this url: http://localhost:8888

    You should see a gui like this: If you not see this gui, something gone wrong. In this case please refere to #Possible problems or contact support@beronet.com

  12. Last step is to install the client application onto the gateway. For this, you have to login to the gateway first. Go to the menu "Apps->Market", press "upload file" and choose the app-file which is in the directory "apps" which can be found in the installation dirctory of the server application. There must be a file named "powerdebug-<version>-app.tar.gz". Choose this file. After upload you will be asked if you really want to install, choose "yes". After installing the app you should find a new menu entry under "Apps"-menu named "powerdebug". Click this new item and you should be redirected to the powerdebug client gui:

Now everything seems to be ready to run.
IMPORTANT: If you've enabled the Windows Firewall, you have to take care to allow incoming request on TCP ports 2221 and 8888, or, better, just disable firwall as long you make a trace. Otherwise client may not able to connect to server,

Install PowerDebug as Linux daemon

To run server as daemon under linux just follow these steps:

  1. Download PowerDebug-Package from here: powerdebug-0.9.5-linux.tar.gz
  2. Unpack zip-file to /opt
  3. Change rights of the init script with:

    chmod ug+x ./powerdebug.sh

  4. Enter following command to start the server:

    ./powerdebug.sh start

  5. If you want to run the server at boot time, just copy powerdebug.sh to /etc/init.d and enter this command:

    sudo update-rc.d powerdebug.sh defaultsThis command is only for Debian based Linux distributions. You may have to investigate how to install init script on your distribution by yourself.

  6. Now it's time to check if the server is porperly working. For that you should open a browser and enter this url: http://localhost:8888

    You should see a gui like this:

Starting and stopping a trace

To start a trace, follow these steps:

  1. Log in to the gateway where you've installed the powerdebug app and choose menu item "Apps->powerdebug"
  2. Enter the IP address of the machine where you've installed the server application into the field "Server"
  3. Choose technologies which has to be traced with check button group "Protocols to trace", ISDN, Analog, GSM, SIP

    If you have chosen SIP, you can also choose which kind of traffic shall be included in the tcpDump: SIP-only, SIP+Audio, ALL

  4. Example of choice:

  5. Now just press start, and after that you'll see the gui with a running trace:

  6. You can now press button "Back" to go back to the gateway configuration gui. If you come back again, you'll see the same as long the trace is running.
  7. If you want to stop the trace, just press "Stop" and after a short while, the "ready to start" gui will be appear again with message "STOPPED"

IMPORTANT: Please don't start a regular fulltrace while powerdebug is also running a trace. This willl cause more load and incomplete trace on powerdebug-server

Where to find the traces

To get a trace file just open the server gui in your prefered browser:

http://<ip-of-your-server>:8888

You'll see the server gui including the list of tracefiles:

To download a trace just choose the right file and press "Download".
The File includes following structure:

  • /
    • <serial-of-your-device>
      • <startdate-of-trace>
        • conf
        • debug.txt
        • dmesg.*
        • ISDN-*.pcap
        • analog.log
        • gsm.log
        • isgw.err
        • isgw.log
        • messages*
        • provisioning.log
        • sofia.log
        • system.log
        • tcpDump.pcap

This trace file can now be sent via EMail, may connected to a already open ticket, to support@beronet.com.

Possible problems

  1. You've executed the install-service.bat, but you don't get the new entry in service manager:

    Either you have executed bat without administrative rights, or the path to your Java VM is not properly set, or Java VM isn't installed.

  2. The service seems to be started, but you don't see the server gui anyhow:

    Propable port 8888 was already allocated by another app

  3. You try to start a trace at the client gui, but get message "Server not responding":

    Either server is not strated, or Windows Firewall blocks traffic, or problem # 2 prevents reachability, or server is not reachable from the network of the gateway.

If you can't solve problems with powerdebug by yourself, just leave a message to support@beronet.com with a sufficient description of your problem.

If you need scheduled remote assistance, you can request our on-demand support services: https://www.beronet.com/support