amqpprox is configured primarily through messages passed to it's unix domain socket (default /tmp/amqpprox).
amqpprox_ctl is a tool for conviently passing configuration commands over this socket.
------------------ ingress ------------------- egress -------------------
| client | -------> | proxy | --------> | farm/backend |
------------------ ------------------- -------------------
$ amqpprox_ctl /tmp/amqpprox HELP
AUTH (SERVICE hostname port target | ALWAYS_ALLOW | PRINT) - Change authentication mechanism for connecting clients
BACKEND (ADD name datacenter host port [SEND-PROXY] [TLS] | ADD_DNS name datacenter address port [SEND-PROXY] [TLS] | DELETE name | PRINT) - Change backend servers
CONN Print the connected sessions
DATACENTER SET name | PRINT
EXIT Exit the program gracefully.
FARM (ADD name selector backend* | PARTITION name policy | DELETE name | PRINT) - Change farms
HELP Print this help text.
LIMIT (CONN_RATE_ALARM | CONN_RATE) (VHOST vhostName numberOfConnections | DEFAULT numberOfConnections) - Configure connection rate limits (normal or alarmonly) for incoming clients connections
LIMIT (DATA_RATE_ALARM | DATA_RATE) (DEFAULT | VHOST vhostName) BytesPerSecond - Configure data rate limits or alarms for incoming client data
LIMIT DISABLE (CONN_RATE_ALARM | CONN_RATE | DATA_RATE_ALARM | DATA_RATE) (VHOST vhostName | DEFAULT) - Disable configured limit thresholds
LIMIT PRINT [vhostName] - Print the configured default or specific connection rate limits for specified vhost
LISTEN START port | START_SECURE port | STOP [port]
LOG CONSOLE verbosity | FILE verbosity
MAP (BACKEND vhost backend | FARM vhost name | UNMAP vhost | DEFAULT farmName | REMOVE_DEFAULT | PRINT) - Change mappings of resources to servers
MAPHOSTNAME DNS - Set up mapping of IPs to hostnames
SESSION id# (PAUSE|DISCONNECT_GRACEFUL|FORCE_DISCONNECT) - Control a particular session
STAT (STOP SEND | SEND <host> <port> | (LISTEN (json|human) (overall|vhost=foo|backend=bar|source=baz|all|process|bufferpool))) - Output statistics
TLS (INGRESS | EGRESS) (KEY_FILE file | CERT_CHAIN_FILE file | RSA_KEY_FILE file | TMP_DH_FILE file | CA_CERT_FILE file | VERIFY_MODE mode* | CIPHERS (PRINT | SET ciphersuite(:ciphersuite)*))
VHOST PAUSE vhost | UNPAUSE vhost | PRINT | BACKEND_DISCONNECT vhost | FORCE_DISCONNECT vhost
The command represents authentication mechanism for connecting clients. By default all the clients will be allowed to connect to broker without any authentication. With the help of this command, one can set up an external HTTP auth service to authenticate clients, before allowing them to start communicating with broker. The schema structure for the HTTP auth service is defined here
Configures the external HTTP auth service to authenticate connecting clients.
For example: AUTH SERVICE localhost 1234 /auth?tier=dev will trigger queries to http://localhost:1234/auth?tier=dev when a client connects.
Stops authentication for connecting clients. So all clients will be allowed to connect to broker.
Prints information about current configured auth mechanism.
A backend represents an instance of an AMQP broker.
SEND-PROXY tells the proxy to send a Proxy protocol header, necessary if broker is configured to require such header i.e. only accept connections from proxies.
TLS tells the proxy to use a TLS-enabled connection with the broker.
datacenter can be used for datacenter affinity partitioning - prioritizing backends that are in the same datacenter as the proxy.
This adds a backend by hostname and port.
This adds a backend by address and port.
Deletes a backend by name. This does not affect existing connections to the deleted backend.
Prints the list of all configured backends in the format name (datacenter): host ip:port
Prints the list of all current connections along with some metrics.
Sets the name of the datacenter where this instance of amqpprox is running. Useful for using datacenter affinity partition policy.
Gracefully shut down amqpprox.
A farm represents a set of backends that a vhost can be mapped to. A client connecting to such vhost will be connected to one of the farm's backends chosen by the configured backend selector.
Adds a farm with selector backend selector. Accepts multiple backends by name as argument. Backends must be added beforehand using BACKEND ADD command.
Applies policy partition policy to the farm given by name. Partition policy allows backend selectors to prioritize backends. The policies are executed in the order they are applied, e.g. the output of the first partitioning policy is the input to the second policy. Applying a policy only affects new connections; existing connections remain with the same backend.
Deletes farm by name. This does not affect existing connections to the backends of the deleted farm.
Prints the list of farms registered with the proxy.
Prints command help text.
Apply limit on allowed average number of connections per second in alarm only mode for all the vhosts. So whenever the in-coming connection violates the limit, the proxy will only emit log at warning level with AMQPPROX_CONNECTION_LIMIT as a substring and the relevant limiter details, instead of actively limiting any actual connection.
Apply limit on allowed average number of connections per second in alarm only mode for specified vhost. The specific limit takes priority over the default limit for any vhost.
Apply limit on allowed average number of connections per second for all the vhosts. So whenever the in-coming connection violates the limit, the proxy will close that connection with appropriate error message and will not allow that client connection to connect to the broker.
Apply limit on allowed average number of connections per second for specified vhost. The specific limit takes priority over the default limit for any vhost.
Apply limit on allowed max bytes per second in alarm only mode for all the vhosts. So whenever any in-coming connection violates the data rate limit, the proxy will only emit log with Data Rate Alarm as a substring and the relevant limiter details, instead of actively limiting any data.
Apply limit on allowed max bytes per second in alarm only mode for specified vhost. The specific limit takes priority over the default limit for any vhost.
Apply limit on allowed max bytes per second for all the vhosts. So the data limit is enforced by counting the number of bytes read from the socket during each read operation, and pausing for one second before starting a read operation if the in-coming client connection violates the data.
Apply limit on allowed max bytes per second for specified vhost. The specific limit takes priority over the default limit for any vhost.
Remove default connection rate limit (allowed average number of connections per second) in alarm only mode for all the vhosts.
Remove specific connection rate limit (allowed average number of connections per second) for the specified vhost. The default limit will be applied to the specified vhost, if the default limit is already configured.
Remove default data rate limit (allowed max bytes per second) in alarm only mode for all the vhosts.
Remove specific data rate limit (allowed max bytes per second) for the specified vhost. The default data limit will be applied to the specified vhost, if the default data limit is already configured.
Print the configured limits in details for the specified vhost. If the vhostName is not specified, then the command will print all the configured default limits.
Starts listening for ingress (client => proxy) connections on the given port.
Starts listening for TLS-enabled ingress (client => proxy) connections on the given port. Use TLS commands to configure beforehand.
Stops listening on the given port. This does not affect existing sessions.
Verbosity argument is an integer 0..5 corresponding to {"FATAL", "ERROR", "WARN", "INFO", "DEBUG", "TRACE"}. For example, amqpprox_ctl /tmp/amqpprox/control LOG CONSOLE 5 sets console logging verbosity to TRACE.
Sets console logging verbosity.
Sets logfile logging verbosity.
There are two types of vhost mapping available:
- backend mapping;
- farm mapping.
Backend mapping maps vhost clients to a particular backend i.e. an AMQP broker instance. Farm mapping maps vhost clients to a farm - a set of backends. Clients will be connected to one of farm's backends depending on configured partitioning policies and backend selector.
Maps vhost to backend. Clients connecting to the vhost will be connected to the specified backend.
Maps vhost to farm given by name. Clients connecting to the vhost will be connected to one of the backends in the specified farm.
Unmaps vhost.
Sets the farm given by farmName as the default farm. If a vhost is not explicitly mapped, the default farm will be used.
Unsets default farm.
Prints the list of mappings.
Enables DNSHostnameMapper to do reverse DNS lookups on client addresses. Resolved hostnames will be injected into client properties sent to the broker. If not enabled, client IP address will be used instead of hostname.
A session represents a client's connection to a broker via the proxy, consisting of ingress (client => proxy) and egress (proxy => broker) connections. Session commands take session id as argument. Session id's can be found by running CONN.
Pauses a session. Proxy will stop processing incoming data from ingress (client => proxy).
Gracefully disconnects a session by sending a synthetic Connection.Close method to the client.
Forcefully disconnects a session by terminating both ingress and egress connections.
Adds a host:port endpoint to send metrics to. This currently does not support filtering the metrics.
Stops sending metrics to all configured endpoints.
Streams metrics to stdout. Pass json or human to specify output format. Metrics can be filtered by passing overall|vhost=foo|backend=bar|source=baz|all|process|bufferpool.
Disable internal collection of certain types of metrics. This is different from the filtering available under STAT LISTEN because this completely skips collection
of these metrics. Where possible, use this instead of filters.
At the moment, only STAT DISABLE per-source (or enable equivalent) is available.
TLS command is used to configure TLS-enabled connections for both ingress (client => proxy) and egress (proxy => broker). See TLS usage documentation.
Configures the private key to be used for ingress/egress connections.
Configures the PEM format certificate to be sent to the other party.
Configures the RSA private key to be used for ingress/egress connections.
Configures Diffie-Hellman parameters.
Configures the CA Certificate(s) used to verify the other party.
Configures the peer verification mode. Possible modes are PEER, NONE, FAIL_IF_NO_PEER_CERT, CLIENT_ONCE.
Prints configured allowed cipher set.
Configures allowed cipher set.
Pauses all sessions for the given vhost. New client connections are still accepted, but proxy will stop processing incoming data from ingress (client => proxy).
Connections for vhost paused during the handshake are resumed by connecting out to the appropriate broker. All other sessions for vhost are disconnected as though FORCE_DISCONNECT had been run.
Closes egress (proxy => broker) sockets for all sessions for the given vhost.
Closes both ingress (client => proxy) and egress (proxy => broker) sockets for all sessions for the given vhost.
Prints the list of vhosts and their paused/unpaused state.