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