Network Interface Monitoring

Is your feature request related to a problem?

Yes, the current Unraid GraphQL API lacks comprehensive network interface monitoring capabilities, which severely limits integration with home automation platforms, monitoring tools, and network management systems. Currently, the API only provides basic network access URLs for connectivity, but no actual network interface data, statistics, or monitoring information.

This creates several problems:

• Monitoring platforms cannot track network performance of Unraid servers
• No visibility into network interface status (up/down, link speed, errors)
• Missing bandwidth utilization tracking for capacity planning and alerting
• No network-based automation triggers for failover scenarios or performance alerts
• Limited troubleshooting capabilities when network issues occur
• Inconsistent monitoring experience compared to other system metrics (CPU, memory, disk) that are well-supported in the API
• Integration challenges with enterprise monitoring solutions and automation platforms

Describe the solution you'd like

Add comprehensive network interface monitoring to the Unraid GraphQL API with the following capabilities:

Core Network Interface Data

• Interface enumeration with names, types, and hardware addresses
• Interface status monitoring (up/down, operational state, link speed, duplex mode)
• Network configuration details (IP addresses, subnet masks, MTU, VLAN tags)
• Physical interface properties (MAC addresses, interface types, carrier status)

Network Statistics & Performance Metrics

• Real-time bandwidth utilization (bytes/packets in/out, current rates)
• Historical network statistics with configurable time windows
• Network error tracking (dropped packets, collisions, CRC errors)
• Interface performance metrics (utilization percentages, peak usage)

Advanced Network Features

• Bonding/teaming interface support with member status and load balancing info
• VLAN interface monitoring with VLAN ID and parent interface relationships
• Bridge interface details for Docker and VM networking
• Network namespace awareness for containerized applications

Proposed GraphQL Schema Extension

type Query {
  networkInterfaces: [NetworkInterface!]!
  networkInterface(name: String!): NetworkInterface
  networkStatistics(interface: String, timeRange: TimeRange): NetworkStats
}

type NetworkInterface {
  id: ID!
  name: String!
  displayName: String
  type: InterfaceType!
  operationalState: OperationalState!
  administrativeState: AdministrativeState!
  
  # Physical properties
  macAddress: String
  mtu: Int!
  speed: Int # Mbps
  duplex: DuplexMode
  carrierDetected: Boolean!
  
  # Network configuration
  ipv4Addresses: [IPAddress!]!
  ipv6Addresses: [IPAddress!]!
  defaultGateway: String
  dnsServers: [String!]!
  
  # VLAN support
  vlanId: Int
  parentInterface: String
  
  # Bonding/teaming
  bondingMode: BondingMode
  bondMembers: [NetworkInterface!]!
  bondPrimary: String
  
  # Real-time statistics
  statistics: NetworkInterfaceStats!
  
  # Historical data
  historicalStats(timeRange: TimeRange!): [NetworkStatsPoint!]!
}

type NetworkInterfaceStats {
  bytesReceived: BigInt!
  bytesSent: BigInt!
  packetsReceived: BigInt!
  packetsSent: BigInt!
  
  # Error counters
  receiveErrors: BigInt!
  transmitErrors: BigInt!
  receiveDropped: BigInt!
  transmitDropped: BigInt!
  collisions: BigInt!
  
  # Current rates (per second)
  receiveRate: Float! # bytes/sec
  transmitRate: Float! # bytes/sec
  packetReceiveRate: Float! # packets/sec
  packetTransmitRate: Float! # packets/sec
  
  # Utilization (percentage of interface capacity)
  utilizationPercent: Float!
  
  lastUpdated: DateTime!
}

enum InterfaceType {
  ETHERNET
  WIRELESS
  LOOPBACK
  BOND
  BRIDGE
  VLAN
  TUN_TAP
  DOCKER
  OTHER
}

enum OperationalState {
  UP
  DOWN
  TESTING
  UNKNOWN
  DORMANT
  NOT_PRESENT
  LOWER_LAYER_DOWN
}

enum AdministrativeState {
  UP
  DOWN
}

enum DuplexMode {
  FULL
  HALF
  UNKNOWN
}

enum BondingMode {
  ROUND_ROBIN
  ACTIVE_BACKUP
  XOR
  BROADCAST
  LACP
  BALANCE_TLB
  BALANCE_ALB
}

Additional context

Implementation Considerations

The Unraid codebase already includes foundational components that can be leveraged:

• systeminformation library for system monitoring (currently used for CPU, memory, disk metrics)
• Comprehensive Network model in api/src/unraid-api/graph/resolvers/info/info.model.ts (currently unused but contains relevant interface fields)
• Established GraphQL infrastructure ready for extension
• Existing authentication and authorization mechanisms

Suggested Implementation Approach

1. Leverage existing systeminformation functions: networkInterfaces(), networkStats(), networkConnections()
2. Create NetworkInterfaceService for data collection, caching, and rate calculations
3. Implement GraphQL resolvers using the existing unused Network model as foundation
4. Add real-time subscriptions for live monitoring capabilities
5. Include historical data collection with configurable retention policies
6. Implement efficient caching to minimize system impact during frequent queries

Use Cases and Benefits

• Enterprise monitoring integration with tools like Grafana, Prometheus
• Automated alerting systems when interfaces go down or utilization exceeds thresholds
• Capacity planning and analysis with historical bandwidth usage data
• Network troubleshooting and diagnostics with comprehensive error rate monitoring
• Load balancing optimization for bonded interfaces in high-availability setups
• Security monitoring for detecting unusual traffic patterns or potential intrusions
• Infrastructure automation for dynamic network configuration and failover scenarios
• Performance optimization through real-time utilization monitoring and bottleneck identification

Technical Benefits

• Consistent API experience with other Unraid system monitoring capabilities
• Reduced polling overhead through GraphQL's efficient query mechanisms
• Standardized data formats for easier integration across different platforms
• Real-time capabilities through GraphQL subscriptions
• Comprehensive coverage of all network interface types (physical, virtual, bonded, VLAN)

Community Impact

This feature would significantly enhance Unraid's appeal for:

• Enterprise and prosumer users requiring comprehensive network monitoring
• Automation enthusiasts building sophisticated monitoring and alerting systems
• System administrators managing multiple Unraid servers
• Integration developers building tools and platforms that work with Unraid
• Network engineers requiring detailed interface statistics and performance data

Environment (if relevant)

Unraid OS Version: 7.1.4

Pre-submission Checklist

• I have searched existing issues to ensure this feature hasn't already been requested
• This is not an Unraid Connect related feature (if it is, please submit via the support form instead)
• I have provided clear examples or use cases for the feature

Start with api/src/unraid-api/graph/resolvers/info/info.model.ts and the existing systeminformation entry points: networkInterfaces(), networkStats(), and networkConnections(). Trace the established GraphQL infrastructure before assessing how interface data, statistics, bonding/VLAN details, and historical metrics fit together. Done means the requested network monitoring capabilities are exposed through a coherent, usable GraphQL API.