2 * Copyright (c) 2008, 2009, 2010, 2011, 2012, 2013 Nicira, Inc.
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:
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
23 #include "dynamic-string.h"
27 #include "poll-loop.h"
30 #include "stream-provider.h"
34 VLOG_DEFINE_THIS_MODULE(unixctl);
36 COVERAGE_DEFINE(unixctl_received);
37 COVERAGE_DEFINE(unixctl_replied);
39 struct unixctl_command {
41 int min_args, max_args;
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. */
55 /* Server for control connection. */
56 struct unixctl_server {
57 struct pstream *listener;
61 static struct vlog_rate_limit rl = VLOG_RATE_LIMIT_INIT(5, 5);
63 static struct shash commands = SHASH_INITIALIZER(&commands);
66 unixctl_help(struct unixctl_conn *conn, int argc OVS_UNUSED,
67 const char *argv[] OVS_UNUSED, void *aux OVS_UNUSED)
69 struct ds ds = DS_EMPTY_INITIALIZER;
70 const struct shash_node **nodes = shash_sort(&commands);
73 ds_put_cstr(&ds, "The available commands are:\n");
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;
79 ds_put_format(&ds, " %-23s %s\n", node->name, command->usage);
83 unixctl_command_reply(conn, ds_cstr(&ds));
88 unixctl_version(struct unixctl_conn *conn, int argc OVS_UNUSED,
89 const char *argv[] OVS_UNUSED, void *aux OVS_UNUSED)
91 unixctl_command_reply(conn, get_program_version());
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
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. */
106 unixctl_command_register(const char *name, const char *usage,
107 int min_args, int max_args,
108 unixctl_cb_func *cb, void *aux)
110 struct unixctl_command *command;
111 struct unixctl_command *lookup = shash_find_data(&commands, name);
113 ovs_assert(!lookup || lookup->cb == cb);
119 command = xmalloc(sizeof *command);
120 command->usage = usage;
121 command->min_args = min_args;
122 command->max_args = max_args;
125 shash_add(&commands, name, command);
129 unixctl_command_reply__(struct unixctl_conn *conn,
130 bool success, const char *body)
132 struct json *body_json;
133 struct jsonrpc_msg *reply;
135 COVERAGE_INC(unixctl_replied);
136 ovs_assert(conn->request_id);
142 if (body[0] && body[strlen(body) - 1] != '\n') {
143 body_json = json_string_create_nocopy(xasprintf("%s\n", body));
145 body_json = json_string_create(body);
149 reply = jsonrpc_create_reply(body_json, conn->request_id);
151 reply = jsonrpc_create_error(body_json, conn->request_id);
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;
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
166 unixctl_command_reply(struct unixctl_conn *conn, const char *result)
168 unixctl_command_reply__(conn, true, result);
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
176 unixctl_command_reply_error(struct unixctl_conn *conn, const char *error)
178 unixctl_command_reply__(conn, false, error);
181 /* Creates a unixctl server listening on 'path', which for POSIX may be:
183 * - NULL, in which case <rundir>/<program>.<pid>.ctl is used.
185 * - A name that does not start with '/', in which case it is put in
188 * - An absolute path (starting with '/') that gives the exact name of
189 * the Unix domain socket to listen on.
191 * For Windows, a kernel assigned TCP port is used and written in 'path'
194 * - NULL, in which case <rundir>/<program>.ctl is used.
196 * - An absolute path that gives the name of the file.
198 * For both POSIX and Windows, if the path is "none", the function will
199 * return successfully but no socket will actually be created.
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.)
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. */
210 unixctl_server_create(const char *path, struct unixctl_server **serverp)
212 struct unixctl_server *server;
213 struct pstream *listener;
214 char *punix_path, *abs_path = NULL;
221 if (path && !strcmp(path, "none")) {
227 abs_path = abs_file_name(ovs_rundir(), path);
228 punix_path = xasprintf("punix:%s", abs_path);
230 punix_path = xasprintf("punix:%s/%s.%ld.ctl", ovs_rundir(),
231 program_name, (long int) getpid());
234 punix_path = xstrdup("ptcp:0:127.0.0.1");
237 error = pstream_open(punix_path, &listener, 0);
239 ovs_error(error, "could not initialize control socket %s", punix_path);
245 abs_path = xstrdup(path);
247 abs_path = xasprintf("%s/%s.ctl", ovs_rundir(), program_name);
250 file = fopen(abs_path, "w");
253 ovs_error(error, "could not open %s", abs_path);
257 fprintf(file, "%d\n", ntohs(listener->bound_port));
258 if (fflush(file) == EOF) {
260 ovs_error(error, "write failed for %s", abs_path);
267 unixctl_command_register("help", "", 0, 0, unixctl_help, NULL);
268 unixctl_command_register("version", "", 0, 0, unixctl_version, NULL);
270 server = xmalloc(sizeof *server);
271 server->listener = listener;
272 list_init(&server->conns);
284 process_command(struct unixctl_conn *conn, struct jsonrpc_msg *request)
288 struct unixctl_command *command;
289 struct json_array *params;
291 COVERAGE_INC(unixctl_received);
292 conn->request_id = json_clone(request->id);
294 params = json_array(request->params);
295 command = shash_find_data(&commands, request->method);
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);
305 struct svec argv = SVEC_EMPTY_INITIALIZER;
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",
315 svec_add(&argv, json_string(params->elems[i]));
317 svec_terminate(&argv);
320 command->cb(conn, argv.n, (const char **) argv.names,
328 unixctl_command_reply_error(conn, error);
334 run_connection(struct unixctl_conn *conn)
338 jsonrpc_run(conn->rpc);
339 error = jsonrpc_get_status(conn->rpc);
340 if (error || jsonrpc_get_backlog(conn->rpc)) {
344 for (i = 0; i < 10; i++) {
345 struct jsonrpc_msg *msg;
347 if (error || conn->request_id) {
351 jsonrpc_recv(conn->rpc, &msg);
353 if (msg->type == JSONRPC_REQUEST) {
354 process_command(conn, msg);
356 VLOG_WARN_RL(&rl, "%s: received unexpected %s message",
357 jsonrpc_get_name(conn->rpc),
358 jsonrpc_msg_type_to_string(msg->type));
361 jsonrpc_msg_destroy(msg);
363 error = error ? error : jsonrpc_get_status(conn->rpc);
370 kill_connection(struct unixctl_conn *conn)
372 list_remove(&conn->node);
373 jsonrpc_close(conn->rpc);
374 json_destroy(conn->request_id);
379 unixctl_server_run(struct unixctl_server *server)
381 struct unixctl_conn *conn, *next;
388 for (i = 0; i < 10; i++) {
389 struct stream *stream;
392 error = pstream_accept(server->listener, &stream);
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) {
400 VLOG_WARN_RL(&rl, "%s: accept failed: %s",
401 pstream_get_name(server->listener),
402 ovs_strerror(error));
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);
415 unixctl_server_wait(struct unixctl_server *server)
417 struct unixctl_conn *conn;
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);
432 /* Destroys 'server' and stops listening for connections. */
434 unixctl_server_destroy(struct unixctl_server *server)
437 struct unixctl_conn *conn, *next;
439 LIST_FOR_EACH_SAFE (conn, next, node, &server->conns) {
440 kill_connection(conn);
443 pstream_close(server->listener);
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).
452 * On Windows, connects to a localhost TCP port as written inside 'path'.
453 * 'path' should be an absolute path of the file.
455 * Returns 0 if successful, otherwise a positive errno value. If successful,
456 * sets '*client' to the new jsonrpc, otherwise to NULL. */
458 unixctl_client_create(const char *path, struct jsonrpc **client)
460 char *abs_path, *unix_path;
461 struct stream *stream;
467 abs_path = strdup(path);
468 file = fopen(abs_path, "r");
471 ovs_error(error, "could not open %s", abs_path);
476 error = fscanf(file, "%d", &port);
478 ovs_error(errno, "failed to read port from %s", abs_path);
484 unix_path = xasprintf("tcp:127.0.0.1:%d", port);
486 abs_path = abs_file_name(ovs_rundir(), path);
487 unix_path = xasprintf("unix:%s", abs_path);
492 error = stream_open_block(stream_open(unix_path, &stream, DSCP_DEFAULT),
498 VLOG_WARN("failed to connect to %s", path);
502 *client = jsonrpc_open(stream);
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. */
513 unixctl_client_transact(struct jsonrpc *client, const char *command, int argc,
514 char *argv[], char **result, char **err)
516 struct jsonrpc_msg *request, *reply;
517 struct json **json_args, *params;
523 json_args = xmalloc(argc * sizeof *json_args);
524 for (i = 0; i < argc; i++) {
525 json_args[i] = json_string_create(argv[i]);
527 params = json_array_create(json_args, argc);
528 request = jsonrpc_create_request(command, params, NULL);
530 error = jsonrpc_transact_block(client, request, &reply);
532 VLOG_WARN("error communicating with %s: %s", jsonrpc_get_name(client),
533 ovs_retval_to_string(error));
538 if (reply->error->type == JSON_STRING) {
539 *err = xstrdup(json_string(reply->error));
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));
546 } else if (reply->result) {
547 if (reply->result->type == JSON_STRING) {
548 *result = xstrdup(json_string(reply->result));
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));
557 jsonrpc_msg_destroy(reply);