0
# Network Interface Operations
1

2
Functions for querying local network interfaces and retrieving IP addresses from the system with support for interface-specific queries and address family filtering.
3

4
## Capabilities
5

6
### Network Interface Queries
7

8
#### address
9

10
Retrieves IP addresses from local network interfaces with flexible filtering options for interface names and address families.
11

12
```javascript { .api }
13
/**
14
 * Gets IP address from network interface
15
 * @param {string} [name] - Interface name, 'public', 'private', or undefined
16
 * @param {string|number} [family] - 'ipv4', 'ipv6', 4, 6, or undefined (defaults to 'ipv4')
17
 * @returns {string|undefined} IP address string or undefined if not found
18
 */
19
function address(name, family);
20
```
21

22
**Parameter Behavior:**
23
- `name`: 
24
  - `undefined`: Returns first IPv4 address or loopback if none found
25
  - `'public'`: Returns first public (non-private) IP address
26
  - `'private'`: Returns first private IP address  
27
  - Interface name (e.g., 'eth0', 'wlan0'): Returns first address from specified interface
28
- `family`: Address family filter ('ipv4', 'ipv6', 4, 6, or undefined for IPv4)
29

30
**Usage Examples:**
31

32
```javascript
33
const ip = require('ip');
34

35
// Get default IP address (first IPv4 or loopback)
36
console.log(ip.address()); // e.g., '192.168.1.100'
37

38
// Get first public IP address
39
console.log(ip.address('public')); // e.g., '203.0.113.10'
40
console.log(ip.address('public', 'ipv4')); // e.g., '203.0.113.10'
41
console.log(ip.address('public', 'ipv6')); // e.g., '2001:db8::1'
42

43
// Get first private IP address
44
console.log(ip.address('private')); // e.g., '192.168.1.100'
45
console.log(ip.address('private', 'ipv6')); // e.g., 'fe80::1'
46

47
// Get address from specific interface
48
console.log(ip.address('eth0')); // e.g., '192.168.1.100'
49
console.log(ip.address('eth0', 'ipv6')); // e.g., 'fe80::a1b2:c3d4:e5f6'
50
console.log(ip.address('wlan0', 'ipv4')); // e.g., '192.168.0.50'
51

52
// Using numeric family identifiers
53
console.log(ip.address('public', 4)); // IPv4 public address
54
console.log(ip.address('private', 6)); // IPv6 private address
55

56
// Returns undefined if no matching address found
57
console.log(ip.address('nonexistent-interface')); // undefined
58
console.log(ip.address('public', 'ipv6')); // undefined (if no public IPv6)
59
```
60

61
### Loopback Address Generation
62

63
#### loopback
64

65
Returns the standard loopback address for the specified address family.
66

67
```javascript { .api }
68
/**
69
 * Returns loopback address for specified family
70
 * @param {string|number} [family] - 'ipv4', 'ipv6', 4, 6, or undefined (defaults to 'ipv4')
71
 * @returns {string} Loopback address string
72
 * @throws {Error} Throws error if family is not 'ipv4' or 'ipv6'
73
 */
74
function loopback(family);
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
const ip = require('ip');
81

82
// Default (IPv4) loopback
83
console.log(ip.loopback()); // '127.0.0.1'
84
console.log(ip.loopback('ipv4')); // '127.0.0.1'
85
console.log(ip.loopback(4)); // '127.0.0.1'
86

87
// IPv6 loopback
88
console.log(ip.loopback('ipv6')); // 'fe80::1'
89
console.log(ip.loopback(6)); // 'fe80::1'
90

91
// Case-insensitive family names
92
console.log(ip.loopback('IPV4')); // '127.0.0.1'
93
console.log(ip.loopback('IPv6')); // 'fe80::1'
94

95
// Error for invalid family
96
try {
97
  ip.loopback('invalid');
98
} catch (error) {
99
  console.log(error.message); // 'family must be ipv4 or ipv6'
100
}
101
```
102

103
## Practical Usage Patterns
104

105
### Server Binding and Configuration
106

107
```javascript
108
const ip = require('ip');
109
const http = require('http');
110

111
// Bind server to first available private IP
112
const privateIp = ip.address('private');
113
const server = http.createServer();
114

115
if (privateIp) {
116
  server.listen(3000, privateIp, () => {
117
    console.log(`Server running on http://${privateIp}:3000`);
118
  });
119
} else {
120
  // Fallback to loopback
121
  const loopback = ip.loopback();
122
  server.listen(3000, loopback, () => {
123
    console.log(`Server running on http://${loopback}:3000`);
124
  });
125
}
126
```
127

128
### Network Interface Discovery
129

130
```javascript
131
const ip = require('ip');
132
const os = require('os');
133

134
function discoverNetworkInterfaces() {
135
  const interfaces = os.networkInterfaces();
136
  const results = {};
137
  
138
  for (const interfaceName of Object.keys(interfaces)) {
139
    results[interfaceName] = {
140
      ipv4: ip.address(interfaceName, 'ipv4'),
141
      ipv6: ip.address(interfaceName, 'ipv6')
142
    };
143
  }
144
  
145
  return results;
146
}
147

148
console.log(discoverNetworkInterfaces());
149
// {
150
//   eth0: { ipv4: '192.168.1.100', ipv6: 'fe80::a1b2:c3d4:e5f6' },
151
//   wlan0: { ipv4: '192.168.0.50', ipv6: undefined },
152
//   lo: { ipv4: '127.0.0.1', ipv6: '::1' }
153
// }
154
```
155

156
### Multi-homed Host Configuration
157

158
```javascript
159
const ip = require('ip');
160

161
function getNetworkConfiguration() {
162
  return {
163
    // Primary addresses
164
    primaryIPv4: ip.address(),
165
    primaryIPv6: ip.address(undefined, 'ipv6'),
166
    
167
    // Public addresses (for external communication)
168
    publicIPv4: ip.address('public', 'ipv4'),
169
    publicIPv6: ip.address('public', 'ipv6'),
170
    
171
    // Private addresses (for internal communication)
172
    privateIPv4: ip.address('private', 'ipv4'),
173
    privateIPv6: ip.address('private', 'ipv6'),
174
    
175
    // Loopback addresses (for local services)
176
    loopbackIPv4: ip.loopback('ipv4'),
177
    loopbackIPv6: ip.loopback('ipv6')
178
  };
179
}
180

181
console.log(getNetworkConfiguration());
182
```