diff --git a/docs/guides/vpn/openvpn/android-client.md b/docs/guides/vpn/openvpn/android-client.md index eb18ac4..87699d6 100644 --- a/docs/guides/vpn/openvpn/android-client.md +++ b/docs/guides/vpn/openvpn/android-client.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + - Install the official OpenVPN App from the [App Store](https://play.google.com/store/apps/details?id=net.openvpn.openvpn) - Log into your OpenVPN server and use the road warrior installer to create a new certificate for your device: diff --git a/docs/guides/vpn/openvpn/clients.md b/docs/guides/vpn/openvpn/clients.md index cfd1202..c3fd90f 100644 --- a/docs/guides/vpn/openvpn/clients.md +++ b/docs/guides/vpn/openvpn/clients.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + ## Create a client config file (`.ovpn`) Now that the server is configured, you'll want to connect some clients so you can make use of your Pi-hole wherever you are. Doing so requires the use of a certificate. You generate these and the resulting `.ovpn` file by running the installer and choosing `1) Add a new user` for each client that will connect to the VPN. diff --git a/docs/guides/vpn/openvpn/deprecation_notice.md b/docs/guides/vpn/openvpn/deprecation_notice.md new file mode 100644 index 0000000..02b2d07 --- /dev/null +++ b/docs/guides/vpn/openvpn/deprecation_notice.md @@ -0,0 +1,5 @@ + +!!! warning "OpenVPN is no longer recommended" + We do no longer recommending the use of OpenVPN for new deployments. Although OpenVPN has served us well in the past, we believe it's time to move towards more modern and efficient solutions. + + We suggest that users now turn their attention to [WireGuard](../wireguard/overview.md), a forward-thinking VPN solution that offers better performance, faster speeds, and easier implementation. WireGuard has been designed with the latest technology in mind, providing simple yet powerful tools for securing your network communications. Pi-hole's step-by-step tutorial is designed to help you understand the ins and outs of WireGuard, regardless of your technical expertise. diff --git a/docs/guides/vpn/openvpn/dual-VPN.md b/docs/guides/vpn/openvpn/dual-VPN.md index e7616bd..705065b 100644 --- a/docs/guides/vpn/openvpn/dual-VPN.md +++ b/docs/guides/vpn/openvpn/dual-VPN.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + ### Dual VPN Setup - Separate DNS and VPN Traffic In order to separate VPN traffic from DNS queries, you will need to run two VPN servers. One server routes the normal user traffic and the second routes only DNS requests. This can be done with two OpenVPN configurations. diff --git a/docs/guides/vpn/openvpn/dual-operation.md b/docs/guides/vpn/openvpn/dual-operation.md index b0a81da..1a3986f 100644 --- a/docs/guides/vpn/openvpn/dual-operation.md +++ b/docs/guides/vpn/openvpn/dual-operation.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + **Up until now, this wiki has been about a server set up on a cloud host, available on the public Internet. This section is aimed at a server set up in a private network like on a Raspberry Pi.** So if blocking works using `eth0` but stops working for `tun0`, as described [here](https://github.com/pi-hole/pi-hole/issues/1553), you may want to run this command `pihole -a -i all`, which should get the behavior you want by opening pihole-FTL up to listen on all ports. This is not recommended for cloud servers as they should _not_ be listening on `eth0`. diff --git a/docs/guides/vpn/openvpn/dynDNS.md b/docs/guides/vpn/openvpn/dynDNS.md index 040cf9a..7b8c3f3 100644 --- a/docs/guides/vpn/openvpn/dynDNS.md +++ b/docs/guides/vpn/openvpn/dynDNS.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + If you operate your Pi-hole + OpenVPN at home, you are likely sitting behind a NAT / dynamically changing IP address. In this case, you should set up a dynamic DNS record, which allows you to reach your server. You can exchange the address that has been configured during the setup of OpenVPN like this: ```bash diff --git a/docs/guides/vpn/openvpn/firewall.md b/docs/guides/vpn/openvpn/firewall.md index cdedaf0..cb24905 100644 --- a/docs/guides/vpn/openvpn/firewall.md +++ b/docs/guides/vpn/openvpn/firewall.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + ### (optional) Secure the server with firewall rules (`iptables`) **If you are behind a NAT and not running the Pi-hole on a cloud server, you do not need to issue the IPTABLES commands below as the firewall rules are already handled by the RoadWarrior installer, but you will need to portforward whatever port you chose in the setup from your public ip to your device using your router.** diff --git a/docs/guides/vpn/openvpn/installation.md b/docs/guides/vpn/openvpn/installation.md index 853e372..dc85e0c 100644 --- a/docs/guides/vpn/openvpn/installation.md +++ b/docs/guides/vpn/openvpn/installation.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + ## Install an operating system Once you have your preferred OS up and running. You may already have a server set up on your network, or you may prefer to make a [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1) droplet. In either case, you'll use the quick OpenVPN "road warrior" installer. The cloud-hosted server option is convenient if you don't want to host the hardware at home, but you'll need to take additional steps to secure the server as it's available on the public Internet. Failure to do so is [not only irresponsible, but you also put yourself and others at risk](https://us-cert.cisa.gov/ncas/alerts/TA13-088A). diff --git a/docs/guides/vpn/openvpn/only-dns-via-vpn.md b/docs/guides/vpn/openvpn/only-dns-via-vpn.md index 1f42eba..f7c64b6 100644 --- a/docs/guides/vpn/openvpn/only-dns-via-vpn.md +++ b/docs/guides/vpn/openvpn/only-dns-via-vpn.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + ### Optional: Only route DNS via VPN With this setup, you will force connected clients to use **only the DNS provided by the VPN connection, i.e. the Pi-hole.** Do this only if you **don't** want to tunnel all traffic from the client through the VPN, but only its DNS queries. diff --git a/docs/guides/vpn/openvpn/overview.md b/docs/guides/vpn/openvpn/overview.md index aee7c87..272021d 100644 --- a/docs/guides/vpn/openvpn/overview.md +++ b/docs/guides/vpn/openvpn/overview.md @@ -1,4 +1,6 @@ ->This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server (such as [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1)). If you wish to have this working on your home network, you will need to tailor Pi-hole to listen on `eth0` (or similar), which we explain in [this section of the tutorial](dual-operation.md). +{!guides/vpn/openvpn/deprecation_notice.md!} + +This tutorial is tailored for setting up OpenVPN on a cloud-hosted virtual server (such as [Digital Ocean](https://www.digitalocean.com/?refcode=344d234950e1)). If you wish to have this working on your home network, you will need to tailor Pi-hole to listen on `eth0` (or similar), which we explain in [this section of the tutorial](dual-operation.md). ### High-level Overview diff --git a/docs/guides/vpn/openvpn/setup-openvpn-server.md b/docs/guides/vpn/openvpn/setup-openvpn-server.md index 3aafa8d..6a8035a 100644 --- a/docs/guides/vpn/openvpn/setup-openvpn-server.md +++ b/docs/guides/vpn/openvpn/setup-openvpn-server.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + ### Change OpenVPN's resolvers First, find the IP of your `tun0` interface: diff --git a/docs/guides/vpn/openvpn/troubleshooting.md b/docs/guides/vpn/openvpn/troubleshooting.md index d369f65..09cf5fb 100644 --- a/docs/guides/vpn/openvpn/troubleshooting.md +++ b/docs/guides/vpn/openvpn/troubleshooting.md @@ -1,3 +1,5 @@ +{!guides/vpn/openvpn/deprecation_notice.md!} + ### CRL expired OpenVPN 2.4 and newer check the validity of the Certificate Revocation List (CRL). This can result in a sudden malfunction of `openvpn` after an update even though no configuration files have changed. This error manifests in the following, not very helpful, error on the client's side: diff --git a/mkdocs.yml b/mkdocs.yml index f2cdc81..5bb5522 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,6 +80,9 @@ markdown_extensions: # Adds the ability to define abbreviations (https://squidfunk.github.io/mkdocs-material/reference/tooltips/) - abbr - attr_list + # Include files in other documents like {!some/dir/in/docs/filename.md!} + - markdown_include.include: + base_path: docs - pymdownx.snippets: # auto_append abbreviations.md to every file # https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary diff --git a/requirements.txt b/requirements.txt index 21f9559..c71068c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,3 +2,4 @@ mkdocs==1.5.2 mkdocs-git-revision-date-localized-plugin==1.2.0 mkdocs-material==9.2.6 mkdocs-redirects==1.2.1 +markdown-include==0.8.1