git.iko.soy/urbit.org
on f0371f2 help sign in
urbit.org/using/admin.md
213 lines 6.4 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`.
123## Moons
125Urbit namespace is distributed by having parent nodes sign the keys for child
126nodes. If you have a planet, your parent star issued your ticket. As a planet
127you, in turn, can sign the keys for moons. The basic idea is: your planet runs
128permanently in a data center somewhere and moons run on all your devices. Each
129planet can issue ~4 billion (`2^32`) moons.
131To generate a random moon from your planet, run:
133```
134~sampel-palnet:dojo> +moon
135moon: ~faswep-navred-sampel-palnet
136\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/
137 .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5
138 x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1
139\/ \/
140```
142You must manually edit the output of `+moon` to get
143the correct format for the `<key>`:
145- strip out the `\/`
147- combine into one line, omitting spaces
149- trim the leading `~.`
151`<key>` would be `0wd.rZU67.3jSny.z1vda ... <snip> ... effP0.de01g.600g1`
152in this example.
154Put `<key>` in a file and that file becomes `<keyfile>`.
156Another way of generating `<keyfile>` is:
158```
159~sampel-palnet:dojo> @moon/key +moon
160moon: ~faswep-navred-sampel-palnet
161```
163`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`
164and does not need editing to be used with the `-k` option.
166You can use the resulting output in the same installation flow from the
167[Booting a Ship](https://urbit.org/docs/getting-started/booting-a-ship/) guide, following the same scheme as
168for booting a planet. That scheme is:
170```
171$ urbit -w <moonname> -G <key> -c <piername>
172```
174or
176```
177$ urbit -w <moonname> -k <keyfile> -c <piername>
178```
180The `-c <piername>` argument is not required, but it is recommended; otherwise,
181the resulting directory is a rather unwieldy moon name.
183Here's how an example moon might be booted:
185```
186$ urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
187```
189or
191```
192$ urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
193```
195Moons are automatically synced to their parent `%kids` desk, and can control
196applications on their parent planet using `|link`. You can read more about
197those operations in the [filesystem](../filesystem) and [console](../shell)
198walkthroughs, respectively.
201## Continuity breaches
203While the Urbit network is in this alpha state, we sometimes have to
204reboot the whole network. This happens either when major changes need
205to be shipped or we hit a bug that can't be fixed over the air.
207Because Urbit networking is stateful we call this a _continuity breach_.
208Everything has to be restarted from scratch. Your pier will continue to
209function after we have breached, but it wont connect to the rest of the
210Urbit network.
212When this happens, back up any files you'd like to save, shut down your
213urbit and recreate it (as if you were starting for the first time).