[lxc-devel] [lxd/master] README: Seriously rework the content
stgraber on Github
lxc-bot at linuxcontainers.org
Mon Jul 3 21:45:08 UTC 2017
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 354 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20170703/0a22ceef/attachment.bin>
-------------- next part --------------
From 7bcba143993f8956ef47c01e655501d9391fb806 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Graber?= <stgraber at ubuntu.com>
Date: Mon, 3 Jul 2017 17:32:26 -0400
Subject: [PATCH] README: Seriously rework the content
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Signed-off-by: Stéphane Graber <stgraber at ubuntu.com>
---
README.md | 232 +++++++++++++++++++++++---------------------------------------
1 file changed, 87 insertions(+), 145 deletions(-)
diff --git a/README.md b/README.md
index c3e4d2514..b4bb38402 100644
--- a/README.md
+++ b/README.md
@@ -1,120 +1,52 @@
+[](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.
-REST API, command line tool and OpenStack integration plugin for LXC.
+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.
-LXD is pronounced lex-dee.
-
-To easily see what LXD is about, you can [try it online](https://linuxcontainers.org/lxd/try-it).
+To get a better idea of what LXD is and what it does, you can [try it online](/lxd/try-it/)!
+Then if you want to run it locally, take a look at our [getting started guide](/lxd/getting-started-cli/).
## Status
-
-* GoDoc: [](https://godoc.org/github.com/lxc/lxd/client)
-* Jenkins (Linux): [](https://jenkins.linuxcontainers.org/job/lxd-github-commit/)
-* Travis (macOS): [](https://travis-ci.org/lxc/lxd/)
-* AppVeyor (Windows): [](https://ci.appveyor.com/project/lxc/lxd/)
-* Weblate (translations): [](https://hosted.weblate.org/projects/linux-containers/lxd/)
-
-
-## Getting started with LXD
-
-Since LXD development is happening at such a rapid pace, we only provide daily
-builds right now. They're available via:
-
- sudo add-apt-repository ppa:ubuntu-lxc/lxd-git-master && sudo apt-get update
- sudo apt-get install lxd
-
-Because group membership is only applied at login, you then either need to
-close and re-open your user session or use the "newgrp lxd" command in the
-shell you're going to interact with lxd from.
-
- newgrp lxd
-
-After you've got LXD installed and a session with the right permissions, you
-can take your [first steps](#first-steps).
-
-#### Getting started with LXD on Windows
-
-LXD server is not available on Windows, but it is possible to use
-[`lxc` client](https://ci.appveyor.com/project/lxc/lxd/branch/master/artifacts)
-with
-[some limitations](https://github.com/lxc/lxd/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20windows)
-to control remote containers.
-
-
-## 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"
- }
-}
-```
-
-## Building from source
-
+Type | Service | Status
+--- | --- | ---
+CI (Linux) | Jenkins | [](https://jenkins.linuxcontainers.org/job/lxd-github-commit/)
+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. All the right versions dependencies are available
-via the LXD PPA:
+Golang 1.5 or later to work. On ubuntu, you can get those with:
- sudo apt-get install software-properties-common
- sudo add-apt-repository ppa:ubuntu-lxc/lxd-git-master
- sudo apt-get update
- sudo apt-get install acl dnsmasq-base git golang liblxc1 lxc-dev make pkg-config rsync squashfs-tools tar xz-utils
+ sudo apt update
+ sudo apt install acl dnsmasq-base git golang liblxc1 lxc-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
+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-get install lvm2 thin-provisioning-tools
- sudo apt-get install btrfs-tools
+ sudo apt install lvm2 thin-provisioning-tools
+ sudo apt install btrfs-tools
To run the testsuite, you'll also need:
- sudo apt-get install curl gettext jq sqlite3 uuid-runtime bzr
+ 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:
+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
@@ -129,7 +61,6 @@ And then download it as usual:
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:
@@ -140,59 +71,29 @@ group to talk to LXD; you can create your own group if you want):
sudo -E $GOPATH/bin/lxd --group sudo
-## First steps
-
-LXD has two parts, the daemon (the `lxd` binary), and the client (the `lxc`
-binary). Now that the daemon is all configured and running (either via the
-packaging or via the from-source instructions above), you can create a container:
-
- $GOPATH/bin/lxc launch ubuntu:14.04
-
-Alternatively, you can also use a remote LXD host as a source of images.
-One comes pre-configured in LXD, called "images" (images.linuxcontainers.org)
-
- $GOPATH/bin/lxc launch images:centos/7/amd64 centos
+## 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.
-
-Contributions to this project should be sent as pull requests on github.
-
-## Hacking
-
-Sometimes it is useful to view the raw response that LXD sends; you can do
-this by:
-
- lxc config set core.trust_password foo
- lxc remote add local 127.0.0.1:8443
- 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
-
-## Upgrading
-
-The `lxd` and `lxc` (`lxd-client`) binaries should be upgraded at the same time with:
-
- apt-get update
- apt-get install lxd lxd-client
+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`
@@ -209,7 +110,6 @@ the `config set` command on the server:
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:
@@ -225,7 +125,6 @@ certificate from `.config/lxc/client.crt` to the server and adding it with:
#### 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
@@ -250,7 +149,6 @@ 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:
@@ -267,8 +165,7 @@ 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:
+Yes. The easiest way to do that is using a privileged container to avoid file ownership issues:
1.a) create a container.
@@ -282,7 +179,52 @@ Yes. The easiest way to do that is using a privileged container:
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`. No other changes should be necessary.
+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
+
+## 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"
+ }
+}
+```
More information about the lxc-devel
mailing list