From e8efaa0f7bfc233d712b151d78cfcd926a949770 Mon Sep 17 00:00:00 2001 From: Avinal Kumar Date: Sat, 4 Jan 2025 22:26:34 +0530 Subject: [PATCH] feat: add instruction on using tailscale certificates (#1454) - PiKVM can use certificates provisioned by tailscale. - This commit adds the instructions - Refer: https://tailscale.com/kb/1153/enabling-https - fixes #988 Signed-off-by: Avinal Kumar --- docs/tailscale.md | 120 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 109 insertions(+), 11 deletions(-) diff --git a/docs/tailscale.md b/docs/tailscale.md index e4b314b7..f510dc8b 100644 --- a/docs/tailscale.md +++ b/docs/tailscale.md @@ -7,8 +7,8 @@ Tailscale is a convenient and free (for private use) tool for organizing a small The basic Tailscale configuration commands are shown below. For detailed instructions, refer to [Tailscale support](https://tailscale.com/contact/support/). - ----- + ## Configuring the PiKVM 1. Update OS: @@ -42,12 +42,12 @@ For detailed instructions, refer to [Tailscale support](https://tailscale.com/co If everything is successful, PiKVM will become a member of your VPN network. !!! warning "Do not update Tailscale if you don't have access to PiKVM without VPN" - Unfortunately, sometimes, updating the Tailscale client can cause problems due to breaking changes. - These are compatibility issues on the Tailscale side. + Unfortunately, sometimes, updating the Tailscale client can cause problems due to + breaking changes. These are compatibility issues on the Tailscale side. Remember this when updating. - ----- + ## Configuring a client device * [Download](https://tailscale.com/download) and install the Tailscale client @@ -55,17 +55,115 @@ If everything is successful, PiKVM will become a member of your VPN network. * Check the [Tailscale admin page](https://login.tailscale.com/admin/machines) to view your VPN network. * Follow the URL in the web browser: `https://` and you will see the PiKVM web interface. +----- + +## Using Tailscale Certificates + +PiKVM uses self-signed SSL certificates out of the box. You can also use +[Tailscale certificates](https://tailscale.com/kb/1153/enabling-https) in place of the default one. + +!!! warning + Tailscale certificates are provided by Let's Encrypt and has a default + [expiry of 90 days](https://letsencrypt.org/2015/11/09/why-90-days/). + There is currently no mechanism available to auto-renew Tailscale + certificate. You may put the commands below in a script to simplify + process. + +1. Switch filesystem to RW if in ReadOnly mode and delete existing PiKVM certificates for nginx and vnc. + + ```console + [root@pikvm ~]# rw + [root@pikvm ~]# rm -v /etc/kvmd/{nginx,vnc}/ssl/*.{crt,key} + ``` + +2. Provision new certificates using [`tailscale cert`](https://tailscale.com/kb/1080/cli#cert) + command. Optionally you may create a directory to store the certificates. + + ```console + [root@pikvm ~]# mkdir .cert + [root@pikvm ~]# cd .cert + [root@pikvm .cert]# tailscale cert + ``` + +3. Copy the certificates to nginx's and vnc's ssl directories. + + ```console + [root@pikvm ~]# cp /root/.cert/.key /etc/kvmd/nginx/ssl/server.key + [root@pikvm ~]# cp /root/.cert/.crt /etc/kvmd/nginx/ssl/server.crt + ``` + + Repeat the same steps for vnc if you have configured it. + + ```console + [root@pikvm ~]# cp /root/.cert/.key /etc/kvmd/vnc/ssl/server.key + [root@pikvm ~]# cp /root/.cert/.crt /etc/kvmd/vnc/ssl/server.crt + ``` + +4. Grant file ownership to nginx and vnc services. Switch filesystem to ReadOnly again + + ```console + [root@pikvm ~]# chown :kvmd-nginx /etc/kvmd/nginx/ssl/* + [root@pikvm ~]# chown :kvmd-vnc /etc/kvmd/vnc/ssl/* + [root@pikvm ~]# ro + ``` + +5. Restart nginx and vnc services + + ```console + [root@pikvm ~]# systemctl restart kvmd-nginx + [root@pikvm ~]# systemctl restart kvmd-vnc + ``` ----- + ## Troubleshooting -If something does not work, the usual advice is to completely remove Tailscale from PiKVM and perform a clean installation: +* If something does not work, the usual advice is to completely remove Tailscale from PiKVM and perform a clean installation: -```console -[root@pikvm ~]# rw -[root@pikvm ~]# pacman -Rscnd tailscale -[root@pikvm ~]# rm -rf /var/lib/tailscale /var/cache/tailscale -[root@pikvm ~]# reboot -``` + ```console + [root@pikvm ~]# rw + [root@pikvm ~]# pacman -Rscnd tailscale + [root@pikvm ~]# rm -rf /var/lib/tailscale /var/cache/tailscale + [root@pikvm ~]# reboot + ``` Now, follow the instructions from the beginning to re-install Tailscale. + +* In case of certificate issues you can try the following steps to debug and fix. + +1. Check if the services are running. If not please start them. For example, + web UI service can be checked using: + + ```console + [root@pikvm ~]# systemctl status kvmd-nginx + ``` + + For VNC: + + ```console + [root@pikvm ~]# systemctl status kvmd-vnc + ``` + +2. If the services are running but not accessible or showing a warning, check + the respective logs. For web UI: + + ```console + [root@pikvm ~]# journalctl -xeu kvmd-nginx + ``` + +3. If the logs shows TLS/certificate/permissions errors, the issue may be with + file ownership. The services must have at least the group ownership of the + certificates. The ownership should look similar to this: + + ```console + [root@pikvm ~]# ls -l /etc/kvmd/{nginx,vnc}/ssl + /etc/kvmd/nginx/ssl: + total 8 + -r--r--r-- 1 root kvmd-nginx 2872 Jan 3 16:07 server.crt + -r--r----- 1 root kvmd-nginx 227 Jan 3 16:07 server.key + + /etc/kvmd/vnc/ssl: + total 8 + -r--r--r-- 1 root kvmd-vnc 2872 Jan 3 16:07 server.crt + -r--r----- 1 root kvmd-vnc 227 Jan 3 16:07 server.key + ```