riverbedRiverbed Cascade Shark REST API v4.0 DRAFT 0.2Created Nov 21, 2013 at 08:44 AM

Overview

This document describes the RESTful APIs exported by Cascade Shark products.

It is assumed that the reader has practical knowledge of RESTful APIs, so the documentation does not go into detail about what REST is and how to use it. Instead the documentation focuses on what data can be accessed or modified, how to access it, and how to encode requests and responses.

The remainder of this section lists the high level functionality exposed by the REST API and describes the data encodings for objects that are used to encode information for requests and responses.

The Resources section lists the supported REST resources and the methods supported on these resources. For each operation, the document describes what the operation does, the specific HTTP method and URL used, the data types used for requests and responses (if any) and any required or optional URL parameters.

The Data Types section describes commonly used data types in the REST API, including example encodings in both JSON and XML.

The Errors section lists the various error codes that may be returned from REST API operations.

Functionality

The Shark REST API provides programmable access to virtually all of the functionality implemented by the shark appliance, including:

  • Applying views and obtaining view output

  • Enumerating and examining packet data sources on the appliance (interfaces, capture jobs, trace clips, and files)

  • Creating trace clips, uploading

  • Extracting packet data from the appliance

  • Extracting and modifiying system configuration, including user configuration, capture job management, basic system configuration, etc.

  • Access system version information and apply system updates

NOTE: Resources and methods used for authentication to the shark appliance through the API, and other resources related to querying for system information are implemented by the Riverbed Common REST API. Before accessing the Shark API, please familiarize yourself with the Common API documentation.

Data Encoding

Most resources exposed by the API support both XML and JSON encoding for requests and responses. The selection of the specific encoding is accomplished through the use of HTTP headers.

The Accept header should be included with all API requests, and it is used to control the encoding of the response body. To specify XML encoding, the header should be set to Accept: text/xml, and to specify JSON encoding, the header should be set to Accept: application/json. If the Accept header is omitted, the default encoding is XML.

The Content-Type header must be included with all PUT or POST requests that include a request body. To specify XML encoding, the header should be set to Content-Type: text/xml. To specify JSON encoding, the header should be set to Content-Type: application/json.

Some resources support alternative content types for requests and responses, as identified in the specific resource documentation below.

Resources

interfaces: List interfaces

List of Shark interfaces.

GET https://{device}/api/shark/4.0/interfaces?filter={string}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
filter <string> 'device' to limit list to physical devices; 'virtual' to limit list to virtual files; 'aggregating' to limit list to aggregating ports. Optional
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ interface ]
Property Name Type Description Notes
interfaces <array of <interface>> List of interfaces on this Shark
interfaces[interface] <interface> Instance of an <interface>

interfaces: Get interface info

Information on Shark interface {interface_id}.

GET https://{device}/api/shark/4.0/interfaces/{interface_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
interface_id <string> Interface identifier
Response Body

Returns an interface data object.

interfaces: Update interface settings

Update information on Shark interface {interface_id}. NOTE: Only physical ('device') interface settings may be updated.

PUT https://{device}/api/shark/4.0/interfaces/{interface_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
interface_id <string> Interface identifier
Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "pass_thru": string,
  "board_speed": {
    "status": string,
    "duplex_type": string,
    "speed_mbps": string
  },
  "tap_type": string,
  "dedup_status": string,
  "speed_options": [
    {
      "status": string,
      "duplex_type": string,
      "speed_mbps": string
    }
  ]
}
Property Name Type Description Notes
interface_settings <object> Update information for a Shark physical interface. Note: If new passthru mode setting is present, all other settings are ignored.
interface_settings.pass_thru <string> New passthru mode status Optional; Values: ENABLED, DISABLED, NOT_SUPPORTED
interface_settings.board_speed <object> Speed, duplex type, and status of a speed option Optional
interface_settings.board_speed.status <string> Status of this link speed option for this interface Optional; Values: SUPPORTED, ENABLED, NEGOTIATED
interface_settings.board_speed.
duplex_type
<string> Duplex type for this speed option Values: HALF, FULL, UNKNOWN
interface_settings.board_speed.
speed_mbps
<string> Throughput for this speed option Values: MBPS_10, MBPS_100, MBPS_1000, MBPS_10000
interface_settings.tap_type <string> New tap type setting Optional; Values: NONE, CPACKET, GIGAMON_HEADER, GIGAMON_TRAILER, GIGAMON_TRAILER_X12, VSS, VSS_PORT_ID, UNKNOWN
interface_settings.dedup_status <string> New packet deduplication setting Optional; Values: ENABLED, DISABLED, NOT_SUPPORTED
interface_settings.speed_options <array of <object>> List of link speed options Optional
interface_settings.speed_options
[link_speed_option]
<object> Speed, duplex type, and status of a speed option
interface_settings.speed_options
[link_speed_option].status
<string> Status of this link speed option for this interface Optional; Values: SUPPORTED, ENABLED, NEGOTIATED
interface_settings.speed_options
[link_speed_option].duplex_type
<string> Duplex type for this speed option Values: HALF, FULL, UNKNOWN
interface_settings.speed_options
[link_speed_option].speed_mbps
<string> Throughput for this speed option Values: MBPS_10, MBPS_100, MBPS_1000, MBPS_10000
Response Body

On success, the server does not provide any body in the responses.

jobs: List jobs

Get the current list of capture jobs

GET https://{device}/api/shark/4.0/jobs
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "id": string,
    "status": job_status,
    "config": job_config,
    "index": job_index_info
  }
]
Property Name Type Description Notes
jobs <array of <object>> List of capture jobs
jobs[job] <object> A capture job
jobs[job].id <string> Job ID
jobs[job].status <job_status> Status information for this job
jobs[job].config <job_config> Configuration information for this job
jobs[job].index <job_index_info> Index information for this job

jobs: Create job

Create a new capture job

POST https://{device}/api/shark/4.0/jobs
Authorization

This request requires authorization.

Request Body

Provide a job_config data object.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "id": string
}
Property Name Type Description Notes
job <object> Information for a new job
job.id <string> Job id

jobs: Get job information

Get information (status and config) for a capture job

GET https://{device}/api/shark/4.0/jobs/{job_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "id": string,
  "status": job_status,
  "config": job_config,
  "index": job_index_info
}
Property Name Type Description Notes
job <object> A capture job
job.id <string> Job ID
job.status <job_status> Status information for this job
job.config <job_config> Configuration information for this job
job.index <job_index_info> Index information for this job

jobs: Get job config

Get configuration for capture job

GET https://{device}/api/shark/4.0/jobs/{job_id}/config
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Response Body

Returns a job_config data object.

jobs: Get job status

Get status information for a capture job

GET https://{device}/api/shark/4.0/jobs/{job_id}/status
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Response Body

Returns a job_status data object.

jobs: Get job stats

Statistics for a capture job

GET https://{device}/api/shark/4.0/jobs/{job_id}/stats
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "packets_written": {
    "total": string,
    "last_second": string,
    "last_minute": string,
    "last_hour": string
  },
  "packets_dropped": {
    "total": string,
    "last_second": string,
    "last_minute": string,
    "last_hour": string
  }
}
Property Name Type Description Notes
job_stats <object>
job_stats.packets_written <object>
job_stats.packets_written.total <string>
job_stats.packets_written.last_second <string>
job_stats.packets_written.last_minute <string>
job_stats.packets_written.last_hour <string>
job_stats.packets_dropped <object>
job_stats.packets_dropped.total <string>
job_stats.packets_dropped.last_second <string>
job_stats.packets_dropped.last_minute <string>
job_stats.packets_dropped.last_hour <string>

jobs: Get job index status

Index information for capture job.

GET https://{device}/api/shark/4.0/jobs/{job_id}/index
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Response Body

Returns a job_index_info data object.

jobs: Update job configuration

Update configuration of a capture job

PUT https://{device}/api/shark/4.0/jobs/{job_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Request Body

Provide a job_config data object.

Response Body

On success, the server does not provide any body in the responses.

jobs: Update job status

Update running status of capture job

PUT https://{device}/api/shark/4.0/jobs/{job_id}/status
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "state": string,
  "clear_packets": boolean
}
Property Name Type Description Notes
status <object> Update job state, optionally clear packets for job
status.state <string> Running state of a capture job Values: ACTIVE, RUNNING, STOPPED, UNKNOWN
status.clear_packets <boolean> 'true' to clear packets for this job Optional
Response Body

On success, the server does not provide any body in the responses.

jobs: Delete job

Delete capture job

DELETE https://{device}/api/shark/4.0/jobs/{job_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Response Body

On success, the server does not provide any body in the responses.

clips: List clips

List of trace clips from capture job {job_id}

GET https://{device}/api/shark/4.0/clips
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "id": string,
    "status": clip_status,
    "config": clip_config,
    "index": index_info
  }
]
Property Name Type Description Notes
clips <array of <object>> List of clips
clips[clip] <object> Description and status of trace clip
clips[clip].id <string> Clip id
clips[clip].status <clip_status> Status information for this clip
clips[clip].config <clip_config> Configuration information for this clip
clips[clip].index <index_info> Index information for this clip

clips: Create clip

Create a new trace clip from capture job {job_id}

POST https://{device}/api/shark/4.0/clips
Authorization

This request requires authorization.

Request Body

Provide a clip_config data object.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "id": string
}
Property Name Type Description Notes
clip <object>
clip.id <string> Identifier of the newly created clip

clips: Get clip detail

Info on clip {clip_id} from capture job {job_id}

GET https://{device}/api/shark/4.0/clips/{clip_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
clip_id <string> Clip identifier
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "id": string,
  "status": clip_status,
  "config": clip_config,
  "index": index_info
}
Property Name Type Description Notes
clip <object> Description and status of trace clip
clip.id <string> Clip id
clip.status <clip_status> Status information for this clip
clip.config <clip_config> Configuration information for this clip
clip.index <index_info> Index information for this clip

clips: Update clip

Update config info for clip {clip_id} from capture job {job_id}

PUT https://{device}/api/shark/4.0/clips/{clip_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
clip_id <string> Clip identifier
Request Body

Provide a clip_config data object.

Response Body

On success, the server does not provide any body in the responses.

clips: Delete clip

Delete clip {clip_id} from capture job {job_id}

DELETE https://{device}/api/shark/4.0/clips/{clip_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
clip_id <string> Clip identifier
Response Body

On success, the server does not provide any body in the responses.

clips: Get clip config

Config info for clip {clip_id} from capture job {job_id}

GET https://{device}/api/shark/4.0/clips/{clip_id}/config
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
clip_id <string> Clip identifier
Response Body

Returns a clip_config data object.

clips: Get clip status

Status info for clip {clip_id} from capture job {job_id}

GET https://{device}/api/shark/4.0/clips/{clip_id}/status
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
clip_id <string> Clip identifier
Response Body

Returns a clip_status data object.

clips: Update clip lock status

Update lock status for clip {clip_id} from capture job {job_id}

PUT https://{device}/api/shark/4.0/clips/{clip_id}/status
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
clip_id <string> Clip identifier
Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "locked": boolean
}
Property Name Type Description Notes
status <object>
status.locked <boolean> 'true' to lock the packets and the index for this clip, 'false' otherwise
Response Body

On success, the server does not provide any body in the responses.

clips: Get clip index info

Index info for clip {clip_id} from capture job {job_id}

GET https://{device}/api/shark/4.0/clips/{clip_id}/index
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
clip_id <string> Clip identifier
Response Body

Returns an index_info data object.

clips: List job exports

Get list of current export operations from a capture job

GET https://{device}/api/shark/4.0/jobs/{job_id}/exports
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
job_id <string> Job identifier
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ export ]
Property Name Type Description Notes
exports <array of <export>> List of exports currently under way
exports[export] <export> Instance of an <export>

filesystem: List root directory

Listing of root user file directory

GET https://{device}/api/shark/4.0/fs
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ dir ]
Property Name Type Description Notes
fs <array of <dir>> List of directories
fs[dir] <dir> Instance of a <dir>

filesystem: List directory

Get information on directory {directory_id}.

GET https://{device}/api/shark/4.0/fs/{directory_path}?directory_id={string}&recursive={string}&details={string}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
directory_id <string> Directory path
recursive <string> 'true' for recursive directory listing, 'false' otherwise. Optional
details <string> 'true' for details on all files, 'false' otherwise. Optional
Response Body

Returns a dir data object.

filesystem: Create file or directory

Create trace file, merged file, multisegment file, or directory on the Shark. The file path is specified in the 'Content-Disposition' HTTP header and the file type to be created is specified using the 'Content-Type' HTTP header.

POST https://{device}/api/shark/4.0/fs/{directory_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
directory_id <string> The directory in which the file or directory is to be created
HTTP Headers
Property Name Type Description Notes
Content-Type <string> The type of object to be created
Content-Disposition <string> The name of the file or directory to be created
Request Body VariantsCreate trace file

Content-Type: application/x-vnd.tcpdump

Provide a request body containing the File contents with content type application/x-vnd.tcpdump.

Create directory

Content-Type: x-shark-directory

Do not provide a request body.

Create virtual file

Content-Type: application/json or text/xml

Provide a request body with the following structure:

  • JSON
  • XML
{
  "type": string,
  "linked_sources": [
    {
      "path": string,
      "default_source": boolean,
      "timeskew": number,
      "description": string
    }
  ]
}
Property Name Type Description Notes
request <object> Contains info about a new multisegment or merged file
request.type <string> File type Values: MULTISEGMENT_FILE, MERGED_FILE
request.linked_sources <array of <object>> Linked sources details list
request.linked_sources[linked_source] <object>
request.linked_sources[linked_source].
path
<string> Linked source path. It could be either an absolute path (fs/ID) or a relative path starting from the aggregated file folder.
request.linked_sources[linked_source].
default_source
<boolean> The default source is the reference source in a multisegment file collection and it is used as reference for the time skew calculation Optional
request.linked_sources[linked_source].
timeskew
<number> It is the packets timestamps offset associated with the linked source Optional
request.linked_sources[linked_source].
description
<string> A simple description field associated with the linked source Optional
Response Body

On success, the server does not provide any body in the responses.

filesystem: Get file info

Get descriptive information for file or directory {file_id}

GET https://{device}/api/shark/4.0/fs/{file_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File or directory path
Response Body

Returns a file data object.

filesystem: Download file contents

Download contents of trace file, merged file, or multisegment file {file_id}.

GET https://{device}/api/shark/4.0/fs/{file_id}/download
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Response Body

On success, the server returns a request body containing data with content type application/x-vnd.tcpdump or application/xml.

filesystem: Modify merged or multisegment file

Modify merged file or multisegment file {file_id} on the Shark.

PUT https://{device}/api/shark/4.0/fs/{file_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "type": string,
  "linked_sources": [
    {
      "path": string,
      "default_source": boolean,
      "timeskew": number,
      "description": string
    }
  ]
}
Property Name Type Description Notes
aggregated <object> Contains info about a new multisegment or merged file
aggregated.type <string> File type Values: MULTISEGMENT_FILE, MERGED_FILE
aggregated.linked_sources <array of <object>> Linked sources details list
aggregated.linked_sources[linked_source] <object>
aggregated.linked_sources[linked_source].
path
<string> Linked source path. It could be either an absolute path (fs/ID) or a relative path starting from the aggregated file folder.
aggregated.linked_sources[linked_source].
default_source
<boolean> The default source is the reference source in a multisegment file collection and it is used as reference for the time skew calculation Optional
aggregated.linked_sources[linked_source].
timeskew
<number> It is the packets timestamps offset associated with the linked source Optional
aggregated.linked_sources[linked_source].
description
<string> A simple description field associated with the linked source Optional
Response Body

On success, the server does not provide any body in the responses.

filesystem: Delete file

Delete file {file_id}. NOTE: If a file to be deleted is open for any reason, the delete operation will fail.

DELETE https://{device}/api/shark/4.0/fs/{file_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Response Body

On success, the server does not provide any body in the responses.

filesystem: Delete directory

Delete user directory {directory_id}. If the directory is not empty, all files in the directory will be deleted as well. NOTE: If a file to be deleted is open for any reason, the delete operation will fail.

DELETE https://{device}/api/shark/4.0/fs/{directory_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
directory_id <string> Directory path
Response Body

On success, the server does not provide any body in the responses.

filesystem: Get file checksum

Obtain a checksum for a trace file.

GET https://{device}/api/shark/4.0/fs/{file_id}/checksum
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "value": string,
  "method": string
}
Property Name Type Description Notes
checksum <object> Contains info about a checksum calculated on a trace file
checksum.value <string> Trace file's checksum
checksum.method <string> Checksum algorithm Values: SHA256

filesystem: Get file index info

Get index information for trace file {file_id}.

GET https://{device}/api/shark/4.0/fs/{file_id}/index
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Response Body

Returns an index_info data object.

filesystem: Create file index

Create index for trace file {file_id}

POST https://{device}/api/shark/4.0/fs/{file_id}/index
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

filesystem: Delete file index

Delete index for trace file {file_id}.

DELETE https://{device}/api/shark/4.0/fs/{file_id}/index
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Response Body

On success, the server does not provide any body in the responses.

filesystem: Move file or directory

Request move of file or directory resource {file_id}

POST https://{device}/api/shark/4.0/fs/{file_id}/move
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "destination": string
}
Property Name Type Description Notes
move <object> Contains the resource's destination id for a move operation
move.destination <string> Resource's destination id
Response Body

On success, the server does not provide any body in the responses.

filesystem: Create timeskew estimate

Start a timeskew estimation process for multisegment file {file_id}.

PUT https://{device}/api/shark/4.0/fs/{file_id}/fs/timeskew_estimate?packet_count={number}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
packet_count <number> Maximum number of packets to process Optional
Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

filesystem: Get timeskew estimate results

Time skew information for multisegment file {file_id}

GET https://{device}/api/shark/4.0/fs/{file_id}/timeskew_estimate
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "status": {
    "state": string,
    "duplicated_count": number,
    "first_invalid_timestamp": timestamp-hp,
    "invalid_source_index": number
  },
  "results": [
    {
      "source_index": number,
      "timeskew": number
    }
  ]
}
Property Name Type Description Notes
timeskew_estimate <object> Time skew estimate information
timeskew_estimate.status <object> Status information for the time skew estimate
timeskew_estimate.status.state <string> Values: EMPTY, COMPUTING, NO_PACKETS, UNIDIRECTIONAL, TIMESTAMP_WARNING, DUPLICATE_WARNING, OK
timeskew_estimate.status.
duplicated_count
<number> Number of packets with the same timestamp in different capture points. Check this field in order to estimate if this is a real issue or not: if the number of packets experiencing this problem is high probably at least two files contain the same packets, otherwise it means that for some packets the timeskew observed makes the delay becomes zero (timeskew = delay for that packet). Optional
timeskew_estimate.status.
first_invalid_timestamp
<timestamp-hp> First timestamp causing the TIMESTAMP_WARNING code
timeskew_estimate.status.
invalid_source_index
<number> Index of the file causing the TIMESTAMP_WARNING code Optional
timeskew_estimate.results <array of <object>> List of linked sources Optional
timeskew_estimate.results[result] <object> Time skew information for a linked source
timeskew_estimate.results[result].
source_index
<number> Index of the linked source
timeskew_estimate.results[result].
timeskew
<number> Estimated time skew compared to the default source

filesystem: Delete timeskew estimate

Delete time skew estimate results for multisegment file {file_id}.

DELETE https://{device}/api/shark/4.0/fs/{file_id}/fs/timeskew_estimate
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
file_id <string> File path
Response Body

On success, the server does not provide any body in the responses.

packet export: Start export operation

Create a new export operation from the given source. This begins the process of extracting packets from the given source and returns a handle through which the caller can obtain status on the operation as well as download the packets themselves.

POST https://{device}/api/shark/4.0/{source_type}/{source_id}/exports
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
source_type <string> Packet source type identifier. Must be one of "interfaces", "jobs", "clips", or "fs".
source_id <string> Specific source identifier of type {source_type}. For example, if source_type is "jobs", then the {source_id} is the job identifier.
Request Body

Provide an export_config data object.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "id": string
}
Property Name Type Description Notes
export_id <object>
export_id.id <string> ID of created export

packet export: List export operations

List active export operations from the given source.

GET https://{device}/api/shark/4.0/{source_type}/{source_id}/exports
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
source_type <string> Packet source type identifier. Must be one of "interfaces", "jobs", "clips", or "fs".
source_id <string> Specific source identifier of type {source_type}. For example, if source_type is "jobs", then the {source_id} is the job identifier.
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ export ]
Property Name Type Description Notes
exports <array of <export>> List of exports currently under way
exports[export] <export> Instance of an <export>

packet export: Get export operation status

Get status of an export operation

GET https://{device}/api/shark/4.0/{source_type}/{source_id}/exports/{export_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
source_type <string> Packet source type identifier. Must be one of "interfaces", "jobs", "clips", or "fs".
source_id <string> Specific source identifier of type {source_type}. For example, if source_type is "jobs", then the {source_id} is the job identifier.
export_id <string> Export operation identifier.
Response Body

Returns an export data object.

packet export: Stop export operation

Stop an export operation

DELETE https://{device}/api/shark/4.0/{source_type}/{source_id}/exports/{export_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
source_type <string> Packet source type identifier. Must be one of "interfaces", "jobs", "clips", or "fs".
source_id <string> Specific source identifier of type {source_type}. For example, if source_type is "jobs", then the {source_id} is the job identifier.
export_id <string> Export operation identifier.
Response Body

On success, the server does not provide any body in the responses.

packet export: Get job export packets

Get the packet stream for an export operation.

GET https://{device}/api/shark/4.0/{source_type}/{source_id}/exports/{export_id}/packets
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
source_type <string> Packet source type identifier. Must be one of "interfaces", "jobs", "clips", or "fs".
source_id <string> Specific source identifier of type {source_type}. For example, if source_type is "jobs", then the {source_id} is the job identifier.
export_id <string> Export operation identifier.
Response Body

On success, the server returns a request body containing data with content type application/vnd.tcpdump.pcap.

packet export: Download job packets

Export packets from a capture job. Response content type is 'application/vnd.tcpdump.pcap'.

GET https://{device}/api/shark/4.0/{source_type}/{source_id}/packets?bytes={number}&seconds={number}&filename={string}&file_format={string}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
source_type <string> Packet source type identifier. Must be one of "interfaces", "jobs", "clips", or "fs".
source_id <string> Specific source identifier of type {source_type}. For example, if source_type is "jobs", then the {source_id} is the job identifier.
bytes <number> Limit on number of bytes to be extracted. Optional
packets <number> Limit on number of packets to be extracted. Optional
seconds <number> Limit on total time (in seconds) of packet extraction. Optional
filename <string> Name of output filename. This will appear in the 'content-disposition' header of the response. Optional
file_format <string> Format of output file: 'PCAP_US' for PCAP format (microsecond resolution); 'PCAP_NS' for PCAP format (nanosecond resolution); 'PCAPNG_US' for PCAP-NG format (microsecond resolution); or 'PCAPNG_NS' for PCAP_NG format (nanosecond resolution). Optional
Response Body

On success, the server does not provide any body in the responses.

views: List views

Get list of currently running views.

GET https://{device}/api/shark/4.0/views
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "id": string,
    "creation_time": timestamp-hp,
    "owner": string,
    "state": string,
    "locked": boolean,
    "watches": [
      {
        "id": string,
        "state": string,
        "last_error": string,
        "event_count": number,
        "first_event_time": timestamp-hp,
        "last_event_time": timestamp-hp
      }
    ]
  }
]
Property Name Type Description Notes
views <array of <object>> View list
views[view] <object> Summary information for a view
views[view].id <string> View ID
views[view].creation_time <timestamp-hp> View creation time
views[view].owner <string> Owner user name
views[view].state <string> View state Values: UNINITIALIZED, LOADED, PARAMS_LOADED, INITIALIZED, READY, RUNNING, ERRORS, DONE, CLOSING, PAUSED
views[view].locked <boolean> True if locked
views[view].watches <array of <object>> Watch list for this view
views[view].watches[watch] <object>
views[view].watches[watch].id <string> Watch Id
views[view].watches[watch].state <string> Watch state Values: UNINITIALIZED, LOADED, PARAMS_LOADED, INITIALIZED, READY, RUNNING, ERRORS, DONE, CLOSING, PAUSED
views[view].watches[watch].last_error <string> Error description, if the watch is in an error state
views[view].watches[watch].event_count <number> Number of triggered events
views[view].watches[watch].
first_event_time
<timestamp-hp> Time of the first triggered event
views[view].watches[watch].
last_event_time
<timestamp-hp> Time of the last triggered event

views: Create view

Create a new view.

POST https://{device}/api/shark/4.0/views
Authorization

This request requires authorization.

Request Body

Provide a view data object.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "id": string,
  "data_source_type": string
}
Property Name Type Description Notes
view_id <object> ID of the newly created view
view_id.id <string> View ID
view_id.data_source_type <string> Data source type Values: INDEX, PACKETS

views: Get view configuration

Get configuration for view {view_id}.

GET https://{device}/api/shark/4.0/views/{view_id}
Authorization

This request requires authorization.

Response Body

Returns a view data object.

views: Delete view

Delete view {view_id}. This will stop any packet processing and delete the view results.

DELETE https://{device}/api/shark/4.0/views/{view_id}
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

views: Get view output legend

Get data legend for the output {output_id} in view {view_id}.

GET https://{device}/api/shark/4.0/views/{view_id}/data/{output_id}/legend
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "base": string,
    "calculation": string,
    "dimension": boolean,
    "name": string,
    "description": string,
    "field": string,
    "id": string,
    "type": string
  }
]
Property Name Type Description Notes
legend <array of <object>> Output legend
legend[label] <object> Legend Entry
legend[label].base <string> Base Values: NONE, DEC, HEX, OCT, DEC_HEX, HEX_DEC, PERC
legend[label].calculation <string> Calculation Values: NONE, SUM, MAX, MIN, AVG, TIME_AVG
legend[label].dimension <boolean> True if dimension
legend[label].name <string> Name
legend[label].description <string> Description
legend[label].field <string> Field
legend[label].id <string> Id
legend[label].type <string> Type Values: NONE, PROTOCOL, BOOLEAN, UINT8, UINT16, UINT24, UINT32, UINT64, INT8, INT16, INT24, INT32, INT64, FLOAT, DOUBLE, ABSOLUTE_TIME, RELATIVE_TIME, STRING, STRINGZ, SHORT_STRING, UINT_STRING, ETHER, BYTES, UINT_BYTES, IPv4, IPv6, UDP_PORT, TCP_PORT, IPXNET, FRAMENUM, PCRE, GUID, OID, NUM_TYPES, INDEX, EUI64

views: Get view output data

Get data for the output {output_id} in view {view_id}.

GET https://{device}/api/shark/4.0/views/{view_id}/data/{output_id}?start={number}&end={number}&delta={string}&aggregated={string}&sortby={string}&fromentry={number}&toentry={number}&sorttype={string}&countonly={number}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
start <number> Timestamp value representing start time. Optional
end <number> Timestamp value representing end time. Optional
delta <string> Sampling interval, in nanoseconds Optional
aggregated <string> 'true' if output is in a single sample. Optional
sortby <string> Name (x0, x1, etc.) of column used to sort output values. Optional
fromentry <number> In paged output: number of first output row. NOTE: Row numbers start from 0. Optional
toentry <number> In paged output: number of last output row. Optional
sorttype <string> 'ascending' or 'descending' Optional
countonly <number> (Only available when 'aggregated' = 'true'.) Return number of rows only. Optional
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "samples": [
    {
      "t": timestamp-hp,
      "p": number,
      "u": number,
      "value_count": number,
      "value_sum": number,
      "vals": [
        [
          string
        ]
      ],
      "gap_start": timestamp-hp,
      "gap_end": timestamp-hp
    }
  ]
}
Property Name Type Description Notes
samples <object> View output
samples.samples <array of <object>> Samples list
samples.samples[sample] <object> Sample for a view output
samples.samples[sample].t <timestamp-hp> Sample timestamp
samples.samples[sample].p <number> Processed packet count Optional
samples.samples[sample].u <number> Unprocessed packet count Optional
samples.samples[sample].value_count <number> Number of distinct rows Optional; Present only when the output is aggregated
samples.samples[sample].value_sum <number> Sum of all the values for the sorting column Optional
samples.samples[sample].vals <array of <array of <string>>> Values list In XML, the values list is encoded as <val x0="val0" x1="val1" .../>, where x0..xN correspond to the columns defined in the view configuraton
samples.samples[sample].vals[val] <array of <string>> Value
samples.samples[sample].vals[val][val] <string>
samples.samples[sample].gap_start <timestamp-hp> Timestamp at the start of a data gap, representing a period of time in which there are no output values for the view If present, then the vals list will be empty. In XML, a gap is encoded as <gap t1="start" t2="end"/>.
samples.samples[sample].gap_end <timestamp-hp> Timestamp at the end of a data gap, representing a period of time in which there are no output values for the view If present, then the vals list will be empty. In XML, a gap is encoded as <gap t1="start" t2="end"/>.

views: Get view statistics

Get processing statistics for view {view_id}.

GET https://{device}/api/shark/4.0/views/{view_id}/stats
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "input_size": number,
  "processed_size": number,
  "state": string,
  "locked": boolean,
  "time_details": {
    "start": timestamp-hp,
    "end": timestamp-hp,
    "delta": number
  },
  "data_source_type": string
}
Property Name Type Description Notes
stats <object> View statistics
stats.input_size <number> Size (in bytes) of the input source to process
stats.processed_size <number> Size (in bytes) of the input source currently processed
stats.state <string> Handle state Values: UNINITIALIZED, LOADED, PARAMS_LOADED, INITIALIZED, READY, RUNNING, ERRORS, DONE, CLOSING, PAUSED
stats.locked <boolean> True if the view is locked
stats.time_details <object> Time details
stats.time_details.start <timestamp-hp> Output start time. Can be 0 if the output has no data.
stats.time_details.end <timestamp-hp> Output end time. Can be 0 if the output has no data.
stats.time_details.delta <number> Output sampling rate
stats.data_source_type <string> Data source type Values: INDEX, PACKETS

views: Lock view

Lock view {view_id}.

POST https://{device}/api/shark/4.0/views/{view_id}/lock
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

views: Unlock view

Unlock view {view_id}.

POST https://{device}/api/shark/4.0/views/{view_id}/unlock
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

views: Get view acl

Get access control list for running view {view_id}.

GET https://{device}/api/shark/4.0/views/{view_id}/acl
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "users": [
    {
      "name": string,
      "owner": boolean
    }
  ],
  "groups": [
    string
  ]
}
Property Name Type Description Notes
acl <object> Access Control List
acl.users <array of <object>> Users in the access control list
acl.users[user] <object> User in the access list
acl.users[user].name <string> User name
acl.users[user].owner <boolean> True if the user is the owner of the view
acl.groups <array of <string>> Groups in the access control list
acl.groups[group] <string>

views: Update view acl

Modify access control list for running view {view_id}.

POST https://{device}/api/shark/4.0/views/{view_id}/acl
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "action": string,
  "value": string
}
Property Name Type Description Notes
acl_action <object> Action type on the access list
acl_action.action <string> Action type on the access list Values: ADD_USER, REMOVE_USER, ADD_GROUP, REMOVE_GROUP
acl_action.value <string> User/group name depending on the action type
Response Body

On success, the server does not provide any body in the responses.

watches: List watches

List of watches for view {view_id}.

GET https://{device}/api/shark/4.0/views/{view_id}/watches
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ watch ]
Property Name Type Description Notes
watches <array of <watch>> Watch list
watches[watch] <watch> Instance of a <watch>

watches: Create watch

Create a new watch for view {view_id}.

POST https://{device}/api/shark/4.0/views/{view_id}/watches
Authorization

This request requires authorization.

Request Body

Provide a watch data object.

Response Body

On success, the server does not provide any body in the responses.

watches: Get watch detail

Config information for watch {watch_id} on view {view_id}.

GET https://{device}/api/shark/4.0/views/{view_id}/watches/{watch_id}
Authorization

This request requires authorization.

Response Body

Returns a watch data object.

watches: Update watch

Update configuration for watch {watch_id} on view {view_id}.

PUT https://{device}/api/shark/4.0/views/{view_id}/watches/{watch_id}
Authorization

This request requires authorization.

Request Body

Provide a watch data object.

Response Body

On success, the server does not provide any body in the responses.

watches: Delete watch

Delete watch {watch_id} on view {view_id}.

DELETE https://{device}/api/shark/4.0/views/{view_id}/watches/{watch_id}
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

watches: Disable watch

Disable watch {watch_id} on view {view_id}.

POST https://{device}/api/shark/4.0/views/{view_id}/watches/{watch_id}/disable
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

watches: Enable watch

Enable watch {watch_id} on view {view_id}.

POST https://{device}/api/shark/4.0/views/{view_id}/watches/{watch_id}/enable
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

settings: Get basic settings

Get basic settings.

GET https://{device}/api/shark/4.0/settings/basic
Authorization

This request requires authorization.

Response Body

Returns a basic_settings data object.

settings: Update basic settings

Update basic settings.

PUT https://{device}/api/shark/4.0/settings/basic
Authorization

This request requires authorization.

Request Body

Provide a basic_settings data object.

Response Body

On success, the server does not provide any body in the responses.

settings: Get audit settings

Get audit settings.

GET https://{device}/api/shark/4.0/settings/audit
Authorization

This request requires authorization.

Response Body

Returns an audit_settings data object.

settings: Update audit settings

Update audit settings.

PUT https://{device}/api/shark/4.0/settings/audit
Authorization

This request requires authorization.

Request Body

Provide an audit_settings data object.

Response Body

On success, the server does not provide any body in the responses.

settings: Get authentication settings

Get authentication settings.

GET https://{device}/api/shark/4.0/settings/auth
Authorization

This request requires authorization.

Response Body

Returns an auth_settings data object.

settings: Update authentication settings

Update authentication settings.

PUT https://{device}/api/shark/4.0/settings/auth
Authorization

This request requires authorization.

Request Body

Provide an auth_settings data object.

Response Body

On success, the server does not provide any body in the responses.

settings: Get firewall settings

Get firewall settings.

GET https://{device}/api/shark/4.0/settings/firewall
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "default_policy": string,
  "firewall_enabled": boolean,
  "rules": [
    {
      "description": string,
      "source": string,
      "dest_port": number,
      "protocol": string,
      "action": string
    }
  ]
}
Property Name Type Description Notes
firewall_settings <object> Firewall configuration
firewall_settings.default_policy <string> Firewall default policy Values: ACCEPT, DROP
firewall_settings.firewall_enabled <boolean> Enables or disable the firewall
firewall_settings.rules <array of <object>> Rules list
firewall_settings.rules[rule] <object>
firewall_settings.rules[rule].
description
<string> Rule description Optional
firewall_settings.rules[rule].source <string> Rule IPV4 source address. It can contain a netmasks specified as CIDR format or as IPV4 address. Optional
firewall_settings.rules[rule].dest_port <number> Rule destination port Optional
firewall_settings.rules[rule].protocol <string> Rule protocol Optional; Values: TCP, UDP, ICMP, ALL
firewall_settings.rules[rule].action <string> Rule action, what the firewall should do with the packet when it matches the rule Values: ACCEPT, DROP, LOG_ACCEPT, LOG_DROP

settings: Update firewall settings

Update firewall settings.

PUT https://{device}/api/shark/4.0/settings/firewall
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "default_policy": string,
  "firewall_enabled": boolean,
  "rules": [
    {
      "description": string,
      "source": string,
      "dest_port": number,
      "protocol": string,
      "action": string
    }
  ]
}
Property Name Type Description Notes
firewall_settings <object> Firewall configuration
firewall_settings.default_policy <string> Firewall default policy Values: ACCEPT, DROP
firewall_settings.firewall_enabled <boolean> Enables or disable the firewall
firewall_settings.rules <array of <object>> Rules list
firewall_settings.rules[rule] <object>
firewall_settings.rules[rule].
description
<string> Rule description Optional
firewall_settings.rules[rule].source <string> Rule IPV4 source address. It can contain a netmasks specified as CIDR format or as IPV4 address. Optional
firewall_settings.rules[rule].dest_port <number> Rule destination port Optional
firewall_settings.rules[rule].protocol <string> Rule protocol Optional; Values: TCP, UDP, ICMP, ALL
firewall_settings.rules[rule].action <string> Rule action, what the firewall should do with the packet when it matches the rule Values: ACCEPT, DROP, LOG_ACCEPT, LOG_DROP
Response Body

On success, the server does not provide any body in the responses.

settings: Get profiler export settings

Get profiler export settings.

GET https://{device}/api/shark/4.0/settings/profiler_export
Authorization

This request requires authorization.

Response Body

Returns a profilerexport_settings data object.

settings: Update profiler export settings

Update profiler export settings.

PUT https://{device}/api/shark/4.0/settings/profiler_export
Authorization

This request requires authorization.

Request Body

Provide a profilerexport_settings data object.

Response Body

On success, the server does not provide any body in the responses.

settings: Get snmp settings

Get SNMP settings.

GET https://{device}/api/shark/4.0/settings/snmp
Authorization

This request requires authorization.

Response Body

Returns a snmp_settings data object.

settings: Update snmp settings

Update SNMP settings.

PUT https://{device}/api/shark/4.0/settings/snmp
Authorization

This request requires authorization.

Request Body

Provide a snmp_settings data object.

Response Body

On success, the server does not provide any body in the responses.

settings: Get notification settings

Management daemon configuration parameters.

GET https://{device}/api/shark/4.0/settings/notification
Authorization

This request requires authorization.

Response Body

Returns a notification_settings data object.

settings: Update notification settings

Update management daemon configuration parameters.

PUT https://{device}/api/shark/4.0/settings/notification
Authorization

This request requires authorization.

Request Body

Provide a notification_settings data object.

Response Body

On success, the server does not provide any body in the responses.

settings: List cors domains

List of domains enabled for Cross Origin Resource Sharing.

GET https://{device}/api/shark/4.0/settings/cors_domains
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  string
]
Property Name Type Description Notes
cors_domains <array of <string>> List of CORS (Cross-Origin Resource Sharing) domains
cors_domains[domain] <string>

settings: Update cors domains

Update list of domains enabled for Cross Origin Resource Sharing.

PUT https://{device}/api/shark/4.0/settings/cors_domains
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
[
  string
]
Property Name Type Description Notes
cors_domains <array of <string>> List of CORS (Cross-Origin Resource Sharing) domains
cors_domains[domain] <string>
Response Body

On success, the server does not provide any body in the responses.

settings: Get protocol groups

Get protocol group settings as a text file.

GET https://{device}/api/shark/4.0/settings/protocol_groups
Authorization

This request requires authorization.

Response Body

On success, the server returns a request body containing data with content type text/plain.

settings: Update protocol groups

Update protocol group settings by uploading a text file with the new settings.

PUT https://{device}/api/shark/4.0/settings/protocol_groups
Authorization

This request requires authorization.

Request Body

Provide a request body containing the Text file of protocol group settings. with content type text/plain.

Response Body

On success, the server does not provide any body in the responses.

settings: Get protocol names

Get protocol name settings as a text file.

GET https://{device}/api/shark/4.0/settings/protocol_names
Authorization

This request requires authorization.

Response Body

On success, the server returns a request body containing data with content type text/plain.

settings: Update protocol names

Update protocol name settings by uploading a text file with the new settings.

PUT https://{device}/api/shark/4.0/settings/protocol_names
Authorization

This request requires authorization.

Request Body

Provide a request body containing the Text file of protocol name settings. with content type text/plain.

Response Body

On success, the server does not provide any body in the responses.

settings: Get raw settings

Get advanced settings as a text file.

GET https://{device}/api/shark/4.0/settings/raw
Authorization

This request requires authorization.

Response Body

On success, the server returns a request body containing data with content type text/plain.

settings: Update raw settings

Update advanced settings by uploading a text file with the new settings.

PUT https://{device}/api/shark/4.0/settings/raw
Authorization

This request requires authorization.

Request Body

Provide a request body containing the Text file of protocol name settings. with content type text/plain.

Response Body

On success, the server does not provide any body in the responses.

licenses: List licenses

List licenses on the system.

GET https://{device}/api/shark/4.0/settings/licenses
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ license ]
Property Name Type Description Notes
licenses <array of <license>> List of licenses currently in system
licenses[license] <license> Instance of a <license>

licenses: Add licenses

Add a set of licenses to the system.

POST https://{device}/api/shark/4.0/settings/licenses
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
[
  string
]
Property Name Type Description Notes
licenses <array of <string>> List of license keys to add to the system
licenses[license] <string>
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "key": string,
    "url": string,
    "status": string
  }
]
Property Name Type Description Notes
licenses <array of <object>> List of new licenses added to the system
licenses[license] <object> Description of a new license added to the system
licenses[license].key <string> New license key added to the system
licenses[license].url <string> Resource URI for the new license key
licenses[license].status <string> Status of the new license Values: INVALID, VALID, VALID_SOON, FUTURE, EXPIRED_SOON, EXPIRED, SUPERSEDED, UNKNOWN

licenses: Get license detail

Get information on license {license_key}.

GET https://{device}/api/shark/4.0/settings/licenses/{license_key}
Authorization

This request requires authorization.

Response Body

Returns a license data object.

licenses: Delete license

Delete license {license_key}.

DELETE https://{device}/api/shark/4.0/settings/licenses/{license_key}
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

licenses: Get license status

Get current licensing status of this Shark VE.

GET https://{device}/api/shark/4.0/settings/licenses/status
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "application_status": string,
  "num_profilers": number,
  "profiler_export_capacity": number,
  "packet_storage_size": number,
  "enterprise_pilot_level": number
}
Property Name Type Description Notes
license_status <object> License status information for this Shark VE
license_status.application_status <string> License status for this Shark VE Values: LICENSED_PHYSICAL, LICENSED, UNLICENSED_SOON, UNLICENSED, UNKNOWN
license_status.num_profilers <number> Number of profilers supported for export
license_status.profiler_export_capacity <number> Export capacity (MBPS) for profiler export
license_status.packet_storage_size <number> Packet storage capacity (GB)
license_status.enterprise_pilot_level <number> Enterprise Pilot level

licenses: Generate license request key

Request license request code.

POST https://{device}/api/shark/4.0/settings/licenses/request
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "token": string
}
Property Name Type Description Notes
license_token <object> Submit a new license request
license_token.token <string> License request token (obtained from Riverbed customer support)
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "license_req": string
}
Property Name Type Description Notes
license_request <object>
license_request.license_req <string> License request string (to be submitted to Riverbed customer support)

certificates: List certificates

List of certificates in the Shark.

GET https://{device}/api/shark/4.0/settings/certificates
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "web_certificate": {
    "issued_to": {
      "common_name": string,
      "email": string,
      "organization": string,
      "organization_unit": string,
      "locality": string,
      "state": string,
      "country": string
    },
    "issued_by": {
      "common_name": string,
      "email": string,
      "organization": string,
      "organization_unit": string,
      "locality": string,
      "state": string,
      "country": string
    },
    "validity": {
      "expire": timestamp,
      "issued": timestamp
    },
    "fingerprint": number,
    "key": {
      "algorithm": string,
      "size": number
    },
    "pem": string
  },
  "profiler_export_certificate": {
    "issued_to": {
      "common_name": string,
      "email": string,
      "organization": string,
      "organization_unit": string,
      "locality": string,
      "state": string,
      "country": string
    },
    "issued_by": {
      "common_name": string,
      "email": string,
      "organization": string,
      "organization_unit": string,
      "locality": string,
      "state": string,
      "country": string
    },
    "validity": {
      "expire": timestamp,
      "issued": timestamp
    },
    "fingerprint": number,
    "key": {
      "algorithm": string,
      "size": number
    },
    "pem": string
  },
  "trusted_profilers": [
    {
      "id": string,
      "certificate": {
        "issued_to": {
          "common_name": string,
          "email": string,
          "organization": string,
          "organization_unit": string,
          "locality": string,
          "state": string,
          "country": string
        },
        "issued_by": {
          "common_name": string,
          "email": string,
          "organization": string,
          "organization_unit": string,
          "locality": string,
          "state": string,
          "country": string
        },
        "validity": {
          "expire": timestamp,
          "issued": timestamp
        },
        "fingerprint": number,
        "key": {
          "algorithm": string,
          "size": number
        },
        "pem": string
      }
    }
  ]
}
Property Name Type Description Notes
certificates <object> Certificates info,
certificates.web_certificate <object> Certificate's info
certificates.web_certificate.issued_to <object> Certificate's details
certificates.web_certificate.issued_to.
common_name
<string> Subject's common name
certificates.web_certificate.issued_to.
email
<string> Subject's email
certificates.web_certificate.issued_to.
organization
<string> Subject's organization
certificates.web_certificate.issued_to.
organization_unit
<string> Subject's organization unit
certificates.web_certificate.issued_to.
locality
<string> Subject's locality
certificates.web_certificate.issued_to.
state
<string> Subject's state (2 letters code)
certificates.web_certificate.issued_to.
country
<string> Subject's state
certificates.web_certificate.issued_by <object> Certificate's details
certificates.web_certificate.issued_by.
common_name
<string> Subject's common name
certificates.web_certificate.issued_by.
email
<string> Subject's email
certificates.web_certificate.issued_by.
organization
<string> Subject's organization
certificates.web_certificate.issued_by.
organization_unit
<string> Subject's organization unit
certificates.web_certificate.issued_by.
locality
<string> Subject's locality
certificates.web_certificate.issued_by.
state
<string> Subject's state (2 letters code)
certificates.web_certificate.issued_by.
country
<string> Subject's state
certificates.web_certificate.validity <object> Certificate's validity info
certificates.web_certificate.validity.
expire
<timestamp> Expire date timestamp in Unix time format Seconds since January 1, 1970
certificates.web_certificate.validity.
issued
<timestamp> Issueing date timestamp in Unix time format Seconds since January 1, 1970
certificates.web_certificate.fingerprint <number> Certificate's fingerprint info
certificates.web_certificate.key <object> Contains information about the certificate's key
certificates.web_certificate.key.
algorithm
<string> Key algorithm Values: RSA
certificates.web_certificate.key.size <number> Key length
certificates.web_certificate.pem <string> Contains the certificate in PEM format encode with Base64. This field contains only the public part of the certificate.
certificates.profiler_export_certificate <object> Certificate's info
certificates.profiler_export_certificate.
issued_to
<object> Certificate's details
certificates.profiler_export_certificate.
issued_to.common_name
<string> Subject's common name
certificates.profiler_export_certificate.
issued_to.email
<string> Subject's email
certificates.profiler_export_certificate.
issued_to.organization
<string> Subject's organization
certificates.profiler_export_certificate.
issued_to.organization_unit
<string> Subject's organization unit
certificates.profiler_export_certificate.
issued_to.locality
<string> Subject's locality
certificates.profiler_export_certificate.
issued_to.state
<string> Subject's state (2 letters code)
certificates.profiler_export_certificate.
issued_to.country
<string> Subject's state
certificates.profiler_export_certificate.
issued_by
<object> Certificate's details
certificates.profiler_export_certificate.
issued_by.common_name
<string> Subject's common name
certificates.profiler_export_certificate.
issued_by.email
<string> Subject's email
certificates.profiler_export_certificate.
issued_by.organization
<string> Subject's organization
certificates.profiler_export_certificate.
issued_by.organization_unit
<string> Subject's organization unit
certificates.profiler_export_certificate.
issued_by.locality
<string> Subject's locality
certificates.profiler_export_certificate.
issued_by.state
<string> Subject's state (2 letters code)
certificates.profiler_export_certificate.
issued_by.country
<string> Subject's state
certificates.profiler_export_certificate.
validity
<object> Certificate's validity info
certificates.profiler_export_certificate.
validity.expire
<timestamp> Expire date timestamp in Unix time format Seconds since January 1, 1970
certificates.profiler_export_certificate.
validity.issued
<timestamp> Issueing date timestamp in Unix time format Seconds since January 1, 1970
certificates.profiler_export_certificate.
fingerprint
<number> Certificate's fingerprint info
certificates.profiler_export_certificate.
key
<object> Contains information about the certificate's key
certificates.profiler_export_certificate.
key.algorithm
<string> Key algorithm Values: RSA
certificates.profiler_export_certificate.
key.size
<number> Key length
certificates.profiler_export_certificate.
pem
<string> Contains the certificate in PEM format encode with Base64. This field contains only the public part of the certificate.
certificates.trusted_profilers <array of <object>> List of Trusted Profiler certificates
certificates.trusted_profilers
[trusted_profiler]
<object> Contains Trusted Profilers certificates info
certificates.trusted_profilers
[trusted_profiler].id
<string> ID associated with the Trusted Profiler certificate
certificates.trusted_profilers
[trusted_profiler].certificate
<object> Certificate's info
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to
<object> Certificate's details
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to.common_name
<string> Subject's common name
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to.email
<string> Subject's email
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to.organization
<string> Subject's organization
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to.organization_unit
<string> Subject's organization unit
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to.locality
<string> Subject's locality
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to.state
<string> Subject's state (2 letters code)
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_to.country
<string> Subject's state
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by
<object> Certificate's details
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by.common_name
<string> Subject's common name
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by.email
<string> Subject's email
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by.organization
<string> Subject's organization
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by.organization_unit
<string> Subject's organization unit
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by.locality
<string> Subject's locality
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by.state
<string> Subject's state (2 letters code)
certificates.trusted_profilers
[trusted_profiler].certificate.
issued_by.country
<string> Subject's state
certificates.trusted_profilers
[trusted_profiler].certificate.
validity
<object> Certificate's validity info
certificates.trusted_profilers
[trusted_profiler].certificate.
validity.expire
<timestamp> Expire date timestamp in Unix time format Seconds since January 1, 1970
certificates.trusted_profilers
[trusted_profiler].certificate.
validity.issued
<timestamp> Issueing date timestamp in Unix time format Seconds since January 1, 1970
certificates.trusted_profilers
[trusted_profiler].certificate.
fingerprint
<number> Certificate's fingerprint info
certificates.trusted_profilers
[trusted_profiler].certificate.key
<object> Contains information about the certificate's key
certificates.trusted_profilers
[trusted_profiler].certificate.key.
algorithm
<string> Key algorithm Values: RSA
certificates.trusted_profilers
[trusted_profiler].certificate.key.
size
<number> Key length
certificates.trusted_profilers
[trusted_profiler].certificate.pem
<string> Contains the certificate in PEM format encode with Base64. This field contains only the public part of the certificate.

certificates: Update profiler export certificate

Upload a new profiler export certificate.

PUT https://{device}/api/shark/4.0/settings/certificates/profiler_export
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "pem": string
}
Property Name Type Description Notes
certificate <object> Validity days for the new self signed certificate
certificate.pem <string> Contains the certificate in PEM format encode with Base64. This field contains both the public and private part of the new certificate.
Response Body

On success, the server does not provide any body in the responses.

certificates: Update web UI certificate

Upload a new web UI certificate.

PUT https://{device}/api/shark/4.0/settings/certificates/web
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "pem": string
}
Property Name Type Description Notes
certificate <object> Validity days for the new self signed certificate
certificate.pem <string> Contains the certificate in PEM format encode with Base64. This field contains both the public and private part of the new certificate.
Response Body

On success, the server does not provide any body in the responses.

certificates: Generate profiler export certificate

Request generation of new self-signed certificate and private key for profiler export

POST https://{device}/api/shark/4.0/settings/certificates/profiler_export/generate
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "issued_to": {
    "email": string,
    "organization": string,
    "organization_unit": string,
    "locality": string,
    "state": string,
    "country": string
  },
  "validity": {
    "days": number
  }
}
Property Name Type Description Notes
certificate_info <object> Contains info used to generate a new self signed certificate (only for Web Server and Profiler Export certificates)
certificate_info.issued_to <object> Contains data to generate a new self-signed certificate
certificate_info.issued_to.email <string> Subject's email
certificate_info.issued_to.organization <string> Subject's organization
certificate_info.issued_to.
organization_unit
<string> Subject's organization unit
certificate_info.issued_to.locality <string> Subject's locality
certificate_info.issued_to.state <string> Subject's state (2 letters code)
certificate_info.issued_to.country <string> Subject's country
certificate_info.validity <object> Validity days for a new self signed certificate
certificate_info.validity.days <number> Validity days for a new self signed certificate
Response Body

On success, the server does not provide any body in the responses.

certificates: Generate web UI certificate

Request generation of new self-signed certificate and private key for the web UI

POST https://{device}/api/shark/4.0/settings/certificates/web/generate
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "issued_to": {
    "email": string,
    "organization": string,
    "organization_unit": string,
    "locality": string,
    "state": string,
    "country": string
  },
  "validity": {
    "days": number
  }
}
Property Name Type Description Notes
certificate_info <object> Contains info used to generate a new self signed certificate (only for Web Server and Profiler Export certificates)
certificate_info.issued_to <object> Contains data to generate a new self-signed certificate
certificate_info.issued_to.email <string> Subject's email
certificate_info.issued_to.organization <string> Subject's organization
certificate_info.issued_to.
organization_unit
<string> Subject's organization unit
certificate_info.issued_to.locality <string> Subject's locality
certificate_info.issued_to.state <string> Subject's state (2 letters code)
certificate_info.issued_to.country <string> Subject's country
certificate_info.validity <object> Validity days for a new self signed certificate
certificate_info.validity.days <number> Validity days for a new self signed certificate
Response Body

On success, the server does not provide any body in the responses.

certificates: Copy web UI certificate for profiler export

Request that web UI certificate be reused for profiler export.

POST https://{device}/api/shark/4.0/settings/certificates/profiler_export/copy_web
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

certificates: Copy profiler export certificate for web UI

Request that profiler export certificate be reused for the web UI.

POST https://{device}/api/shark/4.0/settings/certificates/web/copy_profiler_export
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

certificates: Upload trusted profiler certificate

Upload a new trusted profiler certificate

POST https://{device}/api/shark/4.0/settings/certificates/trusted_profilers
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "id": string,
  "pem": string
}
Property Name Type Description Notes
trusted_profiler <object> Used to upload a new trusted profiler certificate
trusted_profiler.id <string> ID associated with the new Trusted Profiler certificate
trusted_profiler.pem <string> Contains the certificate in PEM format encode with Base64. This field contains only the public part of the certificate.
Response Body

On success, the server does not provide any body in the responses.

certificates: Delete trusted profiler certificate

Delete trusted profiler certificate {certificate_id}.

DELETE https://{device}/api/shark/4.0/settings/certificates/trusted_profilers/{certificate_id}
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

users / groups: List groups

List local user groups defined for this Shark

GET https://{device}/api/shark/4.0/auth/groups
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ group ]
Property Name Type Description Notes
groups <array of <group>> List of groups
groups[group] <group> Instance of a <group>

users / groups: Create group

Create a new local user group

POST https://{device}/api/shark/4.0/auth/groups
Authorization

This request requires authorization.

Request Body

Provide a group data object.

Response Body

On success, the server does not provide any body in the responses.

users / groups: Get group detail

Retrieve a user group

GET https://{device}/api/shark/4.0/auth/groups/{group_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
group_id <string> Group identifier
Response Body

Returns a group data object.

users / groups: Delete group

Delete an existing user group

DELETE https://{device}/api/shark/4.0/auth/groups/{group_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
group_id <string> Group identifier
Response Body

On success, the server does not provide any body in the responses.

users / groups: List users

List of local users

GET https://{device}/api/shark/4.0/auth/users
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[ user ]
Property Name Type Description Notes
users <array of <user>> List of users
users[user] <user> Instance of a <user>

users / groups: Create user

Create new local user

POST https://{device}/api/shark/4.0/auth/users
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "name": string,
  "can_be_locked": boolean,
  "password": string,
  "groups": [
    string
  ]
}
Property Name Type Description Notes
user <object> Information to create a new user
user.name <string> User name
user.can_be_locked <boolean> 'true' if user can get locked, 'false' otherwise
user.password <string> User password
user.groups <array of <string>> List of groups of which the user is a member
user.groups[group] <string>
Response Body

On success, the server does not provide any body in the responses.

users / groups: Get users detail

Get info on local user

GET https://{device}/api/shark/4.0/auth/users/{user_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
user_id <string> User identifier
Response Body

Returns a user data object.

users / groups: Update user password

Update password for local user

PUT https://{device}/api/shark/4.0/auth/users/{user_id}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
user_id <string> User identifier
Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "new_password": string,
  "existing_password": string
}
Property Name Type Description Notes
password <object> Updates user password
password.new_password <string> New password
password.existing_password <string> Existing password Optional
Response Body

On success, the server does not provide any body in the responses.

users / groups: Delete user

Delete local user

DELETE https://{device}/api/shark/4.0/auth/users/{user_id}
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

users / groups: Update user locked state

Update locked status of user [USER_ID]

PUT https://{device}/api/shark/4.0/auth/users/{user_id}/locked
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
user_id <string> User identifier
Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "value": boolean
}
Property Name Type Description Notes
locked <object> Unlock a locked user
locked.value <boolean> 'false' to unlock a locked user. 'true' value not supported as you cannot lock an unlocked user.
Response Body

On success, the server does not provide any body in the responses.

ping: Ping (GET)

Generic ping response.

GET https://{device}/api/shark/4.0/ping
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
}
Property Name Type Description Notes
ping <object>

ping: Ping (POST)

Test availability of POST method.

POST https://{device}/api/shark/4.0/ping
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

ping: Ping (PUT)

Test availability of PUT method.

PUT https://{device}/api/shark/4.0/ping
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

ping: Ping (DELETE)

Test availability of DELETE method.

DELETE https://{device}/api/shark/4.0/ping
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

info: List supported tap types

List of supported tap types

GET https://{device}/api/shark/4.0/info/tap_types
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "type": string,
    "type_pretty": string,
    "description": string
  }
]
Property Name Type Description Notes
tap_types <array of <object>>
tap_types[tap_type] <object>
tap_types[tap_type].type <string> Values: NONE, CPACKET, GIGAMON_HEADER, GIGAMON_TRAILER, GIGAMON_TRAILER_X12, VSS, VSS_PORT_ID, UNKNOWN
tap_types[tap_type].type_pretty <string>
tap_types[tap_type].description <string>

info: Get job defaults

List of capture job defaults

GET https://{device}/api/shark/4.0/info/job_defaults
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "snap_length": number,
  "retention_size_limit": number,
  "retention_size_pct": number,
  "index_size_limit": number,
  "index_size_pct": number,
  "job_name": string
}
Property Name Type Description Notes
job_defaults <object> Default values for a new capture job
job_defaults.snap_length <number> Default snap length
job_defaults.retention_size_limit <number> Default size limit (bytes) on retained capture job
job_defaults.retention_size_pct <number> Default max percent of disk for retained capture job
job_defaults.index_size_limit <number> Default size limit (bytes) of index for new capture job
job_defaults.index_size_pct <number> Default max percent of disk for index
job_defaults.job_name <string> Default name of new job

info: List supported data types

List of supported Shark data types in views

GET https://{device}/api/shark/4.0/info/types
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "name": string,
    "calculations": [
      string
    ]
  }
]
Property Name Type Description Notes
types <array of <object>> List of supported Shark types
types[type] <object> Information for one Shark type
types[type].name <string> Shark type ID Values: NONE, PROTOCOL, BOOLEAN, UINT8, UINT16, UINT24, UINT32, UINT64, INT8, INT16, INT24, INT32, INT64, FLOAT, DOUBLE, ABSOLUTE_TIME, RELATIVE_TIME, STRING, STRINGZ, SHORT_STRING, UINT_STRING, ETHER, BYTES, UINT_BYTES, IPv4, IPv6, UDP_PORT, TCP_PORT, IPXNET, FRAMENUM, PCRE, GUID, OID, NUM_TYPES, INDEX, EUI64
types[type].calculations <array of <string>> List of Shark calculations
types[type].calculations[calculation] <string> Values: NONE, SUM, MAX, MIN, AVG, TIME_AVG

info: List supported extractor fields

List of supported Shark view extractor fields

GET https://{device}/api/shark/4.0/info/fields
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "name": string,
    "type": string,
    "id": string,
    "group": string,
    "display_type": string,
    "description": string,
    "multi_segment": boolean,
    "index_calculations": [
      string
    ],
    "dimension": boolean,
    "index": boolean
  }
]
Property Name Type Description Notes
fields <array of <object>>
fields[field] <object>
fields[field].name <string>
fields[field].type <string> Values: NONE, PROTOCOL, BOOLEAN, UINT8, UINT16, UINT24, UINT32, UINT64, INT8, INT16, INT24, INT32, INT64, FLOAT, DOUBLE, ABSOLUTE_TIME, RELATIVE_TIME, STRING, STRINGZ, SHORT_STRING, UINT_STRING, ETHER, BYTES, UINT_BYTES, IPv4, IPv6, UDP_PORT, TCP_PORT, IPXNET, FRAMENUM, PCRE, GUID, OID, NUM_TYPES, INDEX, EUI64
fields[field].id <string>
fields[field].group <string>
fields[field].display_type <string> Optional; Values: NONE, DEC, HEX, OCT, DEC_HEX, HEX_DEC, PERC
fields[field].description <string> Optional
fields[field].multi_segment <boolean> Optional
fields[field].index_calculations <array of <string>> Optional
fields[field].index_calculations
[index_calculation]
<string> Values: NONE, SUM, MAX, MIN, AVG, TIME_AVG
fields[field].dimension <boolean> Optional
fields[field].index <boolean> Optional

info: List supported file extensions

List of Shark file extensions

GET https://{device}/api/shark/4.0/info/file_extensions
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "description": string,
    "value": string
  }
]
Property Name Type Description Notes
file_extensions <array of <object>>
file_extensions[file_extension] <object>
file_extensions[file_extension].
description
<string>
file_extensions[file_extension].value <string>

info: List mac vendors

List of supported MAC vendors (NOTE: This is a long listing.)

GET https://{device}/api/shark/4.0/info/mac_vendors
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
[
  {
    "code": string,
    "name": string
  }
]
Property Name Type Description Notes
mac_vendors <array of <object>>
mac_vendors[mac_vendor] <object>
mac_vendors[mac_vendor].code <string>
mac_vendors[mac_vendor].name <string>

info: List timezones

List of supported timezones

GET https://{device}/api/shark/4.0/info/timezones
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "selected": string,
  "timezones": [
    string
  ]
}
Property Name Type Description Notes
timezone_config <object>
timezone_config.selected <string>
timezone_config.timezones <array of <string>>
timezone_config.timezones[timezone] <string>

system: Get system info

Detailed information about the currently running Shark.

GET https://{device}/api/shark/4.0/system/info
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "hostname": string,
  "version": string,
  "internal_version": string,
  "protocol_version": string,
  "view_version": string,
  "build_time": string,
  "local_time": timestamp-hp,
  "start_time": timestamp-hp,
  "uptime": number,
  "timezone": string,
  "system_type": string,
  "build_type": string,
  "build_variant": string,
  "has_webui": boolean,
  "webui_port": number,
  "webui_SSL": boolean,
  "webui_root_path": string,
  "embedded_wireshark": boolean,
  "default_user_directory": string
}
Property Name Type Description Notes
system_info <object> Information about this Shark
system_info.hostname <string> Host name of this Shark
system_info.version <string> Current version of Shark software
system_info.internal_version <string> Current long-form version of Shark software
system_info.protocol_version <string> Current version of Shark REST API
system_info.view_version <string> Current version of Shark views
system_info.build_time <string> Date and time at which this Shark was built
system_info.local_time <timestamp-hp> Current system time
system_info.start_time <timestamp-hp> Time at which this Shark started
system_info.uptime <number> Elapsed time (in nanoseconds) since this Shark was started
system_info.timezone <string> UTC offset for this Shark
system_info.system_type <string> Operating system on which this Shark is running
system_info.build_type <string> Type of Shark build ('Final' for production, 'Debug' for testing)
system_info.build_variant <string> Variant of Shark build
system_info.has_webui <boolean> 'true' if the web UI is enabled for this build
system_info.webui_port <number> (If web UI is enabled) Port on which web UI can be accessed Optional
system_info.webui_SSL <boolean> (If web UI is enabled) 'true' if web UI uses SSL for transport Optional
system_info.webui_root_path <string> (If web UI is enabled) Root path for web UI resources Optional
system_info.embedded_wireshark <boolean> 'true' if Wireshark is embedded with this Shark Optional
system_info.default_user_directory <string> Default directory for user files Optional

system: Get audit log

Audit log as text file. Response content type is 'text/plain'.

GET https://{device}/api/shark/4.0/system/audit_log
Authorization

This request requires authorization.

Response Body

On success, the server does not provide any body in the responses.

system: Get version info

Version information for the currently running Shark.

GET https://{device}/api/shark/4.0/system/version_info
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "shark_version": string,
  "shark_probe_version": string,
  "protocol_version": string,
  "packet_recorder_version": string,
  "turbocap_api_version": string,
  "turbocap_driver_version": string,
  "serial_number": string
}
Property Name Type Description Notes
version_info <object>
version_info.shark_version <string>
version_info.shark_probe_version <string>
version_info.protocol_version <string>
version_info.packet_recorder_version <string>
version_info.turbocap_api_version <string>
version_info.turbocap_driver_version <string>
version_info.serial_number <string>

system: Get system storage info

Storage monitor status.

GET https://{device}/api/shark/4.0/system/storage
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "can_reinitialize": boolean,
  "state": string,
  "state_type": string,
  "available_space": number,
  "allocated_space": number,
  "total_space": number,
  "used_space": number,
  "disks": [
    {
      "row_id": string,
      "column_id": string,
      "label": string,
      "model": string,
      "serial": string,
      "expected_serial": string,
      "state": string,
      "state_type": string
    }
  ]
}
Property Name Type Description Notes
storage <object>
storage.can_reinitialize <boolean> Optional
storage.state <string>
storage.state_type <string> Values: OK, WARNING, ERROR
storage.available_space <number> Optional
storage.allocated_space <number> Optional
storage.total_space <number> Optional
storage.used_space <number> Optional
storage.disks <array of <object>> Optional
storage.disks[disk] <object>
storage.disks[disk].row_id <string>
storage.disks[disk].column_id <string>
storage.disks[disk].label <string>
storage.disks[disk].model <string>
storage.disks[disk].serial <string>
storage.disks[disk].expected_serial <string> Optional
storage.disks[disk].state <string>
storage.disks[disk].state_type <string> Values: OK, WARNING, ERROR

system: Reinitialize storage system

Request reinitialization of storage subsystem.

POST https://{device}/api/shark/4.0/system/storage/reinitialize
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

system: Format storage system

Request packet storage reformat.

POST https://{device}/api/shark/4.0/system/format_storage
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "reserved_space": number
}
Property Name Type Description Notes
format_storage <object> Configuration information to format the packet storage
format_storage.reserved_space <number> Percentage of unused space at the end of the packet storage
Response Body

On success, the server does not provide any body in the responses.

system: Restart system

Restart the shark service or reboot the system.

POST https://{device}/api/shark/4.0/system/restart
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "type": string
}
Property Name Type Description Notes
restart <object> Configuration to restart
restart.type <string> Type of service to restart Values: SHARK, PROBE, PACKETRECORDER
Response Body

On success, the server does not provide any body in the responses.

system: Shutdown system

Shut down the system.

POST https://{device}/api/shark/4.0/system/shutdown
Authorization

This request requires authorization.

Request Body

Do not provide a request body.

Response Body

On success, the server does not provide any body in the responses.

system: Generate system dump

GET https://{device}/api/shark/4.0/system/sysdump?dump_type={string}&case_id={string}
Authorization

This request requires authorization.

Parameters
Property Name Type Description Notes
dump_type <string> 'CURRENT': Includes current Shark Probe and Shark Packet Recorder logs; 'PROBE': Includes all Shark Probe logs; 'PACKETRECORDER': Includes all Shark Packet Recorder logs; 'COMPLETE': Includes all Shark Probe and Shark Packet Recorder logs. Optional
case_id <string> Optional case ID to be attached to output file name. Optional
Response Body

On success, the server does not provide any body in the responses.

system: Get system update status

Current system update status.

GET https://{device}/api/shark/4.0/system/update
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "state": string,
  "shark_version": string,
  "shark_user_version": string,
  "init_id": string,
  "iso_name": string,
  "iso_size": number,
  "iso_sha_hash": string,
  "update_to": string,
  "update_to_internal": string,
  "pre_start_message": string,
  "estimate": number,
  "executing_job_description": string,
  "comment": string,
  "need_reboot": boolean
}
Property Name Type Description Notes
update <object>
update.state <string> Values: NEUTRAL, INITIALIZING, INITIALIZED, RUNNING, FAILED_GRACEFUL, FAILED_CRITICAL, UNKNOWN
update.shark_version <string>
update.shark_user_version <string>
update.init_id <string> Optional
update.iso_name <string> Optional
update.iso_size <number> Optional
update.iso_sha_hash <string> Optional
update.update_to <string> Optional
update.update_to_internal <string> Optional
update.pre_start_message <string> Optional
update.estimate <number>
update.executing_job_description <string> Optional
update.comment <string> Optional
update.need_reboot <boolean> Optional

system: Modify system update state

Update state of system update.

PUT https://{device}/api/shark/4.0/system/update/state
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "state": string,
  "init_id": string,
  "reset": boolean
}
Property Name Type Description Notes
update_state <object> Request change in update state value on server
update_state.state <string> Values: NEUTRAL, INITIALIZING, INITIALIZED, RUNNING, FAILED_GRACEFUL, FAILED_CRITICAL, UNKNOWN
update_state.init_id <string> Optional
update_state.reset <boolean> Optional
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "state": string,
  "shark_version": string,
  "shark_user_version": string,
  "init_id": string,
  "iso_name": string,
  "iso_size": number,
  "iso_sha_hash": string,
  "update_to": string,
  "update_to_internal": string,
  "pre_start_message": string,
  "estimate": number,
  "executing_job_description": string,
  "comment": string,
  "need_reboot": boolean
}
Property Name Type Description Notes
update <object>
update.state <string> Values: NEUTRAL, INITIALIZING, INITIALIZED, RUNNING, FAILED_GRACEFUL, FAILED_CRITICAL, UNKNOWN
update.shark_version <string>
update.shark_user_version <string>
update.init_id <string> Optional
update.iso_name <string> Optional
update.iso_size <number> Optional
update.iso_sha_hash <string> Optional
update.update_to <string> Optional
update.update_to_internal <string> Optional
update.pre_start_message <string> Optional
update.estimate <number>
update.executing_job_description <string> Optional
update.comment <string> Optional
update.need_reboot <boolean> Optional

system: Upload system update iso

Upload a new ISO file for system update

POST https://{device}/api/shark/4.0/system/update/iso
Authorization

This request requires authorization.

HTTP Headers
Property Name Type Description Notes
Content-Type <string> Content type Must be 'multipart/form-data'
Content-Disposition <string> Name of the file Must be of the form Content-Disposition: form-data; name="iso-file"; filename="[FILENAME]"
Request Body

Provide a request body containing the update ISO file with content type multipart/form-data.

Response Body

On success, the server does not provide any body in the responses.

system: Fetch system update iso

Request fetch of update ISO from a URL

POST https://{device}/api/shark/4.0/system/update/url
Authorization

This request requires authorization.

Request Body

Provide a request body with the following structure:

  • JSON
  • XML
{
  "url": string
}
Property Name Type Description Notes
update_fetch <object>
update_fetch.url <string>
Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "state": string,
  "shark_version": string,
  "shark_user_version": string,
  "init_id": string,
  "iso_name": string,
  "iso_size": number,
  "iso_sha_hash": string,
  "update_to": string,
  "update_to_internal": string,
  "pre_start_message": string,
  "estimate": number,
  "executing_job_description": string,
  "comment": string,
  "need_reboot": boolean
}
Property Name Type Description Notes
update <object>
update.state <string> Values: NEUTRAL, INITIALIZING, INITIALIZED, RUNNING, FAILED_GRACEFUL, FAILED_CRITICAL, UNKNOWN
update.shark_version <string>
update.shark_user_version <string>
update.init_id <string> Optional
update.iso_name <string> Optional
update.iso_size <number> Optional
update.iso_sha_hash <string> Optional
update.update_to <string> Optional
update.update_to_internal <string> Optional
update.pre_start_message <string> Optional
update.estimate <number>
update.executing_job_description <string> Optional
update.comment <string> Optional
update.need_reboot <boolean> Optional

stats: Get memory stats

System memory information.

GET https://{device}/api/shark/4.0/stats/memory
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "status": string,
  "total": number,
  "used": number,
  "available": number,
  "reserved": number,
  "by_category": [
    {
      "name": string,
      "allocations": number,
      "bytes": number
    }
  ],
  "by_handle": [
    {
      "name": string,
      "by_category": [
        {
          "name": string,
          "allocations": number,
          "bytes": number
        }
      ]
    }
  ]
}
Property Name Type Description Notes
memory <object>
memory.status <string> Values: OK, WARNING, CRITICAL, CONFIGURATION_ERROR
memory.total <number>
memory.used <number>
memory.available <number>
memory.reserved <number>
memory.by_category <array of <object>>
memory.by_category[category] <object>
memory.by_category[category].name <string>
memory.by_category[category].allocations <number>
memory.by_category[category].bytes <number>
memory.by_handle <array of <object>>
memory.by_handle[handle] <object>
memory.by_handle[handle].name <string>
memory.by_handle[handle].by_category <array of <object>>
memory.by_handle[handle].by_category
[category]
<object>
memory.by_handle[handle].by_category
[category].name
<string>
memory.by_handle[handle].by_category
[category].allocations
<number>
memory.by_handle[handle].by_category
[category].bytes
<number>

stats: Get storage stats

System storage information.

GET https://{device}/api/shark/4.0/stats/storage
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "packet_storage": {
    "status": string,
    "total": number,
    "reserved": number,
    "allocated": number,
    "unallocated": number,
    "used": number,
    "unused": number
  },
  "os_storage": {
    "status": string,
    "disk_storage": {
      "total": number,
      "used": number,
      "unused": number
    },
    "index_storage": {
      "total": number,
      "allocated": number,
      "unallocated": number,
      "used": number,
      "unused": number
    }
  }
}
Property Name Type Description Notes
storage <object>
storage.packet_storage <object>
storage.packet_storage.status <string> Values: OK, DISK_FULL, CORRUPTED, HW_FAILURE, UNLICENSED, LICENSE_EXCEEDED, UNKNOWN
storage.packet_storage.total <number>
storage.packet_storage.reserved <number>
storage.packet_storage.allocated <number>
storage.packet_storage.unallocated <number>
storage.packet_storage.used <number>
storage.packet_storage.unused <number>
storage.os_storage <object>
storage.os_storage.status <string> Values: OK, WARNING, CRITICAL, UNKNOWN
storage.os_storage.disk_storage <object>
storage.os_storage.disk_storage.total <number>
storage.os_storage.disk_storage.used <number>
storage.os_storage.disk_storage.unused <number>
storage.os_storage.index_storage <object>
storage.os_storage.index_storage.total <number>
storage.os_storage.index_storage.
allocated
<number>
storage.os_storage.index_storage.
unallocated
<number>
storage.os_storage.index_storage.used <number>
storage.os_storage.index_storage.unused <number>

stats: Get profiler export stats

Profiler export information.

GET https://{device}/api/shark/4.0/stats/profiler_export
Authorization

This request requires authorization.

Response Body

On success, the server returns a response body with the following structure:

  • JSON
  • XML
{
  "last_minute": {
    "exported": {
      "flows": number,
      "packets": number,
      "ip_bytes": number
    },
    "rejected": {
      "flows": number,
      "packets": number,
      "ip_bytes": number
    }
  },
  "last_week": {
    "exported": {
      "flows": number,
      "packets": number,
      "ip_bytes": number,
      "average_flows": number,
      "peak_flows": number
    },
    "rejected": {
      "flows": number,
      "packets": number,
      "ip_bytes": number,
      "average_flows": number,
      "peak_flows": number
    }
  }
}
Property Name Type Description Notes
profiler_export_stats <object> Statistics on the Profiler Export
profiler_export_stats.last_minute <object> Statistics on the data exported in the last minute
profiler_export_stats.last_minute.
exported
<object> Values sent to the profiler/s in the last minute
profiler_export_stats.last_minute.
exported.flows
<number> Number of exported flows
profiler_export_stats.last_minute.
exported.packets
<number> Cumulative number of packets for the exported flows
profiler_export_stats.last_minute.
exported.ip_bytes
<number> Cumulative number of IP bytes (IP header included) for the exported flows
profiler_export_stats.last_minute.
rejected
<object> Values analyzed but not sent to the profiler/s in the last minute
profiler_export_stats.last_minute.
rejected.flows
<number> Number of rejected flows
profiler_export_stats.last_minute.
rejected.packets
<number> Cumulative number of packets for the rejected flows
profiler_export_stats.last_minute.
rejected.ip_bytes
<number> Cumulative number of IP bytes (IP header included) for the rejected flows
profiler_export_stats.last_week <object> Statistics on the data exported in the last week
profiler_export_stats.last_week.exported <object> Values sent to the profiler/s in the last week
profiler_export_stats.last_week.exported.
flows
<number> Number of exported flows
profiler_export_stats.last_week.exported.
packets
<number> Cumulative number of packets for the exported flows
profiler_export_stats.last_week.exported.
ip_bytes
<number> Cumulative number of IP bytes (IP header included) for the exported flows
profiler_export_stats.last_week.exported.
average_flows
<number> Average number of flows exported in the last week
profiler_export_stats.last_week.exported.
peak_flows
<number> Max number of flows exported in a minute in the last week
profiler_export_stats.last_week.rejected <object> Values analyzed but not sent to the profiler/s in the last week
profiler_export_stats.last_week.rejected.
flows
<number> Number of rejected flows
profiler_export_stats.last_week.rejected.
packets
<number> Cumulative number of packets for the rejected flows
profiler_export_stats.last_week.rejected.
ip_bytes
<number> Cumulative number of IP bytes (IP header included) for the rejected flows
profiler_export_stats.last_week.rejected.
average_flows
<number> Average number of flows rejected in the last week
profiler_export_stats.last_week.rejected.
peak_flows
<number> Max number of flows rejected in a minute in the last week

Data types

audit_settings

Audit system settings

  • JSON
  • XML
{
  "audit_categories": [
    {
      "name": string,
      "description": string,
      "audit_type": string,
      "min_remote_server_level": string,
      "min_syslog_level": string
    }
  ]
}
Property Name Type Description Notes
audit_settings <object> Audit system settings
audit_settings.audit_categories <array of <object>> List of audit categories
audit_settings.audit_categories
[audit_category]
<object> Information for each audit category
audit_settings.audit_categories
[audit_category].name
<string> Audit category name
audit_settings.audit_categories
[audit_category].description
<string> Description of events captured by this audit category
audit_settings.audit_categories
[audit_category].audit_type
<string> Audit categories Values: AUTHENTICATION, CAPTURE_JOBS, CRYPTOGRAPHY, COMMUNICATIONS, FILE_OPERATIONS, LICENSING, SETTINGS, SYSTEM_OPERATIONS, USER_MANAGEMENT, VIEWS, WATCHES
audit_settings.audit_categories
[audit_category].
min_remote_server_level
<string> Audit levels for each audit category Values: INFO, ERROR, DISABLED
audit_settings.audit_categories
[audit_category].min_syslog_level
<string> Audit levels for each audit category Values: INFO, ERROR, DISABLED

auth_settings

Authentication settings

  • JSON
  • XML
{
  "webui_settings": {
    "need_purpose": boolean,
    "session_duration": number,
    "login_banner": string
  },
  "auth_sequence": [
    string
  ],
  "remote_auth_settings": {
    "default_group": string,
    "fallback_on_unavailable_only": boolean
  },
  "local_settings": {
    "max_unsuccessful_login_attempts": number,
    "min_password_length": number,
    "min_password_upper_letter": number,
    "min_password_lower_letter": number,
    "min_password_numeric_character": number,
    "min_password_special_character": number,
    "password_change_history": number,
    "max_password_lifetime_days": number
  },
  "tacacs_settings": {
    "client_port": string,
    "authorization_attribute": string,
    "authorization_value": string,
    "authorization_response_attribute": string,
    "accounting_enabled": boolean,
    "accounting_attribute": string,
    "accounting_value": string,
    "accounting_terminator": string,
    "servers": [
      {
        "address": string,
        "port": number,
        "shared_secret": string
      }
    ]
  },
  "radius_settings": {
    "client_port": string,
    "encryption_protocol": string,
    "accounting_enabled": boolean,
    "servers": [
      {
        "address": string,
        "port": number,
        "shared_secret": string
      }
    ]
  }
}
Property Name Type Description Notes
auth_settings <object> Authentication settings
auth_settings.webui_settings <object> WebUI configuration settings for this Shark
auth_settings.webui_settings.
need_purpose
<boolean> Enabled if the user should be prompted to specify a purpose during login
auth_settings.webui_settings.
session_duration
<number> Session inactivity timeout In minutes
auth_settings.webui_settings.
login_banner
<string> Login banner
auth_settings.auth_sequence <array of <string>> List of authentication mechanisms used by Shark
auth_settings.auth_sequence[auth_type] <string> Authentication Mode Values: LOCAL, TACACS, RADIUS
auth_settings.remote_auth_settings <object> Additional authentication parameter settings for TACACS+ and RADIUS servers Optional
auth_settings.remote_auth_settings.
default_group
<string> Default group used for remote authentication
auth_settings.remote_auth_settings.
fallback_on_unavailable_only
<boolean> 'true' fallbacks to the next authentication mechanism if TACACS+ or RADIUS servers are unavailable, 'false' otherwise
auth_settings.local_settings <object> Local authentication type parameters
auth_settings.local_settings.
max_unsuccessful_login_attempts
<number> Number of unsuccessful attempts before user is locked out
auth_settings.local_settings.
min_password_length
<number> Minimum password length
auth_settings.local_settings.
min_password_upper_letter
<number> Minimum number of upper-case letters
auth_settings.local_settings.
min_password_lower_letter
<number> Minimum number of lower-case letters
auth_settings.local_settings.
min_password_numeric_character
<number> Minimum number of numeric characters
auth_settings.local_settings.
min_password_special_character
<number> Minimum number of special characters
auth_settings.local_settings.
password_change_history
<number> Number of previous user passwords stored in history
auth_settings.local_settings.
max_password_lifetime_days
<number> Number of days after which password expires
auth_settings.tacacs_settings <object> TACACS+ authentication configuration
auth_settings.tacacs_settings.
client_port
<string> Client port
auth_settings.tacacs_settings.
authorization_attribute
<string> Authorization attribute
auth_settings.tacacs_settings.
authorization_value
<string> Authorization value
auth_settings.tacacs_settings.
authorization_response_attribute
<string> Authorization response attribute. If set to '*', only the first attribute-value pair returned by the server will be considered during authorization.
auth_settings.tacacs_settings.
accounting_enabled
<boolean> 'true' to enable TACACS+ accounting, 'false' otherwise
auth_settings.tacacs_settings.
accounting_attribute
<string> Acccounting attribute
auth_settings.tacacs_settings.
accounting_value
<string> Accounting value
auth_settings.tacacs_settings.
accounting_terminator
<string> Accounting terminator
auth_settings.tacacs_settings.servers <array of <object>> List of server mappings
auth_settings.tacacs_settings.servers
[server]
<object>
auth_settings.tacacs_settings.servers
[server].address
<string> IP Address
auth_settings.tacacs_settings.servers
[server].port
<number> Port number
auth_settings.tacacs_settings.servers
[server].shared_secret
<string> Shared secret key
auth_settings.radius_settings <object> RADIUS authentication configuration
auth_settings.radius_settings.
client_port
<string> Client port
auth_settings.radius_settings.
encryption_protocol
<string> Encryption protocol Values: PAP, CHAP, MSCHAP1, MSCHAP2
auth_settings.radius_settings.
accounting_enabled
<boolean> 'true' to enable RADIUS accounting, 'false' otherwise
auth_settings.radius_settings.servers <array of <object>> List of server mappings
auth_settings.radius_settings.servers
[server]
<object>
auth_settings.radius_settings.servers
[server].address
<string> IP Address
auth_settings.radius_settings.servers
[server].port
<number> Port number
auth_settings.radius_settings.servers
[server].shared_secret
<string> Shared secret key

basic_settings

Basic Shark configuration options

  • JSON
  • XML
{
  "hostname": string,
  "domain": string,
  "primary_dns": string,
  "secondary_dns": string,
  "ssh_enabled": boolean,
  "fips_enabled": boolean,
  "timezone": string,
  "ntp_config": {
    "profiler_mode": boolean,
    "servers": [
      string
    ]
  },
  "mgmt_ports": [
    {
      "interface": string,
      "enabled": boolean,
      "dhcp": boolean,
      "ip_address": string,
      "netmask": string,
      "gateway": string
    }
  ]
}
Property Name Type Description Notes
basic_settings <object> Basic Shark configuration options
basic_settings.hostname <string> Shark host name
basic_settings.domain <string> Network domain
basic_settings.primary_dns <string> Primary DNS server
basic_settings.secondary_dns <string> Secondary DNS server Optional
basic_settings.ssh_enabled <boolean> 'true' if SSH access to this shark is enabled, 'false' otherwise
basic_settings.fips_enabled <boolean> 'true' if FIPS mode is enabled, 'false' otherwise
basic_settings.timezone <string> Time zone (from IANA Time Zone Database) of this Shark
basic_settings.ntp_config <object> Shark NTP Configuration
basic_settings.ntp_config.profiler_mode <boolean> 'true' if Profiler acts as NTP server, 'false' otherwise
basic_settings.ntp_config.servers <array of <string>> List of NTP Servers
basic_settings.ntp_config.servers
[server]
<string>
basic_settings.mgmt_ports <array of <object>> List of management ports
basic_settings.mgmt_ports[port] <object> Shark management port configuration
basic_settings.mgmt_ports[port].
interface
<string> Interface name
basic_settings.mgmt_ports[port].enabled <boolean> 'true' if enabled, 'false' if disabled Optional
basic_settings.mgmt_ports[port].dhcp <boolean> 'true' if DHCP is enabled on this interface, 'false' otherwise
basic_settings.mgmt_ports[port].
ip_address
<string> IPV4 address for this interface (empty if DHCP is enabled)
basic_settings.mgmt_ports[port].netmask <string> Network mask for this interface (empty of DHCP is enabled)
basic_settings.mgmt_ports[port].gateway <string> Network gateway for this interface (empty if DHCP is enabled)

clip_config

Configuration of a clip

  • JSON
  • XML
{
  "job_id": string,
  "description": string,
  "filters": [
    {
      "type": string,
      "value": string,
      "description": string
    }
  ]
}
Property Name Type Description Notes
clip_config <object> Configuration of a clip
clip_config.job_id <string> Job ID on which the clip is applied Optional
clip_config.description <string> Description of this clip configuration Optional
clip_config.filters <array of <object>> List of clip filters Optional
clip_config.filters[filters] <object> Configuration for a clip filter
clip_config.filters[filters].type <string> Clip configuration filter type Values: TIME, SHARK, BPF, WIRESHARK_DISPLAY
clip_config.filters[filters].value <string> Value of this filter
clip_config.filters[filters].description <string> Description of this filter Optional

clip_status

Status information for a clip

  • JSON
  • XML
{
  "creation_time": timestamp,
  "modification_time": timestamp,
  "estimated_size": number,
  "locked": boolean
}
Property Name Type Description Notes
clip_status <object> Status information for a clip
clip_status.creation_time <timestamp> Clip creation time Optional; Seconds since January 1, 1970
clip_status.modification_time <timestamp> Clip last modified time Optional; Seconds since January 1, 1970
clip_status.estimated_size <number> Estimated size for this clip in packet storage Optional
clip_status.locked <boolean> 'true' if packets and the index for this clip are locked, 'false' otherwise

dimension_restrictions

Specification of dimension restrictions for a watch. Dimension restrictions can be used to narrow down what the watch checks, so that, for example, only some bars in a barchart are observed. If multiple restrictions are present in the list, the server ANDs them.

  • JSON
  • XML
{
  "bool_operator": string,
  "restrictions": [
    {
      "field": string,
      "value": string
    }
  ],
  "sub_restrictions": [ dimension_restrictions ]
}
Property Name Type Description Notes
dimension_restrictions <object> Specification of dimension restrictions for a watch. Dimension restrictions can be used to narrow down what the watch checks, so that, for example, only some bars in a barchart are observed. If multiple restrictions are present in the list, the server ANDs them.
dimension_restrictions.bool_operator <string> The boolean operation to apply: "And" or "Or" Values: NOT_INITIALIZED, AND, OR
dimension_restrictions.restrictions <array of <object>> Restriction list
dimension_restrictions.restrictions
[restriction]
<object>
dimension_restrictions.restrictions
[restriction].field
<string> The dimension field identified by the database column name (e.g. c2 or c5) Column numbering starts with 1 and the field must be a dimension
dimension_restrictions.restrictions
[restriction].value
<string> The matching value
dimension_restrictions.sub_restrictions <array of <dimension_restrictions>> Sub-restriction list
dimension_restrictions.sub_restrictions
[sub_restriction]
<dimension_restrictions> Instance of a <dimension_restrictions>

dir

Directory details

  • JSON
  • XML
{
  "id": string,
  "description": string,
  "created": timestamp,
  "modified": timestamp,
  "files": [ file ],
  "dirs": [ dir ]
}
Property Name Type Description Notes
dir <object> Directory details
dir.id <string> Directory id
dir.description <string> Directory description. It is used when the directory has an alias name. Optional
dir.created <timestamp> Creation time in Unix time format Optional; Seconds since January 1, 1970
dir.modified <timestamp> Modification time in Unix time format Optional; Seconds since January 1, 1970
dir.files <array of <file>> List of files
dir.files[file] <file> Instance of a <file>
dir.dirs <array of <dir>> List of directories
dir.dirs[dir] <dir> Instance of a <dir>

export

Information about an export

  • JSON
  • XML
{
  "id": string,
  "config": export_config,
  "status": export_status
}
Property Name Type Description Notes
export <object> Information about an export
export.id <string> ID of export
export.config <export_config> Configuration of this export
export.status <export_status> Status of this export

export_config

  • JSON
  • XML
{
  "output_filename": string,
  "output_format": string,
  "start_time": timestamp,
  "end_time": timestamp,
  "stop_rule": {
    "size_limit": number,
    "packet_limit": number,
    "time_limit": number
  },
  "filters": [ filter ]
}
Property Name Type Description Notes
export_config <object>
export_config.output_filename <string> If sending packets to file, the filename within the Shark file system Optional
export_config.output_format <string> Output format (PCAP or PCAP-NG) and resolution of packet stream Values: PCAP_US, PCAP_NS, PCAPNG_US, PCAPNG_NS
export_config.start_time <timestamp> Time (seconds from epoch) at which export is to begin Optional; Seconds since January 1, 1970
export_config.end_time <timestamp> Time (seconds from epoch) at which export is to end Optional; Seconds since January 1, 1970
export_config.stop_rule <object> Stop rule for a job Optional
export_config.stop_rule.size_limit <number> Max bytes of packet data Optional
export_config.stop_rule.packet_limit <number> Max number of packets Optional
export_config.stop_rule.time_limit <number> Max time in seconds Optional
export_config.filters <array of <filter>> Collection of filters to apply to packets prior to export Optional
export_config.filters[filter] <filter> Instance of a <filter>

export_status

  • JSON
  • XML
{
  "state": string,
  "bytes_approx": number,
  "creation_time": timestamp-hp,
  "owner": string
}
Property Name Type Description Notes
export_status <object>
export_status.state <string> State of the export Values: UNINITIALIZED, LOADED, PARAMS_LOADED, INITIALIZED, READY, RUNNING, ERRORS, DONE, CLOSING, PAUSED
export_status.bytes_approx <number> For exports from a job, approximate number of bytes in the export Optional
export_status.creation_time <timestamp-hp> Time at which the export was created
export_status.owner <string> User who initiated the export

file

File's details

  • JSON
  • XML
{
  "type": string,
  "id": string,
  "link_type": string,
  "format": string,
  "size": number,
  "created": timestamp,
  "modified": timestamp,
  "linked_sources": [
    {
      "path": string,
      "default_source": boolean,
      "timeskew": number,
      "description": string
    }
  ],
  "index": index_info
}
Property Name Type Description Notes
file <object> File's details
file.type <string> File type Values: MULTISEGMENT_FILE, MERGED_FILE, PCAP_FILE, PCAPNG_FILE, ERF_FILE, UNKNOWN_FILE
file.id <string> File id
file.link_type <string> Link layer type Optional
file.format <string> File time format Optional; Values: PCAP_US, PCAP_NS, PCAPNG_US, PCAPNG_NS, UNKNOWN
file.size <number> File size in bytes Optional
file.created <timestamp> Creation time in Unix time format Optional; Seconds since January 1, 1970
file.modified <timestamp> Modification time in Unix time format Optional; Seconds since January 1, 1970
file.linked_sources <array of <object>> Linked sources details list Optional
file.linked_sources[linked_source] <object>
file.linked_sources[linked_source].path <string> Linked source path. It could be either an absolute path (fs/ID) or a relative path starting from the aggregated file folder.
file.linked_sources[linked_source].
default_source
<boolean> The default source is the reference source in a multisegment file collection and it is used as reference for the time skew calculation Optional
file.linked_sources[linked_source].
timeskew
<number> It is the packets timestamps offset associated with the linked source Optional
file.linked_sources[linked_source].
description
<string> A simple description field associated with the linked source Optional
file.index <index_info> Index info

filter

  • JSON
  • XML
{
  "type": string,
  "value": string,
  "description": string
}
Property Name Type Description Notes
filter <object>
filter.type <string> Filter type Values: TIME, SHARK, BPF, WIRESHARK_DISPLAY, DECRYPT, STATE
filter.value <string> Filter value
filter.description <string> Description, if needed Optional

group

Definition of a user group

  • JSON
  • XML
{
  "name": string,
  "description": string,
  "capabilities": [
    string
  ]
}
Property Name Type Description Notes
group <object> Definition of a user group
group.name <string> Group name
group.description <string> Group description
group.capabilities <array of <string>> Specifies the list of capabilities for the group
group.capabilities[capability] <string> Specifies the capabilities of the group Values: CAPABILITY_ADMINISTRATOR, CAPABILITY_APPLY_VIEWS_ON_FILES, CAPABILITY_APPLY_VIEWS_ON_INTERFACES, CAPABILITY_SHARE_VIEWS, CAPABILITY_CREATE_FILES, CAPABILITY_IMPORT_FILES, CAPABILITY_EXPORT_FILES, CAPABILITY_CREATE_JOBS, CAPABILITY_SCHEDULE_WATCHES, CAPABILITY_ACCESS_PROBE_FILES

index_info

Information for one index

  • JSON
  • XML
{
  "status": string,
  "start_time": timestamp-hp,
  "end_time": timestamp-hp
}
Property Name Type Description Notes
index_info <object> Information for one index
index_info.status <string> Running state of an index Values: OK, RUNNING, ERROR
index_info.start_time <timestamp-hp> First packet timestamp for this index
index_info.end_time <timestamp-hp> Last packet timestamp for this index

interface

Information on a Shark interface

  • JSON
  • XML
{
  "id": string,
  "name": string,
  "description": string,
  "type": string,
  "is_promiscuous_mode": boolean,
  "board": {
    "name": string,
    "type": string,
    "pass_thru": string
  },
  "link": {
    "status": string,
    "type": string,
    "tap_type": string,
    "mac_address": string,
    "is_profiler_export_enabled": boolean,
    "blink_status": string,
    "dedup_status": string,
    "addresses": [
      {
        "address": string,
        "netmask": string,
        "broadcast": string,
        "family": string,
        "destination": string
      }
    ],
    "stats": {
      "bytes_rx": number,
      "packets_rx": number
    },
    "speed_options": [
      {
        "status": string,
        "duplex_type": string,
        "speed_mbps": string
      }
    ]
  },
  "virtual_info": {
    "file_name": string,
    "device_name": string,
    "job_handle": string
  },
  "interface_components": [
    string
  ]
}
Property Name Type Description Notes
interface <object> Information on a Shark interface
interface.id <string> ID of this interface
interface.name <string> Name of this interface
interface.description <string> String describing this interface
interface.type <string> Type of this interface Values: TURBOCAP_ADAPTER, PCAP_ADAPTER, VIRTUAL, BOARD_AGGREGATING, AGGREGATING, UNKNOWN
interface.is_promiscuous_mode <boolean> 'true' if interface is in promiscuous mode, 'false' otherwise Optional
interface.board <object> Information on a physical packet capture board Optional
interface.board.name <string> Name of this board
interface.board.type <string> Type of this board Values: 1G_COPPER, 1G_FIBER, 10G_FIBER, PCAP, UNKNOWN
interface.board.pass_thru <string> Enabled status of pass-thru mode (only supported on 1GB Copper TurboCap cards) Values: ENABLED, DISABLED, NOT_SUPPORTED
interface.link <object> Information on a physical interface link Optional
interface.link.status <string> Indicates whether this link is up or down Optional; Values: UP, DOWN, UNKNOWN
interface.link.type <string> Link layer type of this link Values: NONE, EN10MB, RAW, IEEE802_11, IEEE802_11_RADIO, PPI, PPP_WITH_DIR, LINUX_SLL, C_HDLC, UNKNOWN
interface.link.tap_type <string> Tap type used on this link Values: NONE, CPACKET, GIGAMON_HEADER, GIGAMON_TRAILER, GIGAMON_TRAILER_X12, VSS, VSS_PORT_ID, UNKNOWN
interface.link.mac_address <string> MAC address of this link
interface.link.
is_profiler_export_enabled
<boolean> 'true' if profiler export has been enabled for this link, 'false' otherwise Optional
interface.link.blink_status <string> Indicates 'blink' status for this link Optional; Values: ON, OFF, UNKNOWN
interface.link.dedup_status <string> Indicates whether or not packet deduplication has been enabled for this link Optional; Values: ENABLED, DISABLED, NOT_SUPPORTED
interface.link.addresses <array of <object>> List of link addresses Optional
interface.link.addresses[link_address] <object> Address information for a physical interface
interface.link.addresses[link_address].
address
<string> IP address for this interface
interface.link.addresses[link_address].
netmask
<string> Netmask for this interface
interface.link.addresses[link_address].
broadcast
<string> Broadcast address for this interface
interface.link.addresses[link_address].
family
<string> Protocol family served by this interface
interface.link.addresses[link_address].
destination
<string> Destination address for this interface Optional
interface.link.stats <object> Low-level statistics on traffic over this interface Optional
interface.link.stats.bytes_rx <number> Bytes received
interface.link.stats.packets_rx <number> Packets received
interface.link.speed_options <array of <object>> List of link speed options Optional
interface.link.speed_options
[link_speed_option]
<object> Speed, duplex type, and status of a speed option
interface.link.speed_options
[link_speed_option].status
<string> Status of this link speed option for this interface Optional; Values: SUPPORTED, ENABLED, NEGOTIATED
interface.link.speed_options
[link_speed_option].duplex_type
<string> Duplex type for this speed option Values: HALF, FULL, UNKNOWN
interface.link.speed_options
[link_speed_option].speed_mbps
<string> Throughput for this speed option Values: MBPS_10, MBPS_100, MBPS_1000, MBPS_10000
interface.virtual_info <object> Information on a virtual interface (used internally by Shark) Optional
interface.virtual_info.file_name <string> File name corresponding to virtual interface
interface.virtual_info.device_name <string> Device name corresponding to virtual interface
interface.virtual_info.job_handle <string> If virtual interface is a capture job, handle of the job Optional
interface.interface_components <array of <string>> For aggregating ports, list of physical ports making up the aggregation
interface.interface_components
[component_interface]
<string>

job_config

Configuration information for a job

  • JSON
  • XML
{
  "name": string,
  "interface_name": string,
  "interface_description": string,
  "bpf_filter": string,
  "snap_length": number,
  "start_immediately": boolean,
  "requested_start_time": timestamp,
  "requested_end_time": timestamp,
  "packet_retention": {
    "size_limit": number,
    "packet_limit": number,
    "time_limit": number
  },
  "indexing": {
    "size_limit": number,
    "time_limit": number,
    "synced": boolean
  },
  "stop_rule": {
    "size_limit": number,
    "packet_limit": number,
    "time_limit": number
  }
}
Property Name Type Description Notes
job_config <object> Configuration information for a job
job_config.name <string> Job name
job_config.interface_name <string> Name of interface on which job is collecting packet data
job_config.interface_description <string> Description of interface on which job is collecting packet data Optional
job_config.bpf_filter <string> BPF filter applied to this capture job Optional
job_config.snap_length <number> Packet snap length for this capture job Optional
job_config.start_immediately <boolean> 'true' if job is to start immediately upon creation, 'false' otherwise Optional
job_config.requested_start_time <timestamp> Specific time at which job is to start Optional; Seconds since January 1, 1970
job_config.requested_end_time <timestamp> Specific time at which job is to end Optional; Seconds since January 1, 1970
job_config.packet_retention <object> Packet retention info for a job
job_config.packet_retention.size_limit <number> Max bytes of packet data to be retained
job_config.packet_retention.packet_limit <number> Max number of packets to be retained Optional
job_config.packet_retention.time_limit <number> Time period for which packet data will be retained Optional
job_config.indexing <object> Job index configuration Optional
job_config.indexing.size_limit <number> Max number of bytes for this index Optional
job_config.indexing.time_limit <number> Max time this index can exist Optional
job_config.indexing.synced <boolean> 'true' if index is synced with packet storage Optional
job_config.stop_rule <object> Stop rule for a job Optional
job_config.stop_rule.size_limit <number> Max bytes of packet data Optional
job_config.stop_rule.packet_limit <number> Max number of packets Optional
job_config.stop_rule.time_limit <number> Max time in seconds Optional

job_index_info

  • JSON
  • XML
{
  "status": string,
  "start_time": timestamp-hp,
  "end_time": timestamp-hp,
  "synced_with_job": boolean,
  "size": number
}
Property Name Type Description Notes
job_index_info <object>
job_index_info.status <string> Running state of an index Values: OK, RUNNING, ERROR
job_index_info.start_time <timestamp-hp> Start time of the index
job_index_info.end_time <timestamp-hp> End time of the index
job_index_info.synced_with_job <boolean> Optional
job_index_info.size <number> Size of index on the OS file system Optional

job_status

Status information for a job

  • JSON
  • XML
{
  "state": string,
  "packet_start_time": timestamp-hp,
  "packet_end_time": timestamp-hp,
  "packet_size": number
}
Property Name Type Description Notes
job_status <object> Status information for a job
job_status.state <string> Running state of a capture job Values: ACTIVE, RUNNING, STOPPED, UNKNOWN
job_status.packet_start_time <timestamp-hp> First packet timestamp for this job
job_status.packet_end_time <timestamp-hp> Last packet timestamp for this job
job_status.packet_size <number> Size of this job in packet storage

license

Information for a Shark license

  • JSON
  • XML
{
  "key": string,
  "status": string,
  "is_platform": boolean,
  "feature_name": string,
  "feature_description": string,
  "valid_from": string,
  "valid_to": string
}
Property Name Type Description Notes
license <object> Information for a Shark license
license.key <string> License key for this license
license.status <string> Status of this license Values: INVALID, VALID, VALID_SOON, FUTURE, EXPIRED_SOON, EXPIRED, SUPERSEDED, UNKNOWN
license.is_platform <boolean> 'true' if this is a platform license
license.feature_name <string> Feature covered by this license
license.feature_description <string> Description of feature covered by this license
license.valid_from <string> Date/time (seconds from epoch) at which this license becomes valid (0 if always valid)
license.valid_to <string> Date/time (seconds from epoch) at which this license expires (0 if always valid)

notification_settings

Configuration for email notifications

  • JSON
  • XML
{
  "mail": {
    "from_address": string,
    "to_address": string,
    "smtp_server_address": string,
    "smtp_server_port": number
  },
  "notifier": {
    "enabled": boolean,
    "notifications": [
      {
        "id": string,
        "description": string,
        "enabled": boolean
      }
    ]
  }
}
Property Name Type Description Notes
notification_settings <object> Configuration for email notifications
notification_settings.mail <object> SMTP settings for email notifications Optional
notification_settings.mail.from_address <string> SMTP 'from' setting
notification_settings.mail.to_address <string> SMTP 'to' setting
notification_settings.mail.
smtp_server_address
<string> SMTP server IP address
notification_settings.mail.
smtp_server_port
<number> SMTP server port (defaults to 25) Optional
notification_settings.notifier <object> Email notification settings
notification_settings.notifier.enabled <boolean> 'true' if notifications are enabled, 'false' otherwise
notification_settings.notifier.
notifications
<array of <object>> A list of notification descriptors
notification_settings.notifier.
notifications[notification]
<object>
notification_settings.notifier.
notifications[notification].id
<string> Unique ID for the notification (assigned by the system)
notification_settings.notifier.
notifications[notification].
description
<string> (Optional) Description for the notification Optional
notification_settings.notifier.
notifications[notification].enabled
<boolean> 'true' if notification is enabled, 'false' otherwise

profilerexport_settings

Configuration of the Profiler Export

  • JSON
  • XML
{
  "enabled": boolean,
  "valid_license": boolean,
  "profilers": [
    {
      "address": string,
      "status": {
        "state": string,
        "cause": string
      }
    }
  ],
  "adapter_ports": [
    {
      "enabled": boolean,
      "name": string,
      "description": string,
      "bpf_filter": string,
      "voip_enabled": boolean
    }
  ]
}
Property Name Type Description Notes
profilerexport_settings <object> Configuration of the Profiler Export
profilerexport_settings.enabled <boolean> Enable/disable the Profiler Export
profilerexport_settings.valid_license <boolean> Optional
profilerexport_settings.profilers <array of <object>> List of profilers
profilerexport_settings.profilers
[profiler]
<object> Description of a single profiler
profilerexport_settings.profilers
[profiler].address
<string> Address of a profiler, either IP or full qualified name
profilerexport_settings.profilers
[profiler].status
<object> Information on a profiler connection Optional
profilerexport_settings.profilers
[profiler].status.state
<string> Connection state of a profiler Values: OK, ERROR, DISABLED
profilerexport_settings.profilers
[profiler].status.cause
<string> In case of connection error this field contains the cause Optional
profilerexport_settings.adapter_ports <array of <object>> List of the capture physical ports installed on the appliance
profilerexport_settings.adapter_ports
[adapter_port]
<object> Description of a single physical capture port
profilerexport_settings.adapter_ports
[adapter_port].enabled
<boolean> Enable/disable the export on the capture port
profilerexport_settings.adapter_ports
[adapter_port].name
<string> Name of the capture port, unique on the appliance
profilerexport_settings.adapter_ports
[adapter_port].description
<string> Description of the capture port Optional
profilerexport_settings.adapter_ports
[adapter_port].bpf_filter
<string> BPF filter applied on the traffic captured on the capture port Optional
profilerexport_settings.adapter_ports
[adapter_port].voip_enabled
<boolean> Enable/disable the export of VoIP metrics to profiler

snmp_settings

SNMP configuration for this Shark

  • JSON
  • XML
{
  "enabled": boolean,
  "version": string,
  "location": string,
  "description": string,
  "contact": string,
  "username": string,
  "community": string,
  "security_level": string,
  "authentication": {
    "passphrase": string,
    "protocol": string
  },
  "privacy": {
    "passphrase": string,
    "protocol": string
  }
}
Property Name Type Description Notes
snmp_settings <object> SNMP configuration for this Shark
snmp_settings.enabled <boolean> 'true' if SNMP is enabled, 'false' otherwise
snmp_settings.version <string> SNMP version Values: V1, V2C, V3
snmp_settings.location <string> (Optional) SNMP location string Optional
snmp_settings.description <string> (Optional) SNMP description string Optional
snmp_settings.contact <string> (Optional) SNMP contact string Optional
snmp_settings.username <string> (Required for V3) SNMP user name Optional
snmp_settings.community <string> (Required for V1 and V2C) SNMP community string Optional
snmp_settings.security_level <string> (Required for V3) SNMP security level Optional; Values: NO_AUTH_NO_PRIVACY, AUTH_NO_PRIVACY, AUTH_PRIVACY
snmp_settings.authentication <object> (Required with SNMP authentication) SNMP authentication information Optional
snmp_settings.authentication.passphrase <string> Authentication passphrase (must be at least 8 characters long)
snmp_settings.authentication.protocol <string> Authentication protocol Values: MD5, SHA
snmp_settings.privacy <object> (Required with SNMP privacy) SNMP privacy information Optional
snmp_settings.privacy.passphrase <string> Privacy passphrase (must be at least 8 characters long)
snmp_settings.privacy.protocol <string> Privacy protocol Values: DES, AES

timestamp-hp

High precision timestamp value.

Since REST API clients may have very different needs and capabilitities when it comes to handling high-precision timestamps, the API supports multiple encodings for timestamps with higher precision than a seconds.

The format of a high-precision timestamp value in a request or response object is defined by three attributes: <units>.<precision> <type>

  • units: s, ms, us, ns
  • precision: .ms, .us, .ns (optional)
  • type: string, number (only relevant for JSON)

Here are a few examples:

Format Value XML JSON
s string 1336086278.462862235 1336086278 "1336086278"
s number 1336086278.462862235 1336086278 1336086278
s.ns string 1336086278.462862235 1336086278.462862235 "1336086278.462862235"
s.ns number 1336086278.462862235 1336086278.462862235 1336086278.462862235
s.ms string 1336086278.462862235 1336086278.462 "1336086278.462"
ns string 1336086278.462862235 1336086278462862235 "1336086278462862235"
ns number 1336086278.462862235 1336086278462862235 1336086278462862235

To select a specific timestamp format to be used in the request and response body for any REST API call, the client must indicate the desired format in the X-RBT-High-Precision-Timestamp-Format HTTP Header. The same value applies to both the request and response structures.

For example, to select nanosecond units formatted as a string (for JSON), the header would be specified as X-RBT-High-Precision-Timestamp-Format: ns string.

If the header is not supplied by the client, the default encoding is ns number.

The selection of the type "string" versus "number" is only relevant for JSON (since in XML everything is a string), and the choice depends on the client's particular characteristics. For example, JavaScript can only represent a 53-bit integer value before losing precision. That corresponds to roughly microsecond resolution, so it is not possible to store "ns number" values in a JavaScript integer with full precision, hence a a JavaScript client that requires sub-microsecond precision must use a string encoding and parse the number manually. However, since Python has no such constraints, the easiest encoding to work with would be a nanosecond number.

user

Information about a user account

  • JSON
  • XML
{
  "name": string,
  "is_admin": boolean,
  "is_locked": boolean,
  "can_be_locked": boolean,
  "groups": [
    string
  ]
}
Property Name Type Description Notes
user <object> Information about a user account
user.name <string> User name
user.is_admin <boolean> Indication if the user is an administrator
user.is_locked <boolean> Indication if the user account is locked
user.can_be_locked <boolean> Indication if the user account can be locked
user.groups <array of <string>> List of groups of which the user is a member
user.groups[group] <string>

view

View configuration

  • JSON
  • XML
{
  "info": {
    "title": string,
    "description": string
  },
  "parameters": {
    "sampling_time_msec": number,
    "retention_time_msec": number,
    "autoclose_idle_timeout_msec": number
  },
  "input_source": {
    "path": string,
    "disable_index": boolean,
    "filters": [ filter ]
  },
  "processors": [
    {
      "id": string,
      "keys": [
        {
          "field": string,
          "id": string,
          "default_value": string
        }
      ],
      "metrics": [
        {
          "field": string,
          "operation": string,
          "id": string,
          "default_value": string
        }
      ],
      "filters": [ filter ],
      "outputs": [
        {
          "id": string,
          "fields": [
            {
              "id": string,
              "description": string,
              "operation": string
            }
          ]
        }
      ]
    }
  ],
  "watches": [ watch ],
  "client_config": string
}
Property Name Type Description Notes
view <object> View configuration
view.info <object> View information section Optional
view.info.title <string> View title Optional
view.info.description <string> View description Optional
view.parameters <object> View main configuration parameters section
view.parameters.sampling_time_msec <number> View data sampling time Optional; Default is 1000
view.parameters.retention_time_msec <number> Data retention time: data collected for a view will be deleted after the retention time elapsed Optional; Default is 86400000
view.parameters.
autoclose_idle_timeout_msec
<number> Autoclose timeout: if set, the view will be closed if it is not accessed for a period of time equal to the timeout value Optional; Default is 0
view.input_source <object> Input source configuration
view.input_source.path <string> Path of the source to open Specifies a job, clip, file or live device. Must start with the source type, e.g. fs/admin/trace.pcap or interfaces/tc0
view.input_source.disable_index <boolean> If true, the source will not be allowed to use an index to speed up the processing Optional
view.input_source.filters <array of <filter>> List or filters for this input
view.input_source.filters[filter] <filter> Instance of a <filter>
view.processors <array of <object>> Processors configuration Minimum: 1
view.processors[processor] <object> Processor configuration
view.processors[processor].id <string> Processor Id
view.processors[processor].keys <array of <object>> List of fields that will act as keys in this configuration
view.processors[processor].keys[key] <object>
view.processors[processor].keys[key].
field
<string> Field name according to the Shark syntax
view.processors[processor].keys[key].id <string> Alias that can be given to the field, used as identifier in the output configuration
view.processors[processor].keys[key].
default_value
<string> Default value, if needed Optional
view.processors[processor].metrics <array of <object>> List of fields that will act as metrics in this configuration
view.processors[processor].metrics
[metric]
<object>
view.processors[processor].metrics
[metric].field
<string> Field name according to the Shark syntax
view.processors[processor].metrics
[metric].operation
<string> Calculation done by engine on this field Values: NONE, SUM, MAX, MIN, AVG, TIME_AVG
view.processors[processor].metrics
[metric].id
<string> Alias that can be given to the field, used as identifier in the output configuration
view.processors[processor].metrics
[metric].default_value
<string> Default value, if needed Optional
view.processors[processor].filters <array of <filter>> Filter list for the processor
view.processors[processor].filters
[filter]
<filter> Instance of a <filter>
view.processors[processor].outputs <array of <object>> Output list for the processor
view.processors[processor].outputs
[output]
<object>
view.processors[processor].outputs
[output].id
<string> Output Id
view.processors[processor].outputs
[output].fields
<array of <object>> List of requested fields in the output
view.processors[processor].outputs
[output].fields[field]
<object>
view.processors[processor].outputs
[output].fields[field].id
<string> Id of the field. This is the same of the processor configuration.
view.processors[processor].outputs
[output].fields[field].description
<string> Description, if needed Optional
view.processors[processor].outputs
[output].fields[field].operation
<string> Further output operation, if needed. Notice that using this might reduce performance. Optional; Default is NONE; Values: NONE, AVG, COUNT, MAX, MIN, SUM
view.watches <array of <watch>> Watch list
view.watches[watch] <watch> Instance of a <watch>
view.client_config <string> Client-specific section, not used by Shark Optional; Encoded as CDATA in XML

watch

Watch configuration

  • JSON
  • XML
{
  "watch_uid": string,
  "output_uid": string,
  "enabled": boolean,
  "severity": number,
  "info": {
    "name": string,
    "description": string,
    "group": string
  },
  "validity": {
    "from": {
      "value_type": string,
      "value_us": number
    },
    "to": {
      "value_type": string,
      "value_us": number
    }
  },
  "timing": {
    "sampling_ms": number,
    "interval_ms": number,
    "from": string,
    "time_analysis_mode": string
  },
  "conversation_dimensions": [
    [
      string
    ]
  ],
  "triggers": [
    {
      "uid": string,
      "bool_operator": string,
      "dimension_restrictions": dimension_restrictions,
      "duration_info": {
        "duration_type": string,
        "duration_ms": number
      },
      "repetition_info": {
        "number_of_times": number
      },
      "condition_operator": string,
      "conditions": [
        {
          "field": string,
          "condition_info": {
            "check_type": string,
            "value": string,
            "second_value": string,
            "aggregation_type": string
          }
        }
      ]
    }
  ],
  "actions": {
    "fired_triggers": {
      "bool_operator": string,
      "triggering_mode": string,
      "triggers": [
        string
      ]
    },
    "actions": [
      {
        "uid": string,
        "type": string,
        "side": string,
        "parameters": [
          {
            "name": string,
            "value": string,
            "custom": boolean
          }
        ]
      }
    ]
  }
}
Property Name Type Description Notes
watch <object> Watch configuration
watch.watch_uid <string> Watch Id
watch.output_uid <string> Output Id that the watch refers to
watch.enabled <boolean> True if enabled
watch.severity <number> Severity, specified as an integer number with with syslog convention Optional; Default is 5
watch.info <object> Watch info section
watch.info.name <string> Watch human-friendly name
watch.info.description <string> Watch human-friendly description Optional
watch.info.group <string> Watch group. Can be used to organize the watches. Optional
watch.validity <object> Timing information for the watch. It specifies when the watch must be considered valid and keep under control. Optional
watch.validity.from <object> Watch validity start time. If not specified, Start time will be used.
watch.validity.from.value_type <string> Validity type Values: DEFAULT, NOT_SPECIFIED, START, END, RELATIVE, ABSOLUTE
watch.validity.from.value_us <number> Validity value, can be expressed as the absolute timestamp or relative time span depending on the type
watch.validity.to <object> Watch validity end time. If not specified, End time will be used.
watch.validity.to.value_type <string> Validity type Values: DEFAULT, NOT_SPECIFIED, START, END, RELATIVE, ABSOLUTE
watch.validity.to.value_us <number> Validity value, can be expressed as the absolute timestamp or relative time span depending on the type
watch.timing <object> Information about the window that is considered by the watch during every check
watch.timing.sampling_ms <number> Optional
watch.timing.interval_ms <number> The time interval that the watch will cover. This is the time window that the watch must consider during every check. Optional
watch.timing.from <string> The time interval that the watch will cover Optional; Values: NOT_INITIALIZED, NOW, BEGINNING_OF_VIEW, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR; This is the time window that the watch must consider during every check.
watch.timing.time_analysis_mode <string> Specification of the type of analysis for the data samples Optional; Values: SAMPLE_BY_SAMPLE, AGGREGATED; If SAMPLE_BY_SAMPLE, checks every sample and applies the conditions to it (stripchart style). If AGGREGATED, aggregates per interval_ms to calculate the value for the conditions (barchart style).
watch.conversation_dimensions <array of <array of <string>>> This is used when the watch is supposed to treat two dimensions as if they are part of a single connection. For example, the source and destination ip addresses of a conversation ring. The watch will detect a connection and include the traffic coming from both the senders in a single value to check. Optional
watch.conversation_dimensions
[conversation_group]
<array of <string>>
watch.conversation_dimensions
[conversation_group][field_name]
<string>
watch.triggers <array of <object>> List of the events that are watched. An event is something like "bandwdth bigger than 1000" or "packets for host 1.2.3.4 smaller than 10 for more than a minute".
watch.triggers[trigger] <object>
watch.triggers[trigger].uid <string> The unique identifier of the event
watch.triggers[trigger].bool_operator <string> The boolean operation to apply: "And" or "Or" Values: NOT_INITIALIZED, AND, OR
watch.triggers[trigger].
dimension_restrictions
<dimension_restrictions> The list of dimension restrictions
watch.triggers[trigger].duration_info <object> Information about the amount of time the value crosses the threshold before the event is triggered. If this field is not present, the server event will be triggered after the first sampling interval in which the value is beyond the threshold. The duration must be a multiple of the view sampling time, otherwise the server will return an error. Optional
watch.triggers[trigger].duration_info.
duration_type
<string> Type of duration Values: NOT_INITIALIZED, MORE_THAN, EQUALS
watch.triggers[trigger].duration_info.
duration_ms
<number> The duration time, in milliseconds. This must be a multiple of the view sampling time.
watch.triggers[trigger].repetition_info <object> Information about how many times the treshold needs to be crossed in order for the event to become signaled Optional
watch.triggers[trigger].repetition_info.
number_of_times
<number> How many times the treshold needs to be crossed in order for the event to become signaled
watch.triggers[trigger].
condition_operator
<string> The boolean operation to apply: "And" or "Or" Values: NOT_INITIALIZED, AND, OR
watch.triggers[trigger].conditions <array of <object>> The list of conditions that will have to be validated in order for the event to be satisfied. If multiple conditions are present, the event is satisfied according to the operation value.
watch.triggers[trigger].conditions
[condition]
<object>
watch.triggers[trigger].conditions
[condition].field
<string> The numeric (or non-numeric) value that will be checked against the threshold. Non numeric values can be checked with the Equal, NotEqual and Exists operators. NOTE: the field name refers to the database column name (e.g. c2 or c5) (the base number is 1).
watch.triggers[trigger].conditions
[condition].condition_info
<object> Generic information about this threshold
watch.triggers[trigger].conditions
[condition].condition_info.check_type
<string> The type of check to perform Values: EQUAL, NOT_EQUAL, LESS, LESS_OR_EQUAL, GREATER, GREATER_OR_EQUAL, INSIDE_RANGE, OUTSIDE_RANGE, EXISTS, TOPN_CHANGED
watch.triggers[trigger].conditions
[condition].condition_info.value
<string> The threshold value Optional
watch.triggers[trigger].conditions
[condition].condition_info.
second_value
<string> Second threshold value, when supported (e.g. Inside/Outside range). Optional
watch.triggers[trigger].conditions
[condition].condition_info.
aggregation_type
<string> The type of threshold value Values: VALUE, PERCENTAGE, SUMVALUE, SUMPERCENTAGE, COUNT
watch.actions <object> The actions to be performed when one or more events are signaled. Action examples are: start dumping to disk, create a report, start a view, etc.
watch.actions.fired_triggers <object> The list of events that need to be signaled AT THE SAME TIME in order for the watch actions to run
watch.actions.fired_triggers.
bool_operator
<string> The boolean operation to apply: "And" or "Or" Values: NOT_INITIALIZED, AND, OR
watch.actions.fired_triggers.
triggering_mode
<string> The condition that will cause a line to be considered true Values: ONESHOT, LEADINGEDGE, CONTINUOUS, TRAILINGEDGE, LEADING_AND_TRAILING_EDGE
watch.actions.fired_triggers.triggers <array of <string>> The List of unique ids of the events that need to be signaled
watch.actions.fired_triggers.triggers
[trigger_uid]
<string>
watch.actions.actions <array of <object>> Action list
watch.actions.actions[action] <object>
watch.actions.actions[action].uid <string> Action Id
watch.actions.actions[action].type <string> The type of action. This must correspond to the name of a Shark Probe's action plugin.
watch.actions.actions[action].side <string> Who is in charge of performing the action, either server or client Values: CLIENT, SERVER
watch.actions.actions[action].parameters <array of <object>> Parameter list
watch.actions.actions[action].parameters
[parameter]
<object>
watch.actions.actions[action].parameters
[parameter].name
<string> Parameter name
watch.actions.actions[action].parameters
[parameter].value
<string> Parameter value
watch.actions.actions[action].parameters
[parameter].custom
<boolean> True if it is a custom parameter Optional

Error Codes

In the event that an error occurs while processing a request, the server will respond with appropriate HTTP status code and additional information in the response body:

{
     "error_id":   "{error identifier}",
     "error_text": "{error description}",
     "error_info": {error specific data structure, optional}
}

The table below lists the possible errors and the associated HTTP status codes that may returned.

Error ID HTTP Status Comments
REQUEST_INVALID_INPUT 400 The request is invalid
AUTH_REQUIRED 401 Missing authentication credentials
AUTH_INVALID_CREDENTIALS 401 Invalid user name or password
AUTH_INVALID_SESSION 401 The authentication session has timed out or is invalid
AUTH_EXPIRED_PASSWORD 401 Account password has expired
AUTH_INVALID_CODE 401 The Oauth access code is invalid
AUTH_EXPIRED_TOKEN 401 The Oauth token has expired
AUTH_EXPIRED_CODE 401 The Oauth access code has expired
AUTH_DISABLED_ACCOUNT 403 Account has been disabled
AUTH_FORBIDDEN 403 Account does not have privileges for this request
AUTH_INVALID_TOKEN 403 The Oauth token is invalid
RESOURCE_NOT_FOUND 404 The requested resource was not found
HTTP_INVALID_METHOD 405 The requested method is not supported by this resouce
INTERNAL_ERROR 500 Internal error occurred