import Image from "next/image";
import Alert from "@/components/DocsAlert";

# End-user Client Instructions

Follow these instructions if you're an end-user trying to set up your WireGuard
client to work with Firezone.

## Install and setup

Follow this guide to establish a VPN session through the WireGuard native
client.

### Step 1: Install the native WireGuard client

Firezone is compatible with the official WireGuard clients found here:

- [macOS](https://itunes.apple.com/us/app/wireguard/id1451685025)
- [Windows](https://download.wireguard.com/windows-client/wireguard-installer.exe)
- [iOS](https://itunes.apple.com/us/app/wireguard/id1441195209)
- [Android](https://play.google.com/store/apps/details?id=com.wireguard.android)

For operating systems not listed above see the Official WireGuard site:
[ https://www.wireguard.com/install/](https://www.wireguard.com/install).

### Step 2: Download the device config file

The device config file can either be obtained from your Firezone administrator
or self-generated via the Firezone portal.

To self generate a device config file, visit the domain provided by your
Firezone administrator. This URL will be specific to your company (in this
example it is `https://firezone.example.com`)

<Image
  className="mx-auto"
  alt="firezone okta sso login"
  src="/images/firezone-okta-sso-login.gif"
  width={960}
  height={540}
/>

### Step 3 (optional): Enable on boot

Open the WireGuard client and import the `.conf` file. Activate the VPN session
by toggling the `Activate` switch.

<Image
  className="mx-auto"
  alt="activate tunnel"
  src="/images/activate-tunnel.gif"
  width={960}
  height={540}
/>

## Re-authenticating your session

If your network admin has required periodic authentication to maintain your VPN
session, follow the steps below. You will need:

- **URL of the Firezone portal**: Ask your Network Admin for the link.
- **Credentials**: Your username and password should be provided by your Network
  Admin. If your company is using a Single Sign On provider (like Google or
  Okta), the Firezone portal will prompt you to authenticate via that provider.

### Step 1: Deactivate VPN session

<Image
  className="mx-auto"
  alt="wireguard deactivate"
  src="/images/wireguard-deactivate.png"
  width={960}
  height={540}
/>

### Step 2: Re-authenticate

Visit the URL of your Firezone portal and sign in using credentials provided by
your network admin. If you are already logged into the portal, click the
`Reauthenticate` button, then sign in again.

<Image
  className="mx-auto"
  alt="re-authenticate"
  width={960}
  height={540}
  src="/images/re-authenticate.gif"
/>

### Step 3: Activate VPN session

<Image
  className="mx-auto"
  alt="activate session"
  src="/images/activate-session.png"
  width={960}
  height={540}
/>

## Linux: Network Manager

The following steps can be used on Linux devices to import the WireGuard
configuration profile using Network Manager CLI (`nmcli`).

<Alert
  color="info"
  html={`
Importing the configuration file using the Network Manager GUI may fail
with the following error if the profile has IPv6 support enabled:
<code>
ipv6.method: method "auto" is not supported for WireGuard
</code>
`}
/>

### Step 1: Install the WireGuard tools

The WireGuard userspace tools need to be installed. For most Linux distributions
this will be a package named `wireguard` or `wireguard-tools`.

For Debian/Ubuntu:

```bash
sudo apt install wireguard
```

For Fedora:

```bash
sudo dnf install wireguard-tools
```

For Arch Linux:

```bash
sudo pacman -S wireguard-tools
```

For distributions not listed above see the Official WireGuard site:
[ https://www.wireguard.com/install/](https://www.wireguard.com/install).

### Step 2: Download configuration

The device config file can either be obtained from your Firezone administrator
or self-generated via the Firezone portal.

To self generate a device config file, visit the domain provided by your
Firezone administrator. This URL will be specific to your company (in this
example it is `https://firezone.example.com`)

<Image
  className="mx-auto"
  alt="firezone okta sso login"
  src="/images/firezone-sso-okta-login.gif"
  width={960}
  height={540}
/>

### Step 3: Import configuration

Using `nmcli`, import the downloaded configuration file:

```bash
sudo nmcli connection import type wireguard file /path/to/configuration.conf
```

<Alert
  color="info"
  html={`
The WireGuard connection/interface will match the name of the
configuration file. If required, the connection can be renamed after import:
<code>
nmcli connection modify [old name] connection.id [new name]
</code>
`}
/>

### Step 4: Connect/disconnect

To connect to the VPN via the command line:

```bash
nmcli connection up [vpn name]
```

To disconnect:

```bash
nmcli connection down [vpn name]
```

If using a GUI, the relevant Network Manager applet can also be used to control
the connection.

### Auto connection

The VPN connection can be set to automatically connect by setting the
`autoconnect` option to `yes`:

```bash
nmcli connection modify [vpn name] connection.autoconnect yes
```

To disable the automatic connection set it back to `no`:

```bash
nmcli connection modify [vpn name] connection.autoconnect no
```

## Enable multi-factor authentication

To enable MFA navigate to `/user_account/register_mfa` in the Firezone portal.
After generating the QR code, scan using your authenticator app and input the 6
digit code.

If you lose your authenticator app, contact your Admin to reset access to your
account.
