Skip to main content

Managing Wormholes

A constellation is a secure area in which you can deploy your applications. You can take comfort in the notion that nothing from the public internet can access your resources unless you choose to allow it. A wormhole is the mechanism by which you allow traffic to enter your constellation from the Internet.

Creating a Wormhole​

Creating a wormhole involves clicking the Wormhole+ icon in the tool palette while on the logical view of the constellation canvas. Upon clicking this, you will be presented a dialog like the following:

Add Wormhole
Add Wormhole

There will be two drop-down lists. The first, actor, will draw from a list of all actors currently running in the constellation that are granted the wasmcloud:httpserver capability that are bound to an instance of the HTTP Server - Wormhole provider (note there can be multiples of these on a given canvas if they differ by link name). Clicking Create Wormhole will create the wormhole in the open state. That is, it will be immediately accessible.

Removing and Closing Wormholes​

If you delete (remove) a wormhole, it will be forever gone and you will lose the host name associated with it. In the following screenshot from the wormhole details panel, you can see that the host name is silent-glitter-5370:

Wormhole Details
Wormhole Details

Because of this, you will want to be very careful when deleting wormholes, especially if you have already set up your own custom domain pointing to this host. If you want to stop inbound traffic to your constellation, but you want to retain your claim to the host name, you can click the Close Wormhole button. Once closed, for security reasons, a wormhole will reject incoming traffic, pretending as though it doesn't exist to the outside Internet - you don't want people to be able to tell the difference between closed and non-existent wormholes when probing for weaknesses.

Setting a custom Wormhole name​

When you create a wormhole, Cosmonic will generate a random human-readable name for it. If you want to set a custom name, you can do so by clicking the Edit Wormhole button in the wormhole details panel. This will bring up a window where you can set the name, provided it isn't already in use by another wormhole and it passes rules for a valid DNS subdomain.

Edit Wormhole
Wormhole Details
warning

With great power comes great responsibility. The creation of custom wormhole names that include deceptive or offensive language is strictly prohibited. Cosmonic reserves the right to remove any wormhole that violates this policy.

Using a custom domain​

Cosmonic wormholes support custom domains by using an external CNAME record pointed at a wormhole's A record. When your CNAME is setup, and the wormhole is configured, we are able to provision a certificate for the domain via ACME HTTP

Please follow these steps to setup a custom domain:

  • edit the wormhole and set its name to something meaningful
    • ex: example-test-appname
  • add a CNAME in your DNS provider
    • ex: cname.example.com with a record value of example-test-appname.cosmonic.app
  • edit the wormhole and enter cname.example.com in the custom domain field and click confirm
Edit Wormhole
Wormhole Details
note

Validation of the CNAME occurs after you click confirm Please make sure to configure the CNAME before you set the custom domain to avoid delays

To remove a custom domain, simply edit the Wormhole Custom Domain field to be empty and click confirm

Authenticated Wormholes​

If you want to require an authorization header to access your wormhole, then you can click the require authentication option. Once you do this, Cosmonic will generate a bearer token on behalf of this wormhole. You can then copy that token to a clipboard and supply it in the HTTP Authorization header to obtain authentication.

Sign up for updates

Make sure to stay abreast of all of the Cosmonic news to be informed when new wormhole features, authentication modes, and content types become available.