{"id":19168444,"url":"https://github.com/bloomberg/amqpprox","last_synced_at":"2025-07-01T11:05:56.296Z","repository":{"id":38093563,"uuid":"320663180","full_name":"bloomberg/amqpprox","owner":"bloomberg","description":"An AMQP 0.9.1 proxy server, designed for use in front of an AMQP 0.9.1 compliant message queue broker such as RabbitMQ.","archived":false,"fork":false,"pushed_at":"2024-12-17T18:30:38.000Z","size":698,"stargazers_count":79,"open_issues_count":5,"forks_count":17,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-26T03:10:50.027Z","etag":null,"topics":["amqp","amqp-proxy","amqp0-9-1","rabbitmq"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bloomberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-11T19:18:43.000Z","updated_at":"2025-03-07T01:29:42.000Z","dependencies_parsed_at":"2024-05-13T16:43:54.736Z","dependency_job_id":"38f7813a-4930-4e0e-bb69-2eaeab679e42","html_url":"https://github.com/bloomberg/amqpprox","commit_stats":{"total_commits":160,"total_committers":10,"mean_commits":16.0,"dds":0.66875,"last_synced_commit":"fd251f1e7a70a7eeba1bc6d16fbe419acbf1a4c0"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bloomberg/amqpprox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Famqpprox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Famqpprox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Famqpprox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Famqpprox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bloomberg","download_url":"https://codeload.github.com/bloomberg/amqpprox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bloomberg%2Famqpprox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262950339,"owners_count":23389640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amqp","amqp-proxy","amqp0-9-1","rabbitmq"],"created_at":"2024-11-09T09:42:40.857Z","updated_at":"2025-07-01T11:05:56.270Z","avatar_url":"https://github.com/bloomberg.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"#  amqpprox\n\namqpprox is an AMQP 0.9.1 proxy server, it is designed for use in front of an\nAMQP 0.9.1 compliant message queue broker such as RabbitMQ.\n\n## \n[![OpenSSF\nScorecard](https://api.securityscorecards.dev/projects/github.com/bloomberg/amqpprox/badge)](https://api.securityscorecards.dev/projects/github.com/bloomberg/amqpprox)\n\n## Menu\n\n- [Rationale](#rationale)\n- [Documentation](#documentation)\n- [Features](#features)\n- [Getting Started](#getting-started)\n- [Building](#building)\n- [Installation](#installation)\n- [Contributions](#contributions)\n- [License](#license)\n- [Future Ideas and Direction](#future-ideas-and-direction)\n- [Code of Conduct](#code-of-conduct)\n- [Security Vulnerability Reporting](#security-vulnerability-reporting)\n\n## Rationale\n\nCommonly people use HAProxy software acting as a load balancer to spread load\nbetween multiple machines within a serving cluster and handle failures\ngracefully. With amqpprox we built a similar proxy, except tailored\nspecifically for the AMQP 0.9.1 protocol. This brings benefits which cannot\nbe achieved with layer 4 proxying alone.\n\nThis proxy and how we use it was first publicly outlined in [this\ntalk](https://www.youtube.com/watch?v=tTh1nIKEOU4) at RabbitMQ Summit 2019, then\nreleased \u0026 introduced in detail in [this talk](https://www.youtube.com/watch?v=b2hQ8glQyhs)\nat RabbitMQ Summit 2021.\n\n### Key Advantages\n\n1. We can redirect different virtual hosts to different broker clusters\n2. We are able to understand/log AMQP 0.9.1 sessions passing through the proxy\n3. We can alter which brokers are connected to, in order to optimise network/datacenter\n   cross-traffic.\n4. We can get detailed statistics without relying on the RabbitMQ broker itself\n5. We can easily have clients test connection failovers locally\n\n## Documentation\n\n* [Overall architecture and code walkthrough](docs/architecture.md)\n* [Session relationship between incoming and outgoing connections](docs/sessions.md)\n* [How AMQP handshaking works in the proxy](docs/handshake.md)\n* [Overview of the TLS options](docs/tls.md)\n\n## Features\n\n- [X] No dependencies: config is pushed into it, does nothing by default\n- [X] Unix domain socket for control plane operations\n- [X] Allow switching connections between farms per vhost\n- [X] Load balancing between the farm members\n- [X] Resources (vhosts) can be pointed at DNS farms, not just IPs\n- [X] Statistics about each interaction\n- [X] Able to easily test client failover by severing connections on demand\n\n\n## Getting Started\n### Quick Start \n\nThis guide assumes you have amqpprox [building](#building), and a RabbitMQ broker running on `localhost:5672`.\n\n`amqpprox` can be started with a few command line arguments to start in a simple one mapping mode:\n\n```\n$ amqpprox --consoleVerbosity 5 --destinationDNS localhost --destinationPort 5672 --listenPort 5673\nStarting amqpprox, logging to: 'logs' control using: '/tmp/amqpprox'\nTRACE: Session cleanup starting\nTRACE: Clean up finished with no sessions to clean up\n...\u003csnip\u003e...\n```\n\nYou can then connect your RabbitMQ client via `localhost:5673` and `amqpprox`\nwill proxy all connections into `5673` to the running broker on `5672`. Until\nyou make a connection you won't see much other than periodic cleanup trace, but\nyou can interact with it fully through the `amqpprox_ctl` interface.\n\nThis mode is designed for simple use cases where a user is using only one vhost or\nwants to do local-only testing.\n\n### Getting Started With `amqpprox_ctl` commands\n\n`amqpprox` is the core proxy executable. By default it starts up with no mapped\nvhosts/broker backends/listening ports/other configuration. `amqpprox_ctl` is\nused to provide configuration before telling it to begin listening. See [amqpprox_ctl documentation](https://github.com/bloomberg/amqpprox/blob/main/docs/config.md).\n\n### Start `amqpprox`\n```\n$ amqpprox --help\namqpprox AMQP v0.9.1 proxy:\n\nThis is a proxy program for AMQP v0.9.1, designed to sit in front of a RabbitMQ\ncluster. Most options for configuring the proxy and introspecting its state are\navailable through the amqpprox_ctl program, begin by sending 'HELP' to it.\n\nThis program supports the following options to allow running multiple instances\non a machine and a simplified configuration mode. In the simplified\nconfiguration mode the --listenPort, --destinationDNS and --destinationPort\nmust all be specified, and after which it immediately starts listening on all\ninterfaces for that port and sends all vhosts to the destination DNS entry.\nMore complicated configuration, such as sending different vhosts to different\ndestinations, necessitates the use of the amqpprox_ctl.\n\nAlthough most configuration is injected by the amqpprox_ctl program, the\nlogging directories and the control UNIX domain socket are specified on this\nprogram, to facilitate safely running multiple instances of amqpprox on a\nsingle host.  \n:\n  --help                               This help information\n  --logDirectory arg (=logs)           Set logging directory\n  --controlSocket arg (=/tmp/amqpprox) Set control UNIX domain socket location\n  --cleanupIntervalMs arg (=1000)      Set the cleanup interval to garbage\n                                       collect connections\n  --listenPort arg (=0)                Simple config mode: listening port\n  --destinationPort arg (=0)           Simple config mode: destination port\n  --destinationDNS arg                 Simple config mode: destination DNS\n                                       address\n  -v [ --consoleVerbosity ] arg (=0)   Default console logging verbosity (0 =\n                                       No output through to 5 = Trace-level)\n                                       \n$ amqpprox\nStarting amqpprox, logging to: 'logs' control using: '/tmp/amqpprox'\n```\n\n### `amqpprox_ctl` Example Usage\n\n```sh\n$ amqpprox_ctl --help\nUsage: amqpprox_ctl \u003ccontrol_socket\u003e ARGS\n```\n\n`amqpprox` responds to HELP\n\n```\n$ amqpprox_ctl /tmp/amqpprox HELP\nAUTH (SERVICE hostname port target | ALWAYS_ALLOW | PRINT) - Change authentication mechanism for connecting clients\nBACKEND (ADD name datacenter host port [SEND-PROXY] [TLS] | ADD_DNS name datacenter address port [SEND-PROXY] [TLS] | DELETE name | PRINT) - Change backend servers\nCONN Print the connected sessions\nDATACENTER SET name | PRINT\nEXIT Exit the program gracefully.\nFARM (ADD name selector backend* | PARTITION name policy | DELETE name | PRINT) - Change farms\nHELP Print this help text.\nLIMIT (CONN_RATE_ALARM | CONN_RATE) (VHOST vhostName numberOfConnections | DEFAULT numberOfConnections) - Configure connection rate limits (normal or alarmonly) for incoming clients connections\nLIMIT (DATA_RATE_ALARM | DATA_RATE) (DEFAULT | VHOST vhostName) BytesPerSecond - Configure data rate limits or alarms for incoming client data\nLIMIT DISABLE (CONN_RATE_ALARM | CONN_RATE | DATA_RATE_ALARM | DATA_RATE) (VHOST vhostName | DEFAULT) - Disable configured limit thresholds\nLIMIT PRINT [vhostName] - Print the configured default or specific connection rate limits for specified vhost\nLISTEN START port | START_SECURE port | STOP [port]\nLOG CONSOLE verbosity | FILE verbosity\nMAP (BACKEND vhost backend | FARM vhost name | UNMAP vhost | DEFAULT farmName | REMOVE_DEFAULT | PRINT) - Change mappings of resources to servers\nMAPHOSTNAME DNS - Set up mapping of IPs to hostnames\nSESSION  id# (PAUSE|DISCONNECT_GRACEFUL|FORCE_DISCONNECT) - Control a particular session\nSTAT (STOP SEND | SEND \u003chost\u003e \u003cport\u003e | (LISTEN (json|human) (overall|vhost=foo|backend=bar|source=baz|all|process|bufferpool))) - Output statistics\nSTAT (DISABLE|ENABLE) per-source - Enable/Disable internal collection of per-source statistics. Applies to all send/listeners\nTLS (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)*))\nVHOST PAUSE vhost | UNPAUSE vhost | PRINT | BACKEND_DISCONNECT vhost | FORCE_DISCONNECT vhost\n```\n\nConfigure `amqpprox` how to talk to an AMQP 0.9.1 backend called `rabbit1`, labelled as datacenter `london-az1`, running on `localhost:5672` without TLS/Proxy Protocol.\n```\n$ amqpprox_ctl /tmp/amqpprox BACKEND ADD rabbit1 london-az1 localhost 5672\n$ amqpprox_ctl /tmp/amqpprox BACKEND PRINT\nrabbit1 (london-az1): localhost 127.0.0.1:5672\n```\n\nConfigure `amqpprox` to map inbound connections for `vhost-example` to backend `rabbit1`\n```\n$ amqpprox_ctl /tmp/amqpprox MAP BACKEND vhost-example rabbit1\n$ amqpprox_ctl /tmp/amqpprox MAP PRINT\n\"vhost-example\" =\u003e Backend:rabbit1\n```\n\n`amqpprox` now understands one vhost mapping. Use `LISTEN` to start listening for connections on port 5673:\n\n```\n$ amqpprox_ctl /tmp/amqpprox LISTEN START 5673\n```\n\nAn AMQP 0.9.1 client can now connect to `vhost-example` on port 5673 and `amqpprox` will forward to `rabbit1` on port 5672.\n\n\n## Building\n\nThe default build uses the Conan package manager, make, cmake and will require\na C++17 compiler. These should be installed prior to doing the native build,\nand conan will download the other dependencies during setup.\n\nOnce you have set up the build dependencies on your machine, the project should\nbe buildable with the following commands:\n\n1. `make setup` - This will initialise your Conan environment and create the build\n   directory. It should only needs to be run the first time you are setting up\n   a build, except when bumping the dependency versions.\n2. `make init` - This will do the cmake initialisation, so should be run when\n   changing the files included in the project, or the build system.\n3. `make` - This will run an incremental build and unit-test\n\nWe also provide Dockerfiles for building and running in an isolated\nenvironment, these are directly analogous to the above commands. If you don't\nwish to get Conan set up on your build machine, this can be an alternative\nquick way to get going.\n\n1. `make docker-setup`\n2. `make docker-init`\n3. `make docker-build`\n4. `make docker-shell`: Get an interactive shell within the build environment\n   container.\n\nThere are a number of options exposed through the build system, they're\ndocumented on the [buildfiles README](buildfiles/README.md).\n\nWe only recommend using Linux based operating systems for running amqpprox;\nhowever, we also regularly develop it on Mac OS and expect changes to not break\nthe native build there.\n\nBy default the build doesn't contain debug symbols, for Debug one can make use of the \n`CMAKE_EXTRA_ARGS='-DCMAKE_BUILD_TYPE=Debug'` environment, for Release optimisations \none can set this to `CMAKE_EXTRA_ARGS='-DCMAKE_BUILD_TYPE=Release'` \n\nWe can also generate doxygen documentation for C++ classes.\n- `make docs`: This command will run doxygen, which is currently configured to dump generated files into `generated-docs/`.\n\n## Installation\n\nAt present we do not provide any pre-built releases and we expect users to\nbuild from source. If you are interested in having a pre-built release for your\npreferred package management system, please open an [issue](../../issues/new/choose) letting us know.\n\n## Contributions\n\nWe :heart: contributions.\n\nHave you had a good experience with amqpprox? Why not share some love and contribute code, or just let us know about any issues you had with it?\n\nWe welcome issue reports [here](../../issues/new/choose); be sure to choose the proper issue template for your issue, so that we can be sure you're providing the necessary information.\n\nBefore sending a [Pull Request](../../pulls), please make sure you read our\n[Contribution Guidelines](https://github.com/bloomberg/.github/blob/master/CONTRIBUTING.md).\n\n## License\n\nPlease read the [LICENSE](./LICENSE) file.\n\n## Future Ideas and Direction\n\n- [ ] Support for RabbitMQ Stream binary protocol\n- [ ] Introducing `SO_REUSEPORT` to scale up on one host\n- [ ] Traffic throttling/shaping per vhost/session/connection\n- [ ] Automatic connection teardown/moving when an IP endpoint leaves the farm\n- [ ] Be able to capture or trace more selectively\n- [ ] Utilise io_uring for more efficient asynchronous networking\n\n## Code of Conduct\n\nThis project has adopted a [Code of Conduct](https://github.com/bloomberg/.github/blob/master/CODE_OF_CONDUCT.md).\nIf you have any concerns about the Code, or behavior which you have experienced in the project, please\ncontact us at opensource@bloomberg.net.\n\n## Security Vulnerability Reporting\n\nIf you believe you have identified a security vulnerability in this project, please send email to the project\nteam at opensource@bloomberg.net, detailing the suspected issue and any methods you've found to reproduce it.\n\nPlease do NOT open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until\nwe've had an opportunity to review and address them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Famqpprox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbloomberg%2Famqpprox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbloomberg%2Famqpprox/lists"}