vagrant-lxc-ng/README.md

169 lines
6.7 KiB
Markdown
Raw Normal View History

# vagrant-lxc
2014-08-09 19:20:08 +00:00
[![Build Status](https://travis-ci.org/fgrehm/vagrant-lxc.png?branch=master)](https://travis-ci.org/fgrehm/vagrant-lxc) [![Gem Version](https://badge.fury.io/rb/vagrant-lxc.png)](http://badge.fury.io/rb/vagrant-lxc) [![Code Climate](https://codeclimate.com/github/fgrehm/vagrant-lxc.png)](https://codeclimate.com/github/fgrehm/vagrant-lxc) [![Coverage Status](https://coveralls.io/repos/fgrehm/vagrant-lxc/badge.png?branch=master)](https://coveralls.io/r/fgrehm/vagrant-lxc) [![Gittip](http://img.shields.io/gittip/fgrehm.svg)](https://www.gittip.com/fgrehm/) [![Gitter chat](https://badges.gitter.im/fgrehm/vagrant-lxc.png)](https://gitter.im/fgrehm/vagrant-lxc)
2013-03-08 05:04:17 +00:00
2013-05-17 23:22:30 +00:00
[LXC](http://lxc.sourceforge.net/) provider for [Vagrant](http://www.vagrantup.com/) 1.1+
2013-03-03 03:38:48 +00:00
This is a Vagrant plugin that allows it to control and provision Linux Containers
2013-11-07 00:07:36 +00:00
as an alternative to the built in VirtualBox provider for Linux hosts. Check out
[this blog post](http://fabiorehm.com/blog/2013/04/28/lxc-provider-for-vagrant/)
to see it in action.
## Features
2013-03-03 03:38:48 +00:00
2013-07-28 16:35:40 +00:00
* Provides the same workflow as the Vagrant VirtualBox provider
* Port forwarding via [`redir`](http://linux.die.net/man/1/redir)
2013-04-10 06:12:10 +00:00
2013-05-17 23:22:30 +00:00
## Requirements
* [Vagrant 1.1+](http://www.vagrantup.com/downloads.html)
2013-05-17 23:22:30 +00:00
* lxc 0.7.5+
2014-03-21 23:17:52 +00:00
* `redir` (if you are planning to use port forwarding)
* `brctl` (if you are planning to use private networks, on Ubuntu this means `apt-get install bridge-utils`)
* A [kernel != 3.5.0-17.28](https://github.com/fgrehm/vagrant-lxc/wiki/Troubleshooting#wiki-im-unable-to-restart-containers)
2013-05-17 23:22:30 +00:00
2014-05-13 03:25:53 +00:00
The plugin is known to work better and pretty much out of the box on Ubuntu 14.04+
hosts and installing the dependencies on it basically means a `apt-get install lxc lxc-templates cgroup-lite redir`
and a `apt-get update && apt-get dist-upgrade` to upgrade the kernel. For Debian
2014-05-13 03:25:53 +00:00
hosts you'll need to follow the instructions described on the [Wiki](https://github.com/fgrehm/vagrant-lxc/wiki/Usage-on-debian-hosts)
and old lxc versions (like 0.7.5 shipped with Ubuntu 12.04 by default) might require
[additional configurations to work](#backingstore-options).
2013-09-28 04:19:25 +00:00
If you are on a Mac or Windows machine, you might want to have a look at [this](http://the.taoofmac.com/space/HOWTO/Vagrant)
blog post for some ideas on how to set things up or check out [this other repo](https://github.com/fgrehm/vagrant-lxc-vbox-hosts)
for a set of Vagrant VirtualBox machines ready for vagrant-lxc usage.
2013-03-03 03:38:48 +00:00
2013-11-04 15:00:20 +00:00
**NOTE: Some users have been experiencing networking issues and right now you might need to
disable checksum offloading as described on [this comment](https://github.com/fgrehm/vagrant-lxc/issues/153#issuecomment-26441273)**
2013-03-03 03:38:48 +00:00
2013-04-10 06:12:10 +00:00
## Installation
```
vagrant plugin install vagrant-lxc
```
2014-03-27 22:44:33 +00:00
## Quick start
2013-03-03 03:38:48 +00:00
```
2014-03-27 22:44:33 +00:00
vagrant init fgrehm/precise64-lxc
vagrant up --provider=lxc
2013-03-03 03:38:48 +00:00
```
2014-09-23 02:07:39 +00:00
_Set the `VAGRANT_DEFAULT_PROVIDER` environmental variable to `lxc` in order to
avoid typing `--provider=lxc` all the time._
2013-05-17 23:22:30 +00:00
2014-05-13 03:27:49 +00:00
## Base boxes
Base boxes can be found on [VagrantCloud](https://vagrantcloud.com/search?provider=lxc)
and some scripts to build your own are available at [fgrehm/vagrant-lxc-base-boxes](https://github.com/fgrehm/vagrant-lxc-base-boxes).
If you want to build your own boxes, please have a look at [`BOXES.md`](https://github.com/fgrehm/vagrant-lxc/tree/master/BOXES.md)
for more information.
2014-05-13 03:25:53 +00:00
## Advanced configuration
2013-05-17 23:22:30 +00:00
If you want, you can modify container configurations from within your Vagrantfile
using the [provider block](http://docs.vagrantup.com/v2/providers/configuration.html):
2013-03-04 01:42:18 +00:00
2013-05-17 23:22:30 +00:00
```ruby
Vagrant.configure("2") do |config|
config.vm.box = "quantal64"
2013-03-03 03:38:48 +00:00
config.vm.provider :lxc do |lxc|
2013-11-07 00:07:36 +00:00
# Same effect as 'customize ["modifyvm", :id, "--memory", "1024"]' for VirtualBox
2013-04-10 06:12:10 +00:00
lxc.customize 'cgroup.memory.limit_in_bytes', '1024M'
2013-03-03 03:38:48 +00:00
end
end
```
vagrant-lxc will then write out `lxc.cgroup.memory.limit_in_bytes='1024M'` to the
2013-09-28 04:19:25 +00:00
container config file (usually kept under `/var/lib/lxc/<container>/config`)
prior to starting it.
2013-05-17 23:22:30 +00:00
2014-03-25 03:17:09 +00:00
For other configuration options, please check the [lxc.conf manpages](http://manpages.ubuntu.com/manpages/precise/man5/lxc.conf.5.html).
2013-04-10 06:12:10 +00:00
### Container naming
2014-01-31 17:01:27 +00:00
By default vagrant-lxc will attempt to generate a unique container name
for you. However, if the container name is important to you, you may use the
`container_name` attribute to set it explicitly from the `provider` block:
2014-01-31 17:01:27 +00:00
```ruby
Vagrant.configure("2") do |config|
config.vm.define "db" do |node|
node.vm.provider :lxc do |lxc|
lxc.container_name = :machine # Sets the container name to 'db'
lxc.container_name = 'mysql' # Sets the container name to 'mysql'
2014-01-31 17:01:27 +00:00
end
end
end
```
### Backingstore options
2014-05-13 03:25:53 +00:00
Support for setting `lxc-create`'s backingstore option (`-B` and related) can be
specified from the provider block and it defaults to `best`, to change it:
```ruby
Vagrant.configure("2") do |config|
config.vm.provider :lxc do |lxc|
2014-05-13 03:25:53 +00:00
lxc.backingstore = 'lvm' # or 'btrfs',...
# lvm specific options
lxc.backingstore_option '--vgname', 'schroots'
lxc.backingstore_option '--fssize', '5G'
lxc.backingstore_option '--fstype', 'xfs'
end
end
```
For old versions of lxc (like 0.7.5 shipped with Ubuntu 12.04 by default) that
does not support `best` for the backingstore option, changing it to `none` is
required and a default for all Vagrant environments can be set from your
2014-05-13 03:25:53 +00:00
`~/.vagrant.d/Vagrantfile` using the same `provider` block:
2014-05-13 03:25:53 +00:00
```ruby
Vagrant.configure("2") do |config|
config.vm.provider :lxc do |lxc|
lxc.backingstore = 'none'
end
end
```
### Avoiding `sudo` passwords
2013-07-28 16:35:40 +00:00
This plugin requires **a lot** of `sudo`ing since [user namespaces](https://wiki.ubuntu.com/UserNamespace)
are not supported on mainstream kernels. To work around that, you can use the
2014-05-04 02:11:37 +00:00
`vagrant lxc sudoers` command which will create a file under `/etc/sudoers.d/vagrant-lxc-<VERSION>`
whitelisting all commands required by `vagrant-lxc` to run.
If you are interested on what will be generated by that command, please check
[this code](lib/vagrant-lxc/command/sudoers.rb).
2014-03-21 23:17:52 +00:00
_vagrant-lxc < 1.0.0 users, please check this [Wiki page](https://github.com/fgrehm/vagrant-lxc/wiki/Avoiding-%27sudo%27-passwords)_
## More information
2013-03-03 03:38:48 +00:00
2013-09-21 03:51:44 +00:00
Please refer the [wiki](https://github.com/fgrehm/vagrant-lxc/wiki).
2013-03-04 01:23:26 +00:00
## Problems / ideas?
2013-03-04 04:06:08 +00:00
Please review the [Troubleshooting](https://github.com/fgrehm/vagrant-lxc/wiki/Troubleshooting)
wiki page + [known bugs](https://github.com/fgrehm/vagrant-lxc/issues?labels=bug&page=1&state=open)
list if you have a problem and feel free to use the [issue tracker](https://github.com/fgrehm/vagrant-lxc/issues)
2013-09-28 15:01:12 +00:00
propose new functionality and / or report bugs.
2013-03-05 04:04:39 +00:00
2013-02-25 23:09:32 +00:00
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request