Listeners are the entry points to your UDP Gateway system. Think of a Listener as a virtual UDP server that receives packets from clients on the internet and forwards them to your AWS resources for processing. Each Listener provides you with a domain name and port number that your clients can connect to.
When you create a Listener, Proxylity automatically assigns it:
Once created, your Listener is immediately ready to receive UDP traffic from anywhere on the internet. Packets sent to your Listener's domain and port are automatically forwarded to the Destinations you've configured.
Select one transport for each Listener:
Listeners are typically connected to one or more Destinations, which define where incoming packets should be delivered in your AWS account. While a Listener without destinations won't process packets, you might keep such Listeners to preserve their assigned port numbers or for staging purposes. Destinations can be AWS services like:
You can add multiple Destinations to a single Listener, and you can change which Destinations are connected at any time without affecting your clients.
Listeners support their own MetricsEnabled, LogGroupName, and Role
properties, independently of destination observability. Set MetricsEnabled: true and
provide a listener observability role with cloudwatch:PutMetricData permission to publish
metrics with a Listener dimension. A listener role is also required when configuring logs.
Listener counters measure integration and protocol traffic. Ingress includes all datagrams admitted
by the firewall while the listener is not suspended, before protocol processing; firewall-denied and
suspended-listener datagrams count only as filtered. Egress includes every successfully sent datagram,
including application replies and Packet Source deliveries, using its transport-encoded length.
Enabling listener metrics also publishes separate Packet Source egress counters using the same role,
with dimension PacketSource set to the Packet Source's identifier (the value returned by Ref) and application bytes before
transport encoding. Destination metrics separately measure queued application deliveries, destination filtering, and replies.
These scopes overlap: do not sum listener and destination/source counters as unique traffic.
See the CloudWatch Metrics Reference for all seven metric
names, their meanings, counting rules, permissions, and examples, or the
Listener property reference for configuration.
An account can be suspended, for example when it exceeds the usage limit of its plan. Suspension applies to the whole account: while it is in effect, none of the account's listeners process traffic. A suspension may have an end date, or it may be indefinite.
Suspension is shown on the Proxylity dashboard. A banner on the dashboard home page gives the reason and, for a suspension with an end date, the date until which listeners will not process traffic. The banner links to your account page for more details and options.
Suspension is not shown anywhere in AWS. CloudFormation shows nothing: stacks and the Proxylity resources in
them look normal. While an account is suspended, the datagrams that reach its listeners are counted as
filtered (FilteredPackets and FilteredBytes) and not as ingress, and no log entry is
written. If a listener suddenly receives no traffic and its filtered counts rise, check the dashboard for a
suspension notice.
For security, each Listener includes Client Restrictions that control which IP addresses or networks are allowed to send packets to your Listener. This helps protect your AWS resources from unwanted traffic and potential abuse.
Client Restrictions can be configured to:
Listeners can be created and managed in two ways:
The preferred way to manage Listeners is through AWS CloudFormation using Proxylity's custom resource types. This approach provides:
To get started with CloudFormation, see our Getting Started guide and explore the working examples in our examples repository.
For quick testing, prototyping, or one-off configurations, you can also manage Listeners through the Proxylity Dashboard. From the web interface you can:
While Listeners are designed to receive inbound UDP traffic, sometimes your application needs to initiate UDP delivery to a client without waiting for an inbound packet. Packet Sources enable this by binding an SNS topic in your account to a Listener. Your application publishes to the SNS topic and Proxylity delivers the packets through the Listener's egress path — maintaining the same source IP and port that clients already know.
Packet Sources support plain UDP and WireGuard Listeners, with WireGuard requiring a peer
key for session selection and, when DecapsulatedDelivery is enabled, inner IP addressing for
re-encapsulation. See Packet Sources for full details.
When working with Listeners, keep these points in mind: