//
you're reading...

Integration

Wireshark Plugin User Guide

By ⋅ January 27, 2012 ⋅ Post a comment

Introduction

The CloudShark Plugin for Wireshark makes it seamless to move your capture files from Wireshark to a CloudShark appliance or CloudShark.org. Once installed, the plugin adds a new “CloudShark” menu under the existing Wireshark Tools menu. Capture files are sent to the configured CloudShark appliance or CloudShark.org by selecting the upload option under the Tools menu. The plugin also works with tshark from the command-line.

Requirements

The CloudShark plugin requires Wireshark version 1.4 or newer. The plugin uses Wireshark’s lua scripting interface and runs on all platforms supported by Wireshark provided the lua interface has been enabled. Systems must also contain a recent version of curl. NOTE: The windows installer will automatically install a local version of curl for the plugin.

Installation

The Wireshark plugin can be installed using either a platform specific installer or a generic source distribution. The plugin is only installed for the user who runs the installer. If you run Wireshark as different users, you’ll need to install the plugin for each user ( i.e. user and root accounts).

Visit our Wireshark Plugin page to access the latest version of the plugin.

Windows Installer

The Windows Installer supports Windows XP SP3, Windows Vista and Windows 7. The same Windows installer works on both 32 and 64 bit versions of Windows.

If you are using Windows XP SP3, please make sure you have installed all of your Windows system updates! Afterwards, make sure you have an updated version of Microsoft’s C++ run time libraries. And seriously consider upgrading!
You must use the default Destination Folder when installing on Windows. This will install the CloudShark plugin to the user’s Wireshark plugin directory. If you install to another location on your disk, Wireshark will not find the CloudShark plugin files.

Mac OSX Installer

The Mac OSX Installer supports OSX version 10.6 and newer. Curl is normally included in the base OSX installation.

Generic Installer (Linux and other Unix distributions)

The generic installer supports other Unix based distributions. To install the generic version, download and untar the *.tgz file. The plugin can be installed by running the “install-unix” script as the desired wireshark user.


tar xzvf cloudshark-plugin-1.0-136.tgz
cd cloudshark-1.0-136
./install-unix

Running as root or admin
Note: If you are running Wireshark as root or admin, you may need to enable support for lua scripts by modifying your /etc/wireshark/init.lua script and setting the run_user_scripts_when_superuser entry to true.


run_user_scripts_when_superuser = true

Rather than running as root or admin, try enabling capture privileges for the user running Wireshark.

Configuration

By default, the plugin is configured to work with CloudShark.org. You must modify the plugin configuration file to work with your own CloudShark appliance. The configuration file is installed as ~/.wireshark/plugins/cloudshark/cloudshark_init.lua. The configuration file can be edited right through Wireshark by selecting Tools→CloudShark→Preferences. This menu option will open the current configuration file in a text window that you may edit. After modifing the configuration file, the “Save” option must be selected before the window is closed.

The following configuration variables may be configured. NOTE: The configuration file is a lua file that must conform to the lua syntax. If a syntax error is created, Wireshark will raise a lua exception during the next upload. The configuration is reloaded before every new upload.

-- URL: The CloudShark appliance URL
CLOUDSHARK_URL = "https://www.cloudshark.org"

-- API: The API token to use
CLOUDSHARK_API_KEY = "59f5893a634b99d1bbc2cd9587a5a508"

-- Tags: A comma separated list of tags
CLOUDSHARK_TAGS = ""

-- User: The user name (only if login is required)
CLOUDSHARK_USER = ""

-- Password: The password (only if login is required)
CLOUDSHARK_PASSWORD = ""

-- Tshark: To enable tshark support for the plugin,
-- set the CLOUDSHARK_TSHARK setting to "y" for auto
-- mode or "prompt" for prompting mode.
CLOUDSHARK_TSHARK = "y"

-- Curl: The path to curl if non-standard
-- CLOUDSHARK_CURL = [[C:\example\curl.exe]]

-- CA Bundle: The path to an alternative CA bundle file in pem format
-- CLOUDSHARK_CABUNDLE = [[C:\example\curl-ca-bundle.crt]]

These options are defined as:

  • CLOUDSHARK_URL – The CLOUDSHARK_URL entry contains the URL used to reach your CloudShark appliance. It must also contain desired http or https transport.
  • CLOUDSHARK_API_KEY – The CLOUDSHARK_API_KEY entry contains the API key for your CloudShark appliance. For CloudShark.org, there is a well know API key established for Wireshark. You can allocate a new API key for your CloudShark appliance by visiting the “Settings” menu on the CloudShark admin interface. Also, please see the CloudShark user’s guide for help setting up and configuring the API keys. Captures uploaded through an API key can automatically be assigned to a specific user and group.
  • CLOUDSHARK_TAGS – The CLOUDSHARK_TAGS entry is used to specify tags that should be applied to every Wireshark upload. Tags must be comma separated. Additional tags can also be specified at upload time in the Upload GUI. Useful tags include location information, device information, and security information.
  • CLOUDSHARK_USER – The CLOUDSHARK_USER entry is required when the API key also requires user authentication. NOTE: The defult API key for CloudShark.org does not require user authentication.
  • CLOUDSHARK_PASSWORD – The CLOUDSHARK_PASSWORD entry is required when the API key also requires user authentication. This entry must contain the password. NOTE: The defult API key for CloudShark.org does not require user authentication.
  • CLOUDSHARK_TSHARK – The CLOUDSHARK_TSHARK entry is used to enable the CloudShark plugin for tshark. By default, the plugin does not perform any uploads when tshark is used. You can enable tshark support by setting this value to “y” for automatic uploads or “prompt” to prompt the user before uploading.
  • CLOUDSHARK_CURL – The CLOUDSHARK_CURL entry is used to specify the command path to curl. By default, the plugin executes “curl” which must be in the path for the user running Wireshark. Paths should be entered using lua’s [[ ]] notation rather than using double quotes.
  • CLOUDSHARK_CABUNDLE – The CLOUDSHARK_CABUNDLE entry is used to specify an alternative CA file. Paths should be entered using lua’s [[ ]] notation rather than using double quotes.<

Uploading

A capture file may be uploaded by selecting the “Upload” option from the Tools→CloudShark menu. You may upload a capture file when a live capture is still in progress or stop the capture before the upload. If you upload a live capture, any new packets that arrive while the upload is happening may not be included. For precise results, we recommend that you stop a live capture before uploading.

The Upload dialog provides additional options for adding tags and naming your capture file. Both of these entries are optional. Any tags specified will be added in addition to any tags configured with the CLOUDSHARK_TAGS option. If a new name is specified, the plugin will copy the capture file to this name before uploading. The name field should also contain the desired extention such as .cap or .pcap. If no name is specified, the file name used in the CloudShark session is OS dependent.

A progress dialog will appear once an uploaded is started. At the completion of the upload, Wireshark will open another status dialog with either the location of the CloudShark session URL or an error indication. If the upload is successful, CloudShark will also attempt to open the CloudShark session URL using the default browser.

Using Other Certificates

The default CA file included with the CloudShark plugin will verify certificates from many of the established CA companies. If you need to use a different CA file to verify your CloudShark appliance, you can specify the path to a local CA file that contains the required CA certificates in PEM format. For example:

CLOUDSHARK_CABUNDLE = "/home/fred/my-ca.crt"

Tshark Support

The plugin supports both the Wireshark GUI and tshark. To enable tshark support, configure the CLOUDSHARK_TSHARK setting to either “y” or “prompt”. The same configuration file is used for both Wireshark and tshark. When CLOUDSHARK_TSHARK is “y”, the plugin will automatically upload the current capture file to CloudShark. When CLOUDSHARK_TSHARK is “prompt”, the user will be prompted to confirm the upload. The capture file will not be uploaded in “prompt” mode unless the user specically enters “y” at the prompt.

Tshark Example

tshark -i eth0 -q -c 5
CloudShark plugin for WireShark (c) 2012
Version 1.0 rev 136
Developed by QA Cafe
Capturing on eth0
5 packets captured

Uploading capture file to CloudShark via http://172.16.1.137
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  5048    0    66  100  4982    238  18007 --:--:-- --:--:-- --:--:-- 18050

HTTP Response Code: 200
A new CloudShark session has been created at:

http://172.16.1.137/captures/7d1e5e2645b3

Security

Use of https uploads is recommended. The CloudShark plugin will always upload via https when the CLOUDSHARK_URL is specified using https. The default configuration for CloudShark.org defaults to https.

Default Browser

The CloudShark plugin will open new CloudShark session URLs using the system’s default browser. We recommend setting up your system with an updated version of one of the modern browsers as your default. This will maximize your CloudShark experience. The latest version of Chrome or Safari is recommended.

Disk Space

The plugin uses the ~/.wireshark/plugin/cloudshark directory for working disk space. You must have enough disk space in this directory to support your captures. A good rule of thumb is to allocate 3 times as much disk space as your largest desired capture file. The plugin manages the capture files automatically.

Errors

It is possible that an upload will fail. If the upload does fail, an error message will be reported. Some possible errors include.

  • Invalid CLOUDSHARK_URL
  • Invalid API Key
  • Authentication failure
  • Capture file is too big

Upgrades

The plugin can safely be upgraded to a new version if available. By default, the installer will not overwrite any existing configuration file. Your configuration will be preserved if you have configured your plugin to work with a specific CloudShark appliance.

Uninstall

The plugin can be removed by deleting the ~/.wireshark/plugin/cloudshark directory. There is also an uninstall.exe available in the cloudshark directory on Windows.