using/admin.md · urbit.org

git.iko.soy/urbit.org

on 5fd30d5 help sign in

urbit.org/using/admin.md

211 lines 6.5 kB history raw

1+++

2title = "Admin and Operations"

3weight = 2

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```

105

106Full coverage of the Urbit shell, the Dojo is covered in the

107[Shell walkthrough](@/docs/using/shell.md).

108

109## Web

110

111On startup Urbit tries to bind to `localhost:80`. If you're already

112running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit

113that you just started on `8080`, `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.arvo.network`, but only after you [set up DNS](../dns-proxying).

116

117Your urbit serves a simple homepage from `http://localhost` or

118`https://your-urbit.arvo.network` 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`.

122

123## Moons {#moons}

124

125Planets can spawn moons, which are meant for connected devices: phones, smart

126TVs, digital thermostats. The basic idea is: your planet runs permanently in a

127data center somewhere and moons run on all your devices. Each planet can issue

128~4 billion (`2^32`) moons.

129

130To generate a random moon from your planet, run:

131

132```

133~sampel-palnet:dojo> +moon

134moon: ~faswep-navred-sampel-palnet

135\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/

136 .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5

137 x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1

138\/ \/

139```

140

141You must manually edit the output of `+moon` to get

142the correct format for the `<key>`:

143

144- strip out the `\/`

145

146- combine into one line, omitting spaces

147

148- trim the leading `~.`

149

150`<key>` would be `0wd.rZU67.3jSny.z1vda ... <snip> ... effP0.de01g.600g1`

151in this example.

152

153Put `<key>` in a file and that file becomes `<keyfile>`.

154

155Another way of generating `<keyfile>` is:

156

157```

158~sampel-palnet:dojo> @moon/key +moon

159moon: ~faswep-navred-sampel-palnet

160```

161

162`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`

163and does not need editing to be used with the `-k` option.

164

165You can use the resulting output in the same installation flow from the

166[Booting a Ship](@/docs/getting-started/booting-a-ship.md) guide, following the same scheme as for booting a planet. That scheme is:

167

168```

169$ urbit -w <moonname> -G <key> -c <piername>

170```

171

172or

173

174```

175$ urbit -w <moonname> -k <keyfile> -c <piername>

176```

177

178The `-c <piername>` argument is not required, but it is recommended; otherwise,

179the resulting directory is a rather unwieldy moon name.

180

181Here's how an example moon might be booted:

182

183```

184$ urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon

185```

186

187or

188

189```

190$ urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon

191```

192

193Moons are automatically synced to their parent `%kids` desk, and can control

194applications on their parent planet using `|link`. You can read more about

195those operations in the [filesystem](@/docs/using/filesystem.md) and [console](@/docs/using/shell.md)

196walkthroughs, respectively.

197

198

199## Continuity breaches

200

201While the Urbit network is in this alpha state, we sometimes have to

202reboot the whole network. This happens either when major changes need

203to be shipped or we hit a bug that can't be fixed over the air.

204

205Because Urbit networking is stateful we call this a _continuity breach_.

206Everything has to be restarted from scratch. Your pier will continue to

207function after we have breached, but it wont connect to the rest of the

208Urbit network.

209

210When this happens, back up any files you'd like to save, shut down your

211urbit and recreate it (as if you were starting for the first time).