Pi-hole/pivpn
Pi-hole/pivpn
1
0
Fork 0
mirror of https://github.com/pivpn/pivpn.git synced 2024-12-19 19:30:16 +00:00
Code Issues Projects Releases Packages Wiki Activity

Moved several paragraphs to the wiki

Browse source
This commit is contained in:
Orazio 2020-09-14 17:00:35 +02:00 committed by GitHub
parent 03f5871c71
commit 0a65da1184
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 2 additions and 107 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
README.md
View file

@ -38,14 +38,13 @@ It is recommended that you use a fresh image of the latest Raspbian Lite from
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
(see either source 1 or 2 at the bottom of this Readme)
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 (This is also covered by source 2).
even more conveniently.
Installation
@ -94,111 +93,7 @@ Finally, if you are using RSA, the script will take some time to build the serve
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.
After the installation is complete you can use the command `pivpn` to manage the server. The commands below are just to get started, run `pivpn -h` to see the full list of options.
Managing the PiVPN (WireGuard)
----------------------
`pivpn add`
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.
`pivpn remove`
Asks you for the name of the client to remove. Once you remove a client, it will no longer allow you to use
the given client config (specifically its public key) to connect. This is useful for many reasons but some ex:
You have a profile on a mobile phone and it was lost or stolen. Remove its key and generate a new
one for your new phone. Or even if you suspect that a key may have been compromised in any way,
just remove it and generate a new one.
`pivpn list`
If you add more than a few clients, this gives you a nice list of their names and associated keys.
Managing the PiVPN (OpenVPN)
----------------------
`pivpn add`
You will be prompted to enter a name for your client. Pick anything you like and hit 'enter'.
You will be asked to enter a pass phrase for the client key; make sure it's one you'll remember.
The script will assemble the client .ovpn file and place it in the directory 'ovpns' within your
home directory.
If you need to create a client certificate that is not password protected (IE for use on a router),
then you can use the 'pivpn add nopass' option to generate that.
`pivpn revoke`
Asks you for the name of the client to revoke. Once you revoke a client, it will no longer allow you to use
the given client certificate (ovpn config) to connect. This is useful for many reasons but some ex:
You have a profile on a mobile phone and it was lost or stolen. Revoke its cert and generate a new
one for your new phone. Or even if you suspect that a cert may have been compromised in any way,
just revoke it and generate a new one.
`pivpn list`
If you add more than a few clients, this gives you a nice list of their names and whether their certificate
is still valid or has been revoked. Great way to keep track of what you did with 'pivpn add' and 'pivpn revoke'.
Importing Profiles on Client Machines
--------------------------------------------
**Windows**: 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.
**Mac/Linux**: Open the Terminal app and copy the config from the Raspberry Pi using `scp pi-user@ip-of-your-raspberry:configs/whatever.conf .` (if using WireGuard) or `scp pi-user@ip-of-your-raspberry:ovpns/whatever.ovpn .` (if using OpenVPN). The file will be downloaded in the current working directory, which usually is the home folder of your PC.
**Android/iOS** (WireGuard only): Just skip to _Connecting to the PiVPN server (WireGuard)_
**Android**: 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.
**iOS**: You can use an app that supports SFTP like Documents by Readdle to retrieve it directly from your iOS device.
Connecting to the PiVPN server (WireGuard)
--------------------------------------------
**Windows/Mac**: Download the [WireGuard GUI app](https://www.wireguard.com/install/), import the configuration and activate the tunnel.
**Linux**: 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):
```
mkdir -p /etc/wireguard
chown root:root /etc/wireguard
chmod 700 /etc/wireguard
```
Move the config and activate the tunnel:
```
mv whatever.conf /etc/wireguard/
wg-quick up whatever
```
Run `wg-quick down whatever` to deactivate the tunnel.
**Android/iOS:** 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.
Connecting to the PiVPN server (OpenVPN)
--------------------------------------------
**Windows**: 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'.
**Linux**: 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):
```
apt install openvpn
mkdir -p /etc/openvpn/client
chown root:root /etc/openvpn/client
chmod 700 /etc/openvpn/client
```
Move the config and connect (input the pass phrase if you set one):
```
mv whatever.ovpn /etc/openvpn/client/
openvpn /etc/openvpn/client/whatever.ovpn
```
Press CTRL-C to disconnect.
**Mac**: 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.
**Android**: 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'.
**iOS**: 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.
Removing PiVPN
----------------
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`.
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
--------