From a241a00452f20e2c511ee9d10c6689a8d63c9ef5 Mon Sep 17 00:00:00 2001 From: Tatjana Dehler Date: Tue, 21 Apr 2020 16:07:21 +0200 Subject: [PATCH] doc/mgr/dashboard: Add troubleshooting guide Fixes: https://tracker.ceph.com/issues/25196 Signed-off-by: Tatjana Dehler --- doc/images/dashboard/invalid-credentials.png | Bin 0 -> 5787 bytes doc/mgr/dashboard.rst | 165 +++++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 doc/images/dashboard/invalid-credentials.png diff --git a/doc/images/dashboard/invalid-credentials.png b/doc/images/dashboard/invalid-credentials.png new file mode 100644 index 0000000000000000000000000000000000000000..abd78b024407c73ae3bc7ef705658a5fe89bb5b9 GIT binary patch literal 5787 zcmX9?by!s0*S&;@%us@ebW3+hiAYL^Fu)+)(jlD+2n;3Q>kQr9U4wLYgMvf1bi+6P zzCZ4{`<~~VXFuoev-e(WebrD?z{jJ&0{{SDNl{h{05G`GHUt+FJ$7-!{Lrr_&WieO z001KS_h10<6msE|JE$2$ z1p5tcTpYF{%a0!yu|LU8Gwd`=(hkE3g9S!Yyhpy>x+cHc1kVI+DTdJDQoU?=4lWP; zNrMS2IbmZSyjcJEKO(d{NJ3yCpMx8-R}%xt6O38nBzNI zUA$Dknic2_sKH9a!O~i?bVOEKvYOI#AL0%eik=bU>Toa+;g;#j(o56DkrLx#Coo_J z=S2Mf2UGXUpLx~BGM;Hy>Qna?AC!v;4xY?=ADH(b?k@+2UMa^OedXzG?&}`d{Wh9* zaM~M7iJE`YwsQaM{tzjmS8nq=ukNp!L9FxvsOK%B-GNfvKQJSt zYf&UCV#lq0t>GvEwa51rx^sD|+QvHsntZ?NZ^_bsP*(+zSmOZu%QO^-glGP&wW^0w z_*JmE+GTqF1BYR?Z}mVkt~RBOsHe84YXW!D>( zk`!*O?Wh>~wliR!EZwE4w;VZ$@^NKDpJpT!2QfQ`4@C{{@YoOb9 zDd3*^b?T74)i!Fu;}5?>@U0i}H|N_=KTafph?G?Se3f!Bx1Fgmky5C*py>LLZzo2E z*XFsKxq{)`yHLIIe4V0_wkP$02Fpj)JSo@bPEsf04|htRkW&Ij+VR@rn{Pr7@0%LW z&$&J*2eUx?6&O?G6YO*^l!94aMwtBM%8 z2imKmw@Je$u%w#1Ul^i@){k->^gije?7{hQW&hXbd4zJMz(zc*|d+8Ux& zxDy%W;OFN(njqI}#-#7#jMOY{4BX0aFo_$hg!y0KwpUDG-E2`f933tq8Vk(*FipAI zE^Y|2<+ZD76rW2Elb6k(r(Fr=6n9C^^Q&H9Quo=))cRmpP zV8JA-{VWn0jpd{}oZexG$BoN;bHDPGGOe=;(D2wuJP5FzA7=zi_78$(L#`tw{N+G} zsmmpeo^R+I6tMx1Zn@jss(3(pZ09VG)O4|qOp6U5pPB|t3d$TevSbt#fD9e>gGt+| zf?*Es-$Q4Su5vyGXStv{j9+V@O#vSx?PTcUM22^j(K)sxY`6z()TkWs|$tuClj zj1k0vDQ`d*Pset=B5YUlR(9&k=*#zMeS2*lFX^8i!ClhFQ@SdPmQDyM>#6;Lb{R7e zAoEyXKyN(hJ4R6Z2mt`}a(&EQK#0IcseqDJv4u;|Jo}omPWi-xTy$(lfUGXHAGB{*X+<&lsG$dx6!+THC0E?USo7&+uFU+zZpmxV3fJ?+ZDug6wduYLj5 z%&9tPhElAAX)j~Ij8MZxSCFG*8SeuyAWG;LRY4|BNE3n`lyjL#dRJ%Un@#6@#hyQV zWAx)nD2yaP$<1pg?)X?)8yV+*9Q8Z>^#f%6>A}%&LwQ#d^HTAKWvu)BAE38OS z%<%-RQ}XmnSuw%Fao=M-)-7DwK}F5I{arDX(Fv(Tu!MC-1CF^s%hxi--|H-FCYqhI~?@vkDmIy7TZsDa4H{wJRGn%U;sRaxh>m4`G0fGMI5?wH<(uI9T-smp%iu7{bI zLz6#u1IS+03XFEOjBNicujK3Bj`t;;{}LwD23?%}5PQ2i+E7DszdX|WMdn{n4LvW1 z;m@l~Nr1jA^UnIin9(5ugW8dr&mkh6J;^PPw%aTpv&A!6Z1$sk;1VD6=*X3>(Hju( zX9)PZxQAHAW<9b>%iT{W99R*!QvOyWDg<}$Q<}9t{vP;4NuZ);e4-nlv2PXYLvy|L z_ujc!j0_1OIWiLafl^N9ABl=$0oR97#sSImFVl)joM{DOka(^af5`=;4y(Uf%g0uL z_J6MwRHzy*vrY1-r@Q*C?0&ADv%FNCv8iy~*YMw#QA0t{-Ql5e`FRN>;moHcj}AFG zD*zven@y;vYfSeW($GQoVSjIZ|1LOJ1gG$awKaD$jb&{o!kV3xk?j{p?C&%!gwuNj z$w^wQLK`WDJ^IAQ7DT^o{B&+{9%PZvFP2DSb9coIs+zJ0FMzc3w!7$CsCe5|X_k)o zap@Yyjc&O|Mw>Hip10`FKMH3ZO`nD~+v(_uq~SO$Gs<|->-nGY8)dg%cIPxBL@)po zNPn6Ur|RNGL_u4eq4y59k=`fYRReu@PWiZ&7sm$2WI24p&p#KHRJgm;f}Z4hG%bBy zZM39{_#Tw}md#t|vROt~=eY@R&{KgK{YcZvT&q5Q+}grJ`Be7FLO#pVx! zCwu$e0&BHvT)4}#=5CJ)+v2_>-7|M1KHXW5^1M!FFcwW8-yYi}R~m2G=%5j){KBfP z952^P%wX#MjvuJmKZC#Z(m8nWhw4G6>eQD#?{Ea)Z$jo2ch>)mIlpLrlZ(<{c`$iH zo2#K?LDej3d2DReXRov%p-Xth1IkiV*38L;%)M(KGT!1pO>H&|c$2=WR~bAIbtO97 zIl2|9nPR=>qd%Z|L-U6~vvS>*4KOj~nAX$PN_sYPK;z(hK|Dak2TJqTFXAz(06ih` zy)l@3w@65{uwpa4{jJUjYhR{=^JDJ)asV3JbScE7y|Sbvw|M?E41}%bfAh((uBZ^~ z&4t){GAXKLFgO1*^zojMF;V^a!*QxuYDJwDIPp!cEGW>}h;8THJNPU;Tb(U$Exy{MxS7_r_Jen=(3;8vfD=Ye~MX ztknDE9w;E$gr-Ppk4(Dh^B@rhC^WC~?Fdp!Jai0k=#`5HL;I z`FX5e7KjUM+{xQI+x&&YHu5dbBi}^j6XBAmS4S=vOrt{~pw9Peh!-~bUu>ap+Yiln z7w|SwuuX6qsubUT_+kC?OME;&TAp>)HA(7VX^C9Y+DFG(`-YT7F8k{EOuYz5jX#Hh ze6(~;G%3c)d04G_CaXhmi^)6#sXKNSpSrhkJS7GGhvuWB@A}SIrL3rkK7<(eGC*;o7qkQCE-F@89k+|auP=nE|l2CH~hsw3N(bb`4xF?4A zdNswqaC%O`;^khYa6{jT|1Ot*6Z(hewf)+x!EKYQGbA=Bp(9`XM`l6M6NbFOLNPZ31kYw3t+^=o`8E?io~Q32R%YmseFu}tTym=MxS5*<%s`c`=$hyO zf(Fj1dBfO1*o5(|S;F;zWu`eI=9`q$;*Cc;Uw7q{I3j?3p-#^GTxBellJld3f4*9I zqnmP)TU#!bG)SEomyWYkqK6rC5S{ZQFn?rOL!UX+Y%T4zkwObcTtD_X!G1UxUH3C) zyOa{E*k2xXHYNB1E3X0=u1uKQ2YKY6tdR?!=IDz8k}CS<=Xq?o0mUYF*rmVIP5o}Z z@uK^=h@>o=&9s=Cd56K0$M`Xt1Zdt6)NfCRi?2yu70*qT{9Qhu!*Tarj= z;S?z$bz5*gvM)|KTP4VKbjWai>hp)9U=;U)Z`Cg90Dhk&*Q1jr6&#xKO>E>DEpQq>3!oK`3Md2B}tGecGK z1%(4x<@6D#>--g?U5 z4_*S^p@CnFm%T8w4?y}GkCTXr##y%n5Ql>!kVs>@@!}8pcj*Y(Ydkr*9zM$DkptT3 zM?sM#(e@`+E`;ICB_($W8=^gDA75KQynXB}&)MGTGbg?hV>#6|>hr&{ms6f4$bpo! z`E)0m(bDL9T$9=hZtz^kjKB74r?X{r!HtcOgcH{uR&cV6EH!Lwz^WL-A)y!$UA+KW z;A68V$9#QnfiA~rYUY{G3Eyr{4;pPd4!&@>KSN{Su!(QFx=oJ}#)5yxESBbI%{_!x zL`}#CLu?CO-a^R8ae^#g-~e`@Lv%i(Wat6WGg^q_`E;m_euKYK&6Vq~yNMA2E3B{= z_V(q&N@lR0u?I)|#ZwM?(hmsn!3-^oFmLtygrb5mXfq}-(Vn4~6}4s9anX@s(H>%bepA;o)dL^v06~h?|)S+qurY#z~4K zjiOw$a#VT$9`4kIrqBB#zV|TNUNL+YNpH?dC=dX(Jb6Q(Lz4a|{5zqEeo+<-q!D zI#SgdIi`x_Z)!qA0)WWZ``gTnP`wjYP+xyzuAi3+WkJl7*5VNh%Hg{DIGpezS2r)1 z(D5$Cl?PBTGMLLwN~R@VSs&XEp`hBi{~4}l<)`{y7YNcUex|r9Vox$R|3V0kQ^YIc zDDCr+&_y9V=uuR)0)b0JjKhklz&#qKokbp>&N*kQ%s5=xtv3p6#NwAZWeB70Gec9Y z13=)?KE<~o-eGT_GCcvJ$0H=?-ozGZn20(qgkg5_MKcxR$=xBb`zgS{m`UsIpgu41(d^lHGd_7DnB>PE+ThmCP z*`tv-NqL76R8}lxCnS^a38-EOeaJK5`-Jj3AS_px(q3O@AGPvj4uB)w>47;<5Lh4i zReVSM3{fI=r1L)aB8R7m8=A+#)hI0T1fq+Y{UYGGBQnNah^B~j$J|`vJ-gu*{Ac%TV z6e+Z}Q?hO5MBDD{aPP5M9|mdi0D=(3dMKHAhwlKOVca&QCH1e7W22a<>b8l;(UG1p zX%O2*9M@!{5q`2KDC_L{#C&=7ci$#lS+ed<4PsDOZZw?AJ5y(G(w?>6Anm-4C|oa8 zcxb~yw|UxNudA_*!P-ZzXo~%Mj~d+TR06e{vct_ByX(9Ti|xIX?U;znEI_>GG-n+^ zms=Uul4iq#HrK25L$ppdivLdE1I_%}d7Crhf)2kIl|!5Atwl`cI;po-eKEq4Xy%HC zUd`GrsNB#H2brSvi?O6%3TVyEAOS6s9MIl>v(!KM`LgK58l%0&LD10@0~l~a+uWQ~ zz(5QY`@Mr9h%XUd72qYDbM^EmF7upUZ|@2=r^$vjqIoJyxn z;nwQ{?zMsE!X64tPGAnq`^58`@z%G)8CKN#^vHki6g?c zI7o9J(|Y#^yw&`&WZs?jq98a@x`l|2je&?Kj8y-Wl>s}e)>NPDpZ|Z7;^#tLS@fa* z$%$Q9Z2XFmxU%-06`Uiy|Fe|iO zRT~owofLGNH3<2i;Q6VPS#UT`@U8VLQ33J|t?ari7%Mk!ms@r+T~sOa%e}>Mu0hj@lYYQ#&WzULU=L4L6Eq+ln%;P9BBssLDZ@_`Wh XW!QC7gIzybSO%2j)MU$KOhWz-3i>s> literal 0 HcmV?d00001 diff --git a/doc/mgr/dashboard.rst b/doc/mgr/dashboard.rst index 5d9cc86f5b23..dc88f36ac4dd 100644 --- a/doc/mgr/dashboard.rst +++ b/doc/mgr/dashboard.rst @@ -1070,3 +1070,168 @@ and loosely coupled fashion. .. include:: dashboard_plugins/feature_toggles.inc.rst .. include:: dashboard_plugins/debug.inc.rst + + +Troubleshooting the Dashboard +----------------------------- + +Locating the Dashboard +^^^^^^^^^^^^^^^^^^^^^^ + +If you are unsure of the location of the Ceph Dashboard, run the following command:: + + $ ceph mgr services | jq .dashboard + "https://host:port" + +The command returns the URL where the Ceph Dashboard is located: ``https://:/`` + +.. note:: + + Many Ceph command line tools return results in JSON format. You may have to install + the `jq `_ command-line JSON processor utility on + your operating system beforehand. + + +Accessing the Dashboard +^^^^^^^^^^^^^^^^^^^^^^^ + +If you are unable to access the Ceph Dashboard, run through the following +commands: + +#. Verify the Ceph Dashboard module is enabled:: + + $ ceph mgr module ls | jq .enabled_modules + + Ensure the Ceph Dashboard module is listed in the return value of the + command. Example snipped output from the command above:: + + [ + "dashboard", + "iostat", + "restful" + ] + +#. If it is not listed, activate the module with the following command:: + + $ ceph mgr module enable dashboard + +#. Check the Ceph Dashboard and/or mgr log file for any errors. The exact + location of the log files depends on the Ceph configuration. + + * Check if mgr log messages are written to a file by:: + + $ ceph config get mgr log_to_file + true + + * Get the location of the log file (it's ``/var/log/ceph/-.log`` + by default):: + + $ ceph config get mgr log_file + /var/log/ceph/$cluster-$name.log + +#. Ensure the SSL/TSL support is configured properly: + + * Check if the SSL/TSL support is enabled:: + + $ ceph config get mgr mgr/dashboard/ssl + + * If the command returns ``true``, verify a certificate exists by:: + + $ ceph config-key get mgr/dashboard/crt + + and:: + + $ ceph config-key get mgr/dashboard/key + + * If it doesn't, run the following command to generate a self-signed + certificate or follow the instructions outlined in + :ref:`dashboard-ssl-tls-support`:: + + $ ceph dashboard create-self-signed-cert + + +Trouble Logging into the Dashboard +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are unable to log into the Ceph Dashboard and you receive the following +error, run through the procedural checks below: + +.. image:: ../images/dashboard/invalid-credentials.png + :align: center + +#. Check that your user credentials are correct. If you are seeing the + notification message above when trying to log into the Ceph Dashboard, it + is likely you are using the wrong credentials. Double check your username + and password, and ensure the caps lock key is not enabled by accident. + +#. If your user credentials are correct, but you are experiencing the same + error, check that the user account exists:: + + $ ceph dashboard ac-user-show + + This command returns your user data. If the user does not exist, it will + print:: + + $ Error ENOENT: User does not exist + +#. Check if the user is enabled:: + + $ ceph dashboard ac-user-show | jq .enabled + true + + Check if ``enabled`` is set to ``true`` for your user. If not the user is + not enabled, run:: + + $ ceph dashboard ac-user-enable + +Please see :ref:`dashboard-user-role-management` for more information. + + +A Dashboard Feature is Not Working +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When an error occurs on the backend, you will usually receive an error +notification on the frontend. Run through the following scenarios to debug. + +#. Check the Ceph Dashboard/mgr logfile(s) for any errors. These can be + identified by searching for keywords, such as *500 Internal Server Error*, + followed by ``traceback``. The end of a traceback contains more details about + what exact error occurred. +#. Check your web browser's Javascript Console for any errors. + + +Ceph Dashboard Logs +^^^^^^^^^^^^^^^^^^^ + +Dashboard Debug Flag +'''''''''''''''''''' + +With this flag enabled, traceback of errors are included in backend responses. + +To enable this flag via the Ceph Dashboard, navigate from *Cluster* to *Manager +modules*. Select *Dashboard module* and click the edit button. Click the +*debug* checkbox and update. + +To enable it via the CLI, run the following command:: + + $ ceph dashboard debug enable + + +Setting Logging Level of Dashboard Module +''''''''''''''''''''''''''''''''''''''''' + +Setting the logging level to debug makes the log more verbose and helpful for +debugging. + +#. Increase the logging level of manager daemons:: + + $ ceph tell mgr config set debug_mgr 20 + +#. Adjust the logging level of the Ceph Dashboard module via the Dashboard or + CLI: + + * Navigate from *Cluster* to *Manager modules*. Select *Dashboard module* + and click the edit button. Modify the ``log_level`` configuration. + * To adjust it via the CLI, run the following command:: + + $ bin/ceph config set mgr mgr/dashboard/log_level debug -- 2.47.3