git.iko.soy/urbit.org
on addb6f6 help sign in
urbit.org/docs/using/admin.udon
201 lines 6.3 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'3'
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~your-urbit:dojo> +moon
143```
145You can use the resulting output in the same installation flow from
146[install](/../install) and [setup](/../setup), following the same scheme as
147for booting a planet. That scheme is:
149```
150$ urbit -w <moonname> -t <ticket> -c <piername>
151```
153The `-c <piername>` argument is not required, but it is recommended; otherwise,
154the resulting directory is a rather unwieldy moon name.
156Here's how an example moon might be booted:
158```
159$ urbit -w faswep-navred-sampel-palnet -t habref-mebsem-parsym-batlus -c mymoon
160```
163Moons are automatically synced to their parent `%kids` desk, and can control
164applications on their parent planet using `|link`. You can read more about
165those operations in the [filesystem](/../filesystem) and [console](/../shell)
166walkthroughs, respectively.
169## Continuity breaches
171While the Urbit network is in this alpha state, we sometimes have to
172reboot the whole network. This happens either when major changes need
173to be shipped or we hit a bug that can't be fixed over the air.
175Because Urbit networking is stateful we call this a _continuity breach_.
176Everything has to be restarted from scratch. Your pier will continue to
177function after we have breached, but it wont connect to the rest of the
178Urbit network.
180When this happens, back up any files you'd like to save, shut down your
181urbit and recreate it (as if you were starting for the first time).
183## Creating SSL certificates
185It is possible to create SSL certificates so that you serve files through your
186ship's webserver using https. To do that you, would need a machine that has
187OpenSSL installed. In order to create a new private key and a self-signed
188certificate for your localhost, valid for a year, you can issue the following
189commands:
191```
192$ openssl req -x509 -sha256 -newkey rsa:4096 -keyout private.pem -out certificate.pem -subj '/CN=localhost' -days 365
193$ mkdir -p your-urbit/.urb/tls
194$ mv private.pem certificate.pem your-urbit/.urb/tls
195```
197These certificates would have to be manually trusted by your browser, and it's
198advisable that they are used only for your localhost.
199For public-facing webservers, it would be better to create certificates for your
200fully qualified domain name using a trusted certificate authority like Let's
201Encrypt.