Configuration
PiRogue version >=2.0.0
This documentation only applies when the package pirogue-base
version >=2.0.0
is installed.
Use dpkg -l
to check what version is installed:
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:
The result should look like:
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:
The tool is subdivided in sections on which --help
can be shown, e.g:
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:
The username of the dashboard remains admin
.
If you have forgotten the dashboard password, you can always retrieve it with the following command:
Access Point mode configuration
WiFi access-point mode
This section only applies if the current operating mode is Access Point (a.k.a AP)
Change the WiFi configuration
Get the current WiFi configuration:
The result looks like:
Change the WiFi SSID and password:
Explore the WiFi configuration parameters:
Wireguard mode configuration
Wireguard mode
Only applies if the current operating mode is VPN (a.k.a Wireguard)
Manage VPN peers
Add a new VPN peer:
The result will look like:
Get a list of current active VPN peers:
The result will look like:
Delete a peer, given its index:
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:
The result looks like:
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:
Remote administration
Warning
Network knowledge is required to configure the remote administration system.
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:
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:
Get configuration commands:
Results look like:
On the administration device, we can run the following command to configure the remote administration client:
Setup is done. Try running a first administration command:
Online administration
Requirements
- a managed domain name or fully qualified named virtual machine
- a valid email address to register against certification authorities
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 address185.199.111.153
is redirected to the port50051
on local IP address192.168.1.37
Enable public exposure and access on the PiRogue:
The authentication of the administration client uses a token. You can get the token with:
Or, you can reset it with:
On the administrator’s computer, we run the following command to configure the remote administration client:
Test the communication between the administration client and the PiRogue with: