INSTALLATION

NodeManager Installation and Building

This document provides detailed information on how to install NodeManager on various platforms and how the build process works.

Nodemanager by default will configure the node to be part of the PlanetLab testbed. for more information please visit https://planetlab.io/

Supported Platforms

NodeManager is designed to run on a variety of Linux distributions and architectures.

Architectures

• x86_64: Standard 64-bit Intel/AMD processors.
• arm64 (aarch64): 64-bit ARM processors (e.g., ODROID, Raspberry Pi 4/5).

Distributions & Minimum Versions

• Debian 13 (Trixie)
• Ubuntu: 22.04 LTS (Jammy), 24.04 LTS (Noble), 26.04 LTS
• Rocky Linux: 9, 10
• Raspberry Pi OS: Latest version based on Debian 12 or 13.

Hardware Requirements

Preferred configuration

For optimal performance, the machine should have at least:

• Memory: 16 GB RAM
• CPU: 8 vCPUs
• Storage: 80 GB of available disk space

---

Minimum supported configuration

The minimum hardware configuration required to run the software is:

• Memory: 8 GB RAM
• CPU: 4 vCPUs
• Storage: 40 GB of available disk space

Systems meeting the minimum requirements are fully supported but may provide lower performance than the preferred configuration, particularly for compute-intensive experiments.

Network Requirements

Preferred configuration

The preferred deployment is a machine with a public IP address.

The network should permit:

• Ingress: TCP port 22 (SSH) for maintenance.
• Egress: UDP traffic to port 51820 for WireGuard.
• ICMP: Both inbound and outbound ICMP should be permitted, as it is required for network measurement experiments.
• No filtering of TCP, UDP, or ICMP traffic beyond these requirements.

SSH access may be restricted to the subnet 132.227.123.0/24 if desired.

---

Minimum supported configuration (machine behind NAT)

A machine with a private IP address behind NAT is also supported, provided it can establish an outbound WireGuard tunnel.

The minimum network requirements are:

• The machine must be allowed to initiate outbound UDP connections to 132.227.123.79:51820.
• No application-layer (Layer 7) filtering or proxying should be applied to this UDP traffic.
• Outbound ICMP traffic should be permitted (and inbound ICMP replies allowed) to support network measurement experiments.
• No inbound Internet ports are required on the machine; no port forwarding is necessary.

Because the machine initiates the WireGuard connection, all communication with the VPN will occur over the established tunnel.

Installation Methods

1. Official Repository (Recommended)

The preferred way to install NodeManager is via our official package repositories to ensure you receive updates automatically.

Debian / Ubuntu / Raspbian

Add the repository and install the package:

# Install the GPG key
curl -fsSL https://r.planetlab.io/deb/planetlab.gpg | sudo gpg --dearmor -o /usr/share/keyrings/planetlab.gpg

# Add the repository to sources list
echo "deb [signed-by=/usr/share/keyrings/planetlab.gpg] https://r.planetlab.io/deb stable main" | sudo tee /etc/apt/sources.list.d/planetlab.list

# Update and install
sudo apt update
sudo apt install nodemanager

Rocky Linux / RPM (Coming Soon)

We are currently working on providing official RPM repositories for Rocky Linux and Fedora-based systems.

2. Automated Installation Script

For a quick setup, you can use the installation script which detects your OS and configures the repository automatically:

curl -fsSL https://n.planetlab.io/install.sh | sudo bash

3. Installation using cloud-init

For cloud environments (AWS, OpenStack, etc.) or when using automated provisioning, you can use cloud-init to install and configure NodeManager automatically.

You can retrieve a ready-to-use cloud-config YAML from the Orchestrator:

curl -fsSL https://n.planetlab.io/cloud-init

This configuration will:

• Add the EdgeNet repository and GPG key.
• Install the nodemanager package and its dependencies.
• Enable and start the nodemanager service.

For more information on how this integrates with the node lifecycle, see the Cloud-Init Automation section.

Building NodeManager

NodeManager is built using a Makefile, and packages are generated using nfpm. While aptly is used for repository management, the actual building and packaging process follows these steps.

Prerequisites

• Go 1.24 or later
• Linux (for full functionality including WireGuard and provisioning)

Build and Install

To build and install the node manager on your system:

make build
sudo make install

Building Packages

To create RPM and Debian packages using nfpm:

make packages

Repository Infrastructure (Aptly)

Our Debian repositories are managed via aptly and hosted on a production web server.

Publication Endpoint:

• root_dir: /srv/services/caddy/webroot/r.planetlab.io/public/deb
• link_method: copy

Build Workflow

1. Compilation: The NodeManager source code is compiled for the target architecture using the Makefile.
2. Packaging: The binaries and configuration files are packaged into .deb and .rpm formats using nfpm.
3. Repository Addition (Debian):

   aptly repo add deb ./packages/nodemanager/build/

4. Publishing (Debian): The repository is updated and published using a GPG key:

   aptly publish update -gpg-key=${GPG_KEY_ID} stable filesystem:planetlab:

Troubleshooting Installation

If the service fails to start or you want to monitor the initial configuration:

journalctl -f -u nodemanager