Configuration

$ dpkg -l | grep pirogue-base
ii  pirogue-base    2.0.2    all    Install all PiRogue packages

How the PiRogue administration works#

The PiRogue functionalities are all controlled and configured by the pirogue-admin tool. pirogue-admin uses and writes its configuration files in the system folder: /var/lib/pirogue/admin.

By default, on a first and fresh installation, pirogue-admin detects and generates the best configuration for the current system.

However, modifying this configuration can be done using the pirogue-admin-client tool after the initial installation.

Administration concepts#

After a system installation, it’s possible to get current applied and running configuration with the following command:

pirogue-admin-client system get-configuration

The result should look like:

DASHBOARD_PASSWORD: PiRogue
ENABLE_DHCP: 'True'
ENABLE_PUBLIC_ACCESS: 'False'
EXTERNAL_ADDRESS: 192.168.1.37
EXTERNAL_INTERFACE: enp0s3
EXTERNAL_NETWORKS: 192.168.1.0/24
ISOLATED_ADDRESS: 10.8.0.1
ISOLATED_INTERFACE: wg0
ISOLATED_NETWORK: 10.8.0.0/24
PUBLIC_CONTACT_EMAIL: root@pirogue.local
PUBLIC_DOMAIN_NAME: pirogue.local
PUBLIC_EXTERNAL_ADDRESS: 185.199.111.153
SYSTEM_HOSTNAME: pirogue
SYSTEM_OPERATING_MODE: wireguard
WIFI_COUNTRY_CODE: FR
WIFI_PASSPHRASE: superlongkey
WIFI_SSID: PiRogue

Administrating a PiRogue consists in modifying these variables. Subsequently, lots of system files are updated and system services are started, stopped or reloaded accordingly.

With the wide variety of PiRogue’s new network capabilities, it could be hard to maintain a coherent and safe relationship between all the configuration variables, system files, and services.

This is why PiRogue offers two level of administration:

• pirogue-admin: low-level administration tool (used internally, and must not be used directly)
• pirogue-admin-client: high-level administration tool aiming safety and ease of use

Safe and easy administration#

pirogue-admin-client is the tool to administrate high-level PiRogue features. It allows you to configure many PiRogue components without having to deal with the variables directly.

You can explore all its capabilities using the command line parameter --help, e.g:

pirogue-admin-client --help

The tool is subdivided in sections on which --help can be shown, e.g:

pirogue-admin-client wifi --help
pirogue-admin-client wifi get-configuration --help
pirogue-admin-client wifi set-configuration --help
pirogue-admin-client system --help
# ... and so on

Operating modes#

Depending on system capabilities, pirogue-admin has configured automatically the PiRogue in the adequate mode.

Here are the different modes:

• Wireguard mode: when only one network interface is available on the system
• Appliance mode: when two different network interfaces are available on the system
• Access-point mode: when two different network interfaces are available, one of which has WiFi capabilities

Depending on the operating mode, pirogue-admin-client offers different configuration tools.

General configuration#

The following commands applies to all operating modes.

Dashboard configuration#

The password of the dashboard can be changed with:

pirogue-admin-client dashboard set-configuration --password 'mySuperSecretPassword!'

The username of the dashboard remains admin.

If you have forgotten the dashboard password, you can always retrieve it with the following command:

pirogue-admin-client dashboard get-configuration

Access Point mode configuration#

Change the WiFi configuration#

Get the current WiFi configuration:

pirogue-admin-client wifi get-configuration

The result looks like:

country_code: FR
passphrase: superlongkey
ssid: PiRogue1

Change the WiFi SSID and password:

pirogue-admin-client wifi set-configuration --ssid 'Investigation_Lab' --passphrase 'Hard to guess passphrase !'

Explore the WiFi configuration parameters:

pirogue-admin-client wifi set-configuration --help

Wireguard mode configuration#

Manage VPN peers#

Add a new VPN peer:

pirogue-admin-client vpn add-peer

The result will look like:

idx: 3
private_key: YGe5EF//sIj6QF/2sglmx20b7jxgxFpV1sl8hXBDy34=
public_key: 8lSksu3/HF8vCGi5lCOktI3C9L68PsfNhzDwyuAtMQ0=

Get a list of current active VPN peers:

pirogue-admin-client vpn list-peers

The result will look like:

- idx: 2
  private_key: oA3PBMH5yhBCIykx1odFPbnH+QKq18FBPmdPU1MrmEQ=
  public_key: hdlwEsh7SQ0lEPC5Qpl66y9slJkhH4wUYEpzvkEq6V4=
- idx: 3
  private_key: YGe5EF//sIj6QF/2sglmx20b7jxgxFpV1sl8hXBDy34=
  public_key: 8lSksu3/HF8vCGi5lCOktI3C9L68PsfNhzDwyuAtMQ0=

Delete a peer, given its index:

pirogue-admin-client vpn delete-peer 2

Connect peers to the VPN#

To connect a VPN peer, we need to get its full configuration file. You can get the configuration using the following command:

pirogue-admin-client vpn get-peer-configuration 3

The result looks like:

[Interface]
Address = 10.8.0.3/24
PrivateKey = YGe5EF//sIj6QF/2sglmx20b7jxgxFpV1sl8hXBDy34=
DNS = 10.8.0.1

[Peer]
EndPoint = 185.199.111.153:51820
PublicKey = YxtvfgfpgCpkQKTI9vcVz0LnXGHIwF83Z65OBWw4F0A=
AllowedIPs = 0.0.0.0/0
PersistentKeepAlive = 20

We can save this content to a .conf file and load it on the mobile device we want to connect.

It’s also possible to generate a QR code to scan it with the mobile device Wireguard application:

pirogue-admin-client vpn get-peer-config 3 | qrencode -t ansiutf8

Remote administration#

Depending on the network topology in which the administrator wants to perform remote administration, the configuration of the PiRogue and the administrator’s computer is different.

There are two main topologies possible:

• Local Area Network (LAN): usually home or organization internal network, connections will stay inside the network
• Wide Area Network (WAN): when the PiRogue is exposed on Internet

Administrator’s computer setup#

Regardless of the administration network topology, we must install pirogue-admin-client on the administrator’s computer. It can be done by adding our PPA:

# Install PiRogue PPA
sudo wget -O /etc/apt/sources.list.d/pirogue.list https://pts-project.org/debian-12/pirogue.list
sudo wget -O /etc/apt/trusted.gpg.d/pirogue.gpg   https://pts-project.org/debian-12/pirogue.gpg
sudo apt update
# Install pirogue-admin-client
sudo apt install pirogue-admin-client
# If we want to generate QR-Code
sudo apt install qrencode

LAN administration#

Let’s assume the following topology:

By default, PiRogue installation will generate a self-signed certificate to secure the connections between the PiRogue and the administration client. This certificate is needed to allow the administration daemon running on the PiRogue and by the administration client to communicate between each other securely.

Get the self-signed certificate:

pirogue-admin-client external-network get-administration-certificate > virogue-external.cert

Get configuration commands:

pirogue-admin-client external-network get-administration-clis

Results look like:

# One time client configuration
pirogue-admin-client --save --host '192.168.1.37' --port 50051 --token UH77iumyt64BSThL6N06667SuTcKkOq2EkR5ckvQ5Ww

On the administration device, we can run the following command to configure the remote administration client:

# Replace <remote-user> by the user of your PiRogue installation
scp <remote-user>@192.168.1.37:~/virogue-selfsigned.cert .
pirogue-admin-client --save --host '192.168.1.37' --port 50051 --token UH77iumyt64BSThL6N06667SuTcKkOq2EkR5ckvQ5Ww --certificate ~/virogue-external.cert

Setup is done. Try running a first administration command:

pirogue-admin-client system get-configuration

Online administration#

Let’s assume the following topology:

Let’s assume the following:

• we own a domain name: my-domain.org
• we have a valid administrative email address: contact@my-domain.org
• the following DNS record exists: pirogue-lab.my-domain.org. 3600 IN A 185.199.111.153
• contacting port 50051 on IP address 185.199.111.153 is redirected to the port 50051 on local IP address 192.168.1.37

Enable public exposure and access on the PiRogue:

pirogue-admin-client external-network enable-public-access --domain pirogue-lab.my-domain.org --email contact@my-domain.org

The authentication of the administration client uses a token. You can get the token with:

pirogue-admin-client external-network get-administration-token

Or, you can reset it with:

pirogue-admin-client external-network reset-administration-token

On the administrator’s computer, we run the following command to configure the remote administration client:

pirogue-admin-client --save --host 'pirogue-lab.my-domain.org' --port 50051 --token <administration token>

Test the communication between the administration client and the PiRogue with:

pirogue-admin-client system get-configuration