[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