<commit_before># Communication between instance and host

```{youtube} https://www.youtube.com/watch?v=xZSnqqWykmo
```

Communication between the hosted workload (instance) and its host while
not strictly needed is a pretty useful feature.

In LXD, this feature is implemented through a `/dev/lxd/sock` node which is
created and set up for all LXD instances.

This file is a Unix socket which processes inside the instance can
connect to. It's multi-threaded so multiple clients can be connected at the
same time.

```{note}
[`security.devlxd`](instance-configuration) must be set to `true` (which is the default) for an instance to allow access to the socket.
```

## Implementation details

LXD on the host binds `/var/lib/lxd/devlxd/sock` and starts listening for new
connections on it.

This socket is then exposed into every single instance started by
LXD at `/dev/lxd/sock`.

The single socket is required so we can exceed 4096 instances, otherwise,
LXD would have to bind a different socket for every instance, quickly
reaching the FD limit.

## Authentication

Queries on `/dev/lxd/sock` will only return information related to the
requesting instance. To figure out where a request comes from, LXD will
extract the initial socket's user credentials and compare that to the list of
instances it manages.

## Protocol

The protocol on `/dev/lxd/sock` is plain-text HTTP with JSON messaging, so very
similar to the local version of the LXD protocol.

Unlike the main LXD API, there is no background operation and no
authentication support in the `/dev/lxd/sock` API.

## REST-API

### API structure

* `/`
   * `/1.0`
      * `/1.0/config`
         * `/1.0/config/{key}`
      * `/1.0/devices`
      * `/1.0/events`
      * `/1.0/images/{fingerprint}/export`
      * `/1.0/meta-data`

### API details

#### `/`

##### GET

* Description: List of supported APIs
* Return: list of supported API endpoint URLs (by default `['/1.0']`)

Return value:

```json
[
    "/1.0"
]
```

#### `/1.0`

##### GET

* Description: Information about the 1.0 API
* Return: dict

Return value:

```json
{
    "api_version": "1.0",
    "location": "none",
    "instance_type": "container",
    "state": "Started",
}
```

#### PATCH

* Description: Update instance state (valid states are `Ready` and `Started`)
* Return: none

 Input:

 ```json
 {
    "state": "Ready"
 }
```

#### `/1.0/config`

##### GET

* Description: List of configuration keys
* Return: list of configuration keys URL
<commit_msg>doc: the location is set in responses from GET /1.0 in devlxd API<commit_after># Communication between instance and host

```{youtube} https://www.youtube.com/watch?v=xZSnqqWykmo
```

Communication between the hosted workload (instance) and its host while
not strictly needed is a pretty useful feature.

In LXD, this feature is implemented through a `/dev/lxd/sock` node which is
created and set up for all LXD instances.

This file is a Unix socket which processes inside the instance can
connect to. It's multi-threaded so multiple clients can be connected at the
same time.

```{note}
[`security.devlxd`](instance-configuration) must be set to `true` (which is the default) for an instance to allow access to the socket.
```

## Implementation details

LXD on the host binds `/var/lib/lxd/devlxd/sock` and starts listening for new
connections on it.

This socket is then exposed into every single instance started by
LXD at `/dev/lxd/sock`.

The single socket is required so we can exceed 4096 instances, otherwise,
LXD would have to bind a different socket for every instance, quickly
reaching the FD limit.

## Authentication

Queries on `/dev/lxd/sock` will only return information related to the
requesting instance. To figure out where a request comes from, LXD will
extract the initial socket's user credentials and compare that to the list of
instances it manages.

## Protocol

The protocol on `/dev/lxd/sock` is plain-text HTTP with JSON messaging, so very
similar to the local version of the LXD protocol.

Unlike the main LXD API, there is no background operation and no
authentication support in the `/dev/lxd/sock` API.

## REST-API

### API structure

* `/`
   * `/1.0`
      * `/1.0/config`
         * `/1.0/config/{key}`
      * `/1.0/devices`
      * `/1.0/events`
      * `/1.0/images/{fingerprint}/export`
      * `/1.0/meta-data`

### API details

#### `/`

##### GET

* Description: List of supported APIs
* Return: list of supported API endpoint URLs (by default `['/1.0']`)

Return value:

```json
[
    "/1.0"
]
```

#### `/1.0`

##### GET

* Description: Information about the 1.0 API
* Return: dict

Return value:

```json
{
    "api_version": "1.0",
    "location": "foo.example.com",
    "instance_type": "container",
    "state": "Started",
}
```

#### PATCH

* Description: Update instance state (valid states are `Ready` and `Started`)
* Return: none

 Input:

 ```json
 {
    "state": "Ready"
 }
```

#### `/1.0/config`

##### GET

* Description: List of configuration keys
* Return: list of configuration keys URL

{'fraction_non_alphanumeric': 0.12085731295892042, 'fraction_numerical': 0.012304028577098631, 'mean_word_length': 3.6111619396157364, 'pattern_counts': {'":': 10, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7269282', 'n_tokens_mistral': 1629, 'n_tokens_neox': 1558, 'n_words': 636}