Before starting

• First of all, note that this container requires the Linux's headers to be passed -v /lib/modules:/lib/modules, so if you want to run the container on a Windows or MacOS machine you'll need to pass them by another way.

• Secondly, this project is only available for x86_64 | amd64 on Linux, MacOS and Windows (No phones). Because WSTunnel isn't consistently releasing the binary for arm64 nor armhf and WSTunnel on a phone might be too complicated to pull of.

• Thirdly you need root access on the client for Linux or MacOS or Windows for windows due to some PowerShell line execution.

Note that even if WSTunnel is installed, this is just an addon and the classic Wireguard tunnel will still run normally (maybe for your phone and arm).

Getting started

Server side configuration

Deploy the docker

In order to deploy a wiws docker container you can use the docker CLI or the Docker-Compose. The wiws docker container is based on the Linux server Wireguard Docker container but in order to use WSTunnel, some required environment variables were added to the container, a new port was also added to the container to allow the WSTunnelto listen and forward the traffic. I listed below all the parameters that you need to set in order to use the wiws docker container followed by usage exemples.

Parameters list

Usage exemples

  version: '3.3'
  services:
      wiws:
          container_name: wiws
          cap_add:
            - NET_ADMIN
            - SYS_MODULE
          environment:
              - PUID=1000
              - PGID=1000
              - TZ=Europe/Paris
              - PEERS=1
              - PEERDNS=auto #optional defaults to 'auto'
              - INTERNAL_SUBNET=10.13.13.0 #optional defaults to 10.13.13.0
              - SERVERURL=wiws.domain.com #optional defaults to 'auto' which will be your external IP
              - SERVERPORT=51820 #optional defaults to 51820
              - USINGDNSMASQ=false #optional defaults to false
              - WSPREFIX="" #optional defaults to ""
              - WSSERVERPORT=27832 #optional defaults to 27832
          ports:
              - 27832:27832/tcp
              - 51820:51820/udp #optional used if you want to keep a normal Wireguard server
          volumes:
              - '/path/to/data/config:/config'
              - '/lib/modules:/lib/modules'
          sysctls:
            - net.ipv4.conf.all.src_valid_mark=1
          restart: unless-stopped
          image: vic1707/wiws

docker run -d \
  --name=wiws \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/Paris \
  -e PEERS=1 \
  -e PEERDNS=auto `#optional defaults to 'auto'` \
  -e INTERNAL_SUBNET=10.13.13.0 `#optional defaults to 10.13.13.0` \
  -e SERVERURL=wiws.domain.com `#optional defaults to 'auto' which will be your external IP` \
  -e SERVERPORT=51820 `#optional defaults to 51820` \
  -e USINGDNSMASQ=false `#optional defaults to false` \
  -e WSPREFIX="" `#optional defaults to ""` \
  -e WSSERVERPORT=27832 `#optional defaults to 27832` \
  -p 27832:27832/tcp \
  -p 51820:51820/udp `#optional used if you want to keep a normal Wireguard server` \
  -v /path/to/data/config:/config \
  -v /lib/modules:/lib/modules \
  --sysctl="net.ipv4.conf.all.src_valid_mark=1" \
  --restart unless-stopped \
  vic1707/wiws

Get needed client files

Once the server is started it will generate a usefull a batch of files. You will need to save them in order to put them on the client.

Client side configuration

Needed binary installation

On all clients using the WSTunnel you will need to install the latest WSTunnel binary and add it to PATH.

Needed files set up

Get your file batch from earlier.

On Windows you'll copy wstunnel.ps1 in C:\wstunnel\.

On Linux and MacOS you'll copy wstunnel.sh in /etc/wireguard/ (don't forget to chmod +x it!!).

Those paths and script names can be customized by editing the .unix.conf or .win.conf.

Connection to the server

Unfortunately, the MacOS GUI of Wireguard isn't compatible with WSTunnel, but the GUI works fine on Windows.

If the GUI isn't accepting the wspeer.XXXX.conf you'll have to use the CLI:

• wg-quick up wspeer.XXXX.conf to connect to the server
• wg-quick down wspeer.XXXX.conf to disconnect.

Support Info

• Shell access whilst the container is running: docker exec -it wiws /bin/bash
• To monitor the logs of the container in realtime: docker logs -f wiws

Troubleshooting

If you're facing problem with the container, you should try running the container with the VERBOSE flag set to true. This option should allow you to see the logs of wstunnel. To efficiently debug the problem you should try different things step by step.

1. Check if a normal Wireguard connection works.

2. Check if you can connect to WSTunnel from your local network (by running the wstunnel client command directly on your machine) and request a packet (I personnaly use netcat to do this). a. If you can, you should see a new connection in logs of the container and so the problem is elsewere. b. If you can't, open an issue with all your configuration and the logs of the container.

3. Check if you can connect to WSTunnel from the internet (first without any reverse proxy then with it).