lib/unixctl.c

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2016 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #include <config.h>
  18 #include "unixctl.h"
  19 #include <errno.h>
  20 #include <unistd.h>
  21 #include "coverage.h"
  22 #include "dirs.h"
  23 #include "openvswitch/dynamic-string.h"
  24 #include "openvswitch/json.h"
  25 #include "jsonrpc.h"
  26 #include "openvswitch/list.h"
  27 #include "openvswitch/poll-loop.h"
  28 #include "openvswitch/shash.h"
  29 #include "stream.h"
  30 #include "stream-provider.h"
  31 #include "svec.h"
  32 #include "openvswitch/vlog.h"
  33
  34 VLOG_DEFINE_THIS_MODULE(unixctl);
  35
  36 COVERAGE_DEFINE(unixctl_received);
  37 COVERAGE_DEFINE(unixctl_replied);
  38 \f
  39 struct unixctl_command {
  40     const char *usage;
  41     int min_args, max_args;
  42     unixctl_cb_func *cb;
  43     void *aux;
  44 };
  45
  46 struct unixctl_conn {
  47     struct ovs_list node;
  48     struct jsonrpc *rpc;
  49
  50     /* Only one request can be in progress at a time.  While the request is
  51      * being processed, 'request_id' is populated, otherwise it is null. */
  52     struct json *request_id;   /* ID of the currently active request. */
  53 };
  54
  55 /* Server for control connection. */
  56 struct unixctl_server {
  57     struct pstream *listener;
  58     struct ovs_list conns;
  59     char *path;
  60 };
  61
  62 static struct vlog_rate_limit rl = VLOG_RATE_LIMIT_INIT(5, 5);
  63
  64 static struct shash commands = SHASH_INITIALIZER(&commands);
  65
  66 static void
  67 unixctl_list_commands(struct unixctl_conn *conn, int argc OVS_UNUSED,
  68                       const char *argv[] OVS_UNUSED, void *aux OVS_UNUSED)
  69 {
  70     struct ds ds = DS_EMPTY_INITIALIZER;
  71     const struct shash_node **nodes = shash_sort(&commands);
  72     size_t i;
  73
  74     ds_put_cstr(&ds, "The available commands are:\n");
  75
  76     for (i = 0; i < shash_count(&commands); i++) {
  77         const struct shash_node *node = nodes[i];
  78         const struct unixctl_command *command = node->data;
  79
  80         if (command->usage) {
  81             ds_put_format(&ds, "  %-23s %s\n", node->name, command->usage);
  82         }
  83     }
  84     free(nodes);
  85
  86     unixctl_command_reply(conn, ds_cstr(&ds));
  87     ds_destroy(&ds);
  88 }
  89
  90 static void
  91 unixctl_version(struct unixctl_conn *conn, int argc OVS_UNUSED,
  92                 const char *argv[] OVS_UNUSED, void *aux OVS_UNUSED)
  93 {
  94     unixctl_command_reply(conn, ovs_get_program_version());
  95 }
  96
  97 /* Registers a unixctl command with the given 'name'.  'usage' describes the
  98  * arguments to the command; it is used only for presentation to the user in
  99  * "list-commands" output.  (If 'usage' is NULL, then the command is hidden.)
 100  *
 101  * 'cb' is called when the command is received.  It is passed an array
 102  * containing the command name and arguments, plus a copy of 'aux'.  Normally
 103  * 'cb' should reply by calling unixctl_command_reply() or
 104  * unixctl_command_reply_error() before it returns, but if the command cannot
 105  * be handled immediately then it can defer the reply until later.  A given
 106  * connection can only process a single request at a time, so a reply must be
 107  * made eventually to avoid blocking that connection. */
 108 void
 109 unixctl_command_register(const char *name, const char *usage,
 110                          int min_args, int max_args,
 111                          unixctl_cb_func *cb, void *aux)
 112 {
 113     struct unixctl_command *command;
 114     struct unixctl_command *lookup = shash_find_data(&commands, name);
 115
 116     ovs_assert(!lookup || lookup->cb == cb);
 117
 118     if (lookup) {
 119         return;
 120     }
 121
 122     command = xmalloc(sizeof *command);
 123     command->usage = usage;
 124     command->min_args = min_args;
 125     command->max_args = max_args;
 126     command->cb = cb;
 127     command->aux = aux;
 128     shash_add(&commands, name, command);
 129 }
 130
 131 static void
 132 unixctl_command_reply__(struct unixctl_conn *conn,
 133                         bool success, const char *body)
 134 {
 135     struct json *body_json;
 136     struct jsonrpc_msg *reply;
 137
 138     COVERAGE_INC(unixctl_replied);
 139     ovs_assert(conn->request_id);
 140
 141     if (!body) {
 142         body = "";
 143     }
 144
 145     if (body[0] && body[strlen(body) - 1] != '\n') {
 146         body_json = json_string_create_nocopy(xasprintf("%s\n", body));
 147     } else {
 148         body_json = json_string_create(body);
 149     }
 150
 151     if (success) {
 152         reply = jsonrpc_create_reply(body_json, conn->request_id);
 153     } else {
 154         reply = jsonrpc_create_error(body_json, conn->request_id);
 155     }
 156
 157     if (VLOG_IS_DBG_ENABLED()) {
 158         char *id = json_to_string(conn->request_id, 0);
 159         VLOG_DBG("replying with %s, id=%s: \"%s\"",
 160                  success ? "success" : "error", id, body);
 161         free(id);
 162     }
 163
 164     /* If jsonrpc_send() returns an error, the run loop will take care of the
 165      * problem eventually. */
 166     jsonrpc_send(conn->rpc, reply);
 167     json_destroy(conn->request_id);
 168     conn->request_id = NULL;
 169 }
 170
 171 /* Replies to the active unixctl connection 'conn'.  'result' is sent to the
 172  * client indicating the command was processed successfully.  Only one call to
 173  * unixctl_command_reply() or unixctl_command_reply_error() may be made per
 174  * request. */
 175 void
 176 unixctl_command_reply(struct unixctl_conn *conn, const char *result)
 177 {
 178     unixctl_command_reply__(conn, true, result);
 179 }
 180
 181 /* Replies to the active unixctl connection 'conn'. 'error' is sent to the
 182  * client indicating an error occurred processing the command.  Only one call to
 183  * unixctl_command_reply() or unixctl_command_reply_error() may be made per
 184  * request. */
 185 void
 186 unixctl_command_reply_error(struct unixctl_conn *conn, const char *error)
 187 {
 188     unixctl_command_reply__(conn, false, error);
 189 }
 190
 191 /* Creates a unixctl server listening on 'path', which for POSIX may be:
 192  *
 193  *      - NULL, in which case <rundir>/<program>.<pid>.ctl is used.
 194  *
 195  *      - A name that does not start with '/', in which case it is put in
 196  *        <rundir>.
 197  *
 198  *      - An absolute path (starting with '/') that gives the exact name of
 199  *        the Unix domain socket to listen on.
 200  *
 201  * For Windows, a local named pipe is used. A file is created in 'path'
 202  * which may be:
 203  *
 204  *      - NULL, in which case <rundir>/<program>.ctl is used.
 205  *
 206  *      - An absolute path that gives the name of the file.
 207  *
 208  * For both POSIX and Windows, if the path is "none", the function will
 209  * return successfully but no socket will actually be created.
 210  *
 211  * A program that (optionally) daemonizes itself should call this function
 212  * *after* daemonization, so that the socket name contains the pid of the
 213  * daemon instead of the pid of the program that exited.  (Otherwise,
 214  * "ovs-appctl --target=<program>" will fail.)
 215  *
 216  * Returns 0 if successful, otherwise a positive errno value.  If successful,
 217  * sets '*serverp' to the new unixctl_server (or to NULL if 'path' was "none"),
 218  * otherwise to NULL. */
 219 int
 220 unixctl_server_create(const char *path, struct unixctl_server **serverp)
 221 {
 222     *serverp = NULL;
 223     if (path && !strcmp(path, "none")) {
 224         return 0;
 225     }
 226
 227 #ifdef _WIN32
 228     enum { WINDOWS = 1 };
 229 #else
 230     enum { WINDOWS = 0 };
 231 #endif
 232
 233     long int pid = getpid();
 234     char *abs_path
 235         = (path ? abs_file_name(ovs_rundir(), path)
 236            : WINDOWS ? xasprintf("%s/%s.ctl", ovs_rundir(), program_name)
 237            : xasprintf("%s/%s.%ld.ctl", ovs_rundir(), program_name, pid));
 238
 239     struct pstream *listener;
 240     char *punix_path = xasprintf("punix:%s", abs_path);
 241     int error = pstream_open(punix_path, &listener, 0);
 242     free(punix_path);
 243
 244     if (error) {
 245         ovs_error(error, "%s: could not initialize control socket", abs_path);
 246         free(abs_path);
 247         return error;
 248     }
 249
 250     unixctl_command_register("list-commands", "", 0, 0, unixctl_list_commands,
 251                              NULL);
 252     unixctl_command_register("version", "", 0, 0, unixctl_version, NULL);
 253
 254     struct unixctl_server *server = xmalloc(sizeof *server);
 255     server->listener = listener;
 256     server->path = abs_path;
 257     ovs_list_init(&server->conns);
 258     *serverp = server;
 259     return 0;
 260 }
 261
 262 static void
 263 process_command(struct unixctl_conn *conn, struct jsonrpc_msg *request)
 264 {
 265     char *error = NULL;
 266
 267     struct unixctl_command *command;
 268     struct json_array *params;
 269
 270     COVERAGE_INC(unixctl_received);
 271     conn->request_id = json_clone(request->id);
 272
 273     if (VLOG_IS_DBG_ENABLED()) {
 274         char *params_s = json_to_string(request->params, 0);
 275         char *id_s = json_to_string(request->id, 0);
 276         VLOG_DBG("received request %s%s, id=%s",
 277                  request->method, params_s, id_s);
 278         free(params_s);
 279         free(id_s);
 280     }
 281
 282     params = json_array(request->params);
 283     command = shash_find_data(&commands, request->method);
 284     if (!command) {
 285         error = xasprintf("\"%s\" is not a valid command (use "
 286                           "\"list-commands\" to see a list of valid commands)",
 287                           request->method);
 288     } else if (params->n < command->min_args) {
 289         error = xasprintf("\"%s\" command requires at least %d arguments",
 290                           request->method, command->min_args);
 291     } else if (params->n > command->max_args) {
 292         error = xasprintf("\"%s\" command takes at most %d arguments",
 293                           request->method, command->max_args);
 294     } else {
 295         struct svec argv = SVEC_EMPTY_INITIALIZER;
 296         int  i;
 297
 298         svec_add(&argv, request->method);
 299         for (i = 0; i < params->n; i++) {
 300             if (params->elems[i]->type != JSON_STRING) {
 301                 error = xasprintf("\"%s\" command has non-string argument",
 302                                   request->method);
 303                 break;
 304             }
 305             svec_add(&argv, json_string(params->elems[i]));
 306         }
 307         svec_terminate(&argv);
 308
 309         if (!error) {
 310             command->cb(conn, argv.n, (const char **) argv.names,
 311                         command->aux);
 312         }
 313
 314         svec_destroy(&argv);
 315     }
 316
 317     if (error) {
 318         unixctl_command_reply_error(conn, error);
 319         free(error);
 320     }
 321 }
 322
 323 static int
 324 run_connection(struct unixctl_conn *conn)
 325 {
 326     int error, i;
 327
 328     jsonrpc_run(conn->rpc);
 329     error = jsonrpc_get_status(conn->rpc);
 330     if (error || jsonrpc_get_backlog(conn->rpc)) {
 331         return error;
 332     }
 333
 334     for (i = 0; i < 10; i++) {
 335         struct jsonrpc_msg *msg;
 336
 337         if (error || conn->request_id) {
 338             break;
 339         }
 340
 341         jsonrpc_recv(conn->rpc, &msg);
 342         if (msg) {
 343             if (msg->type == JSONRPC_REQUEST) {
 344                 process_command(conn, msg);
 345             } else {
 346                 VLOG_WARN_RL(&rl, "%s: received unexpected %s message",
 347                              jsonrpc_get_name(conn->rpc),
 348                              jsonrpc_msg_type_to_string(msg->type));
 349                 error = EINVAL;
 350             }
 351             jsonrpc_msg_destroy(msg);
 352         }
 353         error = error ? error : jsonrpc_get_status(conn->rpc);
 354     }
 355
 356     return error;
 357 }
 358
 359 static void
 360 kill_connection(struct unixctl_conn *conn)
 361 {
 362     ovs_list_remove(&conn->node);
 363     jsonrpc_close(conn->rpc);
 364     json_destroy(conn->request_id);
 365     free(conn);
 366 }
 367
 368 void
 369 unixctl_server_run(struct unixctl_server *server)
 370 {
 371     if (!server) {
 372         return;
 373     }
 374
 375     for (int i = 0; i < 10; i++) {
 376         struct stream *stream;
 377         int error;
 378
 379         error = pstream_accept(server->listener, &stream);
 380         if (!error) {
 381             struct unixctl_conn *conn = xzalloc(sizeof *conn);
 382             ovs_list_push_back(&server->conns, &conn->node);
 383             conn->rpc = jsonrpc_open(stream);
 384         } else if (error == EAGAIN) {
 385             break;
 386         } else {
 387             VLOG_WARN_RL(&rl, "%s: accept failed: %s",
 388                          pstream_get_name(server->listener),
 389                          ovs_strerror(error));
 390         }
 391     }
 392
 393     struct unixctl_conn *conn, *next;
 394     LIST_FOR_EACH_SAFE (conn, next, node, &server->conns) {
 395         int error = run_connection(conn);
 396         if (error && error != EAGAIN) {
 397             kill_connection(conn);
 398         }
 399     }
 400 }
 401
 402 void
 403 unixctl_server_wait(struct unixctl_server *server)
 404 {
 405     struct unixctl_conn *conn;
 406
 407     if (!server) {
 408         return;
 409     }
 410
 411     pstream_wait(server->listener);
 412     LIST_FOR_EACH (conn, node, &server->conns) {
 413         jsonrpc_wait(conn->rpc);
 414         if (!jsonrpc_get_backlog(conn->rpc) && !conn->request_id) {
 415             jsonrpc_recv_wait(conn->rpc);
 416         }
 417     }
 418 }
 419
 420 /* Destroys 'server' and stops listening for connections. */
 421 void
 422 unixctl_server_destroy(struct unixctl_server *server)
 423 {
 424     if (server) {
 425         struct unixctl_conn *conn, *next;
 426
 427         LIST_FOR_EACH_SAFE (conn, next, node, &server->conns) {
 428             kill_connection(conn);
 429         }
 430
 431         free(server->path);
 432         pstream_close(server->listener);
 433         free(server);
 434     }
 435 }
 436
 437 const char *
 438 unixctl_server_get_path(const struct unixctl_server *server)
 439 {
 440     return server ? server->path : NULL;
 441 }
 442 \f
 443 /* On POSIX based systems, connects to a unixctl server socket.  'path' should
 444  * be the name of a unixctl server socket.  If it does not start with '/', it
 445  * will be prefixed with the rundir (e.g. /usr/local/var/run/openvswitch).
 446  *
 447  * On Windows, connects to a local named pipe. A file which resides in
 448  * 'path' is used to mimic the behavior of a Unix domain socket.
 449  * 'path' should be an absolute path of the file.
 450  *
 451  * Returns 0 if successful, otherwise a positive errno value.  If successful,
 452  * sets '*client' to the new jsonrpc, otherwise to NULL. */
 453 int
 454 unixctl_client_create(const char *path, struct jsonrpc **client)
 455 {
 456     struct stream *stream;
 457     int error;
 458
 459     char *abs_path = abs_file_name(ovs_rundir(), path);
 460     char *unix_path = xasprintf("unix:%s", abs_path);
 461
 462     *client = NULL;
 463
 464     error = stream_open_block(stream_open(unix_path, &stream, DSCP_DEFAULT),
 465                               -1, &stream);
 466     free(unix_path);
 467     free(abs_path);
 468
 469     if (error) {
 470         VLOG_WARN("failed to connect to %s", path);
 471         return error;
 472     }
 473
 474     *client = jsonrpc_open(stream);
 475     return 0;
 476 }
 477
 478 /* Executes 'command' on the server with an argument vector 'argv' containing
 479  * 'argc' elements.  If successfully communicated with the server, returns 0
 480  * and sets '*result', or '*err' (not both) to the result or error the server
 481  * returned.  Otherwise, sets '*result' and '*err' to NULL and returns a
 482  * positive errno value.  The caller is responsible for freeing '*result' or
 483  * '*err' if not NULL. */
 484 int
 485 unixctl_client_transact(struct jsonrpc *client, const char *command, int argc,
 486                         char *argv[], char **result, char **err)
 487 {
 488     struct jsonrpc_msg *request, *reply;
 489     struct json **json_args, *params;
 490     int error, i;
 491
 492     *result = NULL;
 493     *err = NULL;
 494
 495     json_args = xmalloc(argc * sizeof *json_args);
 496     for (i = 0; i < argc; i++) {
 497         json_args[i] = json_string_create(argv[i]);
 498     }
 499     params = json_array_create(json_args, argc);
 500     request = jsonrpc_create_request(command, params, NULL);
 501
 502     error = jsonrpc_transact_block(client, request, &reply);
 503     if (error) {
 504         VLOG_WARN("error communicating with %s: %s", jsonrpc_get_name(client),
 505                   ovs_retval_to_string(error));
 506         return error;
 507     }
 508
 509     if (reply->error) {
 510         if (reply->error->type == JSON_STRING) {
 511             *err = xstrdup(json_string(reply->error));
 512         } else {
 513             VLOG_WARN("%s: unexpected error type in JSON RPC reply: %s",
 514                       jsonrpc_get_name(client),
 515                       json_type_to_string(reply->error->type));
 516             error = EINVAL;
 517         }
 518     } else if (reply->result) {
 519         if (reply->result->type == JSON_STRING) {
 520             *result = xstrdup(json_string(reply->result));
 521         } else {
 522             VLOG_WARN("%s: unexpected result type in JSON rpc reply: %s",
 523                       jsonrpc_get_name(client),
 524                       json_type_to_string(reply->result->type));
 525             error = EINVAL;
 526         }
 527     }
 528
 529     jsonrpc_msg_destroy(reply);
 530     return error;
 531 }