The following pull request was submitted through Github. It can be accessed and reviewed at: https://github.com/lxc/lxd/pull/5173
This e-mail was sent by the LXC bot, direct replies will not reach the author unless they happen to be subscribed to this list. === Description (from pull-request) === 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 <ka...@jazz.email.ne.jp>
From 906114c8c7db9efab2e7c96cbb82d7834c1e174d Mon Sep 17 00:00:00 2001 From: KATOH Yasufumi <ka...@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 <ka...@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
_______________________________________________ lxc-devel mailing list lxc-devel@lists.linuxcontainers.org http://lists.linuxcontainers.org/listinfo/lxc-devel