{"id":21836020,"url":"https://github.com/nocursor/mac-address","last_synced_at":"2025-04-14T09:23:05.134Z","repository":{"id":33444455,"uuid":"158468584","full_name":"nocursor/mac-address","owner":"nocursor","description":"Elixir library for working with MAC addresses.","archived":false,"fork":false,"pushed_at":"2022-01-28T15:18:27.000Z","size":9,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-27T22:43:11.334Z","etag":null,"topics":["elixir","elixir-lang","id-generation","mac-address"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nocursor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-21T00:29:38.000Z","updated_at":"2024-09-11T22:21:46.000Z","dependencies_parsed_at":"2022-08-07T21:16:47.232Z","dependency_job_id":null,"html_url":"https://github.com/nocursor/mac-address","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nocursor%2Fmac-address","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nocursor%2Fmac-address/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nocursor%2Fmac-address/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nocursor%2Fmac-address/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nocursor","download_url":"https://codeload.github.com/nocursor/mac-address/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248541669,"owners_count":21121612,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","elixir-lang","id-generation","mac-address"],"created_at":"2024-11-27T20:32:03.896Z","updated_at":"2025-04-14T09:23:05.111Z","avatar_url":"https://github.com/nocursor.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"## MAC Address  \n  \n`MACAddress` provides common functions for working with [MAC addresses](https://en.wikipedia.org/wiki/MAC_address).\n\nIt is currently a work in progress, but you may find it immediately useful. The API, however, may be subject to change at this time.\n  \n`MACAddress` offers helper functions and generally makes working with MAC addresses easier in Elixir.\n  \nA major focus of this module is to support consumers of MAC addresses such as cryptographically secure ID generators, commonly found in distributed systems. It is currently being used to munge MAC addresses for use in custom ID generation to avoid leaking the real MAC address of each given machine to the public. It is also being used to parse and send data to/from pipes. This functionality was common across several libraries and applications, thus it is now its own library.\n\nThe general focus with regard to querying MAC addresses is to use the facilities provided by Erlang, and avoid custom scripts unless specifically called out. It is possible that OS command-versions may be available via other functions in the future to augment anything that might be lacking from Erlang and Elixir. For security reasons, this library tempts to avoid this approach that many other libraries take by default (often out of necessity).\n \n## Usage\n\nThe API focuses on MAC addresses and providing Elixir-centric, pragmatic representations and to save boiler-plate. \n\nGet a list of all MAC addresses:\n\n```elixir\nMACAddress.mac_addresses()\n{:ok,\n [\n   {\"bridge0\", \u003c\u003c114, 0, 7, 196, 62, 91\u003e\u003e},\n   {\"en2\", \u003c\u003c114, 0, 4, 171, 64, 91\u003e\u003e},\n   {\"en1\", \u003c\u003c114, 0, 11, 176, 69, 96\u003e\u003e},\n   {\"awdl0\", \u003c\u003c158, 82, 242, 191, 187, 141\u003e\u003e},\n   {\"p2p0\", \u003c\u003c14, 64, 8, 144, 42, 70\u003e\u003e},\n   {\"en0\", \u003c\u003c108, 64, 8, 144, 42, 71\u003e\u003e}\n ]}\n```\n\nGet the MAC address of a specific interface:\n\n```elixir\n MACAddress.mac_address(\"en1\")\n{:ok, \u003c\u003c114, 0, 11, 176, 69, 96\u003e\u003e}\n\n# or exception flavored\nMACAddress.mac_address!(\"en2\")\n\u003c\u003c114, 0, 4, 171, 64, 91\u003e\u003e\n```\n\nSometimes we want to munge our MAC address for public usage. After doing so, we typically would want to store it if we need it again. We might do this in a config, GenServer, Process, Agent, database, or ETS table as a new one will be generated each time.\n\nHere's how we do it:\n\n```elixir\nMACAddress.munge_address(\u003c\u003c114, 0, 4, 171, 64, 91\u003e\u003e)  \n\u003c\u003c248, 234, 234, 252, 80, 101\u003e\u003e\n\n# we can also generate a munged address\n# by default, it will grab the first mac address available, but if there are none, it generates one\nMACAddress.munge_address()                             \n\u003c\u003c27, 110, 236, 180, 44, 34\u003e\u003e\n\n# we can also generate an address with the broadcast bits masked for us\nMACAddress.broadcast_address()\n\u003c\u003c225, 67, 238, 114, 151, 27\u003e\u003e\n```\n\nConvert a MAC address from a hex string, as often found in utilities such as ifconfig:\n\n```elixir\n# by default it will parse `:` or `-`\n MACAddress.from_hex(\"72:00:0b:b0:45:60\")      \n{:ok, \u003c\u003c114, 0, 11, 176, 69, 96\u003e\u003e}\n\n# exception flavor\nMACAddress.from_hex!(\"69:00:0c:b1:45:60\")       \n\u003c\u003c105, 0, 12, 177, 69, 96\u003e\u003e\n\n# we can also control the separators to parse\nMACAddress.from_hex!(\"69\u002600\u00260C\u0026B1\u002645\u002660\", separators: [\"\u0026\"])\n\u003c\u003c105, 0, 12, 177, 69, 96\u003e\u003e\n\n# we can even have multiple separators if we have some weird format\nMACAddress.from_hex!(\"69-00-0C\u0026B1\u002645\u002660\", separators: [\"\u0026\", \"-\"])\n\u003c\u003c105, 0, 12, 177, 69, 96\u003e\u003e\n```\n\nFormat an Elixir binary MAC address in our familiar hex format:\n\n```elixir\nMACAddress.to_hex(\u003c\u003c114, 0, 11, 176, 69, 96\u003e\u003e)\n\"72:00:0b:b0:45:60\"\n\n# we can control the case\nMACAddress.to_hex(\u003c\u003c114, 0, 11, 176, 69, 96\u003e\u003e, case: :upper)\n\"72:00:0B:B0:45:60\"\n\n# we can control the separator too\nMACAddress.to_hex(\u003c\u003c114, 0, 11, 176, 69, 96\u003e\u003e, case: :upper, separator: \"-\")\n\"72-00-0B-B0-45-60\"\n```\n\nUsage will expand with real-world requirements.\n\n## Installation\n\n`MACAddress` is available via [Hex](https://hex.pm/packages/mac_address). The package can be installed\nby adding `mac_address` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:mac_address, \"~\u003e 0.0.0.1\"}\n  ]\nend\n```\n\nThe API docs can be found at [https://hexdocs.pm/mac_address](https://hexdocs.pm/mac_address).\n\n## Limitations\n\nWorking with MAC addresses in Elixir is typically done through the `:inet` module. As such, any limitations that exist in `:inet` are typically true here as well. Most notably, this includes situations where querying addresses requires super user privileges, such as has been observed on Solaris.\n\nIf you need more complex MAC address parsing or vendor identification, a number of packages exist for this purpose. The goal of this library is not to support every known MAC address format, such as those found in applications such as WireShark. Rather, this library is focused on the formats that appear within Elixir and Erlang internally and in major real-world usage.\n\n## Issues/Features\n\nIf you have any feature requests, suggestions, or issues, please leave feedback in the issue tracker. I welcome contributions and changes.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnocursor%2Fmac-address","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnocursor%2Fmac-address","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnocursor%2Fmac-address/lists"}