lib/unixctl.c

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