{"id":18311776,"url":"https://github.com/firezone/wireguardex","last_synced_at":"2025-03-27T00:13:19.925Z","repository":{"id":36990052,"uuid":"496322476","full_name":"firezone/wireguardex","owner":"firezone","description":"Configure WireGuard® interfaces in Elixir using Rust NIFs.","archived":false,"fork":false,"pushed_at":"2023-10-24T12:31:47.000Z","size":181,"stargazers_count":74,"open_issues_count":1,"forks_count":9,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-03-25T03:35:03.469Z","etag":null,"topics":["elixir","erlang","hexpm","nif","rust","wireguard"],"latest_commit_sha":null,"homepage":"https://hex.pm/packages/wireguardex","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firezone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null}},"created_at":"2022-05-25T17:09:01.000Z","updated_at":"2025-03-05T14:10:43.000Z","dependencies_parsed_at":"2023-01-17T12:01:45.391Z","dependency_job_id":"345d124e-9c19-4411-a559-1dc28ca63ba1","html_url":"https://github.com/firezone/wireguardex","commit_stats":{"total_commits":145,"total_committers":6,"mean_commits":"24.166666666666668","dds":0.4758620689655172,"last_synced_commit":"6023389704668b6abf69a93c6bf1925a657e1a95"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firezone%2Fwireguardex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firezone%2Fwireguardex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firezone%2Fwireguardex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firezone%2Fwireguardex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firezone","download_url":"https://codeload.github.com/firezone/wireguardex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245755679,"owners_count":20667027,"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","erlang","hexpm","nif","rust","wireguard"],"created_at":"2024-11-05T16:20:14.892Z","updated_at":"2025-03-27T00:13:19.905Z","avatar_url":"https://github.com/firezone.png","language":"Elixir","readme":"# Wireguardex\n\n## Overview\n\n[![hex.pm](https://img.shields.io/hexpm/v/wireguardex.svg)](https://hex.pm/packages/wireguardex)\n[![hex.pm](https://img.shields.io/hexpm/dt/wireguardex.svg)](https://hex.pm/packages/wireguardex)\n[![hex.pm](https://img.shields.io/hexpm/l/wireguardex.svg)](https://hex.pm/packages/wireguardex)\n\nWireguardex is an Elixir library for configuring [WireGuard®](https://www.wireguard.com/) interfaces.\n\nIt is exposed as a native library via NIFs implemented in [Rust](https://rust-lang.org) using the [rustler](https://crates.io/crates/rustler) and [wireguard-control](https://docs.rs/wireguard-control/latest/wireguard_control/) crates.\n\nUsed by [Firezone](https://github.com/firezone/firezone) to manage WireGuard interfaces in Elixir.\n\n## Getting started\n\nAdd `wireguardex` to your dependencies:\n\n```elixir\ndef deps do\n  [\n    {:wireguardex, \"~\u003e 0.3\"}\n  ]\nend\n```\n\nThen you can just use wireguardex to manage your wireguard interfaces:\n\n```elixir\n# Imports for cleanliness\nimport Wireguardex.DeviceConfigBuilder\nimport Wireguardex.PeerConfigBuilder\nimport Wireguardex, only: [set_device: 2]\n\ninterface_name = \"wg0\"\nprivate_key = Wireguardex.generate_private_key()\n{:ok, public_key} = Wireguardex.get_public_key(private_key)\nlisten_port = 58210\nfwmark = 1234\n\n:ok =\n  device_config() # \u003c-- Start configuring the devices\n  # Here we set configuration for the device\n  |\u003e private_key(private_key)\n  |\u003e public_key(public_key)\n  |\u003e listen_port(listen_port)\n  |\u003e fwmark(fwmark)\n  |\u003e set_device(interface_name) # \u003c-- This actually creates the interface\n```\n\nAfter creation you could also add peers:\n\n```elixir\n# Create a peer\npeer =\n  peer_config()\n  |\u003e public_key(public_key)\n  |\u003e preshared_key(Wireguardex.generate_preshared_key())\n  |\u003e endpoint(\"127.0.0.1:1234\")\n  |\u003e persistent_keepalive_interval(30)\n  |\u003e allowed_ips([\"255.0.0.0/24\", \"127.0.0.0/16\"])\n\n# Add peer to existing device\n:ok = Wireguardex.add_peer(interface_name, peer)\n```\n\nAnd easily remove it afterwards using its public key:\n\n```elixir\n:ok = Wireguardex.remove_peer(interface_name, public_key)\n```\n\nTo get information on an existing device:\n\n```elixir\n{:ok, device} = Wireguardex.get_device(interface_name)\n```\n\nFinally to delete a device:\n\n```elixir\n:ok = Wireguardex.delete_device(interface_name)\n```\n\n## Installation\n\nThe package can be installed by adding `wireguardex` to your list of dependencies\nin `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:wireguardex, \"~\u003e 0.3\"}\n  ]\nend\n```\n\nWireguardex will try to download a precompiled NIF library. If you want to compile\nyour own NIF, you'll need to have Rust installed. The common option is to use\n[Rustup](https://rustup.rs/).\n\nTo force compilation you can set the environment variable `WIREGUARDNIF_BUILD`\nto `true` or `1`. Or you can set the application env to force the NIF to compile:\n\n```elixir\nconfig :rustler_precompiled, :force_build, wireguardex: true\n```\n\n### Note about privileges\n\nThis library creates and modifies network interfaces. If you'd like to run this library as a non-root user, we recommend adding the `CAP_NET_ADMIN` Linux capability to the Erlang VM executable:\n\n```sh\nsudo setcap 'cap_net_admin+eip' \u003cerlang_installation_path\u003e/bin/beam.smp\n```\n\nIf you're using [asdf-vm](https://asdf-vm.com/) to manage dependencies you can do:\n\n```sh\nsudo setcap 'cap_net_admin+eip' $(ls -1 `asdf where erlang 24.3.4`/erts-*/bin/beam.smp)\n```\n\nThis can be handy for development and testing purposes.\n\n**Note**: This will also give `CAP_NET_ADMIN` to any other Erlang programs using this `beam.smp` executable. If this is undesired, consider using a dedicated Erlang installation or `beam.smp` executable for this library.\n\n## Features\n\n* Manage WireGuard interfaces\n* Doesn't require a WireGuard installation\n\n## Tests\n\nRunning the tests in this library will also require a Rust installation, as the NIF is compiled\nlocally before running the tests.\n\nFollow [these](https://www.rust-lang.org/learn/get-started) instructions to install Rust.\n\nThen you can run `mix test` as long as you have the [user privileges to create interfaces](#note-about-privileges).\n\n### Pre-commit\n\nWe use [pre-commit](https://pre-commit.com) to catch any static analysis issues before code is\ncommitted. Install with Homebrew: `brew install pre-commit` or pip: `pip install pre-commit`.\n\n## Acknowledgments\n\n\"WireGuard\" and the \"WireGuard\" logo are registered trademarks of Jason A. Donenfeld.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirezone%2Fwireguardex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirezone%2Fwireguardex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirezone%2Fwireguardex/lists"}