Update README.md

README.md

@@ -1,3 +1,192 @@
-# collabore-tunnel
 
-Make your local services accessible to all on the public Internet
+<h2 align="center">collabore tunnel</h2>
+<p align="center">Make your local services accessible to all on the public Internet</p>
+<p align="center">
+    <a href="#about">About</a> •
+    <a href="#features">Features</a> •
+    <a href="#usage">Usage</a> •
+    <a href="#demo">Demo</a> •
+    <a href="#deploy">Deploy</a> •
+    <a href="#configuration">Configuration</a> •
+    <a href="#license">License</a>
+</p>
+
+## About
+
+collabore tunnel is a free and open source service offered as part of the [club elec collabore platform](https://collabore.fr) operated by [club elec](https://clubelec.insset.fr) that allows you to expose your local services on the public Internet.  
+Showing your friends or colleagues your work on your next website (for example) has never been easier!
+
+collabore tunnel works with two software parts:
+
+- A SSH server developed in Python that allows clients to connect to it and expose their local services to the public Internet by creating a tunnel between the client and the server. The server transmits traffic between the public Internet and the remote local service via a UNIX domain socket on the server.
+- A NGINX web server that makes available on the public Internet the service that has been forwarded with a subdomain based on the UNIX socket name.
+
+## Features
+
+- ✅ **Easy** to use
+- ✅ **No download** and **no signup**
+- ✅ Use the **SSH client** already installed on your device
+- ✅ Generates a random **link** that **can be shared with anyone**
+- ✅ **TLS** and **non-TLS** terminaisons
+- ✅ **Compatible** with any protocol
+
+## Usage
+
+```
+ssh -R /:host:port ssh.tunnel.collabore.fr
+```
+
+## Demo
+
+```
+ $ ssh -R /:localhost:8000 ssh.tunnel.collabore.fr
+===============================================================================
+Welcome to collabore tunnel!
+collabore tunnel is a free and open source service offered as part of the
+club elec collabore platform (https://collabore.fr) operated by club elec that
+allows you to expose your local services on the public Internet.
+To learn more about collabore tunnel,
+visit the documentation website: https://tunnel.collabore.fr/
+club elec (https://clubelec.insset.fr) is a french not-for-profit
+student organisation.
+===============================================================================
+
+Your local service has been exposed to the public Internet address: hivs5g9l739ywr2n.tnl.clb.re
+TLS termination: https://hivs5g9l739ywr2n.tnl.clb.re
+```
+
+## Deploy
+
+We have deployed collabore tunnel on a server running Ubuntu Server 22.04.
+
+**Please adapt these steps to your configuration, ...**  
+*We do not describe the usual server configuration steps or how to link a domain to a server.*
+
+### Install required packages
+
+```
+apt install python3-pip nginx
+```
+
+### Retrieve sources
+
+```
+mkdir /opt/collabore-tunnel
+```
+
+```
+cd /opt/collabore-tunnel
+```
+
+```
+git clone https://github.com/ClubElecINSSET/collabore-tunnel .
+```
+
+### Install Python dependencies
+
+```
+pip install -r requirements.txt
+```
+
+### Install NGINX virtualhosts
+
+```
+rm /etc/nginx/sites-available/default /etc/nginx/sites-enabled/default
+```
+
+```
+cp tnl.clb.re ssh.tunnel.collabore.fr /etc/nginx/sites-available/
+```
+
+```
+ln -s /etc/nginx/sites-available/tnl.clb.re /etc/nginx/sites-enabled/tnl.clb.re
+```
+
+```
+ln -s /etc/nginx/sites-available/ssh.tunnel.collabore.fr /etc/nginx/sites-enabled/ssh.tunnel.collabore.fr
+```
+
+### Install systemd service
+
+```
+cp collabore-tunnel.service /etc/systemd/system/
+```
+
+### Install Let's Encrypt certificate
+
+#### Install acme.sh
+
+```
+curl https://get.acme.sh | sh -s email=clubelec.insset@gmail.com
+```
+
+#### Edit the acme.sh account configuration file
+
+Create access to the OVH API by [clicking here](https://api.ovh.com/createToken/?GET=/domain/zone/clb.re/*&POST=/domain/zone/clb.re/*&PUT=/domain/zone/clb.re/*&GET=/domain/zone/clb.re&DELETE=/domain/zone/clb.re/record/*).  
+This is necessary for the generation of a wildcard certificate.
+
+```
+nano /root/.acme.sh/account.conf 
+```
+
+And add at the end of the file:
+
+```
+SAVED_OVH_AK='application key'
+SAVED_OVH_AS='application secret'
+SAVED_OVH_CK='consumer key'
+```
+
+#### Generate certificates
+
+```
+/root/.acme.sh/acme.sh --issue --keylength 4096 -d tnl.clb.re -d '*.tnl.clb.re' --dns dns_ovh --server letsencrypt
+```
+
+```
+/root/.acme.sh/acme.sh --issue --keylength 4096 -d ssh.tunnel.collabore.fr --nginx --server letsencrypt
+```
+
+#### Install certificates
+
+```
+mkdir -p /etc/nginx/ssl/certs
+```
+
+```
+/root/.acme.sh/acme.sh --install-cert -d tnl.clb.re -d '*.tnl.clb.re' --key-file /etc/nginx/ssl/certs/tnl.clb.re.key --fullchain-file /etc/nginx/ssl/certs/tnl.clb.re.pem --reloadcmd "service nginx force-reload"
+```
+
+```
+/root/.acme.sh/acme.sh --install-cert -d ssh.tunnel.collabore.fr --key-file /etc/nginx/ssl/certs/ssh.tunnel.collabore.fr.key --fullchain-file /etc/nginx/ssl/certs/ssh.tunnel.collabore.fr.pem --reloadcmd "service nginx force-reload"
+```
+
+### Edit and reload NGINX configuration
+
+Please remove the #'s in the files `/etc/nginx/sites-available/tnl.clb.re` and `/etc/nginx/sites-available/ssh.tunnel.collabore.fr`.
+
+```
+systemctl reload nginx
+```
+
+### Enable and start systemd service
+
+```
+systemctl enable collabore-tunnel
+```
+
+```
+systemctl start collabore-tunnel
+```
+
+## Configuration
+
+To configure the collabore tunnel, please modify the configurations of the NGINX virtualhosts and the systemd service according to your needs.
+
+## License
+
+This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.

collabore-tunnel.service

@@ -0,0 +1,40 @@
+[Unit]
+Description=collabore tunnel  Make your local services accessible to all on the public Internet
+After=network.target nginx.service
+
+[Service]
+Environment=UNIX_SOCKETS_DIRECTORY=/tmp/collabore-tunnel
+Environment=SERVER_HOSTNAME=tnl.clb.re
+Environment=CONFIG_DIRECTORY=.
+Environment=SSH_SERVER_HOST=0.0.0.0
+Environment=SSH_SERVER_PORT=22
+Environment=LOG_DEPTH=2
+WorkingDirectory=/opt/collabore-tunnel
+ExecStart=/usr/bin/python3 main.py
+ExecStop=/bin/kill -9 $MAINPID
+ProtectSystem=strict
+ReadWritePaths=/opt/collabore-tunnel /tmp
+ReadOnlyPaths=/usr/bin
+InaccessiblePaths=...
+ProtectHome=true
+ProtectProc=invisible
+ProtectKernelTunables=true
+ProtectControlGroups=true
+NoNewPrivileges=true
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+RestrictNamespaces=uts ipc pid cgroup
+RestrictSUIDSGID=true
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
+RestrictRealtime=yes
+MemoryDenyWriteExecute=yes
+LockPersonality=yes
+IPAddressAllow=192.168.1.0/24
+PrivateDevices=true
+ProtectKernelModules=true
+ProtectKernelLogs=true
+ProtectClock=true
+SystemCallArchitectures=native
+SystemCallFilter=
+
+[Install]
+WantedBy=multi-user.target

requirements.txt

@@ -0,0 +1,2 @@
+asyncssh==2.12.0
+loguru==0.6.0

ssh.tunnel.collabore.fr

@@ -0,0 +1,15 @@
+server {
+    server_name ssh.tunnel.collabore.fr;
+    listen 80;
+
+    #listen 443 ssl;
+
+    #ssl_certificate /etc/nginx/ssl/certs/ssh.tunnel.collabore.fr.pem;
+    #ssl_certificate_key /etc/nginx/ssl/certs/ssh.tunnel.collabore.fr.key;
+
+    location / {
+        return 302 https://tunnel.collabore.fr/;
+    }
+
+    server_tokens off;
+}

tnl.clb.re

@@ -0,0 +1,48 @@
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+}
+
+server {
+    server_name ~^(?<app_name>.+)\.tnl.clb.re$;
+    listen 80;
+
+    #listen 443 ssl;
+
+    #ssl_certificate /etc/nginx/ssl/certs/tnl.clb.re.pem;
+    #ssl_certificate_key /etc/nginx/ssl/certs/tnl.clb.re.key;
+
+    error_page 502 /notunnel.txt;
+    location = /notunnel.txt {
+                return 200 "No tunnel available.";
+                internal;
+    }
+
+    location / {
+        proxy_read_timeout 600s;
+        proxy_send_timeout 600s;
+        proxy_http_version 1.1;
+        proxy_set_header Host $http_host;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_pass http://unix:/tmp/collabore-tunnel/${app_name}.sock;
+    }
+
+    server_tokens off;
+}
+
+server {
+    server_name tnl.clb.re
+    listen 80;
+
+    #listen 443 ssl;
+
+    #ssl_certificate /etc/nginx/ssl/certs/tnl.clb.re.pem;
+    #ssl_certificate_key /etc/nginx/ssl/certs/tnl.clb.re.key;
+
+    location / {
+        return 302 https://tunnel.collabore.fr/;
+    }
+
+    server_tokens off;
+}