[lxc-devel] [lxd/stable-2.0] Backport the read-the-docs documentation fixes
albertodonato on Github
lxc-bot at linuxcontainers.org
Wed Oct 4 09:34:57 UTC 2017
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 301 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20171004/73f668cb/attachment.bin>
-------------- next part --------------
From bd039dc37ff2e413c050b7804d665c972bb1d80e Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Wed, 4 Oct 2017 10:30:59 +0200
Subject: [PATCH 01/23] doc: move README.md to doc/index.md and add link as
README.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
README.md | 239 +----------------------------------------------------------
doc/index.md | 238 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 239 insertions(+), 238 deletions(-)
mode change 100644 => 120000 README.md
create mode 100644 doc/index.md
diff --git a/README.md b/README.md
deleted file mode 100644
index fce6613f4..000000000
--- a/README.md
+++ /dev/null
@@ -1,238 +0,0 @@
-[](https://linuxcontainers.org/lxd)
-# LXD
-LXD is a next generation system container manager.
-It offers a user experience similar to virtual machines but using Linux containers instead.
-
-It's image based with pre-made images available for a [wide number of Linux distributions](https://images.linuxcontainers.org)
-and is built around a very powerful, yet pretty simple, REST API.
-
-To get a better idea of what LXD is and what it does, you can [try it online](https://linuxcontainers.org/lxd/try-it/)!
-Then if you want to run it locally, take a look at our [getting started guide](https://linuxcontainers.org/lxd/getting-started-cli/).
-
-Release announcements can be found here: https://linuxcontainers.org/lxd/news/
-And the release tarballs here: https://linuxcontainers.org/lxd/downloads/
-
-## Status
-Type | Service | Status
---- | --- | ---
-CI (Linux) | Jenkins | [](https://jenkins.linuxcontainers.org/job/lxd-github-commit-stable-2.0/)
-CI (macOS) | Travis | [](https://travis-ci.org/lxc/lxd/)
-CI (Windows) | AppVeyor | [](https://ci.appveyor.com/project/lxc/lxd/)
-Documentation | Godoc | [](https://godoc.org/github.com/lxc/lxd/client)
-Static analysis | GoReport | [](https://goreportcard.com/report/github.com/lxc/lxd)
-Translations | Weblate | [](https://hosted.weblate.org/projects/linux-containers/lxd/)
-Project status | CII Best Practices | [](https://bestpractices.coreinfrastructure.org/projects/1086)
-
-## Installing LXD from packages
-Instructions on installing LXD for a wide variety of Linux distributions and operating systems [can be found on our website](https://linuxcontainers.org/lxd/getting-started-cli/).
-
-## Installing LXD from source
-We recommend having the latest versions of liblxc (>= 2.0.0 required) and CRIU
-(>= 1.7 recommended) available for LXD development. Additionally, LXD requires
-Golang 1.5 or later to work. On ubuntu, you can get those with:
-
- sudo apt update
- sudo apt install acl dnsmasq-base git golang liblxc1 lxc-dev libacl1-dev make pkg-config rsync squashfs-tools tar xz-utils
-
-There are a few storage backends for LXD besides the default "directory" backend.
-Installing these tools adds a bit to initramfs and may slow down your
-host boot, but are needed if you'd like to use a particular backend:
-
- sudo apt install lvm2 thin-provisioning-tools
- sudo apt install btrfs-tools
-
-To run the testsuite, you'll also need:
-
- sudo apt install curl gettext jq sqlite3 uuid-runtime bzr
-
-
-### Building the tools
-LXD consists of two binaries, a client called `lxc` and a server called `lxd`.
-These live in the source tree in the `lxc/` and `lxd/` dirs, respectively.
-To get the code, set up your go environment:
-
- mkdir -p ~/go
- export GOPATH=~/go
-
-And then download it as usual:
-
- go get github.com/lxc/lxd
- cd $GOPATH/src/github.com/lxc/lxd
- make
-
-...which will give you two binaries in $GOPATH/bin, `lxd` the daemon binary,
-and `lxc` a command line client to that daemon.
-
-### Machine Setup
-You'll need sub{u,g}ids for root, so that LXD can create the unprivileged
-containers:
-
- echo "root:1000000:65536" | sudo tee -a /etc/subuid /etc/subgid
-
-Now you can run the daemon (the --group sudo bit allows everyone in the sudo
-group to talk to LXD; you can create your own group if you want):
-
- sudo -E $GOPATH/bin/lxd --group sudo
-
-## Getting started with LXD
-Now that you have LXD running on your system you can read the [getting started guide](https://linuxcontainers.org/lxd/getting-started-cli/) or go through more examples and configurations in [our documentation](https://github.com/lxc/lxd/tree/master/doc).
-
-## Bug reports
-Bug reports can be filed at: https://github.com/lxc/lxd/issues/new
-
-## Contributing
-Fixes and new features are greatly appreciated but please read our [contributing guidelines](CONTRIBUTING.md) first.
-
-## Support and discussions
-### Forum
-A discussion forum is available at: https://discuss.linuxcontainers.org
-
-### Mailing-lists
-We use the LXC mailing-lists for developer and user discussions, you can
-find and subscribe to those at: https://lists.linuxcontainers.org
-
-### IRC
-If you prefer live discussions, some of us also hang out in
-[#lxcontainers](http://webchat.freenode.net/?channels=#lxcontainers) on irc.freenode.net.
-
-## FAQ
-#### How to enable LXD server for remote access?
-By default LXD server is not accessible from the networks as it only listens
-on a local unix socket. You can make LXD available from the network by specifying
-additional addresses to listen to. This is done with the `core.https_address`
-config variable.
-
-To see the current server configuration, run:
-
- lxc config show
-
-To set the address to listen to, find out what addresses are available and use
-the `config set` command on the server:
-
- ip addr
- lxc config set core.https_address 192.168.1.15
-
-#### When I do a `lxc remote add` over https, it asks for a password?
-By default, LXD has no password for security reasons, so you can't do a remote
-add this way. In order to set a password, do:
-
- lxc config set core.trust_password SECRET
-
-on the host LXD is running on. This will set the remote password that you can
-then use to do `lxc remote add`.
-
-You can also access the server without setting a password by copying the client
-certificate from `.config/lxc/client.crt` to the server and adding it with:
-
- lxc config trust add client.crt
-
-
-#### How do I configure LXD storage?
-LXD supports btrfs, directory, lvm and zfs based storage.
-
-First make sure you have the relevant tools for your filesystem of
-choice installed on the machine (btrfs-progs, lvm2 or zfsutils-linux).
-
-You can get a basic configuration done with:
-
- lxd init
-
-"lxd init" supports both directory based storage and ZFS.
-
-"btrfs" is automatically setup if /var/lib/lxd is stored on btrfs.
-
-For LVM, you can set the "storage.lvm\_vg\_name" key to a valid LVM volume group.
-
-For production environments, you should be using block backed storage
-instead both for performance and reliability reasons.
-
-#### How can I live migrate a container using LXD?
-Live migration requires a tool installed on both hosts called
-[CRIU](http://criu.org), which is available in Ubuntu via:
-
- sudo apt-get install criu
-
-Then, launch your container with the following,
-
- lxc launch ubuntu $somename
- sleep 5s # let the container get to an interesting state
- lxc move host1:$somename host2:$somename
-
-And with luck you'll have migrated the container :). Migration is still in
-experimental stages and may not work for all workloads. Please report bugs on
-lxc-devel, and we can escalate to CRIU lists as necessary.
-
-#### Can I bind mount my home directory in a container?
-Yes. The easiest way to do that is using a privileged container to avoid file ownership issues:
-
-1.a) create a container.
-
- lxc launch ubuntu privilegedContainerName -c security.privileged=true
-
-1.b) or, if your container already exists.
-
- lxc config set privilegedContainerName security.privileged true
-2) then.
-
- lxc config device add privilegedContainerName shareName disk source=/home/$USER path=/home/ubuntu
-
-#### How can I run docker inside a LXD container?
-In order to run Docker inside a LXD container the `security.nesting` property of the container should be set to `true`.
-
- lxc config set <container> security.nesting true
-
-Note that LXD containers cannot load kernel modules, so depending on your Docker configuration
-you may need to have the needed extra kernel modules loaded by the host.
-
-You can do so by setting a comma seperate list of kernel modules that your container needs with:
-
- lxc config set <container> linux.kernel_modules <modules>
-
-We have also received some reports that creating a "/.dockerenv" file in your container
-can help Docker ignore some errors it's getting due to running in a nested environment.
-
-## Hacking on LXD
-### Directly using the REST API
-The LXD REST API can be used locally via unauthenticated Unix socket or remotely via SSL encapsulated TCP.
-
-#### Via Unix socket
-```bash
-curl --unix-socket /var/lib/lxd/unix.socket \
- -H "Content-Type: application/json" \
- -X POST \
- -d @hello-ubuntu.json \
- lxd/1.0/containers
-```
-
-#### Via TCP
-TCP requires some additional configuration and is not enabled by default.
-```bash
-lxc config set core.https_address "[::]:8443"
-```
-```bash
-curl -k -L \
- --cert ~/.config/lxc/client.crt \
- --key ~/.config/lxc/client.key \
- -H "Content-Type: application/json" \
- -X POST \
- -d @hello-ubuntu.json \
- "https://127.0.0.1:8443/1.0/containers"
-```
-#### JSON payload
-The `hello-ubuntu.json` file referenced above could contain something like:
-```json
-{
- "name":"some-ubuntu",
- "ephemeral":true,
- "config":{
- "limits.cpu":"2"
- },
- "source": {
- "type":"image",
- "mode":"pull",
- "protocol":"simplestreams",
- "server":"https://cloud-images.ubuntu.com/releases",
- "alias":"14.04"
- }
-}
-```
diff --git a/README.md b/README.md
new file mode 120000
index 000000000..456d7bbe8
--- /dev/null
+++ b/README.md
@@ -0,0 +1 @@
+doc/index.md
\ No newline at end of file
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 000000000..fce6613f4
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,238 @@
+[](https://linuxcontainers.org/lxd)
+# LXD
+LXD is a next generation system container manager.
+It offers a user experience similar to virtual machines but using Linux containers instead.
+
+It's image based with pre-made images available for a [wide number of Linux distributions](https://images.linuxcontainers.org)
+and is built around a very powerful, yet pretty simple, REST API.
+
+To get a better idea of what LXD is and what it does, you can [try it online](https://linuxcontainers.org/lxd/try-it/)!
+Then if you want to run it locally, take a look at our [getting started guide](https://linuxcontainers.org/lxd/getting-started-cli/).
+
+Release announcements can be found here: https://linuxcontainers.org/lxd/news/
+And the release tarballs here: https://linuxcontainers.org/lxd/downloads/
+
+## Status
+Type | Service | Status
+--- | --- | ---
+CI (Linux) | Jenkins | [](https://jenkins.linuxcontainers.org/job/lxd-github-commit-stable-2.0/)
+CI (macOS) | Travis | [](https://travis-ci.org/lxc/lxd/)
+CI (Windows) | AppVeyor | [](https://ci.appveyor.com/project/lxc/lxd/)
+Documentation | Godoc | [](https://godoc.org/github.com/lxc/lxd/client)
+Static analysis | GoReport | [](https://goreportcard.com/report/github.com/lxc/lxd)
+Translations | Weblate | [](https://hosted.weblate.org/projects/linux-containers/lxd/)
+Project status | CII Best Practices | [](https://bestpractices.coreinfrastructure.org/projects/1086)
+
+## Installing LXD from packages
+Instructions on installing LXD for a wide variety of Linux distributions and operating systems [can be found on our website](https://linuxcontainers.org/lxd/getting-started-cli/).
+
+## Installing LXD from source
+We recommend having the latest versions of liblxc (>= 2.0.0 required) and CRIU
+(>= 1.7 recommended) available for LXD development. Additionally, LXD requires
+Golang 1.5 or later to work. On ubuntu, you can get those with:
+
+ sudo apt update
+ sudo apt install acl dnsmasq-base git golang liblxc1 lxc-dev libacl1-dev make pkg-config rsync squashfs-tools tar xz-utils
+
+There are a few storage backends for LXD besides the default "directory" backend.
+Installing these tools adds a bit to initramfs and may slow down your
+host boot, but are needed if you'd like to use a particular backend:
+
+ sudo apt install lvm2 thin-provisioning-tools
+ sudo apt install btrfs-tools
+
+To run the testsuite, you'll also need:
+
+ sudo apt install curl gettext jq sqlite3 uuid-runtime bzr
+
+
+### Building the tools
+LXD consists of two binaries, a client called `lxc` and a server called `lxd`.
+These live in the source tree in the `lxc/` and `lxd/` dirs, respectively.
+To get the code, set up your go environment:
+
+ mkdir -p ~/go
+ export GOPATH=~/go
+
+And then download it as usual:
+
+ go get github.com/lxc/lxd
+ cd $GOPATH/src/github.com/lxc/lxd
+ make
+
+...which will give you two binaries in $GOPATH/bin, `lxd` the daemon binary,
+and `lxc` a command line client to that daemon.
+
+### Machine Setup
+You'll need sub{u,g}ids for root, so that LXD can create the unprivileged
+containers:
+
+ echo "root:1000000:65536" | sudo tee -a /etc/subuid /etc/subgid
+
+Now you can run the daemon (the --group sudo bit allows everyone in the sudo
+group to talk to LXD; you can create your own group if you want):
+
+ sudo -E $GOPATH/bin/lxd --group sudo
+
+## Getting started with LXD
+Now that you have LXD running on your system you can read the [getting started guide](https://linuxcontainers.org/lxd/getting-started-cli/) or go through more examples and configurations in [our documentation](https://github.com/lxc/lxd/tree/master/doc).
+
+## Bug reports
+Bug reports can be filed at: https://github.com/lxc/lxd/issues/new
+
+## Contributing
+Fixes and new features are greatly appreciated but please read our [contributing guidelines](CONTRIBUTING.md) first.
+
+## Support and discussions
+### Forum
+A discussion forum is available at: https://discuss.linuxcontainers.org
+
+### Mailing-lists
+We use the LXC mailing-lists for developer and user discussions, you can
+find and subscribe to those at: https://lists.linuxcontainers.org
+
+### IRC
+If you prefer live discussions, some of us also hang out in
+[#lxcontainers](http://webchat.freenode.net/?channels=#lxcontainers) on irc.freenode.net.
+
+## FAQ
+#### How to enable LXD server for remote access?
+By default LXD server is not accessible from the networks as it only listens
+on a local unix socket. You can make LXD available from the network by specifying
+additional addresses to listen to. This is done with the `core.https_address`
+config variable.
+
+To see the current server configuration, run:
+
+ lxc config show
+
+To set the address to listen to, find out what addresses are available and use
+the `config set` command on the server:
+
+ ip addr
+ lxc config set core.https_address 192.168.1.15
+
+#### When I do a `lxc remote add` over https, it asks for a password?
+By default, LXD has no password for security reasons, so you can't do a remote
+add this way. In order to set a password, do:
+
+ lxc config set core.trust_password SECRET
+
+on the host LXD is running on. This will set the remote password that you can
+then use to do `lxc remote add`.
+
+You can also access the server without setting a password by copying the client
+certificate from `.config/lxc/client.crt` to the server and adding it with:
+
+ lxc config trust add client.crt
+
+
+#### How do I configure LXD storage?
+LXD supports btrfs, directory, lvm and zfs based storage.
+
+First make sure you have the relevant tools for your filesystem of
+choice installed on the machine (btrfs-progs, lvm2 or zfsutils-linux).
+
+You can get a basic configuration done with:
+
+ lxd init
+
+"lxd init" supports both directory based storage and ZFS.
+
+"btrfs" is automatically setup if /var/lib/lxd is stored on btrfs.
+
+For LVM, you can set the "storage.lvm\_vg\_name" key to a valid LVM volume group.
+
+For production environments, you should be using block backed storage
+instead both for performance and reliability reasons.
+
+#### How can I live migrate a container using LXD?
+Live migration requires a tool installed on both hosts called
+[CRIU](http://criu.org), which is available in Ubuntu via:
+
+ sudo apt-get install criu
+
+Then, launch your container with the following,
+
+ lxc launch ubuntu $somename
+ sleep 5s # let the container get to an interesting state
+ lxc move host1:$somename host2:$somename
+
+And with luck you'll have migrated the container :). Migration is still in
+experimental stages and may not work for all workloads. Please report bugs on
+lxc-devel, and we can escalate to CRIU lists as necessary.
+
+#### Can I bind mount my home directory in a container?
+Yes. The easiest way to do that is using a privileged container to avoid file ownership issues:
+
+1.a) create a container.
+
+ lxc launch ubuntu privilegedContainerName -c security.privileged=true
+
+1.b) or, if your container already exists.
+
+ lxc config set privilegedContainerName security.privileged true
+2) then.
+
+ lxc config device add privilegedContainerName shareName disk source=/home/$USER path=/home/ubuntu
+
+#### How can I run docker inside a LXD container?
+In order to run Docker inside a LXD container the `security.nesting` property of the container should be set to `true`.
+
+ lxc config set <container> security.nesting true
+
+Note that LXD containers cannot load kernel modules, so depending on your Docker configuration
+you may need to have the needed extra kernel modules loaded by the host.
+
+You can do so by setting a comma seperate list of kernel modules that your container needs with:
+
+ lxc config set <container> linux.kernel_modules <modules>
+
+We have also received some reports that creating a "/.dockerenv" file in your container
+can help Docker ignore some errors it's getting due to running in a nested environment.
+
+## Hacking on LXD
+### Directly using the REST API
+The LXD REST API can be used locally via unauthenticated Unix socket or remotely via SSL encapsulated TCP.
+
+#### Via Unix socket
+```bash
+curl --unix-socket /var/lib/lxd/unix.socket \
+ -H "Content-Type: application/json" \
+ -X POST \
+ -d @hello-ubuntu.json \
+ lxd/1.0/containers
+```
+
+#### Via TCP
+TCP requires some additional configuration and is not enabled by default.
+```bash
+lxc config set core.https_address "[::]:8443"
+```
+```bash
+curl -k -L \
+ --cert ~/.config/lxc/client.crt \
+ --key ~/.config/lxc/client.key \
+ -H "Content-Type: application/json" \
+ -X POST \
+ -d @hello-ubuntu.json \
+ "https://127.0.0.1:8443/1.0/containers"
+```
+#### JSON payload
+The `hello-ubuntu.json` file referenced above could contain something like:
+```json
+{
+ "name":"some-ubuntu",
+ "ephemeral":true,
+ "config":{
+ "limits.cpu":"2"
+ },
+ "source": {
+ "type":"image",
+ "mode":"pull",
+ "protocol":"simplestreams",
+ "server":"https://cloud-images.ubuntu.com/releases",
+ "alias":"14.04"
+ }
+}
+```
From 2ef2c3a168451ef540d3229843aeb8e9f9363e31 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 10:21:08 +0200
Subject: [PATCH 02/23] doc: move CONTRIBUTING.md to doc/contributing.md and
add link in base dir
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
contributing.md | 1 +
CONTRIBUTING.md => doc/contributing.md | 0
2 files changed, 1 insertion(+)
create mode 120000 contributing.md
rename CONTRIBUTING.md => doc/contributing.md (100%)
diff --git a/contributing.md b/contributing.md
new file mode 120000
index 000000000..9308b99b2
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1 @@
+doc/contributing.md
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/doc/contributing.md
similarity index 100%
rename from CONTRIBUTING.md
rename to doc/contributing.md
From 165013d8d2ad827256d843778a39dd25b6b961f8 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 10:03:24 +0200
Subject: [PATCH 03/23] doc: fixes in index.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/index.md | 135 +++++++++++++++++++++++++++++++++++++++--------------------
1 file changed, 90 insertions(+), 45 deletions(-)
diff --git a/doc/index.md b/doc/index.md
index fce6613f4..0d7fcc362 100644
--- a/doc/index.md
+++ b/doc/index.md
@@ -9,8 +9,8 @@ and is built around a very powerful, yet pretty simple, REST API.
To get a better idea of what LXD is and what it does, you can [try it online](https://linuxcontainers.org/lxd/try-it/)!
Then if you want to run it locally, take a look at our [getting started guide](https://linuxcontainers.org/lxd/getting-started-cli/).
-Release announcements can be found here: https://linuxcontainers.org/lxd/news/
-And the release tarballs here: https://linuxcontainers.org/lxd/downloads/
+Release announcements can be found here: <https://linuxcontainers.org/lxd/news/>
+And the release tarballs here: <https://linuxcontainers.org/lxd/downloads/>
## Status
Type | Service | Status
@@ -29,21 +29,27 @@ Instructions on installing LXD for a wide variety of Linux distributions and ope
## Installing LXD from source
We recommend having the latest versions of liblxc (>= 2.0.0 required) and CRIU
(>= 1.7 recommended) available for LXD development. Additionally, LXD requires
-Golang 1.5 or later to work. On ubuntu, you can get those with:
+Golang 1.6 or later to work. On ubuntu, you can get those with:
- sudo apt update
- sudo apt install acl dnsmasq-base git golang liblxc1 lxc-dev libacl1-dev make pkg-config rsync squashfs-tools tar xz-utils
+```bash
+sudo apt update
+sudo apt install acl dnsmasq-base git golang liblxc1 lxc-dev libacl1-dev make pkg-config rsync squashfs-tools tar xz-utils
+```
There are a few storage backends for LXD besides the default "directory" backend.
Installing these tools adds a bit to initramfs and may slow down your
host boot, but are needed if you'd like to use a particular backend:
- sudo apt install lvm2 thin-provisioning-tools
- sudo apt install btrfs-tools
+```bash
+sudo apt install lvm2 thin-provisioning-tools
+sudo apt install btrfs-tools
+```
To run the testsuite, you'll also need:
- sudo apt install curl gettext jq sqlite3 uuid-runtime bzr
+```bash
+sudo apt install curl gettext jq sqlite3 uuid-runtime bzr
+```
### Building the tools
@@ -51,45 +57,53 @@ LXD consists of two binaries, a client called `lxc` and a server called `lxd`.
These live in the source tree in the `lxc/` and `lxd/` dirs, respectively.
To get the code, set up your go environment:
- mkdir -p ~/go
- export GOPATH=~/go
+```bash
+mkdir -p ~/go
+export GOPATH=~/go
+```
And then download it as usual:
- go get github.com/lxc/lxd
- cd $GOPATH/src/github.com/lxc/lxd
- make
+```bash
+go get github.com/lxc/lxd
+cd $GOPATH/src/github.com/lxc/lxd
+make
+```
-...which will give you two binaries in $GOPATH/bin, `lxd` the daemon binary,
+...which will give you two binaries in `$GOPATH/bin`, `lxd` the daemon binary,
and `lxc` a command line client to that daemon.
### Machine Setup
You'll need sub{u,g}ids for root, so that LXD can create the unprivileged
containers:
- echo "root:1000000:65536" | sudo tee -a /etc/subuid /etc/subgid
+```bash
+echo "root:1000000:65536" | sudo tee -a /etc/subuid /etc/subgid
+```
-Now you can run the daemon (the --group sudo bit allows everyone in the sudo
+Now you can run the daemon (the `--group` sudo bit allows everyone in the sudo
group to talk to LXD; you can create your own group if you want):
- sudo -E $GOPATH/bin/lxd --group sudo
+```bash
+sudo -E $GOPATH/bin/lxd --group sudo
+```
## Getting started with LXD
Now that you have LXD running on your system you can read the [getting started guide](https://linuxcontainers.org/lxd/getting-started-cli/) or go through more examples and configurations in [our documentation](https://github.com/lxc/lxd/tree/master/doc).
## Bug reports
-Bug reports can be filed at: https://github.com/lxc/lxd/issues/new
+Bug reports can be filed at: <https://github.com/lxc/lxd/issues/new>
## Contributing
-Fixes and new features are greatly appreciated but please read our [contributing guidelines](CONTRIBUTING.md) first.
+Fixes and new features are greatly appreciated but please read our [contributing guidelines](contributing.md) first.
## Support and discussions
### Forum
-A discussion forum is available at: https://discuss.linuxcontainers.org
+A discussion forum is available at: <https://discuss.linuxcontainers.org>
### Mailing-lists
We use the LXC mailing-lists for developer and user discussions, you can
-find and subscribe to those at: https://lists.linuxcontainers.org
+find and subscribe to those at: <https://lists.linuxcontainers.org>
### IRC
If you prefer live discussions, some of us also hang out in
@@ -104,19 +118,25 @@ config variable.
To see the current server configuration, run:
- lxc config show
+```bash
+lxc config show
+```
To set the address to listen to, find out what addresses are available and use
the `config set` command on the server:
- ip addr
- lxc config set core.https_address 192.168.1.15
+```bash
+ip addr
+lxc config set core.https_address 192.168.1.15
+```
#### When I do a `lxc remote add` over https, it asks for a password?
By default, LXD has no password for security reasons, so you can't do a remote
add this way. In order to set a password, do:
- lxc config set core.trust_password SECRET
+```bash
+lxc config set core.trust_password SECRET
+```
on the host LXD is running on. This will set the remote password that you can
then use to do `lxc remote add`.
@@ -124,8 +144,9 @@ then use to do `lxc remote add`.
You can also access the server without setting a password by copying the client
certificate from `.config/lxc/client.crt` to the server and adding it with:
- lxc config trust add client.crt
-
+```bash
+lxc config trust add client.crt
+```
#### How do I configure LXD storage?
LXD supports btrfs, directory, lvm and zfs based storage.
@@ -135,13 +156,15 @@ choice installed on the machine (btrfs-progs, lvm2 or zfsutils-linux).
You can get a basic configuration done with:
- lxd init
+```bash
+lxd init
+```
-"lxd init" supports both directory based storage and ZFS.
+`lxd init` supports both directory based storage and ZFS.
-"btrfs" is automatically setup if /var/lib/lxd is stored on btrfs.
+btrfs is automatically setup if `/var/lib/lxd` is stored on btrfs.
-For LVM, you can set the "storage.lvm\_vg\_name" key to a valid LVM volume group.
+For LVM, you can set the `storage.lvm_vg_name` key to a valid LVM volume group.
For production environments, you should be using block backed storage
instead both for performance and reliability reasons.
@@ -150,13 +173,17 @@ instead both for performance and reliability reasons.
Live migration requires a tool installed on both hosts called
[CRIU](http://criu.org), which is available in Ubuntu via:
- sudo apt-get install criu
+```bash
+sudo apt-get install criu
+```
Then, launch your container with the following,
- lxc launch ubuntu $somename
- sleep 5s # let the container get to an interesting state
- lxc move host1:$somename host2:$somename
+```bash
+lxc launch ubuntu $somename
+sleep 5s # let the container get to an interesting state
+lxc move host1:$somename host2:$somename
+```
And with luck you'll have migrated the container :). Migration is still in
experimental stages and may not work for all workloads. Please report bugs on
@@ -167,35 +194,49 @@ Yes. The easiest way to do that is using a privileged container to avoid file ow
1.a) create a container.
- lxc launch ubuntu privilegedContainerName -c security.privileged=true
+```bash
+lxc launch ubuntu privilegedContainerName -c security.privileged=true
+```
1.b) or, if your container already exists.
- lxc config set privilegedContainerName security.privileged true
+```bash
+lxc config set privilegedContainerName security.privileged true
+```
+
2) then.
- lxc config device add privilegedContainerName shareName disk source=/home/$USER path=/home/ubuntu
+```bash
+lxc config device add privilegedContainerName shareName disk source=/home/$USER path=/home/ubuntu
+```
#### How can I run docker inside a LXD container?
-In order to run Docker inside a LXD container the `security.nesting` property of the container should be set to `true`.
+In order to run Docker inside a LXD container the `security.nesting` property of the container should be set to `true`.
- lxc config set <container> security.nesting true
+```bash
+lxc config set <container> security.nesting true
+```
-Note that LXD containers cannot load kernel modules, so depending on your Docker configuration
-you may need to have the needed extra kernel modules loaded by the host.
+Note that LXD containers cannot load kernel modules, so depending on your
+Docker configuration you may need to have the needed extra kernel modules
+loaded by the host.
You can do so by setting a comma seperate list of kernel modules that your container needs with:
- lxc config set <container> linux.kernel_modules <modules>
+```bash
+lxc config set <container> linux.kernel_modules <modules>
+```
-We have also received some reports that creating a "/.dockerenv" file in your container
-can help Docker ignore some errors it's getting due to running in a nested environment.
+We have also received some reports that creating a `/.dockerenv` file in your
+container can help Docker ignore some errors it's getting due to running in a
+nested environment.
## Hacking on LXD
### Directly using the REST API
The LXD REST API can be used locally via unauthenticated Unix socket or remotely via SSL encapsulated TCP.
#### Via Unix socket
+
```bash
curl --unix-socket /var/lib/lxd/unix.socket \
-H "Content-Type: application/json" \
@@ -206,9 +247,11 @@ curl --unix-socket /var/lib/lxd/unix.socket \
#### Via TCP
TCP requires some additional configuration and is not enabled by default.
+
```bash
lxc config set core.https_address "[::]:8443"
```
+
```bash
curl -k -L \
--cert ~/.config/lxc/client.crt \
@@ -218,8 +261,10 @@ curl -k -L \
-d @hello-ubuntu.json \
"https://127.0.0.1:8443/1.0/containers"
```
+
#### JSON payload
The `hello-ubuntu.json` file referenced above could contain something like:
+
```json
{
"name":"some-ubuntu",
From b515bf0b86da2ad89ad65f1daa37643a2a92afda Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Thu, 21 Sep 2017 18:19:59 +0200
Subject: [PATCH 04/23] doc: fixes in api-extensions.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/api-extensions.md | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
diff --git a/doc/api-extensions.md b/doc/api-extensions.md
index 6f8960dc3..291d964bf 100644
--- a/doc/api-extensions.md
+++ b/doc/api-extensions.md
@@ -3,18 +3,17 @@
The changes below were introduced to the LXD API after the 1.0 API was finalized.
They are all backward compatible and can be detected by client tools by
-looking at the api\_extensions field in GET /1.0/.
-
+looking at the `api_extensions` field in `GET /1.0/`.
## id\_map
Enables setting the `security.idmap.isolated` and `security.idmap.isolated`,
`security.idmap.size`, and `raw.id_map` fields.
## id\_map\_base
-This introduces a new security.idmap.base allowing the user to skip the
+This introduces a new `security.idmap.base` allowing the user to skip the
map auto-selection process for isolated containers and specify what host
uid/gid to use as the base.
## instance\_types
-This adds the "instance\_type" field to the container creation request.
+This adds the `instance_type` field to the container creation request.
Its value is expanded to LXD resource limits.
From c79f5d9e1b582962e3fa5ec5b5491e8e72a4d3fa Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:17:01 +0200
Subject: [PATCH 05/23] doc: fixes in cloud-init.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/cloud-init.md | 51 +++++++++++++++++++++++++++------------------------
1 file changed, 27 insertions(+), 24 deletions(-)
diff --git a/doc/cloud-init.md b/doc/cloud-init.md
index dcad9dd4b..37b7ddc98 100644
--- a/doc/cloud-init.md
+++ b/doc/cloud-init.md
@@ -1,4 +1,4 @@
-# Custom Network Configuration With cloud-init
+# Custom network configuration with cloud-init
[cloud-init](https://launchpad.net/cloud-init) may be used for custom network configuration of containers.
@@ -9,17 +9,18 @@ have the cloud-init package installed, therefore, any of the configuration
options mentioned in this guide will not work. On the contrary, images
provided at cloud-images.ubuntu.com have the necessary package installed
and also have a templates directory in their archive populated with
- * cloud-init-meta.tpl
- * cloud-init-user.tpl
- * cloud-init-vendor.tpl
- * cloud-init-network.tpl
+
+ * `cloud-init-meta.tpl`
+ * `cloud-init-user.tpl`
+ * `cloud-init-vendor.tpl`
+ * `cloud-init-network.tpl`
and others not related to cloud-init.
Templates provided with container images at cloud-images.ubuntu.com have
-the following in their metadata.yaml:
+the following in their `metadata.yaml`:
-```
+```yaml
/var/lib/cloud/seed/nocloud-net/network-config:
when:
- create
@@ -29,7 +30,7 @@ the following in their metadata.yaml:
Therefore, either when you create or copy a container it gets a newly rendered
network configuration from a pre-defined template. cloud-init uses the
-network-config file to render /etc/network/interfaces.d/50-cloud-init.cfg when
+network-config file to render `/etc/network/interfaces.d/50-cloud-init.cfg` when
you first start a container. It will not react to any changes if you restart
a container afterwards unless you force it.
@@ -39,13 +40,13 @@ In order to change this you need to define your own network configuration
using user.network-config key in the config dictionary which will override
the default configuration (this is due to how the template is structured).
-The allowed values follow /etc/network/interfaces syntax in case of Ubuntu
+The allowed values follow `/etc/network/interfaces` syntax in case of Ubuntu
images.
For example, to configure a specific network interface with a static IPv4
address and also use a custom nameserver use
-```
+```yaml
config:
user.network-config: |
version: 1
@@ -65,16 +66,16 @@ config:
A container's rootfs will contain the following files as a result:
- * /var/lib/cloud/seed/nocloud-net/network-config
- * /etc/network/interfaces.d/50-cloud-init.cfg
+ * `/var/lib/cloud/seed/nocloud-net/network-config`
+ * `/etc/network/interfaces.d/50-cloud-init.cfg`
The former will be the same as the value provided in user.network-config,
-the latter will be a file in /etc/network/interfaces format converted from
+the latter will be a file in `/etc/network/interfaces` format converted from
the network-config file by cloud-init (if it is not check syslog for cloud-init
error messages).
-/etc/network/interfaces.d/50-cloud-init.cfg should then contain
+`/etc/network/interfaces.d/50-cloud-init.cfg` should then contain
```
# This file is generated from information provided by
@@ -93,7 +94,7 @@ iface eth1 inet static
netmask 255.255.255.0
```
-You will also notice that /run/resolvconf/resolv.conf or /etc/resolv.conf
+You will also notice that `/run/resolvconf/resolv.conf` or `/etc/resolv.conf`
which is pointing to it will contain the desired dns server after boot-up.
```
@@ -105,11 +106,12 @@ nameserver 10.10.10.254
# Implementation Details
cloud-init allows you to seed instance configuration using the following files
-located at /var/lib/cloud/seed/nocloud-net:
- * user-data (required)
- * meta-data (required)
- * vendor-data (optional)
- * network-config (optional)
+located at `/var/lib/cloud/seed/nocloud-net`:
+
+ * `user-data` (required)
+ * `meta-data` (required)
+ * `vendor-data` (optional)
+ * `network-config` (optional)
The network-config file is written to by lxd using data provided in templates
that come with an image. This is governed by metadata.yaml but naming of the
@@ -121,7 +123,7 @@ concerned - this is purely image data that can be modified if needed.
* A good reference on which values you can use are [unit tests for cloud-init](https://git.launchpad.net/cloud-init/tree/tests/unittests/test_datasource/test_nocloud.py#n163)
* [cloud-init directory layout](https://cloudinit.readthedocs.io/en/latest/topics/dir_layout.html)
-A default cloud-init-network.tpl provided with images from the "ubuntu:" image
+A default `cloud-init-network.tpl` provided with images from the "ubuntu:" image
source looks like this:
```
@@ -135,11 +137,12 @@ config:
```
The template syntax is the one used in the pongo2 template engine. A custom
-config_get function is defined to retrieve values from a container
+`config_get` function is defined to retrieve values from a container
configuration.
Options available with such a template structure:
+
* Use DHCP by default on your eth0 interface;
- * Set user.network_mode to "link-local" and configure networking by hand;
- * Seed cloud-init by defining user.network-config.
+ * Set `user.network_mode` to `link-local` and configure networking by hand;
+ * Seed cloud-init by defining `user.network-config`.
From 2d4fd7be6c9da6273bf49332b0c8265ec03aa6fc Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:24:14 +0200
Subject: [PATCH 06/23] doc: fixes in container-environment.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/container-environment.md | 94 +++++++++++++++++++++++---------------------
1 file changed, 50 insertions(+), 44 deletions(-)
diff --git a/doc/container-environment.md b/doc/container-environment.md
index 704d2d0ee..d354ea0ca 100644
--- a/doc/container-environment.md
+++ b/doc/container-environment.md
@@ -1,84 +1,90 @@
# Container runtime environment
LXD attempts to present a consistent environment to the container it runs.
-The exact environment will differ slightly based on kernel features and
-user configuration but will otherwise be identical for all containers.
+The exact environment will differ slightly based on kernel features and user
+configuration but will otherwise be identical for all containers.
## PID1
-LXD spawns whatever is located at /sbin/init as the initial process of the container (PID 1).
+LXD spawns whatever is located at `/sbin/init` as the initial process of the container (PID 1).
This binary should act as a proper init system, including handling re-parented processes.
LXD's communication with PID1 in the container is limited to two signals:
- - SIGINT to trigger a reboot of the container
- - SIGPWR (or alternatively SIGRTMIN+3) to trigger a clean shutdown of the container
+ - `SIGINT` to trigger a reboot of the container
+ - `SIGPWR` (or alternatively `SIGRTMIN`+3) to trigger a clean shutdown of the container
-The initial environment of PID1 is blank except for "container=lxc" which can be used
-by the init system to detect the runtime.
+The initial environment of PID1 is blank except for `container=lxc` which can
+be used by the init system to detect the runtime.
All file descriptors above the default 3 are closed prior to PID1 being spawned.
## Filesystem
LXD assumes that any image it uses to create a new container from will come with at least:
- - /dev (empty)
- - /proc (empty)
- - /sbin/init (executable)
- - /sys (empty)
+
+ - `/dev` (empty)
+ - `/proc` (empty)
+ - `/sbin/init` (executable)
+ - `/sys` (empty)
## Devices
-LXD containers have a minimal and ephemeral /dev based on a tmpfs filesystem.
+LXD containers have a minimal and ephemeral `/dev` based on a tmpfs filesystem.
Since this is a tmpfs and not a devtmpfs, device nodes will only appear if manually created.
The standard set of device nodes will be setup:
- - /dev/console
- - /dev/fd
- - /dev/full
- - /dev/log
- - /dev/null
- - /dev/ptmx
- - /dev/random
- - /dev/stdin
- - /dev/stderr
- - /dev/stdout
- - /dev/tty
- - /dev/urandom
- - /dev/zero
+
+ - `/dev/console`
+ - `/dev/fd`
+ - `/dev/full`
+ - `/dev/log`
+ - `/dev/null`
+ - `/dev/ptmx`
+ - `/dev/random`
+ - `/dev/stdin`
+ - `/dev/stderr`
+ - `/dev/stdout`
+ - `/dev/tty`
+ - `/dev/urandom`
+ - `/dev/zero`
On top of the standard set of devices, the following are also setup for convenience:
- - /dev/fuse
- - /dev/net/tun
- - /dev/mqueue
+
+ - `/dev/fuse`
+ - `/dev/net/tun`
+ - `/dev/mqueue`
## Mounts
The following mounts are setup by default under LXD:
- - /proc (proc)
- - /sys (sysfs)
- - /sys/fs/cgroup/\* (cgroupfs) (only on kernels lacking cgroup namespace support)
+
+ - `/proc` (proc)
+ - `/sys` (sysfs)
+ - `/sys/fs/cgroup/*` (cgroupfs) (only on kernels lacking cgroup namespace support)
The following paths will also be automatically mounted if present on the host:
- - /proc/sys/fs/binfmt\_misc
- - /sys/firmware/efi/efivars
- - /sys/fs/fuse/connections
- - /sys/fs/pstore
- - /sys/kernel/debug
- - /sys/kernel/security
-The reason for passing all of those is legacy init systems which require those
-to be mounted or be mountabled inside the container.
+ - `/proc/sys/fs/binfmt_misc`
+ - `/sys/firmware/efi/efivars`
+ - `/sys/fs/fuse/connections`
+ - `/sys/fs/pstore`
+ - `/sys/kernel/debug`
+ - `/sys/kernel/security`
+
+The reason for passing all of those is legacy init systems which require
+those to be mounted or be mountabled inside the container.
-The majority of those will not be writable (or even readable) from inside an
-unprivileged container and will be blocked by our AppArmor policy inside privileged containers.
+The majority of those will not be writable (or even readable) from inside an
+unprivileged container and will be blocked by our AppArmor policy inside
+privileged containers.
## Network
LXD containers may have any number of network devices attached to them.
The naming for those unless overriden by the user is ethX where X is an incrementing number.
## Container to host communication
-LXD sets up a socket at /dev/lxd/sock which root in the container can use to communicate with LXD on the host.
+LXD sets up a socket at `/dev/lxd/sock` which root in the container can use to communicate with LXD on the host.
The API is [documented here](dev-lxd.md).
## LXCFS
If LXCFS is present on the host, it will automatically be setup for the container.
-This normally results in a number of /proc files being overriden through bind-mounts.
-On older kernels a virtual version of /sys/fs/cgroup may also be setup by LXCFS.
+This normally results in a number of `/proc` files being overriden through bind-mounts.
+On older kernels a virtual version of `/sys/fs/cgroup` may also be setup by LXCFS.
From eb7aa482d88c80fc3d4f80c1e4f4aabac0b32422 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:28:16 +0200
Subject: [PATCH 07/23] doc: fixes in containers.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/containers.md | 81 ++++++++++++++++++++++++++++++-------------------------
1 file changed, 45 insertions(+), 36 deletions(-)
diff --git a/doc/containers.md b/doc/containers.md
index 01ac2722c..7f41d4090 100644
--- a/doc/containers.md
+++ b/doc/containers.md
@@ -1,21 +1,23 @@
# Container configuration
## Properties
The following are direct container properties and can't be part of a profile:
- - name
- - architecture
+
+ - `name`
+ - `architecture`
Name is the container name and can only be changed by renaming the container.
## Key/value configuration
The key/value configuration is namespaced with the following namespaces
currently supported:
- - boot (boot related options, timing, dependencies, ...)
- - environment (environment variables)
- - limits (resource limits)
- - raw (raw container configuration overrides)
- - security (security policies)
- - user (storage for user properties, searchable)
- - volatile (used internally by LXD to store settings that are specific to a specific container instance)
+
+ - `boot` (boot related options, timing, dependencies, ...)
+ - `environment` (environment variables)
+ - `limits` (resource limits)
+ - `raw` (raw container configuration overrides)
+ - `security` (security policies)
+ - `user` (storage for user properties, searchable)
+ - `volatile` (used internally by LXD to store settings that are specific to a specific container instance)
The currently supported keys are:
@@ -78,7 +80,9 @@ backward compatibility).
Those keys can be set using the lxc tool with:
- lxc config set <container> <key> <value>
+```bash
+lxc config set <container> <key> <value>
+```
Volatile keys can't be set by the user and can only be set directly against a container.
@@ -93,23 +97,24 @@ required for a standard POSIX system to work. These aren't visible in
container or profile configuration and may not be overriden.
Those includes:
- - /dev/null (character device)
- - /dev/zero (character device)
- - /dev/full (character device)
- - /dev/console (character device)
- - /dev/tty (character device)
- - /dev/random (character device)
- - /dev/urandom (character device)
- - /dev/net/tun (character device)
- - /dev/fuse (character device)
- - lo (network interface)
-
-Anything else has to be defined in the container configuration or in one
-of its profiles. The default profile will typically contain a network
-interface to become eth0 in the container.
-
-To add extra devices to a container, device entries can be added
-directly to a container, or to a profile.
+
+ - `/dev/null` (character device)
+ - `/dev/zero` (character device)
+ - `/dev/full` (character device)
+ - `/dev/console` (character device)
+ - `/dev/tty` (character device)
+ - `/dev/random` (character device)
+ - `/dev/urandom` (character device)
+ - `/dev/net/tun` (character device)
+ - `/dev/fuse` (character device)
+ - `lo` (network interface)
+
+Anything else has to be defined in the container configuration or in one of its
+profiles. The default profile will typically contain a network interface to
+become `eth0` in the container.
+
+To add extra devices to a container, device entries can be added directly to a
+container, or to a profile.
Devices may be added or removed while the container is running.
@@ -118,10 +123,13 @@ used in a subsequent profile or in the container's own configuration,
the whole entry is overriden by the new definition.
Device entries are added through:
- lxc config device add <container> <name> <type> [key=value]...
- lxc profile device add <profile> <name> <type> [key=value]...
-### Device types
+```bash
+lxc config device add <container> <name> <type> [key=value]...
+lxc profile device add <profile> <name> <type> [key=value]...
+```
+
+## Device types
LXD supports the following device types:
ID (database) | Name | Description
@@ -142,10 +150,11 @@ It can be added in a profile being applied after the profile it originated from
### Type: nic
LXD supports different kind of network devices:
- - physical: Straight physical device passthrough from the host. The targeted device will vanish from the host and appear in the container.
- - bridged: Uses an existing bridge on the host and creates a virtual device pair to connect the host bridge to the container.
- - macvlan: Sets up a new network device based on an existing one but using a different MAC address.
- - p2p: Creates a virtual device pair, putting one side in the container and leaving the other side on the host.
+
+ - `physical`: Straight physical device passthrough from the host. The targeted device will vanish from the host and appear in the container.
+ - `bridged`: Uses an existing bridge on the host and creates a virtual device pair to connect the host bridge to the container.
+ - `macvlan`: Sets up a new network device based on an existing one but using a different MAC address.
+ - `p2p`: Creates a virtual device pair, putting one side in the container and leaving the other side on the host.
Different network interface types have different additional properties, the current list is:
@@ -162,7 +171,7 @@ mtu | integer | parent MTU | no | all
parent | string | - | yes | physical, bridged, macvlan | The name of the host device or bridge
#### bridged or macvlan for connection to physical network
-The "bridged" and "macvlan" interface types can both be used to connect
+The `bridged` and `macvlan` interface types can both be used to connect
to an existing physical network.
macvlan effectively lets you fork your physical NIC, getting a second
@@ -202,7 +211,7 @@ the average of the limits will be used.
### Type: unix-char
Unix character device entries simply make the requested character device
-appear in the container's /dev and allow read/write operations to it.
+appear in the container's `/dev` and allow read/write operations to it.
The following properties exist:
From 9fe90fa8ff751eda2057186031347935cad1e10e Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:30:00 +0200
Subject: [PATCH 08/23] doc: fixes in contributing.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/contributing.md | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/doc/contributing.md b/doc/contributing.md
index 994c3c0a3..763862ca9 100644
--- a/doc/contributing.md
+++ b/doc/contributing.md
@@ -1,7 +1,7 @@
# Pull requests:
Changes to this project should be proposed as pull requests on Github
-at: https://github.com/lxc/lxd
+at: <https://github.com/lxc/lxd>
Proposed changes will then go through code review there and once acked,
be merged in the main branch.
@@ -63,7 +63,9 @@ to pass it on as an open-source contribution.
An example of a valid sign-off line is:
- Signed-off-by: Random J Developer <random at developer.org>
+```
+Signed-off-by: Random J Developer <random at developer.org>
+```
Use your real name and a valid e-mail address.
Sorry, no pseudonyms or anonymous contributions are allowed.
From 85c5d9f1dba1f390dd9151c309bfc559cb7cb8a3 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:33:09 +0200
Subject: [PATCH 09/23] doc: fixes in daemon-behavior.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/daemon-behavior.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/daemon-behavior.md b/doc/daemon-behavior.md
index 56f5bd242..dba876f93 100644
--- a/doc/daemon-behavior.md
+++ b/doc/daemon-behavior.md
@@ -27,9 +27,9 @@ Indicates to LXD that the host is going down.
LXD will attempt a clean shutdown of all the containers. After 30s, it
will kill any remaining container.
-The container power\_state in the containers table is kept as it was so
+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
-Write a memory profile dump to the file specified with \-\-memprofile.
+Write a memory profile dump to the file specified with `--memprofile`.
From 28a2b39c9e3e36b6481fbaf32c29e63a4d6d90d9 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:35:25 +0200
Subject: [PATCH 10/23] doc: fixes in database.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/database.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/database.md b/doc/database.md
index fd7de4f64..a47e51cb5 100644
--- a/doc/database.md
+++ b/doc/database.md
@@ -29,7 +29,8 @@ terribly useful.
# Design
-The design of the database is made to be as close as possible to the REST API.
+The design of the database is made to be as close as possible to
+the [RESTful API](rest-api.md).
The main table and field names are exact match for the REST API.
From cda058cee84aa54820878b9339e28c8f8299503b Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:37:47 +0200
Subject: [PATCH 11/23] doc: fixes in debugging.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/debugging.md | 24 +++++++++++++++++-------
1 file changed, 17 insertions(+), 7 deletions(-)
diff --git a/doc/debugging.md b/doc/debugging.md
index 6f1fbea20..e7a3d5b1c 100644
--- a/doc/debugging.md
+++ b/doc/debugging.md
@@ -17,8 +17,10 @@ This command will monitor messages as they appear on remote server.
Shutting down `lxd` server and running it in foreground with `--debug`
flag will bring a lot of (hopefully) useful info:
- systemctl stop lxd lxd.socket
- lxd --debug --group lxd
+```bash
+systemctl stop lxd lxd.socket
+lxd --debug --group lxd
+ ```
`--group lxd` is needed to grant access to unprivileged users in this
group.
@@ -31,9 +33,11 @@ local socket. This command accesses `GET /1.0` and formats JSON into
human readable form using [jq](https://stedolan.github.io/jq/tutorial/)
utility:
- curl --unix-socket /var/lib/lxd/unix.socket lxd/1.0 | jq .
+```bash
+curl --unix-socket /var/lib/lxd/unix.socket lxd/1.0 | jq .
+```
-See [rest-api.md](rest-api.md) for available API.
+See the [RESTful API](rest-api.md) for available API.
### REST API through HTTPS
@@ -45,7 +49,9 @@ connection tools for authentication and encryption.
Examining certificate. In case you are curious:
- openssl x509 -in client.crt -purpose
+```bash
+openssl x509 -in client.crt -purpose
+```
Among the lines you should see:
@@ -54,7 +60,9 @@ Among the lines you should see:
#### with command line tools
- wget --no-check-certificate https://127.0.0.1:8443/1.0 --certificate=$HOME/.config/lxc/client.crt --private-key=$HOME/.config/lxc/client.key -O - -q
+```bash
+wget --no-check-certificate https://127.0.0.1:8443/1.0 --certificate=$HOME/.config/lxc/client.crt --private-key=$HOME/.config/lxc/client.key -O - -q
+```
#### with browser
@@ -65,6 +73,8 @@ browser.
For example this produces `client.pfx` in Windows-compatible format:
- openssl pkcs12 -clcerts -inkey client.key -in client.crt -export -out client.pfx
+```bash
+openssl pkcs12 -clcerts -inkey client.key -in client.crt -export -out client.pfx
+```
After that, opening https://127.0.0.1:8443/1.0 should work as expected.
From c7f67c01a5c81fa4dddd83e6045d013ba7b9b7d9 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:42:39 +0200
Subject: [PATCH 12/23] doc: fixes in dev-lxd.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/dev-lxd.md | 54 +++++++++++++++++++++++++++++-------------------------
1 file changed, 29 insertions(+), 25 deletions(-)
diff --git a/doc/dev-lxd.md b/doc/dev-lxd.md
index be5b398da..205f79e66 100644
--- a/doc/dev-lxd.md
+++ b/doc/dev-lxd.md
@@ -2,7 +2,7 @@
Communication between the hosted workload (container) and its host while
not strictly needed is a pretty useful feature.
-In LXD, this feature is implemented through a /dev/lxd/sock node which is
+In LXD, this feature is implemented through a `/dev/lxd/sock` node which is
created and setup for all LXD containers.
This file is a Unix socket which processes inside the container can
@@ -10,28 +10,28 @@ connect to. It's multi-threaded so multiple clients can be connected at the
same time.
# Implementation details
-LXD on the host binds /var/lib/lxd/devlxd and starts listening for new
+LXD on the host binds `/var/lib/lxd/devlxd` and starts listening for new
connections on it.
This socket is then bind-mounted into every single container started by
-LXD at /dev/lxd/sock.
+LXD at `/dev/lxd/sock`.
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
-Queries on /dev/lxd/sock will only return information related to the
+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
-The protocol on /dev/lxd/sock is plain-text HTTP with JSON messaging, so very
+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.
+authentication support in the `/dev/lxd/sock` API.
# REST-API
## API structure
@@ -42,47 +42,51 @@ authentication support in the /dev/lxd/sock API.
* /1.0/meta-data
## API details
-### /
+### `/`
#### GET
* Description: List of supported APIs
- * Return: list of supported API endpoint URLs (by default ['/1.0'])
+ * Return: list of supported API endpoint URLs (by default `['/1.0']`)
Return value:
- [
- "/1.0"
- ]
-
-### /1.0
+```json
+[
+ "/1.0"
+]
+```
+### `/1.0`
#### GET
* Description: Information about the 1.0 API
* Return: dict
Return value:
- {
- "api_version": "1.0"
- }
-
-### /1.0/config
+```json
+{
+ "api_version": "1.0"
+}
+```
+### `/1.0/config`
#### GET
* Description: List of configuration keys
* Return: list of configuration keys URL
Note that the configuration key names match those in the container
config, however not all configuration namespaces will be exported to
-/dev/lxd/sock.
-Currently only the user.\* keys are accessible to the container.
+`/dev/lxd/sock`.
+Currently only the `user.*` keys are accessible to the container.
At this time, there also aren't any container-writable namespace.
Return value:
- [
- "/1.0/config/user.a"
- ]
+```json
+[
+ "/1.0/config/user.a"
+]
+```
-### /1.0/config/\<KEY\>
+### `/1.0/config/<KEY>`
#### GET
* Description: Value of that key
* Return: Plain-text value
@@ -91,7 +95,7 @@ Return value:
blah
-### /1.0/meta-data
+### `/1.0/meta-data`
#### GET
* Description: Container meta-data compatible with cloud-init
* Return: cloud-init meta-data
From 0eb33a3ba84bddb2394c063b92a9320174d109c8 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:46:24 +0200
Subject: [PATCH 13/23] doc: fixes in environment.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/environment.md | 18 +++++++++---------
1 file changed, 9 insertions(+), 9 deletions(-)
diff --git a/doc/environment.md b/doc/environment.md
index 058a7a754..e20ae9c79 100644
--- a/doc/environment.md
+++ b/doc/environment.md
@@ -5,20 +5,20 @@ the user's environment and to turn some advanced features on and off.
# Common
Name | Description
:--- | :----
-LXD\_DIR | The LXD data directory
-PATH | List of paths to look into when resolving binaries
-http\_proxy | Proxy server URL for HTTP
-https\_proxy | Proxy server URL for HTTPs
-no\_proxy | List of domains that don't require the use of a proxy
+`LXD_DIR` | The LXD data directory
+`PATH` | List of paths to look into when resolving binaries
+`http_proxy` | Proxy server URL for HTTP
+`https_proxy` | Proxy server URL for HTTPs
+`no_proxy` | List of domains that don't require the use of a proxy
# Client environment variable
Name | Description
:--- | :----
-EDITOR | What text editor to use
-VISUAL | What text editor to use (if EDITOR isn't set)
+`EDITOR` | What text editor to use
+`VISUAL` | What text editor to use (if `EDITOR` isn't set)
# Server environment variable
Name | Description
:--- | :----
-LXD\_SECURITY\_APPARMOR | If set to "false", forces AppArmor off
-LXD\_LXC\_TEMPLATE\_CONFIG | Path to the LXC template configuration directory
+`LXD_SECURITY_APPARMOR` | If set to `false`, forces AppArmor off
+`LXD_LXC_TEMPLATE_CONFIG` | Path to the LXC template configuration directory
From 0256ceb298c95a7ad23e7f74e72c52109c7b413e Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:50:53 +0200
Subject: [PATCH 14/23] doc: fixes in image-handling.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/image-handling.md | 109 +++++++++++++++++++++++++++-----------------------
1 file changed, 58 insertions(+), 51 deletions(-)
diff --git a/doc/image-handling.md b/doc/image-handling.md
index 738368d5c..1ef487725 100644
--- a/doc/image-handling.md
+++ b/doc/image-handling.md
@@ -13,18 +13,18 @@ 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
(no new container spawned) for the number of days set in
-images.remote\_cache\_expiry or until the image's expiry is reached
+`images.remote_cache_expiry` or until the image's expiry is reached
whichever comes first.
-LXD keeps track of image usage by updating the last\_used\_at image
+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
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.
+updated by LXD. This can be changed with `images.auto_update_cached`.
-On startup and then every 6 hours (unless images.auto\_update\_interval
+On startup and then every 6 hours (unless `images.auto_update_interval`
is set), the LXD daemon will go look for more recent version of all the
images in the store which are marked as auto-update and have a recorded
source server.
@@ -53,20 +53,22 @@ non-LXD rootfs tarballs already available today.
## Unified tarball
Tarball, can be compressed and contains:
- - rootfs/
- - metadata.yaml
- - templates/ (optional)
+
+ - `rootfs/`
+ - `metadata.yaml`
+ - `templates/` (optional)
In this mode, the image identifier is the SHA-256 of the tarball.
## Split tarballs
Two (possibly compressed) tarballs. One for metadata, one for the rootfs.
-metadata.tar contains:
- - metadata.yaml
- - templates/ (optional)
+`metadata.tar` contains:
+
+ - `metadata.yaml`
+ - `templates/` (optional)
-rootfs.tar contains a Linux root filesystem at its root.
+`rootfs.tar` contains a Linux root filesystem at its root.
In this mode the image identifier is the SHA-256 of the concatenation of
the metadata and rootfs tarball (in that order).
@@ -76,62 +78,67 @@ The tarball(s) can be compressed using bz2, gz, xz, lzma, tar (uncompressed) or
it can also be a squashfs image.
## Content
-The rootfs directory (or tarball) contains a full file system tree of what will become the container's /.
+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.
-metadata.yaml contains information relevant to running the image under
+`metadata.yaml` contains information relevant to running the image under
LXD, at the moment, this contains:
- architecture: x86_64
- creation_date: 1424284563
+```yaml
+architecture: x86_64
+creation_date: 1424284563
+properties:
+ description: Ubuntu 14.04 LTS Intel 64bit
+ os: Ubuntu
+ release:
+ - trusty
+ - 14.04
+templates:
+ /etc/hosts:
+ when:
+ - create
+ - rename
+ template: hosts.tpl
properties:
- description: Ubuntu 14.04 LTS Intel 64bit
- os: Ubuntu
- release:
- - trusty
- - 14.04
- templates:
- /etc/hosts:
- when:
- - create
- - rename
- template: hosts.tpl
- properties:
- foo: bar
- /etc/hostname:
- when:
- - start
- template: hostname.tpl
- /etc/network/interfaces:
- when:
- - create
- template: interfaces.tpl
- create_only: true
-
-The architecture and creation\_date fields are mandatory, the properties
+ foo: bar
+ /etc/hostname:
+ when:
+ - start
+ template: hostname.tpl
+ /etc/network/interfaces:
+ when:
+ - create
+ template: interfaces.tpl
+ create_only: true
+```
+
+The `architecture` and `creation_date` fields are mandatory, the properties
are just a set of default properties for the image. The os, release,
name and description fields while not mandatory in any way, should be
pretty common.
-For templates, the "when" key can be one or more of:
- - create (run at the time a new container is created from the image)
- - copy (run when a container is created from an existing one)
- - start (run every time the container is started)
+For templates, the `when` key can be one or more of:
+
+ - `create` (run at the time a new container is created from the image)
+ - `copy` (run when a container is created from an existing one)
+ - `start` (run every time the container is started)
The templates will always receive the following context:
- - trigger: name of the event which triggered the template (string)
- - path: path of the file being templated (string)
- - container: key/value map of container properties (name, architecture, privileged and ephemeral) (map[string]string)
- - config: key/value map of the container's configuration (map[string]string)
- - devices: key/value map of the devices assigned to this container (map[string]map[string]string)
- - properties: key/value map of the template properties specified in metadata.yaml (map[string]string)
-The "create\_only" key can be set to have LXD only only create missing files but not overwrite an existing file.
+ - `trigger`: name of the event which triggered the template (string)
+ - `path`: path of the file being templated (string)
+ - `container`: key/value map of container properties (name, architecture, privileged and ephemeral) (map[string]string)
+ - `config`: key/value map of the container's configuration (map[string]string)
+ - `devices`: key/value map of the devices assigned to this container (map[string]map[string]string)
+ - `properties`: key/value map of the template properties specified in metadata.yaml (map[string]string)
+
+The `create_only` key can be set to have LXD only only create missing files but not overwrite an existing file.
As a general rule, you should never template a file which is owned by a
package or is otherwise expected to be overwritten by normal operation
of the container.
For convenience the following functions are exported to pongo templates:
- - config\_get("user.foo", "bar") => Returns the value of "user.foo" or "bar" if unset.
+
+ - `config_get("user.foo", "bar")` => Returns the value of `user.foo` or `"bar"` if unset.
From 279701e8ade1e769b00e469368af7b4edeb4f36d Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 11:53:03 +0200
Subject: [PATCH 15/23] doc: fixes in migration.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/migration.md | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/doc/migration.md b/doc/migration.md
index 7dfe8d94d..ba405f53f 100644
--- a/doc/migration.md
+++ b/doc/migration.md
@@ -4,10 +4,11 @@
Migration has two pieces, a "source", that is, the host that already has the
container, and a "sink", the host that's getting the container. Currently,
-in the 'pull' mode, the source sets up an operation, and the sink connects
+in the `pull` mode, the source sets up an operation, and the sink connects
to the source and pulls the container.
There are three websockets (channels) used in migration:
+
1. the control stream
2. the criu images stream
3. the filesystem stream
From 4f28a12825dd9f91e1c26fda0d25c5952ebf43e6 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 12:32:59 +0200
Subject: [PATCH 16/23] doc: fixes in production-setup.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/production-setup.md | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/doc/production-setup.md b/doc/production-setup.md
index d961d12c1..90e83bc95 100644
--- a/doc/production-setup.md
+++ b/doc/production-setup.md
@@ -57,13 +57,15 @@ You need to change `txqueuelen` of your real NIC to 10000 (not sure about the be
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.
For permanent lxdbr0 txqueuelen value change I prefer edit `/usr/lib/lxd/lxd-bridge`. You can add `ifconfig lxdbr0 txqueuelen 10000` in start section, just after iptables rules. For ex.:
+
```bash
iptables "${use_iptables_lock}" -I FORWARD -o "${LXD_BRIDGE}" -j ACCEPT -m comment --comment "managed by lxd-bridge"
iptables "${use_iptables_lock}" -t mangle -A POSTROUTING -o "${LXD_BRIDGE}" -p udp -m udp --dport 68 -j CHECKSUM --checksum-fill -m comment --comment "managed by lxd-bridge"
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 interfacename# txqueuelen 10000`
+You could set it txqueuelen temporary (for test purpose) with `ifconfig <interface> txqueuelen 10000`
#### /etc/sysctl.conf
From 56c73ed47090071579e7971174a2bc112e60c43a Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 12:33:30 +0200
Subject: [PATCH 17/23] doc: fixes in profiles.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/profiles.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/profiles.md b/doc/profiles.md
index ee52e5249..08d1eb9ae 100644
--- a/doc/profiles.md
+++ b/doc/profiles.md
@@ -8,9 +8,9 @@ specify a specific key wins.
In any case, resource-specific configuration always overrides that coming from
the profiles.
-If not present, LXD will create a "default" profile.
+If not present, LXD will create a `default` profile.
-The "default" profile is set for any new container created which doesn't
+The `default` profile is set for any new container created which doesn't
specify a different profiles list.
From 2f58bcb5bf0ae7aff7ddaac43e5924112aacd469 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 12:36:42 +0200
Subject: [PATCH 18/23] doc: fixes in requirements.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/requirements.md | 3 +++
1 file changed, 3 insertions(+)
diff --git a/doc/requirements.md b/doc/requirements.md
index 883f86e4e..e97d20a67 100644
--- a/doc/requirements.md
+++ b/doc/requirements.md
@@ -8,10 +8,12 @@ Both the golang and gccgo compilers are supported.
The minimum supported kernel version is 3.13.
LXD requires a kernel with support for:
+
* Namespaces (pid, net, uts, ipc and mount)
* Seccomp
The following optional features also require extra kernel options:
+
* Namespaces (user and cgroup)
* AppArmor (including Ubuntu patch for mount mediation)
* Control Groups (blkio, cpuset, devices, memory, pids and net\_prio)
@@ -21,6 +23,7 @@ As well as any other kernel feature required by the LXC version in use.
## LXC
LXD requires LXC 2.0.0 or higher with the following build options:
+
* apparmor (if using LXD's apparmor support)
* seccomp
From 92a16b7ac95512c5dfb6ac23f588a9afc46cb679 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 12:38:16 +0200
Subject: [PATCH 19/23] doc: fixes in security.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/security.md | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/doc/security.md b/doc/security.md
index 0d058ca1e..3166ad4f7 100644
--- a/doc/security.md
+++ b/doc/security.md
@@ -58,11 +58,12 @@ To establish a new trust relationship, a password must be set on the
server and send by the client when adding itself.
A remote add operation should therefore go like this:
+
1. Call GET /1.0
2. Ask the user to confirm the fingerprint.
3. Look at the dict we received back from the server. If "auth" is
- "untrusted", ask the user for the server's password and do a POST to
- /1.0/certificates, then call /1.0 again to check that we're indeed
+ "untrusted", ask the user for the server's password and do a `POST` to
+ `/1.0/certificates`, then call `/1.0` again to check that we're indeed
trusted.
4. Remote is now ready
From aa60fd9657d4064661fc8cd10babbcf4f2cb2220 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 12:40:56 +0200
Subject: [PATCH 20/23] doc: fixes in server.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/server.md | 11 +++++++----
1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/doc/server.md b/doc/server.md
index d182830f1..d4a698e8b 100644
--- a/doc/server.md
+++ b/doc/server.md
@@ -1,9 +1,10 @@
# Server configuration
The key/value configuration is namespaced with the following namespaces
currently supported:
- - core (core daemon configuration)
- - images (image configuration)
- - storage (storage configuration)
+
+ - `core` (core daemon configuration)
+ - `images` (image configuration)
+ - `storage` (storage configuration)
Key | Type | Default | Description
:-- | :--- | :------ | :----------
@@ -27,4 +28,6 @@ images.auto\_update\_cached | boolean | true | Wh
Those keys can be set using the lxc tool with:
- lxc config set <key> <value>
+```bash
+lxc config set <key> <value>
+```
From fcd11ce4d1464ab81ed22be0dad420a8f6261d0b Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 12:55:06 +0200
Subject: [PATCH 21/23] doc: fixes in userns-idmap.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/userns-idmap.md | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/doc/userns-idmap.md b/doc/userns-idmap.md
index cdd62ca53..642158087 100644
--- a/doc/userns-idmap.md
+++ b/doc/userns-idmap.md
@@ -22,15 +22,15 @@ User namespaces require a kernel >= 3.12, LXD will start even on older
kernels but will refuse to start containers.
# Allowed ranges
-On most hosts, LXD will check /etc/subuid and /etc/subgid for
+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.
If the range is shorter than 65536 (which includes no range at all),
then LXD will fail to create or start any container until this is corrected.
-If some but not all of /etc/subuid, /etc/subgid, newuidmap (path lookup)
-and newgidmap (path lookup) can be found on the system, LXD will fail
+If some but not all of `/etc/subuid`, `/etc/subgid`, `newuidmap` (path lookup)
+and `newgidmap` (path lookup) can be found on the system, LXD will fail
the startup of any container until this is corrected as this shows a
broken shadow setup.
From 2575ecdba9fad12e2274a71f2465f5de261f2581 Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Tue, 3 Oct 2017 15:31:15 +0200
Subject: [PATCH 22/23] doc: fixes in rest-api.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/rest-api.md | 171 +++++++++++++++++++++++++++++---------------------------
1 file changed, 90 insertions(+), 81 deletions(-)
diff --git a/doc/rest-api.md b/doc/rest-api.md
index 890592673..feceeae85 100644
--- a/doc/rest-api.md
+++ b/doc/rest-api.md
@@ -5,24 +5,25 @@ remote operations or a unix socket for local operations.
Not all of the REST interface requires authentication:
- * GET to / is allowed for everyone (lists the API endpoints)
- * GET to /1.0 is allowed for everyone (but result varies)
- * POST to /1.0/certificates is allowed for everyone with a client certificate
- * GET to /1.0/images/\* is allowed for everyone but only returns public images for unauthenticated users
+ * `GET` to `/` is allowed for everyone (lists the API endpoints)
+ * `GET` to `/1.0` is allowed for everyone (but result varies)
+ * `POST` to `/1.0/certificates` is allowed for everyone with a client certificate
+ * `GET` to `/1.0/images/*` is allowed for everyone but only returns public images for unauthenticated users
Unauthenticated endpoints are clearly identified as such below.
# API versioning
-The list of supported major API versions can be retrieved using GET /.
+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.
Feature additions done without breaking backward compatibility only
-result in addition to api\_extensions which can be used by the client
+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
There are three standard return types:
+
* Standard return value
* Background operation
* Error
@@ -105,11 +106,12 @@ and can be relied on by API clients. Then there is a text version meant
to make it easier for people manually using the API to figure out what's
happening.
-In most cases, those will be called status and status\_code, the former
+In most cases, those will be called status and `status_code`, the former
being the user-friendly string representation and the latter the fixed
numeric value.
The codes are always 3 digits, with the following ranges:
+
* 100 to 199: resource state (started, stopped, ready, ...)
* 200 to 399: positive action result
* 400 to 599: negative action result
@@ -137,7 +139,7 @@ Code | Meaning
# 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.
+A `recursion` argument can be passed to a GET query against a collection.
The default value is 0 which means that collection member URLs are
returned. Setting it to 1 will have those URLs be replaced by the object
@@ -162,36 +164,36 @@ notification type before triggering remote operations so that it doesn't
have to then poll for their status.
# API structure
- * /
- * /1.0
- * /1.0/certificates
- * /1.0/certificates/\<fingerprint\>
- * /1.0/containers
- * /1.0/containers/\<name\>
- * /1.0/containers/\<name\>/exec
- * /1.0/containers/\<name\>/files
- * /1.0/containers/\<name\>/snapshots
- * /1.0/containers/\<name\>/snapshots/\<name\>
- * /1.0/containers/\<name\>/state
- * /1.0/containers/\<name\>/logs
- * /1.0/containers/\<name\>/logs/\<logfile\>
- * /1.0/events
- * /1.0/images
- * /1.0/images/\<fingerprint\>
- * /1.0/images/\<fingerprint\>/export
- * /1.0/images/aliases
- * /1.0/images/aliases/\<name\>
- * /1.0/networks
- * /1.0/networks/\<name\>
- * /1.0/operations
- * /1.0/operations/\<uuid\>
- * /1.0/operations/\<uuid\>/wait
- * /1.0/operations/\<uuid\>/websocket
- * /1.0/profiles
- * /1.0/profiles/\<name\>
+ * `/`
+ * `/1.0`
+ * `/1.0/certificates`
+ * `/1.0/certificates/<fingerprint>`
+ * `/1.0/containers`
+ * `/1.0/containers/<name>`
+ * `/1.0/containers/<name>/exec`
+ * `/1.0/containers/<name>/files`
+ * `/1.0/containers/<name>/snapshots`
+ * `/1.0/containers/<name>/snapshots/<name>`
+ * `/1.0/containers/<name>/state`
+ * `/1.0/containers/<name>/logs`
+ * `/1.0/containers/<name>/logs/<logfile>`
+ * `/1.0/events`
+ * `/1.0/images`
+ * `/1.0/images/<fingerprint>`
+ * `/1.0/images/<fingerprint>/export`
+ * `/1.0/images/aliases`
+ * `/1.0/images/aliases/<name>`
+ * `/1.0/networks`
+ * `/1.0/networks/<name>`
+ * `/1.0/operations`
+ * `/1.0/operations/<uuid>`
+ * `/1.0/operations/<uuid>/wait`
+ * `/1.0/operations/<uuid>/websocket`
+ * `/1.0/profiles`
+ * `/1.0/profiles/<name>`
# API details
-## /
+## `/`
### GET
* Description: List of supported APIs
* Authentication: guest
@@ -204,7 +206,7 @@ Return value:
"/1.0"
]
-## /1.0/
+## `/1.0/`
### GET
* Description: Server configuration and environment information
* Authentication: guest, untrusted or trusted
@@ -271,7 +273,8 @@ Input (replaces any existing config with the provided one):
}
}
-## /1.0/certificates
+
+## `/1.0/certificates`
### GET
* Description: list of trusted certificates
* Authentication: trusted
@@ -299,7 +302,7 @@ Input:
"password": "server-trust-password" # The trust password for that server (only required if untrusted)
}
-## /1.0/certificates/\<fingerprint\>
+## `/1.0/certificates/<fingerprint>`
### GET
* Description: trusted certificate information
* Authentication: trusted
@@ -328,7 +331,7 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## /1.0/containers
+## `/1.0/containers`
### GET
* Description: List of containers
* Authentication: trusted
@@ -509,7 +512,7 @@ Input (using a local container):
"source": "my-old-container"} # Name of the source container
}
-## /1.0/containers/\<name\>
+## `/1.0/containers/<name>`
### GET
* Description: Container information
* Authentication: trusted
@@ -643,7 +646,7 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## /1.0/containers/\<name\>/exec
+## `/1.0/containers/<name>/exec`
### POST
* Description: run a remote command
* Authentication: trusted
@@ -716,22 +719,23 @@ 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
* Return: Raw file or standard error
The following headers will be set (on top of standard size and mimetype headers):
- * X-LXD-uid: 0
- * X-LXD-gid: 0
- * X-LXD-mode: 0700
+
+ * `X-LXD-uid`: 0
+ * `X-LXD-gid`: 0
+ * `X-LXD-mode`: 0700
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
@@ -741,14 +745,15 @@ Input:
* Standard http file upload
The following headers may be set by the client:
- * X-LXD-uid: 0
- * X-LXD-gid: 0
- * X-LXD-mode: 0700
+
+ * `X-LXD-uid`: 0
+ * `X-LXD-gid`: 0
+ * `X-LXD-mode`: 0700
This is designed to be easily usable from the command line or even a web
browser.
-## /1.0/containers/\<name\>/logs
+## `/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
@@ -765,7 +770,7 @@ Return:
"/1.0/containers/blah/logs/lxc.log"
]
-## /1.0/containers/\<name\>/logs/\<logfile\>
+## `/1.0/containers/<name>/logs/<logfile>`
### GET
* Description: returns the contents of a particular log file.
* Authentication: trusted
@@ -778,7 +783,7 @@ Return:
* Operation: Sync
* Return: empty response or standard error
-## /1.0/containers/\<name\>/snapshots
+## `/1.0/containers/<name>/snapshots`
### GET
* Description: List of snapshots
* Authentication: trusted
@@ -804,7 +809,7 @@ Input:
"stateful": true # Whether to include state too
}
-## /1.0/containers/\<name\>/snapshots/\<name\>
+## `/1.0/containers/<name>/snapshots/<name>`
### GET
* Description: Snapshot information
* Authentication: trusted
@@ -900,7 +905,7 @@ Input (none at present):
HTTP code for this should be 202 (Accepted).
-## /1.0/containers/\<name\>/state
+## `/1.0/containers/<name>/state`
### GET
* Description: current state
* Authentication: trusted
@@ -1063,21 +1068,23 @@ 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
* Return: none (never ending flow of events)
Supported arguments are:
+
* type: comma separated list of notifications to subscribe to (defaults to all)
The notification types are:
+
* operation (notification about creation, updates and termination of all background operations)
* logging (every log entry from the server)
@@ -1103,7 +1110,7 @@ This never returns. Each notification is sent as a separate JSON dict:
}
}
-## /1.0/images
+## `/1.0/images`
### GET
* Description: list of images (public or private)
* Authentication: guest or trusted
@@ -1126,16 +1133,18 @@ Return:
* Return: background operation or standard error
Input (one of):
+
* Standard http file upload
* Source image dictionary (transfers a remote image)
* Source container dictionary (makes an image out of a local container)
* Remote image URL dictionary (downloads a remote image)
In the http file upload case, The following headers may be set by the client:
- * X-LXD-fingerprint: SHA-256 (if set, uploaded file must match)
- * X-LXD-filename: FILENAME (used for export)
- * X-LXD-public: true/false (defaults to false)
- * X-LXD-properties: URL-encoded key value pairs without duplicate keys (optional properties)
+
+ * `X-LXD-fingerprint`: SHA-256 (if set, uploaded file must match)
+ * `X-LXD-filename`: FILENAME (used for export)
+ * `X-LXD-public`: true/false (defaults to false)
+ * `X-LXD-properties`: URL-encoded key value pairs without duplicate keys (optional properties)
In the source image case, the following dict must be used:
@@ -1190,8 +1199,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
@@ -1263,8 +1272,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
@@ -1274,11 +1283,11 @@ The secret string is required when an untrusted LXD is spawning a new
container from a private image stored on a different LXD.
Rather than require a trust relationship between the two LXDs, the
-client will POST to /1.0/images/\<fingerprint\>/export to get a secret
+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
+## `/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
@@ -1303,7 +1312,7 @@ 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
+## `/1.0/images/aliases`
### GET
* Description: list of aliases (public or private based on image visibility)
* Authentication: guest or trusted
@@ -1332,7 +1341,7 @@ Input:
"name": "alias-name"
}
-## /1.0/images/aliases/\<name\>
+## `/1.0/images/aliases/<name>`
### GET
* Description: Alias description and target
* Authentication: guest or trusted
@@ -1385,7 +1394,7 @@ Input (none at present):
{
}
-## /1.0/networks
+## `/1.0/networks`
### GET
* Description: list of networks
* Authentication: trusted
@@ -1397,7 +1406,7 @@ Input (none at present):
"/1.0/networks/lxdbr0"
]
-## /1.0/networks/\<name\>
+## `/1.0/networks/<name>`
### GET
* Description: information about a network
* Authentication: trusted
@@ -1412,7 +1421,7 @@ Input (none at present):
]
}
-## /1.0/operations
+## `/1.0/operations`
### GET
* Description: list of operations
* Authentication: trusted
@@ -1424,7 +1433,7 @@ Input (none at present):
"/1.0/operations/092a8755-fd90-4ce4-bf91-9f87d03fd5bc"
]
-## /1.0/operations/\<uuid\>
+## `/1.0/operations/<uuid>`
### GET
* Description: background operation
* Authentication: trusted
@@ -1465,8 +1474,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
@@ -1476,8 +1485,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
@@ -1490,7 +1499,7 @@ Input (similar but times out after 30s): ?timeout=30
* Operation: sync
* Return: websocket stream or standard error
-## /1.0/profiles
+## `/1.0/profiles`
### GET
* Description: List of configuration profiles
* Authentication: trusted
@@ -1525,7 +1534,7 @@ Input:
}
}
-## /1.0/profiles/\<name\>
+## `/1.0/profiles/<name>`
### GET
* Description: profile configuration
* Authentication: trusted
From e1076d27fef170294bbd3c4653f6ceeea94ea5ab Mon Sep 17 00:00:00 2001
From: Alberto Donato <alberto.donato at canonical.com>
Date: Wed, 4 Oct 2017 11:04:44 +0200
Subject: [PATCH 23/23] doc: fixes in storage-backends.md
Signed-off-by: Alberto Donato <alberto.donato at canonical.com>
---
doc/storage-backends.md | 17 +++++++++--------
1 file changed, 9 insertions(+), 8 deletions(-)
diff --git a/doc/storage-backends.md b/doc/storage-backends.md
index 4ede1d404..c5eb04237 100644
--- a/doc/storage-backends.md
+++ b/doc/storage-backends.md
@@ -27,12 +27,13 @@ When the filesystem on the source and target hosts differs or when there is no f
rsync is used to transfer the container content across.
## I/O limits
-I/O limits in IOp/s or MB/s can be set on storage devices when attached to a container (see containers.md).
+I/O limits in IOp/s or MB/s can be set on storage devices when attached to a container (see [Containers](containers.md)).
-Those are applied through the Linux "blkio" cgroup controller which makes it possible
+Those are applied through the Linux `blkio` cgroup controller which makes it possible
to restrict I/O at the disk level (but nothing finer grained than that).
Because those apply to a whole physical disk rather than a partition or path, the following restrictions apply:
+
- Limits will not apply to filesystems that are backed by virtual devices (e.g. device mapper).
- If a fileystem is backed by multiple block devices, each device will get the same limit.
- If the container is passed two disk devices that are each backed by the same disk,
@@ -54,7 +55,7 @@ This also means that access to cached data will not be affected by the limit.
- The btrfs backend is automatically used if /var/lib/lxd is on a btrfs filesystem.
- Uses a subvolume per container, image and snapshot, creating btrfs snapshots when creating a new object.
- - When using for nesting, the host btrfs filesystem must be mounted with the "user\_subvol\_rm\_allowed" mount option.
+ - When using for nesting, the host btrfs filesystem must be mounted with the `user_subvol_rm_allowed` mount option.
- btrfs supports storage quotas via qgroups. While btrfs qgroups are
hierarchical, new subvolumes will not automatically be added to the qgroups
of their parent subvolumes. This means that users can trivially escape any
@@ -64,16 +65,16 @@ This also means that access to cached data will not be affected by the limit.
### LVM
- - A LVM VG must be created and then storage.lvm\_vg\_name set to point to it.
- - If a thinpool doesn't already exist, one will be created, the name of the thinpool can be set with storage.lvm\_thinpool\_name .
+ - A LVM VG must be created and then `storage.lvm_vg_name` set to point to it.
+ - If a thinpool doesn't already exist, one will be created, the name of the thinpool can be set with `storage.lvm_thinpool_name` .
- Uses LVs for images, then LV snapshots for containers and container snapshots.
- The filesystem used for the LVs is ext4 (can be configured to use xfs instead).
- LVs are created with a default size of 10GiB (can be configured through).
### ZFS
- - LXD can use any zpool or part of a zpool. storage.zfs\_pool\_name must be set to the path to be used.
- - ZFS doesn't have to (and shouldn't be) mounted on /var/lib/lxd
+ - LXD can use any zpool or part of a zpool. `storage.zfs_pool_name` must be set to the path to be used.
+ - ZFS doesn't have to (and shouldn't be) mounted on `/var/lib/lxd`
- Uses ZFS filesystems for images, then snapshots and clones to create containers and snapshots.
- Due to the way copy-on-write works in ZFS, parent filesystems can't
be removed until all children are gone. As a result, LXD will
@@ -105,7 +106,7 @@ This also means that access to cached data will not be affected by the limit.
#### Growing a loop backed ZFS pool
LXD doesn't let you directly grow a loop backed ZFS pool, but you can do so with:
-```
+```bash
sudo truncate -s +5G /var/lib/lxd/zfs.img
sudo zpool set autoexpand=on lxd
sudo zpool online -e lxd /var/lib/lxd/zfs.img
More information about the lxc-devel
mailing list