README.md

   1
   2 Cloudeebus
   3 ==========
   4
   5 Cloudeebus - DBus for the Cloud - is a component which enables calling DBus
   6  methods and registering on DBus signals from Javascript.
   7
   8
   9 Install
  10 -------
  11
  12 ### Installing Cloudeebus from the project root directory:
  13
  14 Cloudeebus will install itself in Python's dist-packages folder. The
  15  cloudeebus.py wrapper shell goes in the executables path.
  16
  17         sudo python setup.py install
  18
  19 See the [Getting Started](https://github.com/01org/cloudeebus/wiki/Getting-started)
  20  section of the [Cloudeebus wiki](https://github.com/01org/cloudeebus/wiki)
  21  for a list of dependencies to install.
  22
  23
  24 ### Running Cloudeebus:
  25
  26 The Cloudeebus server must be run either with credentials and a whitelist to
  27  restrict access to DBus services, or in opendoor mode.
  28
  29         usage: cloudeebus.py [-h] [-v] [-d] [-o] [-p PORT] [-c CREDENTIALS] [-w WHITELIST] [-n NETMASK,IP ADDRESS]
  30
  31         Javascript DBus bridge.
  32
  33         optional arguments:
  34           -h, --help            show this help message and exit
  35           -v, --version         print version and exit
  36           -d, --debug           log debug info on standard output
  37           -o, --opendoor        allow anonymous access to all services
  38           -p PORT, --port PORT  port number
  39           -c CREDENTIALS, --credentials CREDENTIALS
  40                                 path to credentials file
  41           -w WHITELIST , --whitelist  WHITELIST
  42                                 path to whitelist file (which the list of allowed DBus
  43                                 service to use)
  44           -s SERVICELIST, --servicelist SERVICELIST
  45                                 path to servicelist file (which the list of allowed
  46                                 DBus service to create (=agent))
  47           -n NETMASK, --netmask NETMASK
  48                                 netmask,IP filter (comma separated.) eg. : -n
  49                                 127.0.0.1,192.168.2.0/24,10.12.16.0/255.255.255.0
  50
  51
  52 Documentation
  53 -------------
  54
  55   * [Cloudeebus](http://01.org/cloudeebus) project home page on [01.org](http://01.org)
  56   * [Javascript API](https://github.com/01org/cloudeebus/wiki/API) reference.
  57   * [Architecture](https://github.com/01org/cloudeebus/wiki/Architecture) block diagram.
  58
  59
  60 Examples
  61 --------
  62
  63 ### dbus-tools
  64
  65 The /doc/dbus-tools folder contains dbus-send and dbus-register test pages.
  66 Cloudeebus runs in opendoor mode, the dbus-tools pages have no manifest.
  67
  68         cloudeebus.py --debug --opendoor --port=9001 &
  69         firefox ./doc/dbus-tools/dbus-register.html ./doc/dbus-tools/dbus-send.html &
  70
  71 ### sample
  72
  73 The /doc/sample folder contains a working sample using credentials, whitelist and manifest.
  74 Cloudeebus runs with credentials and a whitelist that are matched by the
  75  sample page manifest.
  76
  77         cloudeebus.py --debug --credentials=./doc/sample/CREDENTIALS --whitelist=./doc/sample/WHITELIST &
  78         firefox ./doc/sample/cloudeebus.html &
  79
  80 The sample page is also online as a [live demo](http://01org.github.com/cloudeebus/).
  81
  82 ### agent
  83
  84 The /doc/agent folder contains a working client sample using credentials, whitelist and manifest and
  85 a working service sample using credentials, servicelist and manifest.
  86 One instance of cloudeebus runs with credentials and a whitelist that are matched by the
  87 client page manifest.
  88
  89         cloudeebus.py --debug --credentials=./doc/agent/CREDENTIALS --whitelist=./doc/agent/SAMPLELIST -p 9002 &
  90         firefox ./doc/agent/client.html &
  91
  92 The other instance of cloudeebus runs with credentials and a servicelist that are matched by the
  93 server page manifest.
  94
  95         cloudeebus.py --debug --credentials=./doc/agent/CREDENTIALS --servicelist=./doc/agent/SAMPLELIST -p 9003 &
  96         firefox ./doc/agent/server.html &
  97
  98
  99 Acknowledgements
 100 ----------------
 101
 102 Cloudeebus uses code from the following open-source projects:
 103
 104   * [AutobahnJS](http://autobahn.ws/js) ([MIT](http://opensource.org/licenses/MIT) License)
 105   * [AutobahnPython](http://autobahn.ws/python) ([Apache 2.0](http://opensource.org/licenses/Apache-2.0) License)