src/ceph/src/pybind/mgr/dashboard/README.rst

   1
   2 =========================
   3 ceph-mgr dashboard module
   4 =========================
   5
   6 Dependencies
   7 ============
   8
   9 On Ubuntu Xenial:
  10
  11 ::
  12
  13     apt-get install python-cherrypy3
  14
  15 On Fedora:
  16
  17 ::
  18
  19     dnf install -y python-cherrypy
  20
  21
  22 If you had already enabled the module, restart ceph-mgr after installing dependencies to reload the module.
  23
  24 Enabling
  25 ========
  26
  27 Enable the module with::
  28
  29   ceph mgr module enable dashboard
  30
  31 You can see currently enabled modules with::
  32
  33   ceph mgr module ls
  34
  35 If you use any other ceph-mgr modules, make sure they're in the list too.
  36
  37 An address where the dashboard will listen on needs to be configured as well, set this to ``::`` to listen on all
  38 IPv4 and IPv6 addresses.
  39
  40 ::
  41
  42     ceph config-key set mgr/dashboard/server_addr ::
  43
  44 Restart the ceph-mgr daemon after modifying the setting to load the module.
  45
  46 Accessing
  47 =========
  48
  49 Point your browser at port 7000 on the server where ceph-mgr is running.
  50
  51 FAQs
  52 ====
  53
  54 Q: Aargh there's no authentication!  Are you crazy?
  55 A: At present this module only serves read-only status information, and it is disabled by default.  Administrators can make a decision
  56    at the point of enabling the module whether they want to limit access to the port, and/or put it behind an authenticating HTTP proxy
  57    such as Apache+digest auth.
  58    A motivated person could totally build in some authentication stuff though: that would probably only be worth the effort at the point
  59    that non-readonly features were added.
  60
  61 Q: Aargh there's no SSL!  Are you crazy?
  62 A: See the authentication question.  You can always configure your own SSL gateway on top of this if you need it.
  63
  64 Q: Why CherryPy?
  65 A: ceph-mgr is a pure CPython environment, which means that anything gevent based doesn't work (gevent relies on C-level hacks).  CherryPy
  66    includes a web server based on standard python threads, making it a convenient choice.  There are other web frameworks of course.
  67
  68 Q: Does this use the `restful` module?
  69 A: No.  This module loads everything it needs directly via the interfaces available to ceph-mgr modules, and sends it straight to your browser.
  70
  71 Q: My browser says "connection refused"
  72 A: Check that you have a running ceph-mgr daemon.  Look in the ceph-mgr log (/var/log/ceph/ceph-mgr...) for errors loading modules.  Check
  73    that you have enabled the module (see "Enabling" above)
  74
  75 Q: My log contains an error like "ImportError: No module named cherrypy"
  76 A: See "Dependencies" above.  Make sure you installed a 3.x version of cherrypy, many distros have multiple cherrypy packages.
  77
  78 Q: I want to add something to the UI, how do I do it?
  79 A: See HACKING.rst
  80