README autumn cleaning

README.md

@@ -1,26 +1,31 @@
 # vagrant-lxc [![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)
 
-Linux Containers support for Vagrant 1.1+
+[LXC](http://lxc.sourceforge.net/) provider for [Vagrant](http://www.vagrantup.com/) 1.1+
 
 Check out this [blog post](http://fabiorehm.com/blog/2013/04/28/lxc-provider-for-vagrant)
 to see the plugin in action and find out more about it.
 
-## Dependencies
+## Features
 
-* Vagrant 1.1+ (1.1.3+ recommended)
+* Vagrant's `up`, `halt`, `reload`, `destroy`, `ssh`, `provision` and `package` commands (box packaging is kind of experimental)
-* lxc 0.7.5+ (0.8.0-rc1+ recommended)
+* Shared folders
+* Provisioning with any built-in Vagrant provisioner
+* Setting container's host name
+* Port forwarding
+
+*Please refer to the [closed issues](https://github.com/fgrehm/vagrant-lxc/issues?labels=&milestone=&page=1&state=closed)
+and the [changelog](CHANGELOG.md) for most up to date information.*
+
+
+## Requirements
+
+* [Vagrant 1.1+](http://downloads.vagrantup.com/)
+* lxc 0.7.5+
 * redir (if you are planning to use port forwarding)
-* A Kernel [higher than 3.5.0-17.28](#help-im-unable-to-restart-containers)
+* A [bug-free](#help-im-unable-to-restart-containers) kernel
 
-On a clean Ubuntu 12.10 machine it means something like:
+On a clean Ubuntu 12.10 machine it basically means a `apt-get update && apt-get dist-upgrade`
-
+to upgrade the kernel and `apt-get install lxc redir`.
-```
-sudo apt-get update && sudo apt-get dist-upgrade
-sudo apt-get install lxc redir
-# Downloads and install Vagrant 1.1.5
-wget "http://files.vagrantup.com/packages/64e360814c3ad960d810456add977fd4c7d47ce6/vagrant_`uname -m`.deb" -O /tmp/vagrant.deb
-sudo dpkg -i /tmp/vagrant.deb
-```
 
 
 ## Installation
@@ -38,28 +43,47 @@ After installing, add a [base box](#available-boxes) using any name you want, fo
 vagrant box add quantal64 http://dl.dropbox.com/u/13510779/lxc-quantal-amd64-2013-05-08.box
 ```
 
-Make a Vagrantfile that looks like the following, filling in your information where necessary:
+Then create a Vagrantfile that looks like the following, changing the box name
+to the one you've just added:
 
 ```ruby
 Vagrant.configure("2") do |config|
-  # Change it to the name of the box you have just added
+  config.vm.box = "quantal64"
-  config.vm.box = "lxc-quantal64"
+end
+```
 
-  # You can omit this block if you don't need to override any container setting
+And finally run `vagrant up --provider=lxc`.
+
+If you are using Vagrant 1.2+ you can also set `VAGRANT_DEFAULT_PROVIDER`
+environmental variable to `lxc` in order to avoid typing `--provider=lxc` all
+the time.
+
+If you are on a mac or windows host and still want to try this plugin out, you
+can use the [Ubuntu 12.10 VirtualBox machine I use for development](#using-virtualbox-for-development).
+
+
+### Advanced configuration
+
+If you want, you can modify container configurations from within your Vagrantfile
+using the [provider block](http://docs.vagrantup.com/v2/providers/configuration.html):
+
+```ruby
+Vagrant.configure("2") do |config|
+  config.vm.box = "quantal64"
   config.vm.provider :lxc do |lxc|
-    # OPTIONAL: Same effect as as 'customize ["modifyvm", :id, "--memory", "1024"]' for VirtualBox
+    # Same effect as as 'customize ["modifyvm", :id, "--memory", "1024"]' for VirtualBox
     lxc.customize 'cgroup.memory.limit_in_bytes', '1024M'
-    # OPTIONAL: Limits swap size
-    lxc.customize 'cgroup.memory.memsw.limit_in_bytes', '512M'
   end
 end
 ```
 
-And finally run `vagrant up --provider=lxc`. If you are using Vagrant 1.2+ you can
+This will make vagrant-lxc pass in `-s lxc.cgroup.memory.limit_in_bytes=1024M`
-also set `VAGRANT_DEFAULT_PROVIDER` environmental variable to `lxc`.
+to `lxc-start` when booting containers. This will override any previously value
+set from container's configuration file that is usually kept under
+`/var/lib/lxc/<container-name>/config`.
+
+For other configuration options, please check [lxc.conf manpages](http://manpages.ubuntu.com/manpages/quantal/man5/lxc.conf.5.html).
 
-If you are on a mac or window host and still want to try this plugin out, you
-can use the [same Vagrant VirtualBox machine I use for development](#using-virtualbox-for-development).
 
 ### Available boxes
 
@@ -77,7 +101,7 @@ and I've only done some basic testing with the others*
 
 There is a set of [rake tasks](tasks/boxes.rake) that you can use to build base
 boxes as needed. By default it won't include any provisioning tool and you can
-pick the one you want by providing some environment variables.
+pick the ones you want by providing some environment variables.
 
 For example:
 
@@ -85,39 +109,29 @@ For example:
 CHEF=1 rake boxes:ubuntu:build:precise64
 ```
 
-Will build a Ubuntu Precise x86_64 box with chef pre-installed.
+Will build a Ubuntu Precise x86_64 box with Chef pre-installed.
+
 
 ### Storing container's rootfs on a separate partition
 
 Before the 0.3.0 version of this plugin, there used to be a support for specifying
-the container's rootfs path from the `Vagrantfile`, on 0.3.0 this was removed as you
+the container's rootfs path from the Vagrantfile, on 0.3.0 this was removed as you
 can achieve the same effect by symlinking or mounting `/var/lib/lxc` on a separate
 partition.
 
-### NFS shared folders
 
-NFS shared folders are not supported and will behave as a "normal" shared folder
+### NFS synced folders
-so we can share the same Vagrantfile with VBox environments.
 
-
+NFS shared folders are not supported and will behave as a "normal" synced folder
-## What is currently supported?
+so we can use the same Vagrantfile with VBox environments.
-
-Pretty much everything you need from Vagrant:
-
-* Vagrant's `up`, `halt`, `reload`, `destroy`, `ssh` and `package` commands (box packaging is kind of experimental)
-* Shared folders
-* Provisioning
-* Setting container's host name
-* Port forwarding
-
-*Please refer to the [closed issues](https://github.com/fgrehm/vagrant-lxc/issues?labels=&milestone=&page=1&state=closed)
-and the [changelog](CHANGELOG.md) for most up to date information.*
 
 
 ## Current limitations
 
-* Does not detect forwarded ports collision, right now you are responsible for taking care of that
+* The plugin does not detect forwarded ports collision, right now you are
-* A hell lot of `sudo`s (this will probably be like this until [user namespaces](http://s3hh.wordpress.com/2013/02/12/user-namespaces-lxc-meeting/) are supported)
+  responsible for taking care of that.
+* There is a hell lot of `sudo`s involved and this will probably be around until
+  [user namespaces](https://wiki.ubuntu.com/LxcSecurity) are supported.
 * [Does not tell you if dependencies are not met](https://github.com/fgrehm/vagrant-lxc/issues/11)
   (will probably just throw up some random error)
 * + bunch of other [core features](https://github.com/fgrehm/vagrant-lxc/issues?labels=core&milestone=&page=1&state=open)
@@ -126,7 +140,7 @@ and the [changelog](CHANGELOG.md) for most up to date information.*
 
 ## Development
 
-If  want to develop from your physical machine, just sing that same old song:
+If want to develop from your physical machine, just sing that same old song:
 
 ```
 git clone git://github.com/fgrehm/vagrant-lxc.git
@@ -141,16 +155,9 @@ To run acceptance specs, you'll have to ssh into one of the [development boxes](
 bundle exec rake spec:acceptance
 ```
 
-To build the provided quantal64 box:
+### Using vagrant-lxc to develop itself
 
-```
+Yes! The gem has been [bootstrapped](http://bit.ly/bootstrapping-compilers)
-bundle exec rake boxes:quantal64:build
-vagrant box add quantal64 boxes/output/lxc-quantal64.box
-```
-
-### Using `vagrant-lxc` to develop itself
-
-Yes! The gem has been [bootstrapped](http://en.wikipedia.org/wiki/Bootstrapping_(compilers)
 and since you can boot a container from within another, after cloning the
 project you can run the commands below from the host machine to get a container
 ready for development:
@@ -165,15 +172,16 @@ bundle exec vagrant up quantal --provider=lxc
 bundle exec vagrant ssh quantal
 ```
 
-That should result in a container ready to be `bundle exec vagrant ssh`ed.
+That should result in a container ready to rock. Once you've SSH into the guest
-Once you've SSH into the guest container, you'll be already on the project's root.
+container, you'll be already on the project's root. Keep in mind that you'll
-Keep in mind that you'll probably need to run `sudo aa-complain /usr/bin/lxc-start`
+probably need to run `sudo aa-complain /usr/bin/lxc-start` on the host whenever
-on the host whenever you want to hack on it, otherwise you won't be able to
+you want to hack on it, otherwise you won't be able to start nested containers
-start nested containers there to try things out.
+there to try things out.
 
 ### Using VirtualBox for development
 
 ```
+bundle install
 cd development
 # Pass in --provider=virtualbox in case you have VAGRANT_DEFAULT_PROVIDER set to something else
 bundle exec vagrant up quantal
@@ -183,7 +191,7 @@ bundle exec vagrant ssh quantal
 ```
 
 
-## Protips
+### Protips
 
 If you want to find out more about what's going on under the hood on vagrant,
 prepend `VAGRANT_LOG=debug` to your `vagrant` commands. For `lxc-start`s
@@ -209,8 +217,8 @@ to a bug on linux kernel, so make sure you are using a bug-free kernel
 
 Sometimes the dev boxes I'm using are not able to `lxc-start` containers
 anymore. Most of the times it was an issue with the arguments I provided
-to it for customization (or a *buggy* kernel). If you run into that, rollback your changes
+to it for customization or the *buggy kernel*. If you run into that, rollback your
-and try to `vagrant reload` the dev box. If it still doesn't work,
+changes and try to `vagrant reload` the dev box. If it still doesn't work,
 please file a bug at the [issue tracker](https://github.com/fgrehm/vagrant-lxc/issues).
 
 
@@ -219,6 +227,7 @@ please file a bug at the [issue tracker](https://github.com/fgrehm/vagrant-lxc/i
 * [vagabond](https://github.com/chrisroberts/vagabond) - "a tool integrated with Chef to build local nodes easily"
 * [vagueant](https://github.com/neerolyte/vagueant) - "vaguely like Vagrant for linux containers (lxc)"
 
+
 ## Contributing
 
 1. Fork it