# `Hyper.Node.Users`
[🔗](https://github.com/harmont-dev/hyper/blob/main/lib/hyper/node/users.ex#L1)

Process running on the `Hyper.Node` responsible for creating and managing POSIX users.

The reason we need this is that Firecracker prefers that each new virtual machine we create is
managed with a unique user. Each said user needs access to /dev/kvm.

To solve this problem, `Hyper.Node.Users` mints user ids under the configured group.

# `id`

```elixir
@type id() :: integer()
```

A uid/gid.

# `bind`

```elixir
@spec bind(id(), pid()) :: :ok
```

Free `id` automatically when `owner` dies.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `claim`

```elixir
@spec claim() :: {:ok, id()} | {:error, :exhausted}
```

Allocate an id without auto-freeing. Pair with `release/1` or `bind/2`.

# `release`

```elixir
@spec release(id()) :: :ok
```

Return an id to the pool.

# `test_system`

```elixir
@spec test_system() :: :ok | {:error, term()}
```

Verify the configured uid/gid range is free, raising if anything occupies it.

Run at node startup so we fail closed: handing out a uid that collides with an
existing user would let a VM run as that user - a security hazard. Checks NSS
users and groups (via `getent`) and the subordinate-id ranges in `/etc/subuid`
and `/etc/subgid` for overlap with the configured range.

# `with_id`

```elixir
@spec with_id((id() -> result)) :: result | {:error, :exhausted} when result: var
```

Run the given callable with a new UID, freeing it afterward.

---

*Consult [api-reference.md](api-reference.md) for complete listing*