nixpkgs/docs/modules/nixos/ports.md

ports NixOS Module

Port management module for NixOS.

Overview

This module provides centralized port management across multiple hosts. Define default ports and host-specific overrides to prevent conflicts.

See Port Management Guide for detailed usage.

Quick Start

{config, ...}: {
  m3ta.ports = {
    enable = true;

    # Define default ports
    definitions = {
      nginx = 80;
      grafana = 3000;
      prometheus = 9090;
    };

    # Host-specific overrides
    hostOverrides = {
      laptop = {
        nginx = 8080;
        grafana = 3001;
      };
    };

    # Current host
    currentHost = config.networking.hostName;
  };
}

Module Options

m3ta.ports.enable

Enable port management.

• Type: boolean
• Default: false

m3ta.ports.definitions

Default port definitions.

• Type: attrsOf int
• Default: {}

Example:

definitions = {
  nginx = 80;
  grafana = 3000;
  prometheus = 9090;
};

m3ta.ports.hostOverrides

Host-specific port overrides.

• Type: attrsOf (attrsOf int)
• Default: {}

Example:

hostOverrides = {
  laptop = {
    nginx = 8080;
    grafana = 3001;
  };
  server = {
    nginx = 80;
    prometheus = 9091;
  };
};

m3ta.ports.currentHost

Current hostname. Determines which overrides to apply.

• Type: string
• Example: config.networking.hostName

Functions

config.m3ta.ports.get "service"

Get port for a service with host-specific override.

services.nginx = {
  port = config.m3ta.ports.get "nginx";
};

If current host is laptop and hostOverrides.laptop.nginx = 8080, returns 8080. If no override, returns default 80.

config.m3ta.ports.getHostPorts "hostname"

Get all ports for a specific host.

# Get all ports for laptop
laptopPorts = config.m3ta.ports.getHostPorts "laptop";
# Returns: { nginx = 8080; grafana = 3000; ... }

config.m3ta.ports.listServices

List all defined service names.

allServices = config.m3ta.ports.listServices;
# Returns: ["nginx" "grafana" "prometheus"]

Usage Examples

Basic Usage

{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
    };
    currentHost = "server";
  };

  services.nginx = {
    enable = true;
    httpConfig = ''
      server {
        listen ${toString (config.m3ta.ports.get "nginx")};
      }
    '';
  };
}

Multi-Host Setup

{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
      prometheus = 9090;
    };
    hostOverrides = {
      laptop = {
        nginx = 8080;
        grafana = 3001;
      };
      server = {
        nginx = 80;
        grafana = 3000;
      };
    };
    currentHost = config.networking.hostName;
  };

  services.nginx = {
    enable = true;
    httpConfig = ''
      server {
        listen ${toString (config.m3ta.ports.get "nginx")};
      }
    '';
  };
}

With Multiple Services

{config, ...}: {
  m3ta.ports = {
    enable = true;
    definitions = {
      # Monitoring
      grafana = 3000;
      prometheus = 9090;
      loki = 3100;
      promtail = 9080;

      # Web
      nginx = 80;

      # Databases
      postgres = 5432;
      redis = 6379;
      qdrant = 6333;
    };
    currentHost = config.networking.hostName;
  };

  # Use ports
  services.grafana = {
    enable = true;
    settings.server.http_port = config.m3ta.ports.get "grafana";
  };

  services.postgresql = {
    enable = true;
    port = config.m3ta.ports.get "postgres";
  };
}

Related

• Port Management Guide - Detailed guide
• Home Manager Ports Module - User-level port management