Skip to content

Commit a60bab1

Browse files
committed
docs: add live snapshot API documentation
Add documentation for the live snapshot feature including: - serviceConfig configuration options - Device ID format and usage - HTTP API endpoint (/snapshot) - New config format requirements - Usage examples and notes Signed-off-by: Yifan Yuan <tuji.yyf@alibaba-inc.com>
1 parent 6aa64b6 commit a60bab1

File tree

1 file changed

+69
-1
lines changed

1 file changed

+69
-1
lines changed

README.md

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,11 @@ Default configure file `overlaybd.json` is installed to `/etc/overlaybd/`.
169169
"updateInterval": 60000000
170170
},
171171
"enableAudit": true,
172-
"auditPath": "/var/log/overlaybd-audit.log"
172+
"auditPath": "/var/log/overlaybd-audit.log",
173+
"serviceConfig": {
174+
"enable": false,
175+
"address": "http://127.0.0.1:9862"
176+
}
173177
}
174178
```
175179

@@ -210,6 +214,8 @@ Default configure file `overlaybd.json` is installed to `/etc/overlaybd/`.
210214
| certConfig.certFile | The path for SSL/TLS client certificate file |
211215
| certConfig.keyFile | The path for SSL/TLS client key file |
212216
| userAgent | customized userAgent to identify HTTP request. default value is package version like 'overlaybd/1.1.14-6c449832' |
217+
| serviceConfig.enable | Enable live snapshot API service, `false` is default. |
218+
| serviceConfig.address | API service listening address, default `http://127.0.0.1:9862`. |
213219

214220

215221
> NOTE: `download` is the config for background downloading. After an overlaybd device is lauched, a background task will be running to fetch the whole blobs into local directories. After downloading, I/O requests are directed to local files. Unlike other options, download config is reloaded when a device launching.
@@ -381,6 +387,68 @@ At last, compression may be needed.
381387
```
382388
The zfile can be used as lower layer with online decompression.
383389

390+
### Live Snapshot
391+
392+
Overlaybd supports creating live snapshots without stopping the device. This feature allows you to capture the current state of a writable layer and stack a new writable layer on top.
393+
394+
#### Device ID
395+
396+
To use the live snapshot feature, you need to specify a device ID when creating the overlaybd device. The device ID is appended to the config path with a semicolon separator:
397+
398+
```bash
399+
echo -n dev_config=overlaybd//root/config.v1.json;mydevice123 > /sys/kernel/config/target/core/user_1/vol1/control
400+
```
401+
402+
#### Enable API Service
403+
404+
Add the following to your `overlaybd.json`:
405+
406+
```json
407+
"serviceConfig": {
408+
"enable": true,
409+
"address": "http://127.0.0.1:9862"
410+
}
411+
```
412+
413+
#### Create Snapshot
414+
415+
Send an HTTP POST request to the `/snapshot` endpoint:
416+
417+
```bash
418+
curl -X POST "http://127.0.0.1:9862/snapshot?dev_id=mydevice123&config=/path/to/new_config.json"
419+
```
420+
421+
The response will be in JSON format:
422+
423+
```json
424+
{
425+
"success": true,
426+
"message": "Snapshot created successfully"
427+
}
428+
```
429+
430+
#### New Config Format
431+
432+
The new config file should include the current upper layer as the last lower layer:
433+
434+
```json
435+
{
436+
"lowers": [
437+
{
438+
"file": "/opt/overlaybd/layer0"
439+
},
440+
{
441+
"file": "/path/to/current_upper_data.lsmt"
442+
}
443+
],
444+
"upper": {
445+
"index": "/path/to/new_upper_index.lsmt",
446+
"data": "/path/to/new_upper_data.lsmt"
447+
}
448+
}
449+
```
450+
451+
**Note**: The new upper layer must be different from the old upper layer.
384452

385453
## Kernel module
386454

0 commit comments

Comments
 (0)