Skip to content

Commit

Permalink
Update README (update installation method for macOS, Asuswrt-merlin, …
Browse files Browse the repository at this point in the history 
…Entware, OpenWrt)
  • Loading branch information
@1951FDG
1951FDG committed Mar 28, 2021
1 parent e3a82e2 commit 2c51175
Show file tree
Hide file tree
Showing 2 changed files with 139 additions and 115 deletions.
250 changes: 137 additions & 113 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,30 +3,30 @@
<p align="center">
<a href="https://pypi.python.org/pypi/openpyn"><img alt="Downloads" src="https://img.shields.io/pypi/v/openpyn.svg"></a>
<a href="https://pepy.tech/project/openpyn"><img alt="Downloads" src="https://pepy.tech/badge/openpyn"></a> </p>
A python3 script (systemd service as well) to manage openvpn connections. Created to easily connect to and switch between, OpenVPN servers hosted by NordVPN. Quickly Connect to the least busy servers with lowest latency from you (using current data from Nordvpn's API). Find servers in a specific country or even a city. It Tunnels DNS traffic through the VPN which normally (when using OpenVPN) goes through your ISP's DNS (unencrypted) and compromises Privacy!
A python3 script (systemd service as well) to manage OpenVPN connections. Created to easily connect to and switch between, OpenVPN servers hosted by NordVPN. Quickly Connect to the least busy servers with lowest latency from you (using current data from NordVPN’s API). Find servers in a specific country or even a city. It Tunnels DNS traffic through the VPN which normally (when using OpenVPN) goes through your ISP’s DNS (unencrypted) and compromises Privacy!

## Features

- Automatically connect to least busy, low latency servers in a given country.
- Systemd integration, easy to check VPN status, autostart at startup.
- Find and connect to servers in a specific city or state.
- Uses NordVPN's DNS servers and tunnels DNS queries through the VPN Tunnel.
- Uses NordVPN’s DNS servers and tunnels DNS queries through the VPN Tunnel.
- Use Iptables rules to prevent IP leakage if tunnel breaks (Experimental), ie KILL SWITCH.
- Quickly Connect to any specific server. i.e au10 or us20.
- Downloads and Updates (modifications) the latest config files from NordVPN.
- Option to run the script in background (as a systemd service).
- Options to finetune server selection based on "Server Load" or "Ping Latency".
- Auto excludes the servers if a ping to them fails or some packets drops when pinging \\
or if they don't support OpenVPN \\ (TCP or UDP depending upon which one you are trying to use).
- Finds and displays nord vpn servers (with extra info) in a given country.
- Now list and connect to servers with "Netflix" --netflix, "Peer To Peer" --p2p, "Dedicated IP" --dedicated, \\
- Auto excludes the servers if a ping to them fails or some packets drops when pinging
or if they don’t support OpenVPN (TCP or UDP depending upon which one you are trying to use).
- Finds and displays NordVPN servers (with extra info) in a given country.
- Now list and connect to servers with "Netflix" --netflix, "Peer To Peer" --p2p, "Dedicated IP" --dedicated,
"Tor Over VPN" --tor, "Double VPN" --double, "Anti DDos" --anti-ddos support.
- Desktop notification are shown when VPN connects and disconnects. (needs to run without sudo)
- Auto retry if \[soft,auth-failure\] received, auto failover to next best server if connection dies.
- NVRAM write support for Asuswrt-merlin
- Pass through openvpn options, e.g. openpyn uk -o '--status /var/log/status.log --log /var/log/log.log'
- Pass through OpenVPN options, e.g. openpyn uk -o '--status /var/log/status.log --log /var/log/log.log'
- Logs are stored in '/var/log/openpyn/' for information and troubleshooting.
- Temporarily disable ipv6 to prevent leakage (when using -f).
- Temporarily disable IPv6 to prevent leakage (when using -f).

## Demo

Expand All @@ -36,94 +36,108 @@ A python3 script (systemd service as well) to manage openvpn connections. Create

1. Install dependencies if they are not already present.

```bash
# common dependencies
sudo apt install openvpn python3-setuptools python3-pip
```
```bash
# common dependencies
sudo apt install openvpn python3-setuptools python3-pip
```

2. The following python dependencies are needed and will be installed when using pip.
2. The following Python dependencies are needed and will be installed when using pip.

```bash
requests colorama coloredlogs verboselogs tqdm jsonschema
```
```bash
requests colorama coloredlogs verboselogs tqdm jsonschema
```

### Installation Methods

1. Install openpyn with pip3 (Python=>3.5)
**Recommended method to get the latest version and receive frequent updates.**
Do not install with --user switch, as OpenVPN needs to run as sudo and sudo won't be able to locate openpyn.
```bash
sudo python3 -m pip install --upgrade openpyn
```

2. Alternatively clone and install.

```bash
git clone https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn && sudo python3 -m pip install --upgrade .
```

For the latest in development features, try the 'test' branch instead

```bash
git clone --branch test https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn && sudo python3 -m pip install --upgrade -e .
```

3. For macOS with Python=>3.5 (credit: [1951FDG](https://github.com/1951FDG))

```bash
# common dependencies
xcode-select --install
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.bash_profile
brew install python3 openvpn
sudo brew services start openvpn
```

```bash
git clone https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn
git pull
sudo python3 -m pip install --upgrade .
```

4. On Asuswrt-merlin, install [Entware-ng-3x](https://gist.github.com/1951FDG/3cada1211df8a59a95a8a71db6310299#file-asuswrt-merlin-md) (credit: [1951FDG](https://github.com/1951FDG))

```bash
# common dependencies
opkg install git git-http iputils-ping procps-ng-pgrep python3 python3-pip sudo
```

```bash
cd /tmp/share/
git clone https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn/
git pull
pip3 install --upgrade setuptools
pip3 install --upgrade .
```
Do not install with --user switch, as OpenVPN needs to run as sudo and sudo won’t be able to locate openpyn.

> **Note**:
> Steps below not required if only using --nvram option
```bash
sudo python3 -m pip install --upgrade openpyn
```

```bash
# change the DNS in your router, either in LAN or WAN settings
**DNS Server1** 103.86.96.100
**DNS Server2** 103.86.99.100
```
2. Alternatively clone and install.

```bash
# steps need to be done once after every router reboot
modprobe tun
iptables -A FORWARD -i eth0 -o tun0 -s 192.168.1.0/24 -m conntrack --ctstate NEW -j ACCEPT
iptables -A FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
iptables -A POSTROUTING -t nat -o tun0 -j MASQUERADE
```
```bash
git clone https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn/
sudo python3 -m pip install --upgrade .
```

For the latest in development features, try the 'test' branch instead

```bash
git clone --branch test https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn/
sudo python3 -m pip install --upgrade .
```

3. On macOS (credit: [1951FDG](https://github.com/1951FDG))

```bash
# install Homebrew
xcode-select --install
curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh
echo 'export PATH="/usr/local/sbin:$PATH"' >> ~/.bash_profile
```

```bash
# common dependencies
brew install python3 openvpn
sudo brew services start openvpn
```

```bash
git clone --branch test https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn/
sudo python3 -m pip install --upgrade pip
sudo python3 -m pip install --upgrade .
```

4. On Asuswrt-merlin, standard installation [Entware](https://gist.github.com/1951FDG/3cada1211df8a59a95a8a71db6310299#file-asuswrt-merlin-md) (credit: [1951FDG](https://github.com/1951FDG))

Steps below **may** also work for OpenWrt

```bash
# common dependencies
opkg install git git-http iputils-ping procps-ng-pgrep python3 python3-pip sudo unzip wget
```

```bash
# allow admin user to run sudo
sed -i 's~root ALL=(ALL) ALL~admin ALL=(ALL) ALL~g' /opt/etc/sudoers
```

```bash
cd /tmp/share/
git clone --branch test https://github.com/jotyGill/openpyn-nordvpn.git
cd openpyn-nordvpn/
python3 -m pip install --upgrade pip
python3 -m pip install --upgrade .
```

Steps below **not** required if only using --nvram option

```bash
# steps need to be done once after every device reboot
modprobe tun
iptables -A FORWARD -i eth0 -o tun0 -s 192.168.1.0/24 -m conntrack --ctstate NEW -j ACCEPT
iptables -A FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
iptables -A POSTROUTING -t nat -o tun0 -j MASQUERADE
```

Steps below **may** be required if **not** using --nvram option

```bash
# change the DNS, either in LAN or WAN settings
**DNS Server1** 103.86.96.100
**DNS Server2** 103.86.99.100
```

## Setup

Initialise the script with "--init" (store credentials, install Systemd service, update/install vpn config files)
Initialise the script with "--init" (store credentials, install Systemd service, update/install VPN config files)

```bash
sudo openpyn --init
Expand All @@ -132,7 +146,7 @@ sudo openpyn --init
Note: if you get ' openpyn: command not found' when using sudo on Fedora, create a symbolic link.
`sudo ln -s /usr/local/bin/openpyn /bin/openpyn`

That's it, run the script! when done with it, press "Ctr + C" to exit.
That’s it, run the script! when done with it, press "Ctr + C" to exit.

## Basic Usage

Expand All @@ -151,18 +165,18 @@ openpyn us -a ny
openpyn us --area "new york"
```

- To enforce Firewall rules to prevent dns leakage, also from ip leakage if tunnel breaks. i.e KILL SWITCH
also temporarily disables ipv6 by running "sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1"
- To enforce firewall rules to prevent DNS leakage, also from IP leakage if tunnel breaks. i.e KILL SWITCH
also temporarily disables IPv6 by running "sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1"

```bash
openpyn us -f # Experimental!, Warning, clears IPtables rules!
openpyn us -f # Experimental!, Warning, clears iptables rules!
# (changes are non persistent, simply reboot if having networking issues)
```

- When using "-f", To allow custom ports (from internal ip ranges, i.e 192.168 or 10.) through the firewall.
- When using "-f", To allow custom ports (from internal IP ranges, i.e 192.168 or 10.) through the firewall.

```bash
openpyn us -f --allow 22 80 443 #only accessible from local network
openpyn us -f --allow 22 80 443 # only accessible from local network
```

- To allow ports from other ranges use the `--allow-config` or `--allow-config-json` options. More details can be found [here](./docs/allowed-ports-config.md)
Expand Down Expand Up @@ -191,7 +205,7 @@ openpyn -l uk
```bash
openpyn -l uk --p2p
openpyn --list uk --dedicated
openpyn -l --tor # tor over vpn in all countries
openpyn -l --tor # Tor over VPN in all countries
```

- To find the least loaded 10 NordVPN servers in US that support "peer-to-peer",
Expand All @@ -214,40 +228,40 @@ sudo openpyn us -d
systemctl status openpyn
```

- To kill a running openvpn connection.
- To kill a running OpenVPN connection.

```bash
sudo openpyn -k
```

- To Flush the iptables and kill any running openvpn connections.
- To flush the iptables and kill any running OpenVPN connections.

```bash
sudo openpyn -x #optionally --allow 22 if using as ssh server
sudo openpyn -x # optionally --allow 22 if using as SSH server
```

- To Download/Update the latest vpn config files from NordVPN by:
- To download/update the latest VPN config files from NordVPN.

```bash
openpyn --update
```

- To quickly save best NordVPN server in US to NVRAM for "OpenVPN Client 5"
(ASUSWRT-Merlin):
- To save the least busy NordVPN server in US to NVRAM for "OpenVPN Client 5".

```bash
openpyn us --nvram 5
openpyn us --nvram 5 # (ASUSWRT-Merlin)
```

## Usage Options

```bash
usage: openpyn [-h] [-v] [--init] [-d] [-k] [-x] [--update] [--skip-dns-patch]
[--silent] [--test] [-n NVRAM] [-o OPENVPN_OPTIONS]
[-loc latitude longitude] [-s SERVER] [-c COUNTRY_CODE] [--tcp]
[--silent] [--test] [-n NVRAM] [--no-redirect-gateway]
[-o OPENVPN_OPTIONS] [-s SERVER] [-c COUNTRY_CODE] [--tcp]
[-a AREA] [-m MAX_LOAD] [-t TOP_SERVERS] [--p2p] [--dedicated]
[--tor] [--double] [--anti-ddos] [--netflix]
[-l [LIST_SERVERS]] [--status] [--stats] [-f] [--allow-locally]
[-l [LIST_SERVERS]] [--status] [--stats] [-f] [-r]
[--allow-locally]
[--allow INTERNALLY_ALLOWED [INTERNALLY_ALLOWED ...]]
[--allow-config INTERNALLY_ALLOWED_CONFIG]
[--allow-config-json INTERNALLY_ALLOWED_CONFIG_JSON]
Expand Down Expand Up @@ -286,6 +300,12 @@ optional arguments:
-n NVRAM, --nvram NVRAM
Specify client to save configuration to NVRAM
(ASUSWRT-Merlin)
OpenVPN Options:
Configurable Options Being Passed Downed To OpenVPN
--no-redirect-gateway
Don’t set --redirect-gateway
-o OPENVPN_OPTIONS, --openvpn-options OPENVPN_OPTIONS
Pass through OpenVPN options, e.g. openpyn uk -o '--
status /var/log/status.log --log /var/log/log.log'
Expand Down Expand Up @@ -329,16 +349,20 @@ Display Options:
conjunction with (-a | --area, and server types
(--p2p, --tor) e.g "openpyn -l it --p2p --area milano"
--status Show last change in connection status
--stats Show openvpn connection stats
--stats Show OpenVPN connection stats
Firewall Options:
Firewall and KillSwitch Options
Firewall, KillSwitch and Route Options
-f, --force-fw-rules Enforce firewall rules to drop traffic when tunnel
breaks , force disable DNS traffic going to any other
interface
-r, --add-route Add route to default-gateway; Needed to continue
serving any service including SSH. Required on VPSs.
To ensure it doesn’t leak traffic use it with -f and
--allow
--allow-locally To be used with "-f" to allow input traffic on all
ports from locally connected / INTERNAL IP RANGEs. for
ports from locally connected / INTERNAL IP SUBNET. for
example 192.168.1.* range
--allow INTERNALLY_ALLOWED [INTERNALLY_ALLOWED ...]
To be used with "-f" to allow TCP connections to given
Expand All @@ -347,30 +371,30 @@ Firewall Options:
(i.e. 192.168.1.* range) by "openpyn us -f --allow 22
80"
--allow-config INTERNALLY_ALLOWED_CONFIG
To be used with "-f" to allow a complex set of port
rules. This option requires a path to a JSON file that
contains the relevent config
To be used with "-f" to allow a complex set of allow
port rules. This option requires a path to a JSON file
that contains the relevant config
--allow-config-json INTERNALLY_ALLOWED_CONFIG_JSON
To be used with "-f" to allow a complex a complex set
of allow port rules. This option requires works the
same as "--allow-config" option but accepts a json
object as a string instead
To be used with "-f" to allow a complex set of allow
port rules. This option works the same as "--allow-
config" option but accepts a JSON object as a string
instead
```
## Todo
- [x] find servers with P2P support, Dedicated ips, Anti DDoS, Double VPN, Onion over VPN
- [x] find servers with P2P support, Dedicated IPs, Anti DDoS, Double VPN, Onion over VPN
- [x] utilise the frequently updated api at "api.nordvpn.com/server"
- [x] clean exit, handle exceptions
- [x] store credentials from user input, if "credentials" file exists use that instead
- [x] sane command-line options following the POSIX guidelines
- [ ] ability to store profiles (sort of works as the systemd service file stores last state)
- [x] find and display server's locations (cities)
- [x] find and display server’s locations (cities)
- [x] accept full country names
- [x] colourise output
- [x] modularize
- [x] create a combined config of multiple servers (on the fly) for auto failover
- [x] uninstall.sh #sudo pip3 uninstall openpyn
- [x] uninstall.sh # sudo pip3 uninstall openpyn
- [x] view status of the connection after launching in --daemon mode
- [x] desktop notifications
- [x] initd script for Asuswrt-merlin: "/opt/etc/init.d/S23openpyn start"
Loading

0 comments on commit 2c51175

Please sign in to comment.