@@ -8,16 +8,20 @@ aliases = ["docs/using/messaging/", "docs/using/admin/"]
8hidetitle = "true"
8hidetitle = "true"
11−Your urbit (also called your _ship_) is a persistent Unix process that you
11+This document deals with:
12−mainly control from its console, called the `dojo`.
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`.
16+If you're looking for information on using the GUI application [Port](/getting-started#port), see the [Port guide](/using/running/port) instead.
14−### Shutdown
18+## Shutdown
16You can turn your urbit off with `Ctrl-d` from the Chat or Dojo prompts.
20You can turn your urbit off with `Ctrl-d` from the Chat or Dojo prompts.
18You can force-quit your urbit with `Ctrl-z` from anywhere.
22You can force-quit your urbit with `Ctrl-z` from anywhere.
20−### Restart
24+## Restart
22To restart your urbit simply pass the name of your pier:
26To restart your urbit simply pass the name of your pier:
@@ -31,7 +35,7 @@ or
31$ ./urbit comet
35$ ./urbit comet
34−### Logging
38+## Logging
36To log an urbit's command line output to a file, use `script`:
40To log an urbit's command line output to a file, use `script`:
@@ -39,7 +43,7 @@ To log an urbit's command line output to a file, use `script`:
39$ script urbit.log ./urbit your-urbit
43$ script urbit.log ./urbit your-urbit
42−### Moving your pier
46+## Moving your pier
44Piers are designed to be portable, but it _must_ be done while the urbit
48Piers are designed to be portable, but it _must_ be done while the urbit
45is not running. Urbit networking is stateful, so you can't run two copies
49is 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
66./urbit your-urbit
70./urbit your-urbit
69−### Hardware requirements
73+## Hardware requirements
71Urbit 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.
75Urbit 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.
73Urbit 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.
77Urbit 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.
75−### Console
79+## Console
77Your 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.
81Your 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.
@@ -107,13 +111,13 @@ Ctrl-u Kill to beginning of line
107Ctrl-y Yank from kill buffer
111Ctrl-y Yank from kill buffer
110−### Updates
114+## Updates
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.
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.
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`.
118#### Additional OTA Troubleshooting
122#### Additional OTA Troubleshooting
@@ -124,65 +128,41 @@ Please check the Support Wiki for additional OTA troubleshooting, such as:
124OTAs](https://github.com/urbit/support/wiki/Stuck-flow-preventing-planets-from-receiving-OTAs),
128OTAs](https://github.com/urbit/support/wiki/Stuck-flow-preventing-planets-from-receiving-OTAs),
125and [No content shows in Links page after OTA](https://github.com/urbit/support/wiki/No-content-shows-in-Links-page-after-OTA).
129and [No content shows in Links page after OTA](https://github.com/urbit/support/wiki/No-content-shows-in-Links-page-after-OTA).
127−### Landscape
131+## Web interface
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).
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.
133−### Moons {#moons}
137+## Moons {#moons}
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.
137To generate a random moon from your planet, run:
141To generate a random moon from your planet, run:
140~sampel-palnet:dojo> |moon
144~sampel-palnet:dojo> |moon
141moon: ~faswep-navred-sampel-palnet
145moon: ~faswep-navred-sampel-palnet
142−\/0w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SI\/
146+0w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SIEUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1
143− EUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1
147−You must manually edit the output of `|moon` to get the correct format for the `key`:
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.
151−- combine into one line, omitting spaces
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`
156−Put `key` in a file and that file becomes `keyfile`.
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:
161−$ ./urbit -w <moonname> -G <key> -c <piername>
167−$ ./urbit -w <moonname> -k <keyfile> -c <piername>
170−The `-c <piername>` argument is not required, but it is recommended; otherwise,
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`.
171−the resulting directory is a rather unwieldy moon name.
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:
176−$ ./urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
156+$ ./urbit -w <moon-name> -G <key> -c <pier-name>
182−$ ./urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
162+$ ./urbit -w <moon-name> -k <key-file> -c <pier-name>
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`.
187To 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:
167To 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:
@@ -193,10 +173,12 @@ To breach a moon -- that is, to reset its presence on the network so that it's t
193To cycle the keys of a moon without breaching, run:
173To cycle the keys of a moon without breaching, run:
196−|moon-cycle-keys ~sampel-sipnym-wicdev-wisryt
176+|moon-cycle-keys ~faswep-navred-sampel-palnet
179+You can then run `|rekey` on the moon with the key given by the above command as the argument.
199−### Escaping A Sponsor {#escape}
181+## Escaping A Sponsor {#escape}
201To use the network as a planet or star, you must be sponsored by an active star
183To use the network as a planet or star, you must be sponsored by an active star
202or galaxy, respectively. If your sponsor isn't suiting your needs, you can
184or 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
204[Bridge](https://bridge.urbit.org/) following the instructions
186[Bridge](https://bridge.urbit.org/) following the instructions
205[here](/using/id/using-bridge#escaping-your-sponsor).
187[here](/using/id/using-bridge#escaping-your-sponsor).
207−### Continuity breaches
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.
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.
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).
215−### Life and rift number
189+## Life and rift number
217You can check your ship's _life_ and _rift_ number by running `+keys our` in
191You can check your ship's _life_ and _rift_ number by running `+keys our` in
218dojo. 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).
192dojo. 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).
220## DNS setup {#dns-setup}
194## DNS setup {#dns-setup}
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.
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.
224−Stars and planets follow the same process DNS request process, and galaxies have their own requirements. Moons and comets are not supported.
226−### Planets and Stars
228For 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.
198For 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.
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.
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:
235−> -dns-address &dns-address [%if .1.2.3.4]
203+-dns-address [%if .1.2.3.4]
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`.
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`.
242Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
210Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
244### Configuring SSL
212### Configuring SSL
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:
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:
255−> :acme &path /network/arvo/sampel-palnet
217+:acme &path /network/arvo/sampel-palnet
258### Galaxies
220### Galaxies
@@ -267,69 +229,8 @@ There is a command for galaxies that will try to re-use their already-necessary
268This 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 `~`.
230This 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 `~`.
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.
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).
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).
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 `#`.
281−~sampel-palnet:chat-cli= #(add 2 2)
287−~sampel-palnet# (add 2 2)
293−To share a URL, send it as its own message, with no content before or after it.
296−~sampel-palnet:chat-cli= https://urbit.org/
302−~sampel-palnet/ https://urbit.org/
305−### Expanding messages
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.
310−~sampel-palnet+ some message
312−~sampel-palnet+ let's try selecting this message!
313−~sampel-palnet+ another message
314−~sampel-palnet:chat-cli=
317−In the above example, we can select the middle message by issuing any of the following command:
325−`;n` looks for the last message whose sequence number ends in `n`. `;;` simply picks the second-to-last message.
327−Detailed message output will look something like this:
331− 0v5.g7r7l.n0d7m.mp4bn.gp6vr.sm5lj at ~2019.10.17..22.08.27..8a03
333− to ~dopzod/urbit-help
334−let's try selecting this message!