Download & Install FreePN on Gentoo

🚀 Quickstart

• System Requirements
• How to Install
• How to Use
• How to Upgrade
• How to Uninstall
• Troubleshooting

🔗 Gentoo System Requirements

FreePN supports the latest version (rolling release) of Gentoo Linux (& derivatives based on Portage).

Please ensure that your build is fully up to date before proceeding, otherwise you may encounter issues installing the necessary packages.

For optimal performance, please ensure that your system has at least 2GB of RAM (i.e. a Raspberry Pi Model 4, 2GB RAM or better would be sufficient). Depending on your configuration, FreePN may run on systems with lower specs, but performance may be unstable.

Note: the below walkthrough assumes you are using Systemd as your service manager on Gentoo.

---

🔗 How to Install FreePN on Gentoo

Installation of FreePN requires running a few commands in Terminal. Please open your Terminal and execute the following commands:

First, we need to install the Portage overlay. To do this, we need to create a file for the overlay in the /etc/portage/repos.conf directory named python-overlay.conf. Create & open the file with nano by running:

sudo nano /etc/portage/repos.conf/python-overlay.conf

Once you've opened the file with nano, paste the following text into it:

[python-overlay]

# Various python ebuilds for FreePN
# Maintainer: nerdboy <nerdboy@gentoo.org>

location = /var/db/repos/python-overlay
sync-type = git
sync-uri = https://github.com/freepn/python-overlay.git
priority = 50
auto-sync = yes

If your system is configured to save overlay files in a different directory, you can accommodate this by changing the location field to the appropriate directory. Most users can ignore this and simply paste the above text as is.

Next, save and exit nano by pressing Ctrl+X, Y, and then Enter.

Now, sync the repo by running the following:

sudo emaint sync --repo python-overlay

Install the FreePN package WITH the desktop UI & dependencies:

sudo emerge freepn-gtk3-tray

OR Optional: Install FreePN & dependencies WITHOUT the desktop UI:

sudo emerge net-misc/fpnd

Finally, add your local <username> to the fpnd group by running (replace <username> with your login id):

sudo usermod -aG fpnd <username>

If you don't know your login id, you can easily find it by running:

whoami

Your login id will be the output of this command.

After executing the above commands (assuming you've installed the desktop UI), you should see a new application installed on your Desktop named FreePN Tray.

Otherwise, if you skipped the desktop UI installation step, you can still access the FreePN network and control your connection via your Terminal.

---

🔗 How to Use FreePN on Gentoo

If you installed FreePN WITH the desktop UI

Open the FreePN tray application. You will notice a chevron (the FreePN logo) with an X icon (meaning the VPN is currnetly stopped) in the middle appear in the top right of your home screen's menu bar. Your menu bar should look like this:

Click the chevron (the FreePN logo). You should see the following dropdown menu open:

Start

Click Start to connect to the FreePN network.

Please allow up to two minutes for FreePN to fully establish a peer connection.

Once fully connected, the X icon in the chevron (FreePN logo) should change to show a key shape (the Status text should read Connected as well).

Status

You can see the status of your connection to the FreePN network by reading the text next to the chevron (FreePN logo) in your menu bar. Common statuses include:

• Starting: your FreePN client is initializing / establishing network interfaces.
• Waiting: your FreePN client is establishing a connecting with the coordinating server and trying to find a peer to connect to.
• Config: your FreePN client is being paired with a peer.
• Connected: your connection to the FreePN network has been established. You're good to go.

You can also check the status of your connection to the FreePN network by clicking the Status button.

Stop

To diconnect from the FreePN network, simply click Stop.

If you installed FreePN WITHOUT the desktop UI

Start

To connect to the FreePN network via Terminal, open your Terminal and execute the command:

systemctl start fpnd.service

Please allow up to two minutes for FreePN to fully establish a peer connection.

Status

To check the status of your connection to the FreePN network, execute the following in your Terminal:

tail -f /run/fpnd/fpnd.state

You should see an output similar to the following:

To bring the command prompt back up from this view, press Ctrl+C.

To recap the above, common statuses include:

• Starting: your FreePN client is initializing / establishing network interfaces.
• Waiting: your FreePN client is establishing a connecting with the coordinating server and trying to find a peer to connect to.
• Config: your FreePN client is being paired with a peer.
• Connected: your connection to the FreePN network has been established. You're good to go.

Stop

To disconnect from the FreePN network, execute the command:

systemctl stop fpnd.service

---

🔗 Upgrade FreePN

To upgrade FreePN, simply execute the following command:

sudo emaint sync --repo python-overlay

then, if you installed FreePN WITH the desktop UI & dependencies:

sudo emerge freepn-gtk3-tray

OR: if you installed FreePN WITHOUT the desktop UI:

sudo emerge net-misc/fpnd

---

🔗 Uninstall FreePN

To uninstall FreePN (assuming you installed FreePN WITH the desktop UI), simply execute the following command:

sudo emerge freepn-gtk3-tray -C

OR if you installed FreePN WITHOUT the optional desktop UI, this command:

sudo emerge net-misc/fpnd -C

---

🔗 Troubleshooting

Common Problems

The desktop UI / state message says UPGRADE and FreePN is not connecting.

Starting with fpnd-0.9.7 and freepn-gtk3-tray-0.0.8, if your version of FreePN is too old or incompatible, you will see an 'UPGRADE' message in the desktop UI and state file. If you're seeing this message, you will not be able to connect to the FreePN network until you upgrade. To upgrade your installation of FreePN execute the following:

sudo emaint sync --repo python-overlay

then, if you installed FreePN WITH the desktop UI & dependencies:

sudo emerge freepn-gtk3-tray

OR: if you installed FreePN WITHOUT the desktop UI:

sudo emerge net-misc/fpnd

Once you've upgraded your installation of FreePN, restart your computer, then try connecting again. If all else fails, try uninstalling FreePN, then install again.

FreePN is slow to connect

Please note that while establishing a connection to the FreePN network is usually relatively quick (30 seconds on average), depending on network conditions, it may take up to two minutes to connect.

FreePN is not working / not connecting

If you have recently installed FreePN and are experiencing issues, we recommend restarting your machine to ensure all packages and updates properly finish installation.

Clicking Stop, waiting a few moments, then clicking Start again (and waiting for a new peer connection) in the desktop UI's dropdown menu should also help resolve up a number of network configuration issues & issues with FreePN not connecting (such as a common issue where FreePN will remain in the Config state indefinitely, never establishing a connection).

On occasion, you may need to Stop and Start the program two or three times. Please watch the FreePN Status to determine the state of your connection, and allow up to two minutes for a connection to be established each time you Stop and Start the program.

Additional Issues

If after troubleshooting you are still experiencing problems with FreePN, please consider filing an issue on GitHub here, or sending an email to admin@freepn.com.