ceph/src/common/admin_socket.h

   1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
   2 // vim: ts=8 sw=2 smarttab
   3 /*
   4  * Ceph - scalable distributed file system
   5  *
   6  * Copyright (C) 2011 New Dream Network
   7  *
   8  * This is free software; you can redistribute it and/or
   9  * modify it under the terms of the GNU Lesser General Public
  10  * License version 2.1, as published by the Free Software
  11  * Foundation.  See file COPYING.
  12  *
  13  */
  14
  15 #ifndef CEPH_COMMON_ADMIN_SOCKET_H
  16 #define CEPH_COMMON_ADMIN_SOCKET_H
  17
  18 #if defined(WITH_SEASTAR) && !defined(WITH_ALIEN)
  19 #include "crimson/admin/admin_socket.h"
  20 #else
  21
  22 #include <condition_variable>
  23 #include <mutex>
  24 #include <string>
  25 #include <string_view>
  26 #include <thread>
  27
  28 #include "include/buffer.h"
  29 #include "include/common_fwd.h"
  30 #include "common/ref.h"
  31 #include "common/cmdparse.h"
  32
  33 class AdminSocket;
  34 class MCommand;
  35 class MMonCommand;
  36
  37 using namespace std::literals;
  38
  39 inline constexpr auto CEPH_ADMIN_SOCK_VERSION = "2"sv;
  40
  41 class AdminSocketHook {
  42 public:
  43   /**
  44    * @brief
  45    * Handler for admin socket commands, synchronous version
  46    *
  47    * Executes action associated with admin command and returns byte-stream output @c out.
  48    * There is no restriction on output. Each handler defines output semantics.
  49    * Typically output is textual representation of some ceph's internals.
  50    * Handler should use provided formatter @c f if structuralized output is being produced.
  51    *
  52    * @param command[in] String matching constant part of cmddesc in @ref AdminSocket::register_command
  53    * @param cmdmap[in]  Parameters extracted from argument part of cmddesc in @ref AdminSocket::register_command
  54    * @param f[in]       Formatter created according to requestor preference, used by `ceph --format`
  55    * @param errss[out]  Error stream, should contain details in case of execution failure
  56    * @param out[out]    Produced output
  57    *
  58    * @retval 0 Success, errss is ignored and does not contribute to output
  59    * @retval <0 Error code, errss is prepended to @c out
  60    *
  61    * @note If @c out is empty, then admin socket will try to flush @c f to out.
  62    */
  63   virtual int call(
  64     std::string_view command,
  65     const cmdmap_t& cmdmap,
  66     Formatter *f,
  67     std::ostream& errss,
  68     ceph::buffer::list& out) = 0;
  69
  70   /**
  71    * @brief
  72    * Handler for admin socket commands, asynchronous version
  73    *
  74    * Executes action associated with admin command and prepares byte-stream response.
  75    * When processing is done @c on_finish must be called.
  76    * There is no restriction on output. Each handler defines own output semantics.
  77    * Typically output is textual representation of some ceph's internals.
  78    * Input @c inbl can be passed, see ceph --in-file.
  79    * Handler should use provided formatter @c f if structuralized output is being produced.
  80    * on_finish handler has following parameters:
  81    * - result code of handler (same as @ref AdminSocketHook::call)
  82    * - error message, text
  83    * - output
  84    *
  85    * @param[in] command String matching constant part of cmddesc in @ref AdminSocket::register_command
  86    * @param[in] cmdmap  Parameters extracted from argument part of cmddesc in @ref AdminSocket::register_command
  87    * @param[in] f       Formatter created according to requestor preference, used by `ceph --format`
  88    * @param[in] inbl    Input content for handler
  89    * @param[in] on_finish Function to call when processing is done
  90    *
  91    * @note If @c out is empty, then admin socket will try to flush @c f to out.
  92    */
  93   virtual void call_async(
  94     std::string_view command,
  95     const cmdmap_t& cmdmap,
  96     Formatter *f,
  97     const bufferlist& inbl,
  98     std::function<void(int,const std::string&,bufferlist&)> on_finish) {
  99     // by default, call the synchronous handler and then finish
 100     bufferlist out;
 101     std::ostringstream errss;
 102     int r = call(command, cmdmap, f, errss, out);
 103     on_finish(r, errss.str(), out);
 104   }
 105   virtual ~AdminSocketHook() {}
 106 };
 107
 108 class AdminSocket
 109 {
 110 public:
 111   AdminSocket(CephContext *cct);
 112   ~AdminSocket();
 113
 114   AdminSocket(const AdminSocket&) = delete;
 115   AdminSocket& operator =(const AdminSocket&) = delete;
 116   AdminSocket(AdminSocket&&) = delete;
 117   AdminSocket& operator =(AdminSocket&&) = delete;
 118
 119   /**
 120    * register an admin socket command
 121    *
 122    * The command is registered under a command string.  Incoming
 123    * commands are split by space and matched against the longest
 124    * registered command.  For example, if 'foo' and 'foo bar' are
 125    * registered, and an incoming command is 'foo bar baz', it is
 126    * matched with 'foo bar', while 'foo fud' will match 'foo'.
 127    *
 128    * The entire incoming command string is passed to the registered
 129    * hook.
 130    *
 131    * @param command command string
 132    * @param cmddesc command syntax descriptor
 133    * @param hook implementation
 134    * @param help help text.  if empty, command will not be included in 'help' output.
 135    *
 136    * @return 0 for success, -EEXIST if command already registered.
 137    */
 138   int register_command(std::string_view cmddesc,
 139                        AdminSocketHook *hook,
 140                        std::string_view help);
 141
 142   /*
 143    * unregister all commands belong to hook.
 144    */
 145   void unregister_commands(const AdminSocketHook *hook);
 146
 147   bool init(const std::string& path);
 148
 149   void chown(uid_t uid, gid_t gid);
 150   void chmod(mode_t mode);
 151
 152   /// execute (async)
 153   void execute_command(
 154     const std::vector<std::string>& cmd,
 155     const bufferlist& inbl,
 156     std::function<void(int,const std::string&,bufferlist&)> on_fin);
 157
 158   /// execute (blocking)
 159   int execute_command(
 160     const std::vector<std::string>& cmd,
 161     const bufferlist& inbl,
 162     std::ostream& errss,
 163     bufferlist *outbl);
 164
 165   void queue_tell_command(cref_t<MCommand> m);
 166   void queue_tell_command(cref_t<MMonCommand> m); // for compat
 167
 168 private:
 169
 170   void shutdown();
 171   void wakeup();
 172
 173   std::string create_wakeup_pipe(int *pipe_rd, int *pipe_wr);
 174   std::string destroy_wakeup_pipe();
 175   std::string bind_and_listen(const std::string &sock_path, int *fd);
 176
 177   std::thread th;
 178   void entry() noexcept;
 179   void do_accept();
 180   void do_tell_queue();
 181
 182   CephContext *m_cct;
 183   std::string m_path;
 184   int m_sock_fd = -1;
 185   int m_wakeup_rd_fd = -1;
 186   int m_wakeup_wr_fd = -1;
 187   bool m_shutdown = false;
 188
 189   bool in_hook = false;
 190   std::condition_variable in_hook_cond;
 191   std::mutex lock;  // protects `hooks`
 192   std::unique_ptr<AdminSocketHook> version_hook;
 193   std::unique_ptr<AdminSocketHook> help_hook;
 194   std::unique_ptr<AdminSocketHook> getdescs_hook;
 195
 196   std::mutex tell_lock;
 197   std::list<cref_t<MCommand>> tell_queue;
 198   std::list<cref_t<MMonCommand>> tell_legacy_queue;
 199
 200   struct hook_info {
 201     AdminSocketHook* hook;
 202     std::string desc;
 203     std::string help;
 204
 205     hook_info(AdminSocketHook* hook, std::string_view desc,
 206               std::string_view help)
 207       : hook(hook), desc(desc), help(help) {}
 208   };
 209
 210   /// find the first hook which matches the given prefix and cmdmap
 211   std::pair<int, AdminSocketHook*> find_matched_hook(
 212     std::string& prefix,
 213     const cmdmap_t& cmdmap);
 214
 215   std::multimap<std::string, hook_info, std::less<>> hooks;
 216
 217   friend class AdminSocketTest;
 218   friend class HelpHook;
 219   friend class GetdescsHook;
 220 };
 221
 222 #endif
 223 #endif