content/using/os/getting-started.md · urbit.org

git.iko.soy/urbit.org

urbit.org/content/using/os/getting-started.md

337 lines 14 kB history raw

1+++

2title = "Getting Started"

3description = "How to operate your ship, including using your ship's filesystem and messaging applications, starting a moon, or requesting a DNS proxy."

4template = "doc.html"

5weight = 1

6aliases = ["docs/using/messaging/", "docs/using/admin/"]

7[extra]

8hidetitle = "true"

9+++

11Your urbit (also called your _ship_) is a persistent Unix process that you

12mainly control from its console, called the `dojo`.

14### Shutdown

16You can turn your urbit off with `Ctrl-d` from the Chat 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```sh

25$ ./urbit some-planet

26```

28or

30```sh

31$ ./urbit comet

32```

34### Logging

36To log an urbit's command line output to a file, use `script`:

38```sh

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 not running. 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```sh

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

60tar xfvz your-urbit.tar.gz

61```

63Delete the tar file, and, after installing Urbit on your new server, start your urbit back up with:

65```sh

66./urbit your-urbit

67```

69### Hardware requirements

71Urbit can run on any x86 computer (unofficial, unsupported [ARM binaries](https://botter-nidnul.github.io/AArch64_Urbit_Static_Binaries.html) are also available), ideally with at least 2GB of RAM.

73Urbit maintains a persistent log of the history of your ship. Eventually this log will be automatically trimmed when necessary, but for now it only increases in size. An actively used planet will consume 5-50 GB of storage space per year of operation.

75### Console

77Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.

79In the CLI, Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the Dojo prompt. Since there is no Dojo command or Hoon expression that starts with ')', the Dojo rejects it.

81`Ctrl-x` - Switches the prompt between running console apps

83`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack

84trace.

86`Ctrl-d` - From Chat or Dojo, stops your Urbit process.

88`Ctrl-z` - Stops the Urbit process from _anywhere_.

90`↑` / `↓` - History navigation

92The following emacs-style key bindings are available:

94```

95Ctrl-a Cursor to beginning of the line (Home)

96Ctrl-b Cursor one character backward (left-arrow)

97Ctrl-e Cursor to the end of the line (End)

98Ctrl-f Cursor one character forward (right-arrow)

99Ctrl-g Beep; cancel reverse-search

100Ctrl-k Kill to end of line

101Ctrl-l Clear the screen

102Ctrl-n Next line in history (down-arrow)

103Ctrl-p Previous line in history (up-arrow)

104Ctrl-r Reverse-search

105Ctrl-t Transpose characters

106Ctrl-u Kill to beginning of line

107Ctrl-y Yank from kill buffer

108```

109

110### Updates

111

112By default, you will automatically receive updates ([OTAs](@/docs/glossary/ota-updates.md)) from your sponsor. To check your OTA source, run `|ota` in the [dojo](@/docs/glossary/dojo.md).

113

114If for some reason (for example, if your sponsor is out of date), you can switch OTA sources by running `|ota ~otasrc %kids` in the dojo, where `~otasrc` is the ship from which you want to receive updates. It is a good idea to contact the source ship and ask permission to sync from them.

115

116If OTAs are not succeeding, or if you are on an version of Urbit before the `|ota` command was introduced, you can run `|merge %home (sein:title our now our) %kids, =gem %take-that`. **Note:** This will wipe out any custom changes to the base distribution.

117

118#### Additional OTA Troubleshooting

119Please check the Support Wiki for additional OTA troubleshooting, such as:

120[OTA 1.0.71 failed](https://github.com/urbit/support/wiki/OTA-1.0.71-failed),

121[Missing OTA](https://github.com/urbit/support/wiki/Missing-OTA),

122[Stuck flow preventing planets from receiving

123OTAs](https://github.com/urbit/support/wiki/Stuck-flow-preventing-planets-from-receiving-OTAs),

124and [No content shows in Links page after OTA](https://github.com/urbit/support/wiki/No-content-shows-in-Links-page-after-OTA).

125

126### Landscape

127

128On startup Urbit tries to bind to `localhost:80`. If you're already running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit that you just started on `8080`, `8081`, and so on. For planets only, we also proxy web domains through Urbit's own servers. Any planet `~your-urbit` is also at `your-urbit.arvo.network`, but only after you [set up DNS](#dns-proxying).

129

130Once running, you can sign into Landscape, your ship’s web interface, from `http://localhost` or `https://your-urbit.arvo.network`. Since our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.

131

132### Moons {#moons}

133

134Planets can spawn moons, which are meant for connected devices: phones, smart TVs, digital thermostats. The basic idea is that your planet runs permanently in a data center somewhere, while moons run on all your devices. Each planet can issue ~4 billion (`2^32`) moons.

135

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

137

138```

139~sampel-palnet:dojo> |moon

140moon: ~faswep-navred-sampel-palnet

141\/0w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SI\/

142 EUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1

143\/ \/

144```

145

146You must manually edit the output of `|moon` to get the correct format for the `<key>`:

147

148- strip out the `\/`

149

150- combine into one line, omitting spaces

151

152`<key>` would be `0w5cT5t.wCO6i.~e1xg.Oz0qb.QNO6I.3Kt2T.h9M9F.U3vU~.X3Qu0.gtb19.IYTkY.80kWZ.SIEUE.DXa8i.TiDof.o3-1C.RHLKS.k81M0.ecz5o.ic0Bg.600g1`

153in this example.

154

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

156

157You can use the resulting output in the same installation flow from the [Installing Urbit](@/getting-started.md) guide, following the same scheme as for booting a planet. That scheme is:

158

159```sh

160$ ./urbit -w <moonname> -G <key> -c <piername>

161```

162

163or

164

165```sh

166$ ./urbit -w <moonname> -k <keyfile> -c <piername>

167```

168

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

170the resulting directory is a rather unwieldy moon name.

171

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

173

174```sh

175$ ./urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon

176```

177

178or

179

180```sh

181$ ./urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon

182```

183

184Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.

185

186To breach a moon -- that is, to reset its presence on the network so that it's treated as a freshly spawned ship by others -- run from the parent ship:

187

188```

189|moon-breach ~faswep-navred-sampel-palnet

190```

191

192To cycle the keys of a moon without breaching, run:

193

194```

195|moon-cycle-keys ~sampel-sipnym-wicdev-wisryt

196```

197

198

199### Escaping A Sponsor {#escape}

200

201To use the network as a planet or star, you must be sponsored by an active star

202or galaxy, respectively. If your sponsor isn't suiting your needs, you can

203escape to a different one. This can be done with

204[Bridge](https://bridge.urbit.org/) following the instructions

205[here](@/using/id/using-bridge.md#escaping-your-sponsor).

206

207### Continuity breaches

208

209While the Urbit network is in this alpha state, we sometimes have to reboot the whole network. This happens either when major changes need to be shipped or we hit a bug that can't be fixed over the air.

210

211Because Urbit networking is stateful we call this a _continuity breach_. Everything has to be restarted from scratch. Your pier will continue to function after we have breached, but it won’t connect to the rest of the Urbit network.

212

213When this happens, back up any files you'd like to save, shut down your urbit, and recreate it (as if you were starting for the first time).

214

215### Life and rift number

216

217You can check your ship's _life_ and _rift_ number by running `+keys our` in

218dojo. You can inspect another ship's life and rift number by running `+keys

219~sampel-palnet`. For information on what life and rift are, see [Guide to Breaches](@/using/id/guide-to-breaches.md).

220

221## DNS proxying {#dns-proxying}

222

223We have a system that lets you request a domain name for your ship in the form of `ship.arvo.network`, where `ship` is your ship's name minus the `~`. This allows users to access their ships remotely using Landscape, our graphical web interface.

224

225Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.

226

227### Planets and Stars

228

229For a planet or star's DNS proxying request to be made and fulfilled, they must be hosting their ship someplace with a public IP address, and its HTTP server must be listening on port 80.

230

231To get `ship.arvo.network` on a planet or star, you must set up DNS routing with its parent ship by starting the `:dns` app.

232

233To do so, simply run this command in your ship's Dojo, passing the IP address as an argument, using the .0.0.0.0 (`@if`) syntax. For example:

234

235```

236> -dns-address &dns-address [%if .1.2.3.4]

237```

238

239`:dns`, running locally, will make an HTTP request to that IP address on port 80 to confirm that it is itself available at that IP and port. If that fails, you'll receive a `%bail-early` message in `:chat-cli`; this request will retry a few times. If the self-check is successful, the request is relayed to `~zod`, and you'll receive a message saying, `request for DNS sent to ~zod`. Once `~zod` has acknowledged receipt of the request, your local `:dns` app will send a `:chat-cli` message saying `awaiting response from ~zod`.

240

241The request will be picked up shortly, and the `ship.arvo.network` DNS record will be set to the given IP address. Once that's set up, `~zod` will be notified and `~zod` will, in turn, notify your ship. That ship will now try to verify that it can reach itself on `ship.arvo.network` over port 80. If it can't, it'll send a message saying, `unable to access via ship.arvo.network`. If it can, it will configure itself with that domain and say `confirmed access via ship.arvo.network`.

242

243Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.

244

245### Configuring SSL

246

247To enable SSL on your ship, use the `acme` agent, which will request a certificate through Let's Encrypt. First, make sure the agent is started:

248

249```

250> |start %acme

251```

252

253Next, provide the path for the SSL certificate by poking the `acme` agent. The path format is `/tld/your_domain/your_subdomain`, so if your domain is `sampel-palnet.arvo.network`, you'd use it like so:

254

255```

256> :acme &path /network/arvo/sampel-palnet

257```

258

259### Galaxies

260

261Galaxies are already required to have separate DNS entry at galaxy.urbit.org. There's no automated process for getting that binding, so if you're a galaxy-holder, get in touch with us at support@urbit.org.

262

263There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:

264

265```

266> -dns-auto

267```

268

269This will make HTTP-requests to self-check availability over `galaxy.$AMES-DOMAIN` (currently galaxy.urbit.org), where `galaxy` is the galaxy's name minus the `~`.

270

271Otherwise, `-dns-auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, Chat messages, and so on.

272

273### Ports

274

275The built-in logic for listening on port 80 is to try to bind to port 80; if it cannot, it tries 8080, then increments until it can bind a port. Port 80 is available to unprivileged process on recent version of macOS. Otherwise, the process needs to either be run as root, or be given special permission (CAP\_NET_BIND on Linux).

276

277### Hoon

278

279You can use Chat to evaluate Hoon code and share the results with everyone in a chat. To do so, preface your Hoon with `#`.

280

281```

282~sampel-palnet:chat-cli= #(add 2 2)

283```

284

285This will print as:

286

287```

288~sampel-palnet# (add 2 2)

289 4

290```

291

292### URLs

293

294To share a URL, send it as its own message, with no content before or after it.

295

296```

297~sampel-palnet:chat-cli= https://urbit.org/

298```

299

300This will print as:

301

302```

303~sampel-palnet/ https://urbit.org/

304```

305

306### Expanding messages

307

308In the case of URLs, they may be too long to display on a single message line. For Hoon code, the code or result could be big. In `:chat-cli`, these get shortened when initially printed out. To view the entire contents, you can select the message in various ways.

309

310```

311~sampel-palnet+ some message

312----------[240]

313~sampel-palnet+ let's try selecting this message!

314~sampel-palnet+ another message

315~sampel-palnet:chat-cli=

316```

317

318In the above example, we can select the middle message by issuing any of the following command:

319

320```