macaddress

What is macaddress?

The macaddress npm package is a utility for retrieving and working with MAC addresses in Node.js. It provides functionalities to get the MAC address of a network interface, retrieve all MAC addresses on the system, and even spoof MAC addresses.

What are macaddress's main functionalities?

Get MAC address of a specific network interface

This feature allows you to get the MAC address of a specific network interface, such as 'eth0'. The callback function returns the MAC address as a string.

const macaddress = require('macaddress');
macaddress.one('eth0', function (err, mac) {
  console.log(mac); // 'XX:XX:XX:XX:XX:XX'
});

Get all MAC addresses on the system

This feature retrieves all MAC addresses on the system. The callback function returns an object where each key is a network interface and the value is the corresponding MAC address.

const macaddress = require('macaddress');
macaddress.all(function (err, all) {
  console.log(all); // { 'eth0': 'XX:XX:XX:XX:XX:XX', 'eth1': 'YY:YY:YY:YY:YY:YY', ... }
});

Spoof a MAC address

This feature allows you to generate a random MAC address, which can be useful for testing or spoofing purposes. The callback function returns the generated MAC address as a string.

const macaddress = require('macaddress');
macaddress.random(function (err, mac) {
  console.log(mac); // 'ZZ:ZZ:ZZ:ZZ:ZZ:ZZ'
});

Other packages similar to macaddress

node-macaddress

The node-macaddress package provides similar functionalities to macaddress, such as retrieving MAC addresses of network interfaces. However, it may have a different API and additional features like support for more platforms.

network-address

The network-address package focuses on retrieving network addresses, including MAC addresses and IP addresses. It provides a more comprehensive set of tools for network-related information compared to macaddress.

README

node-macaddress

Retrieve MAC addresses in Linux, OS X, and Windows.

A common misconception about MAC addresses is that every host had one MAC address, while a host may have multiple MAC addresses – since every network interface may have its own MAC address.

This library allows to discover the MAC address per network interface and chooses an appropriate interface if all you're interested in is one MAC address identifying the host system (see API + Examples below).

A common misconception about this library is that it reports the mac address of the client that accesses some kind of backend. It does not. Reporting the mac address is not in any way similar to reporting the IP address of the client that accesses your application. This library reports the mac address of the server the application is running on. This useful for example for distributed/scaled applications, for example when generating UUIDs.

Also it seems to be worth noting that this library is not intended to be used in a browser. There is no web api reporting the mac address of the machine (and that is a good thing).

Features:

• works on Linux, Mac OS X, Windows, and on most UNIX systems.
• node ≥ 0.12 and io.js report MAC addresses in os.networkInterfaces() this library utilizes this information when available.
• also features a sane replacement for os.networkInterfaces() (see API + Examples below).
• works with stoneage node versions ≥ v0.8 (...)
• Promise support

Usage

npm install --save macaddress

var macaddress = require('macaddress');

API + Examples

(async)  .one(iface, callback) → string
(async)  .one(iface)           → Promise<string>
(async)  .one(callback)        → string
(async)  .all()                → Promise<{ iface: { type: address } }>
(async)  .all(callback)        → { iface: { type: address } }
(sync)   .networkInterfaces()  → { iface: { type: address } }

---

.one([iface], callback)

Retrieves the MAC address of the given iface.

If iface is omitted, this function automatically chooses an appropriate device (e.g. eth0 in Linux, en0 in OS X, etc.).

Without iface parameter:

macaddress.one(function (err, mac) {
  console.log("Mac address for this host: %s", mac);  
});

or using Promise

macaddress.one().then(function (mac) {
  console.log("Mac address for this host: %s", mac);  
});

→ Mac address for this host: ab:42:de:13:ef:37

With iface parameter:

macaddress.one('awdl0', function (err, mac) {
  console.log("Mac address for awdl0: %s", mac);  
});

or using Promise

macaddress.one('awdl0').then(function (mac) {
  console.log("Mac address for awdl0: %s", mac);  
});

→ Mac address for awdl0: ab:cd:ef:34:12:56

---

.all(callback)

Retrieves the MAC addresses for all non-internal interfaces.

macaddress.all(function (err, all) {
  console.log(JSON.stringify(all, null, 2));
});

or using Promise

macaddress.all().then(function (all) {
  console.log(JSON.stringify(all, null, 2));
});

{
  "en0": {
    "ipv6": "fe80::cae0:ebff:fe14:1da9",
    "ipv4": "192.168.178.20",
    "mac": "ab:42:de:13:ef:37"
  },
  "awdl0": {
    "ipv6": "fe80::58b9:daff:fea9:23a9",
    "mac": "ab:cd:ef:34:12:56"
  }
}

---

.networkInterfaces()

A useful replacement of os.networkInterfaces(). Reports only non-internal interfaces.

console.log(JSON.stringify(macaddress.networkInterfaces(), null, 2));

{
  "en0": {
    "ipv6": "fe80::cae0:ebff:fe14:1dab",
    "ipv4": "192.168.178.22"
  },
  "awdl0": {
    "ipv6": "fe80::58b9:daff:fea9:23a9"
  }
}