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