# Devices

> Octelium documentation. Canonical page: <https://octelium.com/docs/octelium/latest/management/core/device>.

A *Device* is a representation by the *Cluster* of a *User*'s machine. A *Device* can be optionally registered/enrolled or re-registered by a logged-in *User* via the command `octelium auth device register` or simply `octelium auth dev`. However, it's up to access control to allow or deny a *User* based on their *Device* information (read more about *Device*-based access control [here](#access-control)). A *Device* belongs to the one *User* that registered it. One or more *User*'s *Sessions* can belong to the same *Device*.

## State

A *Device* has one of 3 states at a time, namely `ACTIVE`, `REJECTED` and `PENDING` as follows:

- `ACTIVE` indicates an active *Device*, whose *Session* can access any *Service* if authorized.
- `REJECTED` means that the *Device* is simply deactivated and any *Session* created from that *Device*, cannot access any *Service* unless the *Device* is set to `ACTIVE` again.
- `PENDING` indicates that the *Device* is still pending for a decision whether to be activated or deactivated or `REJECTED`.

The *Cluster* by default automatically sets the state for a newly created *Device* to `ACTIVE`. You can explicitly set a default *Device* state for a specific *User* (read more [here](https://octelium.com/docs/octelium/latest/management/core/user.md#device)) as follows:

```yaml
kind: User
metadata:
  name: john
spec:
  type: HUMAN
  # !mark(1:2)
  session:
    defaultState: ACTIVE
```

You can also set the default state at the *Cluster* level via *ClusterConfig* (read more [here](https://octelium.com/docs/octelium/latest/management/core/cluster-config.md#device)), separately for `HUMAN` and `WORKLOAD` *Users*, as follows:

```yaml
kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  device:
    human:
      # !mark
      defaultState: PENDING
    workload:
      # !mark
      defaultState: ACTIVE
```

### Approving Devices

You can approve a *Device* to set its state to `ACTIVE` simply as follows:

```bash
octeliumctl update device --approve <DEVICE_NAME>
```

### Rejecting Devices

You can reject a *Device* to set its state to `REJECTED` simply as follows:

```bash
octeliumctl update device --reject <DEVICE_NAME>
```

## Per User Limit

You can also set an upper limit of maximum *Devices* allowed per *User* as follows:

```yaml
kind: ClusterConfig
metadata:
  name: cluster-config
spec:
  device:
    human:
      # !mark
      maxPerUser: 20
    workload:
      # !mark
      maxPerUser: 100
```

And as always, you update the *ClusterConfig* via the command `octeliumctl apply` (read more [here](https://octelium.com/docs/octelium/latest/management/core/cluster-config.md)).

## Listing Devices

You can list the *Cluster*'s *Devices*\_ (read more about listing resources [here](https://octelium.com/docs/octelium/latest/management/core/overview.md#listing-resources)) as follows:

```bash
octeliumctl get device
# Or simply
octeliumctl get dev

# Or list by a certain User
octeliumctl get dev --user john

# Show a certain Device
octeliumctl get dev <NAME>
```

## Access Control

You can control access to *Services* in your *Policies* based on the *Device* information. Here is an example where you only allow `LINUX` or `MAC` *Devices*:

```yaml
kind: Policy
metadata:
  name: allowed-devices
spec:
  rules:
    - effect: ALLOW
      condition:
        match: ctx.device.status.osType in ["LINUX", "MAC"]
```

## API Reference

[Device JSON Schema (Octelium core/v1, latest documentation)](https://octelium.com/schemas/octelium/latest/Device.schema.json)