[lxc-devel] [lxd/master] doc: add the appropriate titles to some documents
tenforward on Github
lxc-bot at linuxcontainers.org
Tue Oct 16 10:58:35 UTC 2018
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 554 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20181016/a94d67b5/attachment.bin>
-------------- next part --------------
From 906114c8c7db9efab2e7c96cbb82d7834c1e174d Mon Sep 17 00:00:00 2001
From: KATOH Yasufumi <karma at jazz.email.ne.jp>
Date: Tue, 16 Oct 2018 19:04:41 +0900
Subject: [PATCH] doc: add the appropriate titles to some documents
In some documents, the first level header ("#") is "Introduction". In
readthedocs, this header is used for menus. So we add the first level
header that represents the contents of the documents.
Signed-off-by: KATOH Yasufumi <karma at jazz.email.ne.jp>
---
doc/architectures.md | 6 +-
doc/configuration.md | 2 +-
doc/contributing.md | 8 +-
doc/daemon-behavior.md | 14 +-
doc/database.md | 14 +-
doc/debugging.md | 2 +
doc/dev-lxd.md | 43 ++---
doc/environment.md | 10 +-
doc/image-handling.md | 18 +-
doc/production-setup.md | 23 +--
doc/rest-api.md | 367 ++++++++++++++++++++--------------------
doc/security.md | 21 +--
doc/userns-idmap.md | 13 +-
13 files changed, 280 insertions(+), 261 deletions(-)
diff --git a/doc/architectures.md b/doc/architectures.md
index 30af23cbda..a40d47a0e8 100644
--- a/doc/architectures.md
+++ b/doc/architectures.md
@@ -1,4 +1,6 @@
-# Introduction
+# Architectures
+
+## Introduction
LXD just like LXC can run on just about any architecture that's
supported by the Linux kernel and by Go.
@@ -18,7 +20,7 @@ soft-float and refers to both as "armv7". If useful to the user, the
exact userspace ABI may be set as an image and container property,
allowing easy query.
-# Architectures
+## Architectures
ID | Name | Notes | Personalities
:--- | :--- | :---- | :------------
diff --git a/doc/configuration.md b/doc/configuration.md
index 0d3288c2e8..dabf5db6ee 100644
--- a/doc/configuration.md
+++ b/doc/configuration.md
@@ -1,4 +1,4 @@
-# Introduction
+# Configuration
Current LXD stores configurations for a few components:
- [Server](server.md)
diff --git a/doc/contributing.md b/doc/contributing.md
index 763862ca97..82f5ed3b96 100644
--- a/doc/contributing.md
+++ b/doc/contributing.md
@@ -1,4 +1,6 @@
-# Pull requests:
+# Contributing
+
+## Pull requests:
Changes to this project should be proposed as pull requests on Github
at: <https://github.com/lxc/lxd>
@@ -7,7 +9,7 @@ Proposed changes will then go through code review there and once acked,
be merged in the main branch.
-# License and copyright:
+## License and copyright:
By default, any contribution to this project is made under the Apache
2.0 license.
@@ -16,7 +18,7 @@ The author of a change remains the copyright holder of their code
(no copyright assignment).
-# Developer Certificate of Origin:
+## Developer Certificate of Origin:
To improve tracking of contributions to this project we use the DCO 1.1
and use a "sign-off" procedure for all changes going into the branch.
diff --git a/doc/daemon-behavior.md b/doc/daemon-behavior.md
index dba876f93d..326de520b7 100644
--- a/doc/daemon-behavior.md
+++ b/doc/daemon-behavior.md
@@ -1,9 +1,11 @@
-# Introduction
+# Daemon behavior
+
+## Introduction
This specification covers some of the daemon's behavior, such as
reaction to given signals, crashes, ...
-# Startup
+## Startup
On every start, LXD checks that its directory structure exists. If it
doesn't, it'll create the required directories, generate a keypair and
initialize the database.
@@ -13,15 +15,15 @@ for any container for which the stored power state differs from the
current one. If a container's power state was recorded as running and the
container isn't running, LXD will start it.
-# Signal handling
-## SIGINT, SIGQUIT, SIGTERM
+## Signal handling
+### SIGINT, SIGQUIT, SIGTERM
For those signals, LXD assumes that it's being temporarily stopped and
will be restarted at a later time to continue handling the containers.
The containers will keep running and LXD will close all connections and
exit cleanly.
-## SIGPWR
+### SIGPWR
Indicates to LXD that the host is going down.
LXD will attempt a clean shutdown of all the containers. After 30s, it
@@ -31,5 +33,5 @@ The container `power_state` in the containers table is kept as it was so
that LXD after the host is done rebooting can restore the containers as
they were.
-## SIGUSR1
+### SIGUSR1
Write a memory profile dump to the file specified with `--memprofile`.
diff --git a/doc/database.md b/doc/database.md
index d3671fc0a9..4626663aac 100644
--- a/doc/database.md
+++ b/doc/database.md
@@ -1,4 +1,6 @@
-# Introduction
+# Database
+
+## Introduction
So first of all, why a database?
Rather than keeping the configuration and state within each container's
@@ -18,7 +20,7 @@ database, it's only a matter of accessing the already cached database
with a pretty simple query.
-# Database engine
+## Database engine
Since LXD supports clustering, and all members of the cluster must share the
same database state, the database engine is based on a [distributed
version](https://github.com/CanonicalLtd/dqlite) of SQLite, which provides
@@ -40,13 +42,13 @@ Backups of the global database directory and of the local database file are made
before upgrades, and are tagged with the ``.bak`` suffix. You can use those if
you need to revert the state as it was before the upgrade.
-# Dumping the database content or schema
+## Dumping the database content or schema
If you want to get a SQL text dump of the content or the schema of the databases,
use the ``lxd sql <local|global> [.dump|.schema]`` command, which produces the
equivalent output of the ``.dump`` or ``.schema`` directives of the sqlite3
command line tool.
-# Running custom queries from the console
+## Running custom queries from the console
If you need to perform SQL queries (e.g. ``SELECT``, ``INSERT``, ``UPDATE``)
against the local or global database, you can use the ``lxd sql`` command (run
``lxd sql --help`` for details).
@@ -56,7 +58,7 @@ Please consult the LXD team first (creating a [GitHub
issue](https://github.com/lxc/lxd/issues/new) or
[forum](https://discuss.linuxcontainers.org/) post).
-# Running custom queries at LXD daemon startup
+## Running custom queries at LXD daemon startup
In case the LXD daemon fails to start after an upgrade because of SQL data
migration bugs or similar problems, it's possible to recover the situation by
creating ``.sql`` files containing queries that repair the broken update.
@@ -71,7 +73,7 @@ run in a SQL transaction).
As above, please consult the LXD team first.
-# Syncing the cluster database to disk
+## Syncing the cluster database to disk
If you want to flush the content of the cluster database to disk, use the ``lxd
sql global .sync`` command, that will write a plain SQLite database file into
``./database/global/db.bin``, which you can then inspect with the ``sqlite3``
diff --git a/doc/debugging.md b/doc/debugging.md
index e7a3d5b1c6..a5bf78f813 100644
--- a/doc/debugging.md
+++ b/doc/debugging.md
@@ -1,3 +1,5 @@
+# Debugging
+
Here are different ways to help troubleshooting `lxc` and `lxd` code.
#### lxc --debug
diff --git a/doc/dev-lxd.md b/doc/dev-lxd.md
index 0bf997d388..692f2513b4 100644
--- a/doc/dev-lxd.md
+++ b/doc/dev-lxd.md
@@ -1,4 +1,5 @@
-# Introduction
+# Communication between container and host
+## Introduction
Communication between the hosted workload (container) and its host while
not strictly needed is a pretty useful feature.
@@ -9,7 +10,7 @@ This file is a Unix socket which processes inside the container can
connect to. It's multi-threaded so multiple clients can be connected at the
same time.
-# Implementation details
+## Implementation details
LXD on the host binds `/var/lib/lxd/devlxd` and starts listening for new
connections on it.
@@ -20,21 +21,21 @@ The bind-mount is required so we can exceed 4096 containers, otherwise,
LXD would have to bind a different socket for every container, quickly
reaching the FD limit.
-# Authentication
+## Authentication
Queries on `/dev/lxd/sock` will only return information related to the
requesting container. To figure out where a request comes from, LXD will
extract the initial socket ucred and compare that to the list of
containers it manages.
-# Protocol
+## 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
+## REST-API
+### API structure
* /
* /1.0
* /1.0/config
@@ -43,9 +44,9 @@ authentication support in the `/dev/lxd/sock` API.
* /1.0/images/{fingerprint}/export
* /1.0/meta-data
-## API details
-### `/`
-#### GET
+### API details
+#### `/`
+##### GET
* Description: List of supported APIs
* Return: list of supported API endpoint URLs (by default `['/1.0']`)
@@ -56,8 +57,8 @@ Return value:
"/1.0"
]
```
-### `/1.0`
-#### GET
+#### `/1.0`
+##### GET
* Description: Information about the 1.0 API
* Return: dict
@@ -68,8 +69,8 @@ Return value:
"api_version": "1.0"
}
```
-### `/1.0/config`
-#### GET
+#### `/1.0/config`
+##### GET
* Description: List of configuration keys
* Return: list of configuration keys URL
@@ -88,8 +89,8 @@ Return value:
]
```
-### `/1.0/config/<KEY>`
-#### GET
+#### `/1.0/config/<KEY>`
+##### GET
* Description: Value of that key
* Return: Plain-text value
@@ -97,8 +98,8 @@ Return value:
blah
-### `/1.0/events`
-#### GET
+#### `/1.0/events`
+##### GET
* Description: websocket upgrade
* Return: none (never ending flow of events)
@@ -136,8 +137,8 @@ This never returns. Each notification is sent as a separate JSON dict:
}
}
-### `/1.0/images/<FINGERPRINT>/export`
-#### GET
+#### `/1.0/images/<FINGERPRINT>/export`
+##### GET
* Description: Download a public/cached image from the host
* Return: raw image or error
* Access: Requires security.devlxd.images set to true
@@ -147,8 +148,8 @@ Return value:
See /1.0/images/<FINGERPRINT>/export in the daemon API.
-### `/1.0/meta-data`
-#### GET
+#### `/1.0/meta-data`
+##### GET
* Description: Container meta-data compatible with cloud-init
* Return: cloud-init meta-data
diff --git a/doc/environment.md b/doc/environment.md
index 2e2ab8767e..2be312eca5 100644
--- a/doc/environment.md
+++ b/doc/environment.md
@@ -1,8 +1,10 @@
-# Introduction
+# Environment variables
+
+## Introduction
The LXD client and daemon respect some environment variables to adapt to
the user's environment and to turn some advanced features on and off.
-# Common
+## Common
Name | Description
:--- | :----
`LXD_DIR` | The LXD data directory
@@ -12,13 +14,13 @@ Name | Description
`https_proxy` | Proxy server URL for HTTPs
`no_proxy` | List of domains that don't require the use of a proxy
-# Client environment variable
+## Client environment variable
Name | Description
:--- | :----
`EDITOR` | What text editor to use
`VISUAL` | What text editor to use (if `EDITOR` isn't set)
-# Server environment variable
+## Server environment variable
Name | Description
:--- | :----
`LXD_EXEC_PATH` | Full path to the LXD binary (used when forking subcommands)
diff --git a/doc/image-handling.md b/doc/image-handling.md
index 5451f0db08..3689581d90 100644
--- a/doc/image-handling.md
+++ b/doc/image-handling.md
@@ -1,4 +1,6 @@
-# Introduction
+# Image handling
+
+## Introduction
LXD uses an image based workflow. It comes with a built-in image store
where the user or external tools can import images.
@@ -8,7 +10,7 @@ It's possible to spawn remote containers using local images or local
containers using remote images. In such cases, the image may be cached
on the target LXD.
-# Caching
+## Caching
When spawning a container from a remote image, the remote image is
downloaded into the local image store with the cached bit set. The image
will be kept locally as a private image until either it's been unused
@@ -19,7 +21,7 @@ whichever comes first.
LXD keeps track of image usage by updating the `last_used_at` image
property every time a new container is spawned from the image.
-# Auto-update
+## Auto-update
LXD can keep images up to date. By default, any image which comes from a
remote server and was requested through an alias will be automatically
updated by LXD. This can be changed with `images.auto_update_cached`.
@@ -45,7 +47,7 @@ than delay the container creation.
This behavior only happens if the current image is scheduled to be
auto-updated and can be disabled by setting `images.auto_update_interval` to 0.
-# Image format
+## Image format
LXD currently supports two LXD-specific image formats.
The first is a unified tarball, where a single tarball
@@ -60,7 +62,7 @@ using for LXD-specific images.
The latter is designed to allow for easy image building from existing
non-LXD rootfs tarballs already available today.
-## Unified tarball
+### Unified tarball
Tarball, can be compressed and contains:
- `rootfs/`
@@ -69,7 +71,7 @@ Tarball, can be compressed and contains:
In this mode, the image identifier is the SHA-256 of the tarball.
-## Split tarballs
+### Split tarballs
Two (possibly compressed) tarballs. One for metadata, one for the rootfs.
`metadata.tar` contains:
@@ -82,11 +84,11 @@ Two (possibly compressed) tarballs. One for metadata, one for the rootfs.
In this mode the image identifier is the SHA-256 of the concatenation of
the metadata and rootfs tarball (in that order).
-## Supported compression
+### Supported compression
The tarball(s) can be compressed using bz2, gz, xz, lzma, tar (uncompressed) or
it can also be a squashfs image.
-## Content
+### Content
The rootfs directory (or tarball) contains a full file system tree of what will become the container's `/`.
The templates directory contains pongo2-formatted templates of files inside the container.
diff --git a/doc/production-setup.md b/doc/production-setup.md
index 2a15e4fd3c..4e649a171b 100644
--- a/doc/production-setup.md
+++ b/doc/production-setup.md
@@ -1,4 +1,5 @@
-# Introduction
+# Production setup
+## Introduction
So you've made it past trying out [LXD live online](https://linuxcontainers.org/lxd/try-it/),
or on a server scavenged from random parts. You like what you see,
and now you want to try doing some serious work with LXD.
@@ -8,7 +9,7 @@ to the server configuration will be needed, to avoid common pitfalls when
using containers that require tens of thousands of file operations.
-## Common errors that may be encountered
+### Common errors that may be encountered
`Failed to allocate directory watch: Too many open files`
@@ -18,8 +19,8 @@ using containers that require tens of thousands of file operations.
`neighbour: ndisc_cache: neighbor table overflow!`
-# Server Changes
-## /etc/security/limits.conf
+## Server Changes
+### /etc/security/limits.conf
Domain | Type | Item | Value | Default | Description
:----- | :--- | :---- | :-------- | :-------- | :----------
@@ -31,7 +32,7 @@ root | hard | nofile | 1048576 | unset | maximum number of open files
\* | hard | memlock | unlimited | unset | maximum locked-in-memory address space (KB)
-## /etc/sysctl.conf
+### /etc/sysctl.conf
Parameter | Value | Default | Description
:----- | :--- | :--- | :---
@@ -49,19 +50,19 @@ Then, reboot the server.
[1]: http://man7.org/linux/man-pages/man7/inotify.7.html
[2]: https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt
-## Network Bandwidth Tweaking
+### Network Bandwidth Tweaking
If you have at least 1GbE NIC on your lxd host with a lot of local activity (container - container connections, or host - container connections), or you have 1GbE or better internet connection on your lxd host it worth play with txqueuelen. These settings work even better with 10GbE NIC.
-### Server Changes
+#### Server Changes
-#### txqueuelen
+##### txqueuelen
You need to change `txqueuelen` of your real NIC to 10000 (not sure about the best possible value for you), and change and change lxdbr0 interface `txqueuelen` to 10000.
In Debian-based distros you can change `txqueuelen` permanently in `/etc/network/interfaces`
You can add for ex.: `up ip link set eth0 txqueuelen 10000` to your interface configuration to set txqueuelen value on boot.
You could set it txqueuelen temporary (for test purpose) with `ifconfig <interface> txqueuelen 10000`
-#### /etc/sysctl.conf
+##### /etc/sysctl.conf
You also need to increase `net.core.netdev_max_backlog` value.
You can add `net.core.netdev_max_backlog = 182757` to `/etc/sysctl.conf` to set it permanently (after reboot)
@@ -69,13 +70,13 @@ You set `netdev_max_backlog` temporary (for test purpose) with `echo 182757 > /p
Note: You can find this value too high, most people prefer set `netdev_max_backlog` = `net.ipv4.tcp_mem` min. value.
For example I use this values `net.ipv4.tcp_mem = 182757 243679 365514`
-### Containers changes
+#### Containers changes
You also need to change txqueuelen value for all you ethernet interfaces in containers.
In Debian-based distros you can change txqueuelen permanently in `/etc/network/interfaces`
You can add for ex.: `up ip link set eth0 txqueuelen 10000` to your interface configuration to set txqueuelen value on boot.
-### Notes regarding this change
+#### Notes regarding this change
10000 txqueuelen value commonly used with 10GbE NICs. Basically small txqueuelen values used with slow devices with a high latency, and higher with devices with low latency. I personally have like 3-5% improvement with these settings for local (host with container, container vs container) and internet connections. Good thing about txqueuelen value tweak, the more containers you use, the more you can be can benefit from this tweak. And you can always temporary set this values and check this tweak in your environment without lxd host reboot.
diff --git a/doc/rest-api.md b/doc/rest-api.md
index bcec18c893..92b5215f7b 100644
--- a/doc/rest-api.md
+++ b/doc/rest-api.md
@@ -1,4 +1,5 @@
-# Introduction
+# REST API
+## Introduction
All the communications between LXD and its clients happen using a
RESTful API over http which is then encapsulated over either SSL for
remote operations or a unix socket for local operations.
@@ -12,7 +13,7 @@ Not all of the REST interface requires authentication:
Unauthenticated endpoints are clearly identified as such below.
-# API versioning
+## API versioning
The list of supported major API versions can be retrieved using `GET /`.
The reason for a major API bump is if the API breaks backward compatibility.
@@ -21,14 +22,14 @@ Feature additions done without breaking backward compatibility only
result in addition to `api_extensions` which can be used by the client
to check if a given feature is supported by the server.
-# Return values
+## Return values
There are three standard return types:
* Standard return value
* Background operation
* Error
-### Standard return value
+#### Standard return value
For a standard synchronous operation, the following dict is returned:
{
@@ -40,7 +41,7 @@ For a standard synchronous operation, the following dict is returned:
HTTP code must be 200.
-### Background operation
+#### Background operation
When a request results in a background operation, the HTTP code is set to 202 (Accepted)
and the Location HTTP header is set to the operation URL.
@@ -82,7 +83,7 @@ The body is mostly provided as a user friendly way of seeing what's
going on without having to pull the target operation, all information in
the body can also be retrieved from the background operation URL.
-### Error
+#### Error
There are various situations in which something may immediately go
wrong, in those cases, the following return value is used:
@@ -95,7 +96,7 @@ wrong, in those cases, the following return value is used:
HTTP code must be one of of 400, 401, 403, 404, 409, 412 or 500.
-# Status codes
+## Status codes
The LXD REST API often has to return status information, be that the
reason for an error, the current state of an operation or the state of
the various resources it exports.
@@ -117,7 +118,7 @@ The codes are always 3 digits, with the following ranges:
* 400 to 599: negative action result
* 600 to 999: future use
-## List of current status codes
+### List of current status codes
Code | Meaning
:--- | :------
@@ -137,7 +138,7 @@ Code | Meaning
400 | Failure
401 | Cancelled
-# Recursion
+## Recursion
To optimize queries of large lists, recursion is implemented for collections.
A `recursion` argument can be passed to a GET query against a collection.
@@ -148,14 +149,14 @@ they point to (typically a dict).
Recursion is implemented by simply replacing any pointer to an job (URL)
by the object itself.
-# Async operations
+## Async operations
Any operation which may take more than a second to be done must be done
in the background, returning a background operation ID to the client.
The client will then be able to either poll for a status update or wait
for a notification using the long-poll API.
-# Notifications
+## Notifications
A websocket based API is available for notifications, different notification
types exist to limit the traffic going to the client.
@@ -163,7 +164,7 @@ It's recommended that the client always subscribes to the operations
notification type before triggering remote operations so that it doesn't
have to then poll for their status.
-# PUT vs PATCH
+## PUT vs PATCH
The LXD API supports both PUT and PATCH to modify existing objects.
PUT replaces the entire object with a new definition, it's typically
@@ -178,7 +179,7 @@ specifying the property that you want to change. To unset a key, setting
it to empty will usually do the trick, but there are cases where PATCH
won't work and PUT needs to be used instead.
-# API structure
+## API structure
* [`/`](#)
* [`/1.0`](#10)
* [`/1.0/certificates`](#10certificates)
@@ -230,9 +231,9 @@ won't work and PUT needs to be used instead.
* [`/1.0/cluster/members`](#10clustermembers)
* [`/1.0/cluster/members/<name>`](#10clustermembersname)
-# API details
-## `/`
-### GET
+## API details
+### `/`
+#### GET
* Description: List of supported APIs
* Authentication: guest
* Operation: sync
@@ -244,8 +245,8 @@ Return value:
"/1.0"
]
-## `/1.0/`
-### GET
+### `/1.0/`
+#### GET
* Description: Server configuration and environment information
* Authentication: guest, untrusted or trusted
* Operation: sync
@@ -296,7 +297,7 @@ Return value (if guest or untrusted):
"public": false, # Whether the server should be treated as a public (read-only) remote by the client
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: Replaces the server configuration or other properties
* Authentication: trusted
* Operation: sync
@@ -311,7 +312,7 @@ Input (replaces any existing config with the provided one):
}
}
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: Updates the server configuration or other properties
* Introduced: with API extension `patch`
* Authentication: trusted
@@ -326,8 +327,8 @@ Input (updates only the listed keys, rest remains intact):
}
}
-## `/1.0/certificates`
-### GET
+### `/1.0/certificates`
+#### GET
* Description: list of trusted certificates
* Authentication: trusted
* Operation: sync
@@ -339,7 +340,7 @@ Return:
"/1.0/certificates/3ee64be3c3c7d617a7470e14f2d847081ad467c8c26e1caad841c8f67f7c7b09"
]
-### POST
+#### POST
* Description: add a new trusted certificate
* Authentication: trusted or untrusted
* Operation: sync
@@ -354,8 +355,8 @@ Input:
"password": "server-trust-password" # The trust password for that server (only required if untrusted)
}
-## `/1.0/certificates/<fingerprint>`
-### GET
+### `/1.0/certificates/<fingerprint>`
+#### GET
* Description: trusted certificate information
* Authentication: trusted
* Operation: sync
@@ -370,7 +371,7 @@ Output:
"fingerprint": "SHA256 Hash of the raw certificate"
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: Replaces the certificate properties
* Introduced: with API extension `certificate_update`
* Authentication: trusted
@@ -384,7 +385,7 @@ Input:
"name": "bar"
}
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: Updates the certificate properties
* Introduced: with API extension `certificate_update`
* Authentication: trusted
@@ -398,7 +399,7 @@ Input:
}
-### DELETE
+#### DELETE
* Description: Remove a trusted certificate
* Authentication: trusted
* Operation: sync
@@ -411,8 +412,8 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## `/1.0/containers`
-### GET
+### `/1.0/containers`
+#### GET
* Description: List of containers
* Authentication: trusted
* Operation: sync
@@ -425,7 +426,7 @@ Return value:
"/1.0/containers/blah1"
]
-### POST (optional `?target=<member>`)
+#### POST (optional `?target=<member>`)
* Description: Create a new container
* Authentication: trusted
* Operation: async
@@ -620,8 +621,8 @@ Input (using a backup):
Raw compressed tarball as provided by a backup download.
-## `/1.0/containers/<name>`
-### GET
+### `/1.0/containers/<name>`
+#### GET
* Description: Container information
* Authentication: trusted
* Operation: sync
@@ -671,7 +672,7 @@ Output:
"status_code": 103
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: replaces container configuration or restore snapshot
* Authentication: trusted
* Operation: async
@@ -708,7 +709,7 @@ Input (restore snapshot):
"restore": "snapshot-name"
}
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: update container configuration
* Introduced: with API extension `patch`
* Authentication: trusted
@@ -729,7 +730,7 @@ Input:
"ephemeral": true
}
-### POST (optional `?target=<member>`)
+#### POST (optional `?target=<member>`)
* Description: used to rename/migrate the container
* Authentication: trusted
* Operation: async
@@ -766,7 +767,7 @@ Output in metadata section (for migration):
These are the secrets that should be passed to the create call.
-### DELETE
+#### DELETE
* Description: remove the container
* Authentication: trusted
* Operation: async
@@ -779,14 +780,14 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## `/1.0/containers/<name>/console`
-### GET
+### `/1.0/containers/<name>/console`
+#### GET
* Description: returns the contents of the container's console log
* Authentication: trusted
* Operation: N/A
* Return: the contents of the console log
-### POST
+#### POST
* Description: attach to a container's console devices
* Authentication: trusted
* Operation: async
@@ -812,14 +813,14 @@ Control (window size change):
}
}
-### DELETE
+#### DELETE
* Description: empty the container's console log
* Authentication: trusted
* Operation: Sync
* Return: empty response or standard error
-## `/1.0/containers/<name>/exec`
-### POST
+### `/1.0/containers/<name>/exec`
+#### POST
* Description: run a remote command
* Authentication: trusted
* Operation: async
@@ -913,8 +914,8 @@ operation's metadata:
"return": 0
}
-## `/1.0/containers/<name>/files`
-### GET (`?path=/path/inside/the/container`)
+### `/1.0/containers/<name>/files`
+#### GET (`?path=/path/inside/the/container`)
* Description: download a file or directory listing from the container
* Authentication: trusted
* Operation: sync
@@ -932,7 +933,7 @@ The following headers will be set (on top of standard size and mimetype headers)
This is designed to be easily usable from the command line or even a web
browser.
-### POST (`?path=/path/inside/the/container`)
+#### POST (`?path=/path/inside/the/container`)
* Description: upload a file to the container
* Authentication: trusted
* Operation: sync
@@ -952,7 +953,7 @@ The following headers may be set by the client:
This is designed to be easily usable from the command line or even a web
browser.
-### DELETE (`?path=/path/inside/the/container`)
+#### DELETE (`?path=/path/inside/the/container`)
* Description: delete a file in the container
* Introduced: with API extension `file_delete`
* Authentication: trusted
@@ -964,8 +965,8 @@ Input (none at present):
{
}
-## `/1.0/containers/<name>/snapshots`
-### GET
+### `/1.0/containers/<name>/snapshots`
+#### GET
* Description: List of snapshots
* Authentication: trusted
* Operation: sync
@@ -977,7 +978,7 @@ Return value:
"/1.0/containers/blah/snapshots/snap0"
]
-### POST
+#### POST
* Description: create a new snapshot
* Authentication: trusted
* Operation: async
@@ -990,8 +991,8 @@ Input:
"stateful": true # Whether to include state too
}
-## `/1.0/containers/<name>/snapshots/<name>`
-### GET
+### `/1.0/containers/<name>/snapshots/<name>`
+#### GET
* Description: Snapshot information
* Authentication: trusted
* Operation: sync
@@ -1046,7 +1047,7 @@ Return:
"stateful": false
}
-### POST
+#### POST
* Description: used to rename/migrate the snapshot
* Authentication: trusted
* Operation: async
@@ -1075,7 +1076,7 @@ Return (with migration=true):
Renaming to an existing name must return the 409 (Conflict) HTTP code.
-### DELETE
+#### DELETE
* Description: remove the snapshot
* Authentication: trusted
* Operation: async
@@ -1088,8 +1089,8 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## `/1.0/containers/<name>/state`
-### GET
+### `/1.0/containers/<name>/state`
+#### GET
* Description: current state
* Authentication: trusted
* Operation: sync
@@ -1239,7 +1240,7 @@ Output:
}
}
-### PUT
+#### PUT
* Description: change the container state
* Authentication: trusted
* Operation: async
@@ -1254,8 +1255,8 @@ Input:
"stateful": true # Whether to store or restore runtime state before stopping or startiong (only valid for stop and start, defaults to false)
}
-## `/1.0/containers/<name>/logs`
-### GET
+### `/1.0/containers/<name>/logs`
+#### GET
* Description: Returns a list of the log files available for this container.
Note that this works on containers that have been deleted (or were never
created) to enable people to get logs for failed creations.
@@ -1271,21 +1272,21 @@ Return:
"/1.0/containers/blah/logs/lxc.log"
]
-## `/1.0/containers/<name>/logs/<logfile>`
-### GET
+### `/1.0/containers/<name>/logs/<logfile>`
+#### GET
* Description: returns the contents of a particular log file.
* Authentication: trusted
* Operation: N/A
* Return: the contents of the log file
-### DELETE
+#### DELETE
* Description: delete a particular log file.
* Authentication: trusted
* Operation: Sync
* Return: empty response or standard error
-## `/1.0/containers/<name>/metadata`
-### GET
+### `/1.0/containers/<name>/metadata`
+#### GET
* Description: Container metadata
* Introduced: with API extension `container_edit_metadata`
* Authentication: trusted
@@ -1316,7 +1317,7 @@ Return:
}
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: Replaces container metadata
* Introduced: with API extension `container_edit_metadata`
* Authentication: trusted
@@ -1347,8 +1348,8 @@ Input:
}
}
-## `/1.0/containers/<name>/metadata/templates`
-### GET
+### `/1.0/containers/<name>/metadata/templates`
+#### GET
* Description: List container templates
* Introduced: with API extension `container_edit_metadata`
* Authentication: trusted
@@ -1362,14 +1363,14 @@ Return:
"hosts.tpl"
]
-### GET (`?path=<template>`)
+#### GET (`?path=<template>`)
* Description: Content of a container template
* Introduced: with API extension `container_edit_metadata`
* Authentication: trusted
* Operation: Sync
* Return: the content of the template
-### POST (`?path=<template>`)
+#### POST (`?path=<template>`)
* Description: Add a continer template
* Introduced: with API extension `container_edit_metadata`
* Authentication: trusted
@@ -1380,7 +1381,7 @@ Input:
* Standard http file upload.
-### PUT (`?path=<template>`)
+#### PUT (`?path=<template>`)
* Description: Replace content of a template
* Introduced: with API extension `container_edit_metadata`
* Authentication: trusted
@@ -1391,15 +1392,15 @@ Input:
* Standard http file upload.
-### DELETE (`?path=<template>`)
+#### DELETE (`?path=<template>`)
* Description: Delete a container template
* Introduced: with API extension `container_edit_metadata`
* Authentication: trusted
* Operation: Sync
* Return: standard return value or standard error
-## `/1.0/containers/<name>/backups`
-### GET
+### `/1.0/containers/<name>/backups`
+#### GET
* Description: List of backups for the container
* Introduced: with API extension `container_backup`
* Authentication: trusted
@@ -1413,7 +1414,7 @@ Return value:
"/1.0/containers/c1/backups/c1/backup1",
]
-### POST
+#### POST
* Description: Create a new backup
* Introduced: with API extension `container_backup`
* Authentication: trusted
@@ -1429,8 +1430,8 @@ Input:
"optimized_storage": true # if True, btrfs send or zfs send is used for container and snapshots
}
-## `/1.0/containers/<name>/backups/<name>`
-### GET
+### `/1.0/containers/<name>/backups/<name>`
+#### GET
* Description: Backup information
* Introduced: with API extension `container_backup`
* Authentication: trusted
@@ -1447,14 +1448,14 @@ Output:
"optimized_storage": false
}
-### DELETE
+#### DELETE
* Description: remove the backup
* Introduced: with API extension `container_backup`
* Authentication: trusted
* Operation: async
* Return: background operation or standard error
-### POST
+#### POST
* Description: used to rename the backup
* Introduced: with API extension `container_backup`
* Authentication: trusted
@@ -1467,8 +1468,8 @@ Input:
"name": "new-name"
}
-## `/1.0/containers/<name>/backups/<name>/export`
-### GET
+### `/1.0/containers/<name>/backups/<name>/export`
+#### GET
* Description: fetch the backup tarball
* Introduced: with API extension `container_backup`
* Authentication: trusted
@@ -1481,12 +1482,12 @@ Output:
"data": <byte-stream>
}
-## `/1.0/events`
+### `/1.0/events`
This URL isn't a real REST API endpoint, instead doing a GET query on it
will upgrade the connection to a websocket on which notifications will
be sent.
-### GET (`?type=operation,logging`)
+#### GET (`?type=operation,logging`)
* Description: websocket upgrade
* Authentication: trusted
* Operation: sync
@@ -1524,8 +1525,8 @@ This never returns. Each notification is sent as a separate JSON dict:
}
}
-## `/1.0/images`
-### GET
+### `/1.0/images`
+#### GET
* Description: list of images (public or private)
* Authentication: guest or trusted
* Operation: sync
@@ -1540,7 +1541,7 @@ Return:
"/1.0/images/c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
]
-### POST
+#### POST
* Description: create and publish a new image
* Authentication: trusted
* Operation: async
@@ -1626,8 +1627,8 @@ After the input is received by LXD, a background operation is started
which will add the image to the store and possibly do some backend
filesystem-specific optimizations.
-## `/1.0/images/<fingerprint>`
-### GET (optional `?secret=SECRET`)
+### `/1.0/images/<fingerprint>`
+#### GET (optional `?secret=SECRET`)
* Description: Image description and metadata
* Authentication: guest or trusted
* Operation: sync
@@ -1667,7 +1668,7 @@ Output:
"uploaded_at": "2016-02-16T00:44:47Z"
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: Replaces the image properties, update information and visibility
* Authentication: trusted
* Operation: sync
@@ -1686,7 +1687,7 @@ Input:
"public": true,
}
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: Updates the image properties, update information and visibility
* Introduced: with API extension `patch`
* Authentication: trusted
@@ -1703,7 +1704,7 @@ Input:
"public": true,
}
-### DELETE
+#### DELETE
* Description: Remove an image
* Authentication: trusted
* Operation: async
@@ -1716,8 +1717,8 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## `/1.0/images/<fingerprint>/export`
-### GET (optional `?secret=SECRET`)
+### `/1.0/images/<fingerprint>/export`
+#### GET (optional `?secret=SECRET`)
* Description: Download the image tarball
* Authentication: guest or trusted
* Operation: sync
@@ -1731,8 +1732,8 @@ client will `POST` to `/1.0/images/<fingerprint>/export` to get a secret
token which it'll then pass to the target LXD. That target LXD will then
GET the image as a guest, passing the secret token.
-## `/1.0/images/<fingerprint>/refresh`
-### POST
+### `/1.0/images/<fingerprint>/refresh`
+#### POST
* Description: Refresh an image from its origin
* Authentication: trusted
* Operation: async
@@ -1740,8 +1741,8 @@ GET the image as a guest, passing the secret token.
This creates an operation to refresh the specified image from its origin.
-## `/1.0/images/<fingerprint>/secret`
-### POST
+### `/1.0/images/<fingerprint>/secret`
+#### POST
* Description: Generate a random token and tell LXD to expect it be used by a guest
* Authentication: guest or trusted
* Operation: async
@@ -1765,8 +1766,8 @@ The secret is automatically invalidated 5s after an image URL using it
has been accessed. This allows to both retried the image information and
then hit /export with the same secret.
-## `/1.0/images/aliases`
-### GET
+### `/1.0/images/aliases`
+#### GET
* Description: list of aliases (public or private based on image visibility)
* Authentication: guest or trusted
* Operation: sync
@@ -1780,7 +1781,7 @@ Return:
"/1.0/images/aliases/xenial"
]
-### POST
+#### POST
* Description: create a new alias
* Authentication: trusted
* Operation: sync
@@ -1794,8 +1795,8 @@ Input:
"name": "alias-name"
}
-## `/1.0/images/aliases/<name>`
-### GET
+### `/1.0/images/aliases/<name>`
+#### GET
* Description: Alias description and target
* Authentication: guest or trusted
* Operation: sync
@@ -1809,7 +1810,7 @@ Output:
"target": "c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: Replaces the alias target or description
* Authentication: trusted
* Operation: sync
@@ -1822,7 +1823,7 @@ Input:
"target": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
}
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: Updates the alias target or description
* Introduced: with API extension `patch`
* Authentication: trusted
@@ -1835,7 +1836,7 @@ Input:
"description": "New description"
}
-### POST
+#### POST
* Description: rename an alias
* Authentication: trusted
* Operation: sync
@@ -1849,7 +1850,7 @@ Input:
Renaming to an existing name must return the 409 (Conflict) HTTP code.
-### DELETE
+#### DELETE
* Description: Remove an alias
* Authentication: trusted
* Operation: sync
@@ -1860,8 +1861,8 @@ Input (none at present):
{
}
-## `/1.0/networks`
-### GET
+### `/1.0/networks`
+#### GET
* Description: list of networks
* Authentication: trusted
* Operation: sync
@@ -1874,7 +1875,7 @@ Return:
"/1.0/networks/lxdbr0"
]
-### POST
+#### POST
* Description: define a new network
* Introduced: with API extension `network`
* Authentication: trusted
@@ -1893,8 +1894,8 @@ Input:
}
}
-## `/1.0/networks/<name>`
-### GET
+### `/1.0/networks/<name>`
+#### GET
* Description: information about a network
* Authentication: trusted
* Operation: sync
@@ -1912,7 +1913,7 @@ Return:
]
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: replace the network information
* Introduced: with API extension `network`
* Authentication: trusted
@@ -1932,7 +1933,7 @@ Input:
Same dict as used for initial creation and coming from GET. Only the
config is used, everything else is ignored.
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: update the network information
* Introduced: with API extension `network`
* Authentication: trusted
@@ -1947,7 +1948,7 @@ Input:
}
}
-### POST
+#### POST
* Description: rename a network
* Introduced: with API extension `network`
* Authentication: trusted
@@ -1965,7 +1966,7 @@ the renamed resource.
Renaming to an existing name must return the 409 (Conflict) HTTP code.
-### DELETE
+#### DELETE
* Description: remove a network
* Introduced: with API extension `network`
* Authentication: trusted
@@ -1979,8 +1980,8 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## `/1.0/networks/<name>/state`
-### GET
+### `/1.0/networks/<name>/state`
+#### GET
* Description: network state
* Authentication: trusted
* Operation: sync
@@ -2021,8 +2022,8 @@ Return:
"type": "broadcast"
}
-## `/1.0/operations`
-### GET
+### `/1.0/operations`
+#### GET
* Description: list of operations
* Authentication: trusted
* Operation: sync
@@ -2035,8 +2036,8 @@ Return:
"/1.0/operations/092a8755-fd90-4ce4-bf91-9f87d03fd5bc"
]
-## `/1.0/operations/<uuid>`
-### GET
+### `/1.0/operations/<uuid>`
+#### GET
* Description: background operation
* Authentication: trusted
* Operation: sync
@@ -2063,7 +2064,7 @@ Return:
"err": ""
}
-### DELETE
+#### DELETE
* Description: cancel an operation. Calling this will change the state to "cancelling" rather than actually removing the entry.
* Authentication: trusted
* Operation: sync
@@ -2076,8 +2077,8 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## `/1.0/operations/<uuid>/wait`
-### GET (optional `?timeout=30`)
+### `/1.0/operations/<uuid>/wait`
+#### GET (optional `?timeout=30`)
* Description: Wait for an operation to finish
* Authentication: trusted
* Operation: sync
@@ -2087,8 +2088,8 @@ Input (wait indefinitely for a final state): no argument
Input (similar but times out after 30s): ?timeout=30
-## `/1.0/operations/<uuid>/websocket`
-### GET (`?secret=SECRET`)
+### `/1.0/operations/<uuid>/websocket`
+#### GET (`?secret=SECRET`)
* Description: This connection is upgraded into a websocket connection
speaking the protocol defined by the operation type. For example, in the
case of an exec operation, the websocket is the bidirectional pipe for
@@ -2101,8 +2102,8 @@ Input (similar but times out after 30s): ?timeout=30
* Operation: sync
* Return: websocket stream or standard error
-## `/1.0/profiles`
-### GET
+### `/1.0/profiles`
+#### GET
* Description: List of configuration profiles
* Authentication: trusted
* Operation: sync
@@ -2114,7 +2115,7 @@ Return:
"/1.0/profiles/default"
]
-### POST
+#### POST
* Description: define a new profile
* Authentication: trusted
* Operation: sync
@@ -2136,8 +2137,8 @@ Input:
}
}
-## `/1.0/profiles/<name>`
-### GET
+### `/1.0/profiles/<name>`
+#### GET
* Description: profile configuration
* Authentication: trusted
* Operation: sync
@@ -2162,7 +2163,7 @@ Output:
]
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: replace the profile information
* Authentication: trusted
* Operation: sync
@@ -2186,7 +2187,7 @@ Input:
Same dict as used for initial creation and coming from GET. The name
property can't be changed (see POST for that).
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: update the profile information
* Introduced: with API extension `patch`
* Authentication: trusted
@@ -2208,7 +2209,7 @@ Input:
}
}
-### POST
+#### POST
* Description: rename a profile
* Authentication: trusted
* Operation: sync
@@ -2227,7 +2228,7 @@ Renaming to an existing name must return the 409 (Conflict) HTTP code.
Attempting to rename the `default` profile will return the 403 (Forbidden) HTTP code.
-### DELETE
+#### DELETE
* Description: remove a profile
* Authentication: trusted
* Operation: sync
@@ -2242,8 +2243,8 @@ HTTP code for this should be 202 (Accepted).
Attempting to delete the `default` profile will return the 403 (Forbidden) HTTP code.
-## `/1.0/projects`
-### GET
+### `/1.0/projects`
+#### GET
* Description: List of projects
* Introduced: with API extension `projects`
* Authentication: trusted
@@ -2256,7 +2257,7 @@ Return:
"/1.0/projects/default"
]
-### POST
+#### POST
* Description: define a new project
* Introduced: with API extension `projects`
* Authentication: trusted
@@ -2274,8 +2275,8 @@ Input:
"description": "Some description string"
}
-## `/1.0/projects/<name>`
-### GET
+### `/1.0/projects/<name>`
+#### GET
* Description: project configuration
* Introduced: with API extension `projects`
* Authentication: trusted
@@ -2296,7 +2297,7 @@ Output:
]
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: replace the project information
* Introduced: with API extension `projects`
* Authentication: trusted
@@ -2316,7 +2317,7 @@ Input:
Same dict as used for initial creation and coming from GET. The name
property can't be changed (see POST for that).
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: update the project information
* Introduced: with API extension `projects`
* Authentication: trusted
@@ -2332,7 +2333,7 @@ Input:
"description": "Some description string"
}
-### POST
+#### POST
* Description: rename a project
* Introduced: with API extension `projects`
* Authentication: trusted
@@ -2352,7 +2353,7 @@ Renaming to an existing name must return the 409 (Conflict) HTTP code.
Attempting to rename the `default` project will return the 403 (Forbidden) HTTP code.
-### DELETE
+#### DELETE
* Description: remove a project
* Introduced: with API extension `projects`
* Authentication: trusted
@@ -2368,8 +2369,8 @@ HTTP code for this should be 202 (Accepted).
Attempting to delete the `default` project will return the 403 (Forbidden) HTTP code.
-## `/1.0/storage-pools`
-### GET
+### `/1.0/storage-pools`
+#### GET
* Description: list of storage pools
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2386,7 +2387,7 @@ Return:
"/1.0/storage-pools/pool4"
]
-### POST
+#### POST
* Description: create a new storage pool
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2403,8 +2404,8 @@ Input:
"name": "pool1"
}
-## `/1.0/storage-pools/<name>`
-### GET
+### `/1.0/storage-pools/<name>`
+#### GET
* Description: information about a storage pool
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2455,7 +2456,7 @@ Return:
}
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: replace the storage pool information
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2476,7 +2477,7 @@ Return:
}
}
-### PATCH
+#### PATCH
* Description: update the storage pool configuration
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2491,7 +2492,7 @@ Input:
}
}
-### DELETE
+#### DELETE
* Description: delete a storage pool
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2503,8 +2504,8 @@ Input (none at present):
{
}
-## `/1.0/storage-pools/<name>/resources`
-### GET
+### `/1.0/storage-pools/<name>/resources`
+#### GET
* Description: information about the resources available to the storage pool
* Introduced: with API extension `resources`
* Authentication: trusted
@@ -2533,8 +2534,8 @@ Return:
}
-## `/1.0/storage-pools/<name>/volumes`
-### GET
+### `/1.0/storage-pools/<name>/volumes`
+#### GET
* Description: list of storage volumes
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2567,7 +2568,7 @@ Return:
"/1.0/storage-pools/default/volumes/image/62e850a334bb9d99cac00b2e618e0291e5e7bb7db56c4246ecaf8e46fa0631a6"
]
-### POST
+#### POST
* Description: create a new storage volume on a given storage pool
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2609,8 +2610,8 @@ Input (when migrating a volume):
}
}
-## `/1.0/storage-pools/<pool>/volumes/<type>`
-### POST
+### `/1.0/storage-pools/<pool>/volumes/<type>`
+#### POST
* Description: create a new storage volume of a particular type on a given storage pool
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2649,8 +2650,8 @@ Input (when migrating a volume):
}
}
-## `/1.0/storage-pools/<pool>/volumes/<type>/<name>`
-### POST
+### `/1.0/storage-pools/<pool>/volumes/<type>/<name>`
+#### POST
* Description: rename a storage volume on a given storage pool
* Introduced: with API extension `storage_api_volume_rename`
* Authentication: trusted
@@ -2684,7 +2685,7 @@ Output in metadata section (for migration):
These are the secrets that should be passed to the create call.
-### GET
+#### GET
* Description: information about a storage volume of a given type on a storage pool
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2712,7 +2713,7 @@ Return:
}
-### PUT (ETag supported)
+#### PUT (ETag supported)
* Description: replace the storage volume information or restore from snapshot
* Introduced: with API extension `storage`, `storage_api_volume_snapshots`
* Authentication: trusted
@@ -2738,7 +2739,7 @@ Return:
"restore": "snapshot-name"
}
-### PATCH (ETag supported)
+#### PATCH (ETag supported)
* Description: update the storage volume information
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2753,7 +2754,7 @@ Return:
}
}
-### DELETE
+#### DELETE
* Description: delete a storage volume of a given type on a given storage pool
* Introduced: with API extension `storage`
* Authentication: trusted
@@ -2766,8 +2767,8 @@ Input (none at present):
}
-## `/1.0/storage-pools/<pool>/volumes/<type>/<name>/snapshots`
-### GET
+### `/1.0/storage-pools/<pool>/volumes/<type>/<name>/snapshots`
+#### GET
* Description: List of volume snapshots
* Authentication: trusted
* Operation: sync
@@ -2779,7 +2780,7 @@ Return value:
"/1.0/storage-pools/default/volumes/custom/foo/snapshots/snap0"
]
-### POST
+#### POST
* Description: create a new volume snapshot
* Authentication: trusted
* Operation: async
@@ -2791,8 +2792,8 @@ Input:
"name": "my-snapshot", # Name of the snapshot
}
-## `/1.0/storage-pools/<pool>/volumes/<type>/<volume>/snapshots/name`
-### GET
+### `/1.0/storage-pools/<pool>/volumes/<type>/<volume>/snapshots/name`
+#### GET
* Description: Snapshot information
* Authentication: trusted
* Operation: sync
@@ -2806,7 +2807,7 @@ Return:
"name": "snap0"
}
-### PUT
+#### PUT
* Description: Volume snapshot information
* Authentication: trusted
* Operation: sync
@@ -2818,7 +2819,7 @@ Input:
"description": "new-description"
}
-### POST
+#### POST
* Description: used to rename the volume snapshot
* Authentication: trusted
* Operation: async
@@ -2830,7 +2831,7 @@ Input:
"name": "new-name"
}
-### DELETE
+#### DELETE
* Description: remove the volume snapshot
* Authentication: trusted
* Operation: async
@@ -2838,8 +2839,8 @@ Input:
HTTP code for this should be 202 (Accepted).
-## `/1.0/resources`
-### GET
+### `/1.0/resources`
+#### GET
* Description: information about the resources available to the LXD server
* Introduced: with API extension `resources`
* Authentication: guest, untrusted or trusted
@@ -2876,8 +2877,8 @@ Return:
}
}
-## `/1.0/cluster`
-### GET
+### `/1.0/cluster`
+#### GET
* Description: information about a cluster (such as networks and storage pools)
* Introduced: with API extension `clustering`
* Authentication: trusted or untrusted
@@ -2905,7 +2906,7 @@ Return:
],
}
-### PUT
+#### PUT
* Description: bootstrap or join a cluster, or disable clustering on this node
* Introduced: with API extension `clustering`
* Authentication: trusted
@@ -2951,8 +2952,8 @@ Input (disable clustering on the node):
"enabled": false,
}
-## `/1.0/cluster/members`
-### GET
+### `/1.0/cluster/members`
+#### GET
* Description: list of LXD members in the cluster
* Introduced: with API extension `clustering`
* Authentication: trusted
@@ -2966,8 +2967,8 @@ Return:
"/1.0/cluster/members/lxd2"
]
-## `/1.0/cluster/members/<name>`
-### GET
+### `/1.0/cluster/members/<name>`
+#### GET
* Description: retrieve the member's information and status
* Introduced: with API extension `clustering`
* Authentication: trusted
@@ -2983,7 +2984,7 @@ Return:
"state": "Online"
}
-### POST
+#### POST
* Description: rename a cluster member
* Introduced: with API extension `clustering`
* Authentication: trusted
@@ -2996,7 +2997,7 @@ Input:
"server_name": "node1",
}
-### DELETE (optional `?force=1`)
+#### DELETE (optional `?force=1`)
* Description: remove a member of the cluster
* Introduced: with API extension `clustering`
* Authentication: trusted
diff --git a/doc/security.md b/doc/security.md
index 0d3f970880..17bacdc9a5 100644
--- a/doc/security.md
+++ b/doc/security.md
@@ -1,4 +1,5 @@
-# Introduction
+# Security
+## Introduction
Local communications over the UNIX socket happen over a cleartext HTTP
socket and access is restricted by socket ownership and mode.
@@ -22,7 +23,7 @@ certificate for any client-server communication.
To cause certificates to be regenerated, simply remove the old ones. On the
next connection a new certificate will be generated.
-# Adding a remote with a default setup
+## Adding a remote with a default setup
In the default setup, when the user adds a new server with `lxc remote add`,
the server will be contacted over HTTPs, its certificate downloaded and the
fingerprint will be shown to the user.
@@ -46,7 +47,7 @@ a TXT record, then if the domain is signed by DNSSEC, the client will
automatically accept the fingerprint if it matches that in the DNS
record.
-# Adding a remote with a PKI based setup
+## Adding a remote with a PKI based setup
In the PKI setup, a system administrator is managing a central PKI, that
PKI then issues client certificates for all the lxc clients and server
certificates for all the LXD daemons.
@@ -78,7 +79,7 @@ pre-generated files.
After this is done, restarting the server will have it run in PKI mode.
-# Adding a remote with Candid
+## Adding a remote with Candid
When LXD is configured with Candid, it will request that clients trying to
authenticating with it get a Discharge token from the authentication server
specified by the `candid.api.url` setting.
@@ -94,14 +95,14 @@ verifies the token, thus authenticating the request. The token is stored as
cookie and is presented by the client at each request to LXD.
-# Managing trusted clients
+## Managing trusted clients
The list of certificates trusted by a LXD server can be obtained with `lxc
config trust list`.
To revoke trust to a client its certificate can be removed with `lxc config
trust remove FINGERPRINT`.
-# Password prompt
+## Password prompt
To establish a new trust relationship, a password must be set on the
server and send by the client when adding itself.
@@ -115,8 +116,8 @@ A remote add operation should therefore go like this:
trusted.
4. Remote is now ready
-# Failure scenarios
-## Server certificate changes
+## Failure scenarios
+### Server certificate changes
This will typically happen in two cases:
* The server was fully reinstalled and so changed certificate
@@ -132,7 +133,7 @@ can be replaced by the new one or the remote be removed altogether and
re-added.
-## Server trust relationship revoked
+### Server trust relationship revoked
In this case, the server still uses the same certificate but all API
calls return a 403 with an error indicating that the client isn't
trusted.
@@ -141,7 +142,7 @@ This happens if another trusted client or the local server administrator
removed the trust entry on the server.
-# Production setup
+## Production setup
For production setup, it's recommended that `core.trust_password` is unset
after all clients have been added. This prevents brute-force attacks trying to
guess the password.
diff --git a/doc/userns-idmap.md b/doc/userns-idmap.md
index f6daa6dee8..dcd61994c8 100644
--- a/doc/userns-idmap.md
+++ b/doc/userns-idmap.md
@@ -1,4 +1,5 @@
-# Introduction
+# Idmaps for user namespace
+## Introduction
LXD runs safe containers. This is achieved mostly through the use of
user namespaces which make it possible to run containers unprivileged,
greatly limiting the attack surface.
@@ -17,11 +18,11 @@ running as uid 100000.
Allocations should always be of at least 65536 uids and gids to cover
the POSIX range including root (0) and nobody (65534).
-# Kernel support
+## Kernel support
User namespaces require a kernel >= 3.12, LXD will start even on older
kernels but will refuse to start containers.
-# Allowed ranges
+## Allowed ranges
On most hosts, LXD will check `/etc/subuid` and `/etc/subgid` for
allocations for the "lxd" user and on first start, set the default
profile to use the first 65536 uids and gids from that range.
@@ -39,11 +40,11 @@ on a host using an old version of shadow. In this mode, LXD will assume
it can use any uids and gids above 65535 and will take the first 65536
as its default map.
-# Varying ranges between hosts
+## Varying ranges between hosts
The source map is sent when moving containers between hosts so that they
can be remapped on the receiving host.
-# Different idmaps per container
+## Different idmaps per container
LXD supports using different idmaps per container, to further isolate
containers from each other. This is controlled with two per-container
configuration keys, `security.idmap.isolated` and `security.idmap.size`.
@@ -63,7 +64,7 @@ want to use as the base for the container.
These properties require a container reboot to take effect.
-# Custom idmaps
+## Custom idmaps
LXD also supports customizing bits of the idmap, e.g. to allow users to bind
mount parts of the host's filesystem into a container without the need for any
uid-shifting filesystem. The per-container configuration key for this is
More information about the lxc-devel
mailing list