Skip to content

ControlSocket

Jump to bottom Edit New page
Tom Barbette edited this page Oct 3, 2018 · 2 revisions

ControlSocket Element Documentation

NAME

ControlSocket — Click element; opens control sockets for other programs

SYNOPSIS

ControlSocket("TCP", PORTNUMBER [, keywords READONLY, PROXY, VERBOSE, LOCALHOST, RETRIES, RETRY_WARNINGS])
ControlSocket("UNIX", FILENAME [, keywords])

Ports: none
Drivers: userlevel

DESCRIPTION

Opens a control socket that allows other user-level programs to call read or write handlers on the router. Depending on its configuration string, ControlSocket will listen on TCP port PORTNUMBER, or on a UNIX-domain socket named FILENAME. With the PROXY keyword argument, you can make ControlSocket speak to a kernel driver; see below.

The "server" (that is, the ControlSocket element) speaks a relatively simple line-based protocol. Commands sent to the server are single lines of text; they consist of words separated by spaces. The server responds to every command with at least one message line followed optionally by some data. Message lines start with a three-digit response code, as in FTP. When multiple message lines are sent in response to a single command, all but the last begin with the response code and a hyphen (as in "200-Hello!"); the last line begins with the response code and a space (as in "200 Hello!").

The server will accept lines terminated by CR, LF, or CRLF. Its response lines are always terminated by CRLF.

When a connection is opened, the server responds by stating its protocol version number with a line like "Click::ControlSocket/1.3". The current version number is 1.3. Changes in minor version number will only add commands and functionality to this specification, not change existing functionality.

ControlSocket supports hot-swapping, meaning you can change configurations without interrupting existing clients. The hot-swap will succeed only if the old ControlSocket and the new ControlSocket have the same element name, and the same socket type and port/filename parameters. Additionally, the new ControlSocket must have RETRIES set to 1 or more, since the old ControlSocket has already bound the relevant socket.

Keyword arguments are:

  • READONLY — Boolean. Disallows write handlers if true (it is false by default).
  • PROXY — String. Specifies an element proxy. When a user requests the value of handler E.H, ControlSocket will actually return the value of `PROXY.E.H'. This is useful with elements like KernelHandlerProxy. Default is empty (no proxy).
  • VERBOSE — Boolean. When true, ControlSocket will print messages whenever it accepts a new connection or drops an old one. Default is false.
  • LOCALHOST — Boolean. When true, a TCP ControlSocket will only accept connections from the local host (127.0.0.1). Default is false.
  • RETRIES — Integer. If greater than 0, ControlSocket won't immediately fail when it can't open its socket. Instead, it will attempt to open the socket once a second until it succeeds, or until RETRIES unsuccessful attempts (after which it will stop the router). Default is 0.
  • RETRY_WARNINGS — Boolean. If true, ControlSocket will print warning messages every time it fails to open a socket. If false, it will print messages only on the final failure. Default is true.

The PORT argument for TCP ControlSockets can also be an integer followed by a plus sign, as in "ControlSocket(TCP, 41930+)". This means that the ControlSocket should bind on some port greater than or equal to PORT. If PORT itself is in use, ControlSocket will try several nearby ports before giving up. This can be useful in tests.

SERVER COMMANDS

Many server commands take a handler argument. These arguments name handlers, and take one of three forms: elementname.handlername names a particular element's handler; elementnumber.handlername also names an element handler, but the element is identified by index, starting from 1; and handlername names a global handler. (There are seven global read handlers, named version, list, classes, config, flatconfig, packages, and requirements. See click.o(8) for more information.)

  • READ handler [params...] — Call a read handler, passing the params, if any, as arguments, and return the results. On success, responds with a "success" message (response code 2xy) followed by a line like "DATA n". Here, n is a decimal integer indicating the length of the read handler data. The n bytes immediately following (the CRLF that terminates) the DATA line are the handler's results.

  • READDATA handler n — Call a read handler, passing the n bytes immediately following (the CRLF that terminates) the READDATA line as arguments, and return the results with "DATA n" as in the READ command. Introduced in version 1.2 of the ControlSocket protocol.

  • READUNTIL handler terminator — Call a read handler and return the results with "DATA n" as in the READ command. Parameters for handler are read from the input stream. Parameter reading stops at the first line that equals terminator. If terminator is not supplied, parameter reading stops at the first blank line. When searching for a terminator, ControlSocket removes trailing spaces from both terminator and the input lines. Introduced in version 1.3 of the ControlSocket protocol.

  • WRITE handler params... — Call a write handler, passing the params, if any, as arguments.

  • WRITEDATA handler n — Call a write handler. The arguments to pass are the n bytes immediately following (the CRLF that terminates) the WRITEDATA line.

  • WRITEUNTIL handler terminator — Call a write handler. The arguments to pass are the read from the input stream, stopping at the first line that equals terminator.

  • CHECKREAD handler — Checks whether a handler exists and is readable. The return status is 200 for readable handlers, and an appropriate error status for non-readable handlers or nonexistent handlers.

  • CHECKWRITE handler — Checks whether a handler exists and is writable.

  • LLRPC llrpc [n] — Call an LLRPC llrpc and return the results. Llrpc should have the form element#hexnumber. The hexnumber is the LLRPC number, from \xFFclick/llrpc.h>, in hexadecimal network format. Translate CLICK_LLRPC constants to network format by calling CLICK_LLRPC_HTON(CLICK_LLRPC_...). If n is given, then the n bytes immediately following (the CRLF that terminates) the LLRPC line are passed in as an argument. The results are returned after a "DATA nn" line, as in READ.

    ControlSocket will not call an LLRPC unless it can determine (from the command number) how much data the LLRPC expects and returns. (Only "flat" LLRPCs may be called; they are declared using the _CLICK_IOC_[RWS]F macros.)

  • QUIT — Close the connection.

The server's response codes follow this pattern.

  • 2xy — The command succeeded.
  • 5xy — The command failed.

Here are some of the particular error messages:

  200 OK.
  220 OK, but the handler reported some warnings.
  500 Syntax error.
  501 Unimplemented command.
  510 No such element.
  511 No such handler.
  520 Handler error.
  530 Permission denied.
  540 No router installed.

ControlSocket is only available in user-level processes.

EXAMPLES

  ControlSocket(unix, /tmp/clicksocket);

ELEMENT HANDLERS

  • port (read-only) — Returns the ControlSocket's port number. Only available for TYPE TCP.
  • filename (read-only) — Returns the ControlSocket's UNIX socket filename. Only available for TYPE UNIX.

SEE ALSO

ChatterSocket, KernelHandlerProxy

Generated by click-elem2man from ../elements/userlevel/controlsocket.hh:10 on 2018/10/03.

Add a custom footer
Clone this wiki locally