@@ -8,16 +8,20 @@ aliases = ["docs/using/messaging/", "docs/using/admin/"]
88hidetitle = "true"
99+++
1010
11−Your urbit (also called your _ship_) is a persistent Unix process that you
12−mainly control from its console, called the `dojo`.
11+This document deals with:
1312
14−### Shutdown
13+- Running an Urbit ship with the ordinary runtime [from the command line](/getting-started/cli).
14+- Basic setup, configuration and usage in Urbit's shell called the `dojo`.
15+
16+If you're looking for information on using the GUI application [Port](/getting-started#port), see the [Port guide](/using/running/port) instead.
17+
18+## Shutdown
1519
1620You can turn your urbit off with `Ctrl-d` from the Chat or Dojo prompts.
1721
1822You can force-quit your urbit with `Ctrl-z` from anywhere.
1923
20−### Restart
24+## Restart
2125
2226To restart your urbit simply pass the name of your pier:
2327
@@ -31,7 +35,7 @@ or
3135$ ./urbit comet
3236```
3337
34−### Logging
38+## Logging
3539
3640To log an urbit's command line output to a file, use `script`:
3741
@@ -39,7 +43,7 @@ To log an urbit's command line output to a file, use `script`:
3943$ script urbit.log ./urbit your-urbit
4044```
4145
42−### Moving your pier
46+## Moving your pier
4347
4448Piers are designed to be portable, but it _must_ be done while the urbit
4549is not running. Urbit networking is stateful, so you can't run two copies
@@ -66,13 +70,13 @@ Delete the tar file, and, after installing Urbit on your new server, start your
6670./urbit your-urbit
6771```
6872
69−### Hardware requirements
73+## Hardware requirements
7074
7175Urbit can run on any x86 computer (unofficial, unsupported [ARM binaries](https://botter-nidnul.github.io/AArch64_Urbit_Static_Binaries.html) are also available), ideally with at least 2GB of RAM.
7276
7377Urbit maintains a persistent log of the history of your ship. Eventually this log will be automatically trimmed when necessary, but for now it only increases in size. An actively used planet will consume 5-50 GB of storage space per year of operation.
7478
75−### Console
79+## Console
7680
7781Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.
7882
@@ -107,13 +111,13 @@ Ctrl-u Kill to beginning of line
107111Ctrl-y Yank from kill buffer
108112```
109113
110−### Updates
114+## Updates
111115
112−By default, you will automatically receive updates ([OTAs](/docs/glossary/ota-updates)) from your sponsor. To check your OTA source, run `|ota` in the [dojo](/docs/glossary/dojo).
116+By default, your `%base` [desk](/docs/glossary/desk) (which contains the [Arvo](/docs/glossary/arvo) kernel and core apps) receives updates ([OTAs](/docs/glossary/ota-updates)) from your sponsor. Other desks will receive updates from their respective publishers. To check the OTA source for each desk, run `+vats` in the [dojo](/docs/glossary/dojo). It will print out details for each desk - the `source` field shows which ship the desk gets updates from and the `updates` field shows `tracking` if automatic updates are enabled.
113117
114−If for some reason (for example, if your sponsor is out of date), you can switch OTA sources by running `|ota ~otasrc %kids` in the dojo, where `~otasrc` is the ship from which you want to receive updates. It is a good idea to contact the source ship and ask permission to sync from them.
118+If for some reason updates are not enabled or the current source is not online or up to date, you can enable updates or change source with the `|install` command.
115119
116−If OTAs are not succeeding, or if you are on an version of Urbit before the `|ota` command was introduced, you can run `|merge %home (sein:title our now our) %kids, =gem %take-that`. **Note:** This will wipe out any custom changes to the base distribution.
120+`|install (sein:title our now our) %landscape` will enable updates to the `%landscape` desk from your sponsor. `|install ~some-ship %landscape` will enable updates to the landscape desk from whatever ship is specified in place of `~some-ship`. For third party apps, make sure to correctly specify the publisher's ship. Each desk's updates are managed separately, so you'll need to run this for each desk separately. For the `%base` desk specifically, you sync from `%kids` rather than `%base` on the remote ship, so must specify it like `|install (sein:title our now our) %kids, =local %base`.
117121
118122#### Additional OTA Troubleshooting
119123
@@ -124,65 +128,41 @@ Please check the Support Wiki for additional OTA troubleshooting, such as:
124128OTAs](https://github.com/urbit/support/wiki/Stuck-flow-preventing-planets-from-receiving-OTAs),
125129and [No content shows in Links page after OTA](https://github.com/urbit/support/wiki/No-content-shows-in-Links-page-after-OTA).
126130
127−### Landscape
131+## Web interface
128132
129−On startup Urbit tries to bind to `localhost:80`. If you're already running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit that you just started on `8080`, `8081`, and so on. For planets only, we also provide web domains through Urbit's own domain. Any planet `~your-urbit` is also at `your-urbit.arvo.network`, but only after you [set up DNS](#dns-setup).
133+On startup, urbit tries to bind to `localhost:80`. If you're already running something on port `80`, or your host OS will not allow urbit to bind port `80`, urbit will try `8080`, then `8081`, `8082`, and so on. For planets only, we also provide subdomains of `arvo.network` for free. Any planet `~your-urbit` is also at `your-urbit.arvo.network`, but only after you [set up DNS](#dns-setup).
130134
131−Once running, you can sign into Landscape, your ship’s web interface, from `http://localhost` or `https://your-urbit.arvo.network`. Since our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.
135+Once running, you can sign into your ship’s web interface from `http://localhost` (if bound to port `80`), `http://localhost:8080` (if bound to port `8080`), or `https://your-urbit.arvo.network` if you've set up DNS.
132136
133−### Moons {#moons}
137+## Moons {#moons}
134138
135−Planets can spawn moons, which are meant for connected devices: phones, smart TVs, digital thermostats. The basic idea is that your planet runs permanently in a data center somewhere, while moons run on all your devices. Each planet can issue ~4 billion (`2^32`) moons.
139+Planets can spawn moons, which are conceptually meant for connected devices: phones, smart TVs, digital thermostats. The basic idea is that your planet runs permanently in a data center somewhere, while moons run on all your devices. Each planet can issue ~4 billion (`2^32`) moons.
136140
137141To generate a random moon from your planet, run:
138142
139143```
140144~sampel-palnet:dojo> |moon
141145moon: ~faswep-navred-sampel-palnet
142−\/0w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SI\/
143− EUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1
144−\/ \/
146+0w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SIEUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1
145147```
146148
147−You must manually edit the output of `|moon` to get the correct format for the `key`:
148−
149−- strip out the `\/`
150−
151−- combine into one line, omitting spaces
152−
153−`key` would be `0w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SIEUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1`
154−in this example.
155−
156−Put `key` in a file and that file becomes `keyfile`.
157−
158−You can use the resulting output in the same installation flow from the [Installing Urbit](/getting-started/) guide, following the same scheme as for booting a planet. That scheme is:
159−
160−```sh
161−$ ./urbit -w <moonname> -G <key> -c <piername>
162−```
163−
164−or
165−
166−```sh
167−$ ./urbit -w <moonname> -k <keyfile> -c <piername>
168−```
149+The `moon:` part is the name of the moon, in this case `~faswep-navred-sampel-palnet`. The next line starting with `0w5...` is the private key necessary to boot it.
169150
170−The `-c <piername>` argument is not required, but it is recommended; otherwise,
171−the resulting directory is a rather unwieldy moon name.
151+You can just copy the key (which in this case would be the `0w5[...]600g1` part) to the clipboard, or save it in a `.key` file, for example `faswep-navred-sampel-palnet.key`.
172152
173−Here's how an example moon might be booted:
153+You can use the key and moon name in the same installation flow from the [Command line installation](/getting-started/cli) guide, following the same scheme as for booting a planet. That scheme is:
174154
175155```sh
176−$ ./urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
156+$ ./urbit -w <moon-name> -G <key> -c <pier-name>
177157```
178158
179159or
180160
181161```sh
182−$ ./urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
162+$ ./urbit -w <moon-name> -k <key-file> -c <pier-name>
183163```
184164
185−Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.
165+Note the `<moon-name>` excludes the leading `~`. The `-c <piername>` argument is not required, but it is recommended; otherwise, the resulting directory is a rather unwieldy moon name. Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.
186166
187167To breach a moon -- that is, to reset its presence on the network so that it's treated as a freshly spawned ship by others -- run from the parent ship:
188168
@@ -193,10 +173,12 @@ To breach a moon -- that is, to reset its presence on the network so that it's t
193173To cycle the keys of a moon without breaching, run:
194174
195175```
196−|moon-cycle-keys ~sampel-sipnym-wicdev-wisryt
176+|moon-cycle-keys ~faswep-navred-sampel-palnet
197177```
198178
199−### Escaping A Sponsor {#escape}
179+You can then run `|rekey` on the moon with the key given by the above command as the argument.
180+
181+## Escaping A Sponsor {#escape}
200182
201183To use the network as a planet or star, you must be sponsored by an active star
202184or galaxy, respectively. If your sponsor isn't suiting your needs, you can
@@ -204,55 +186,35 @@ escape to a different one. This can be done with
204186[Bridge](https://bridge.urbit.org/) following the instructions
205187[here](/using/id/using-bridge#escaping-your-sponsor).
206188
207−### Continuity breaches
208−
209−While the Urbit network is in this alpha state, we sometimes have to reboot the whole network. This happens either when major changes need to be shipped or we hit a bug that can't be fixed over the air.
210−
211−Because Urbit networking is stateful we call this a _continuity breach_. Everything has to be restarted from scratch. Your pier will continue to function after we have breached, but it won’t connect to the rest of the Urbit network.
212−
213−When 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).
214−
215−### Life and rift number
189+## Life and rift number
216190
217191You can check your ship's _life_ and _rift_ number by running `+keys our` in
218192dojo. You can inspect another ship's life and rift number by running `+keys ~sampel-palnet`. For information on what life and rift are, see [Life and Rift](/docs/azimuth/life-and-rift).
219193
220194## DNS setup {#dns-setup}
221195
222−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.
223−
224−Stars and planets follow the same process DNS request process, and galaxies have their own requirements. Moons and comets are not supported.
225−
226−### Planets and Stars
196+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. Stars and planets follow the same DNS request process, and galaxies have their own requirements. Moons and comets are not supported.
227197
228198For a planet or star's DNS 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.
229199
230−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.
231−
232−To do so, simply run this command in your ship's Dojo, passing the IP address as an argument, using the .0.0.0.0 (`@if`) syntax. For example:
200+To initiate a DNS request, run the following thread in your ship's dojo, passing the IP address as an argument with .0.0.0.0 (`@if`) syntax. For example:
233201
234202```
235−> -dns-address &dns-address [%if .1.2.3.4]
203+-dns-address [%if .1.2.3.4]
236204```
237205
238−`: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`.
206+The `%dns-address` thread, 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 `couldn't access ship on port 80` message in the terminal; 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, the `%dns-address` thread will print a terminal message saying `awaiting response from ~zod`.
239207
240−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`.
208+The request will make take a little time to be fulfilled, but eventually 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`.
241209
242210Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
243211
244212### Configuring SSL
245213
246−To enable SSL on your ship, use the `acme` agent, which will request a certificate through Let's Encrypt. First, make sure the agent is started:
214+To enable SSL on your ship, you must poke the `%acme` agent with the domain encoded in a path and it will request a certificate. The path format is `/tld/your_domain/your_subdomain`, so if your domain is `sampel-palnet.arvo.network`, you'd use it like so:
247215
248216```
249−> |start %acme
250−```
251−
252−Next, provide the path for the SSL certificate by poking the `acme` agent. The path format is `/tld/your_domain/your_subdomain`, so if your domain is `sampel-palnet.arvo.network`, you'd use it like so:
253−
254−```
255−> :acme &path /network/arvo/sampel-palnet
217+:acme &path /network/arvo/sampel-palnet
256218```
257219
258220### Galaxies
@@ -267,69 +229,8 @@ There is a command for galaxies that will try to re-use their already-necessary
267229
268230This 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 `~`.
269231
270−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.
232+Otherwise, `-dns-auto` works the same as `-dns-address` does with stars and planets: if it's available or unavailable, terminal messages, and so on.
271233
272234### Ports
273235
274−The built-in logic for listening on port 80 is to try to bind to 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).
275−
276−### Hoon
277−
278−You can use Chat to evaluate Hoon code and share the results with everyone in a chat. To do so, preface your Hoon with `#`.
279−
280−```
281−~sampel-palnet:chat-cli= #(add 2 2)
282−```
283−
284−This will print as:
285−
286−```
287−~sampel-palnet# (add 2 2)
288− 4
289−```
290−
291−### URLs
292−
293−To share a URL, send it as its own message, with no content before or after it.
294−
295−```
296−~sampel-palnet:chat-cli= https://urbit.org/
297−```
298−
299−This will print as:
300−
301−```
302−~sampel-palnet/ https://urbit.org/
303−```
304−
305−### Expanding messages
306−
307−In the case of URLs, they may be too long to display on a single message line. For Hoon code, the code or result could be big. In `:chat-cli`, these get shortened when initially printed out. To view the entire contents, you can select the message in various ways.
308−
309−```
310−~sampel-palnet+ some message
311−----------[240]
312−~sampel-palnet+ let's try selecting this message!
313−~sampel-palnet+ another message
314−~sampel-palnet:chat-cli=
315−```
316−
317−In the above example, we can select the middle message by issuing any of the following command:
318−
319−```
320−;240
321−;40
322−;;
323−```
324−
325−`;n` looks for the last message whose sequence number ends in `n`. `;;` simply picks the second-to-last message.
326−
327−Detailed message output will look something like this:
328−
329−```
330−? 240
331− 0v5.g7r7l.n0d7m.mp4bn.gp6vr.sm5lj at ~2019.10.17..22.08.27..8a03
332− ~sampel-palnet
333− to ~dopzod/urbit-help
334−let's try selecting this message!
335−```
236+The built-in logic for listening on port 80 is to try to bind to 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 versions of macOS. Otherwise, the process needs to either be run as root, or be given special permission (`sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit/binary` on Linux).