1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
(dev-incus)=
# Communication between instance and host
Communication between the hosted workload (instance) and its host while
not strictly needed is a pretty useful feature.
In Incus, this feature is implemented through a `/dev/incus/sock` node which is
created and set up for all Incus 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}
{config:option}`instance-security:security.guestapi` must be set to `true` (which is the default) for an instance to allow access to the socket.
```
## Implementation details
Incus on the host binds `/var/lib/incus/guestapi/sock` and starts listening for new
connections on it.
This socket is then exposed into every single instance started by
Incus at `/dev/incus/sock`.
The single socket is required so we can exceed 4096 instances, otherwise,
Incus would have to bind a different socket for every instance, quickly
reaching the FD limit.
## Authentication
Queries on `/dev/incus/sock` will only return information related to the
requesting instance. To figure out where a request comes from, Incus will
extract the initial socket's user credentials and compare that to the list of
instances it manages.
## Protocol
The protocol on `/dev/incus/sock` is plain-text HTTP with JSON messaging, so very
similar to the local version of the Incus protocol.
Unlike the main Incus API, there is no background operation and no
authentication support in the `/dev/incus/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: JSON object
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
Note that the configuration key names match those in the instance
configuration, however not all configuration namespaces will be exported to
`/dev/incus/sock`.
Currently only the `cloud-init.*` and `user.*` keys are accessible to the instance.
At this time, there also aren't any instance-writable namespace.
Return value:
```json
[
"/1.0/config/user.a"
]
```
#### `/1.0/config/<KEY>`
##### GET
* Description: Value of that key
* Return: Plain-text value
Return value:
blah
#### `/1.0/devices`
##### GET
* Description: Map of instance devices
* Return: JSON object
Return value:
```json
{
"eth0": {
"name": "eth0",
"network": "incusbr0",
"type": "nic"
},
"root": {
"path": "/",
"pool": "default",
"type": "disk"
}
}
```
#### `/1.0/events`
##### GET
* Description: WebSocket upgrade
* Return: none (never ending flow of events)
Supported arguments are:
* type: comma-separated list of notifications to subscribe to (defaults to all)
The notification types are:
* `config` (changes to any of the `user.*` configuration keys)
* `device` (any device addition, change or removal)
This never returns. Each notification is sent as a separate JSON object:
```json
{
"timestamp": "2017-12-21T18:28:26.846603815-05:00",
"type": "device",
"metadata": {
"name": "kvm",
"action": "added",
"config": {
"type": "unix-char",
"path": "/dev/kvm"
}
}
}
```
```json
{
"timestamp": "2017-12-21T18:28:26.846603815-05:00",
"type": "config",
"metadata": {
"key": "user.foo",
"old_value": "",
"value": "bar"
}
}
```
#### `/1.0/images/<FINGERPRINT>/export`
##### GET
* Description: Download a public/cached image from the host
* Return: raw image or error
* Access: Requires `security.guestapi.images` set to `true`
Return value:
See /1.0/images/<FINGERPRINT>/export in the daemon API.
#### `/1.0/meta-data`
##### GET
* Description: Container meta-data compatible with cloud-init
* Return: cloud-init meta-data
Return value:
#cloud-config
instance-id: af6a01c7-f847-4688-a2a4-37fddd744625
local-hostname: abc
|
