Quickstart

This quickstart guide will get you Flapjack running in a VM locally using Vagrant and VirtualBox.

You'll also learn the basics of how to:

To skip this tutorial and jump straight to the code, view the project on GitHub.

Getting Flapjack running

Dependencies

Setup

Get the repo, and build your Vagrant box:

git clone https://github.com/flpjck/vagrant-flapjack.git
cd vagrant-flapjack
vagrant up

For an alternative provider to VirtualBox (e.g. VMware Fusion), you can specify the provider when running vagrant up:

vagrant up --provider=vmware_fusion
More information: Check out the vagrant-flapjack project on GitHub.

Verify

Visit http://localhost:3080 from your host workstation. You should see the Flapjack Web UI:

Screenshot of the Flapjack Web UI

You should also find Icinga and Nagios UIs running at:

URL Username Password
http://localhost:3083/nagios3 nagiosadmin nagios
http://localhost:3083/icinga icingaadmin icinga

Get comfortable with the Flapjack CLI

SSH into the VM:

vagrant ssh

Have a look at the commands under /opt/flapjack/bin:

export PATH=$PATH:/opt/flapjack/bin
# ...
flapjack --help
# ...
simulate-failed-check --help
# ...
Details of these commands are available on the Flapjack wiki.

CLI

Simulate a check failure

Run something like:

simulate-failed-check fail-and-recover \
  --entity foo-app-01.example.com \
  --check Sausage \
  --time 3

This will send a stream of critical events for 3 minutes, and send one ok event at the end. If you want the last event to be a failure as well, use the fail command instead of fail-and-recover.

Verify

Reload the Flapjack Web UI and you should now be able to see the status of the check you're simulating, e.g. at:

http://localhost:3080/check?entity=foo-app-01.example.com&check=Sausage

Integrate Flapjack with Nagios (and Icinga)

Both Nagios and Icinga are configured already to append check output data to the following named pipe: /var/cache/icinga/event_stream.fifo.

flapjack-nagios receiver takes check output data from Nagios and turns it into events that Flapjack understands:

Flapjack's architecture

All that remains is to configure flapjack-nagios-receiver to read from this named pipe, configure its Redis connection, and start it up.

sudo /etc/init.d/flapjack-nagios-receiver start

More details on configuration are avilable on the wiki.

Verify

Reload the Flapjack web interface and you should now see the checks from Icinga and/or Nagios appearing there.

Checks

Create some contacts and Entities

Currently Flapjack does not include a friendly web interface for managing contacts and entities, so for now we use json, curl, and the Flapjack API.

The vagrant-flapjack project ships with example json files that you can use in this tutorial, or you can copy and paste the longform curl commands below that include the json.

Create Contacts Ada and Charles

We'll be using the POST /contacts API call to create two contacts.

Run the following from your workstation, cd'd into the vagrant-flapjack directory:

curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/json" \
  -d @examples/contacts_ada_and_charles.json \
  http://localhost:3081/contacts

Or alternatively, copy and paste the following. This does the same thing, but includes the json data inline.

curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/json" -d \
 '{
    "contacts": [
      {
        "id": "21",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "media": {
          "sms": {
            "address": "+61412345678",
            "interval": "3600",
            "rollup_threshold": "5"
          },
          "email": {
            "address": "ada@example.com",
            "interval": "7200",
            "rollup_threshold": null
          }
        },
        "tags": [
          "legend",
          "first computer programmer"
        ]
      },
      {
        "id": "22",
        "first_name": "Charles",
        "last_name": "Babbage",
        "email": "charles@example.com",
        "media": {
          "sms": {
            "address": "+61412345679",
            "interval": "3600",
            "rollup_threshold": "5"
          },
          "email": {
            "address": "charles@example.com",
            "interval": "7200",
            "rollup_threshold": null
          }
        },
        "tags": [
          "legend",
          "polymath"
        ]
      }
    ]
  }' \
 http://localhost:3081/contacts

Navigate to Contacts in the Flapjack web UI and you should see Ada Lovelace and Charles Babbage listed:

Contacts - List

Selecting Ada should give you something like:

Contact - Ada Lovelace

Create entities foo-app-01 and foo-db-01 (.example.com)

We'll be using the POST /entities api call to create two entities.

We're going to assign both Ada and Charles to foo-app-01, and just Ada to foo-db-01.

curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/json" \
  -d @examples/entities_foo-app-01_and_foo-db-01.json \
  http://localhost:3081/entities

Or with json inline if you prefer:

curl -w 'response: %{http_code} \n' -X POST -H "Content-type: application/json" -d \
 '{
    "entities": [
      {
        "id": "801",
        "name": "foo-app-01.example.com",
        "contacts": [
          "21",
          "22"
        ],
        "tags": [
          "foo",
          "app"
        ]
      },
      {
        "id": "802",
        "name": "foo-app-02.example.com",
        "contacts": [
          "21"
        ],
        "tags": [
          "foo",
          "db"
        ]
      }

    ]
  }' \
 http://localhost:3081/entities

Verify

Visit foo-app-01 in the web UI and you should see something like:

Entity - foo-app-01.example.com

Feedback?

Found an error in the above? Please submit a bug report and/or a pull request against the gh-pages branch with the fix.

Something not clear? That's a bug too!

Got questions? Suggestions? Talk to us via irc, mailing list, or twitter. See Support for details.

Coming soon

Stay tuned for more info on how to configure:

In the mean time, check out the API documentation on how to import contacts and entities.