Logging

What is it?
BBSSH allows you to enable extensive logging of terminal and session activity. This log file can be used by the BBSSH developers to help track down the reason for some of the problems you might encounter.

There are two types of logging: session and terminal. If you’re asked to provide a log file, whoever asks will tell which type of log is needed. If you use the “send feedback” option in BBSSH and are prompted to send a log file, this is the session log file.  Note that unless you change settings by following the steps for changing log level, the only sensitive information contained in the session log file is the host and port you are connecting to.

By default, if you are running a stable build logging is turned off completely. If you are running an unstable or beta build, some logging is already turned on.

Enable Session debug logging

  1. Close any open connections.
  2. Return to the BBSSH main screen.
  3. Hold down the alt key while pressing: LGFS
  4. To turn logging off, use Alt+LGFX or just exit BBSSH

Next, you may be asked to change the logging level. For security purposes, when Session logging is enabled it does not record a lot of information. All logging reverts to defaults when BBSSH is shut down.

To set the amount of information logged (after enabling logging above):

  1. Close any open connections.
  2. Return to the BBSSH main screen.
  3. Maximum insecure logging: Alt+LGMX
  4. Maximum secure logging: +LGIN
  5. Minimum /default logging: Alt+LGWN

Enable Terminal logging

Terminal logging (available in 2.0.2 and later) captures everything sent by the remote server for display on-screen. This information is useful for tracking down display or rendering issues. BBSSH developers have a tool which can take a terminal log and play it back, so they see the same thing that you saw.

To enable terminal logging:

  1. Close the connection that you want to log.
  2. Return to the BBSSH main screen.
  3. Select the session you wish to enable log for.
  4. Hold down the alt key while pressing: LGTM
  5. To turn logging off, disconnect the session – it will automatically stop logging.

Sending Log Files

  1. If you have an SDCard, log files are saved in the root path of the SD card.   If you don’t, they are saved in the “user” directory of your device storage.
    1. Session logs are named as: BBSSH_YYYYMMDD.txt eg BBBSSH_20110228.txt.
    2. Terminal logs are in two parts, and are named as TERM_sessionname#.log and term_sessionname#.idx, eg TERM_myhouse1.log and term_myhouse1.idx.  The numeric portion is internally generated and is not guaranteed unique – so it’s important that you send and delete these files as soon as you’re done recreating the problem you’ve encountered.
  2. For most cases, you can send log files by using the “send feedback” menu in BBSSH. You will be prompted to attach the log file if a session log exists.
  3. If you need to modify a file (see Security Considerations below) before sending it — or if you need to attach terminal logs — then use “send feedback” to get the correct email address; and then manually attach the  file.
  4. You can also send them from your desktop, if transferring the files to the desktop for viewing/editing.  Use “send feedback” to get the email address, and attach the file(s) normally.
  5. If you wish to encrypt the email using PGP, we’re working on setting up an inbox secured with this.

Security Considerations

Some log levels can cause sensitive data to be included in the log files. Please review the critical security notes below about the different logging levels.

Maximum Secure Logging

When logging at this level, the log file will not capture sensitive data such as passwords. This mode logs activity within BBSSH and ssh protocol level information, but not the data sent in any case where doing so is a security risk. This mode will capture the host name and port that you are connecting to.

Default Logging

Default logging captures less data than “maximum secure logging”; the log file will not capture sensitive data such as passwords; however it will capture the host name and port you are connecting to. Note that logging is not enabled at all by default, unless you are running an unstable or beta release.

Maximum Insecure Logging

Because this level logs all data sent/received it can capture sensitive data if…

  • You authenticate to the server using any method other than private key (eg password, keyboard-interactive). note that if you get prompted for your key password this is not logged
  • Once logged in, you type an additional password into the remote session
  • you view a password in plaintext on the remote session

If any of the above apply, you *must* edit the log file to remove sensitive information prior to sending the log file to the BBSSH team.
This logging level will never be enabled by default — you must specifically enable it as described above.

Terminal Logging

Terminal logging captures terminal data sent from the remote server to your BlackBerry. If you see sensitive information on your screen, it is also captured in the log. No outbound data is captured.
Because this file cannot be edited without corrupting it, you must not send it if you have any reason to think you have viewed sensitive information in the saved session.

Share