> For the complete documentation index, see [llms.txt](https://support.goodaccess.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.goodaccess.com/configuration-guides/linux.md).

# Linux

This guide will teach you how to install the GoodAccess Client Application to various Linux distributions.

## Installation

### Step 1 - Adding the repository

Run the following bootstrap script in your terminal to add the GoodAccess repository:

```
curl -fsSL https://packages.goodaccess.com/production/app/Linux/linux-bootstrap.sh | sudo bash
```

<details>

<summary><strong>What does this script do?</strong></summary>

The automated bootstrap script:

* **Detects** your Linux distribution.
* **Downloads and imports** our public GPG key (to verify package authenticity).
* **Adds** the GoodAccess package repository to your system's package manager.

</details>

### Step 2 - Installing the GoodAccess Client Application

Select your distribution below and install the GoodAccess Client Application using the following command.

{% tabs %}
{% tab title="Debian/Ubuntu" %}

```
sudo apt install goodaccess
```

{% endtab %}

{% tab title="Fedora/RHEL" %}

```
sudo dnf install goodaccess
```

{% endtab %}

{% tab title="Arch" %}

```
sudo pacman -S goodaccess
```

{% endtab %}
{% endtabs %}

You have now successfully installed the GoodAccess Client Application.

{% hint style="info" %}
**If you are experiencing problems:**

* check our [Linux Troubleshooting](#troubleshooting)
* or [contact our technical support](https://www.goodaccess.com/contact)
  {% endhint %}

## System Requirements

{% hint style="info" %}

* **Desktop Environment:** Modern desktop environment (e.g., **GNOME**, **KDE**, or similar).
* **Init System:** `systemd`
* **Web Browser:** Modern web browser with Deep Link support (e.g., Firefox, Chrome, etc.).
* **Dependencies:** `libc6`, `libstdc++6`, `dmidecode`, `iputils-ping`, `wireguard-tools`, `iproute2`, `nftables | iptables`, `polkitd`, `systemd-resolved`
* **Privileges:** Admin rights (sudo) within the OS (required to install and run GoodAccessService).
* **Architecture:** Only **x86\_64 (amd64)** is currently supported.
  {% endhint %}

## Troubleshooting

{% hint style="info" %}
This section covers **Linux-specific** issues. For general connection or login problems, please check our [general Troubleshooting](/faq-and-troubleshooting/troubleshooting.md).

In case you aren't able to resolve your issue with the following guidelines, please [contact our technical support](https://www.goodaccess.com/contact).
{% endhint %}

<details>

<summary>Unable to connect with any protocol</summary>

#### Symptom

The GoodAccess Client Application fails to establish a connection regardless of the selected connection protocol.

{% stepper %}
{% step %}

#### Check the GoodAccessService

Run the following command to check status of the GoodAccessService:

```
systemctl status goodaccess
```

Verify that the output shows both:

* `Loaded: ... enabled` (configured to start automatically at boot)
* `Active: active (running)`

<img src="https://418253935-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiJ406Lpi9EKoWDi7GFL7%2Fuploads%2FBTdSGct3IBuYxXaGB8lQ%2FLinux_Troubleshooting_1.png?alt=media&amp;token=380e7e2a-fe2a-4afa-bbe9-ea5c0bac2bbf" alt="Linux terminal displaying the script with highlighted important information." data-size="original">
{% endstep %}

{% step %}

#### Start and enable the service (if inactive)

If the status is `inactive` or `failed`, start the service and enable it on boot:

```
sudo systemctl enable --now goodaccess
```

Once started, reopen the GoodAccess Client Application and try connecting again.
{% endstep %}

{% step %}

#### Next steps

* **If the service is running, but you still can't connect:** Please follow our [general Troubleshooting](/faq-and-troubleshooting/troubleshooting.md).
* **If the service fails to start:** Go to **Settings > Debug Features**, click **Export Logs**, save the ZIP file, and attach it to your message when contacting our [technical support](https://www.goodaccess.com/contact).
  {% endstep %}
  {% endstepper %}

</details>

<details>

<summary>Tray Icon missing</summary>

* Install Gnome Extension "[Tray Icons: Reloaded](https://extensions.gnome.org/extension/2890/tray-icons-reloaded/)"

</details>

<details>

<summary>Arch Linux: WireGuard protocol fails to connect</summary>

#### Symptom

When you attempt to connect using the WireGuard protocol, the status switch returns to OFF after a few seconds without displaying an error in the UI. Other protocols connect normally.

{% stepper %}
{% step %}

#### Check the service logs

Inspect the GoodAccess background service log:

```
journalctl -u goodaccess.service
```

Look for the following error lines:

```
resolvconf: command not found
Failed to start WireGuard tunnel GoodAccess
```

*If you do not see these errors in the log, please refer to our* [*general Troubleshooting*](/faq-and-troubleshooting/troubleshooting.md)*. Otherwise, proceed to the next step.*
{% endstep %}

{% step %}

#### Install and enable DNS resolver

WireGuard requires a `resolvconf` implementation to configure DNS. Install the provider package for `systemd-resolved` and enable the service:

```
sudo pacman -S systemd-resolvconf
sudo systemctl enable --now systemd-resolved
```

{% endstep %}

{% step %}

#### Configure the system DNS

Point the system resolver to `systemd-resolved`:

```
sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
```

If you are using **NetworkManager**, restart it to apply the new DNS configuration:

```
sudo systemctl restart NetworkManager
```

{% endstep %}

{% step %}

#### Reconnect

Open the GoodAccess Client Application and connect using the WireGuard protocol again.
{% endstep %}
{% endstepper %}

</details>