@@ -0,0 +1,163 @@
1++++
2+title = "coturn Operator Guide"
3+description = "Instructions for running a coturn server on your star."
4+weight = 4
5+template = "doc.html"
6++++
7+
8+# coturn Operator Guide
9+
10+To make voice and video calls through urbit we use a protocol called WebRTC which allows ships to connect directly to each other. Most times one or both ships are behind NATs and firewalls and often they are unable to connect. To get around this, instead of connecting directly to each other the ships can all connect to a TURN server (Transversal Using Relays around NATs) which will relay all the data between all the participants. Since this is relaying a bunch of data there are no free TURN servers on the internet. Thus a nice service that a star can provide is to run a TURN server and allow it's sponsored planets to use it. This guide will show you how to set one up.
11+
12+The server you want to run is called [coturn](https://github.com/coturn/coturn).
13+
14+coturn requires a server to run on, a domain, and a certificate. It can run on the same machine as your star or a separate machine.
15+
16+## Getting a server, domain, and certificate
17+
18+- If you need a server or domain follow the [Cloud Hosting guide](https://urbit.org/using/running/hosting) until the section 'Installing Urbit.' Stop there since you don't need to install urbit on the coturn machine.
19+- Follow [this guide](https://www.digitalocean.com/community/tutorials/how-to-acquire-a-let-s-encrypt-certificate-using-dns-validation-with-certbot-dns-digitalocean-on-ubuntu-20-04) to install certbot and use it to aquire a certificate.
20+
21+## Installing docker
22+
23+We will install docker and run the coturn docker container with our own certificate and configuration file.
24+
25+- Install Docker with these commands taken from [this guide](https://docs.docker.com/engine/install/ubuntu/#installation-methods)
26+
27+```
28+$ sudo apt-get update
29+$ sudo apt-get install \
30+ ca-certificates \
31+ curl \
32+ gnupg \
33+ lsb-release
34+$ sudo mkdir -p /etc/apt/keyrings
35+$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
36+$ echo \
37+ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
38+ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
39+$ sudo apt-get update
40+$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
41+```
42+
43+- Verify that Docker is installed correctly with this command:
44+```
45+$ sudo docker run hello-world
46+```
47+
48+# Install coturn
49+- First create a directory for it
50+
51+```
52+$ mkdir ~/coturn
53+```
54+
55+- Copy your cert into the directory so coturn can use it.
56+
57+```
58+$ mkdir ~/coturn/certs
59+$ sudo cp /etc/letsencrypt/live/<YOUR-DOMAIN>/cert.pem /etc/letsencrypt/live/<YOUR-DOMAIN>/privkey.pem ~/coturn/certs
60+```
61+
62+- Generate a secret which will be shared by both coturn and the uturn gall agent.
63+
64+```
65+$ sudo apt install pwgen
66+$ pwgen -s 64 1
67+```
68+
69+The output of the pwgen command is your secret. Anyone with it can access your coturn server so keep it safe.
70+
71+- Create a config file
72+```
73+$ touch ~/coturn/coturn.conf
74+$ nano ~/coturn/coturn.conf
75+```
76+
77+- Copy these contents into your coturn.conf
78+```
79+# STUN server port is 3478 for UDP and TCP, and 5349 for TLS.
80+# Allow connection on the UDP port 3478
81+listening-port=3478
82+# and 5349 for TLS (secure)
83+tls-listening-port=5349
84+
85+# Require authentication
86+fingerprint
87+use-auth-secret
88+static-auth-secret=<YOUR SECRET YOU GENERATED>
89+
90+server-name=<YOUR DOMAIN>
91+realm=<YOUR DOMAIN>
92+
93+total-quota=100
94+stale-nonce=600
95+
96+# Path to the SSL certificate and private key.
97+cert=/coturn/certs/cert.pem
98+pkey=/coturn/certs/privkey.pem
99+
100+# Specify the allowed OpenSSL cipher list for TLS/DTLS connections
101+cipher-list="ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384"
102+```
103+
104+- Make sure to put the secret you generated into the static-auth-secret line.
105+- Make sure the paths to your certificate are correct.
106+- Make sure to set realm and domain to your domain (ie zod.net)
107+
108+- Run coturn
109+```
110+$ sudo docker run -d --network=host \
111+ -v ~/coturn:/coturn \
112+ instrumentisto/coturn -c /coturn/turnserver.conf
113+```
114+
115+# Test that coturn is working
116+First you need to generate credentials for it using this python program. The credentials are created with a username, which can be anything, a TTL, which is how long they last, and the secret you put in the config file earlier.
117+
118+```
119+$ touch coturn.py
120+$ nano coturn.py
121+```
122+
123+- Copy this into coturn.py and replace SECRET with your secret. The user doesn't matter at all (it's only used to match connections with users in the logs) so just leave it as user1.
124+
125+```
126+import hashlib
127+import hmac
128+import base64
129+from time import time
130+
131+user = 'user1'
132+secret = b'SECRET'
133+
134+ttl = 24 * 3600 # Time to live
135+timestamp = int(time()) + ttl
136+username = str(timestamp) + ':' + user
137+dig = hmac.new(secret, bytes(username, 'latin-1'), hashlib.sha1).digest()
138+password = base64.b64encode(dig).decode()
139+
140+print('username: %s' % username)
141+print('password: %s' % password)
142+```
143+
144+- Now run it to generate credentials
145+```
146+$ python coturn.py
147+```
148+
149+This will spit out a username and password.
150+
151+- Go to https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/
152+- Remove the existing google stun server in the list.
153+- Add a server called `turn:your-domain` (ie turn:turn.zod.net)
154+- Copy the username and password generated by the python script into the fields.
155+- Click Gather Candidates. If you see component type 'rtp relay' in the list then it worked.
156+
157+# Configure uturn
158+- Now you should go to your ship (either your star or a moon) and poke uturn with the URL and secret of your turn server. Make sure to begin the URL with 'turn:' and put in your secret.
159+
160+```
161+> :uturn &set-server-config [%server url='turn:turn.zod.net' secret='mysecret']
162+```
163+