@@ -1,70 +1,61 @@
11+++
2−title = "Operations"
2+title = "Using Your Ship"
3+description = "How to operate your ship, including using your ship's filesystem and messaging applications, starting a moon, or requesting a DNS proxy."
34template = "page_indiced.html"
4−slug = "/operations/"
5+weight = 2
6+aliases = ["docs/using/arvo-network-dns/", "docs/using/messaging/", "docs/using/shell/", "docs/using/admin/"]
57+++
68
7−## Using Bridge {#using-bridge}
8−
9−[Bridge](https://github.com/urbit/bridge) is the application we built for interacting with [Azimuth](https://azimuth.network), the Urbit PKI, and managing your Urbit ID. Importantly, Bridge also allows you to generate a keyfile that you will need to boot your ship so that it can use the Arvo network.
10−
11−This guide assumes that you have an Urbit ID, or that you have found someone to send an Urbit ID to your Ethereum address and are looking to claim it.
12−
13−### Online Bridge
14−
15−To connect to Bridge, go to [https://bridge.urbit.org](https://bridge.urbit.org) into your browser, and enter your identity's credentials in the appropriate fields. If you were invited to claim an Urbit ID, it's very likely that you received an email that would direct you to Bridge, and you can simply follow the hyperlink in that email.
16−
17−Once you arrive, proceed through the steps presented. You'll eventually arrive at a page with a few choices: `Invite`, `Admin`, and `Boot Arvo`. `Admin` is the only option that you're interested in right now; click on it. On the `Admin` page, click the `Download Arvo Keyfile` button. Once you have downloaded the keyfile, you can exit Bridge and proceed to [install the Urbit binary](@/install.md).
9+## DNS proxying {#dns-proxying}
1810
19−### Offline Bridge
11+We have a system that lets you request a domain name for your 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.
2012
21−Alternatively, Bridge can be run locally. It's more complicated, but we recommend this option for managing sufficiently valuable assets, such as several stars or more. To install local Bridge, navigate to the [release page on GitHub](https://github.com/urbit/bridge/releases/). Download the `.zip` file of the latest version. After you download it, follow the instructions below.
13+Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.
2214
23−To use Bridge:
15+### Planets and Stars
2416
25−- Unzip the .zip file that you downloaded (bridge-$version.zip).
26−- Open up your command line interface (Terminal on OSX, Command Prompt on Windows).
27−- Navigate to the bridge-$version directory, where $version is the appropriate version number.
28−- Run this command: `python3 -m http.server 5000 --bind 127.0.0.1.`
17+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.
2918
30−You can then use the Bridge app by navigating to `http://localhost:5000` in your internet browser.
19+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.
3120
32−Note: Bridge allows you to both make reads and writes to the Ethereum blockchain. Writing to the blockchain, such as changing your networking keys, will incur a transaction cost that will require you to have some ETH in your address.
21+To do so, simply run this command in your ship's Dojo:
3322
34−Once the program is running in your browser, go through the steps presented according to the type of wallet you have. You’ll be presented with a few login options. A notable option is Urbit Master Ticket. This is for those who used our Wallet Generator software. If you bought points from an Urbit sale and then used the Wallet Generator, your networking keys will be set for you. All other login options will require you to set your own networking keys.
23+```
24+> :dns|request
25+```
3526
36−### Accept your transfer
27+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:
3728
38−If you were given points by Tlon you likely already fully own them. But if someone else sent you a point, then you will first need to use Bridge to accept that transfer.
29+```
30+> :dns|request .1.2.3.4
31+```
3932
40−After you access your Ethereum address, if a point was sent to that address, you'll come to a page that has an `Incoming Transfers` header, under which is a graphic. Click the `Details ->` link under that graphic.
33+`: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 `:chat-cli`; 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 `:chat-cli` message saying `awaiting response from ~zod`.
4134
42−Now you'll be on the management page of your point. The transfer isn't completed yet, so click `Accept incoming transfer`. Then check both boxes and and click their associated `Sign Transaction` and `Send Transaction` buttons.
35+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 set up, `~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`.
4336
44−If you already own a point, click on the `Details ->` under your sigil in the `Your Points` section.
37+Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
4538
46−### Set your networking keys
39+### Galaxies
4740
48−If you just accepted a point, you'll be returned to your point screen. Notice that that links and buttons are now clickable. You now own this point!
41+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.
4942
50−Click the link that says `Set network keys`. The field presented in the resulting page expects a 32-byte hexadecimal string. If it's filled already, no action is required. If it is empty, you will need to generate such a string. You can generate this data any way you please, but in the terminal on MacOS or Linux, you can write
43+There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:
5144
52−```sh
53−hexdump -n 32 -e '4/4 "%08X"' /dev/random
45+```
46+> :dns|auto
5447```
5548
56−and use the result.
49+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 `~`.
5750
58−It should be noted that setting your network keys is an event on the Ethereum network and will therefore cost a trivial, but non-zero, amount of [gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
51+Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, Chat messages, and so on.
5952
60−### Generate your keyfile
53+### More information
6154
62−From the detail page associated with your point, click the `Generate Arvo Keyfile` link and you'll be taken to a page with a field titled `Network seed`. This field should already be filled in, and should match the hexadecimal string that you entered in the previous step. If it's not filled in or does not match, fill it in with the correct string.
63−Click `Generate ->`, which will download a keyfile onto your machine.
55+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 `:chat-cli` 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.
6456
65−With that keyfile in hand, you can now exit Bridge and continue to the guide to [install the Urbit binary](@/install.md).
57+The built-in logic for listening on port 80 is 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).
6658
67−## Using your ship {#urbit-administration}
6859
6960Your urbit (also called your _ship_) is a persistent Unix process that you mainly control from the console.
7061
@@ -201,7 +192,7 @@ moon: ~faswep-navred-sampel-palnet
201192
202193`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key` and does not need editing to be used with the `-k` option.
203194
204−You can use the resulting output in the same installation flow from the [Installing Urbit](@/install.md) guide, following the same scheme as for booting a planet. That scheme is:
195+You can use the resulting output in the same installation flow from the [Installing Urbit](@/using/install.md) guide, following the same scheme as for booting a planet. That scheme is:
205196
206197```sh
207198$ ./urbit -w <moonname> -G <key> -c <piername>
@@ -238,82 +229,6 @@ Because Urbit networking is stateful we call this a _continuity breach_. Everyth
238229
239230When this happens, back up any files you'd like to save, shut down your urbit, and recreate it (as if you were starting for the first time).
240231
241−## Creating a comet {#creating-a-comet}
242−
243−**Comets** are urbits whose names are 128-bits or 16 syllables, such as:
244−
245−`~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`
246−
247−Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network.
248−
249−### Booting a comet
250−
251−To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:
252−
253−```sh
254−$ ./urbit -c mycomet
255−```
256−
257−This will take a few minutes and will spin out a bunch of boot messages. Toward the end, you'll see something like:
258−
259−```
260−ames: on localhost, UDP 31337.
261−http: live (insecure, public) on 8080
262−http: live ("secure", public) on 8443
263−http: live (insecure, loopback) on 12321
264−~dasres_marzod:dojo>
265−```
266−
267−## DNS proxying {#dns-proxying}
268−
269−We have a system that lets you request a domain name for your 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.
270−
271−Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.
272−
273−### Planets and Stars
274−
275−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.
276−
277−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.
278−
279−To do so, simply run this command in your ship's Dojo:
280−
281−```
282−> :dns|request
283−```
284−
285−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:
286−
287−```
288−> :dns|request .1.2.3.4
289−```
290−
291−`: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 `:chat-cli`; 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 `:chat-cli` message saying `awaiting response from ~zod`.
292−
293−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 set up, `~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`.
294−
295−Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
296−
297−### Galaxies
298−
299−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.
300−
301−There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:
302−
303−```
304−> :dns|auto
305−```
306−
307−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 `~`.
308−
309−Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, Chat messages, and so on.
310−
311−### More information
312−
313−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 `:chat-cli` 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.
314−
315−The built-in logic for listening on port 80 is 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).
316−
317232## Messaging {#messaging}
318233
319234Let’s get started using the `:chat-cli` application, also known more simply as _Chat_. It's the simplest way to talk to people using the command line interface.