Skip to content

Commit

Permalink
feat(ossupport): Add Alpine & Jammy support info
Browse files Browse the repository at this point in the history 
add alipine documentation
update README
update hardware and OS info
make information more clear
add info about multiple protocols
Remove about, this info stays only on website and project README
Update feedback & support with only relevant data, avoid duplication cross repositories
update contributions
add info about experimental docker support
remove projects dead links
  • Loading branch information
@coolapso
coolapso committed Aug 26, 2022
1 parent 1b3a6df commit 93d84ba
Show file tree
Hide file tree
Showing 5 changed files with 109 additions and 107 deletions.
7 changes: 6 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ PiVPN Documentation is powered by [MKDocs-Material](https://squidfunk.github.io/

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


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)

To add a new document
Expand All @@ -24,6 +23,7 @@ To add a new document
EG. `docs/url-friendly.md` or `docs/guides/url-friendly.md`
- Edit your document using Markdown, there are loads of resources available for the correct syntax.


### Test your changes

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.
Expand All @@ -38,6 +38,11 @@ When working on this repo, it is advised that you review your changes locally be
* Push code to your fork `git push origin master`
* Make Pull Request


### Commit message style

when commiting changes, use [Angular commit message format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format).

### Deployment

Once changes are merged to master branch, CI Pipeline will run and take care of everything.
Expand Down
47 changes: 39 additions & 8 deletions docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,52 @@ summary: Frequently asked questions

## What boards/OSes does PiVPN support?

PiVPN runs at least on the following boards:
### PiVPN runs at least on the following hardware

* Raspberry Pi models (1/2/3/4/Zero) running Raspbian Stretch, Raspberry Pi OS Buster (32-bit), Ubuntu Server 20.04 Focal Fossa (32-bit and 64-bit).
* All SBC's running DietPi.
* Odroid C1, Odroid C2 (arm64), Odroid XU3/4, Pine A64, NanoPi NEO, NanoPi NEO Air, NanoPi M1.
* Most x86_64 (Intel and AMD) servers running a Debian or Ubuntu based distro.
* Raspberry Pi models (1/2/3/4/Zero)
* All SBC's supported by [DietPi](https://dietpi.com/).
* x86_64 (Intel and AMD) servers

## What About Octopi?
### PiVPN Supports the following systems

* Raspbian and Raspberry PI OS
* Stretch
* Buster
* Bullseye
* Ubuntu Server
* Bionic Beaver (18.04)
* Focal Fossa (20.04)
* Jammy Jellyfish (22.04)
* [DietPi](https://dietpi.com/)
* [Alpine Linux](install.md#alpine)

### What about other Debian / Ubuntu based distributions?

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.

### What about docker?

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.

### What About Octopi?

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`

## How do I know what changed in stable/master branch?
### Can I have Wireguard and OpenVPN at the same time?

To know what has changed in the master branch read: [CHANGELOG.md](https://github.com/pivpn/pivpn/blob/master/CHANGELOG.md)
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.

```
# pivpn help
::: To pass off to the pivpn command for each protocol
:::
::: Usage: pivpn wg <command> [option]
::: Usage: pivpn ovpn <command> [option]
:::
::: -h, help Show this help dialog
::: -u, uninstall Uninstall pivpn from your system!
::: -bk, backup Backup VPN configs and user profiles
```

## My ISP doesn't give me a static external IP address and my server IP address keeps changing!

Expand Down
111 changes: 21 additions & 90 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,9 @@ Authors: 4s3ti

# Welcome to PiVPN Docs

![Logos](img/pivpnbanner.png)

## About

PiVPN is a set of shell scripts initially developed by **@0-kaladin** that serve to easily turn your Raspberry Pi (TM)
into a VPN server using two free, open-source protocols:
* [WireGuard](https://www.wireguard.com/)
* [OpenVPN](https://openvpn.net)

Have you been looking for a good guide or tutorial for setting up a VPN server on a Raspberry Pi or Ubuntu based server?
Run this script and you don't need a guide or tutorial, this will do it all for you, in a fraction of the time and with hardened security settings in place by default.

The master branch of this script installs and configures either WireGuard or OpenVPN (or both) on Raspbian, Debian or Ubuntu and it as been tested to run not only on Raspberry Pi but also in any Cloud Provider VPS.
We recommend using the latest Raspbian Lite image on a Raspberry Pi in your home so you can VPN into your home from a unsecure remote locations and safely use the internet.
However, the scripts do try to detect different distributions and make adjustments accordingly.
They should work on the majority of Ubuntu and Debian based distributions including those using UFW by default instead of raw iptables.

This script's primary mission in life is to allow a user to have a home VPN for as cost effective as possible and without being a technical wizard.
Hence the design of PiVPN to work on a Raspberry Pi ($35) and then one command installer.
Followed by easy management of the VPN thereafter with the 'pivpn' command.
That being said...

> This will also work on a free-tier Amazon AWS server using Ubuntu or Debian. I don't want to support every scenario there but getting it to run and install successfully on a free server in the cloud was also important.
Many people have untrustworthy ISP's so running on a server elsewhere means you can connect to the VPN from home and your ISP will just see encrypted traffic as your traffic will now be leaving out the Amazon infrastructure.

## Prerequisites

To follow this guide and use the script to setup a VPN, you will need to have
a Raspberry Pi Model B or later with, an SD or microSD card with Raspbian installed,
a power adapter appropriate to the power needs of your model, and an ethernet cable or wifi
adapter to connect your Pi to your router or gateway.
It is recommended that you use a fresh image of the latest Raspbian Lite from
the [Raspberry Pi's downloads page](https://raspberrypi.org/downloads), but if you don't, be sure to make a backup
image of your existing installation before proceeding.
You should also setup your Pi with a static IP address
but it is not required as the script can do this for you.
You will need to have your router forwarding UDP port 1194 or whatever custom
port you may have chose in the installer
(varies by model & manufacturer; consult your router manufacturer's documentation to do this).
Enabling SSH on your Pi is also highly recommended, so that you can run a very
compact headless server without a monitor or keyboard and be able to access it
even more conveniently.

## How it works
[![Logos](img/pivpnbanner.png)](https://pivpn.io)

## How does PiVPN work?

The script will first update your APT repositories, upgrade packages, and install WireGuard (default) or OpenVPN, which will take some time.

Expand All @@ -72,64 +31,36 @@ The script will also make some changes to your system to allow it to forward int

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).

---
## Feedback & Support

PiVPN is purely community driven, and we are interested in making this script work for as many people as possible, we welcome any feedback on your experience.
Please be respectful and be aware that this is maintained with our free time!

### General Guidelines

* Please check our documentation
* Please carefully read the [contributors' guide](https://github.com/pivpn/pivpn/blob/master/CONTRIBUTING.md)
* Please read the pinned posts on [Github Discussions](https://github.com/pivpn/pivpn/discussions)
* Please use Github [Github Discussions](https://github.com/pivpn/pivpn/discussions) instead of Issues
* Please provide as much information as you can
* Fill the adequate template and provide all the requested data
* If you can't find the adequate template, please ask first in any of our official channels
* The Github issues page is not intended for general support usage or feature requests
* PiVPN team may close any Discussion/Issue without any warning if they don't follow the Guidelines

### Official PiVPN Community support
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.

If you have any questions or need any support, feel free to reach out at any of the following platforms
You can also reach out at:

* [Github Discussions](https://github.com/pivpn/pivpn/discussions)
* Reddit at [r/pivpn](https://www.reddit.com/r/pivpn/)
* \#pivpn at [libera.chat](https://libera.chat) IRC network
* \#pivpn:matrix.org at [matrix.org](https://matrix.org)
* Reddit at [r/pivpn](https://www.reddit.com/r/pivpn/)


### Feature requests

Feature requests are very welcome, please do so at:

* [Feature requests](https://github.com/pivpn/pivpn/discussions/categories/feature-requests)

### Bug reports

* [Open Github Issue](https://github.com/pivpn/pivpn/issues)

!!! Note
Because it didn't work doesn't mean its a bug!
please make sure you have read all the documentation and you have reached out through the official channels! before claiming a bug!

---
## contributions

PiVPN is not taking donations at this time but if you want to show your appreciation, then contribute or leave feedback on suggestions or improvements.
PiVPN is not taking donations but if you want to show your appreciation, then contribute or leave feedback on suggestions or improvements.

Contributions can come in all kinds of different ways and you don't need to be a developer to be able to help out, here are some ways you can help out:
Contributions can come in all kinds of different ways! You don't need to be a developer to help out.

* Please check the current [issues](https://github.com/pivpn/pivpn/issues) and [discussions](https://github.com/pivpn/pivpn/discussions)
to see where you can help.
* Help improving [documentation](https://github.com/pivpn/docs), either with new content or improving the existing writing.
* Testing!! Run pivpn in different ways, different systems, different configurations and let us know if you find something!
* 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
* [Documentation](https://github.com/pivpn/docs)! Documentation is never good enough! There is always something missing, or typos, or better English!
* Our [website](https://pivpn.io) is also Open Source. feel free to suggest any changes or improvements [here](https://github.com/pivpn/pivpn.io)
* Testing!! Run pivpn in different ways, different systems, different configurations! Let us know if you find something!
* Assisting other users in any of our official channels is also very welcomed

Still, if you consider PiVPN useful and want to Donate instead, then consider donating to:

Still if you have found this tool to be useful and want to Donate instead, then consider the following sources.

1. [OpenVPNSetup](https://github.com/StarshipEngineer/OpenVPN-Setup)
2. [pi-hole.net](https://github.com/pi-hole/pi-hole)
3. [OpenVPN](https://openvpn.net)
4. [WireGuard](https://www.wireguard.com/)
5. [EFF](https://www.eff.org/)
1. [PiVPN Contributors](https://github.com/pivpn/pivpn/graphs/contributors)
2. [OpenVPNSetup](https://github.com/StarshipEngineer/OpenVPN-Setup)
3. [pi-hole.net](https://github.com/pi-hole/pi-hole)
4. [OpenVPN](https://openvpn.net)
5. [WireGuard](https://www.wireguard.com/)
6. [EFF](https://www.eff.org/)
43 changes: 42 additions & 1 deletion docs/install.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ title: Installation
summary: How to install
Authors: 4s3ti


# Installation

## Method 1
Expand Down Expand Up @@ -70,7 +71,47 @@ pivpnGitUrl="https://github.com/userthatforked/pivpn.git"
pivpnGitBranch="myfeaturebranch"
```

### Updating pivpn
## Alpine

### Requirements

* Bash
* `apk add bash`
* busybox-initscripts
* `apk add busybox-initscripts`
* run as root or have sudo installed
* `apk add sudo; echo '%wheel ALL=(ALL) ALL' > /etc/sudoers.d/wheel`

#### AWS Cloud Images (AMI)

On AWS sudo is is not available by default in the the Alpine AMI'and you should use `doas` to install the required dependencies.

```
doas su
apk add bash
apk add busybox-initscripts
apk add sudo
echo '%wheel ALL=(ALL) ALL' > wheel
mv wheel /etc/sudoers.d/
chown root:root /etc/sudoers.d/wheel
```

## Docker (experimental)

It is currently possible to use PiVPN on Alpine Containers

* The container should meet the [Alpine requirements](#alpine)
* The container should run with `--cap_add NET_ADMIN`
* The container needs to have access to `/sys/fs/cgroup` (`-v /sys/fs/cgroup` or `VOLUME [ "/sys/fs/cgroup" ]` in the Dockerfile)

!!! note
This is experimental and we are not providing offical support or images.

Sharing PiVPN/Wireguard/OpenVPN Images is not advised

Feel free to open a [Discussion](https://github.com/pivpn/pivpn/discussions)

## Updating pivpn

VPN protocols are updated via system package manager

Expand Down
8 changes: 1 addition & 7 deletions docs/projects.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,14 @@ The links below showcase some good write-ups and tutorials that use PiVPN.
Some other decent information may also be contained regarding VPNs and security in general.
If you find you have more questions on this area then read and/or watch some of them below!

* [Setup OpenVPN and cli email client](https://peppe7o.com/raspberry-pi-vpn-server-with-pivpn/)
* [Maintainer post about where to properly place a VPN](https://blog.4s3ti.net/vpn-where-to.html)
* [Create your own VPN server with the Raspberry Pi](http://kamilslab.com/2016/0/21/how-to-turn-your-raspberry-pi-into-a-home-vpn-server-using-pivpn/)
* [PiVPN - Create your own VPN for your home network](http://chasingtech.net/wp/2016/0/2/pivpn-create-your-own-vpn-for-your-home-network/)
* [Maintainer post about where to properly place a VPN](https://4s3ti.net/en/posts/vpnusage/)

## Video Guides</b>

* [Raspberry Pi - OpenVPN Setup via PiVPN](https://www.youtube.com/watch?v=pUBMcsvJfe4).
> Note: I don't think you'd have to do anything with iptables as he shows.
This shows connecting with Windows client.

* [How to Setup PiVPN on the Raspberry Pi Tutorial](https://www.youtube.com/watch?v=8RSHSt3RuLk)
* [Raspberry Pi - OpenVPN Setup via PiVPN](https://www.youtube.com/watch?v=pUBMcsvJfe3)


## Related Projects

Expand Down

0 comments on commit 93d84ba

Please sign in to comment.