Proxy routes

On this page

What a proxy route is#

A proxy route is a reverse proxy that forwards a public web address to one of your server's allocations. If you run a web service on your server, like a map such as Dynmap or BlueMap, a route gives it a clean HTTPS address instead of a raw IP and port. You manage routes on the Proxy Routes page, which the panel opens from your server's Networking area. The page header explains that routes can be path-based, subdomain-based, or use a custom domain you own, and a count chip next to the Routes heading shows how many you have.

Allocations are the IP and port pairs your server listens on, so the route needs to know which one to send traffic to. See Networking for how allocations and subdomains work.

Note: Proxy routes expose a web service to the public internet. If you want to link several of your own servers together on a private network instead, that is a separate feature. See Private networks.

Creating a route#

Click New Route to open the Create Proxy Route dialog. If you have no routes yet, the empty state offers a Create First Route button that does the same thing. First pick the allocation you want the route to forward traffic to, which is the internal port your web service is bound to. Then choose a route type. The type you pick decides what the public URL looks like and what you need to set up first, so the rest of the form changes to match your choice.

While the route is being created the button reads Creating..., and otherwise it reads Create Route. The new route appears in the list right away, though a custom domain will sit in a pending state until its DNS is verified.

Route types#

There are three route types, and the dropdown shows an example of each so you can tell them apart.

  • Path-based puts your service under a path on your active subdomain, for example /map. The path has to start with / and can only contain letters, numbers, hyphens, underscores, and slashes.
  • Subdomain gives your service its own subdomain under one of Pyro's domains (pyro.social or pyro.lgbt), for example map.myserver.pyro.social. You enter just the prefix, like map. The prefix can use lowercase letters, numbers, and hyphens, up to 63 characters.
  • Custom Domain uses a domain you own, for example maps.example.com. This type works on its own and does not need a subdomain. You can also set an optional path for it, which defaults to the root path if you leave it blank.
Note: Path-based and Subdomain routes both need an active subdomain on your server. Until you have one, those two options stay disabled in the dropdown and show a (requires subdomain) label, only Custom Domain is selectable, and a Subdomain Required banner appears below the routes list. Set a subdomain in Subdomain Management on the Networking page first.

Setting up a custom domain#

After you create a Custom Domain route, the panel marks it as needing verification and shows a DNS record to add at your registrar under a Domain Verification Required box. The record has three fields: a Type that tells you the record type to create, a Name for the host the record applies to, and a Value for where it should point.

Add the record at your registrar, then click Check Propagation. Once the record verifies, an SSL certificate is provisioned for the domain and the URL starts serving over HTTPS. The panel confirms this with a message that the domain was verified and SSL certificate provisioning will begin shortly. While that runs, the route shows a pending status badge.

Note: DNS changes take time to spread, so a check can come back not yet verified. The panel keeps retrying on its own for a while and shows the attempt count as Retry 1/3 on the route. Once those automatic attempts run out it offers a Retry Verification action in the route menu. Manual retries are rate-limited, and the route tells you how many minutes are left before the next one is allowed.

Once a domain is active, its certificate renews automatically. The route card shows when the certificate expires and turns that label amber if the date is within 30 days, but you do not need to renew it by hand.

Managing routes#

Each route appears as a card with its name, a status badge, and the internal target it forwards to under a Target label. Clicking the route name copies its full URL to your clipboard. The menu on the right of the card holds the actions for an existing route.

  • Edit Route changes which allocation the route forwards traffic to. The dialog shows the route's full URL for reference and lets you pick a different allocation. The route type and its address stay the same.
  • Enable Route or Disable Route turns the route on or off without deleting it. This is a separate menu action, not part of the edit dialog. A disabled route shows a Disabled badge and stops serving traffic.
  • Delete Route removes the route for good. The panel asks you to confirm first because this cannot be undone.

The status badge tells you where a route stands. A working route reads Active, an enabled route that is not yet serving reads Inactive, and a route you have turned off reads Disabled. Custom domain routes show their own verification and SSL status in the badge instead, such as while DNS is pending or a certificate is being issued.

Who can create and manage routes depends on the role you give each member, since creating, editing, and deleting routes are separate permissions. See Users and permissions.