OpenCanary
==========

Getting Started
--------------

To get started create a virtual environment to play in:

.. code-block:: sh

   $ virtualenv env
   $ . env/bin/activate

Inside the virtualenv, install OpenCanary following the instructions in the `README <https://github.com/thinkst/opencanary>`_.

OpenCanary ships with a default config, which we'll copy and edit to get started. The config is a single `JSON <https://en.wikipedia.org/wiki/JSON>`_ dictionary.

.. code-block:: sh

   $ 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.

.. code-block:: json

   {
       "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.

.. code-block:: sh

   $ opencanaryd --start
   [...]
   $ ftp localhost
   [...]
   $ cat /var/tmp/opencanary.log
   [...]
   {"dst_host": "127.0.0.1", "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": "127.0.0.1", "src_port": 49635}
   

Troubleshooting
---------------

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

.. code-block:: sh

   $ jq . ~/.opencanary.conf

Run opencanaryd in the foreground to see more error messages.

.. code-block:: sh

   $ opencanaryd --dev

You may also easily restart the service using,

.. code-block:: sh

   $ opencanaryd --restart

