├── .github └── workflows │ └── static.yml ├── .gitignore ├── .releaserc ├── .travis.yml ├── Dockerfile ├── LICENSE ├── README.md ├── docs ├── faq.md ├── guides │ ├── dynamic-dns.md │ └── user-data.md ├── img │ ├── favicon-16x16.png │ ├── favicon-32x32.png │ ├── favicon.ico │ ├── logos.jpg │ ├── pivpnbanner-white.png │ ├── pivpnbanner.png │ └── pivpnlogo.png ├── index.md ├── install.md ├── openvpn.md ├── projects.md ├── robots.txt └── wireguard.md ├── mkdocs.yml └── nginx └── docs.conf /.github/workflows/static.yml: -------------------------------------------------------------------------------- 1 | # Simple workflow for deploying static content to GitHub Pages 2 | name: Deploy static content to Pages 3 | 4 | on: 5 | # Runs on pushes targeting the default branch 6 | push: 7 | branches: ["master"] 8 | 9 | # Allows you to run this workflow manually from the Actions tab 10 | workflow_dispatch: 11 | 12 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 13 | permissions: 14 | contents: read 15 | pages: write 16 | id-token: write 17 | 18 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. 19 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. 20 | concurrency: 21 | group: "pages" 22 | cancel-in-progress: false 23 | 24 | jobs: 25 | # Single deploy job since we're just deploying 26 | deploy: 27 | environment: 28 | name: github-pages 29 | url: ${{ steps.deployment.outputs.page_url }} 30 | runs-on: ubuntu-latest 31 | steps: 32 | - name: Checkout 33 | uses: actions/checkout@v4 34 | - uses: actions/setup-python@v4 35 | with: 36 | python-version: 3.x 37 | - run: pip install mkdocs-material 38 | name: install mkdocs-material 39 | - run: mkdocs build 40 | - name: Setup Pages 41 | uses: actions/configure-pages@v4 42 | - name: Upload artifact 43 | uses: actions/upload-pages-artifact@v3 44 | with: 45 | # Upload entire repository 46 | path: './site' 47 | - name: Deploy to GitHub Pages 48 | id: deployment 49 | uses: actions/deploy-pages@v4 50 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | site 2 | -------------------------------------------------------------------------------- /.releaserc: -------------------------------------------------------------------------------- 1 | { 2 | "name": "docs.pivpn.io", 3 | "plugins": [ 4 | "@semantic-release/commit-analyzer", 5 | "@semantic-release/release-notes-generator", 6 | [ 7 | "@semantic-release/changelog", 8 | { 9 | "changelogFile": "./CHANGELOG.md" 10 | } 11 | ], 12 | ["@semantic-release/github", { 13 | "assets": [ 14 | {"path": "dist/asset.min.css", "label": "CSS distribution"}, 15 | {"path": "dist/asset.min.js", "label": "JS distribution"} 16 | ] 17 | }], 18 | [ 19 | "@semantic-release-plus/docker", 20 | { 21 | "name": "pivpn/docs" 22 | } 23 | ], 24 | ], 25 | "devDependencies": { 26 | "@semantic-release/gitlab": "^7.0.3", 27 | "semantic-release": "^18.0.0" 28 | }, 29 | "release": { 30 | "branches": [ 31 | "master", 32 | ] 33 | } 34 | } 35 | 36 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | os: linux 2 | dist: focal 3 | language: python 4 | python: 5 | - "3.9" 6 | services: 7 | - docker 8 | 9 | stages: 10 | - test 11 | - name: "release" 12 | if: type = push 13 | 14 | jobs: 15 | include: 16 | - stage: test 17 | name: "Test" 18 | if: type = pull_request 19 | before_install: 20 | - python -V 21 | install: 22 | - pip install mkdocs-material 23 | before_script: 24 | - mkdocs --version 25 | script: 26 | - mkdocs build 27 | 28 | - stage: "publish" 29 | name: "publish" 30 | if: branch = master 31 | env: 32 | - IMAGE=pivpn/docs 33 | before_install: 34 | - nvm install 17 35 | - python -V 36 | - node -v 37 | install: 38 | - pip install mkdocs-material 39 | - npm install @semantic-release/github -D 40 | - npm install @semantic-release/changelog -D 41 | - npm install @semantic-release-plus/docker -D 42 | before_script: 43 | - mkdocs --version 44 | - echo $DOCKER_PASSWORD | docker login -u $DOCKER_USERNAME --password-stdin 45 | script: 46 | - mkdocs build 47 | - docker build -t $IMAGE . 48 | - npx semantic-release 49 | 50 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM nginx 2 | 3 | HEALTHCHECK --interval=30s --timeout=3s \ 4 | CMD curl -f http://localhost/ || exit 1 5 | 6 | ADD site /usr/share/nginx/html 7 | COPY nginx/docs.conf /etc/nginx/conf.d/docs.conf 8 | RUN find /usr/share/nginx/html -type d -exec chmod 755 {} \; 9 | RUN find /usr/share/nginx/html -type f -exec chmod 644 {} \; 10 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) [year] [fullname] 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ![Pivpn Banner](docs/img/pivpnbanner.png) 2 | 3 | [![Deploy static content to Pages](https://github.com/pivpn/docs/actions/workflows/static.yml/badge.svg)](https://github.com/pivpn/docs/actions/workflows/static.yml) 4 | 5 | ## Documentation & User Guides 6 | 7 | This repo is the source for the official [PiVPN Documentation](https://docs.pivpn.io). 8 | 9 | ### How to contribute 10 | 11 | PiVPN Documentation is powered by [MKDocs-Material](https://squidfunk.github.io/mkdocs-material/), 12 | 13 | Please refer to [MKDocs Documentation](https://www.mkdocs.org/user-guide/) and [MKDocs-Material Documentation](https://squidfunk.github.io/mkdocs-material/) for more detailed information for information on how to install or more detailed documentation 14 | 15 | To add a new link on the navigation panel you need to edit the `mkdocs.yml` file in the root of the repo. There is a guide for building the navbar at [mkdocs wiki](https://www.mkdocs.org/user-guide/configuration/#nav) 16 | 17 | To add a new document 18 | 19 | - Navigate to the `docs/` directory 20 | - Create the file using a URL friendly filename. 21 | EG. `docs/url-friendly.md` or `docs/guides/url-friendly.md` 22 | - Edit your document using Markdown, there are loads of resources available for the correct syntax. 23 | 24 | 25 | ### Test your changes 26 | 27 | When working on this repo, it is advised that you review your changes locally before committing them. The `mkdocs serve` command can be used to live preview your changes (as you type) on your local machine. 28 | 29 | * Install [MKDocs-Material](https://squidfunk.github.io/mkdocs-material/getting-started/) 30 | * Fork the repo 31 | * clone it locally with `git clone https://github.com/YOUR-USERNAME/docs` 32 | * run `mkdocs serve` 33 | * open browser, and access `localhost:8000` 34 | * Make your changes and verify them live while you do them 35 | * Commit code `git commit -a`, make sure you add a nice message to your commit 36 | * Push code to your fork `git push origin master` 37 | * Make Pull Request 38 | 39 | ### Deployment 40 | 41 | Once changes are merged to master branch, CI Pipeline will run and take care of everything. 42 | -------------------------------------------------------------------------------- /docs/faq.md: -------------------------------------------------------------------------------- 1 | title: FAQ 2 | summary: Frequently asked questions 3 | 4 | # FAQ (Frequently asked questions) 5 | 6 | ## What boards/OSes does PiVPN support? 7 | 8 | ### PiVPN runs at least on the following hardware 9 | 10 | * Raspberry Pi models (1/2/3/4/5/Zero) 11 | * All SBC's supported by [DietPi](https://dietpi.com/). 12 | * x86_64 (Intel and AMD) servers 13 | 14 | ### PiVPN Supports the following systems 15 | 16 | * Raspbian and Raspberry PI OS 17 | * Bullseye 18 | * Bookworm 19 | * Ubuntu Server 20 | * Focal Fossa (20.04) 21 | * Jammy Jellyfish (22.04) 22 | * Noble Numbat (24.04) 23 | * [DietPi](https://dietpi.com/) 24 | * [Alpine Linux](install.md#alpine) 25 | 26 | ### What about other Debian / Ubuntu based distributions? 27 | 28 | PiVPN may be able run and install VPN Protocols on any other Debian or Ubuntu based distributions however we do not provide support for them. 29 | 30 | ### What about docker? 31 | 32 | Support for docker images is currently experimental and we do not provide any official images or official support. There is no ETA for full support. 33 | 34 | ### What About Octopi? 35 | 36 | As per [Github Issue #373 on Octpi](https://github.com/guysoft/OctoPi/issues/373) OctoPi doesn't play well with PiVPN installer as they use a git wrapper that blocks it from running as root user. To disable the git wrapper please do: `sudo rm /root/bin/git` 37 | 38 | ### Can I have Wireguard and OpenVPN at the same time? 39 | 40 | Yes! All you have to do is to run PiVPN installation again. PiVPN will ask you what intend to do and setup everything for you. After the installation is finished all you have to do is to use `pivpn wg [options]` and `pivpn ovpn [options]` to manage each protocol. 41 | 42 | ``` 43 | # pivpn help 44 | ::: To pass off to the pivpn command for each protocol 45 | ::: 46 | ::: Usage: pivpn wg [option] 47 | ::: Usage: pivpn ovpn [option] 48 | ::: 49 | ::: -h, help Show this help dialog 50 | ::: -u, uninstall Uninstall pivpn from your system! 51 | ::: -bk, backup Backup VPN configs and user profiles 52 | ``` 53 | 54 | ## My ISP doesn't give me a static external IP address and my server IP address keeps changing! 55 | 56 | You will need a dynamic DNS service and a hostname. If your IP address changes, your hostname will then automatically point to the new IP address. Some free dynamic DNS services are , or . 57 | 58 | ### DynDns 59 | 60 | Refer to: [https://help.dyn.com/ddclient/](https://help.dyn.com/ddclient/) 61 | 62 | `apt-get install ddclient` 63 | 64 | `/etc/ddclient.conf` example config: 65 | ``` 66 | # Configuration file for ddclient generated by debconf 67 | # 68 | # /etc/ddclient.conf 69 | 70 | ssl=yes 71 | protocol=dyndns2 72 | use=web, web=checkip.dyndns.com, web-skip='IP Address' 73 | server=members.dyndns.org 74 | login=username 75 | password='password' 76 | mydyn.domain.com 77 | ``` 78 | 79 | If you use a namecheap domain your ddclient setup can be found [here](https://www.namecheap.com/support/knowledgebase/article.aspx/583/11/how-do-i-configure-ddclient). 80 | 81 | ## How do I troubleshoot connection issues? 82 | 83 | ### Preliminary checks 84 | 85 | - Confirm that all checks are [OK] using `pivpn -d`. 86 | 87 | In our case: 88 | 89 | ``` 90 | $ pivpn -d 91 | [...] 92 | :::: Self check :::: 93 | :: [OK] IP forwarding is enabled 94 | :: [OK] Iptables MASQUERADE rule set 95 | :: [OK] OpenVPN is running 96 | :: [OK] OpenVPN is enabled (it will automatically start on reboot) 97 | :: [OK] OpenVPN is listening on port 1194/udp 98 | ============================================= 99 | [...] 100 | ``` 101 | 102 | If your debug log shows some [ERR], accept the [Y/n], run `pivpn -d` again and verify that all checks pass. If not, stop here and look up the error (if you get any) among existing issues or open a new issue. 103 | 104 | *** 105 | 106 | - Verify that the server is running. 107 | - OpenVPN, restart the server with `sudo systemctl restart openvpn`, run `pivpn -d` and confirm that the snippet of the server log ends with `Initialization Sequence Completed`. 108 | - WireGuard, restart the server with `sudo systemctl restart wg-quick@wg0`. Run `lsmod | grep wireguard` and confirm that you get at least this output (numbers don't matter). 109 | 110 | ``` 111 | wireguard 225280 0 112 | ip6_udp_tunnel 16384 1 wireguard 113 | udp_tunnel 16384 1 wireguard 114 | ``` 115 | 116 | *** 117 | 118 | - Acquire the installation settings using `cat /etc/pivpn/wireguard/setupVars.conf` if using WireGuard or `cat /etc/pivpn/openvpn/setupVars.conf` if using OpenVPN. 119 | 120 | ``` 121 | [...] 122 | IPv4dev=eth0 <--- Network interface you have chosen 123 | 124 | IPv4addr=192.168.23.211/24 <--- IP address of the Raspberry Pi at the time of installation 125 | (only consider the 192.168.23.211 part) 126 | 127 | IPv4gw=192.168.23.1 <--- Gateway IP, which you will type into a web browser to open 128 | the management interface 129 | 130 | pivpnPROTO=udp <--- Protocol you need to use in the port forwarding entry 131 | 132 | pivpnPORT=1194 <--- Port you need to forward 133 | 134 | pivpnHOST=192.0.2.48 <--- Public IP or DNS name your clients will use to connect to 135 | the PiVPN 136 | [...] 137 | ``` 138 | 139 | *** 140 | 141 | - Check that the current IP address of the interface `IPv4dev` is the same as `IPv4addr`. You can see the current IP with `ip -f inet address show IPv4dev`. 142 | 143 | In our case: 144 | 145 | ``` 146 | $ ip -f inet address show eth0 147 | 2: eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 148 | `inet 192.168.23.211/24 brd 192.168.23.255 scope global dynamic eth0 149 | valid_lft 84694sec preferred_lft 84694sec 150 | ``` 151 | 152 | Confirmed: `192.168.23.211` is the same as the content of the `IPv4addr` variable. 153 | 154 | If it's not the same, go to your router admin webpage and reserve the static IP `IPv4addr` to the MAC address of the `IPv4dev` interface. To show the MAC address: `cat /sys/class/net/IPv4dev/address`. Then reboot the Raspberry Pi. 155 | 156 | *** 157 | 158 | - Check that the current public IP of your connection is the same as `pivpnHOST`. To check the current public IP: `curl -s https://checkip.amazonaws.com`. 159 | 160 | In our case: 161 | 162 | ``` 163 | $ curl -s https://checkip.amazonaws.com 164 | 192.0.2.48 165 | ``` 166 | 167 | Confirmed: `192.0.2.48` is the same as the content of the `pivpnHOST` variable. 168 | 169 | If the IP is different, then update the IP using the [OpenVPN](openvpn.md#changing-the-public-ipdns) or [WireGuard](wireguard.md#changing-the-public-ipdns) guide. If your IP changes frequently, the norm on most home connections, consider using a [Dynamic DNS](faq.md#my-isp-doesnt-give-me-a-static-external-ip-address-and-my-server-ip-address-keeps-changing). 170 | 171 | If you are already using a DDNS, and thus `pivpnHOST` contains your domain name, use `dig +short yourdomain.example.com` to check whether the returned IP matches `curl -s https://checkip.amazonaws.com`. 172 | 173 | ### Packet capture 174 | 175 | We will use `tcpdump` to take a peek into the network interface to see if packets are reaching our Raspberry Pi. 176 | 177 | First off, if you want to test the connection using your smartphone as a client, make sure to use MOBILE DATA, do not test from the same network where the Raspberry Pi is located. If you want to use a PC, connect to the internet via TETHERING/HOTSPOT. 178 | 179 | Connecting from the same network as the server not only doesn't make sense (you are already inside the network the VPN is supposed to connect you to) but may not work with many routers. 180 | 181 | From your device, go to https://ipleak.net and check what's your IP address, let's say we have 192.0.2.45. 182 | 183 | 1. Open a root shell: `sudo -s` 184 | 2. Install tcpdump: `apt install tcpdump -y` 185 | 3. Run `tcpdump -n -i IPv4dev pivpnPROTO port pivpnPORT` (it will block the terminal but don't worry) 186 | 4. Try to connect from your device 187 | 5. Shortly after you should see some packets being exchanged between your Raspberry Pi and your device 188 | 189 | In our case: 190 | 191 | ``` 192 | # tcpdump -n -i eth0 udp port 1194 193 | tcpdump: verbose output suppressed, use -v or -vv for full protocol decode 194 | listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes 195 | 10:57:38.952503 IP 192.0.2.45.28050 > 192.168.23.211.1194: UDP, length 32 <--- Your device sent a packet to the Raspberry Pi 196 | 10:57:49.109202 IP 192.168.23.211.1194 > 192.0.2.45.28050: UDP, length 128 <--- Your Raspberry Pi responded to your device 197 | 10:57:49.144774 IP 192.0.2.45.28050 > 192.168.23.211.1194: UDP, length 128 198 | 10:57:59.490185 IP 192.168.23.211.1194 > 192.0.2.45.28050: UDP, length 32 199 | ``` 200 | 201 | You are looking at udp or tcp packets coming to your Raspberry Pi on the port you specified, via the network interface (ethernet or wifi) you chose. The example output above is a successful conversation. 202 | 203 | Here's an unsuccessful one (no packets reach the Raspberry Pi): 204 | 205 | ``` 206 | tcpdump: verbose output suppressed, use -v or -vv for full protocol decode 207 | listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes 208 | ``` 209 | 210 | 6. Press CTRL-C to stop the capture 211 | 7. Exit the root shell: `exit` 212 | 213 | ### Tweaking MTU 214 | 215 | On some networks, you may see that packets are being exchanged, data transfer occurs in both directions (Rx/Tx) as seen in the WireGuard app or `pivpn -c`, but can't browse the web or connect to servers in the LAN. This is sometimes caused by improper [MTU](https://en.wikipedia.org/wiki/Maximum_transmission_unit). To attempt a fix, start from the default MTU of 1420 and lower the value by 10 until you find the highest that works. The MTU can be changed by adding/editing the `MTU = something` line of the `[Interface]` section of the client `.conf` file, or by changing the MTU section in the WireGuard app on Android and iOS. 216 | 217 | ### What to do if I see no packets? 218 | 219 | - If you set up PiVPN with ethernet and later switched to wifi, you will have a different IP. Easiest way to fix is to reinstall and pick the new network interface. 220 | - Check if your ISP uses Carrier-grade NAT (check online). With CGNAT, your router gets a private IP, making port forwarding ineffective. This is mostly the norm if your router connects via 4G/LTE. If that's the case, you need to ask the ISP for a public IP. 221 | - If you see packets coming to the Pi, but no response to the smartphone, it may indicate routing issues, attempts to block the connection (on either side), poor connectivity. In all cases, try to connect from a different network. It may also indicate misconfigured keys though this shouldn't happen with the official scripts. 222 | - If you have multiple chained routers, then you need to configure multiple port forwardings. Example: `(192.0.2.48) ISP router (192.168.1.1)` ---> `(192.168.1.2) Own router (192.168.23.1)` ---> `(192.168.23.211) Raspberry Pi`. Given that, on the ISP router port forward 1194 udp to 192.168.1.2 and on your own router port forward 1194 UDP to 192.168.23.211. 223 | - You may have misconfigured firewall rules on your Pi, open an issue and add the output of `sudo iptables -S` and `sudo iptables -t nat -S`. 224 | 225 | If you performed all the following steps and suggestions, but you still can't connect, open a new issue showing all the steps you followed to troubleshoot. Include the packet capture as well (censor client IPs if you want). Remember to follow the ISSUE TEMPLATE. 226 | -------------------------------------------------------------------------------- /docs/guides/dynamic-dns.md: -------------------------------------------------------------------------------- 1 | title: Dynamic DNS with DuckDNS 2 | summary: Setting up a dynamic dns so that your wireguard always connects. 3 | Authors: chriscn 4 | 5 | # Dynamic DNS 6 | After running PiVPN for a while you may notice that you are unable to connect anymore. This may be due to your Public IP being changed. You then have a dilemma, in order to connect to your VPN you need to known the IP; however you can't get that information unless you are on your internal network. 7 | 8 | The solution comes through [Dynamic DNS](https://en.wikipedia.org/wiki/Dynamic_DNS). Which will automatically update an A record on a specific domain name allowing you to always connect. 9 | 10 | There are several DynamicDNS providers, some free some not. This tutorial will cover [DuckDNS](https://www.duckdns.org/) however the same principles can apply to other providers. 11 | 12 | ## DuckDNS 13 | 1. Head to [DuckDNS](https://www.duckdns.org/) and Sign In with an account. 14 | 2. Head to [DuckDNS/Subdomains](https://www.duckdns.org/domains) and register a subdomain name. It can be whatever you like. 15 | 3. Head to [DuckDNS/Install](https://www.duckdns.org/install.jsp) and select **Linux CRON** and your domain name and follow the install instructions; you can run this on the same Raspberry Pi that you run PiVPN. You should end up with a file and cronjob running at `~/duckdns/duck.sh` 16 | 4. Once you've installed the script you need to change your configuration files and your setup variables. 17 | 1. `configs` - Within each configuration file change the `Endpoint` line from your old ip to your new domain name. Most likely `[].duckdns.org` 18 | 2. `setupVars` - Changing the values here will mean next time you create a client they'll have the new dynamic dns. 19 | 1. Change directory using `cd` to `/etc/pivpn/wireguard` and open the file `setupVars.conf` in your favourite text editor (you may need sudo), e.g. `sudo nano setupVars.conf`. 20 | 2. Change the `pivpnHOST` value to your new domain name. 21 | 5. Enjoy. You now have a dynamic dns setup on your raspberry pi ensuring that you can always connect to your VPN. 22 | -------------------------------------------------------------------------------- /docs/guides/user-data.md: -------------------------------------------------------------------------------- 1 | title: Cloud instance user data 2 | summary: How to run the script on cloud instance user data 3 | Authors: 4s3ti 4 | 5 | # Cloud instance user data 6 | 7 | PiVPN can be used to install OpenVPN or Wireguard completely unattended during a cloud instance boot (example AWS) 8 | 9 | !!! Note 10 | This info is focused at more advanced users that wish to have their own VPN in the cloud or spin up VPN servers on demand with PiVPN. 11 | 12 | * You should be comfortable reading bash and understanding what the provided scripts below are doing. 13 | * You should know what a cloud instance is 14 | * You should know what user data is 15 | 16 | 17 | 18 | Configuration file examples can be found [here](https://github.com/pivpn/pivpn/tree/master/examples) 19 | 20 | You can use the following script as an example and adjust the values to suit your needs 21 | 22 | ``` 23 | #!/bin/bash 24 | 25 | # Create options file 26 | cat << EOF > /tmp/options.conf 27 | USING_UFW=0 28 | IPv4dev=ens5 29 | install_user=admin 30 | install_home=/home/admin 31 | VPN=openvpn 32 | pivpnPROTO=udp 33 | pivpnPORT=1194 34 | pivpnDNS1=8.8.8.8 35 | pivpnDNS2=8.8.4.4 36 | TWO_POINT_FOUR=1 37 | pivpnENCRYPT=256 38 | USE_PREDEFINED_DH_PARAM=1 39 | INPUT_CHAIN_EDITED=0 40 | FORWARD_CHAIN_EDITED=0 41 | pivpnDEV=tun0 42 | pivpnNET=10.8.0.0 43 | subnetClass=24 44 | UNATTUPG=1 45 | EOF 46 | 47 | # Install git and clone pivpn repo 48 | apt update && apt install -y git 49 | git clone https://github.com/pivpn/pivpn /tmp/pivpn 50 | 51 | # Install PiVPN from options.conf 52 | cd /tmp/ || exit 53 | bash pivpn/auto_install/install.sh --unattended /tmp/options.conf 54 | ``` 55 | -------------------------------------------------------------------------------- /docs/img/favicon-16x16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pivpn/docs/78369f003cc8a6e671b957f4c812214c9fcb3914/docs/img/favicon-16x16.png -------------------------------------------------------------------------------- /docs/img/favicon-32x32.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pivpn/docs/78369f003cc8a6e671b957f4c812214c9fcb3914/docs/img/favicon-32x32.png -------------------------------------------------------------------------------- /docs/img/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pivpn/docs/78369f003cc8a6e671b957f4c812214c9fcb3914/docs/img/favicon.ico -------------------------------------------------------------------------------- /docs/img/logos.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pivpn/docs/78369f003cc8a6e671b957f4c812214c9fcb3914/docs/img/logos.jpg -------------------------------------------------------------------------------- /docs/img/pivpnbanner-white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pivpn/docs/78369f003cc8a6e671b957f4c812214c9fcb3914/docs/img/pivpnbanner-white.png -------------------------------------------------------------------------------- /docs/img/pivpnbanner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pivpn/docs/78369f003cc8a6e671b957f4c812214c9fcb3914/docs/img/pivpnbanner.png -------------------------------------------------------------------------------- /docs/img/pivpnlogo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pivpn/docs/78369f003cc8a6e671b957f4c812214c9fcb3914/docs/img/pivpnlogo.png -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | title: Home 2 | summary: Documentation homepage 3 | Authors: 4s3ti 4 | 5 | # Welcome to PiVPN Docs 6 | 7 | [![Logos](img/pivpnbanner.png)](https://pivpn.io) 8 | 9 | > [!WARNING] 10 | > PiVPN is maintained on a best-effort basis, please read more about it [here](https://github.com/pivpn/pivpn/releases/tag/v4.6.1). Previous announcement is [here](https://github.com/pivpn/pivpn/releases/tag/v4.6.0). 11 | 12 | ## How does PiVPN work? 13 | 14 | The script will first update your APT repositories, upgrade packages, and install WireGuard (default) or OpenVPN, which will take some time. 15 | 16 | It will ask which authentication method you wish the guts of your server to use. If you go for WireGuard, you don't get to choose: you will use a Curve25519 public key, which provides 128-bit security. On the other end, if you prefer OpenVPN, default settings will generate ECDSA certificates, which are based on Elliptic Curves, allowing much smaller keys while providing an equivalent security level to traditional RSA (256 bit long, equivalent to 3072 bit RSA). You can also use 384-bit and 521-bit, even though they are quite overkill. 17 | 18 | If you decide to customize settings, you will still be able to use RSA certificates if you need backward compatibility with older gear. You can choose between a 2048-bit, 3072-bit, or 4096-bit certificate. If you're unsure or don't have a convincing reason one way or the other I'd use 2048 today (provides 112-bit security). 19 | 20 | From the OpenVPN site: 21 | 22 | > For asymmetric keys, general wisdom is that 1024-bit keys are no longer sufficient to protect against well-equipped adversaries. Use of 2048-bit is a good minimum. It is wise to ensure all keys across your active PKI (including the CA root keypair) are using at least 2048-bit keys. 23 | 24 | > Up to 4096-bit is accepted by nearly all RSA systems (including OpenVPN), but use of keys this large will dramatically increase generation time, TLS handshake delays, and CPU usage for TLS operations; the benefit beyond 2048-bit keys is small enough not to be of great use at the current time. It is often a larger benefit to consider lower validity times than more bits past 2048, but that is for you to decide. 25 | 26 | 27 | After this, the script will go back to the command line as it builds the server's own certificate authority (OpenVPN only). The script will ask you if you'd like to change the default port, protocol, client's DNS server, etc. If you know you want to change these things, feel free, and the script will put all the information where it needs to go in the various config files. 28 | 29 | If you aren't sure, it has been designed that you can simply hit 'Enter' through all the questions and have a working configuration at the end. 30 | 31 | Finally, if you are using RSA, the script will take some time to build the server's Diffie-Hellman key exchange (OpenVPN only). If you chose 2048-bit encryption, it will take about 40 minutes on a Model B+, and several hours if you choose a larger size. 32 | 33 | The script will also make some changes to your system to allow it to forward internet traffic and allow VPN connections through the Pi's firewall. When the script informs you that it has finished configuring PiVPN, it will ask if you want to reboot. I have it where you do not need to reboot when done but it also can't hurt. 34 | 35 | After the installation is complete you can use the command `pivpn` to manage the server. Have a look at the [OpenVPN](https://github.com/pivpn/pivpn/wiki/OpenVPN) or [WireGuard](https://github.com/pivpn/pivpn/wiki/WireGuard) wiki for some example commands, connection instructions, FAQs, [troubleshooting steps](https://github.com/pivpn/pivpn/wiki/FAQ#how-do-i-troubleshoot-connection-issues). 36 | 37 | --- 38 | ## Feedback & Support 39 | 40 | Our prefered contact method is through [Github Discussions page](https://github.com/pivpn/pivpn/discussions), please make sure you read the [General Guidelines](https://github.com/pivpn/pivpn/blob/master/README.md#feedback--support) before opening any new issue or discussion. 41 | 42 | You can also reach out at: 43 | 44 | * \#pivpn at [libera.chat](https://libera.chat) IRC network 45 | * \#pivpn:matrix.org at [matrix.org](https://matrix.org) 46 | * Reddit at [r/pivpn](https://www.reddit.com/r/pivpn/) 47 | 48 | 49 | --- 50 | ## contributions 51 | 52 | PiVPN is not taking donations but if you want to show your appreciation, then contribute or leave feedback on suggestions or improvements. 53 | 54 | Contributions can come in all kinds of different ways! You don't need to be a developer to help out. 55 | 56 | * Please check the current [issues](https://github.com/pivpn/pivpn/issues) and [discussions](https://github.com/pivpn/pivpn/discussions). Maybe there is something you can help with 57 | * [Documentation](https://github.com/pivpn/docs)! Documentation is never good enough! There is always something missing, or typos, or better English! 58 | * Our [website](https://pivpn.io) is also Open Source. feel free to suggest any changes or improvements [here](https://github.com/pivpn/pivpn.io) 59 | * Testing!! Run pivpn in different ways, different systems, different configurations! Let us know if you find something! 60 | * Assisting other users in any of our official channels is also very welcomed 61 | 62 | Still, if you consider PiVPN useful and want to Donate instead, then consider donating to: 63 | 64 | 1. [PiVPN Contributors](https://github.com/pivpn/pivpn/graphs/contributors) 65 | 2. [OpenVPNSetup](https://github.com/StarshipEngineer/OpenVPN-Setup) 66 | 3. [pi-hole.net](https://github.com/pi-hole/pi-hole) 67 | 4. [OpenVPN](https://openvpn.net) 68 | 5. [WireGuard](https://www.wireguard.com/) 69 | 6. [EFF](https://www.eff.org/) 70 | -------------------------------------------------------------------------------- /docs/install.md: -------------------------------------------------------------------------------- 1 | title: Installation 2 | summary: How to install 3 | Authors: 4s3ti 4 | 5 | 6 | # Installation 7 | 8 | ## Method 1 9 | ```Shell 10 | curl -L https://install.pivpn.io | bash 11 | ``` 12 | 13 | ## Method 2 (direct link) 14 | ```Shell 15 | curl https://raw.githubusercontent.com/pivpn/pivpn/master/auto_install/install.sh | bash 16 | ``` 17 | 18 | ## Method 3 (clone repo) 19 | ```Shell 20 | git clone https://github.com/pivpn/pivpn.git 21 | bash pivpn/auto_install/install.sh 22 | ``` 23 | 24 | ## To install from Test/Development branch 25 | 26 | `curl -L https://test.pivpn.io | TESTING= bash` 27 | 28 | 29 | ## Non-interactive installation 30 | 31 | You can run the PiVPN installer from within scripts using the `--unattended` command line option provided with a .conf file. You can find examples [here](https://github.com/pivpn/pivpn/tree/master/examples). 32 | 33 | ``` 34 | curl -L https://install.pivpn.io > install.sh 35 | chmod +x install.sh 36 | ./install.sh --unattended options.conf 37 | ``` 38 | 39 | It's not required to specify all options. If some of them are missing, they will be filled with defaults or generated at runtime if it can be done unambiguously. For example if you have just one network interface, such interface will be used but if you have more, the script will stop. 40 | 41 | If not specified, `IPv4addr` and `IPv4gw` default to the current network settings, `pivpnHOST` to the public IP, `pivpnSEARCHDOMAIN` to empty. Rest of the default options are in the examples. 42 | 43 | The options provided must make sense in relation to each other, for example you can't use `TWO_POINT_FOUR=1` with `pivpnENCRYPT=2048`. 44 | 45 | ## To install from custom git url and branch (for DEV) 46 | 47 | This is inteded to be used when testing changes during 48 | development and **not** for standard installations. 49 | Without this the script will always checkout the master branch. 50 | 51 | - Git repo can be pivpn or any other git repo (e.g. a fork). 52 | - Git branch can be specified as required 53 | 54 | #### Syntax 55 | 56 | ```shell 57 | git clone < customgitrepourl > 58 | bash pivpn/auto_install/install.sh --giturl < customgitrepourl > --gitbranch < customgitbranch > 59 | ``` 60 | 61 | #### Example 62 | ```shell 63 | git clone https://github.com/userthatforked/pivpn.git 64 | bash pivpn/auto_install/install.sh --giturl https://github.com/userthatforked/pivpn.git --gitbranch myfeaturebranch 65 | ``` 66 | 67 | The unattended setup config also supports a custom giturl and branch. 68 | 69 | ```shell 70 | pivpnGitUrl="https://github.com/userthatforked/pivpn.git" 71 | pivpnGitBranch="myfeaturebranch" 72 | ``` 73 | 74 | ## Alpine 75 | 76 | ### Requirements 77 | 78 | * Bash 79 | * `apk add bash` 80 | * busybox openrc initscripts 81 | * v3.16 or earlier 82 | * `apk add busybox-initscripts` 83 | * v3.17+ 84 | * `apk add busybox-openrc` 85 | * run as root or have sudo installed 86 | * `apk add sudo; echo '%wheel ALL=(ALL) ALL' > /etc/sudoers.d/wheel` 87 | 88 | Enable the community [repository](https://wiki.alpinelinux.org/wiki/Repositories) 89 | 90 | #### AWS Cloud Images (AMI) 91 | 92 | On AWS sudo is is not available by default in the the Alpine AMI'and you should use `doas` to install the required dependencies. 93 | 94 | ``` 95 | doas su 96 | apk add bash 97 | apk add busybox-initscripts 98 | apk add sudo 99 | echo '%wheel ALL=(ALL) ALL' > wheel 100 | mv wheel /etc/sudoers.d/ 101 | chown root:root /etc/sudoers.d/wheel 102 | ``` 103 | 104 | ## Docker (experimental) 105 | 106 | It is currently possible to use PiVPN on Alpine Containers 107 | 108 | * The container should meet the [Alpine requirements](#alpine) 109 | * The container should run with `--cap_add NET_ADMIN` 110 | * The container needs to have access to `/sys/fs/cgroup` (`-v /sys/fs/cgroup` or `VOLUME [ "/sys/fs/cgroup" ]` in the Dockerfile) 111 | 112 | !!! note 113 | This is experimental and we are not providing offical support or images. 114 | 115 | Sharing PiVPN/Wireguard/OpenVPN Images is not advised 116 | 117 | Feel free to open a [Discussion](https://github.com/pivpn/pivpn/discussions) 118 | 119 | ## Updating pivpn 120 | 121 | VPN protocols are updated via system package manager 122 | 123 | !!! note 124 | Read [Updating OpenVPN](openvpn.md#updating-openvpn) or [Updating Wireguard](wireguard.md#updating-wireguard) for information on how to update the VPN protocol. 125 | 126 | ## Uninstall 127 | 128 | If at any point you wish to remove PiVPN from your Pi and revert it to a pre-installation state, such as if you want to undo a failed installation to try again or you want to remove PiVPN without installing a fresh Raspbian image, just run `pivpn uninstall`. 129 | -------------------------------------------------------------------------------- /docs/openvpn.md: -------------------------------------------------------------------------------- 1 | title: OpenVPN 2 | summary: PiVPN/OpenVPN Specific information 3 | 4 | # PiVPN OpenVPN 5 | 6 | ## List of commands 7 | 8 | ``` 9 | -a, add [nopass] Create a client ovpn profile, optional nopass" 10 | -c, clients List any connected clients to the server" 11 | -d, debug Start a debugging session if having trouble" 12 | -l, list List all valid and revoked certificates" 13 | -r, revoke Revoke a client ovpn profile" 14 | -h, help Show this help dialog" 15 | -u, uninstall Uninstall PiVPN from your system!" 16 | -up, update Updates PiVPN Scripts" 17 | -bk, backup Backup Openvpn and ovpns dir" 18 | ``` 19 | 20 | ### Creating new client certificate 21 | 22 | `pivpn add` 23 | 24 | You will be prompted to enter a name for your client. Pick anything you like and hit 'enter'. 25 | You will be asked to enter a pass phrase for the client key; make sure it's one you'll remember. 26 | The script will assemble the client .ovpn file and place it in the directory 'ovpns' within your 27 | home directory. 28 | 29 | If you need to create a client certificate that is not password protected (IE for use on a router), 30 | then you can use the 'pivpn add nopass' option to generate that. 31 | 32 | ### Revoking a client certificate 33 | 34 | `pivpn revoke` 35 | 36 | Asks you for the name of the client to revoke. Once you revoke a client, it will no longer allow you to use 37 | the given client certificate (ovpn config) to connect. This is useful for many reasons but some ex: 38 | You have a profile on a mobile phone and it was lost or stolen. Revoke its cert and generate a new 39 | one for your new phone. Or even if you suspect that a cert may have been compromised in any way, 40 | just revoke it and generate a new one. 41 | 42 | ### Listing clients 43 | 44 | `pivpn list` 45 | 46 | If you add more than a few clients, this gives you a nice list of their names and whether their certificate 47 | is still valid or has been revoked. Great way to keep track of what you did with 'pivpn add' and 'pivpn revoke'. 48 | 49 | ### Creating a server backup 50 | 51 | `pivpn backup` 52 | 53 | Creates a backup archive of your OpenVPN Settings and Client certificates, and places it on your pivpn user home directory 54 | 55 | ### Help with troubleshooting 56 | 57 | `pivpn debug` 58 | 59 | Outputs setup information needed when troubleshooting issues 60 | 61 | ## Importing client profiles 62 | 63 | ### Windows 64 | 65 | Use a program like WinSCP or Cyberduck. Note that you may need administrator permission to move files to some folders on your Windows machine, so if you have trouble transferring the profile to a particular folder with your chosen file transfer program, try moving it to your desktop. 66 | 67 | ### Mac/Linux 68 | 69 | Open the Terminal app and copy the config from the Raspberry Pi to a target directory on your local machine: 70 | 71 | `scp pi-user@ip-of-your-raspberry:ovpns/whatever.ovpn path/to/target` 72 | 73 | ### Android 74 | 75 | You can either retrieve it on PC and then move it to your device via USB, or you can use an app like Turbo FTP & SFTP client to retrieve it directly from your Android device. 76 | 77 | ### iOS 78 | 79 | You can use an app that supports SFTP like Documents by Readdle to retrieve it directly from your iOS device. 80 | 81 | ## Connecting to OpenVPN 82 | 83 | ### Windows 84 | 85 | Download the [OpenVPN GUI](https://openvpn.net/community-downloads/), install it, and place the profile in the 'config' folder of your OpenVPN directory, i.e., in 'C:\Program Files\OpenVPN\config'. After importing, connect to the VPN server on Windows by running the OpenVPN GUI with administrator permissions, right-clicking on the icon in the system tray, and clicking 'Connect'. 86 | 87 | ### Linux 88 | 89 | Install OpenVPN using your package manager (APT in this example). Now, as root user, create the /etc/openvpn/client folder and prevent anyone but root to enter it (you only need to do this the first time): 90 | ``` 91 | apt install openvpn 92 | mkdir -p /etc/openvpn/client 93 | chown root:root /etc/openvpn/client 94 | chmod 700 /etc/openvpn/client 95 | ``` 96 | Move the config and connect (input the pass phrase if you set one): 97 | ``` 98 | mv whatever.ovpn /etc/openvpn/client/ 99 | openvpn /etc/openvpn/client/whatever.ovpn 100 | ``` 101 | Press CTRL-C to disconnect. 102 | 103 | ### Mac 104 | 105 | You can use an OpenVPN client like [Tunnelblick](https://tunnelblick.net/downloads.html). Here's a [guide](https://tunnelblick.net/czUsing.html) to import the configuration. 106 | 107 | ### Android 108 | 109 | Install the [OpenVPN Connect app](https://play.google.com/store/apps/details?id=net.openvpn.openvpn), select 'Import' from the drop-down menu in the upper right corner of the main screen, choose the directory on your device where you stored the .ovpn file, and select the file. Connect by selecting the profile under 'OpenVPN Profile' and pressing 'Connect'. 110 | 111 | ### iOS 112 | 113 | Install the [OpenVPN Connect app](https://apps.apple.com/it/app/openvpn-connect/id590379981). Then go to the app where you copied the .ovpn file to, select the file, find an icon or button to 'Share' or 'Open with', and choose to open with the OpenVPN app. 114 | 115 | ## Pi-hole with PiVPN 116 | You can safely install PiVPN on the same Raspberry Pi as your Pi-hole install, and point your VPN clients to the IP of your Pi-hole so they get ad blocking, etc. (replace `192.168.23.211` with the LAN IP of your Raspberry Pi). 117 | 118 | Note that if you install PiVPN after Pi-hole, your existing Pi-hole installation will be detected and the script will ask if you want to use it as the DNS for the VPN, so you won't need to go through all these steps. 119 | 120 | 1. Edit the server config with `sudo nano /etc/openvpn/server.conf` 121 | 2. Remove every `push "dhcp-option DNS [...]"` line 122 | 3. Add this line `push "dhcp-option DNS 192.168.23.211"` to point clients to the Pi-hole IP 123 | 4. Save the file and exit 124 | 5. Restart openvpn with `sudo systemctl restart openvpn` 125 | 6. Run `pihole -a -i local` to tell Pi-hole to listen on all interfaces 126 | 127 | ## Changing the public IP/DNS 128 | You will need to change `/etc/openvpn/easy-rsa/pki/Default.txt` and your `.ovpn` files if you have already generated them. 129 | 130 | ## Blocking Internet access 131 | 132 | If you want clients to have access to your network but not route internet traffic through VPN, edit `/etc/openvpn/server.conf` and replace: 133 | 134 | `push "redirect-gateway def1"` with `push "route 192.168.23.0 255.255.255.0"` 135 | 136 | **OBS:** Replace `192.168.23.0` and `255.255.255.0` with the correct values for your network 137 | 138 | Restart the openvpn service: `sudo systemctl restart openvpn` 139 | 140 | ## Migrating PiVPN & OpenVPN 141 | 142 | Backup your server with `pivpn -bk` 143 | copy the tar archive to your computer. 144 | example using scp on linux: 145 | 146 | `scp @:~/pivpnbackup/ ` 147 | 148 | **Install OpenVPN on the new pi/server** 149 | 150 | 1. Backup the current install: `sudo cp -r /etc/openvpn /etc/openvpn_backup` 151 | 2. Extract the backup archive: `tar xzpfv ` 152 | 3. Copy the extracted content: `sudo cp -r etc/openvpn /etc` 153 | 4. Restart the openvpn service: `sudo systemctl restart openvpn` 154 | 155 | **OBS:** Please be aware of the difference between `/etc/` and `etc/`! 156 | /etc with the starting slash is a system directory 157 | etc/ without starting slash and tailing slash means its a directory in your current working dir. 158 | 159 | ## Resolving local hostnames 160 | 161 | All you have to do is to use your router as DNS Server instead of using other public DNS providers. 162 | If you have already a working installation of OpenVPN, all you need to do is to edit `/etc/openvpn/server.conf` and replace every `push "dhcp-option DNS [...]"` line, with A SINGLE `push "dhcp-option DNS 192.168.23.1"` (assuming 192.168.23.1 is your gateway IP). Then restart the openvpn service: `sudo systemctl restart openvpn`. 163 | 164 | Alternatively you can change `/etc/hosts` file and add ` ` 165 | Example: 166 | ``` 167 | 192.168.1.1 JohnDoeRouter 168 | 192.168.1.2 JohnDoePC 169 | 192.168.1.3 JaneDoePC 170 | 192.168.1.4 CatPC 171 | 192.168.1.5 DogPC 172 | ``` 173 | ## Updating OpenVPN 174 | 175 | **PC/Desktop only!!** 176 | 177 | If you installed an earlier version of PiVPN and wish to update OpenVPN to a newer version just do the following steps: 178 | 179 | ``` 180 | sudo -s 181 | wget -O - https://swupdate.openvpn.net/repos/repo-public.gpg | apt-key add - 182 | echo "deb http://build.openvpn.net/debian/openvpn/stable [osrelease] main" > /etc/apt/sources.list.d/openvpn-aptrepo.list 183 | exit 184 | ``` 185 | 186 | Where [osrelease] should be replaced with: 187 | - **stretch** (Debian 9.x) 188 | - **buster** (Debian 10.x) 189 | - **xenial** (Ubuntu 16.04) 190 | - **bionic** (Ubuntu 18.04) 191 | 192 | More information can be found here: 193 | 194 | ## Setting up static IP for clients 195 | 196 | **If you installed PiVPN on or after Feb 17th 2020 static IPs are set by default.** 197 | 198 | 1. Add this line `client-config-dir /etc/openvpn/ccd` in `/etc/openvpn/server.conf` 199 | 2. Create client config directory: `sudo mkdir /etc/openvpn/ccd` 200 | 3. Fix permissions: `sudo chown -R openvpn:openvpn /etc/openvpn/ccd` 201 | 4. Adding clients: `sudo nano /etc/openvpn/ccd/exampleuser` (Add clients with their common name, in this case `exampleuser.ovpn`) 202 | 5. Configuring static IP: add this line `ifconfig-push 10.8.0.3 255.255.255.0` to `/etc/openvpn/ccd/exampleuser` 203 | 6. Restart openvpn with `sudo systemctl restart openvpn` 204 | 205 | (Here 10.8.0.3 is going to be static IP for user `exampleuser`, if you want to configure additional users, repeat from step 4) 206 | 207 | **Note: You have to assign static IP for all clients in order to avoid IP address conflict.** 208 | 209 | ## kicking a connected client 210 | 211 | From issue [#577](https://github.com/pivpn/pivpn/issues/577) 212 | 213 | 1. Stop the server with `sudo systemctl openvpn stop` 214 | 2. Edit the server config with `sudo nano /etc/openvpn/server.conf` 215 | 3. Add this line`management 127.0.0.1 PORT` (replace PORT with a port number, like 1234) 216 | 3. Save the file and exit 217 | 5. Start the server with `sudo systemctl openvpn start` 218 | 219 | To connect to the management interface, use `nc 127.0.0.1 PORT`, then disconnect a client with `kill CLIENTNAME`, use CTRL-C to exit. 220 | 221 | More info [here](https://openvpn.net/community-resources/management-interface/). Consider also setting a password on the management interface as suggested on the [manual](https://community.openvpn.net/openvpn/wiki/Openvpn24ManPage). 222 | 223 | ## Connecting over mobile data 224 | 225 | Trouble connecting over mobile data? Try [this](https://github.com/pivpn/pivpn/issues/54) 226 | 227 | ## Trouble with Telekom Hybrid 228 | 229 | If you have problems with the connections you can test the following: 230 | 231 | Add `tun-mtu 1316` in `/etc/openvpn/easy-rsa/pki/Default.txt` to set a hybrid compatible MTU size (for newly created .ovpn files). For already existing .ovpn files `tun-mtu 1316` can also be inserted there manually. With Telekom hybrid connections, you may have to experiment a little with MTU (`tun-mtu`, `link-mtu` and `mssfix`). 232 | 233 | 234 | ## OpenVPN Technical Information 235 | 236 | ### Info on TLS 237 | 238 | 'Modern' OpenVPN (2.x, using the TLS mode) basically sets up two connections: 239 | 240 | The 'control channel'. This is a low bandwidth channel, over which e.g. network parameters and key material for the 'data channel' is exchanged'. OpenVPN uses TLS to protect control channel packets. 241 | The 'data channel'. This is the channel over which the actual VPN traffic is sent. This channel is keyed with key material exchanged over the control channel. 242 | Both these channels are duplexed over a single TCP or UDP port. 243 | 244 | --tls-cipher controls the cipher used by the control channel. --cipher together with --auth control the protection of the data channel. 245 | 246 | And regarding security, OpenVPN uses encrypt-then-mac for its data channel, rather than mac-then-encrypt like TLS. All the CBC-related issues you hear about are due to the combination mac-then-encrypt + CBC. This means that AES-CBC for the data channel is perfectly fine from a security perspective. 247 | 248 | (And there is no GCM support for the data channel yet. That will arrive in OpenVPN 2.4.) 249 | 250 | If I wanted to specify ciphers, this is the list I'd use (I think): 251 | 252 | ``` 253 | TLS-ECDHE-RSA-WITH-AES-256-GCM-SHA384 254 | TLS-ECDHE-ECDSA-WITH-AES-256-GCM-SHA384 255 | TLS-ECDHE-RSA-WITH-AES-256-CBC-SHA384 256 | TLS-ECDHE-ECDSA-WITH-AES-256-CBC-SHA384 257 | TLS-DHE-RSA-WITH-AES-256-GCM-SHA384 258 | TLS-DHE-RSA-WITH-AES-256-CBC-SHA256 259 | TLS-DHE-RSA-WITH-AES-128-GCM-SHA256 260 | TLS-DHE-RSA-WITH-AES-128-CBC-SHA256 261 | ``` 262 | -------------------------------------------------------------------------------- /docs/projects.md: -------------------------------------------------------------------------------- 1 | title: Tutorials & Related Projects 2 | summary: list of tutorials and related projects 3 | 4 | !!! warning 5 | Items on this page can be outdated, and they should be taken only as references. 6 | 7 | ## Blogs / Video's About PiVPN 8 | 9 | The links below showcase some good write-ups and tutorials that use PiVPN. 10 | Some other decent information may also be contained regarding VPNs and security in general. 11 | If you find you have more questions on this area then read and/or watch some of them below! 12 | 13 | * [Maintainer post about where to properly place a VPN](https://4s3ti.net/en/posts/vpnusage/) 14 | 15 | ## Video Guides 16 | 17 | * [Raspberry Pi - OpenVPN Setup via PiVPN](https://www.youtube.com/watch?v=pUBMcsvJfe4). 18 | > Note: I don't think you'd have to do anything with iptables as he shows. 19 | This shows connecting with Windows client. 20 | 21 | 22 | ## Related Projects 23 | 24 | * [StarshipEngineer/OpenVPN-Setup](https://github.com/StarshipEngineer/OpenVPN-Setup) 25 | Shell script to set up a OpenVPN server. 26 | * [InnovativeInventor/docker-pivpn](https://github.com/InnovativeInventor/docker-pivpn) 27 | A secure docker container that sets up PiVPN and SSH. 28 | * [OpenVPN](https://openvpn.net) 29 | The foundation for all open-source VPN projects. 30 | * [WireGuard](https://www.wireguard.com/) 31 | *An extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography.* 32 | -------------------------------------------------------------------------------- /docs/robots.txt: -------------------------------------------------------------------------------- 1 | User-agent: * 2 | -------------------------------------------------------------------------------- /docs/wireguard.md: -------------------------------------------------------------------------------- 1 | title: Wireguard 2 | summary: PiVPN/Wireguard Specific information 3 | 4 | # PiVPN Wireguard 5 | 6 | ## List of commands 7 | 8 | ``` 9 | -a, add Create a client conf profile 10 | -c, clients List any connected clients to the server 11 | -d, debug Start a debugging session if having trouble 12 | -l, list List all clients 13 | -qr, qrcode Show the qrcode of a client for use with the mobile app 14 | -r, remove Remove a client 15 | -h, help Show this help dialog 16 | -u, uninstall Uninstall pivpn from your system! 17 | -up, update Updates PiVPN Scripts 18 | -bk, backup Backup VPN configs and user profiles 19 | ``` 20 | 21 | ### Creating new client configuration 22 | 23 | `pivpn add` 24 | 25 | You will be prompted to enter a name for your client. Pick anything you like and hit 'enter'. The script will assemble the client .conf file and place it in the directory 'configs' within your home directory. 26 | 27 | ### Removing a client configuration 28 | 29 | `pivpn remove` 30 | 31 | Asks you for the name of the client to remove. Once you remove a client, it will no longer allow you to use 32 | the given client config (specifically its public key) to connect. This is useful for many reasons but one example: 33 | You have a profile on a mobile phone and it was lost or stolen. Remove its key and generate a new 34 | one for your new phone. Or even if you suspect that a key may have been compromised in any way, 35 | just remove it and generate a new one. 36 | 37 | ### Listing clients 38 | 39 | `pivpn list` 40 | 41 | If you add more than a few clients, this gives you a nice list of their names and associated keys. 42 | 43 | ### Creating a server backup 44 | 45 | `pivpn backup` 46 | 47 | Creates a backup archive of your Wireguard Settings and Client certificates, and places it on your pivpn user home directory 48 | 49 | ### Help with troubleshooting 50 | 51 | `pivpn debug` 52 | 53 | Outputs setup information needed when troubleshooting issues 54 | 55 | 56 | ## Importing client profiles 57 | 58 | ### Windows 59 | 60 | Use a program like WinSCP or Cyberduck. Note that you may need administrator permission to move files to some folders on your Windows machine, so if you have trouble transferring the profile to a particular folder with your chosen file transfer program, try moving it to your desktop. 61 | 62 | ### Mac/Linux 63 | 64 | Open the Terminal app and copy the config from the Raspberry Pi to a target directory on your local machine: 65 | 66 | `scp pi-user@ip-of-your-raspberry:configs/whatever.conf path/to/target`. 67 | 68 | ### Android / iOS 69 | 70 | Just skip to [Connecting to Wireguard](wireguard.md#androidios) below. 71 | 72 | ## Connecting to Wireguard 73 | 74 | ### Windows/Mac 75 | 76 | Download the [WireGuard GUI app](https://www.wireguard.com/install/), import the configuration and activate the tunnel. 77 | 78 | ### Linux 79 | 80 | Install [WireGuard](https://www.wireguard.com/install/) following the instructions for your distribution. Now, as root user, create the /etc/wireguard folder and prevent anyone but root to enter it (you only need to do this the first time): 81 | ``` 82 | mkdir -p /etc/wireguard 83 | chown root:root /etc/wireguard 84 | chmod 700 /etc/wireguard 85 | ``` 86 | Move the config and activate the tunnel: 87 | ``` 88 | mv whatever.conf /etc/wireguard/ 89 | wg-quick up whatever 90 | ``` 91 | Run `wg-quick down whatever` to deactivate the tunnel. 92 | 93 | ### Android/iOS 94 | 95 | Run `pivpn -qr` on the PiVPN server to generate a QR code of your config, download the Wireguard app [Android link](https://play.google.com/store/apps/details?id=com.wireguard.android) / [iOS link](https://apps.apple.com/it/app/wireguard/id1441195209), click the '+' sign and scan the QR code with your phone's camera. Flip the switch to activate the tunnel. 96 | 97 | !!! note 98 | If you are having deformed or weirdly formatted qrcodes, please try using `pivpn -qr -a256` to generate a qrcode in ansi256, this will generate a substantially bigger qrcode but plays nicely when using other types of fonts on your terminal. 99 | 100 | 101 | 102 | ## Pi-hole with PiVPN 103 | 104 | You can safely install PiVPN on the same Raspberry Pi as your Pi-hole install, and point your VPN clients to the IP of your Pi-hole so they get ad blocking, etc. (replace `192.168.23.211` with the LAN IP of your Raspberry Pi). 105 | 106 | !!! note 107 | if you install PiVPN **after** Pi-hole, your existing Pi-hole installation will be detected and the script will ask if you want to use it as the DNS for the VPN, so you won't need to go through the following steps. 108 | 109 | If you installed PiVPN **before** pi-hole: 110 | 111 | 1. Edit the PiVPN configuration with `/etc/pivpn/wireguard/setupVars.conf` 112 | 2. Remove the `pivpnDNS1=[...]` and `pivpnDNS2=[...]` lines 113 | 3. Add this line `pivpnDNS1=192.168.23.211` to point clients to the Pi-hole IP 114 | 4. Save the file and exit 115 | 5. Run `pihole -a -i local` to tell Pi-hole to listen on all interfaces 116 | 117 | New clients you generate will use Pi-hole but you need to manually edit existing clients: 118 | 119 | 1. Open your configuration, for example whatever.conf 120 | 2. Replace the line `DNS = [...], [...]` with this line `DNS = 192.168.23.211` 121 | 4. Save the file and connect again 122 | 123 | 124 | ## Changing the public IP/DNS 125 | 126 | 1. Edit the PiVPN configuration with `sudo nano /etc/pivpn/wireguard/setupVars.conf` 127 | 2. Update the `pivpnHOST=[...]` line 128 | 3. Save and exit 129 | 130 | New clients you generate will use the new endpoint but you need to manually edit existing clients: 131 | 132 | 1. Open your configuration, for example whatever.conf 133 | 2. Update the line `Endpoint = [...]:51820` 134 | 3. Save the file and connect again 135 | 136 | ## Blocking internet access 137 | 138 | Replace the following line in your client configuration: `AllowedIPs = 0.0.0.0/0, ::0/0` with `AllowedIPs = , , `. 139 | 140 | - `your-lan-ip/netmask` might be something like `192.168.0.1/24` (check your network settings to confirm); 141 | - `wireguard-ipv4/netmask` will likely be `10.19.17.0/24`; and 142 | - `wireguard-ipv6/netmask` will likely be `fd11:5ee:bad:c0de::/64`. 143 | 144 | The final line might look like `AllowedIPs = 192.168.0.1/24, 10.19.17.0/24, fd11:5ee:bad:c0de::/64`. 145 | 146 | If your PiVPN installation is older, it’s likely that Wireguard’s IPv4/netmask will be `10.6.0.0/24` instead. To confirm the exact values, check the `/etc/pivpn/wireguard/setupVars.conf` file, paying attention to the values of the `pivpnNET`, `subnetClass`, `pivpnNETv6` and `subnetClassv6` variables. 147 | 148 | The client configuration files are located in `/etc/wireguard/configs` and are only readable by the `root` user. After altering the file, `pivpn -qr` will generate QR code containing the altered value of `AllowedIPs`. 149 | 150 | To make PiVPN generate split-tunnels by default, alter the value of `ALLOWED_IPS` variable in `/etc/pivpn/wireguard/setupVars.conf` instead. All profiles generated after the change will be of a split-tunnel type. 151 | 152 | ## Migrating PiVPN & Wireguard 153 | 154 | Backup your server with `pivpn -bk` 155 | copy the tar archive to your computer. 156 | example using scp on Linux: 157 | 158 | `scp @:~/pivpnbackup/ ` 159 | 160 | 1. Backup the current (new instance) install: `sudo cp -r /etc/wireguard /etc/new_wireguard_backup` 161 | 2. Extract the backup archive: `tar xzpfv ` 162 | 3. Copy the extracted content: `sudo cp -r etc/wireguard /etc` 163 | 4. Restart the wireguard service: `sudo systemctl restart wg-quick@wg0` 164 | 165 | !!! warning 166 | Please be aware of the difference between `/etc/` and `etc/`!!! 167 | 168 | `/etc` with the starting slash is a system directory 169 | 170 | `etc/` without starting slash and tailing slash means its a directory in your current working dir. 171 | 172 | ## Resolving local hostnames 173 | 174 | 175 | All you have to do is to use your router as DNS Server instead of using other public DNS providers. 176 | If you have already a working installation of WireGuard, all you need to do is to edit your client config and change the line `DNS = [...], [...]` to `DNS = 192.168.23.1` (assuming 192.168.23.1 is your gateway IP). 177 | 178 | Alternatively you can change `/etc/hosts` file and add ` ` 179 | Example: 180 | ``` 181 | 192.168.1.1 JohnDoeRouter 182 | 192.168.1.2 JohnDoePC 183 | 192.168.1.3 JaneDoePC 184 | 192.168.1.4 CatPC 185 | 192.168.1.5 DogPC 186 | ``` 187 | 188 | ## Keep Wireguard connected / Connection issues / PersistentKeepalive 189 | 190 | Per default Wireguard connects on-demand which is fine for most situations. 191 | It's also the recommended configuration for mobile devices because of energy consumption. 192 | 193 | But it might be useful to keep the Wireguard connection up to avoid certain connection 194 | issues that can occur e.g. when NAT is being used which forces undesired disconnections. 195 | Keeping the connection up can also reduce the reconnection time a bit, even though 196 | Wireguard usually connects in under a second. 197 | 198 | A good value of thumb for this setting is 25 seconds. You may also put a lower number if required. Setting it to 0 turns the feature off, which is the default. ([Wireguard Quickstart Guide](https://www.wireguard.com/quickstart/#nat-and-firewall-traversal-persistence)) 199 | 200 | The WireGuard client config file required the config parameter 201 | `PersistentKeepalive = 25` in the `[Peer]` section. 202 | 203 | This setting will be added automatically to the client config profiles when added to 204 | the `/etc/pivpn/wireguard/setupVars.conf` file (`pivpnPERSISTENTKEEPALIVE=25`). 205 | 206 | ## Updating Wireguard 207 | 208 | !!! note 209 | if you installed PiVPN on or after March 17th 2020 WireGuard will be upgraded via the package manager (APT) 210 | 211 | Run `pivpn -wg` and follow the instructions. 212 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: docs.pivpn.io 2 | copyright: Copyright © 2020 PiVPN 3 | theme: 4 | icon: 5 | repo: fontawesome/brands/github 6 | name: material 7 | logo: img/pivpnlogo.png 8 | favicon: img/favicon.ico 9 | palette: 10 | primary: blue grey 11 | features: 12 | - navigation.expand 13 | 14 | repo_name: PiVPN 15 | repo_url: https://github.com/pivpn/pivpn 16 | edit_uri: https://pivpn/docs/master/docs 17 | 18 | markdown_extensions: 19 | - admonition 20 | 21 | nav: 22 | - index.md 23 | - install.md 24 | - openvpn.md 25 | - wireguard.md 26 | - faq.md 27 | - projects.md 28 | - Guides: 29 | - Dynamic DNS: guides/dynamic-dns.md 30 | - User Data: guides/user-data.md 31 | 32 | extra: 33 | social: 34 | - icon: fontawesome/brands/github 35 | link: https://github.com/pivpn/pivpn 36 | - icon: fontawesome/brands/reddit 37 | link: https://www.reddit.com/r/pivpn/ 38 | - icon: fontawesome/solid/globe 39 | link: https://pivpn.io 40 | - icon: fontawesome/solid/heart-pulse 41 | link: https://status.pivpn.io 42 | -------------------------------------------------------------------------------- /nginx/docs.conf: -------------------------------------------------------------------------------- 1 | server { 2 | listen 80; 3 | server_name docs.pivpn.io www.docs.pivpn.io; 4 | server_tokens off; 5 | etag off; 6 | root /usr/share/nginx/html; 7 | index index.html; 8 | autoindex off; 9 | error_page 404 403 https://docs.pivpn.io; 10 | 11 | #conditions & security 12 | if ($request_method !~ ^(GET|HEAD|POST)$) { 13 | return 444; 14 | } 15 | 16 | add_header x-xss-protection "1;mode=block" always; 17 | add_header x-frame-options "SAMEORIGIN" always; 18 | add_header x-content-type-options "nosniff" always; 19 | 20 | #locations 21 | location ~ /\.ht { 22 | deny all; 23 | } 24 | 25 | } 26 | 27 | server { 28 | listen 80; 29 | server_name docs.pivpn.dev www.docs.pivpn.dev; 30 | rewrite ^ https://docs.pivpn.io permanent; 31 | server_tokens off; 32 | etag off; 33 | root /usr/share/nginx/html; 34 | index index.html; 35 | autoindex off; 36 | error_page 404 403 https://docs.pivpn.io; 37 | 38 | #conditions & security 39 | if ($request_method !~ ^(GET|HEAD|POST)$) { 40 | return 444; 41 | } 42 | 43 | add_header x-xss-protection "1;mode=block" always; 44 | add_header x-frame-options "SAMEORIGIN" always; 45 | add_header x-content-type-options "nosniff" always; 46 | 47 | #locations 48 | location ~ /\.ht { 49 | deny all; 50 | } 51 | } 52 | --------------------------------------------------------------------------------