@@ -0,0 +1,181 @@
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+# Configure firewall to open up coturn ports
48+- coturn requires ports 3478 and 5349 to talk to it plus ports 49152-65535 to relay data. (I know this is a ton of ports but it IS a relay server).
49+
50+```
51+$ sudo ufw allow 3478
52+$ sudo ufw allow 5349
53+$ sudo ufw allow 49152:65535/udp
54+```
55+
56+- Turn on the firewall
57+```
58+$ sudo ufw enable
59+```
60+
61+- Check the status
62+```
63+$ sudo ufw status
64+```
65+
66+# Install coturn
67+- First create a directory for it
68+
69+```
70+$ mkdir ~/coturn
71+```
72+
73+- Copy your cert into the directory so coturn can use it.
74+
75+```
76+$ mkdir ~/coturn/certs
77+$ sudo cp /etc/letsencrypt/live/<YOUR-DOMAIN>/cert.pem /etc/letsencrypt/live/<YOUR-DOMAIN>/privkey.pem ~/coturn/certs
78+```
79+
80+- Generate a secret which will be shared by both coturn and the uturn gall agent.
81+
82+```
83+$ sudo apt install pwgen
84+$ pwgen -s 64 1
85+```
86+
87+The output of the pwgen command is your secret. Anyone with it can access your coturn server so keep it safe.
88+
89+- Create a config file
90+```
91+$ touch ~/coturn/coturn.conf
92+$ nano ~/coturn/coturn.conf
93+```
94+
95+- Copy these contents into your coturn.conf
96+```
97+# STUN server port is 3478 for UDP and TCP, and 5349 for TLS.
98+# Allow connection on the UDP port 3478
99+listening-port=3478
100+# and 5349 for TLS (secure)
101+tls-listening-port=5349
102+
103+# Require authentication
104+fingerprint
105+use-auth-secret
106+static-auth-secret=<YOUR SECRET YOU GENERATED>
107+
108+server-name=<YOUR DOMAIN>
109+realm=<YOUR DOMAIN>
110+
111+total-quota=100
112+stale-nonce=600
113+
114+# Path to the SSL certificate and private key.
115+cert=/coturn/certs/cert.pem
116+pkey=/coturn/certs/privkey.pem
117+
118+# Specify the allowed OpenSSL cipher list for TLS/DTLS connections
119+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"
120+```
121+
122+- Make sure to put the secret you generated into the static-auth-secret line.
123+- Make sure the paths to your certificate are correct.
124+- Make sure to set realm and domain to your domain (ie zod.net)
125+
126+- Run coturn
127+```
128+$ sudo docker run -d --network=host \
129+ -v ~/coturn:/coturn \
130+ instrumentisto/coturn -c /coturn/turnserver.conf
131+```
132+
133+# Test that coturn is working
134+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.
135+
136+```
137+$ touch coturn.py
138+$ nano coturn.py
139+```
140+
141+- 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.
142+
143+```
144+import hashlib
145+import hmac
146+import base64
147+from time import time
148+
149+user = 'user1'
150+secret = b'SECRET'
151+
152+ttl = 24 * 3600 # Time to live
153+timestamp = int(time()) + ttl
154+username = str(timestamp) + ':' + user
155+dig = hmac.new(secret, bytes(username, 'latin-1'), hashlib.sha1).digest()
156+password = base64.b64encode(dig).decode()
157+
158+print('username: %s' % username)
159+print('password: %s' % password)
160+```
161+
162+- Now run it to generate credentials
163+```
164+$ python coturn.py
165+```
166+
167+This will spit out a username and password.
168+
169+- Go to https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/
170+- Remove the existing google stun server in the list.
171+- Add a server called `turn:your-domain` (ie turn:turn.zod.net)
172+- Copy the username and password generated by the python script into the fields.
173+- Click Gather Candidates. If you see component type 'rtp relay' in the list then it worked.
174+
175+# Configure uturn
176+- 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.
177+
178+```
179+> :uturn &set-server-config [%server url='turn:turn.zod.net' secret='mysecret']
180+```
181+