User Modules are a way for you to create and deploy your own custom services to your Canaries. Once deployed, your Canary will listen on the specified port, and once hit, will behave in the way you want it to.
Creating your custom service is quick and can be easily done by following the below steps.
Step 1 - Setup environment
Setup and activate python virtual environment:
- virtualenv usermodenv
- source usermodenv/bin/activate
Next, install canaryusermodule python module:
As of v0.31.0, the python wheel format no longer includes the metadata.json file. The Canary expects this, so the user module will fail to load. This is easily fixed by installing the 0.30.0 version of wheel in your virtual env.
- pip install canaryusermodule wheel==0.30.0
Step 2 - Generate test module and install into virtual env
Generate test module:
- usermodgen HelloTest
Install test module into virtual env:
- cd hellotest
- python setup.py develop
Step 3 - Dev and test module
Test with and watch raw json logs in foreground:
- opencanaryd --usermodule
Hack!, hack!, hack! (Repeat above as desired)
Optional: delete test user module from virtual enviroment:
- pip uninstall -y hellotest
Step 5 - Build and upload
Build test module:
The usermodule will be the *.whl in dist. Upload this to canary.
In order to upload your user module you will need to boot your device into configuration mode.
If you cannot remember how to do that, see this.