@@ -0,0 +1,52 @@
1++++
2+title = "DNS Proxying"
3+weight = 2
4+template = "doc.html"
5++++
6+
7+We have a system that lets you request a domain name for their ship in the form of `ship.arvo.network`, where `ship` is your ship's name minus the `~`. This allows users to access their ships remotely using Landscape, our graphical web interface.
8+
9+Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.
10+
11+## Planets and Stars
12+
13+For a planet or star's DNS proxying request to be made and fulfilled, they must be hosting their ship someplace with a public IP address, and its HTTP server must be listening on port 80.
14+
15+To get `ship.arvo.network` on a planet or star, you must set up DNS routing with its parent ship by starting the `:dns` app.
16+To do so, simply run this command in your ship's Dojo:
17+
18+```
19+> :dns|request
20+```
21+
22+You'll then be prompted to enter the public IP address of your ship. You can also pass the IP address as an argument, using the .0.0.0.0 (`@if`) syntax. For example:
23+
24+```
25+> :dns|request .1.2.3.4
26+```
27+
28+`:dns`, running locally, will make an HTTP request to that IP address on port 80 to confirm that it is itself available at that IP and port. If that fails, you'll receive a `%bail-early` message in `:talk`; this request will retry a few times. If the self-check is successful, the request is relayed to `~zod`, and you'll receive a message saying, `request for DNS sent to ~zod`. Once `~zod` has acknowledged receipt of the request, your local `:dns` app will send a `:talk` message saying `awaiting response from ~zod`.
29+
30+The request will be picked up shortly, and the `ship.arvo.network` DNS record will be set to the given IP address. Once that's setup, `~zod` will be notified, and `~zod` will, in turn, notify your ship. That ship will now try to verify that it can reach itself on `ship.arvo.network` over port 80. If it can't, it'll send a message saying `unable to access via ship.arvo.network`. If it can, it will configure itself with that domain, and say `confirmed access via ship.arvo.network`.
31+
32+Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend using Chrome or Brave.
33+
34+## Galaxies
35+
36+Galaxies are already required to have separate DNS entry at galaxy.urbit.org. There's no automated process for getting that binding, so if you're a galaxy-holder, get in touch with us at support@urbit.org.
37+
38+There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:
39+
40+```
41+> :dns|auto
42+```
43+
44+This will make HTTP-requests to self-check availability over `galaxy.$AMES-DOMAIN` (currently galaxy.urbit.org), where `galaxy` is the galaxy's name minus the `~`.
45+
46+Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, talk messages, and so on.
47+
48+## More Information
49+
50+Configuring a ship's domain causes the `:acme` app to request an HTTPS certificate for that domain from LetsEncrypt. Note that LetsEncrypt also requires that the HTTP server be listening on port 80. If the certificate request fails, `:acme` will send a `:talk` message with an explanation. Once the certificate is successfully retrieved, `:acme` will install it, causing the HTTP servers to restart. A secure server will be started on port 443 (the HTTPS default) if it's available. Otherwise, it will try 8443, and then increment to the next port until it can successfully bind one.
51+
52+The built-in logic for listening on port 80 similar. Urbit tries to bind port 80; if it cannot, it tries 8080, then increments until it can bind a port. Port 80 is available to unprivileged process on recent version of macOS. Otherwise, the process needs to either be run as root, or be given special permission (CAP\_NET_BIND on Linux).