[lxc-devel] [lxd/stable-2.0] doc: add the appropriate titles to some documents
tenforward on Github
lxc-bot at linuxcontainers.org
Thu Oct 18 07:12:55 UTC 2018
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 470 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20181018/7972e21d/attachment.bin>
-------------- next part --------------
From 8338d20199d749bd18b25131efb884d1cd1164ca Mon Sep 17 00:00:00 2001
From: KATOH Yasufumi <karma at jazz.email.ne.jp>
Date: Thu, 18 Oct 2018 16:06:14 +0900
Subject: [PATCH] doc: add the appropriate titles to some documents
This is same as 906114c on master branch. The first level header now
represents the contents of each document.
Signed-off-by: KATOH Yasufumi <karma at jazz.email.ne.jp>
---
doc/architectures.md | 6 +-
doc/configuration.md | 2 +-
doc/contributing.md | 7 +-
doc/daemon-behavior.md | 13 +--
doc/database.md | 45 +++++-----
doc/debugging.md | 2 +
doc/dev-lxd.md | 35 ++++----
doc/environment.md | 9 +-
doc/image-handling.md | 17 ++--
doc/production-setup.md | 23 ++---
doc/rest-api.md | 189 ++++++++++++++++++++--------------------
doc/security.md | 17 ++--
doc/userns-idmap.md | 13 +--
13 files changed, 196 insertions(+), 182 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 a1be2d00ba..96a3834e5a 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..6b6da4af78 100644
--- a/doc/contributing.md
+++ b/doc/contributing.md
@@ -1,4 +1,5 @@
-# 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 +8,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 +17,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..e28705901d 100644
--- a/doc/daemon-behavior.md
+++ b/doc/daemon-behavior.md
@@ -1,9 +1,10 @@
-# 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 +14,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 +32,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 a47e51cb59..533b9f2c2b 100644
--- a/doc/database.md
+++ b/doc/database.md
@@ -1,4 +1,5 @@
-# Introduction
+# Database
+## Introduction
So first of all, why a database?
Rather than keeping the configuration and state within each container's
@@ -18,7 +19,7 @@ database, it's only a matter of accessing the already cached database
with a pretty simple query.
-# Database engine
+## Database engine
As this is a purely internal database with a single client and very
little data, we'll be using sqlite3.
@@ -28,7 +29,7 @@ database accessible when the compute node itself isn't, wouldn't be
terribly useful.
-# Design
+## Design
The design of the database is made to be as close as possible to
the [RESTful API](rest-api.md).
@@ -45,7 +46,7 @@ may cause a schema update and data being shuffled. In those cases, LXD
will make a copy of the old database as ".old" to allow for a revert.
-# Tables
+## Tables
The list of tables is:
* certificates
@@ -74,12 +75,12 @@ You'll notice that compared to the REST API, there are three main differences:
of a container at a given point in time, including its configuration and
on-disk state. So having snapshots in a separate table would only be needless duplication.
-# Notes on sqlite3
+## Notes on sqlite3
sqlite3 only supports 5 storage classes: NULL, INTEGER, REAL, TEXT and BLOB
There are then a set of aliases for each of those storage classes which is what we use below.
-# Schema
-## certificates
+## Schema
+### certificates
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -92,7 +93,7 @@ certificate | TEXT | - | NOT NULL | PEM encode
Index: UNIQUE ON id AND fingerprint
-## config (server configuration)
+### config (server configuration)
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -103,7 +104,7 @@ value | TEXT | - | | Configurat
Index: UNIQUE ON id AND key
-## containers
+### containers
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -118,7 +119,7 @@ creation\_date | DATETIME | - | | Image crea
Index: UNIQUE ON id AND name
-## containers\_config
+### containers\_config
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -132,7 +133,7 @@ Index: UNIQUE ON id AND container\_id + key
Foreign keys: container\_id REFERENCES containers(id)
-## containers\_devices
+### containers\_devices
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -146,7 +147,7 @@ Index: UNIQUE ON id AND container\_id + name
Foreign keys: container\_id REFERENCES containers(id)
-## containers\_devices\_config
+### containers\_devices\_config
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -160,7 +161,7 @@ Index: UNIQUE ON id AND container\_device\_id + key
Foreign keys: container\_device\_id REFERENCES containers\_devices(id)
-## containers\_profiles
+### containers\_profiles
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -174,7 +175,7 @@ Index: UNIQUE ON id AND container\_id + profile\_id
Foreign keys: container\_id REFERENCES containers(id) and profile\_id REFERENCES profiles(id)
-## images
+### images
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -194,7 +195,7 @@ last\_use\_date | DATETIME | - | | Last time
Index: UNIQUE ON id AND fingerprint
-## images\_aliases
+### images\_aliases
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -208,7 +209,7 @@ Index: UNIQUE ON id AND name
Foreign keys: image\_id REFERENCES images(id)
-## images\_properties
+### images\_properties
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -222,7 +223,7 @@ Index: UNIQUE ON id
Foreign keys: image\_id REFERENCES images(id)
-## images\_source
+### images\_source
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -237,7 +238,7 @@ Index: UNIQUE ON id
Foreign keys: image\_id REFERENCES images(id)
-## profiles
+### profiles
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -248,7 +249,7 @@ description | TEXT | - | | Descriptio
Index: UNIQUE on id AND name
-## profiles\_config
+### profiles\_config
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -262,7 +263,7 @@ Index: UNIQUE ON id AND profile\_id + key
Foreign keys: profile\_id REFERENCES profiles(id)
-## profiles\_devices
+### profiles\_devices
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -276,7 +277,7 @@ Index: UNIQUE ON id AND profile\_id + name
Foreign keys: profile\_id REFERENCES profiles(id)
-## profiles\_devices\_config
+### profiles\_devices\_config
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
@@ -290,7 +291,7 @@ Index: UNIQUE ON id AND profile\_device\_id + key
Foreign keys: profile\_device\_id REFERENCES profiles\_devices(id)
-## schema
+### schema
Column | Type | Default | Constraint | Description
:----- | :--- | :------ | :--------- | :----------
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 205f79e669..d451dcc841 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,30 +21,30 @@ 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
* /1.0/config/{key}
* /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']`)
@@ -54,8 +55,8 @@ Return value:
"/1.0"
]
```
-### `/1.0`
-#### GET
+#### `/1.0`
+##### GET
* Description: Information about the 1.0 API
* Return: dict
@@ -66,8 +67,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
@@ -86,8 +87,8 @@ Return value:
]
```
-### `/1.0/config/<KEY>`
-#### GET
+#### `/1.0/config/<KEY>`
+##### GET
* Description: Value of that key
* Return: Plain-text value
@@ -95,8 +96,8 @@ Return value:
blah
-### `/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 fae35be819..1db917efc0 100644
--- a/doc/environment.md
+++ b/doc/environment.md
@@ -1,8 +1,9 @@
-# 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
@@ -11,13 +12,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 1ef4877253..325775c9bc 100644
--- a/doc/image-handling.md
+++ b/doc/image-handling.md
@@ -1,4 +1,5 @@
-# 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 +9,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 +20,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`.
@@ -36,7 +37,7 @@ image is removed from the store.
The user can also request a particular image be kept up to date when
manually copying an image from a remote server.
-# Image format
+## Image format
LXD currently supports two LXD-specific image formats.
The first is a unified tarball, where a single tarball
@@ -51,7 +52,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/`
@@ -60,7 +61,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:
@@ -73,11 +74,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 90e83bc956..6ca26f972d 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`
@@ -17,8 +18,8 @@ using containers that require tens of thousands of file operations.
`failed to open stream: Too many open files in...`
-# Server Changes
-## /etc/security/limits.conf
+## Server Changes
+### /etc/security/limits.conf
Domain | Type | Item | Value | Default | Description
:----- | :--- | :---- | :-------- | :-------- | :----------
@@ -30,7 +31,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
:----- | :--- | :--- | :---
@@ -46,12 +47,12 @@ Then, reboot the server.
[1]: http://man7.org/linux/man-pages/man7/inotify.7.html
-## 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`
@@ -67,7 +68,7 @@ ifconfig lxdbr0 txqueuelen 10000
If you use lxd master in production or find this inappropriate you can set in `rc.local` or in another way you like.
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)
@@ -75,13 +76,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 501d8ad181..ad4d07de9a 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.
-# API structure
+## API structure
* `/`
* `/1.0`
* `/1.0/certificates`
@@ -193,9 +194,9 @@ have to then poll for their status.
* `/1.0/profiles`
* `/1.0/profiles/<name>`
-# API details
-## `/`
-### GET
+## API details
+### `/`
+#### GET
* Description: List of supported APIs
* Authentication: guest
* Operation: sync
@@ -207,8 +208,8 @@ Return value:
"/1.0"
]
-## `/1.0/`
-### GET
+### `/1.0/`
+#### GET
* Description: Server configuration and environment information
* Authentication: guest, untrusted or trusted
* Operation: sync
@@ -259,7 +260,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
+#### PUT
* Description: Updates the server configuration or other properties
* Authentication: trusted
* Operation: sync
@@ -275,8 +276,8 @@ Input (replaces any existing config with the provided one):
}
-## `/1.0/certificates`
-### GET
+### `/1.0/certificates`
+#### GET
* Description: list of trusted certificates
* Authentication: trusted
* Operation: sync
@@ -288,7 +289,7 @@ Return:
"/1.0/certificates/3ee64be3c3c7d617a7470e14f2d847081ad467c8c26e1caad841c8f67f7c7b09"
]
-### POST
+#### POST
* Description: add a new trusted certificate
* Authentication: trusted or untrusted
* Operation: sync
@@ -303,8 +304,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
@@ -319,7 +320,7 @@ Output:
"fingerprint": "SHA256 Hash of the raw certificate"
}
-### DELETE
+#### DELETE
* Description: Remove a trusted certificate
* Authentication: trusted
* Operation: sync
@@ -332,8 +333,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
@@ -346,7 +347,7 @@ Return value:
"/1.0/containers/blah1"
]
-### POST
+#### POST
* Description: Create a new container
* Authentication: trusted
* Operation: async
@@ -513,8 +514,8 @@ Input (using a local container):
"source": "my-old-container"} # Name of the source container
}
-## `/1.0/containers/<name>`
-### GET
+### `/1.0/containers/<name>`
+#### GET
* Description: Container information
* Authentication: trusted
* Operation: sync
@@ -564,7 +565,7 @@ Output:
}
-### PUT
+#### PUT
* Description: update container configuration or restore snapshot
* Authentication: trusted
* Operation: async
@@ -601,7 +602,7 @@ Input (restore snapshot):
"restore": "snapshot-name"
}
-### POST
+#### POST
* Description: used to rename/migrate the container
* Authentication: trusted
* Operation: async
@@ -634,7 +635,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
@@ -647,8 +648,8 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## `/1.0/containers/<name>/exec`
-### POST
+### `/1.0/containers/<name>/exec`
+#### POST
* Description: run a remote command
* Authentication: trusted
* Operation: async
@@ -720,8 +721,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 from the container
* Authentication: trusted
* Operation: sync
@@ -736,7 +737,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
@@ -754,8 +755,8 @@ 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.
-## `/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.
@@ -771,21 +772,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>/snapshots`
-### GET
+### `/1.0/containers/<name>/snapshots`
+#### GET
* Description: List of snapshots
* Authentication: trusted
* Operation: sync
@@ -797,7 +798,7 @@ Return value:
"/1.0/containers/blah/snapshots/snap0"
]
-### POST
+#### POST
* Description: create a new snapshot
* Authentication: trusted
* Operation: async
@@ -810,8 +811,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
@@ -866,7 +867,7 @@ Return:
"stateful": false
}
-### POST
+#### POST
* Description: used to rename/migrate the snapshot
* Authentication: trusted
* Operation: async
@@ -893,7 +894,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
@@ -906,8 +907,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
@@ -1054,7 +1055,7 @@ Output:
}
}
-### PUT
+#### PUT
* Description: change the container state
* Authentication: trusted
* Operation: async
@@ -1069,12 +1070,12 @@ 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/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
@@ -1111,8 +1112,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
@@ -1127,7 +1128,7 @@ Return:
"/1.0/images/c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
]
-### POST
+#### POST
* Description: create and publish a new image
* Authentication: trusted
* Operation: async
@@ -1200,8 +1201,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
@@ -1241,7 +1242,7 @@ Output:
"uploaded_at": "2016-02-16T00:44:47Z"
}
-### PUT
+#### PUT
* Description: Updates the image properties
* Authentication: trusted
* Operation: sync
@@ -1260,7 +1261,7 @@ Input:
"public": true,
}
-### DELETE
+#### DELETE
* Description: Remove an image
* Authentication: trusted
* Operation: async
@@ -1273,8 +1274,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
@@ -1288,8 +1289,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>/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
@@ -1313,8 +1314,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
@@ -1328,7 +1329,7 @@ Return:
"/1.0/images/aliases/xenial"
]
-### POST
+#### POST
* Description: create a new alias
* Authentication: trusted
* Operation: sync
@@ -1342,8 +1343,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
@@ -1357,7 +1358,7 @@ Output:
"target": "c9b6e738fae75286d52f497415463a8ecc61bbcb046536f220d797b0e500a41f"
}
-### PUT
+#### PUT
* Description: Updates the alias target or description
* Authentication: trusted
* Operation: sync
@@ -1370,7 +1371,7 @@ Input:
"target": "54c8caac1f61901ed86c68f24af5f5d3672bdc62c71d04f06df3a59e95684473"
}
-### POST
+#### POST
* Description: rename an alias
* Authentication: trusted
* Operation: sync
@@ -1384,7 +1385,7 @@ Input:
Renaming to an existing name must return the 409 (Conflict) HTTP code.
-### DELETE
+#### DELETE
* Description: Remove an alias
* Authentication: trusted
* Operation: sync
@@ -1395,8 +1396,8 @@ Input (none at present):
{
}
-## `/1.0/networks`
-### GET
+### `/1.0/networks`
+#### GET
* Description: list of networks
* Authentication: trusted
* Operation: sync
@@ -1409,8 +1410,8 @@ Return:
"/1.0/networks/lxdbr0"
]
-## `/1.0/networks/<name>`
-### GET
+### `/1.0/networks/<name>`
+#### GET
* Description: information about a network
* Authentication: trusted
* Operation: sync
@@ -1426,8 +1427,8 @@ Return:
]
}
-## `/1.0/operations`
-### GET
+### `/1.0/operations`
+#### GET
* Description: list of operations
* Authentication: trusted
* Operation: sync
@@ -1440,8 +1441,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
@@ -1468,7 +1469,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
@@ -1481,8 +1482,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
@@ -1492,8 +1493,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
@@ -1506,8 +1507,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
@@ -1519,7 +1520,7 @@ Return:
"/1.0/profiles/default"
]
-### POST
+#### POST
* Description: define a new profile
* Authentication: trusted
* Operation: sync
@@ -1541,8 +1542,8 @@ Input:
}
}
-## `/1.0/profiles/<name>`
-### GET
+### `/1.0/profiles/<name>`
+#### GET
* Description: profile configuration
* Authentication: trusted
* Operation: sync
@@ -1564,7 +1565,7 @@ Output:
}
}
-### PUT
+#### PUT
* Description: update the profile
* Authentication: trusted
* Operation: sync
@@ -1589,7 +1590,7 @@ Same dict as used for initial creation and coming from GET. The name
property can't be changed (see POST for that).
-### POST
+#### POST
* Description: rename a profile
* Authentication: trusted
* Operation: sync
@@ -1606,7 +1607,7 @@ the renamed resource.
Renaming to an existing name must return the 409 (Conflict) HTTP code.
-### DELETE
+#### DELETE
* Description: remove a profile
* Authentication: trusted
* Operation: sync
diff --git a/doc/security.md b/doc/security.md
index 3166ad4f75..011c1f8b5a 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,14 +47,14 @@ 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.
-# 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.
@@ -67,8 +68,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
@@ -84,7 +85,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.
@@ -93,7 +94,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 6421580875..4754c0eec3 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