Initial setup

Preparation

We will install in order:

1. a machine (the administrator’s),
2. a gateway and other machines in the same zone,
3. the tailnet network (coordination server),
4. other zones linked to our configuration.

Unique Configuration

All these nodes will be described in a single NixOS configuration on the administrator’s machine, from which we can update and evolve the entire network and its machines.

Initial Installation

Under optimization

The initial installation steps are being streamlined. In the meantime, the manual method is available on the English version of this site.

Creating a Zone

A zone (subnet) consists of at least a gateway, behind which you can have as many computers as you want.

The Gateway

A mini-computer that is always on, with at least 2 network interfaces (one ethernet connected to the ISP box and others that are part of the subnet - ethernet and wifi).

What hardware for my gateway?

A protectli 🡕 model or equivalent is ideal. This one 🡕 is sufficient with:

• NVME disk >= 256G
• Coreboot bios preferably
• Optional: wifi card

Client Checklist

If the installation is done remotely, here is the information to provide:

1. Connect the gateway to the ISP box.
2. Put the ISO (provided by the administrator) on a USB key 🡕 and connect it.
3. Note the gateway IP address (visible via the ISO or in the box).
4. In the ISP box interface, redirect port 22 to the gateway.
5. The administrator can now access the gateway and install it.
6. Finalize the installation: other devices, wifi, computers, local services.

Technical Note

Port 22 redirection allows SSH access to the gateway from the internet, essential for its installation. The USB key system is only accessible via an SSH authentication key, it is impossible to access it with a password. This redirection is no longer necessary once the gateway is installed, but access remains useful in case of problems.

Administrator Checklist

Coming soon…

Other Computers

• Any computer, smartphone, tablet connected to the gateway network automatically becomes part of the network (VPN) and can access services with some configurations.
• Available PCs? Pre-configured Linux systems provide many programs and all software and services pre-configured for network users.

---

Creating a User Account

Tip

Each user will have:

• An identifier (lowercase first name without accents if possible) and a main password.
• An address at poncon.fr, e.g. prenom@domain.tld (mailbox or redirection to another email).
• A local matrix address, e.g. @prenom:domain.tld (instant messaging and visio).

3 Important Elements

• The main password for vaultwarden 🡕, to open their vault.
• The IDM 🡕 authentication key to access all services.
• An additional password in IDM 🡕 in case of key loss.

Account Creation Steps

What the new user will need to do

• Choose a main password via the vaultwarden invitation (by e-mail).
• Create an “authentication key” and a recovery password (IDM).
• Install Bitwarden on their devices and configure it.
• Applications: install and configure as needed.

1. Create the system account

   POSIX account (optional)

   This step creates a POSIX account that will be available on Linux machines (servers, workstations, etc.) designated by the configuration. It is possible to create non-POSIX users (non-declarative) directly in Vaultwarden and Kanidm.

   A user must have:

   • an identifier (lowercase first name)
   • an email address (at domain.tld preferably)

   Add the user to the configuration file:

   usr/config.yaml

   users:
     charlie:
       uid: 1003
       name: "Charlie"
       profile: "teenager"
       groups: ["kids-ag", "global"]

   Then generate, commit and apply the configuration.

2. Vaultwarden account

   In the Vaultwarden administration interface, the previous user must be present (otherwise create it).

   1. Administrator: send an invitation.
   2. User: receives an email to enter their main password.
   3. Administrator: confirm the user in the interface.
       

3. On HCS (coordination server)

   Enable the Kanidm account:

   # Kanidm Onboarding -> transmit the link or qr-code
   kanidm person credential create-reset-token <login> --name idm_admin

   Then follow the steps for creating keys and passwords.

4. Bitwarden

   Installing and configuring Bitwarden on browsers and smartphones will allow the new user to simplify access to their account and services.

   Select “self-hosted”

   And enter the vaultwarden URL before entering the main password, otherwise you will send it to bitwarden.com!

   Recommended settings

   • Auto-fill → corresponding detection → “host”
   • Auto-fill → enable auto-fill
   • Set Bitwarden as the default password manager.

5. Access to Services

   SSO allows access to services with a single authentication. Access rules are defined by Kanidm claims.

Creating a Linux Machine

Creating a Linux machine is a quick operation.

Prerequisites:

• The cloud ISO image to generate with just iso.
• A machine declared in the configuration. Example:

usr/config.yaml

hosts:
- hostname: "bob-laptop"
  name: "Bob's Dell Laptop"
  zone: "main:2.2"
  profile: "laptop"
  groups: ["zone-main", "guests"]
  features: ["nfs-client"]
  mac: "f0:1f:af:13:62:23,bc:78:56:25:b8:57"

Procedure:

• Burn the cloud ISO image to a USB key.
• Connect the computer to the network and boot from the key.
• Apply the system then restart without the key.

System Application:

# Replace with the machine IP
just full-install bob-laptop nix 10.1.2.34

Full Installation

In a few minutes, the just full-install command will install the complete system with programs, configurations and users. If the operation fails, it is possible to resume the steps viewable in the Justfile file.

Connecting from Outside

To access all services (as well as shares) when not in a zone, a Tailscale VPN client is required. The administrator’s intervention is required for this configuration.

• Install the tailscale client (application).
• Request to join the headscale.domaine.tld network.
• The administrator must then validate this access:

# Connect to the HCS
just enter hcs

# Method 1: create a temporary authentication key on user 1 (nix)
#             then connect the client with this key. This method allows
#             accepting several clients at once (reusable).
sudo headscale preauthkeys create --reusable --expiration 1h --user 1

# Method 2: connect the client then activate its key.
sudo headscale nodes register --key xxx --user nix