Difference between revisions of "LXD"

From ArchWiki
Jump to navigation Jump to search
m (Add link to documentation)
(→‎Accessing LXD as a unprivileged user: add warning about lxd group membership similar to one in docker page)
 
(25 intermediate revisions by 10 users not shown)
Line 1: Line 1:
 
[[Category:Virtualization]]
 
[[Category:Virtualization]]
 +
[[es:LXD]]
 
[[ja:LXD]]
 
[[ja:LXD]]
 
'''[https://linuxcontainers.org/lxd/ LXD]''' is a container "hypervisor" and a new user experience for [[Linux Containers]].
 
'''[https://linuxcontainers.org/lxd/ LXD]''' is a container "hypervisor" and a new user experience for [[Linux Containers]].
 +
 +
{{Related articles start}}
 +
{{Related|Linux Containers}}
 +
{{Related articles end}}
  
 
== Setup ==
 
== Setup ==
Line 7: Line 12:
 
Install [[LXC]] and the {{AUR|lxd}} package, then [[start]] {{ic|lxd.service}}.
 
Install [[LXC]] and the {{AUR|lxd}} package, then [[start]] {{ic|lxd.service}}.
  
Verify that the running kernel is properly configured to run a container:
+
See [[Linux Containers#Enable support to run unprivileged containers (optional)]] if you want to run ''unprivileged'' containers. Otherwise see [[#Launching container without CONFIG_USER_NS]].
$ lxc-checkconfig
 
 
 
The safest type of container that LXD can create is ''unprivileged''. This is done by leveraging the Linux kernel's '''User Namespaces''' feature. However, due to more general security concerns, the default Arch kernel does ''not'' ship with User Namespaces enabled ({{ic|CONFIG_USER_NS}} is a kernel compile-time decision). You have three (3) options to use a kernel with {{ic|CONFIG_USER_NS}} and thereby create ''unprivileged'' containers:
 
 
 
* Install the {{Pkg|linux-hardened}} kernel package along-side the default {{Pkg|linux}} kernel.  When you wish to run unprivileged LXD containers, boot with {{Pkg|linux-hardened}} by selecting it in the bootloader. {{Pkg|linux-hardened}} is compiled with {{ic|CONFIG_USER_NS}}. Otherwise, run with {{Pkg|linux}} as normal.
 
* Install the {{AUR|linux-userns}} or {{AUR|linux-lts-userns}} packages from the [[AUR]].  Both are compiled with {{ic|CONFIG_USER_NS}}, the latter being the Long-Term Support version.
 
* Compile and install your own custom kernel with {{ic|CONFIG_USER_NS}} enabled.
 
  
{{Note|If you decide to run a kernel '''without User Namespaces''', LXD containers will be ''privileged'' and that involves some risk (in the event a process escapes the container).  See [[#Launching container without CONFIG_USER_NS]] below.}}
+
=== Alternative installation method ===
  
=== Sub{u,g}id configuration ===
+
An alternative method of installation is via [[snapd]], by installing the {{AUR|snapd}} package and running:
  
You will need sub{u,g}ids for root, so that LXD can create the unprivileged containers:
+
# snap install lxd
  
$ echo "root:1000000:65536" | sudo tee -a /etc/subuid /etc/subgid
+
=== Configure LXD ===
 +
LXD needs to configure a storage pool, and (if you want internet access) network configuration. To do so, run the following as root:
 +
# lxd init
  
 
=== Accessing LXD as a unprivileged user ===
 
=== Accessing LXD as a unprivileged user ===
Line 30: Line 30:
 
  # usermod -a -G lxd <user>
 
  # usermod -a -G lxd <user>
  
 +
{{Warning|Anyone added to the {{ic|lxd}} group is root equivalent. More information [https://github.com/lxc/lxd#security here] and [https://bugs.launchpad.net/ubuntu/+source/lxd/+bug/1829071 here].}}
 +
 +
== Basic usage ==
 +
=== Create container ===
 +
 +
LXD has two parts, the daemon (the lxd binary), and the client (the lxc binary). Now that the daemon is all configured and running, you can create a container:
 +
 +
$ lxc launch ubuntu:16.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)
 +
 +
$ lxc launch images:centos/7/amd64 centos
 +
 +
To create an amd64 Arch container:
 +
 +
$ lxc launch images:archlinux/current/amd64 arch
 +
 +
== Advanced usage ==
 
=== LXD Networking ===
 
=== LXD Networking ===
  
Line 72: Line 90:
 
If you encounter issue with the provided example configuration, or have suggestions to improve it, please leave a comment on the {{AUR|lxd}} page.
 
If you encounter issue with the provided example configuration, or have suggestions to improve it, please leave a comment on the {{AUR|lxd}} page.
  
== Basic usage ==
+
=== Modify processes and files limit ===
=== First steps ===
+
 
 +
You may want to increase file descriptor limit or max user processes limit, since default file descriptor limit is 1024 on Arch Linux.
 +
 
 +
[[Edit]] the {{ic|lxd.service}}:
 +
 
 +
{{hc|# systemctl edit lxd.service|2=
 +
[Service]
 +
LimitNOFILE=infinity
 +
LimitNPROC=infinity
 +
TasksMax=infinity
 +
}}
 +
 
 +
== Troubleshooting ==
 +
=== Check kernel config ===
 +
By default Arch Linux kernel is compiled correctly for Linux Containers and its frontend LXD. However, if you're using a custom kernel, or changed kernel options the kernel might be configured incorrectly. Verify that the running kernel is properly configured to run a container:
 +
$ lxc-checkconfig
 +
 
 +
=== Launching container without CONFIG_USER_NS ===
 +
For launching images you must provide {{ic|1=security.privileged=true}} during image creation:
 +
 
 +
$ lxc launch ubuntu:16.04 ubuntu -c security.privileged=true
  
LXD has two parts, the daemon (the lxd binary), and the client (the lxc binary). Now that the daemon is all configured and running, you can create a container:
+
Or for already existed image you may edit config:
  
$ lxc launch ubuntu:14.04
+
{{hc|$ lxc config edit ubuntu|
 +
name: ubuntu
 +
profiles:
 +
- default
 +
config:
 +
  ...
 +
  security.privileged: "true"
 +
  ...
 +
devices:
 +
  root:
 +
    path: /
 +
    type: disk
 +
ephemeral: false
 +
}}
  
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)
+
Or to enable {{ic|1=security.privileged=true}} for new containers, edit the config for the default profile:
  
  $ lxc launch images:centos/7/amd64 centos
+
  $ lxc profile edit default
  
== Advance usage ==
+
=== No ipv4 on unprivileged Arch container ===
=== Modify processes and files limit ===
 
  
You may want to increase file descriptor limit or max user processes limit, since default file descriptor limit is 1024 on Archlinux
+
{{Remove|As of systemd v239, this issue has been [https://github.com/lxc/lxd/issues/4071#issuecomment-405868612 fixed]. Updating {{pkg|systemd}} should fix this issue without the workaround below.}}
  
$ sudo systemctl edit lxd
+
This was tested and validated on LXD v.2.20. The container can not start the {{ic|1=systemd-networkd}} service so does not get a valid ipv4 address. A work-around was suggested by Stéphane Graber ([https://github.com/lxc/lxd/issues/4071 Github Issue]), execute on the host and restart the container:
  
And config as follow:
+
$ lxc profile set default security.syscalls.blacklist "keyctl errno 38"
  
[Service]
+
:stgraber: "The reason is that the networkd systemd unit somehow makes use of the kernel keyring, which doesn't work inside unprivileged containers right now. The line above makes that system call return not-implemented which is enough of a workaround to get things going again."
LimitNOFILE=infinity
 
LimitNPROC=infinity
 
TasksMax=infinity
 
  
Then restart lxd
+
=== Resource limits are not applied when viewed from inside a container ===
  
$ sudo systemctl restart lxd
+
The service lxcfs (found in the Community repository) needs to be installed and started :
  
== Troubleshooting ==
+
$ systemctl start lxcfs
=== Launching container without CONFIG_USER_NS ===
 
For launching images you must provide {{ic|1=security.privileged=true}} during image creation:
 
  
$ lxc launch ubuntu:16.04 ubuntu -c security.privileged=true
+
lxd will need to be restarted. Enable lxcfs for the service to be started at boot time.  
  
Or for already existed image you may edit config:
+
== Uninstall ==
 +
[[Stop]] and disable {{ic|lxd.service}} and {{ic|lxd.socket}}:
  
$ lxc config edit ubuntu
+
Then uninstall the package via pacman:
 +
  # pacman -R lxd
  
name: ubuntu
+
If you uninstalled the package without disabling the service, you might have a lingering broken symlink at {{ic|/etc/systemd/system/multi-user.wants/lxd.service}}.
profiles:
 
- default
 
config:
 
  ...
 
  security.privileged: "true"
 
  ...
 
devices:
 
  root:
 
    path: /
 
    type: disk
 
ephemeral: false
 
  
Or to enable {{ic|1=security.privileged=true}} for new containers, edit the config for the default profile:
+
If you want to remove all data:
 +
  # rm -r /var/lib/lxd
  
$ lxc profile edit default
+
If you used any of the example networking configs, you should remove those as well.
  
 
== See also ==
 
== See also ==

Latest revision as of 14:52, 1 July 2019

LXD is a container "hypervisor" and a new user experience for Linux Containers.

Setup

Required software

Install LXC and the lxdAUR package, then start lxd.service.

See Linux Containers#Enable support to run unprivileged containers (optional) if you want to run unprivileged containers. Otherwise see #Launching container without CONFIG_USER_NS.

Alternative installation method

An alternative method of installation is via snapd, by installing the snapdAUR package and running:

# snap install lxd

Configure LXD

LXD needs to configure a storage pool, and (if you want internet access) network configuration. To do so, run the following as root:

# lxd init

Accessing LXD as a unprivileged user

By default the LXD daemon allows users in the lxd group access, so add your user to the group:

# usermod -a -G lxd <user>
Warning: Anyone added to the lxd group is root equivalent. More information here and here.

Basic usage

Create container

LXD has two parts, the daemon (the lxd binary), and the client (the lxc binary). Now that the daemon is all configured and running, you can create a container:

$ lxc launch ubuntu:16.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)

$ lxc launch images:centos/7/amd64 centos

To create an amd64 Arch container:

$ lxc launch images:archlinux/current/amd64 arch

Advanced usage

LXD Networking

LXD uses LXC's networking capabilities. By default it connects containers to the lxcbr0 network device. Refer to the LXC documentation on network configuration to set up a bridge for your containers.

If you want to use a different interface than lxcbr0 edit the default using the lxc command line tool:

$ lxc profile edit default

An editor will open with a config file that by default contains:

name: default
config: {}
devices:
  eth0:
    name: eth0
    nictype: bridged
    parent: lxcbr0
    type: nic

You can set the parent parameter to whichever bridge you want LXD to attach the containers to by default.

Example network configuration

Thanks to @jpic, the LXD package now provides some example networking configuration in /usr/share/lxd/. To use this configuration run the following commands:

$ ln -s /usr/share/lxd/dnsmasq-lxd.conf /etc/dnsmasq-lxd.conf
$ ln -s /usr/share/lxd/systemd/system/dnsmasq@lxd.service /etc/systemd/system/dnsmasq@lxd.service 
$ ln -s /usr/share/lxd/netctl/lxd  /etc/netctl/lxd
$ ln -s /usr/share/lxd/dbus-1/system.d/dnsmasq-lxd.conf /etc/dbus-1/system.d/dnsmasq-lxd.conf

If you use NetworkManager, also symlink the following file:

$ ln -s /usr/share/lxd/NetworkManager/dnsmasq.d/lxd.conf /etc/NetworkManager/dnsmasq.d/lxd.conf

Change parent: lxcbr0 to parent: lxd:

$ lxc profile edit default

Finally, enable and start dnsmasq@lxd.service and netctl@lxd.service.

If you encounter issue with the provided example configuration, or have suggestions to improve it, please leave a comment on the lxdAUR page.

Modify processes and files limit

You may want to increase file descriptor limit or max user processes limit, since default file descriptor limit is 1024 on Arch Linux.

Edit the lxd.service:

# systemctl edit lxd.service
[Service]
LimitNOFILE=infinity
LimitNPROC=infinity
TasksMax=infinity

Troubleshooting

Check kernel config

By default Arch Linux kernel is compiled correctly for Linux Containers and its frontend LXD. However, if you're using a custom kernel, or changed kernel options the kernel might be configured incorrectly. Verify that the running kernel is properly configured to run a container:

$ lxc-checkconfig

Launching container without CONFIG_USER_NS

For launching images you must provide security.privileged=true during image creation:

$ lxc launch ubuntu:16.04 ubuntu -c security.privileged=true

Or for already existed image you may edit config:

$ lxc config edit ubuntu
name: ubuntu
profiles:
- default
config:
  ...
  security.privileged: "true"
  ...
devices:
  root:
    path: /
    type: disk
ephemeral: false

Or to enable security.privileged=true for new containers, edit the config for the default profile:

$ lxc profile edit default

No ipv4 on unprivileged Arch container

Tango-edit-cut.pngThis section is being considered for removal.Tango-edit-cut.png

Reason: As of systemd v239, this issue has been fixed. Updating systemd should fix this issue without the workaround below. (Discuss in Talk:LXD#)

This was tested and validated on LXD v.2.20. The container can not start the systemd-networkd service so does not get a valid ipv4 address. A work-around was suggested by Stéphane Graber (Github Issue), execute on the host and restart the container:

$ lxc profile set default security.syscalls.blacklist "keyctl errno 38"
stgraber: "The reason is that the networkd systemd unit somehow makes use of the kernel keyring, which doesn't work inside unprivileged containers right now. The line above makes that system call return not-implemented which is enough of a workaround to get things going again."

Resource limits are not applied when viewed from inside a container

The service lxcfs (found in the Community repository) needs to be installed and started :

$ systemctl start lxcfs

lxd will need to be restarted. Enable lxcfs for the service to be started at boot time.

Uninstall

Stop and disable lxd.service and lxd.socket:

Then uninstall the package via pacman:

 # pacman -R lxd

If you uninstalled the package without disabling the service, you might have a lingering broken symlink at /etc/systemd/system/multi-user.wants/lxd.service.

If you want to remove all data:

 # rm -r /var/lib/lxd

If you used any of the example networking configs, you should remove those as well.

See also