Remote Control Protocol

beng-proxy can listen for multicast packets on a UDP port. These packets contain one or more commands. This is useful to notify a whole cluster of beng-proxy servers of an event.

UDP is, by design, a lossy protocol. One must always consider that not all nodes may have received a given packet.

The protocol does not implement authentication. The commands are designed in a way that they do not affect security. However, it may pose a weakness against DoS attacks, if an attacker manages to inject packets into the internal network.

A command consists of a header containing length and command (network byte order), and an optional payload. The payload is padded with null bytes to the next 4 byte border.

Configuring

The configuration line option control allows you to specify an address to listen on:

control {
  bind "@beng-lb"
}

This binds to the abstract address beng-lb.

Known attributes:

  • bind: an adddress to bind to. May be the wildcard * or an IPv4/IPv6 address followed by a port. IPv6 addresses should be enclosed in square brackets to disambiguate the port separator. Local sockets start with a slash /, and abstract sockets start with the symbol @.

  • multicast_group: join this multicast group, which allows receiving multicast commands. Value is a multicast IPv4/IPv6 address. IPv6 addresses may contain a scope identifier after a percent sign (%).

  • interface: limit this listener to the given network interface.

Commands

  • NOP: ignored

  • TCACHE_INVALIDATE: Invalidates translation cache entries. This packet follows the same semantics as the INVALIDATE translation response packet, but instead of passing just a list of command numbers referring to a real translation request, you need to send the values as well. The payload of this packet consists of one or more concatenated translation packets in network byte order, padded with zeroes to multiples of 4 bytes. If the payload is empty, then the whole translation cache will be flushed.

    The following translation commands are valid inside the TCACHE_INVALIDATE payload:

    • URI: the raw URI from the HTTP request (without the query string)

    • PARAM: a parameter passed by the browser

    • SESSION: a session identifier generated by the translation server

    • REALM_SESSION: Like SESSION, but realm-local

    • LISTENER_TAG: The tag of the listener that accepted the connection

    • REMOTE_HOST: the client’s address or host name and the port number

    • HOST: the Host HTTP request header

    • LANGUAGE: the Accept-Language request header sent by the client

    • USER_AGENT: the User-Agent request header sent by the client

    • QUERY_STRING: the query string from request URI, without the question mark

    • INTERNAL_REDIRECT: causes beng-proxy to submit the same translation request again

    • ENOTDIR: The specified file does not exist, but a portion of the path points to a regular file

    • USER: the user name currently logged in using AUTH

    • SITE: optional identification or name of the site this resource belongs to

    • CACHE_TAG: Mark a cache item with this tag (an opaque string)

  • EXPIRE_TCACHE_TAG: Expire (invalidate) all cache items (and other resources referenced by them, such as child processes) within an arbitrary amount of time chosen by the recipient. Payload is a CACHE_TAG.

    This combines TCACHE_INVALIDATE with FADE_CHILDREN and can be used if this affects thousands of child processes. By allowing the recipient to choose an arbitrary delay, it avoids congesting the server with bulk process restarts.

  • ENABLE_NODE: Re-enable the specified node after a failure, remove all failure/fade states. The payload is the node name according to lb.conf, followed by a colon and the port number.

  • FADE_NODE: Fade out the specified node, preparing for its shutdown: the server will only be used for pre-existing sessions that refer to it. The payload is the node name according to lb.conf, followed by a colon and the port number. The effect lasts for 3 hours.

  • FADE_CHILDREN: Fade out child processes. If a payload is given, then this is a tag which fades only child processes with the given CHILD_TAG.

  • TERMINATE_CHILDREN: Terminate all child processes with the CHILD_TAG from the payload. Unlike FADE_CHILDREN, this does not wait for completion of the child’s currently work.Fade out child processes.

  • DISABLE_URING: Disable io_uring (temporarily). Optional payload is a big-endian 32 bit integer containing the number of seconds after which it will be re-enabled automatically. As this overrides any previous DISABLE_URING command, zero explicitly re-enables io_uring now. This switch exists to make debugging with strace easier, because strace does not cope well with io_uring.

  • DISABLE_ZEROCONF: Hide all registered Zeroconf services. To reveal them again, use ENABLE_ZEROCONF. This is a privileged operation (only allowed through local socket by user root).

  • ENABLE_ZEROCONF: Re-publish all registered Zeroconf services to undo the effect of DISABLE_ZEROCONF.

  • FLUSH_NFS_CACHE: Deprecated.

  • FLUSH_FILTER_CACHE: Flush all items from the filter cache. If a payload is given, then this is a tag which flushes only cache items with the given CACHE_TAG.

  • FLUSH_HTTP_CACHE: Flush all items from the HTTP cache with the given CACHE_TAG.

  • DISCARD_SESSION: Discard the session with the given ATTACH_SESSION value.

  • ENABLE_QUEUE / DISABLE_QUEUE: Enable the queue named in the payload. (This is used only by Workshop.)

  • RELOAD_STATE: Reload state from the state directories and apply it to the current process.

  • DISCONNECT_DATABASE: Disconnect all database connections matching the payload. This is usually received and handled by myproxy processes and the payload is the account identifier.

  • RESET_LIMITER: Reset data structures bound to the specified account that keep track of resource usage limits. This shall be sent after resource limits have been changed and applies only to data structures that cannot automatically apply these because they do not have enough context (e.g. token buckets).

  • REJECT_CLIENT: Reject clients from the specified address. Payload is a big-endian 32 bit integer containing the number of seconds after which the effect will expire, followed by a string describing the client address (e.g. 192.168.1.200, fe80::1234:5678%public). If an entry for this address already exists, this packet will only update the expiration time. An expiry of 0 means remove the entry immediately.

    This is implemented in beng-lb and requires enabling the client_ban_list listener option.

  • TARPIT_CLIENT: Like #REJECT_CLIENT, but slow down the client instead of rejecting it.

  • CANCEL_JOB: Cancel an asynchronous job (usually Workshop). Payload is the Workshop partition name and the job id (as string), separated by a null byte.

Only TCACHE_INVALIDATE, FLUSH_FILTER_CACHE are allowed when received via IP. The other commands are only accepted from clients connected on a local socket (aka Unix Domain Socket, AF_LOCAL).

Client

The Debian package cm4all-beng-control contains a generic non-interactive client which can send commands to beng-proxy or beng-lb.

The following command sends NOP to an abstract socket:

cm4all-beng-control --server=@bp-control nop

And here is a multicast on interface eth1:

cm4all-beng-control --server=ff02::dead%eth1 nop