# Wirescale
[](https://pypi.org/project/wirescale/)
[](https://github.com/fernandoenzo/wirescale)
Welcome to Wirescale, a revolutionary tool that transforms the way you use VPNs. Built for Linux, Wirescale leverages the power of WireGuard’s kernel-level
performance
and Tailscale’s unbeatable udp hole-punching capabilities to create a robust, fully customizable mesh VPN experience.
## Table of contents
<!--ts-->
* [Installation](#installation)
* [Prerequisites](#prerequisites)
* [Install](#install)
* [Upgrade](#upgrade)
* [Uninstall](#uninstall)
* [Use case](#use-case)
* [Architecture](#architecture)
* [Upgrading a connection](#upgrading-a-connection)
* [The `autoremove-%i` unit](#the-autoremove-i-unit)
* [The `[Wirescale]` section](#the-wirescale-section)
* [Packaging](#packaging)
* [Python Wheel](#python-wheel)
* [Standalone executable binary](#standalone-executable-binary)
* [Contributing](#contributing)
* [License](#license)
<!--te-->
## Installation
### Prerequisites
- `ping`
- `pipx >= 1.1.0`
- `python >= 3.11`
- `socat >= 1.7.4`
- `systemd >= 252`
- `tailscale >= 1.60`
### Install
The installation is a three-step dance involving the program itself, the `systemd` service `wirescaled.service`, and the socket `wirescaled.socket`, also
managed by `systemd`. Here’s the quickest way to get everything up and running:
```commandline
~ $ wget -O /tmp/install-wirescale https://raw.githubusercontent.com/fernandoenzo/wirescale/master/install.sh
~ $ chmod +x /tmp/install-wirescale
~ $ /tmp/install-wirescale
```
This magic script will download Wirescale, place it in a user-friendly folder via `pipx`, and create symbolic links to the systemd units
in `/etc/systemd/system`. Easy peasy!
### Upgrade
Once Wirescale is installed, keeping it up-to-date is a piece of cake with `pipx`.
Starting from version `1.5` of `pipx` you can simply do:
```commandline
~ $ sudo pipx upgrade --global wirescale
```
For `pipx` versions lower than `1.5`, you’ll need to specify the folders where Wirescale resides:
```commandline
~ $ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx upgrade wirescale
```
This command tells `pipx` exactly where to find `wirescale`, ensuring your upgrades are smooth and hassle-free. Now, you’re always equipped with the latest and
greatest version of Wirescale!
Don't forget to restart the `wirescaled.service` unit once the upgrade is completed:
```commandline
~ $ systemctl restart wirescaled.service
```
### Uninstall
Need to uninstall? No problem! This script will make Wirescale disappear without a trace:
```commandline
~ $ wget -O /tmp/uninstall-wirescale https://raw.githubusercontent.com/fernandoenzo/wirescale/master/uninstall.sh
~ $ chmod +x /tmp/uninstall-wirescale
~ $ /tmp/uninstall-wirescale
```
## Use case
Tailscale has become the go-to solution for establishing point-to-point connections, effortlessly traversing NATs and interconnecting endpoints. However, it
relies on a custom version of `wireguard-go` reimplemented by Tailscale, instead of the usual `wireguard`. This approach has its limitations - you can’t
customize any connection parameters, and it doesn’t operate at the kernel level, which leads to suboptimal performance.
Beyond that, I struggle with a few things about Tailscale, such as the fact that it is not completely open source (coordination server is not, and I am forced
to use a sketchy alternative like `headscale`) and it doesn't utilize the official WireGuard implementation like other projects such as Netmaker or Netbird.
These projects, however, come with their own set of issues, like the complexity of their configuration process, unlike Tailscale, which is straightforward and
quick.
While this might be acceptable for most users who aren’t concerned about performance or software freedom, I’ve always found it regrettable that Tailscale is not
completely open source, even though [they like to falsely promote themselves as such](https://tailscale.com/opensource). Additionally, the fact that it also
doesn't offer the same level of customization as the Wireguard configuration files bothered me. This is particularly relevant for advanced use cases, which is
what this tool was designed for.
Wirescale takes a pre-existing Tailscale network and forces a hole punching between two machines. Using the port data obtained from the hole punching, Wirescale
sets up a pure WireGuard connection between the two machines. But here’s the kicker - it uses user-defined WireGuard configuration files, allowing for 100%
customization of every parameter. From pre/post scripts and network IPs to AllowedIPs and more, you have complete control over your WireGuard configuration.
In essence, Wirescale allows you to upgrade your connection between two machines on a Tailscale network to a pure WireGuard connection. And the best part? It
operates independently of the Tailscale process.
### Architecture
Wirescale is a multitasking champ! It runs as a UNIX and WebSockets server from the `systemd` unit, listening on both the local socket opened in
the `wirescaled.socket` unit and the Tailscale IP of the machine running it. This means it can handle both remote requests for connection upgrades and local
requests for a directed upgrade to another peer.
Curious about the different modes of operation? Run `wirescale -h` to see them:
- `daemon` mode is launched from the `systemd` unit. Configure it with the options that suit your needs (`wirescale daemon -h` will list them all).
- `recover` mode is for internal use only, so we won’t go into details here. Just know it’s working hard behind the scenes.
- `upgrade` mode is where the magic happens, and we’ll dive deeper into this shortly.
- `down` option is the easiest way to take down a network interface raised with `wirescale`
### Upgrading a connection
Let’s imagine you have a Tailscale network with two machines, which we’ll call `alice` (100.64.0.1) and `bob` (100.64.0.2). These names, `alice` and `bob`, are
how Tailscale identifies the machines when you run `tailscale status` and list all the devices.
Now, you want to take it up a notch. You want a pure, unadulterated point-to-point WireGuard connection between `alice` and `bob`. It’s like setting up a
private line in a world of party lines. How do you do it? Simple. You create WireGuard configuration files in `/etc/wirescale/`. For each peer you want to
connect to, you’ll need to define a file with its name. So, on the `alice` machine, you’ll define an `/etc/wirescale/bob.conf`, and on the `bob` machine, you’ll
define an `/etc/wirescale/alice.conf`.
These configuration files are standard WireGuard files, with an optional additional `[Wirescale]` section, as shown in the following complete example:
```
[Interface]
Address = 192.168.3.1
PrivateKey = sLBcu1HI/SCOXLwAnuG79DGS1jWDiwk0SyCM40uYuWI=
DNS = 1.1.1.1, 8.8.8.8
Table = off
MTU = 1500
PreUp = /bin/example arg1 arg2 %i %s
PostUp = /bin/example arg1 arg2 %i %s
PreDown = /bin/example arg1 arg2 %i %s
PostDown = /bin/example arg1 arg2 %i %s
[Peer]
PublicKey = QGAYCYJ1Ez7C32wZNw+nI8aBRM8E6OJGKOk0KiCYy0c=
PresharedKey = YFSVOA8Eo0Cj5q9ef0LBA3TudRhKP+3hZMwCljUnKms=
AllowedIPs = 192.168.3.0/24
[Wirescale]
iptables = false
interface = custom_name
suffix = true
recover-tries = 2
recreate-tries = 1
```
Notice the abscence of `Endpoint` and `ListenPort` fields? That’s `wirescale` working its magic, automatically filling these in based on what
it captures from `tailscale`.
With Wirescale, you’re in control. You can go from a zero-trust configuration to a fully self-managed one. That means you don’t need to use a complete
configuration file like in the previous example. The only essential fields you need to define are `Address` and `AllowedIPs`, as shown in the following example:
```
[Interface]
Address = 192.168.3.1
[Peer]
AllowedIPs = 192.168.3.0/24
```
If you opt for this, `wirescale` will automatically negotiate the public key and the pre-shared key for each connection established between peers. You can even
asymmetrically configure the peers, specifying the `PrivateKey` field in one of them if you want it to always use the same one, and not in the other. In any
case, any compatibility conflict between the peers’ configurations will be appropriately warned by `wirescale`. It’s your network, your rules!
We’ll focus on the options in the `[Wirescale]` section later. All you need to know now is that these options are also explained in `wirescale upgrade -h`, and
that an option set by command line always takes precedence when `wirescale` acts as a client, as is the case here, over one set in a configuration file.
Once you’re happy with your setup, just launch the following command on one of the nodes, say, `alice`:
```commandline
~ $ wirescale upgrade bob
```
Then we’ll see how the connection is established, with an output similar to the following if everything goes well:
```
Checking peer 'bob' is correct. This might take some minutes...
Start checking peer 'bob'
Checking that an endpoint is available for peer 'bob' (100.64.0.2)...
Peer 'bob' (100.64.0.2) is reachable
Connecting to local UNIX socket...
Connection to local UNIX socket established
defe22 - Enqueueing upgrade request to peer 'bob' (100.64.0.2)...
defe22 - The upgrade request for the peer 'bob' (100.64.0.2) is the next one in the processing queue
defe22 - The upgrade request for the peer 'bob' (100.64.0.2) has acquired the exclusive semaphore
defe22 - Starting to process the upgrade request for the peer 'bob' (100.64.0.2)
defe22 - Remote peer 'bob' (100.64.0.2) has enqueued our request
defe22 - Remote peer 'bob' (100.64.0.2) has started to process our upgrade request
defe22 - Stopping tailscale...
defe22 - Setting up WireGuard interface 'bob'...
defe22 - Starting tailscale...
defe22 - Launching autoremove subprocess. Running as unit: autoremove-bob.service
defe22 - Success! Now you have a new working P2P connection through interface 'bob'
```
In this example, `defe22` is a randomly generated unique uid to easily follow the process trace when we execute the
command `journalctl -f -u wirescaled.service`.
You can see your brand new P2P WireGuard connection working with:
```commandline
~ $ wg show bob
```
and you'll get an output like this:
```
interface: bob
public key: Jagl9ZKgJpnatDNH+2Z1WQC13dVMSyLyAh0iU98qrRc=
private key: (hidden)
listening port: 39216
peer: 9FFbjKGCbGWDIyDB6ZW4D/ENgxqBSBIiBfkBYCCSvjI=
preshared key: (hidden)
endpoint: 70.125.39.64:38741
allowed ips: 192.168.3.0/24
latest handshake: 5 seconds ago
transfer: 308.02 KiB received, 368.59 KiB sent
persistent keepalive: every 10 seconds
```
It’s worth noting that the configuration files generated by Wirescale are located in `/run/wirescale/`, so you can check the transparency of the process.
Just a quick heads-up! If you stumble upon an "unexpected" Endpoint (like seeing a private IP when you’re expecting a public one due to an additional VPN
between your machine and the peer), don’t be alarmed! You might have run into a [known issue](https://github.com/tailscale/tailscale/issues/1552) that Tailscale
has steadfastly refused to fix. However, I’ve independently addressed this in my [Tailgate](https://github.com/fernandoenzo/tailgate/) project, which you'll
definitely find worth exploring.
### The `autoremove-%i` unit
In Wireguard’s configuration files, `%i` is a placeholder that gets replaced with the network interface name. If you look at the second-to-last line of the
previous log, you’ll notice that a systemd unit called `autoremove-bob.service` was started right after the tunnel was set up. This unit has only one job: to
either restore the connection if it drops or to remove the network interface if the connection can’t be restored.
A connection made with wirescale is a pure P2P link between machines. This connection can drop for a variety of reasons, ranging from a machine losing its
internet connection, to a router unilaterally closing the open connection, or even the local Linux firewall deciding it’s done with it.
The`autoremove-bob.service` unit is designed to attempt to restore the connection based on the `recover-tries` option in the WireGuard configuration file (or
the`--recover-tries` command-line option when running `wirescale upgrade`). If the connection can’t be restored after the specified number of attempts, the
network interface will be removed and a new connection will be attempted from scratch, based on the `recreate-tries` parameter or the `--recreate-tries`
command-line option.
It’s crucial to note that both the `recover` and `upgrade` options require Tailscale to be operational to perform a new hole punching with the other peer. This
is essential for establishing a direct connection between the two machines. However, if it’s not possible to find an Endpoint to the other peer, and the traffic
is being relayed through a DERP server, `wirescale` will NOT set up a tunnel between the machines. This ensures that wirescale only establishes connections when
a direct peer-to-peer link is possible
Moreover, this systemd unit will actively try to keep the routers from closing the connection by sending small periodic packets using both `ping` and `socat`.
Therefore, it’s mandatory to have these two utilities installed on your system. For the first 75 minutes after the connection is established, `ping` and `socat`
will work together to “assure” the connection and ensure it can last indefinitely without interference from the routers.
### The `[Wirescale]` section
The `[Wirescale]` section of config files seen before is entirely optional, and accepts the following fields:
- `interface` The network interface name that WireGuard will set up for this peer. Defaults to the peer name.
- `iptables` Can be `true` or `false`. If set to `true`, iptables rules will be added to allow incoming traffic through the new network interface. Use this
only if the connection is unstable and needs to be recovered repeatedly. This should not be necessary in most cases. Defaults to `false`.
- `recover-tries` The number of automatic recovery attempts if the connection drops before the network interface is brought down. Negative values indicate
unlimited attempts. Defaults to 3 tries.
- `recreate-tries` The number of attempts to create a new tunnel if the network interface was brought down after failing to recover it. Negative values
indicate unlimited retries. Defaults to 0 tries.
- `suffix` Can be `true` or `false`. When set to `true`, a numeric suffix is appended to new interfaces that share names with existing ones. This suffix can be
referenced in the configuration file as `%s`, mirroring the substitution process that `%i` undergoes for the interface name. If no suffix is added, `%s`
defaults to 0.
As mentioned earlier, any of these fields can be optionally configured when running the `wirescale upgrade` command. It's important to note that if Wirescale
operates in a client role, command-line arguments will override settings specified in the configuration file.
Additionally, when Wirescale functions as a server through the `wirescale daemon` command specified in the `systemd` unit, the situation changes. In this
scenario, preferences set via the configuration file will supersede those provided through command-line arguments.
## Packaging
This section walks you through the packaging process. However, it’s important to note that you typically won’t need to worry about this. The recommended way to
upgrade the program is through `pipx`, as explained earlier.
### Python Wheel
To generate the program wheel, available at PyPi, install first `autopackage` with `pipx`:
```commandline
~ $ pipx install autopackage
```
Once `autopackage` is installed, run the following command::
```commandline
~ $ autopackage -s setup.py
```
This will generate the `whl` package and place it in the `/releases` directory.
### Standalone executable binary
In addition to the wheel, you can also create a standalone binary of the program. This binary can run independently, without requiring a Python interpreter or
any other library dependencies on your machine.
To build this binary, we’ll use a prepared script that leverages Docker:
```commandline
~ $ ./bundle/generate
```
Running this command will generate an executable in the `/dist` directory. You can move this executable to `/usr/local/bin`, and it will operate independently.
One of the key advantages of this standalone binary is its compatibility. It’s designed to work across different Linux distributions, making the program
versatile and user-friendly.
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
## License
This program is licensed under the
[GNU Affero General Public License v3 or later (AGPLv3+)](https://choosealicense.com/licenses/agpl-3.0/)
Raw data
{
"_id": null,
"home_page": "https://github.com/fernandoenzo/wirescale/",
"name": "wirescale",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "wireguard tunnel tunneling vpn tailscale secure networking mesh p2p peer-to-peer ip link route routing net internet ping subnet subnetting",
"author": "Fernando Enzo Guarini",
"author_email": "fernandoenzo@gmail.com",
"download_url": "https://github.com/fernandoenzo/wirescale/releases/",
"platform": "any",
"description": "# Wirescale\n\n[](https://pypi.org/project/wirescale/)\n\n\n\n\n\n[](https://github.com/fernandoenzo/wirescale)\n\nWelcome to Wirescale, a revolutionary tool that transforms the way you use VPNs. Built for Linux, Wirescale leverages the power of WireGuard\u2019s kernel-level\nperformance\nand Tailscale\u2019s unbeatable udp hole-punching capabilities to create a robust, fully customizable mesh VPN experience.\n\n## Table of contents\n\n<!--ts-->\n\n* [Installation](#installation)\n * [Prerequisites](#prerequisites)\n * [Install](#install)\n * [Upgrade](#upgrade)\n * [Uninstall](#uninstall)\n* [Use case](#use-case)\n * [Architecture](#architecture)\n * [Upgrading a connection](#upgrading-a-connection)\n * [The `autoremove-%i` unit](#the-autoremove-i-unit)\n * [The `[Wirescale]` section](#the-wirescale-section)\n* [Packaging](#packaging)\n * [Python Wheel](#python-wheel)\n * [Standalone executable binary](#standalone-executable-binary)\n* [Contributing](#contributing)\n* [License](#license)\n\n<!--te-->\n\n## Installation\n\n### Prerequisites\n\n- `ping`\n- `pipx >= 1.1.0`\n- `python >= 3.11`\n- `socat >= 1.7.4`\n- `systemd >= 252`\n- `tailscale >= 1.60`\n\n### Install\n\nThe installation is a three-step dance involving the program itself, the `systemd` service `wirescaled.service`, and the socket `wirescaled.socket`, also\nmanaged by `systemd`. Here\u2019s the quickest way to get everything up and running:\n\n```commandline\n~ $ wget -O /tmp/install-wirescale https://raw.githubusercontent.com/fernandoenzo/wirescale/master/install.sh\n~ $ chmod +x /tmp/install-wirescale\n~ $ /tmp/install-wirescale\n```\n\nThis magic script will download Wirescale, place it in a user-friendly folder via `pipx`, and create symbolic links to the systemd units\nin `/etc/systemd/system`. Easy peasy!\n\n### Upgrade\n\nOnce Wirescale is installed, keeping it up-to-date is a piece of cake with `pipx`.\n\nStarting from version `1.5` of `pipx` you can simply do:\n\n```commandline\n~ $ sudo pipx upgrade --global wirescale\n```\n\nFor `pipx` versions lower than `1.5`, you\u2019ll need to specify the folders where Wirescale resides:\n\n```commandline\n~ $ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx upgrade wirescale\n```\n\nThis command tells `pipx` exactly where to find `wirescale`, ensuring your upgrades are smooth and hassle-free. Now, you\u2019re always equipped with the latest and\ngreatest version of Wirescale!\n\nDon't forget to restart the `wirescaled.service` unit once the upgrade is completed:\n\n```commandline\n~ $ systemctl restart wirescaled.service\n```\n\n### Uninstall\n\nNeed to uninstall? No problem! This script will make Wirescale disappear without a trace:\n\n```commandline\n~ $ wget -O /tmp/uninstall-wirescale https://raw.githubusercontent.com/fernandoenzo/wirescale/master/uninstall.sh\n~ $ chmod +x /tmp/uninstall-wirescale\n~ $ /tmp/uninstall-wirescale\n```\n\n## Use case\n\nTailscale has become the go-to solution for establishing point-to-point connections, effortlessly traversing NATs and interconnecting endpoints. However, it\nrelies on a custom version of `wireguard-go` reimplemented by Tailscale, instead of the usual `wireguard`. This approach has its limitations - you can\u2019t\ncustomize any connection parameters, and it doesn\u2019t operate at the kernel level, which leads to suboptimal performance.\n\nBeyond that, I struggle with a few things about Tailscale, such as the fact that it is not completely open source (coordination server is not, and I am forced\nto use a sketchy alternative like `headscale`) and it doesn't utilize the official WireGuard implementation like other projects such as Netmaker or Netbird.\nThese projects, however, come with their own set of issues, like the complexity of their configuration process, unlike Tailscale, which is straightforward and\nquick.\n\nWhile this might be acceptable for most users who aren\u2019t concerned about performance or software freedom, I\u2019ve always found it regrettable that Tailscale is not\ncompletely open source, even though [they like to falsely promote themselves as such](https://tailscale.com/opensource). Additionally, the fact that it also\ndoesn't offer the same level of customization as the Wireguard configuration files bothered me. This is particularly relevant for advanced use cases, which is\nwhat this tool was designed for.\n\nWirescale takes a pre-existing Tailscale network and forces a hole punching between two machines. Using the port data obtained from the hole punching, Wirescale\nsets up a pure WireGuard connection between the two machines. But here\u2019s the kicker - it uses user-defined WireGuard configuration files, allowing for 100%\ncustomization of every parameter. From pre/post scripts and network IPs to AllowedIPs and more, you have complete control over your WireGuard configuration.\n\nIn essence, Wirescale allows you to upgrade your connection between two machines on a Tailscale network to a pure WireGuard connection. And the best part? It\noperates independently of the Tailscale process.\n\n### Architecture\n\nWirescale is a multitasking champ! It runs as a UNIX and WebSockets server from the `systemd` unit, listening on both the local socket opened in\nthe `wirescaled.socket` unit and the Tailscale IP of the machine running it. This means it can handle both remote requests for connection upgrades and local\nrequests for a directed upgrade to another peer.\n\nCurious about the different modes of operation? Run `wirescale -h` to see them:\n\n- `daemon` mode is launched from the `systemd` unit. Configure it with the options that suit your needs (`wirescale daemon -h` will list them all).\n- `recover` mode is for internal use only, so we won\u2019t go into details here. Just know it\u2019s working hard behind the scenes.\n- `upgrade` mode is where the magic happens, and we\u2019ll dive deeper into this shortly.\n- `down` option is the easiest way to take down a network interface raised with `wirescale`\n\n### Upgrading a connection\n\nLet\u2019s imagine you have a Tailscale network with two machines, which we\u2019ll call `alice` (100.64.0.1) and `bob` (100.64.0.2). These names, `alice` and `bob`, are\nhow Tailscale identifies the machines when you run `tailscale status` and list all the devices.\n\nNow, you want to take it up a notch. You want a pure, unadulterated point-to-point WireGuard connection between `alice` and `bob`. It\u2019s like setting up a\nprivate line in a world of party lines. How do you do it? Simple. You create WireGuard configuration files in `/etc/wirescale/`. For each peer you want to\nconnect to, you\u2019ll need to define a file with its name. So, on the `alice` machine, you\u2019ll define an `/etc/wirescale/bob.conf`, and on the `bob` machine, you\u2019ll\ndefine an `/etc/wirescale/alice.conf`.\n\nThese configuration files are standard WireGuard files, with an optional additional `[Wirescale]` section, as shown in the following complete example:\n\n```\n[Interface]\nAddress = 192.168.3.1\nPrivateKey = sLBcu1HI/SCOXLwAnuG79DGS1jWDiwk0SyCM40uYuWI=\nDNS = 1.1.1.1, 8.8.8.8\nTable = off\nMTU = 1500\nPreUp = /bin/example arg1 arg2 %i %s\nPostUp = /bin/example arg1 arg2 %i %s\nPreDown = /bin/example arg1 arg2 %i %s\nPostDown = /bin/example arg1 arg2 %i %s\n\n[Peer]\nPublicKey = QGAYCYJ1Ez7C32wZNw+nI8aBRM8E6OJGKOk0KiCYy0c=\nPresharedKey = YFSVOA8Eo0Cj5q9ef0LBA3TudRhKP+3hZMwCljUnKms=\nAllowedIPs = 192.168.3.0/24\n\n[Wirescale]\niptables = false\ninterface = custom_name\nsuffix = true\nrecover-tries = 2\nrecreate-tries = 1\n```\n\nNotice the abscence of `Endpoint` and `ListenPort` fields? That\u2019s `wirescale` working its magic, automatically filling these in based on what\nit captures from `tailscale`.\n\nWith Wirescale, you\u2019re in control. You can go from a zero-trust configuration to a fully self-managed one. That means you don\u2019t need to use a complete\nconfiguration file like in the previous example. The only essential fields you need to define are `Address` and `AllowedIPs`, as shown in the following example:\n\n```\n[Interface]\nAddress = 192.168.3.1\n\n[Peer]\nAllowedIPs = 192.168.3.0/24\n```\n\nIf you opt for this, `wirescale` will automatically negotiate the public key and the pre-shared key for each connection established between peers. You can even\nasymmetrically configure the peers, specifying the `PrivateKey` field in one of them if you want it to always use the same one, and not in the other. In any\ncase, any compatibility conflict between the peers\u2019 configurations will be appropriately warned by `wirescale`. It\u2019s your network, your rules!\n\nWe\u2019ll focus on the options in the `[Wirescale]` section later. All you need to know now is that these options are also explained in `wirescale upgrade -h`, and\nthat an option set by command line always takes precedence when `wirescale` acts as a client, as is the case here, over one set in a configuration file.\n\nOnce you\u2019re happy with your setup, just launch the following command on one of the nodes, say, `alice`:\n\n```commandline\n~ $ wirescale upgrade bob\n```\n\nThen we\u2019ll see how the connection is established, with an output similar to the following if everything goes well:\n\n```\nChecking peer 'bob' is correct. This might take some minutes...\nStart checking peer 'bob'\nChecking that an endpoint is available for peer 'bob' (100.64.0.2)...\nPeer 'bob' (100.64.0.2) is reachable\nConnecting to local UNIX socket...\nConnection to local UNIX socket established\ndefe22 - Enqueueing upgrade request to peer 'bob' (100.64.0.2)...\ndefe22 - The upgrade request for the peer 'bob' (100.64.0.2) is the next one in the processing queue\ndefe22 - The upgrade request for the peer 'bob' (100.64.0.2) has acquired the exclusive semaphore\ndefe22 - Starting to process the upgrade request for the peer 'bob' (100.64.0.2)\ndefe22 - Remote peer 'bob' (100.64.0.2) has enqueued our request\ndefe22 - Remote peer 'bob' (100.64.0.2) has started to process our upgrade request\ndefe22 - Stopping tailscale...\ndefe22 - Setting up WireGuard interface 'bob'...\ndefe22 - Starting tailscale...\ndefe22 - Launching autoremove subprocess. Running as unit: autoremove-bob.service\ndefe22 - Success! Now you have a new working P2P connection through interface 'bob'\n```\n\nIn this example, `defe22` is a randomly generated unique uid to easily follow the process trace when we execute the\ncommand `journalctl -f -u wirescaled.service`.\n\nYou can see your brand new P2P WireGuard connection working with:\n\n```commandline\n~ $ wg show bob\n```\n\nand you'll get an output like this:\n\n```\ninterface: bob\n public key: Jagl9ZKgJpnatDNH+2Z1WQC13dVMSyLyAh0iU98qrRc=\n private key: (hidden)\n listening port: 39216\n\npeer: 9FFbjKGCbGWDIyDB6ZW4D/ENgxqBSBIiBfkBYCCSvjI=\n preshared key: (hidden)\n endpoint: 70.125.39.64:38741\n allowed ips: 192.168.3.0/24\n latest handshake: 5 seconds ago\n transfer: 308.02 KiB received, 368.59 KiB sent\n persistent keepalive: every 10 seconds\n```\n\nIt\u2019s worth noting that the configuration files generated by Wirescale are located in `/run/wirescale/`, so you can check the transparency of the process.\n\nJust a quick heads-up! If you stumble upon an \"unexpected\" Endpoint (like seeing a private IP when you\u2019re expecting a public one due to an additional VPN\nbetween your machine and the peer), don\u2019t be alarmed! You might have run into a [known issue](https://github.com/tailscale/tailscale/issues/1552) that Tailscale\nhas steadfastly refused to fix. However, I\u2019ve independently addressed this in my [Tailgate](https://github.com/fernandoenzo/tailgate/) project, which you'll\ndefinitely find worth exploring.\n\n### The `autoremove-%i` unit\n\nIn Wireguard\u2019s configuration files, `%i` is a placeholder that gets replaced with the network interface name. If you look at the second-to-last line of the\nprevious log, you\u2019ll notice that a systemd unit called `autoremove-bob.service` was started right after the tunnel was set up. This unit has only one job: to\neither restore the connection if it drops or to remove the network interface if the connection can\u2019t be restored.\n\nA connection made with wirescale is a pure P2P link between machines. This connection can drop for a variety of reasons, ranging from a machine losing its\ninternet connection, to a router unilaterally closing the open connection, or even the local Linux firewall deciding it\u2019s done with it.\nThe`autoremove-bob.service` unit is designed to attempt to restore the connection based on the `recover-tries` option in the WireGuard configuration file (or\nthe`--recover-tries` command-line option when running `wirescale upgrade`). If the connection can\u2019t be restored after the specified number of attempts, the\nnetwork interface will be removed and a new connection will be attempted from scratch, based on the `recreate-tries` parameter or the `--recreate-tries`\ncommand-line option.\n\nIt\u2019s crucial to note that both the `recover` and `upgrade` options require Tailscale to be operational to perform a new hole punching with the other peer. This\nis essential for establishing a direct connection between the two machines. However, if it\u2019s not possible to find an Endpoint to the other peer, and the traffic\nis being relayed through a DERP server, `wirescale` will NOT set up a tunnel between the machines. This ensures that wirescale only establishes connections when\na direct peer-to-peer link is possible\n\nMoreover, this systemd unit will actively try to keep the routers from closing the connection by sending small periodic packets using both `ping` and `socat`.\nTherefore, it\u2019s mandatory to have these two utilities installed on your system. For the first 75 minutes after the connection is established, `ping` and `socat`\nwill work together to \u201cassure\u201d the connection and ensure it can last indefinitely without interference from the routers.\n\n### The `[Wirescale]` section\n\nThe `[Wirescale]` section of config files seen before is entirely optional, and accepts the following fields:\n\n- `interface` The network interface name that WireGuard will set up for this peer. Defaults to the peer name.\n- `iptables` Can be `true` or `false`. If set to `true`, iptables rules will be added to allow incoming traffic through the new network interface. Use this\n only if the connection is unstable and needs to be recovered repeatedly. This should not be necessary in most cases. Defaults to `false`.\n- `recover-tries` The number of automatic recovery attempts if the connection drops before the network interface is brought down. Negative values indicate\n unlimited attempts. Defaults to 3 tries.\n- `recreate-tries` The number of attempts to create a new tunnel if the network interface was brought down after failing to recover it. Negative values\n indicate unlimited retries. Defaults to 0 tries.\n- `suffix` Can be `true` or `false`. When set to `true`, a numeric suffix is appended to new interfaces that share names with existing ones. This suffix can be\n referenced in the configuration file as `%s`, mirroring the substitution process that `%i` undergoes for the interface name. If no suffix is added, `%s`\n defaults to 0.\n\nAs mentioned earlier, any of these fields can be optionally configured when running the `wirescale upgrade` command. It's important to note that if Wirescale\noperates in a client role, command-line arguments will override settings specified in the configuration file.\n\nAdditionally, when Wirescale functions as a server through the `wirescale daemon` command specified in the `systemd` unit, the situation changes. In this\nscenario, preferences set via the configuration file will supersede those provided through command-line arguments.\n\n## Packaging\n\nThis section walks you through the packaging process. However, it\u2019s important to note that you typically won\u2019t need to worry about this. The recommended way to\nupgrade the program is through `pipx`, as explained earlier.\n\n### Python Wheel\n\nTo generate the program wheel, available at PyPi, install first `autopackage` with `pipx`:\n\n```commandline\n~ $ pipx install autopackage\n```\n\nOnce `autopackage` is installed, run the following command::\n\n```commandline\n~ $ autopackage -s setup.py\n```\n\nThis will generate the `whl` package and place it in the `/releases` directory.\n\n### Standalone executable binary\n\nIn addition to the wheel, you can also create a standalone binary of the program. This binary can run independently, without requiring a Python interpreter or\nany other library dependencies on your machine.\n\nTo build this binary, we\u2019ll use a prepared script that leverages Docker:\n\n```commandline\n~ $ ./bundle/generate\n```\n\nRunning this command will generate an executable in the `/dist` directory. You can move this executable to `/usr/local/bin`, and it will operate independently.\n\nOne of the key advantages of this standalone binary is its compatibility. It\u2019s designed to work across different Linux distributions, making the program\nversatile and user-friendly.\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\n\n\nThis program is licensed under the\n[GNU Affero General Public License v3 or later (AGPLv3+)](https://choosealicense.com/licenses/agpl-3.0/)\n",
"bugtrack_url": null,
"license": "AGPLv3+",
"summary": "Wirescale: Secure, Efficient Connectivity. Elevate your network with stable WireGuard tunnels over Tailscale, enhancing speed and flexibility with customizable configuration.",
"version": "0.9.5.post4",
"project_urls": {
"Download": "https://github.com/fernandoenzo/wirescale/releases/",
"Homepage": "https://github.com/fernandoenzo/wirescale/"
},
"split_keywords": [
"wireguard",
"tunnel",
"tunneling",
"vpn",
"tailscale",
"secure",
"networking",
"mesh",
"p2p",
"peer-to-peer",
"ip",
"link",
"route",
"routing",
"net",
"internet",
"ping",
"subnet",
"subnetting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dab28c93243d0c98164ca30e0610c9cb991b3339bc43074938fd86d8c878dcf8",
"md5": "e5b0bc3e44a0382e78edfe2303ec4d51",
"sha256": "17c89a22e9fa7e121a8caf59c567897b435a0e4f45bd0a9cccad95b4580b17de"
},
"downloads": -1,
"filename": "wirescale-0.9.5.post4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e5b0bc3e44a0382e78edfe2303ec4d51",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 61099,
"upload_time": "2024-06-23T09:35:15",
"upload_time_iso_8601": "2024-06-23T09:35:15.705189Z",
"url": "https://files.pythonhosted.org/packages/da/b2/8c93243d0c98164ca30e0610c9cb991b3339bc43074938fd86d8c878dcf8/wirescale-0.9.5.post4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-23 09:35:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fernandoenzo",
"github_project": "wirescale",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "wirescale"
}
JSON
