C embed
Installation · Integration · Sockets · Messages · Provider · Embed
This console app embeds the URnetwork SDK in your own product on Windows, macOS and Linux, on the SDK's C ABI (urnetwork_). It obtains its installation's scoped client JWT from your backend, starts a local device with it, and shows the status and the data caps your backend set for the installation. The device carries only the app's own traffic: it is not a device VPN and it does not provide. What the app sends through it continues in the Sockets examples; the Messages examples run on a provider-capable device of their own (Next). It follows the embed contract and the Go reference.
Files
| File | Purpose |
|---|---|
| main.c | Commands, exit codes, stop signals, the SDK's logs and --licenses. |
| session.c | Device lifecycle on the C ABI: creation with the client JWT and instance ID, listeners, the best available destination, cap reads, status and handle release. |
| fetch.c | ur_, the token fetch to replace with your own sign-in, plus the cap read and the configuration, over a replaceable HTTP function. |
| http_curl.c | That HTTP function on libcurl. |
| status.c | Status rules, data fields, decimal byte amounts, reset and retry times, and the cap object. |
| state.c | The private installation state directory, with base64, UUID and JWT payload decoding. |
| json.c | A small JSON reader; the app needs no JSON library. |
| embed.h | Declarations shared by the files. |
| selftest.c, selftest_main.c | Credential-free self-test: ./embed --self-test, and make self-test without the SDK library or libcurl. |
| Makefile, CMakeLists.txt | Builds for Make and for CMake with the SDK package. |
| server/embed_server.c | The backend tool: provision, cap, usage, usage-all, remove and acl. |
Build and self-test
Use a C11 compiler, libcurl, and a native SDK build with urnet_ and urnet_: the first SDK release after sdk c638dfa8, or a local build of sdk main. Like the other C examples, the Makefile defaults use .. and .. (after make -C sdk/cgo package in an adjacent sdk checkout); for an installed package, pass its include and library directories. libcurl comes from pkg-config (Homebrew's curl on macOS, libcurl4-openssl-dev on Debian and Ubuntu). From c/embed on macOS or Linux:
make SDK_ INCLUDE= /absolute/ path/ to/ include SDK_ LIBDIR= /absolute/ path/ to/ lib
make self-test SDK_ INCLUDE= /absolute/ path/ to/ include
./embed --self-test
./embed --licenses > licenses.json
./embed --versionThe Makefile records SDK_LIBDIR as the run path. To ship the library beside the app on Linux, build with SDK_ and copy libURnetworkSdk.so next to embed. The CMake build uses the package's urnetwork:: target and CMake's CURL::, and registers the self-test with CTest:
cmake -S . -B build -DCMAKE_ PREFIX_ PATH= /absolute/ path/ to/ sdk-prefix
cmake --build build
ctest --test-dir build
./build/embed --self-testOn Windows, in PowerShell, with Visual Studio and libcurl from vcpkg:
vcpkg install curl:x64-windows
cmake -S . -B build -DCMAKE_ PREFIX_ PATH= C: \path\to\urnetwork-sdk -DCMAKE_ TOOLCHAIN_ FILE= C: \vcpkg\scripts\buildsystems\vcpkg. cmake
cmake --build build --config Release
ctest --test-dir build -C Release
.\build\Release\embed.exe --self-test
.\build\Release\embed.exe --licenses > licenses.json
.\build\Release\embed.exe --versionThe CMake build copies URnetworkSdk.dll beside embed.exe, and vcpkg's toolchain copies libcurl's DLL; keep both there.
--self-test needs no credentials and no network and creates no device. It checks the contract's byte, reset time, client limit and status line vectors and the order of the status rules; the data fields (checking, unavailable, a later failure keeping the last reading, the Embed-not-enabled refusal clearing it, no cap for a null limit); the cap object (null and absent limits, capped and capped_, an unknown reason, refused answers); the JWT client_id claim; the token fetch against a stand-in server (the request, saving client.jwt atomically, a mismatched client refused, and each answer mapped to its exit code); the cap read; the state files (private permissions, atomic replacement, instance-id created once, a symlink refused); the configuration errors; and the start line. make self-test and the CMake embed-self-test target run the same checks in a binary that links neither the SDK library nor libcurl. This example was built and its self-tests run on macOS arm64 against a local build of sdk main; the Linux and Windows builds were not run.
The backend tool in server is a POSIX command-line program on libcurl and json-c, like the integration allocator it extends:
cd server
make
./embed-server --self-testBackend: provision clients and set data caps
Only your backend holds the root credential. Use an API key in production: create one with POST /account/ (called with a network JWT); it authenticates as your network exactly like the network JWT and is just as powerful, so keep it in your secret store, never on an installation. To rotate it, create a new key, deploy it, then remove the old one with POST /account/; remove a leaked key at once (contract).
Your backend provisions one client per running installation: the platform keeps one connection per client, so two installations that share a client keep displacing each other. The key is user:, where the installation ID is the app's instance-id. Your apps can get their token from the Go token server, the reference backend they call over HTTP, or your backend can run this language's tool:
cd server
umask 077
mkdir -p /absolute/ path/ to/ private-service-state
export URNETWORK_ ROOT_ JWT= 'api-key-or-network-jwt-from-your-secret-store'
export URNETWORK_ CLIENT_ MAP= '/ absolute/ path/ to/ private-service-state/ embed-clients.json'
export URNETWORK_ DEFAULT_ ACL_ GROUP= isolated
KEY= 'user: alice: 22222222-2222-2222-2222-222222222222'
./embed-server provision "$KEY" /absolute/ path/ to/ private-service-state/ alice.jwt
./embed-server cap "$KEY" --monthly 10000000000
./embed-server usage "$KEY"
./embed-server usage-all
./embed-server acl "$KEY" default
./embed-server statusprovision reissues the key's client or provisions a new one, provisions again when the old client was deactivated after 30 days without connecting, writes the client JWT to the file you name with owner-only permissions, never prints it, and prints {"client_. Your backend delivers that token to the installation as its client.jwt. cap posts only the options you give: --monthly and --total take a byte count or null (clear the cap), and --reset-total starts a new running total. The monthly cap resets at 00:00 UTC on the first of the month; a cap of 0 pauses the installation. usage prints the key's cap object and usage-all prints every capped client of your network, one per line. New clients go into the ACL group that URNETWORK_ names: isolated when it is unset, so your users never see each other in your network's peer list, or default for an app that uses Messages. provision saves a new client's mapping with a pending_acl record, applies the group with POST /network/, and only then writes the client JWT; after a failure the record stays and the next provision applies the group. acl <key> default or acl <key> isolated moves a client later and prints {"client_. cap, usage, remove and acl exit 78 with no client is mapped for that key; run provision first for a key without a client, and a held map lock exits 1. On a server that predates a route the tool exits 1 with /network/, or <path> answered 404: the server predates the data-cap routes for the cap routes; set URNETWORK_ to provision on a server without ACL groups (contract). status prints your network's Embed state from GET /network/ as one line, embed enabled: yes | client limit: 5000 | active clients: 1234. Until the URnetwork team enables Embed for your network (an Embed plan), cap, usage, usage-all and acl exit 78 with embed not enabled: Embed isn't enabled for this network; see https://, and provision still writes the client JWT but keeps the default ACL group in pending_acl and prints embed not enabled: the client's defaults stay pending until Embed is enabled; see https:// on stderr; the next provision after Embed is enabled applies it (contract). Without the tool, the backend sends the requests itself:
API= https:// api. bringyour.com
curl -fsS -X POST "$API/ network/ auth-client" \
-H "Authorization: Bearer $URNETWORK_ROOT_JWT" -H 'Content-Type: application/json' \
--data '{"description": "embed client", "device_spec": "urnetwork-examples/ curl"}'
curl -fsS -X POST "$API/ network/ client-acl-group" \
-H "Authorization: Bearer $URNETWORK_ROOT_JWT" -H 'Content-Type: application/json' \
--data '{"client_id": "11111111-1111-1111-1111-111111111111", "acl_group": "isolated"}'
curl -fsS -X POST "$API/ network/ client-data-cap" \
-H "Authorization: Bearer $URNETWORK_ROOT_JWT" -H 'Content-Type: application/json' \
--data '{"client_id": "11111111-1111-1111-1111-111111111111", "monthly_byte_limit": 10000000000}'
curl -fsS "$API/ network/ client-data-cap?client_ id= 11111111-1111-1111-1111-111111111111" \
-H "Authorization: Bearer $URNETWORK_ROOT_JWT"To pause an installation, set a cap to 0 (./); set it back to resume. To remove one, ./ removes its client and its mapping; the installation loses access at its next connection, and your service must also refuse that user's sign-in, or the next sign-in provisions a new client.
A network can have 100 top-level clients by default: the active clients that are not provider installs, so each running installation counts until it is removed or deactivated after 30 days without connecting. Past the limit, provisioning is refused and the tool prints client limit reached: your network is at its client limit; see https:// with exit code 78. An Embed plan raises your network's limit: request one on the Services page.
Package
- The SDK runtime ships beside the app:
libURnetworkSdk.on macOS (the recorded run path, ordylib @executable_in a bundle),path libURnetworkSdk.soon Linux (build withSDK_),RPATH= '$$ORIGIN' URnetworkSdk.dllon Windows. The app also needs libcurl: the system's on macOS and Linux, and libcurl's DLL besideembed.exeon Windows. - License: the SDK and connect are under the Mozilla Public License 2.0, a file-level copyleft: your app's code can stay proprietary, and changes to the SDK's own files must be shared under the MPL. Publish the SDK's licenses and data attributions with your app:
./embed --licensesprints them as JSON fromurnet_for this operating system's app kind (get_ licenses apple,windowsorlinux), with no network. - In-app traffic only: the device routes only what the app sends through it, so the app needs no VPN entitlement. Your privacy policy and store disclosures must still say that the app routes some of its users' traffic through URnetwork; the SDK ships no Apple privacy manifest.
client.jwtlives in the private state directory below and is a bearer secret: never print, log or back it up. A production app may also encrypt it with the Keychain, DPAPI or the Secret Service.
Configure the installation
The app keeps its state in one private directory named by URNETWORK_: client.jwt, instance-id (created on first run) and the SDK's bounded logs/. With the token server, the app fetches its client JWT on every start:
# Linux; on macOS use "$HOME/ Library/ Application Support/urnetwork-embed"
umask 077
export URNETWORK_ EMBED_ STATE_ DIR= "$HOME/ .local/ state/ urnetwork-embed"
mkdir -p "$URNETWORK_ EMBED_ STATE_ DIR"
chmod 700 "$URNETWORK_ EMBED_ STATE_ DIR"
export URNETWORK_ TOKEN_ SERVER_ URL= 'http:// 127.0.0.1: 8790'
export URNETWORK_ DEMO_ SESSION= 'demo-session-token-from-the-token-server'# Windows: the profile directory keeps the files private to the user
$env: URNETWORK_ EMBED_ STATE_ DIR = "$env: LOCALAPPDATA\urnetwork-embed"
New-Item -ItemType Directory -Force -Path $env: URNETWORK_ EMBED_ STATE_ DIR | Out-Null
$env: URNETWORK_ TOKEN_ SERVER_ URL = 'http://127.0.0.1:8790'
$env: URNETWORK_ DEMO_ SESSION = 'demo-session-token-from-the-token-server'The token server URL is an HTTPS origin, or loopback HTTP (localhost, 127.0.0.1, [::1]) for local testing. Without a token server, leave both settings unset and write client.jwt with the backend tool: run ./embed once to create instance-id (it exits with code 78 because there is no client.jwt yet), then provision with that installation ID:
./server/embed-server provision "user:alice:$(cat "$URNETWORK_ EMBED_ STATE_ DIR/ instance-id")" "$URNETWORK_ EMBED_ STATE_ DIR/ client.jwt"URNETWORK_ (default https://) is where the app reads its caps. Never put the root credential on an installation.
Run
./embedOn Windows run .\embed.exe with URnetworkSdk.dll and libcurl's DLL beside it. The app prints its client and installation IDs, then a status line on stdout whenever a field changes, and at least once a minute:
embed client 11111111-1111-1111-1111-111111111111, installation 22222222-2222-2222-2222-222222222222
status: connecting | data this month: checking | data total: checking
status: connected | data this month: 1.2 GB of 5.0 GB | data total: no cap| Field | Meaning |
|---|---|
| status | connecting until the device has a provider for the app's traffic, then connected; client limit, retry at HH:MM UTC; paused while a cap your backend set is 0; data cap reached, resets YYYY-MM-DD HH:MM UTC for the monthly cap, or data cap reached for the running total. |
| data this month | checking until the first cap read, unavailable if it failed, no cap without a monthly cap, otherwise the bytes used of the cap in decimal units. While Embed isn't enabled for your network, the cap read answers Embed isn't enabled for this network. and both data fields read unavailable (contract). |
| data total | The same for the running-total cap. |
client limit means the platform disconnected this client because your network reached its plan's limit on concurrently connected clients; the SDK reconnects by itself at the time shown. At a data cap the device gets no new transfer contracts until the month rolls over at 00:00 UTC on the first, or your backend raises, clears or resets the cap; usage can pass a cap by up to the size of the contracts still open. The app reads its caps with its own client JWT at start, every 5 minutes and within 5 seconds of a contract change; a server without the cap routes shows unavailable.
SDK log lines also appear on stderr, and the full log is in logs/. Ctrl-C (or SIGTERM) stops the device and exits with code 0. Exit code 78 is a configuration or credential problem that a restart does not fix: missing or invalid state, a network JWT, a credential the server rejected, or a token server answer of 401 or 409. Exit code 1 is any other failure, including any other token server answer. The commands are run (the default), --self-test, --licenses and --version; any other argument is a usage error (78).
Next: traffic through the device
The embed example ends where the app's own traffic begins. The Sockets and Messages examples use the same identity from the state directory:
export URNETWORK_ CLIENT_ JWT= "$(cat "$URNETWORK_ EMBED_ STATE_ DIR/ client.jwt")"
export URNETWORK_ INSTANCE_ ID= "$(cat "$URNETWORK_ EMBED_ STATE_ DIR/ instance-id")"Run one program at a time with one identity. Sockets route TCP, UDP and HTTP clients through the device.
Messages exchange the URMS text and ACK protocol with other clients of your network, but not on the embed device, which does not provide. A Messages program starts its own provider-capable device for the installation, and that device provides to your network: your network's other clients can route traffic through the installation, so ask your users first. Messages also need the client in the default ACL group: provision with URNETWORK_, or move the client with the backend tool's acl <key> default. An isolated client, the examples' default, never appears in your network's peer list; a default client appears there while the network has 100 or fewer recently active top-level clients that are not isolated, and your app decides what of it to show.