Getting Started

To get started create a virtual environment to play in:

$ virtualenv env
$ . env/bin/activate

Inside the virtualenv, install OpenCanary following the instructions in the README.

OpenCanary ships with a default config, which we’ll copy and edit to get started. The config is a single JSON dictionary.

$ opencanaryd --copyconfig
$ $EDITOR ~/.opencanary.conf

In the config file we’ll change device.node_id which must be unique for each instance of opencanaryd, and we’ll configure logger to log alerts to a file.

  "device.node_id": "Your-very-own-unique-name",
  // ...
  "logger": {
    "class": "PyLogger",
    "kwargs": {
      "handlers": {
        "file": {
          "class": "logging.FileHandler",
          "filename": "/var/tmp/opencanary.log"
  // ...

With that in place, we can run the daemon and test that it logs a failed FTP login attempt to the log file.

$ opencanaryd --start
$ ftp localhost
$ cat /var/tmp/opencanary.log
{"dst_host": "", "dst_port": 21, "local_time": "2015-07-20 13:38:21.281259", "logdata": {"PASSWORD": "default", "USERNAME": "admin"}, "logtype": 2000, "node_id": "opencanary-0", "src_host": "", "src_port": 49635}


The tool JQ can be used to check that the config file is well-formed JSON.

$ jq . ~/.opencanary.conf

Run opencanaryd in the foreground to see more error messages.

$ opencanaryd --dev

You may also easily restart the service using,

$ opencanaryd --restart