From 578258298830020d3a3a238f534c8100244d3650 Mon Sep 17 00:00:00 2001 From: Francisco Vilmar Cardoso Ruviaro Date: Sun, 28 Jun 2020 01:16:26 +0000 Subject: [PATCH] Add manpage --- protonvpn.1 | 641 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 641 insertions(+) create mode 100644 protonvpn.1 diff --git a/protonvpn.1 b/protonvpn.1 new file mode 100644 index 0000000..1f37675 --- /dev/null +++ b/protonvpn.1 @@ -0,0 +1,641 @@ +.\" Text automatically generated by txt2man +.TH protonvpn-cli 1 "22 June 2020" "protonvpn-cli-2.2.4" "command-line client for ProtonVPN" +.SH NAME +\fBProtonVPN-CLI \fP- command-line client for ProtonVPN +\fB +.SH SYNOPSIS +.nf +.fam C +\fBprotonvpn\fP [\fICOMMANDS\fP] [\fIARGUMENTS\fP] [\fIOPTIONS\fP] + +.fam T +.fi +.fam T +.fi +.SH DESCRIPTION +ProtonVPN-CLI is a user-friendly command-line tool for accessing the Swiss based privacy-focused ProtonVPN VPN service. +.PP +Need a ProtonVPN account to use it: can create one at https://protonvpn.com. Free accounts are available, although with +limited features: only 3 countries (Japan, Netherlands, USA) are available with the free plan. +It can also easily add an extra layer of privacy by activating Tor (needs paid plan). +.SH COMMANDS +.TP +.B +init +Initialize a ProtonVPN profile. +.TP +.B +c, connect +Connect to a ProtonVPN server. +.TP +.B +r, reconnect +Reconnect to the last server. +.TP +.B +d, disconnect +Disconnect the current session. +.TP +.B +s, status +Show connection status. +.TP +.B +configure +Change ProtonVPN-CLI configuration. +.TP +.B +refresh +Refresh OpenVPN configuration and server data. +.TP +.B +examples +Print some example commands. +.SH ARGUMENTS +.TP +.B + +Servername (CH#4, CH-US-1, HK5-Tor, JP-FREE#1, NL-FREE#2, US-FREE#3). +.SH OPTIONS +.TP +.B +\fB-f\fP, \fB--fastest\fP +Select the fastest ProtonVPN server. +.TP +.B +\fB-r\fP, \fB--random\fP +Select a random ProtonVPN server. +.TP +.B +\fB--cc\fP CODE +Determine the country for fastest connect. +.TP +.B +\fB--sc\fP +Connect to the fastest Secure-Core server. +.TP +.B +\fB--p2p\fP +Connect to the fastest torrent server. +.TP +.B +\fB--tor\fP +Connect to the fastest Tor server. +.TP +.B +\fB-p\fP PROTOCOL +Determine the protocol (UDP or TCP). +.TP +.B +\fB-h\fP, \fB--help\fP +Show this help message. +.TP +.B +\fB-v\fP, \fB--version\fP +Display version. +.SH CONFIGURATION FILES +Configuration files are in user's home directory '~/.pvpn-cli'. +The '~/.pvpn-cli' directory has the following files: +.TP +.B +- openvpn config +~/.pvpn-cli/connect.ovpn +.TP +.B +- openvpn log +~/.pvpn-cli/ovpn.log +.TP +.B +- \fBprotonvpn\fP config +~/.pvpn-cli/pvpn-cli.cfg +.TP +.B +- \fBprotonvpn\fP log +~/.pvpn-cli/pvpn-cli.log +.TP +.B +- \fBprotonvpn\fP credential +~/.pvpn-cli/pvpnpass +.TP +.B +- resolv.conf backup +~/.pvpn-cli/resolv.conf.backup +.TP +.B +- \fBprotonvpn\fP server info +~/.pvpn-cli/serverinfo.json +.TP +.B +- \fBprotonvpn\fP split tunneling +~/.pvpn-cli/split_tunnel.txt +.SH USAGE +\fBprotonvpn\fP init +.PP +\fBprotonvpn\fP (c | connect) [] [\fB-p\fP ] +.PP +\fBprotonvpn\fP (c | connect) [\fB-f\fP | \fB--fastest\fP] [\fB-p\fP ] +.PP +\fBprotonvpn\fP (c | connect) [\fB--cc\fP ] [\fB-p\fP ] +.PP +\fBprotonvpn\fP (c | connect) [\fB--sc\fP] [\fB-p\fP ] +.PP +\fBprotonvpn\fP (c | connect) [\fB--p2p\fP] [\fB-p\fP ] +.PP +\fBprotonvpn\fP (c | connect) [\fB--tor\fP] [\fB-p\fP ] +.PP +\fBprotonvpn\fP (c | connect) [\fB-r\fP | \fB--random\fP] [\fB-p\fP ] +.PP +\fBprotonvpn\fP (r | reconnect) +.PP +\fBprotonvpn\fP (d | disconnect) +.PP +\fBprotonvpn\fP (s | status) +.PP +\fBprotonvpn\fP configure +.PP +\fBprotonvpn\fP refresh +.PP +\fBprotonvpn\fP examples +.PP +\fBprotonvpn\fP (\fB-h\fP | \fB--help\fP) +.PP +\fBprotonvpn\fP (\fB-v\fP | \fB--version\fP) +.SH EXTENSIVE USAGE +Initialize the ProtonVPN profile, before using ProtonVPN-CLI you need to initialize your profile. To do this, type: +.PP +.nf +.fam C + # protonvpn init + +.fam T +.fi +The client will ask you for your OpenVPN username and password. +.PP +You can find them at https://account.protonvpn.com/account, Account > OpenVPN / IKEv2 username. +.PP +Use the following credentials when connecting to ProtonVPN servers without application: +.PP +.nf +.fam C + OpenVPN / IKEv2 username AaBbCcDdEeFfGg1234567890 + OpenVPN / IKEv2 password 0987654321gGfFeEdDcCbBaA + +.fam T +.fi +Follow the prompts and enter your OpenVPN credentials: +.PP +.nf +.fam C + --- Please make sure to use the OpenVPN credentials --- + + Enter your ProtonVPN OpenVPN username: AaBbCcDdEeFfGg1234567890 + Enter your ProtonVPN OpenVPN password: 0987654321gGfFeEdDcCbBaA + Confirm your ProtonVPN OpenVPN password: 0987654321gGfFeEdDcCbBaA + +.fam T +.fi +Next, you need to select your plan. If you are currently enjoying the 7-day free trial of ProtonVPN Plus, select 3) Plus. +.PP +.nf +.fam C + Please choose your ProtonVPN Plan + 1) Free + 2) Basic + 3) Plus + 4) Visionary + + Your plan: 1 + +.fam T +.fi +IMPORTANT: After your trial expires, you will need to reconfigure your plan to 1) Free. +To set this up, enter \fBprotonvpn\fP configure. Then select 2) ProtonVPN Plan. Finally, select 1) Free. +.PP +Now, you need to choose which default transmission protocol you want to use. +UDP is typically the faster option, while TCP is a more reliable protocol +that's better suited for unstable connections and in restricted networks. +The default selection is UDP. +.PP +.nf +.fam C + Choose the default OpenVPN protocol. + OpenVPN can act on two different protocols: UDP and TCP. + UDP is preferred for speed but might be blocked in some networks. + TCP is not as fast but a lot harder to block. + Input your preferred protocol. (Default: UDP) + + 1) UDP + 2) TCP + + Your choice: 2 + +.fam T +.fi +Finally, confirm your input with y +.PP +.nf +.fam C + You entered the following information: + Username: AaBbCcDdEeFfGg1234567890 + Password: ************************ + Tier: Free + Default protocol: TCP + + Is this information correct? [Y/n]: Y + + Writing configuration to disk\.\.\. + + Done! Your account has been successfully initialized. + +.fam T +.fi +Connect to ProtonVPN +.PP +.nf +.fam C + You are now ready to connect to ProtonVPN. For example, you can let ProtonVPN-CLI find + the fastest server for you. Just type protonvpn connect -f and a connection will be established. + +.fam T +.fi +List of all Commands +.RS +.TP +.B +\fBprotonvpn\fP init +Initialize ProtonVPN profile. +.TP +.B +\fBprotonvpn\fP connect, c +Select a ProtonVPN server and connect to it. +.TP +.B +\fBprotonvpn\fP c [servername] +Connect to a specified server. +.TP +.B +\fBprotonvpn\fP c \fB-r\fP +Connect to a random server. +.TP +.B +\fBprotonvpn\fP c \fB-f\fP +Connect to the fastest server. +.TP +.B +\fBprotonvpn\fP c \fB--p2p\fP +Connect to the fastest P2P server. +.TP +.B +\fBprotonvpn\fP c \fB--cc\fP [countrycode] +Connect to the fastest server in a specified country. +.TP +.B +\fBprotonvpn\fP c \fB--sc\fP +Connect to the fastest Secure Core server. +.TP +.B +\fBprotonvpn\fP reconnect, r +Reconnect or connect to the last server used. +.TP +.B +\fBprotonvpn\fP disconnect, d +Disconnect the current session. +.TP +.B +\fBprotonvpn\fP status, s +Print connection status. +.TP +.B +\fBprotonvpn\fP configure +Change CLI configuration. +.TP +.B +\fBprotonvpn\fP refresh +Refresh OpenVPN configuration and server data. +.TP +.B +\fBprotonvpn\fP examples +Print example commands. +.TP +.B +\fBprotonvpn\fP \fB--version\fP +Display version. +.TP +.B +\fBprotonvpn\fP \fB--help\fP +Show help message. +.RE +.PP +All connect options can be used with the \fB-p\fP flag to explicitly specify which transmission protocol is used for that connection (either udp or tcp). +.PP +Command Explanations +You can see the full list of commands by running \fBprotonvpn\fP \fB--help\fP and a list of examples by running \fBprotonvpn\fP examples. +.RS +.PP +Most of the commands need to be run as root, so use su - with the commands in this guide! +.PP +Before using any other commands, you need to initialize your profile: +.PP +.nf +.fam C + # protonvpn init + +.fam T +.fi +To connect to a server, you always need the connect option (or just c): +.PP +.nf +.fam C + # protonvpn connect + +.fam T +.fi +Running the above command will give you a menu that lets you select the country, server, and transmission protocol interactively. +If you specify a server name after connect, you can connect directly to the server of your choice: +.PP +.nf +.fam C + # protonvpn connect JP-FREE#1 + # protonvpn connect JP-FREE#2 + # protonvpn connect JP-FREE#3 + + # protonvpn connect NL-FREE#1 + # protonvpn connect NL-FREE#2 + # protonvpn connect NL-FREE#3 + + # protonvpn connect US-FREE#1 + # protonvpn connect US-FREE#2 + # protonvpn connect US-FREE#3 + +.fam T +.fi +The server name can be written in several ways. For example, usny6, us-ny-6 or usny-06 are all valid formats. +.PP +To connect to the fastest server, you can use the \fB--fastest\fP or \fB-f\fP flag: +.PP +.nf +.fam C + # protonvpn c --fastest + + # protonvpn c -f + +.fam T +.fi +You can use the \fB--random\fP or \fB-r\fP flag to connect to a random server: +.PP +.nf +.fam C + # protonvpn c -r + +.fam T +.fi +There are several other variables to keep in mind when you want to connect to the “fastest” server. +You can connect to the fastest server in a country, the fastest Secure Core server, the fastest P2P-enabled server, or the fastest Tor server. +.PP +Fastest server in a country (replace UK with the code of the desired country, e.g. US for USA, JP for Japan, AU for Australia, etc.): +.PP +.nf +.fam C + # protonvpn c --cc UK + +.fam T +.fi +Fastest Secure Core server: +.PP +.nf +.fam C + # protonvpn c --sc + +.fam T +.fi +Fastest P2P/torrent server: +.PP +.nf +.fam C + # protonvpn c --p2p + +.fam T +.fi +Fastest Tor server: +.PP +.nf +.fam C + # protonvpn c --tor + +.fam T +.fi +All connection methods (except the interactive menu) can be used with the \fB-p\fP flag to choose a transmission protocol. +Possible values are either TCP or UDP. If that flag is not used, your connection will use the default transmission protocol you specified during the initialization: +.PP +Connect to the fastest server with TCP: +.PP +.nf +.fam C + # protonvpn c -f -p TCP + +.fam T +.fi +Connect to a random server with UDP: +.PP +.nf +.fam C + # protonvpn c -rp UDP + +.fam T +.fi +To disconnect the VPN, you need to use the disconnect or d option: +.PP +.nf +.fam C + # protonvpn disconnect + + # protonvpn d + +.fam T +.fi +If you're having trouble with your connection, e.g., because you switched networks or your device woke up from sleeping, +you can easily reconnect to the last server with the reconnect or r option: +.PP +.nf +.fam C + # protonvpn reconnect + + # protonvpn r + +.fam T +.fi +If you want to see the status and information of your current connection, you can use the status or s option: +.PP +.nf +.fam C + # protonvpn status + + # protonvpn s + +.nf +.fam C + Status: Connected + Time: 0:35:22 + IP: 89.39.107.198 + Server: NL-FREE#1 + Features: Normal + Protocol: TCP + Kill Switch: Disabled + Country: Netherlands + City: None + Load: 70% + Received: 190.85 KB + Sent: 11.72 KB + +.fam T +.fi +If you want to change the settings you selected during initialization, you can do this with the configure option, +just follow the prompts to change your username/password, default protocol and so on: +.PP +.nf +.fam C + # protonvpn configure + +.nf +.fam C + What do you want to change? + + 1) Username and Password + 2) ProtonVPN Plan + 3) Default Protocol + 4) DNS Management + 5) Kill Switch + 6) Split Tunneling + 7) Purge Configuration + + Please enter your choice or leave empty to quit: + +.fam T +.fi +.SH FEATURES + +DNS Management +.PP +DNS Leak Protection +.PP +.nf +.fam C + ProtonVPN-CLI features a DNS Leak Protection feature, which makes sure that your online traffic uses ProtonVPN's DNS Servers. + This prevents third parties (like your ISP) from being able to see your DNS queries (and, therefore, your browsing history). + + ProtonVPN-CLI accomplishes this by updating the /etc/resolv.conf file when you connect to a VPN server, + and makes sure that only ProtonVPN's DNS Server is written in this file. + It will also backup the previous state of /etc/resolv.conf to revert all changes upon disconnection. + + Please note that if you change your network (e.g., if you connect to a different WiFi hotspot) without first disconnecting, + /etc/resolv.conf will likely be updated, which would remove ProtonVPN's DNS Servers. + This could cause DNS leaks, so to keep your data safe, use protonvpn reconnect after changing your network. + +.fam T +.fi +Enabling DNS Leak Protection +.PP +.nf +.fam C + To enable DNS Leak Protection, use the protonvpn configure command, then press 4 to choose DNS Management. + Then press 1 to choose that you want to enable DNS Leak Protection. + + After you activate this feature, your DNS queries will be secure. + +.fam T +.fi +Custom DNS +.PP +.nf +.fam C + You can also make a custom DNS server your default for all your ProtonVPN connections. ProtonVPN-CLI lets you add up to 3 custom DNS Servers. + +.fam T +.fi +Enabling Custom DNS +.PP +.nf +.fam C + To configure custom DNS Servers, use the protonvpn configure command, then press 4 to choose DNS Management. + Then press 2 to choose that you want to configure a custom DNS Server. + Now enter the IP addresses of up to 3 DNS Servers you want to use and confirm with Enter. + +.fam T +.fi +Disabling DNS Management +.PP +.nf +.fam C + If you don't want ProtonVPN-CLI to do any changes to your DNS, you can do this as well. + This will cause ProtonVPN-CLI to not touch /etc/resolv.conf and your device will always use the DNS servers configured by you or through your network. + +.fam T +.fi +Disabling any DNS management +.PP +.nf +.fam C + To enable DNS Leak Protection use the protonvpn configure command, then press 4 to choose DNS Management. Then press 3 to disable any DNS management. + +.fam T +.fi +IPv6 Leak Protection +.PP +.nf +.fam C + ProtonVPN-CLI features an IPv6 Leak Protection feature. It makes sure that your IPv6 address is not leaked when you connect to a ProtonVPN server. + + This feature is enabled by default, and for security reasons, it can't be disabled. + + It works by detecting the IPv6 address, backing it up, and removing it from the default interface. + When disconnecting, it adds the IPv6 address back to the default interface and deletes the backup. + +.fam T +.fi +Enabling Kill Switch +.PP +.nf +.fam C + To enable Kill Switch, open the configuration menu with protonvpn configure, then select 5 for Kill Switch and + confirm the activation with either 1 or 2, depending on your preference. + + 1 will block access from your directly connected network (e.g. public WiFi) and is recommended for laptops that may connect to untrusted networks. + + 2 will allow access from your directly connected network and is for computers that don't leave a secure and trusted LAN, like your home network. + + On the next connection Kill Switch will be enabled. + + Note: Kill Switch only activates on unexpected connection drops. It will not persist through reboots and not activate when calling protonvpn disconnect. + To simulate the Kill Switch, kill the OpenVPN process while connected with pkill openvpn. + +.fam T +.fi +Split Tunneling +.PP +.nf +.fam C + ProtonVPN-CLI features IP-based split tunneling. This means that you can exclude specific IP addresses or IP ranges from being routed through the VPN tunnel. + + Note: Split Tunneling does not work when the Kill Switch is enabled. + +.fam T +.fi +Enable Split Tunneling +.PP +.nf +.fam C + To enable Split Tunneling, open the configuration menu with protonvpn configure, then select Split Tunneling with 6. Then confirm with y. + + Now add the IPs you want to exclude (one IP at a time) or IP ranges in CIDR notation. + + If you want to have a big list of IPs or ranges that you want to exclude, it is recommended to add one IP via the method mentioned above. + This will create the file ~/.pvpn-cli/split_tunnel.txt. You can then paste the IPs or networks in CIDR notation in this file, one IP/network per line. + + Then call protonvpn refresh to update the OpenVPN template with your excluded IP addresses. + +.fam T +.fi +.SH AUTHOR +ProtonVPN-CLI was written by Proton Technologies AG and contributors. +.PP +This manual page was written by Francisco Vilmar Cardoso Ruviaro for the Debian project (but may be used by others).