git.iko.soy/urbit.org
on ddc7737 help sign in
urbit.org/using/admin.md
218 lines 6.5 kB history raw
1+++
2title = "Admin and Operations"
3weight = 1
4template = "doc.html"
5+++
6Your urbit (also called your _ship_) is a persistent Unix process that you
7mainly control from the console. For some things, a browser will also work.
9## Shutdown
11You can turn your urbit off with `Ctrl-d` from the Talk or Dojo prompts.
13You can force-quit your urbit with `Ctrl-z` from anywhere.
15## Restart
17To restart your urbit simply pass the name of your pier:
19```
20$ urbit some-planet
21```
23or
25```
26$ urbit comet
27```
29## Logging
31To log an urbit's command line output to a file, use `script`:
33```
34$ script urbit.log urbit your-urbit
35```
37## Moving your pier
39Piers are designed to be portable, but it _must_ be done while the urbit
40is turned off. Urbit networking is stateful, so you can't run two copies
41of the same urbit in two places.
43To move a pier, simply move the contents of the directory it lives in.
44To keep these files as small as possible we usually use the `--sparse`
45option in `tar`. With a pier `your-urbit/`, something like this should work:
47```
48tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
49scp your-old-server:~/your-urbit.tar.gz your-new-server:~
50```
52Then to unzip it, on your other Unix server, run:
54```
55tar xfvz your-urbit.tar.gz
56```
58Delete the tar file, and, after installing Urbit on your new server,
59start your urbit back up with:
61```
62urbit your-urbit
63```
65## Console
67Your Urbit terminal is separated into two parts: the prompt (the bottom
68line) and the record (everything above that). The record is shared; all
69the output from all the apps in your command set appears in it. The
70prompt is multiplexed.
72In the CLI, Urbit apps can process your input before you hit return. To
73see this in action try entering `)` as the first character at the Dojo
74prompt. Since there is no Dojo command or Hoon expression that starts
75with ')', the Dojo rejects it.
77`Ctrl-x` - Switches the prompt between running console apps
79`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack
80trace.
82`Ctrl-d` - From Talk or Dojo, stops your Urbit process.
84`Ctrl-z` - Stops the Urbit process from _anywhere_.
86`↑` / `↓` - History navigation
88The following emacs-style key bindings are available:
90```
91Ctrl-a Cursor to beginning of the line (Home)
92Ctrl-b Cursor one character backward (left-arrow)
93Ctrl-e Cursor to the end of the line (End)
94Ctrl-f Cursor one character forward (right-arrow)
95Ctrl-g Beep; cancel reverse-search
96Ctrl-k Kill to end of line
97Ctrl-l Clear the screen
98Ctrl-n Next line in history (down-arrow)
99Ctrl-p Previous line in history (up-arrow)
100Ctrl-r Reverse-search
101Ctrl-t Transpose characters
102Ctrl-u Kill to beginning of line
103Ctrl-y Yank from kill buffer
104```
106Full coverage of the Urbit shell, the Dojo is covered in the
107[Shell walkthrough](../shell/).
109## Web
111On startup Urbit tries to bind to `localhost:8080`. If you're already
112running something on `8080` -- such as another urbit -- you'll find the urbit
113that you just started on `8081`, and so on. For planets only, we also proxy web
114domains through Urbit's own servers. Any planet `~your-urbit` is also at
115`your-urbit.urbit.org`.
117Your urbit serves a simple homepage from `http://localhost:8080` or
118`https://your-urbit.urbit.org` that should be self-explanatory. Since
119our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS.
120You can find that on `8443`. Or `8444` (and so on) if you're already
121running something on `8443`.
123A complete walkthrough of the Urbit web interface is
124[here](../web/).
126## Moons
128Urbit namespace is distributed by having parent nodes sign the keys for child
129nodes. If you have a planet, your parent star issued your ticket. As a planet
130you, in turn, can sign the keys for moons. The basic idea is: your planet runs
131permanently in a data center somewhere and moons run on all your devices. Each
132planet can issue ~4 billion (`2^32`) moons.
134To generate a random moon from your planet, run:
136```
137~sampel-palnet:dojo> +moon
138moon: ~faswep-navred-sampel-palnet
139\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/
140 .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5
141 x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1
142\/ \/
143```
145You must manually edit the output of `+moon` to get
146the correct format for the `<key>`:
148- strip out the `\/`
150- combine into one line, omitting spaces
152- trim the leading `~.`
154`<key>` would be `0wd.rZU67.3jSny.z1vda ... <snip> ... effP0.de01g.600g1`
155in this example.
157Put `<key>` in a file and that file becomes `<keyfile>`.
159*`<keyfile>` must not have a trailing newline.*
161Another way of generating `<keyfile>` is:
163```
164~sampel-palnet:dojo> @moon/key +moon
165moon: ~faswep-navred-sampel-palnet
166```
168`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`
169and does not need editing to be used with the `-k` option.
171You can use the resulting output in the same installation flow from
172[install](../install) and [setup](../setup), following the same scheme as
173for booting a planet. That scheme is:
175```
176$ urbit -w <moonname> -G <key> -c <piername>
177```
179or
181```
182$ urbit -w <moonname> -k <keyfile> -c <piername>
183```
185The `-c <piername>` argument is not required, but it is recommended; otherwise,
186the resulting directory is a rather unwieldy moon name.
188Here's how an example moon might be booted:
190```
191$ urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
192```
194or
196```
197$ urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
198```
200Moons are automatically synced to their parent `%kids` desk, and can control
201applications on their parent planet using `|link`. You can read more about
202those operations in the [filesystem](../filesystem) and [console](../shell)
203walkthroughs, respectively.
206## Continuity breaches
208While the Urbit network is in this alpha state, we sometimes have to
209reboot the whole network. This happens either when major changes need
210to be shipped or we hit a bug that can't be fixed over the air.
212Because Urbit networking is stateful we call this a _continuity breach_.
213Everything has to be restarted from scratch. Your pier will continue to
214function after we have breached, but it wont connect to the rest of the
215Urbit network.
217When this happens, back up any files you'd like to save, shut down your
218urbit and recreate it (as if you were starting for the first time).