Skip to content

Commit 11d2da0

Browse files
johnny-mnemonicjohnny-mnemonic
committed
README-networking.md: Add README for networking options
Signed-off-by: Johnny Mnemonic <jm@machine-hall.org>
1 parent 45d3194 commit 11d2da0

File tree

1 file changed

+88
-0
lines changed

1 file changed

+88
-0
lines changed

‎README-networking.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Ski networking #
2+
3+
Ski supports two ways of networking:
4+
5+
1. The original _Socket Filtering_ or _Berkeley Packet Filter_ (BPF) based networking that requires a distinct physical network interface for communication between the Ski instance and the host and network. Always enabled, unless explicitly disabled by using `--disable-netdev` or `--enable-tuntap` in the configure step.
6+
7+
2. The newer TUN/TAP based networking that can work with a virtual TAP device, similar to QEMU/KVM. Only enabled with `--enable-tuntap` in the configure step.
8+
9+
10+
## BPF based networking ##
11+
12+
Ski auto-ups the respective physical device on the host before use. The physical device on the host mustn't have an IP address configured. An IP address is configured for the emulated interface in the Ski instance though. For this type of networking Ski has to run under the root account or needs the [capabilities](https://man7.org/linux/man-pages/man7/capabilities.7.html) `CAP_NET_ADMIN` and `CAP_NET_RAW`. Set these with `setcap 'cap_net_raw=ep cap_net_admin=ep' ski`. In the latter case Ski can run under an ordinary user account.
13+
14+
### Example ###
15+
16+
```
17+
network
18+
19+
+------------|----------------------------|----------------+
20+
| host | | |
21+
| | | |
22+
| +---------+-----------+ +------------+-------------+ |
23+
| | host main interface | | other physical interface | |
24+
| +---------------------+ +------------+-------------+ |
25+
| | |
26+
| +---------+---------+ |
27+
| | | | |
28+
| | +-------+-------+ | |
29+
| | | Ski interface | | |
30+
| | +---------------+ | |
31+
| | | |
32+
| | Ski instance | |
33+
| +-------------------+ |
34+
| |
35+
+----------------------------------------------------------+
36+
37+
```
38+
39+
| What | IP address/metmask |
40+
| ------------ | ------------------ |
41+
| network | 172.16.0.0/16 |
42+
| host | 172.16.0.2/16 |
43+
| Ski instance | 172.16.0.3/16 |
44+
45+
46+
## TUN/TAP networking ##
47+
48+
When the used TAP device on the host was not pre-created before launching the Ski instance using it, a TAP interface is created automatically (requires Ski to run as root or have `CAP_NET_ADMIN` set). When pre-created before launch of Ski, Ski can run and make use of it as ordinary user w/o the need for any capabilities.
49+
50+
To allow network communication the usual setup includes a host-local bridge which bridges the main network interface of the host with the TAP device that is used by a Ski instance. The bridge has an IP address configured for communications with other networked hosts. The bridged interfaces don't have an IP address configured on the host. An IP address is configured for the emulated interface in the Ski instance though, which in this case is the other end of the TAP device on the host.
51+
52+
### Example ###
53+
54+
```
55+
network
56+
57+
+------------|-----------------+
58+
| host | |
59+
| | |
60+
| +---------+-----------+ |
61+
| | host main interface | |
62+
| +-----+--------+------+ |
63+
| | bridge | |
64+
| +-----+--------+------+ |
65+
| | TAP device | |
66+
| +---------+-----------+ |
67+
| | |
68+
| | |
69+
| +---------+---------+ |
70+
| | | | |
71+
| | +-------+-------+ | |
72+
| | | Ski interface | | |
73+
| | +---------------+ | |
74+
| | | |
75+
| | Ski instance | |
76+
| +-------------------+ |
77+
| |
78+
+------------------------------+
79+
80+
```
81+
82+
| What | IP address/metmask |
83+
| ------------ | ------------------ |
84+
| network | 172.16.0.0/16 |
85+
| host | 172.16.0.2/16 |
86+
| Ski instance | 172.16.0.3/16 |
87+
88+
> **NOTE:** In the TUN/TAP case make sure that the TAP device on the host is always up before it is used inside Ski. Otherwise the Ski instance will crash on first use. Ski does not auto-up the TAP device on the host in this case, as it would then need to always run as root or with the respective capabilities to do that and then loose the ability to be ran under an ordinary user account.

0 commit comments

Comments
 (0)