WARNING: Version 1.0.1 of Packetbeat has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Developer Guide: Adding a New Protocol Protocol Modules »
Elastic Docs ›Packetbeat Reference [1.0.1] ›Developer Guide: Adding a New Protocol

Getting Ready

edit

Getting Ready

edit

Packetbeat is written in Go, so having Go installed and knowing the basics are prerequisites for understanding this guide. But don’t worry if you aren’t a Go expert. Go is a relatively new language, and very few people are experts in it. In fact, several people learned Go by contributing to Packetbeat and libbeat, including the original Packetbeat authors.

You will also need a good understanding of the wire protocol that you want to add support for. For standard protocols or protocols used in open source projects, you can usually find detailed specifications and example source code. Wireshark is a very useful tool for understanding the inner workings of the protocols it supports.

In some cases you can even make use of existing libraries for doing the actual parsing and decoding of the protocol. If the particular protocol has a Go implementation with a liberal enough license, you might be able to use it to parse and decode individual messages instead of writing your own parser.

Before starting, please also read the CONTRIBUTING file on GitHub.

Cloning and Compiling

edit

After you have installed Go and set up the GOPATH environment variable to point to your preferred workspace location, you can clone Packetbeat with the following commands:

$ mkdir -p $GOPATH/src/github.com/elastic
$ cd $GOPATH/src/github.com/elastic
$ git clone https://github.com/elastic/beats.git

Then you can compile it with:

$ cd beats
$ make

Note that the location where you clone is important. If you prefer working outside of the GOPATH environment, you can clone to another directory and only create a symlink to the $GOPATH/src/github.com/elastic/ directory.

Forking and Branching

edit

We recommend the following work flow for contributing to Packetbeat:

  • Fork Beats in GitHub to your own account
  • In the $GOPATH/src/github.com/elastic/beats folder, add your fork as a new remote. For example (replace tsg with your GitHub account): 
$ git remote add tsg git@github.com:tsg/beats.git
  • Create a new branch for your work: 
$ git checkout -b cool_new_protocol
  • Commit as often as you like, and then push to your private fork with: 
$ git push --set-upstream tsg cool_new_protocol
  • When you are ready to submit your PR, simply do so from the GitHub web interface. Feel free to submit your PR early. You can still add commits to the branch after creating the PR. Submitting the PR early gives us more time to provide feedback and perhaps help you with it.

A Note About Dependencies

edit

Packetbeat uses Godep for vendoring its dependencies. The way Godep works is that it copies the source code of all dependencies in the Godep/_workspace folder.

Use godep restore to install vendored dependencies into your GOPATH. This helps with validating code as you type.

If you add a new dependency, you can use godep get to add it to the vendored folder.

« Developer Guide: Adding a New Protocol Protocol Modules »