# How CasaOS Handles Network Detection and IP Helper Utilities

> Discover how CasaOS uses built-in packages for network detection and IP helper utilities. It efficiently manages NAT types, IP validation, and external IP discovery.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: internals
- Published: 2026-06-28

---

**CasaOS provides network detection and IP helper utilities through two self-contained packages that detect NAT types using STUN servers and manage IPv4/IPv6 address validation, external IP discovery, and local interface enumeration.**

CasaOS is an open-source home server system developed by IceWhaleTech that requires robust network awareness to manage diverse home-network environments. The platform implements dedicated utility packages for network detection and IP address management in [`pkg/utils/network_detection.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/network_detection.go) and [`pkg/utils/ip_helper/ip.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/ip_helper/ip.go), enabling services to adapt to different NAT configurations while exposing accurate address information to users and downstream components.

## NAT Type Detection Implementation

CasaOS detects the NAT type of the host—such as Full Cone, Symmetric, or other classifications—through a lightweight wrapper around the third-party library `nat-type-identifier-go`.

### The GetNetWorkTypeDetection Function

In [`pkg/utils/network_detection.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/network_detection.go), the `GetNetWorkTypeDetection` function runs NAT detection asynchronously using goroutines and channels:

```go
func GetNetWorkTypeDetection(data chan string, url string) {
    result, err := natType.GetDeterminedNatType(true, 5, url)
    if err == nil { data <- result }
}

```

The function accepts a string channel and a STUN server URL (typically `stun.l.google.com:19302`). It calls `natType.GetDeterminedNatType` with three parameters: `true` to enable UDP probing, a **5-second timeout**, and the STUN-compatible service URL. The detected NAT type string is sent back to the caller via the supplied channel, allowing non-blocking integration with the main application flow.

## IP Helper Utilities

The [`pkg/utils/ip_helper/ip.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/ip_helper/ip.go) file provides a comprehensive toolkit for IPv4/IPv6 handling, external IP discovery, and local interface enumeration.

### IP Validation Functions

**`IsIPv4`** and **`IsIPv6`** perform simple string-based checks using colon count to determine the IP version. **`HasLocalIP`** validates whether an IP belongs to private RFC 1918 ranges (10/8, 172.16/12, 192.168/16) or the link‑local 169.254/16 range.

### External IP Discovery

To retrieve public addresses, CasaOS queries ipify.org endpoints through an internal `httper` wrapper:

- **`GetExternalIPV4`** queries `https://api.ipify.org`
- **`GetExternalIPV6`** queries `https://api6.ipify.org`

### Local Interface Enumeration

CasaOS provides several methods for gathering local network interface information:

- **`GetLoclIp`** (note the implementation spelling) iterates over `net.InterfaceAddrs` to return the first non-loopback IPv4 address
- **`GetDeviceAllIP(port)`** returns every interface address (IPv4 or IPv6) with an optional port suffix
- **`GetDeviceAllIPv4`** returns a `map[string]string` mapping interface names to IPv4 addresses (e.g., `{"eth0": "192.168.1.42"}`) for all up, non-loopback interfaces

## Integration with Core Services

The system service layer utilizes these utilities to expose host network information to the UI and API. In [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go), the IP helper is employed to collect IPv4 interfaces:

```go
allIpv4 := ip_helper.GetDeviceAllIPv4()
// `allIpv4` is map[string]string { "eth0": "192.168.1.42", … }

```

This map is marshaled into JSON for downstream consumers, enabling the dashboard to display accurate local network endpoints and allowing peer discovery services to bind to appropriate addresses.

## Practical Implementation Examples

### Detecting NAT Type on Startup

```go
func startNetworkDetection() {
    natChan := make(chan string, 1)
    // Use a public STUN server (Google's) as the detection endpoint.
    go utils.GetNetWorkTypeDetection(natChan, "stun.l.google.com:19302")

    select {
    case nat := <-natChan:
        fmt.Printf("Detected NAT type: %s\n", nat)
    case <-time.After(6 * time.Second):
        fmt.Println("NAT detection timed out")
    }
}

```

### Fetching External IP Addresses

```go
func printExternalIPs() {
    fmt.Println("Public IPv4:", ip_helper.GetExternalIPV4())
    fmt.Println("Public IPv6:", ip_helper.GetExternalIPV6())
}

```

### Listing Local IPv4 Interfaces

```go
func listLocalIPv4() {
    ips := ip_helper.GetDeviceAllIPv4()
    for iface, addr := range ips {
        fmt.Printf("%s → %s\n", iface, addr)
    }
}

```

### Verifying Private Network Status

```go
func checkLocal(ipStr string) {
    ip := net.ParseIP(ipStr)
    if ip_helper.HasLocalIP(ip) {
        fmt.Println(ipStr, "is a private/local address")
    } else {
        fmt.Println(ipStr, "is public")
    }
}

```

## Summary

- **NAT Detection**: CasaOS uses `GetNetWorkTypeDetection` in [`pkg/utils/network_detection.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/network_detection.go) to identify NAT traversal characteristics via the `nat-type-identifier-go` library, essential for services like ZeroTier that require knowledge of symmetric vs. full-cone NAT configurations.
- **IP Management**: The `ip_helper` package provides `GetExternalIPV4`, `GetExternalIPV6`, `GetDeviceAllIPv4`, and `HasLocalIP` for comprehensive address handling, supporting both public IP discovery and local interface enumeration.
- **Service Integration**: Core services in [`service/system.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go) consume these utilities to expose reliable network information through the system API, mapping interface names to IPv4 addresses for UI display and service binding.

## Frequently Asked Questions

### What NAT types can CasaOS detect?

CasaOS can detect standard NAT classifications including Full Cone, Restricted Cone, Port Restricted Cone, and Symmetric NAT. The detection relies on the `nat-type-identifier-go` library, which performs STUN-based probing against a configured server (such as `stun.l.google.com:19302`) with a 5-second timeout.

### How does CasaOS determine external IP addresses?

CasaOS queries `https://api.ipify.org` for IPv4 and `https://api6.ipify.org` for IPv6 through the `GetExternalIPV4` and `GetExternalIPV6` functions in [`pkg/utils/ip_helper/ip.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/pkg/utils/ip_helper/ip.go). These functions utilize an internal `httper` wrapper to perform HTTP GET requests and return the public IP as a string.

### What is the difference between GetLoclIp and GetDeviceAllIPv4?

`GetLoclIp` (as implemented in the source) returns the first non-loopback IPv4 address found on the system, providing a single default local address. In contrast, `GetDeviceAllIPv4` returns a complete map of all network interface names to their IPv4 addresses, enabling applications to see all available local endpoints rather than just the primary one.

### How does CasaOS validate whether an IP address is local or private?

The `HasLocalIP` function checks if an IP falls within private RFC 1918 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) or the link-local range 169.254.0.0/16. This validation allows CasaOS to distinguish between public internet addresses and local network addresses for security and routing decisions.