mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-10-18 07:31:55 +00:00
doc: Fetch latest manual
Signed-off-by: James Valleroy <jvalleroy@mailbox.org>
This commit is contained in:
James Valleroy
parent
951157062c
commit
1b924610ee
@ -8,6 +8,19 @@ For more technical details, see the [[https://salsa.debian.org/freedombox-team/f
|
||||
|
||||
The following are the release notes for each !FreedomBox version.
|
||||
|
||||
== FreedomBox 26.13 (2026-10-06) ==
|
||||
|
||||
=== Highlights ===
|
||||
|
||||
* wireguard: Fix issues with QR codes and config download
|
||||
|
||||
=== Other Changes ===
|
||||
|
||||
* gitlab-ci: Set default artifact expiry to 3 months
|
||||
* locale: Update translations for Chinese (Simplified Han script)
|
||||
* wireguard: Don't setup server implicitly
|
||||
* storage: tests: Fix a failure from psutil change
|
||||
|
||||
== FreedomBox 26.12 (2026-09-14) ==
|
||||
|
||||
=== Highlights ===
|
||||
|
||||
@ -16,56 +16,132 @@
|
||||
|
||||
!WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography. It can be a useful replacement for IPSec or [[FreedomBox/Manual/OpenVPN|OpenVPN]].
|
||||
|
||||
=== Usage ===
|
||||
|
||||
In !FreedomBox, the !WireGuard app can be used for two separate purposes.
|
||||
|
||||
==== As a server ====
|
||||
|
||||
The first purpose is that !FreedomBox can act as a VPN server. Say, you are at a coffee shop and connected to their Wi-Fi network with your phone or laptop. You don't want the network operators or their Internet providers to know which websites you visit. You can encrypt all your Internet traffic including domain name lookups and send it to your !FreedomBox and your !FreedomBox will then send this to the broader Internet using the Internet connection that !FreedomBox has at your home. This has two effects. The network at the coffee shop will only see encrypted network traffic going to your !FreedomBox (but not any other network traffic) and the websites you visit will think you are browsing from your home and not the coffee shop.
|
||||
|
||||
==== As a client ====
|
||||
|
||||
The second purpose is that you can make your !FreedomBox a VPN client. Say, you don't want your Internet provider to monitor the traffic that originates from your !FreedomBox and other home devices. You can purchase a VPN account from one of the !WireGuard VPN providers (alternatively, you can ask a friend with !FreedomBox to allow you as a !WireGuard client on their !WireGuard server). Then configure !FreedomBox's !WireGuard app as a VPN client. All traffic originating from !FreedomBox (including !BitTorrent traffic) will be encrypted and sent to your VPN provider. From there the traffic is decrypted and set to the broader Internet. This, again, has two effects. Your home Internet provider will see only encrypted traffic going to VPN provider (but not any other network traffic) and the websites you visit from !FreedomBox will think you are browsing from the location of VPN server. Many VPN providers setup their servers in many different countries and let you choose a server from a particular country. The websites you access from !FreedomBox will think that the traffic is originating from the country you have chosen.
|
||||
|
||||
Additionally, you can make all your home devices use this VPN setup. For this you need to setup your Wi-Fi router "behind" the !FreedomBox. Your Wi-Fi router will be plugged into the "LAN" port of your !FreedomBox and configured in "repeater" mode (note that you will need to setup !FreedomBox on a device that has two Ethernet ports, such as [[FreedomBox/Hardware/LibreCrafts|Libre Crafts FreedomBox]]). Once this is done, network traffic from all the devices connect to the Wi-Fi router will then pass through !FreedomBox. If !WireGuard VPN client is configured on !FreedomBox, then all the traffic originating from these devices will use the VPN automatically.
|
||||
|
||||
=== Installation ===
|
||||
|
||||
You can install wireguard from the Apps section of the !FreedomBox web interface.
|
||||
You can install !WireGuard from the Apps section of the !FreedomBox web interface.
|
||||
|
||||
=== Configure FreedomBox as a VPN Server ===
|
||||
|
||||
To configure !FreedomBox as a server, click on the "Start !WireGuard Server" button if you see it along with the message "!WireGuard server not started yet" in the "As a Server" section. This is only needed once. After this, you see server information such as its public key, end points, and IP address in this section.
|
||||
|
||||
If your !FreedomBox is setup behind a router, then you need to configure your router to forward incoming traffic on the UDP port 51820 to !FreedomBox's port 51820.
|
||||
|
||||
=== Configure Mobile App to use VPN Server ===
|
||||
|
||||
The recommended app for Android and iOS is the official !WireGuard app available from app stores. Currently, the app is not available in F-Droid app store, so use the APK instead. Links are available in the "Clients Apps" section on the !WireGuard page.
|
||||
|
||||
==== Using QR Code ====
|
||||
|
||||
This is the simplest and recommended way to configure the !WireGuard mobile app.
|
||||
|
||||
1. In the !FreedomBox !WireGuard app page, click on "Add Client Automatically". Click on the "Show QR Code". !FreedomBox will show a QR code.
|
||||
1. In the !WireGuard mobile app, click on the "+" button in the main page to create a new tunnel. From the menu shown, select "Scan from QR code" option. A dialog asking you allow camera permission to the !WireGuard app will be shown. Allow it.
|
||||
1. Then show the QR code generated by !FreedomBox in the first step.
|
||||
1. If scanning the code is successful, then the app will ask for a name for the tunnel. Provide any name you choose such as "!MyFreedomBox". Your configuration is complete.
|
||||
1. Enable the tunnel using slider button whenever you wish to connect to your !FreedomBox VPN server.
|
||||
1. See the section below on Troubleshooting to verify that the setup is working.
|
||||
|
||||
{{attachment:wireguard-app.png|WireGuard App|height=400}}
|
||||
{{attachment:wireguard-app-add-tunnel.png|Add tunnel menu|height=400}}
|
||||
{{attachment:wireguard-app-after-qr-code.png|After scanning QR code|height=400}}
|
||||
{{attachment:wireguard-app-tunnel-added.png|Tunnel Added|height=400}}
|
||||
|
||||
==== Using Configuration File ====
|
||||
|
||||
If scanning QR code is not possible for some reason, use this approach.
|
||||
|
||||
1. In the !FreedomBox !WireGuard app page, click on "Add Client Automatically". Click on the "Download config file" option. A file is downloaded to your device. If this device is not the mobile device you wish to configure, then transfer this file to your mobile device (or send to the person who wants to your VPN server).
|
||||
1. In the !WireGuard mobile app, click on the "+" button in the main page to create a new tunnel. From the menu shown, select "Import from file or archive". Then select the configuration file that was downloaded from !FreedomBox web interface (or transferred to the mobile device).
|
||||
1. If import is successful, you will see the message "Imported wg-client" and a new tunnel added with the name "wg-client". You can rename it to a more memorable name such as "!MyFreedomBox".
|
||||
1. Enable the tunnel using slider button whenever you wish to connect to your !FreedomBox VPN server.
|
||||
1. See the section below on Troubleshooting to verify that the setup is working.
|
||||
|
||||
{{attachment:wireguard-app.png|WireGuard App|height=400}}
|
||||
{{attachment:wireguard-app-add-tunnel.png|Add tunnel menu|height=400}}
|
||||
{{attachment:wireguard-app-imported.png|Configuration file imported|height=400}}
|
||||
{{attachment:wireguard-app-tunnel-added.png|Tunnel Added|height=400}}
|
||||
|
||||
|
||||
=== Usage ===
|
||||
==== Using Manual Configuration ====
|
||||
|
||||
* Point-to-point tunnel
|
||||
* VPN client with default route
|
||||
If scanning QR code and importing from a configuration is not possible, use this approach.
|
||||
|
||||
1. In the !FreedomBox !WireGuard app page, click on "Add Client Automatically". Note the Private Key and all other details on the page.
|
||||
1. In the !WireGuard mobile app, click on the "+" button in the main page to create a new tunnel. From the menu shown, select "Create from scratch".
|
||||
1. In the Interface section provide name that is memorable such as "!MyFreedomBox". At the "Private Key", provide the private key generated by !FreedomBox in the first step. Public key is automatically filled up by the app (as public key is part of/derived from the private key). For Addresses, provide the value of "IP Address" from first step. For "DNS Servers" provide "10.84.0.1".
|
||||
1. After completing the Interface section, click on "Add peer" at the bottom of the page. For Public key, provide "Server public key" as seen in !FreedomBox !WireGuard app page "As a server" section. Provide one of the endpoints shown in the first step in the Endpoint field. Provide "0.0.0.0/0,::0/0" as Allowed IPs.
|
||||
1. Select save. You should see a new tunnel created.
|
||||
1. Enable the tunnel using slider button whenever you wish to connect to your !FreedomBox VPN server.
|
||||
1. See the section below on Troubleshooting to verify that the setup is working.
|
||||
|
||||
{{attachment:wireguard-app.png|WireGuard App|height=400}}
|
||||
{{attachment:wireguard-app-add-tunnel.png|Add tunnel menu|height=400}}
|
||||
{{attachment:wireguard-app-manual-add-1.png|Filling Interface section|height=400}}
|
||||
{{attachment:wireguard-app-manual-add-2.png|Filling Peer section|height=400}}
|
||||
{{attachment:wireguard-app-tunnel-added.png|Tunnel Added|height=400}}
|
||||
|
||||
|
||||
=== Configuration - Debian Peers ===
|
||||
=== Configure Desktop App (GNU/Linux) to use VPN Server ===
|
||||
|
||||
Note: These steps are handled automatically on !FreedomBox. So you only need to follow these steps on any Debian clients that will connect to !FreedomBox, or Debian servers that !FreedomBox will connect to.
|
||||
On a GNU/Linux desktop such as Debian, install the "wireguard" or "wireguard-tools" package. See the [[https://www.wireguard.com/install/|installation]] page for more details.
|
||||
|
||||
* [[WireGuard#Step_1_-_Generating_Keypairs|Step 1 - Generating Keypairs]]
|
||||
* [[WireGuard#Step_2_-_Configuration|Step 2 - Alternative A - Manual Configuration]]
|
||||
1. In the !FreedomBox !WireGuard app page, click on "Add Client Automatically". Click on the "Download config file" option. A file is downloaded to your device. If this device is not the device you wish to configure, then transfer this file to your device (or send to the person who wants to your VPN server).
|
||||
1. To activate the !WireGuard tunnel, run the command "sudo wg-quick up /path/to/your/wg-client.conf". To deactivate the tunnel, run "sudo wg-quick down /path/to/your/wg-client.conf".
|
||||
1. See the section below on Troubleshooting to verify that the setup is working.
|
||||
|
||||
=== Configure Desktop App (Windows) to use VPN Server ===
|
||||
|
||||
=== Configuration - Mobile Clients ===
|
||||
Download and install the official !WireGuard client for Windows. See the [[https://www.wireguard.com/install/|installation]] page for more details.
|
||||
|
||||
!WireGuard has a user space implementation for mobile devices available via the !WireGuard app - available for Android and iOS (a full list of supported operating systems is available [[https://www.wireguard.com/install/|here]]).
|
||||
1. In the !FreedomBox !WireGuard app page, click on "Add Client Automatically". Click on the "Download config file" option. A file is downloaded to your device. If this device is not the device you wish to configure, then transfer this file to your device (or send to the person who wants to your VPN server).
|
||||
1. Import the configuration file into the !WireGuard for Windows app. After that, you should be able to activate and deactivate the tunnel.
|
||||
1. See the section below on Troubleshooting to verify that the setup is working.
|
||||
|
||||
The client can be configured in several ways:
|
||||
=== Configure Desktop App (macOS) to use VPN Server ===
|
||||
|
||||
==== Alternative A - Create configuration manually ====
|
||||
Download and install the official !WireGuard client for macOS. See the [[https://www.wireguard.com/install/|installation]] page for more details.
|
||||
|
||||
This is self-explanatory, you actually create the config on the mobile device then transfer the relevant keys to the server's config.
|
||||
1. In the !FreedomBox !WireGuard app page, click on "Add Client Automatically". Click on the "Download config file" option. A file is downloaded to your device. If this device is not the device you wish to configure, then transfer this file to your device (or send to the person who wants to your VPN server).
|
||||
1. Import the configuration file into the !WireGuard for macOS app. After that, you should be able to activate and deactivate the tunnel.
|
||||
1. See the section below on Troubleshooting to verify that the setup is working.
|
||||
|
||||
==== Alternative B - Create configuration from archive ====
|
||||
=== Troubleshooting ===
|
||||
|
||||
Here you have to create a .zip archive of the client configuration file, transfer it to the device then import it into the app.
|
||||
After you activate the tunnel, all traffic on the system will go through the VPN you have configured. If there is an error in configuration, activating the tunnel will not fail as there is no connection to be made. You traffic will simply fail to reach the server and this will happen silently. Use the following tricks to ensure that your !WireGuard configuration is correct.
|
||||
|
||||
==== Alternative C - Import by reading a QR code (most secure method) ====
|
||||
1. Activate the tunnel.
|
||||
1. Open a browser and access a website like https://www.wikipedia.org/ . It should work.
|
||||
1. Open a browser and access the link https://10.84.0.1. This should show you your !FreedomBox web interface (after a security warning).
|
||||
1. Click the tunnel in the !WireGuard client app. It should show you some value for "Last handshake". It should also show you a non-zero value for data received.
|
||||
1. On !FreedomBox's !WireGuard app page, click on the public key of the client in the "Peers" table of "As a server" section. This shows you the Allowed Client page. In this page, data received should be non-zero and "Last handshake" should show a valid value.
|
||||
1. If you have the "ping" utility installed on your client machine, running "ping 9.9.9.9" should receive responses.
|
||||
1. If you have "traceroute" utility installed on your machine, running "traceroute 9.9.9.9" should show "10.84.0.1" (your !FreedomBox) as the first step in delivering the packets.
|
||||
|
||||
The mobile client as of version 0.0.20180724 supports QR code based input.
|
||||
If the above does not work, verify the following:
|
||||
|
||||
DebianPackage:qrencode can be used to generate qr codes, even in a terminal/console using UTF8 characters.
|
||||
1. The public key of the client should be shown in the list of Peers in the "As a Server" section of !WireGuard app in !FreedomBox. It should match exactly.
|
||||
1. The allowed IP listed against the public key in !FreedomBox should be the value of IP address set in the client app.
|
||||
1. The public key of the !FreedomBox server shown in "As a Server" section of !WireGuard app in !FreedomBox interface should be the public key set in peer section of client app. It should match exactly.
|
||||
1. Allowed IPs should be "0.0.0.0/0,::0/0" in client app in the peer section of tunnel configuration.
|
||||
1. The endpoint of the peer in client app should be a domain name or the IP address of the !FreedomBox server followed by a ":51820". Your !FreedomBox should also be reachable from this IP address or domain name. Deactivate the tunnel and type this address in the browser (without the port) from the client machine. !FreedomBox web interface should show up.
|
||||
|
||||
The syntax is:
|
||||
|
||||
{{{
|
||||
# qrencode -t ansiutf8 < client.conf
|
||||
}}}
|
||||
|
||||
This will generate a QR code that is readable by the mobile client.
|
||||
|
||||
The advantage of this approach is that there is no need to transfer sensitive information via data channels that can potentially be compromised and there is no need for any additional software.
|
||||
=== Known Issues ===
|
||||
|
||||
* In version 26.12 of !FreedomBox, the Show QR Code and Download configuration functionality is broken. It will be fixed in version 26.13.
|
||||
|
||||
=== External Links ===
|
||||
|
||||
|
||||
BIN
doc/manual/en/images/wireguard-app-add-tunnel.png
Normal file
BIN
doc/manual/en/images/wireguard-app-add-tunnel.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 92 KiB |
BIN
doc/manual/en/images/wireguard-app-after-qr-code.png
Normal file
BIN
doc/manual/en/images/wireguard-app-after-qr-code.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
BIN
doc/manual/en/images/wireguard-app-imported.png
Normal file
BIN
doc/manual/en/images/wireguard-app-imported.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
BIN
doc/manual/en/images/wireguard-app-manual-add-1.png
Normal file
BIN
doc/manual/en/images/wireguard-app-manual-add-1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 158 KiB |
BIN
doc/manual/en/images/wireguard-app-manual-add-2.png
Normal file
BIN
doc/manual/en/images/wireguard-app-manual-add-2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 151 KiB |
BIN
doc/manual/en/images/wireguard-app-tunnel-added.png
Normal file
BIN
doc/manual/en/images/wireguard-app-tunnel-added.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
BIN
doc/manual/en/images/wireguard-app.png
Normal file
BIN
doc/manual/en/images/wireguard-app.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
@ -8,6 +8,19 @@ For more technical details, see the [[https://salsa.debian.org/freedombox-team/f
|
||||
|
||||
The following are the release notes for each !FreedomBox version.
|
||||
|
||||
== FreedomBox 26.13 (2026-10-06) ==
|
||||
|
||||
=== Highlights ===
|
||||
|
||||
* wireguard: Fix issues with QR codes and config download
|
||||
|
||||
=== Other Changes ===
|
||||
|
||||
* gitlab-ci: Set default artifact expiry to 3 months
|
||||
* locale: Update translations for Chinese (Simplified Han script)
|
||||
* wireguard: Don't setup server implicitly
|
||||
* storage: tests: Fix a failure from psutil change
|
||||
|
||||
== FreedomBox 26.12 (2026-09-14) ==
|
||||
|
||||
=== Highlights ===
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user