Proxylity

Listeners

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.

How Listeners Work

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.

Listener Transports

Select one transport for each Listener:

Listeners and Destinations

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.

Listener Metrics and Logs

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.

Account Suspension

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.

Client Restrictions

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:

Managing Listeners

Listeners can be created and managed in two ways:

Infrastructure as Code (Recommended)

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.

Dashboard

For quick testing, prototyping, or one-off configurations, you can also manage Listeners through the Proxylity Dashboard. From the web interface you can:

Packet Sources

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.

Important Considerations

When working with Listeners, keep these points in mind: