add userguide entries for unencrypted wifi and tls

related to https://github.com/gokrazy/gokrazy/issues/51
This commit is contained in:
Michael Stapelberg 2020-06-01 11:23:34 +02:00
parent f967cb6bb3
commit 59d57578b9
25 changed files with 337 additions and 7 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.6 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 479 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 851 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 146 KiB

BIN
docs/img/iotee.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 447 KiB

BIN
docs/img/iotee.thumb.2x.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 218 KiB

BIN
docs/img/iotee.thumb.3x.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 385 KiB

BIN
docs/img/iotee.thumb.jpg Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 82 KiB

View File

@ -2,6 +2,18 @@
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://gokrazy.org/userguide/remotesyslog/</loc>
</url>
<url>
<loc>https://gokrazy.org/userguide/tls-for-untrusted-networks/</loc>
</url>
<url>
<loc>https://gokrazy.org/userguide/unencrypted-wifi/</loc>
</url>
<url>
<loc>https://gokrazy.org/</loc>
</url>
@ -30,8 +42,4 @@
<loc>https://gokrazy.org/modules/</loc>
</url>
<url>
<loc>https://gokrazy.org/userguide/remotesyslog/</loc>
</url>
</urlset>

View File

@ -47,7 +47,11 @@ body {
<h1 id="gokrazy-userguide">gokrazy Userguide</h1>
<p>The gokrazy Userguide walks you through various topics.</p>
<p>After following the <a href="/quickstart/">Quickstart guide</a>, you should have a working
gokrazy installation to further customize.</p>
<p>This userguide walks you through various topics. If you feel a common use-case
should be included here but isnt, please <a href="https://github.com/gokrazy/gokrazy/issues">file an issue on
GitHub</a>.</p>
<h2 id="userguide-contents">Userguide contents</h2>
@ -57,6 +61,14 @@ body {
<a href="https://gokrazy.org/userguide/remotesyslog/">Using Remote Syslog to send gokrazy logs over the network</a>
</li>
<li>
<a href="https://gokrazy.org/userguide/tls-for-untrusted-networks/">Using TLS in untrusted networks</a>
</li>
<li>
<a href="https://gokrazy.org/userguide/unencrypted-wifi/">Connecting to unencrypted WiFi networks</a>
</li>
</ul>
<footer class="footer" style="text-align: center">

View File

@ -0,0 +1,98 @@
<!DOCTYPE html>
<html> <head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Using TLS in untrusted networks</title>
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.2/css/bootstrap.min.css">
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link href="/jumbotron-narrow.css" rel="stylesheet">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400">
<style type="text/css">
body {
font-family: "Open Sans";
}
.table-striped>tr:nth-child(odd){
background-color:red;
}
</style>
</head>
<body>
<div class="container"><div class="header"><nav>
<ul class="nav nav-pills pull-right">
<li role="presentation" class=""><a href="/">Home </a></li>
<li role="presentation" class=""><a href="/platforms/">Platforms </a></li>
<li role="presentation" class=""><a href="/quickstart/">Quickstart </a></li>
<li role="presentation" class=""><a href="/showcase/">Showcase </a></li>
<li role="presentation" class=""><a href="/userguide/">Userguide </a></li>
<li role="presentation" class=""><a href="https://github.com/gokrazy/gokrazy">Source </a></li>
</ul>
</nav>
<h3 class="text-muted">gokrazy</h3>
</div>
<h1 id="using-tls-in-untrusted-networks">Using TLS in untrusted networks</h1>
<p>Lets assume that you have <a href="/quickstart/">installed gokrazy on a Raspberry Pi</a>
and are currently successfully updating it over the network like so:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">gokr-packer <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -update<span style="color:#f92672">=</span>yes <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/hello <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/breakglass <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/serial-busybox
</code></pre></div><h2 id="enabling-tls">Enabling TLS</h2>
<p>To start using TLS, specify the <code>-tls=self-signed</code> flag, and set <code>-insecure</code> for
the first update:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">gokr-packer <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -tls<span style="color:#f92672">=</span>self-signed <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -insecure <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -update<span style="color:#f92672">=</span>yes <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/hello <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/breakglass <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/serial-busybox
</code></pre></div><p>The gokrazy packer will:</p>
<ul>
<li>generate a self-signed certificate</li>
<li>include the certificate in the gokrazy installation</li>
<li>verify the certificate fingerprint in future updates</li>
</ul>
<p>The gokrazy installation will start listening on TCP port 443 for HTTPS
connections and redirect any HTTP traffic to HTTPS. When opening the gokrazy web
interface in your browser, you will need to explicitly permit communication due
to the self-signed certificate.</p>
<p>For all future updates, remove the <code>-insecure</code> flag and keep the <code>-tls=self-signed</code> flag:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">gokr-packer <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -tls<span style="color:#f92672">=</span>self-signed <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -update<span style="color:#f92672">=</span>yes <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/hello <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/breakglass <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/serial-busybox
</code></pre></div><p>You can now safely update your gokrazy installation over untrusted networks,
such as <a href="/userguide/unencrypted-wifi/">unencrypted WiFi networks</a>.</p>
<h2 id="disabling-tls">Disabling TLS</h2>
<p>Just remove the <code>-tls</code> flag from your <code>gokr-packer</code> command line. After the next
update, gokrazy will no longer contain the certificates and will serve
unencrypted HTTP again.</p>
<footer class="footer" style="text-align: center">
<p>© 2017 gokrazy authors (Michael Stapelberg and contributors)</p>
</footer>
</div>
</body>
</html>
</div>
</body>
</html>

View File

@ -0,0 +1,90 @@
<!DOCTYPE html>
<html> <head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Connecting to unencrypted WiFi networks</title>
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.2/css/bootstrap.min.css">
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link href="/jumbotron-narrow.css" rel="stylesheet">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400">
<style type="text/css">
body {
font-family: "Open Sans";
}
.table-striped>tr:nth-child(odd){
background-color:red;
}
</style>
</head>
<body>
<div class="container"><div class="header"><nav>
<ul class="nav nav-pills pull-right">
<li role="presentation" class=""><a href="/">Home </a></li>
<li role="presentation" class=""><a href="/platforms/">Platforms </a></li>
<li role="presentation" class=""><a href="/quickstart/">Quickstart </a></li>
<li role="presentation" class=""><a href="/showcase/">Showcase </a></li>
<li role="presentation" class=""><a href="/userguide/">Userguide </a></li>
<li role="presentation" class=""><a href="https://github.com/gokrazy/gokrazy">Source </a></li>
</ul>
</nav>
<h3 class="text-muted">gokrazy</h3>
</div>
<h1 id="connecting-to-unencrypted-wifi-networks">Connecting to unencrypted WiFi networks</h1>
<p>Remember that using an unencrypted WiFi network means anyone in range can read
your communication. Hence, we strongly recommend <a href="/userguide/tls-for-untrusted-networks/">using TLS for accessing the
gokrazy web interface and doing
updates</a>.</p>
<p>To make gokrazy connect to a WiFi network, first include the
<code>github.com/gokrazy/wifi</code> package in your <code>gokr-packer</code> command line, e.g.:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell">gokr-packer <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -tls<span style="color:#f92672">=</span>self-signed <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> -update<span style="color:#f92672">=</span>yes <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/hello <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/breakglass <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/serial-busybox <span style="color:#ae81ff">\
</span><span style="color:#ae81ff"></span> github.com/gokrazy/wifi
</code></pre></div><p>Then, configure the <code>wifi</code> program by creating the file <code>wifi.json</code> on the
permanent data partition:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-shell" data-lang="shell"><span style="color:#75715e"># The following assumes you already created a file system</span>
<span style="color:#75715e"># on the permanent data partition. Otherwise, please use:</span>
<span style="color:#75715e"># sudo mkfs.ext4 /dev/disk/by-partuuid/2e18c40c-04</span>
sudo mount /dev/disk/by-partuuid/2e18c40c-04 /mnt
echo <span style="color:#e6db74">&#39;{&#34;ssid&#34;: &#34;I/O Tee&#34;}&#39;</span> | sudo tee /mnt/wifi.json
sudo umount /mnt
</code></pre></div><p>After starting gokrazy, the <code>wifi</code> program will connect to the WiFi network <code>I/O Tee</code>:</p>
<p><a href="/img/2020-05-27-gokrazy-wifi-unencrypted.jpg"><img src="/img/2020-05-27-gokrazy-wifi-unencrypted.thumb.jpg" srcset="/img/2020-05-27-gokrazy-wifi-unencrypted.thumb.2x.jpg 2x,/img/2020-05-27-gokrazy-wifi-unencrypted.thumb.3x.jpg 3x" width="700" align="right" style="border: 1px solid grey; margin-bottom: 2em; margin-top: 1em"></a></p>
<h2 id="for-debugging-known-working-wifi-router-setup">For debugging: known-working WiFi router setup</h2>
<p>In case you have trouble getting your Raspberry Pi to connect to your network,
this is how I set up my <a href="https://openwrt.org/toh/tp-link/tl-wdr4300">TP-LINK
TL-WDR4300</a> with <a href="https://openwrt.org/">OpenWrt
19.07</a>:</p>
<p><a href="/img/iotee.jpg"><img src="/img/iotee.thumb.jpg" srcset="/img/iotee.thumb.2x.jpg 2x,/img/iotee.thumb.3x.jpg 3x" width="700" align="right" style="border: 1px solid grey; margin-bottom: 2em; margin-top: 1em"></a></p>
<p>The MAC address filter isnt a security measure, but prevents others from
accidentally joining this open network.</p>
<footer class="footer" style="text-align: center">
<p>© 2017 gokrazy authors (Michael Stapelberg and contributors)</p>
</footer>
</div>
</body>
</html>
</div>
</body>
</html>

View File

@ -8,6 +8,11 @@ menu:
# gokrazy Userguide
The gokrazy Userguide walks you through various topics.
After following the [Quickstart guide](/quickstart/), you should have a working
gokrazy installation to further customize.
This userguide walks you through various topics. If you feel a common use-case
should be included here but isnt, please [file an issue on
GitHub](https://github.com/gokrazy/gokrazy/issues).
## Userguide contents

View File

@ -1,5 +1,6 @@
---
title: "Using Remote Syslog to send gokrazy logs over the network"
weight: 10
---
# Using Remote Syslog to send gokrazy logs over the network

View File

@ -0,0 +1,62 @@
---
title: "Using TLS in untrusted networks"
weight: 20
---
# Using TLS in untrusted networks
Lets assume that you have [installed gokrazy on a Raspberry Pi](/quickstart/)
and are currently successfully updating it over the network like so:
```shell
gokr-packer \
-update=yes \
github.com/gokrazy/hello \
github.com/gokrazy/breakglass \
github.com/gokrazy/serial-busybox
```
## Enabling TLS
To start using TLS, specify the `-tls=self-signed` flag, and set `-insecure` for
the first update:
```shell
gokr-packer \
-tls=self-signed \
-insecure \
-update=yes \
github.com/gokrazy/hello \
github.com/gokrazy/breakglass \
github.com/gokrazy/serial-busybox
```
The gokrazy packer will:
* generate a self-signed certificate
* include the certificate in the gokrazy installation
* verify the certificate fingerprint in future updates
The gokrazy installation will start listening on TCP port 443 for HTTPS
connections and redirect any HTTP traffic to HTTPS. When opening the gokrazy web
interface in your browser, you will need to explicitly permit communication due
to the self-signed certificate.
For all future updates, remove the `-insecure` flag and keep the `-tls=self-signed` flag:
```shell
gokr-packer \
-tls=self-signed \
-update=yes \
github.com/gokrazy/hello \
github.com/gokrazy/breakglass \
github.com/gokrazy/serial-busybox
```
You can now safely update your gokrazy installation over untrusted networks,
such as [unencrypted WiFi networks](/userguide/unencrypted-wifi/).
## Disabling TLS
Just remove the `-tls` flag from your `gokr-packer` command line. After the next
update, gokrazy will no longer contain the certificates and will serve
unencrypted HTTP again.

View File

@ -0,0 +1,54 @@
---
title: "Connecting to unencrypted WiFi networks"
weight: 30
---
# Connecting to unencrypted WiFi networks
Remember that using an unencrypted WiFi network means anyone in range can read
your communication. Hence, we strongly recommend [using TLS for accessing the
gokrazy web interface and doing
updates](/userguide/tls-for-untrusted-networks/).
To make gokrazy connect to a WiFi network, first include the
`github.com/gokrazy/wifi` package in your `gokr-packer` command line, e.g.:
```shell
gokr-packer \
-tls=self-signed \
-update=yes \
github.com/gokrazy/hello \
github.com/gokrazy/breakglass \
github.com/gokrazy/serial-busybox \
github.com/gokrazy/wifi
```
Then, configure the `wifi` program by creating the file `wifi.json` on the
permanent data partition:
```shell
# The following assumes you already created a file system
# on the permanent data partition. Otherwise, please use:
# sudo mkfs.ext4 /dev/disk/by-partuuid/2e18c40c-04
sudo mount /dev/disk/by-partuuid/2e18c40c-04 /mnt
echo '{"ssid": "I/O Tee"}' | sudo tee /mnt/wifi.json
sudo umount /mnt
```
After starting gokrazy, the `wifi` program will connect to the WiFi network `I/O
Tee`:
<a href="/img/2020-05-27-gokrazy-wifi-unencrypted.jpg"><img src="/img/2020-05-27-gokrazy-wifi-unencrypted.thumb.jpg" srcset="/img/2020-05-27-gokrazy-wifi-unencrypted.thumb.2x.jpg 2x,/img/2020-05-27-gokrazy-wifi-unencrypted.thumb.3x.jpg 3x" width="700" align="right" style="border: 1px solid grey; margin-bottom: 2em; margin-top: 1em"></a>
## For debugging: known-working WiFi router setup
In case you have trouble getting your Raspberry Pi to connect to your network,
this is how I set up my [TP-LINK
TL-WDR4300](https://openwrt.org/toh/tp-link/tl-wdr4300) with [OpenWrt
19.07](https://openwrt.org/):
<a href="/img/iotee.jpg"><img src="/img/iotee.thumb.jpg" srcset="/img/iotee.thumb.2x.jpg 2x,/img/iotee.thumb.3x.jpg 3x" width="700" align="right" style="border: 1px solid grey; margin-bottom: 2em; margin-top: 1em"></a>
The MAC address filter isnt a security measure, but prevents others from
accidentally joining this open network.

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.6 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 479 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 851 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 146 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 447 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 218 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 385 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 82 KiB

View File

@ -3,7 +3,7 @@
{{ .Content }}
<ul>
{{ range .Pages }}
{{ range .Pages.ByWeight }}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
</li>