How to Configure Hostname

1. Click "Edit" next to the hostname field
2. Enter a valid hostname following RFC 1035 standards
3. Click "Save" to store in database only
4. Click "Save & Apply" to also update VM configuration via cloud-init
5. Reboot the VM for changes to take effect

Examples

Common DNS Servers:

Management API Endpoint: Update VM Name

Note: The VM name is used by cloud-init as the hostname. Changes require a VM restart to take effect via cloud-init. The management platform uses a ticket-based authentication system with CSRF protection.

Storage System Architecture

The platform supports multiple storage backends, each optimized for different use cases:

Cloud-init Hostname Configuration

Cloud-init reads the VM name from QEMU config and applies it as hostname:

# /etc/cloud/cloud.cfg.d/99_hostname.cfg
hostname: web-server-01
fqdn: web-server-01.example.com
preserve_hostname: false

The hostname is set during first boot or when cloud-init clean is run followed by a reboot.

• Password Storage: Passwords are hashed using bcrypt (cost factor 10) before database storage
• Cloud-init Transmission: Passwords are transmitted to QEMU API via HTTPS/TLS 1.2+
• API Authentication: Uses PVEAuthCookie with CSRF token validation (RFC 7231)
• Session Management: Tickets expire after 2 hours of inactivity (configurable)
• Password Policy: Minimum 8 characters, no maximum (enforced client-side and server-side)

RRD Data Collection

Performance data is collected using Round Robin Database (RRD) format:

Data Retention: Hour (1 year), Day (5 years), Week (10 years), Month (50 years), Year (indefinite)

• Usage Calculation: Shows current CPU time used divided by total vCPU cores allocated
• Progress Bar: Visual indicator that can exceed 100% to show over-allocation scenarios
• Real-time Updates: Refreshes alongside the live status poll
• Data Source: Directly from Proxmox hypervisor metrics

• Usage Display: Shows used memory vs. total allocated memory
• Format: Human-readable format (B, KB, MB, GB) for easy understanding
• Entitlement Label: Displays your provisioned RAM entitlement
• Calculation: Based on the VPS's provisioned RAM configuration

• Uptime Display: Shows how long the VM has been running (formatted as days, hours, minutes)
• Power Events: Tracks starts, shutdowns, and reboots from task history
• Data Source: Combined data from hypervisor status and historical task logs
• Badge: Always shows "Live" to indicate real-time data

• Download Rate: Inbound traffic speed (displayed in green)
• Upload Rate: Outbound traffic speed (displayed in blue)
• Update Frequency: Every 30 seconds (matches Proxmox RRD sampling)
• Data Source: Proxmox RRD data via the /rrddata API endpoint
• Format: Human-readable with automatic unit conversion (B/s, KiB/s, MiB/s, GiB/s)

• Tracking: Automatically tracks peak download and upload rates
• Reset: Resets when the page is refreshed or reloaded
• Display: Shown next to current rates for easy comparison

• Time Range: Last 10 minutes of network activity
• Data Lines: Separate lines for download (green) and upload (blue) traffic
• Data Points: Up to 20 samples from Proxmox RRD data
• Interactive: Hover over data points to see exact values at specific times
• Auto-update: Graph updates automatically every 30 seconds with new data
• Toggle: Click "Graph" again to hide the chart

• Combined: Total of current download and upload rates
• Total In: Cumulative bytes received since VM start
• Total Out: Cumulative bytes sent since VM start
• Data Source: From Proxmox /status/current endpoint
• Format: Human-readable format (B, KB, MB, GB) for easy reading

• Interface Identification: Each card shows the interface name and bridge (e.g., "net0 (Route1p2)")
• Independent Tracking: Each interface tracks its own rates, peaks, and history
• Layout: Multiple interfaces are displayed in a responsive grid layout
• Data Aggregation: Total statistics combine data from all interfaces

How the Platform Updates Boot Order

UEFI Boot Manager Configuration:

# EFI Boot Manager entries (stored in EFI disk)
# Boot0000: Hard Disk
# Boot0001: CD-ROM
# Boot0002: Network

# UEFI boot order is managed via EFI variables
# Accessible through QEMU Guest Agent or UEFI shell:
# efibootmgr -o 0000,0001,0002

# QEMU UEFI boot configuration
{
  "bios": "ovmf",
  "efidisk0": "local-lvm:vm-100-disk-1,size=4M",
  "boot": "order=scsi0"
}

PXE Boot Process:

1. DHCP Discovery: VM broadcasts DHCP request (RFC 2131)
2. DHCP Offer: Server responds with IP, boot server, boot file
3. TFTP Download: Boot file (pxelinux.0) downloaded via TFTP (RFC 1350)
4. Boot Execution: PXE loader executes boot file

# DHCP option 66 (Boot Server Host Name)
# DHCP option 67 (Bootfile Name)

# QEMU PXE configuration
-netdev user,id=net0 \\
-device virtio-net-pci,netdev=net0 \\
-boot n

Debugging Techniques:

The firewall can be enabled or disabled using the toggle switch at the top of the Firewall tab. When enabled, all configured firewall rules will be active and enforced. When disabled, all traffic will be allowed by default.

• Enabled: All firewall rules are active and traffic is filtered according to your rules
• Disabled: All traffic is allowed, firewall rules are ignored

Firewall rules control which network traffic is allowed or blocked. Rules are processed in order from top to bottom, and the first matching rule determines the action taken.

Rule Actions

Rule Parameters

• Source: IP address or network (CIDR notation) where traffic originates from (e.g., 192.168.1.0/24)
• Destination: IP address or network (CIDR notation) where traffic is going to
• Protocol: Network protocol (TCP, UDP, ICMP, ICMPv6, or Any)
• Destination Port: Port number or range (e.g., 80, 443, or 1000:2000)
• Source Port: Source port number or range
• Interface: Network interface name (e.g., net0) to apply the rule to
• Log Level: Optional logging level for matching traffic (info, warning, error, etc.)
• Comment: Optional description for the rule

Rule Order

Rules are processed in order from top to bottom. The first matching rule determines the action. It's important to place more specific rules before general ones. For example:

1. Allow specific IP addresses first
2. Then allow specific port ranges
3. Finally, block or reject all other traffic

Aliases allow you to create named references to IP addresses or networks. This makes firewall rules more readable and easier to maintain. Instead of typing IP addresses repeatedly, you can use an alias name.

Example: Create an alias named trusted-network for 192.168.1.0/24, then use trusted-network in your firewall rules instead of the full CIDR notation.

• Alias names must be unique
• CIDR notation is required (e.g., 192.168.1.0/24)
• Aliases can be used in firewall rule source and destination fields

IP sets are collections of IP addresses or networks that can be referenced in firewall rules. They are useful for managing large lists of IP addresses, such as blocked IPs or allowed IPs for specific services.

Use Cases:

• Blocking multiple IP addresses from accessing your services
• Creating allow lists for specific applications
• Managing IP addresses that change frequently

Note: After creating an IP set, you can add individual IP addresses or networks to it through the API. IP sets can then be referenced in firewall rules using the set name.

• Default Deny: Start with a default deny policy and explicitly allow only necessary traffic
• Specific Rules First: Place more specific rules before general ones to ensure correct matching
• Use Aliases: Use aliases for frequently referenced networks to improve readability and maintenance
• Enable Logging: Enable logging on important rules to monitor traffic and troubleshoot issues
• Test Rules: Test new rules carefully to avoid accidentally blocking legitimate traffic
• Document Rules: Use comments to document the purpose of each rule
• Regular Review: Periodically review and clean up unused rules, aliases, and IP sets

Allow SSH from Specific IP

Action: ACCEPT
Source: 192.168.1.100
Protocol: TCP
Destination Port: 22
Comment: Allow SSH from office

Block All Traffic from a Network

Action: DROP
Source: 10.0.0.0/8
Comment: Block private network range

Allow Web Traffic on Ports 80 and 443

Action: ACCEPT
Protocol: TCP
Destination Port: 80,443
Comment: Allow HTTP and HTTPS

Network Topology & Bridge Configuration

Physical Host (Management Node)
  └── Linux Bridge (vmbr0) - Managed by platform
      ├── Host Interface (eth0) - Physical NIC
      ├── VLAN Interfaces (vmbr0.100, vmbr0.200)
      └── TAP Device (vnetX) - Created per VM
          └── QEMU VM
              └── VirtIO/E1000 Network Adapter
                  └── Guest OS Network Stack

# Bridge Configuration (managed by platform)
# /etc/network/interfaces or netplan
auto vmbr0
iface vmbr0 inet static
    address 192.168.1.10/24
    gateway 192.168.1.1
    bridge_ports eth0
    bridge_stp off
    bridge_fd 0
    bridge_vlan_aware yes

TAP devices operate at Layer 2 (Ethernet) and are bridged to the physical network interface. The management platform automatically creates and manages TAP devices for each VM network interface.

How Network Settings Are Applied

QEMU Network Device Configuration

# QEMU command-line equivalent
-netdev type=tap,id=net0,ifname=vnet0,script=/etc/qemu-ifup,downscript=/etc/qemu-ifdown \\
-device virtio-net-pci,netdev=net0,mac=52:54:00:12:34:56,bus=pcie.0,addr=0x2

# Configuration parameters:
# -netdev type: tap|user|bridge|socket
# -device: virtio-net-pci|e1000|rtl8139
# mac: MAC address (auto-generated if not specified)
# bus: PCIe bus location
# addr: PCIe device address

VirtIO Performance Optimization:

• Multiqueue: Enable with mq=on,vectors=4 for multi-core VMs
• vhost-net: Kernel-based packet processing (lower latency)
• RSS (Receive Side Scaling): Distribute network load across CPU cores
• TSO/GSO: TCP Segmentation Offload for large packet handling

# Optimized VirtIO configuration
-device virtio-net-pci,netdev=net0,mq=on,vectors=4

# Enable vhost-net in QEMU
-netdev type=tap,id=net0,vhost=on

Troubleshooting Tips:

The management platform includes an integrated firewall system that can apply rules at the VM level, bridge level, or cluster level.

DNS Record Structure

# DNS Resource Record Format (RFC 1035 Section 3.2.1)
NAME            TYPE    CLASS   TTL     RDLENGTH  RDATA
web.example.com A       IN      3600    4        192.168.1.1

# DNS Message Format
Header (12 bytes)
  - ID (16 bits): Transaction identifier
  - Flags (16 bits): QR, Opcode, AA, TC, RD, RA, Z, RCODE
  - QDCOUNT (16 bits): Number of questions
  - ANCOUNT (16 bits): Number of answers
  - NSCOUNT (16 bits): Number of authority records
  - ARCOUNT (16 bits): Number of additional records

Question Section
  - QNAME: Domain name (variable length)
  - QTYPE: Record type (A=1, AAAA=28)
  - QCLASS: Class (IN=1)

Answer Section
  - Resource Records (variable)

While DNSSEC is not currently implemented in the subdomain system, understanding DNS security is important:

• RFC 4033: DNS Security Introduction and Requirements
• RFC 4034: Resource Records for DNS Security Extensions
• RFC 4035: Protocol Modifications for DNS Security
• TSIG (RFC 2845): Transaction Signatures for DNS updates

Cloud-init YAML Configuration

# /var/lib/cloud/seed/nocloud/user-data
#cloud-config
users:
  - name: admin
    groups: sudo
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...
    lock_passwd: false
    passwd: $6$rounds=4096$salt$hashedpassword

# Network configuration (version 2)
network:
  version: 2
  ethernets:
    eth0:
      addresses:
        - 192.168.1.100/24
      gateway4: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4

# DNS configuration
manage_resolv_conf: true
resolv_conf:
  nameservers: ['8.8.8.8', '1.1.1.1']
  searchdomains: ['example.com']

# QEMU cloud-init configuration
{
  "cicustom": "user=local:snippets/user-data",
  "cipassword": "$5$rounds=5000$salt$hash",
  "ciuser": "admin",
  "ipconfig0": "ip=192.168.1.100/24,gw=192.168.1.1",
  "nameserver": "8.8.8.8 8.8.4.4",
  "searchdomain": "example.com",
  "ostype": "l26"  # Linux 2.6+ kernel
}

# Cloud-init data source (NoCloud)
-drive file=user-data.img,format=raw,if=virtio
-drive file=meta-data.img,format=raw,if=virtio

SSH Public Key Format:

# RSA key (RFC 4253 Section 6.6)
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... user@host

# ED25519 key (RFC 8709)
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... user@host

# ECDSA key (RFC 5656)
ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBB... user@host

# Key fingerprint (SHA256)
ssh-keygen -lf ~/.ssh/id_rsa.pub
# SHA256:AbCdEf1234567890... user@host (RSA)

Security Best Practice: Use ED25519 keys (stronger, faster) or RSA 4096-bit minimum.

Static IP Configuration (RFC 791/2460):

# IPv4 Static Configuration
network:
  version: 2
  ethernets:
    eth0:
      addresses:
        - 192.168.1.100/24        # CIDR notation
      gateway4: 192.168.1.1      # Default gateway
      routes:
        - to: 10.0.0.0/8
          via: 192.168.1.254
      nameservers:
        addresses: [8.8.8.8, 1.1.1.1]
        search: [example.com]

# IPv6 Static Configuration (RFC 2460)
network:
  version: 2
  ethernets:
    eth0:
      addresses:
        - 2001:db8::100/64
      gateway6: 2001:db8::1
      nameservers:
        addresses: [2001:4860:4860::8888]

VRAM Allocation Guidelines:

Note: VRAM is allocated from VM's main memory. Higher VRAM reduces available RAM for the guest OS. Use the minimum required for your use case.

Background Statistics Collection

# Statistics collection runs via Laravel scheduler
# Scheduled command: proxmox:poll-statistics
# Frequency: Hourly (every hour on the hour)

# Command implementation:
php artisan schedule:run

# The scheduler executes:
Schedule::command(PollServerStatistics::class)
    ->description('Poll Proxmox server statistics hourly')
    ->hourly();

# Statistics are stored in database table:
# ext_proxmox_servers_statistics

# Fields tracked:
# - server_id: Foreign key to server
# - netin, netout: Network traffic counters
# - diskread, diskwrite: Disk I/O counters
# - diskused, diskmax: Disk space usage
# - memoryused, memorymax: Memory usage
# - cpuused, cpumax: CPU usage
# - uptime: VM uptime in seconds
# - vmstatus: Current VM power state
# - DateTime: Timestamp of statistic
# - is_automatic: Boolean flag (true for automatic, false for manual)

Statistics Data Management

# Automatic statistics cleanup logic:
# When creating a new automatic statistic:

1. Create new statistic with is_automatic = true
2. Count total automatic statistics for server
3. If count > 24:
   - Find oldest automatic statistics (order by DateTime ASC)
   - Delete excess entries (count - 24)
   - Keep exactly 24 automatic statistics

# Manual statistics management:
# - Users can create up to 5 manual statistics
# - Manual statistics are marked with is_automatic = false
# - Manual statistics can be deleted individually
# - Manual statistics are NOT automatically cleaned up

# Query examples:
# Get all statistics for a server:
SELECT * FROM ext_proxmox_servers_statistics 
WHERE server_id = ? 
ORDER BY DateTime DESC;

# Get only automatic statistics:
SELECT * FROM ext_proxmox_servers_statistics 
WHERE server_id = ? AND is_automatic = true
ORDER BY DateTime DESC
LIMIT 24;

# Get manual statistics:
SELECT * FROM ext_proxmox_servers_statistics 
WHERE server_id = ? AND is_automatic = false
ORDER BY DateTime DESC;

The Live Telemetry section at the top of the Statistics tab shows real-time performance graphs sourced directly from the Proxmox RRD API. These graphs are optimized to load quickly and to avoid overloading either the browser or the API.

Memory Utilization Graph Details

• The Memory Utilization graph displays a single series showing current RAM usage over time.
• The vertical axis locks to the VM's configured maximum memory when a valid value is available; otherwise it auto-scales to fit the data so the graph is never flat.
• Values are shown in bytes and converted to human-readable units (KiB, MiB, GiB) on the y-axis using binary prefixes.
• Export actions download the currently displayed memory data points as a CSV file.

Disk Configuration Format

# Platform disk configuration format
# scsi0: storage:disk-name,size=32G,format=raw,cache=writeback,iothread=1

# Storage types:
# - local-lvm: LVM thin pool (local-lvm:vm-100-disk-0)
# - cephpool: Ceph RBD (cephpool:vm-100-disk-0)
# - local: Directory storage (local:100/vm-100-disk-0.raw)
# - nfs: NFS mount (nfs:vm-100-disk-0)

# Disk options:
# - size: Disk size (e.g., 32G, 100G)
# - format: raw|qcow2|vmdk
# - cache: none|writeback|writethrough|unsafe|directsync
# - iothread: Enable I/O thread (1|0)
# - discard: Enable TRIM/discard (on|ignore)
# - ssd: Emulate SSD (1|0)
# - replicate: Enable replication (1|0) - for Ceph

# Example configurations:
{
  "scsi0": "local-lvm:vm-100-disk-0,size=32G,format=raw,cache=writeback",
  "scsi1": "cephpool:vm-100-disk-1,size=100G,format=raw,replicate=1",
  "ide2": "local:iso/debian-12.iso,media=cdrom"
}

# Add disk via API
POST /api2/json/nodes/{node}/qemu/{vmid}/config
{
  "scsi1": "local-lvm:vm-100-disk-1,size=50G"
}

Platform Resource Management:

# Resource pools allow grouping VMs for management
POST /api2/json/pools
{
  "poolid": "production",
  "comment": "Production VMs"
}

# Add VM to pool
PUT /api2/json/pools/{poolid}
{
  "vms": "100,101,102"
}

# Resource limits per VM
PUT /api2/json/nodes/{node}/qemu/{vmid}/config
{
  "memory": 4096,           # RAM in MB
  "cores": 4,                # CPU cores
  "cpu": "host",             # CPU type
  "balloon": 1024,           # Balloon device memory (MB)
  "shares": 1000,            # CPU shares (relative priority)
  "cpulimit": 2,             # CPU limit (cores)
  "cpuunits": 1024,          # CPU weight (relative to 1024)
  "net0": "virtio=...,rate=100"  # Network rate limit (MB/s)
}

# Platform automatically enforces limits via:
# - cgroups (CPU, memory)
# - tc (traffic control for network)
# - iotune (disk I/O limits)

The platform supports high availability for VMs across cluster nodes using Corosync and Pacemaker.

# Enable HA for VM
POST /api2/json/cluster/ha/groups
{
  "group": "production",
  "nodes": "pve-node-01,pve-node-02,pve-node-03",
  "restart": 1,
  "max_restart": 3,
  "max_relocate": 3
}

POST /api2/json/cluster/ha/resources
{
  "sid": "vm:100",
  "group": "production",
  "max_restart": 3,
  "max_relocate": 3
}

# HA behavior:
# - Automatic VM restart on node failure
# - VM migration to healthy node
# - Fencing of failed nodes
# - Requires shared storage (Ceph, NFS)

# HA requirements:
# - Minimum 3 nodes for quorum
# - Shared storage for VM disks
# - Network connectivity between nodes
# - Corosync cluster configuration

Backup Storage & Format

The management platform uses a proprietary backup format (VMA - Virtual Machine Archive) that stores complete VM state including disks, configuration, and snapshots.

# Backup file format
vzdump-qemu-{vmid}-{timestamp}.vma.zst

# Backup contents:
# - VM configuration (QEMU config)
# - Disk images (raw or qcow2)
# - Metadata (VM name, description, tags)
# - Compression: zstd (default) or gzip

# Backup storage locations
# - local storage: /var/lib/vz/dump/
# - NFS storage: mounted NFS share
# - S3-compatible: object storage
# - PBS (Platform Backup Server): dedicated backup server

# Create backup via API
POST /api2/json/nodes/{node}/qemu/{vmid}/vzdump
{
  "storage": "local",
  "compress": "zstd",
  "mode": "snapshot",
  "remove": 0
}

# Backup modes:
# - snapshot: Live backup (VM continues running)
# - stop: Stop VM before backup
# - suspend: Suspend VM during backup

# Restore backup via API
POST /api2/json/nodes/{node}/storage/{storage}/content
{
  "filename": "vzdump-qemu-100-20240101_120000.vma.zst",
  "vmid": 200,
  "storage": "local-lvm"
}

Platform Backup Jobs:

# Create backup job
POST /api2/json/config/backup
{
  "vmid": "100",
  "storage": "local",
  "compress": "zstd",
  "mode": "snapshot",
  "schedule": "0 2 * * *",  # Cron format: daily at 2 AM
  "prune-backups": "keep-last=7,keep-daily=30,keep-weekly=12,keep-monthly=12"
}

# Retention policy:
# - keep-last: Keep last N backups
# - keep-daily: Keep daily backups for N days
# - keep-weekly: Keep weekly backups for N weeks
# - keep-monthly: Keep monthly backups for N months

# List backup jobs
GET /api2/json/config/backup

# Backup job execution
# Platform runs backup jobs via cron or systemd timers
# Logs available at: /var/log/pve/tasks/active

VNC Proxy & WebSocket

# Platform VNC proxy API
GET /api2/json/nodes/{node}/qemu/{vmid}/vncproxy
{
  "port": "5900",
  "user": "root@pam",
  "ticket": "PVE:root@pam:65A8B123::..."
}

# VNC WebSocket URL format
wss://{host}:8006/api2/json/nodes/{node}/qemu/{vmid}/vncwebsocket?port={port}&vncticket={ticket}

# Platform automatically:
# - Creates VNC server on VM startup
# - Manages VNC port allocation
# - Provides WebSocket proxy for browser access
# - Handles authentication via tickets

# VNC configuration in VM
{
  "vga": "std",           # Standard VGA (includes VNC)
  "vnc": 1,               # Enable VNC
  "vncdisplay": 0,        # VNC display number
  "keyboard": "en-us"     # Keyboard layout
}

# Serial console access
{
  "serial0": "socket",
  "vga": "serial0"
}

# Platform serial console
GET /api2/json/nodes/{node}/qemu/{vmid}/termproxy
# Returns WebSocket URL for serial console

The platform implements ticket-based authentication for console access, providing secure temporary access tokens.

# Ticket format
PVE:username@realm:timestamp:signature

# Ticket components:
# - PVE: Platform identifier
# - username@realm: User and authentication realm (pam, pve, etc.)
# - timestamp: Unix timestamp
# - signature: HMAC-SHA256 signature

# Ticket validation:
# - Tickets expire after 2 hours (configurable)
# - Signature verified against shared secret
# - Realm determines authentication method:
#   - pam: Linux PAM authentication
#   - pve: Platform-specific authentication
#   - ldap: LDAP authentication
#   - openid: OpenID Connect

# Console access permissions:
# - VM.Audit: Read-only console access
# - VM.Console: Full console access
# - VM.PowerMgmt: Power management (required for some operations)

BGP (Border Gateway Protocol) is an exterior gateway routing protocol (RFC 4271) used to exchange routing information between autonomous systems (AS) on the internet. Unlike interior gateway protocols like OSPF or RIP, BGP is designed for routing between different organizations and networks.

• Autonomous System (AS): A collection of IP networks under a single administrative control, identified by a unique AS number (ASN)
• Path Vector Protocol: BGP maintains not just routes, but the entire path (AS path) to reach destinations
• TCP-based: Uses TCP port 179 for reliable communication between BGP peers
• Policy-based: Routes are selected and filtered based on configurable policies

BGP Session Establishment

BGP operates through sessions between routers (BGP speakers). The process involves:

1. TCP Connection: BGP peers establish a TCP connection on port 179
2. OPEN Message: Exchange BGP capabilities, AS numbers, and hold timers
3. UPDATE Messages: Exchange routing information (prefixes, attributes)
4. KEEPALIVE Messages: Maintain session (sent every 30 seconds by default)
5. NOTIFICATION Messages: Error handling and session termination

# BGP Message Types (RFC 4271)
# 1. OPEN - Initial session negotiation
# 2. UPDATE - Route advertisements/withdrawals
# 3. NOTIFICATION - Error messages
# 4. KEEPALIVE - Session maintenance

# BGP Finite State Machine:
# Idle → Connect → Active → OpenSent → OpenConfirm → Established

# Session States:
# - Idle: Initial state, no connection
# - Connect: TCP connection attempt
# - Active: TCP connection failed, retrying
# - OpenSent: OPEN message sent, waiting for response
# - OpenConfirm: OPEN message received, waiting for KEEPALIVE
# - Established: Session active, exchanging routes

BGP Route Selection Process

When multiple paths exist to a destination, BGP uses a decision process to select the best route:

1. Valid Next-Hop: Next-hop must be reachable
2. Highest Local Preference: Administrative preference (default: 100)
3. Shortest AS Path: Fewer AS hops preferred
4. Lowest Origin Type: IGP < EGP < Incomplete
5. Lowest MED (Multi-Exit Discriminator): Prefer lower MED values
6. eBGP over iBGP: External routes preferred over internal
7. Lowest IGP Metric: Shortest path to BGP next-hop
8. Oldest Route: Prefer route received first
9. Lowest Router ID: Tie-breaker using BGP router ID
10. Shortest Cluster List: For route reflectors
11. Lowest Neighbor Address: Final tie-breaker

# BGP Attributes (Path Attributes):
# - AS_PATH: List of AS numbers traversed
# - NEXT_HOP: IP address of next router
# - ORIGIN: Route origin (IGP, EGP, Incomplete)
# - LOCAL_PREF: Local preference (iBGP only)
# - MED: Multi-Exit Discriminator
# - COMMUNITY: Route tagging for policy
# - ORIGINATOR_ID: Route reflector originator
# - CLUSTER_LIST: Route reflector cluster IDs

BGP Route Types

BIRD (BIRD Internet Routing Daemon) is a full-featured routing daemon that supports BGP, OSPF, RIP, and other routing protocols. BIRD2 is the current version, with improved IPv6 support and better performance.

Installation

# Debian/Ubuntu
sudo apt update
sudo apt install bird2

# CentOS/RHEL/Fedora
sudo dnf install bird2
# or
sudo yum install bird2

# Arch Linux
sudo pacman -S bird2

# Verify installation
birdc -v
# Should show: BIRD 2.x.x

Basic BIRD2 Configuration

BIRD2 uses a single configuration file: /etc/bird/bird.conf

# /etc/bird/bird.conf
# Basic BIRD2 configuration

# Router ID (unique identifier, typically an IP address)
router id 192.168.1.1;

# Protocol kernel - sync routes with Linux kernel
protocol kernel {
    ipv4 {
        import all;
        export all;
    };
    learn;              # Learn routes from kernel
    scan time 10;       # Scan kernel routing table every 10 seconds
}

# Protocol device - scan network interfaces
protocol device {
    scan time 10;       # Scan interfaces every 10 seconds
}

# Static routes (optional)
protocol static {
    ipv4;
    route 10.0.0.0/8 via 192.168.1.254;
}

# BGP protocol definition
protocol bgp peer1 {
    description "BGP peer to AS 65001";
    local as 65000;                    # Your AS number
    neighbor 192.168.1.100 as 65001;   # Peer IP and AS
    
    # IPv4 configuration
    ipv4 {
        import filter {
            # Accept all routes by default
            accept;
        };
        export filter {
            # Export all routes
            accept;
        };
    };
    
    # Connection settings
    connect retry time 30;    # Retry connection every 30 seconds
    hold time 90;             # Hold timer (seconds)
    keepalive time 30;         # Keepalive interval (seconds)
    
    # Authentication (optional)
    password "your-secure-password";
    
    # Graceful restart (optional)
    graceful restart;
}

Note: Replace AS numbers, IP addresses, and passwords with your actual values. AS numbers must be obtained from your Regional Internet Registry (RIR).

Starting and Managing BIRD2

# Start BIRD2
sudo systemctl start bird
sudo systemctl enable bird  # Enable on boot

# Check status
sudo systemctl status bird

# View BIRD2 status
sudo birdc show status

# View BGP protocols
sudo birdc show protocols

# View BGP neighbors
sudo birdc show protocols all bgp1

# View routes
sudo birdc show route
sudo birdc show route for 192.168.1.0/24
sudo birdc show route protocol bgp1

# View route details
sudo birdc show route all

# Reload configuration
sudo birdc configure
# or restart service
sudo systemctl restart bird

# View BIRD2 logs
sudo journalctl -u bird -f

Route Filtering and Policy

BIRD2 allows sophisticated route filtering using filter functions:

# Define filter functions
filter bgp_import {
    # Reject default route
    if (net = 0.0.0.0/0) then reject;
    
    # Accept only /24 or smaller prefixes
    if (net.len > 24) then reject;
    
    # Reject RFC 1918 private addresses
    if (net ~ [10.0.0.0/8+, 172.16.0.0/12+, 192.168.0.0/16+]) then reject;
    
    # Set local preference for specific routes
    if (net ~ [203.0.113.0/24+]) then {
        bgp_local_pref = 200;
        accept;
    }
    
    # Accept all others
    accept;
}

filter bgp_export {
    # Only export our own prefixes
    if (source = RTS_STATIC) then accept;
    if (source = RTS_DEVICE) then accept;
    reject;
}

# Apply filters to BGP protocol
protocol bgp peer1 {
    local as 65000;
    neighbor 192.168.1.100 as 65001;
    
    ipv4 {
        import filter bgp_import;
        export filter bgp_export;
    };
}

BGP Communities

Communities allow tagging routes for policy control:

# Set communities on export
filter bgp_export_with_communities {
    if (source = RTS_STATIC) then {
        bgp_community.add((65000, 100));  # Add community (AS, value)
        accept;
    }
    reject;
}

# Filter based on communities on import
filter bgp_import_communities {
    # Reject routes with NO_EXPORT community
    if (bgp_community ~ [(65001, 65535)]) then reject;
    
    # Prefer routes with HIGH_PREF community
    if (bgp_community ~ [(65001, 200)]) then {
        bgp_local_pref = 150;
    }
    
    accept;
}

# Well-known communities:
# (0, 0) - Internet (no special meaning)
# (65535, 0) - NO_EXPORT - Don't export to eBGP peers
# (65535, 1) - NO_ADVERTISE - Don't advertise to any peer
# (65535, 2) - NO_EXPORT_SUBCONFED - Don't export outside confederation

Route Reflector Configuration

For large iBGP networks, use route reflectors to avoid full mesh:

# Route Reflector Server
protocol bgp rr_client1 {
    local as 65000;
    neighbor 192.168.1.10 as 65000;
    
    ipv4 {
        import all;
        export all;
    };
    
    # Enable route reflection
    rr client;  # This is a route reflector client
}

# Route Reflector Client
protocol bgp rr_server {
    local as 65000;
    neighbor 192.168.1.1 as 65000;  # Route reflector server
    
    ipv4 {
        import all;
        export all;
    };
    
    # No special configuration needed on client
}

IPv6 BGP (MP-BGP)

BIRD2 supports IPv6 through Multiprotocol BGP (MP-BGP):

protocol bgp peer1 {
    local as 65000;
    neighbor 2001:db8::1 as 65001;
    
    # IPv6 configuration
    ipv6 {
        import all;
        export all;
    };
    
    # Can also configure both IPv4 and IPv6
    ipv4 {
        import all;
        export all;
    };
    ipv6 {
        import all;
        export all;
    };
}

# Useful debugging commands
sudo birdc show protocols all    # Detailed protocol status
sudo birdc show route all         # All routes with attributes
sudo birdc show route filtered    # Filtered routes
sudo birdc show route rejected    # Rejected routes
sudo birdc show route count       # Route count statistics
sudo birdc show route protocol bgp1 all  # Routes from specific peer

# Enable debug logging
# Edit /etc/bird/bird.conf and add:
# log syslog { debug, trace, info, remote, warning, error, auth, fatal, bug };

# View detailed logs
sudo journalctl -u bird -f -n 100

• Use BGP passwords: Always configure MD5 authentication or TCP-AO for BGP sessions
• Route filtering: Implement strict import/export filters to prevent route hijacking
• Prefix limits: Set maximum prefix limits to prevent resource exhaustion
• RPKI validation: Use Resource Public Key Infrastructure to validate route origins
• BGP communities: Use communities for traffic engineering and policy enforcement
• Monitor sessions: Set up monitoring for BGP session state and route changes
• AS path filtering: Reject routes with unexpected AS paths

# Example secure BGP configuration
protocol bgp secure_peer {
    local as 65000;
    neighbor 192.168.1.100 as 65001;
    
    password "strong-random-password-here";
    
    # Prefix limits
    ipv4 {
        import limit 1000 action block;  # Max 1000 routes
        import filter strict_import;
        export filter strict_export;
    };
    
    # Connection security
    connect retry time 30;
    hold time 90;
    keepalive time 30;
    
    # Graceful restart
    graceful restart;
}

# Strict import filter
filter strict_import {
    # Reject default route
    if (net = 0.0.0.0/0) then reject;
    
    # Reject private addresses
    if (net ~ [10.0.0.0/8+, 172.16.0.0/12+, 192.168.0.0/16+]) then reject;
    
    # Reject too-specific prefixes
    if (net.len > 24) then reject;
    
    # Accept valid routes
    accept;
}