dev-lxc 3.2.0 → 3.3.0

data/docs/base_containers.md

@@ -1,44 +1,44 @@
-### Base Containers
-
-The container that is used as the base container for a cluster's containers must exist before
-the cluster can be built. The cluster's containers are cloned from the base container using
-the btrfs filesystem to very quickly provide a lightweight duplicate of the container.
-
-This container provides the chosen OS platform and version (e.g. b-ubuntu-1404).
-
-A typical LXC container has minimal packages installed so `dev-lxc` makes sure that the
-same packages used in Chef's [bento boxes](https://github.com/opscode/bento) are
-installed to provide a more typical server environment.
-A few additional packages are also installed.
-
-Base containers have openssh-server installed and running with unique SSH Host Keys.
-
-Base containers have a "dev-lxc" user with "dev-lxc" password and passwordless sudo.
-
-*Once this base container is created there is rarely a need to delete it.*
-
-### Create a dev-lxc Base Container
-
-dev-lxc is able to create base containers that have openssh-server installed and running with unique SSH Host Keys.
-
-dev-lxc base containers have a "dev-lxc" user with "dev-lxc" password and passwordless sudo.
-
-You can see a menu of base containers that `dev-lxc` can create by using the following command.
-
-```
-dl create-base-container
-```
-
-The initial creation of base containers can take awhile so let's go ahead and start creating
-an Ubuntu 14.04 container now.
-
-```
-dl create-base-container b-ubuntu-1404
-```
-
-Note: It is possible to pass additional arguments to the underlying LXC create command.
-For example:
-
-```
-dl create-base-container b-ubuntu-1404 -o -- '--no-validate --keyserver http://my.key.server.com'
-```
+### Base Containers
+
+The container that is used as the base container for a cluster's containers must exist before
+the cluster can be built. The cluster's containers are cloned from the base container using
+the btrfs filesystem to very quickly provide a lightweight duplicate of the container.
+
+This container provides the chosen OS platform and version (e.g. b-ubuntu-1404).
+
+A typical LXC container has minimal packages installed so `dev-lxc` makes sure that the
+same packages used in Chef's [bento boxes](https://github.com/opscode/bento) are
+installed to provide a more typical server environment.
+A few additional packages are also installed.
+
+Base containers have openssh-server installed and running with unique SSH Host Keys.
+
+Base containers have a "dev-lxc" user with "dev-lxc" password and passwordless sudo.
+
+*Once this base container is created there is rarely a need to delete it.*
+
+### Create a dev-lxc Base Container
+
+dev-lxc is able to create base containers that have openssh-server installed and running with unique SSH Host Keys.
+
+dev-lxc base containers have a "dev-lxc" user with "dev-lxc" password and passwordless sudo.
+
+You can see a menu of base containers that `dev-lxc` can create by using the following command.
+
+```
+dl create-base-container
+```
+
+The initial creation of base containers can take awhile so let's go ahead and start creating
+an Ubuntu 14.04 container now.
+
+```
+dl create-base-container b-ubuntu-1404
+```
+
+Note: It is possible to pass additional arguments to the underlying LXC create command.
+For example:
+
+```
+dl create-base-container b-ubuntu-1404 -o -- '--no-validate --keyserver http://my.key.server.com'
+```

data/docs/byobu_keybindings.md

@@ -1,22 +1,22 @@
-## byobu keybindings
-
-byobu makes it easy to manage multiple terminal windows and panes. You can press `F1` to get help which includes a [list of keybindings](http://manpages.ubuntu.com/manpages/wily/en/man1/byobu.1.html#contenttoc8).
-
-`C-` refers to the keyboard's `Control` key.
-`M-` refers to the keyboard's `Meta` key which is the `Alt` key on a PC keyboard and the `Option` key on an Apple keyboard.
-
-The prefix key is set to `C-o`
-
-Some of the keyboard shortcuts that will be most useful to you are:
-
-* `M-Up`, `M-Down` - switch between byobu sessions
-* `M-Left`, `M-Right` - switch between windows in a session
-* `shift-Left`, `shift-Right`, `shift-Up`, `shift-Down` - switch between panes in a window
-  * Windows users using Conemu must first disable "Start selection with Shift+Arrow" in "Mark/Copy" under the "Keys & Macro" settings
-* `C-o C-s` - synchronize panes
-* `C-o z` - zoom into and out of a pane
-* `C-o M-1` - evenly split panes horizontally
-* `C-o M-2` - evenly split panes vertically
-* `M-pageup`, `M-pagedown` - page up/down in scrollback
-
-Note: `Shift-F2` does not create horizontal splits for Windows users. Use the `C-o |` key binding instead.
+## byobu keybindings
+
+byobu makes it easy to manage multiple terminal windows and panes. You can press `F1` to get help which includes a [list of keybindings](http://manpages.ubuntu.com/manpages/wily/en/man1/byobu.1.html#contenttoc8).
+
+`C-` refers to the keyboard's `Control` key.
+`M-` refers to the keyboard's `Meta` key which is the `Alt` key on a PC keyboard and the `Option` key on an Apple keyboard.
+
+The prefix key is set to `C-o`
+
+Some of the keyboard shortcuts that will be most useful to you are:
+
+* `M-Up`, `M-Down` - switch between byobu sessions
+* `M-Left`, `M-Right` - switch between windows in a session
+* `shift-Left`, `shift-Right`, `shift-Up`, `shift-Down` - switch between panes in a window
+  * Windows users using Conemu must first disable "Start selection with Shift+Arrow" in "Mark/Copy" under the "Keys & Macro" settings
+* `C-o C-s` - synchronize panes
+* `C-o z` - zoom into and out of a pane
+* `C-o M-1` - evenly split panes horizontally
+* `C-o M-2` - evenly split panes vertically
+* `M-pageup`, `M-pagedown` - page up/down in scrollback
+
+Note: `Shift-F2` does not create horizontal splits for Windows users. Use the `C-o |` key binding instead.

data/docs/configuration.md

@@ -1,235 +1,277 @@
-### dev-lxc.yml Config Files
-
-dev-lxc uses a YAML configuration file named `dev-lxc.yml` to define a cluster.
-
-The `init` command generates sample config files for various server types. You can run `dl help init` to see the many types of server configurations that can be generated.
-
-The `--base-container` option can be used to set the type of base container you want used in the generated configuration.
-
-The `--product-versions` option can be used to set the package channel and version to use for multiple products. If a version is not specified then it will default to `latest`. If `none` is used then that product will be removed from the generated configuration.
-
-For example, the following command will generate a configuration for a standalone Chef Server that uses the `b-centos-7` base container and install chef-server 12.13.0 from the `stable` channel, the latest version of manage from the `current` channel and remove the reporting product.
-
-```
-dl init --chef --base-container b-centos-7 --product-versions chef-server:stable:12.13.0 manage:current reporting:none
-```
-
-Let's generate a config for a cluster with a standalone Chef Server, Supermarket server,
-Compliance server, Chef Automate server and a Job Dispatch Runner and remove the "reporting" product from the generated configuration.
-
-```
-dl init --chef --compliance --supermarket --automate --runners --product-versions reporting:none > dev-lxc.yml
-```
-
-We can easily append additional configurations to this file. For example, the following command appends an infrastructure node.
-
-```
-dl init --nodes -a >> /root/work/clusters/automate/dev-lxc.yml
-```
-
-The contents of `dev-lxc.yml` should look like this.
-
-```
-# enable_build_snapshots automatically makes container snapshots at key times during the build process
-# default value is `true`
-#enable_build_snapshots: true
-
-# base_container must be the name of an existing container
-base_container: b-ubuntu-1404
-
-# memory_per_server sets the maximum amount of user memory (including file cache) for each server.
-# dev-lxc will set the `memory.limit_in_bytes` cgroup for each server to apply this limit.
-# If no units are specified, the value is interpreted as bytes.
-# You can use suffixes to represent larger units - k or K for kilobytes, m or M for megabytes, and g or G for gigabytes.
-# The default behavior is that no limit is set.
-#memory_per_server: 4G
-
-# list any host directories you want mounted into the servers
-#mounts:
-#  - /root/clusters root/clusters
-
-# list any SSH public keys you want added to /home/dev-lxc/.ssh/authorized_keys
-#ssh-keys:
-#  - /root/clusters/id_rsa.pub
-
-# DHCP reserved (static) IPs must be selected from the IP range 10.0.3.150 - 254
-
-chef-server:
-  users:          # a user's password will be the same as its username
-    - mary-admin
-    - joe-user
-  orgs:
-    demo:
-      admins:
-        - mary-admin
-      non-admins:
-        - joe-user
-  servers:
-    chef.lxc:
-      ipaddress: 10.0.3.203
-      products:
-        chef-server:
-          channel: stable
-          version: latest
-        manage:
-          channel: stable
-          version: latest
-        push-jobs-server:
-          channel: stable
-          version: latest
-
-compliance:
-  admin_user: admin         # the password will be the same as the username
-  servers:
-    compliance.lxc:
-      ipaddress: 10.0.3.205
-      products:
-        compliance:
-          channel: stable
-          version: latest
-
-supermarket:
-  servers:
-    supermarket.lxc:
-      ipaddress: 10.0.3.206
-      products:
-        supermarket:
-          channel: stable
-          version: latest
-
-automate:
-  servers:
-    automate.lxc:
-      ipaddress: 10.0.3.200
-      products:
-        automate:
-          channel: stable
-          version: latest
-      license_path: ../delivery.license
-      chef_org: delivery
-      enterprise_name: demo-ent
-
-runners:
-  servers:
-    runner-1.lxc:
-      products:
-        chefdk:     # downloaded only
-          channel: stable
-          version: latest
-
-nodes:
-  chef_server_url: https://chef.lxc/organizations/demo
-  validation_client_name: demo-validator
-  # comment out or remove the validation_key path to use chef-server keys generated by dev-lxc
-  validation_key: # /path/for/ORG-validator.pem
-  servers:
-    node-1.lxc:
-      products:
-        chef:
-          channel: stable
-          version: latest
-
-```
-
-The dev-lxc.yml config file is very customizable. You can add or remove mounts, products or servers,
-change ip addresses, server names, the base_container and more.
-
-As you can see there are six server types represented by six servers.
-
-1. chef-server - chef.lxc
-2. compliance - compliance.lxc
-3. supermarket - supermarket.lxc
-4. automate - automate.lxc
-5. runners - runner-1.lxc
-6. nodes - node-1.lxc
-
-#### Global Settings
-
-The global settings used by each of the server types are `enable_build_snapshots`, the `base_container`, `memory_per_server`, a list of `mounts` and a list of `ssh-keys`. These settings are described in the config comments.
-
-Be sure to set `base_container` in the `dev-lxc.yml` to an existing container's name.  
-This container will be cloned to create each container in the cluster.  
-If you don't already have a container to use as a `base_container` then you can follow the instructions in the  
-[Create a dev-lxc Base Container section](https://github.com/jeremiahsnapp/dev-lxc#create-a-dev-lxc-base-container) to create one.
-
-#### Server Specific Settings
-
-It is possible to define different values for `enable_build_snapshots`, `base_container`, `memory_per_server`, `mounts` or `ssh-keys` for a particular server type or even for a particular server as you can see in the following snippet.
-
-```
-nodes:
-  base_container: b-ubuntu-1404
-  servers:
-    node-1.lxc:
-      base_container: b-centos-6
-    node-2.lxc:
-```
-
-IP addresses from the range 10.0.3.150 - 254 can be assigned to the servers. If an IP address
-is not specified then a dynamic IP address is assigned when the server starts.
-
-#### mixlib-install Library Automatically Manages a Cache of Product Packages
-
-dev-lxc uses the [mixlib-install](https://github.com/chef/mixlib-install) library to download Chef products
-to a cache in `/var/dev-lxc` in the host instance. This cache is automatically mounted into each server when it starts.
-
-A list of Chef products to be installed can be defined for each server
-using [product names that mixlib-install understands](https://github.com/chef/mixlib-install/blob/master/PRODUCT_MATRIX.md).
-
-The channel and version of the product can be defined also.
-
-Channel can be `current`, `stable` or `unstable` with `stable` as the default.
-Version can be `latest` or a version number with `latest` as the default.
-
-For example, the following specifies the `current` channel and version `0.16.1` of the `chefdk` product.
-
-```
-nodes:
-  servers:
-    node-1.lxc:
-      products:
-        chefdk:
-          channel: current
-          version: 0.16.1
-```
-
-The `package_source` setting can be used to specify a package file on disk.
-
-```
-nodes:
-  servers:
-    node-1.lxc:
-      products:
-        chefdk:
-          package_source: /root/chefdk_0.16.1-1_amd64.deb
-```
-
-#### Chef Server Orgs/Users
-
-When defining a Chef Server you can include organizations and users that will be automatically created and associated accordingly.
-
-#### Automatic Integration Between Servers
-
-dev-lxc knows how to automatically configure Chef Server standalone, Chef Server tier topology,
-Chef Server HA 2.0 as well as Chef Automate, Chef Client, Analytics, Compliance and Supermarket.
-
-If a Chef Automate server, Compliance server, Analytics server or Supermarket server is defined in the same config file as
-a Chef Server then each server will automatically be integrated with that Chef Server.
-
-If a node server with Chef Client or Chef DK installed is defined in the same config file as
-a Chef Server then the Chef Client will automatically be configured to use that Chef Server.
-
-Alternatively, values for `chef_server_url`, `validation_client_name` and `validation_key` can
-be set in the config file either for all nodes or for each individual node.
-
-```
-nodes:
-  chef_server_url: https://chef.lxc/organizations/demo
-  validation_client_name: demo-validator
-  # comment out or remove the validation_key path to use chef-server keys generated by dev-lxc
-  validation_key: # /path/to/org/validation/key
-  servers:
-    node-1.lxc:
-      products:
-        chef:
-```
+### dev-lxc.yml Config Files
+
+dev-lxc uses a YAML configuration file named `dev-lxc.yml` to define a cluster.
+
+The `init` command generates sample config files for various server types. You can run `dl help init` to see the many types of server configurations that can be generated.
+
+The `--base-container` option can be used to set the type of base container you want used in the generated configuration.
+
+The `--product-versions` option can be used to set the package channel and version to use for multiple products. If a version is not specified then it will default to `latest`. If `none` is used then that product will be removed from the generated configuration.
+
+For example, the following command will generate a configuration for a standalone Chef Server that uses the `b-centos-7` base container and install chef-server 12.13.0 from the `stable` channel, the latest version of manage from the `current` channel and remove the reporting product.
+
+```
+dl init --chef --base-container b-centos-7 --product-versions chef-server:stable:12.13.0 manage:current reporting:none
+```
+
+Let's generate a config for a cluster with a standalone Chef Server, Supermarket server,
+Compliance server, Chef Automate server and a Job Dispatch Runner and remove the "reporting" product from the generated configuration.
+
+```
+dl init --chef --compliance --supermarket --automate --runners --product-versions reporting:none > dev-lxc.yml
+```
+
+We can easily append additional configurations to this file. For example, the following command appends an infrastructure node.
+
+```
+dl init --nodes -a >> /root/work/clusters/automate/dev-lxc.yml
+```
+
+The contents of `dev-lxc.yml` should look like this.
+
+```
+# enable_build_snapshots automatically makes container snapshots at key times during the build process
+# default value is `true`
+#enable_build_snapshots: true
+
+# base_container must be the name of an existing container
+base_container: b-ubuntu-1404
+
+# memory_per_server sets the maximum amount of user memory (including file cache) for each server.
+# dev-lxc will set the `memory.limit_in_bytes` cgroup for each server to apply this limit.
+# If no units are specified, the value is interpreted as bytes.
+# You can use suffixes to represent larger units - k or K for kilobytes, m or M for megabytes, and g or G for gigabytes.
+# The default behavior is that no limit is set.
+#memory_per_server: 4G
+
+# list any host directories you want mounted into the servers
+#mounts:
+#  - /root/clusters root/clusters
+
+# list any SSH public keys you want added to /home/dev-lxc/.ssh/authorized_keys
+#ssh-keys:
+#  - /root/clusters/id_rsa.pub
+
+# DHCP reserved (static) IPs must be selected from the IP range 10.0.3.150 - 254
+
+chef-server:
+  users:          # a user's password will be the same as its username
+    - mary-admin
+    - joe-user
+  orgs:
+    demo:
+      admins:
+        - mary-admin
+      non-admins:
+        - joe-user
+  servers:
+    chef.lxc:
+      ipaddress: 10.0.3.203
+      products:
+        chef-server:
+          channel: stable
+          version: latest
+        manage:
+          channel: stable
+          version: latest
+        push-jobs-server:
+          channel: stable
+          version: latest
+
+compliance:
+  admin_user: admin         # the password will be the same as the username
+  servers:
+    compliance.lxc:
+      ipaddress: 10.0.3.205
+      products:
+        compliance:
+          channel: stable
+          version: latest
+
+supermarket:
+  servers:
+    supermarket.lxc:
+      ipaddress: 10.0.3.206
+      products:
+        supermarket:
+          channel: stable
+          version: latest
+
+automate:
+  servers:
+    automate.lxc:
+      ipaddress: 10.0.3.200
+      products:
+        automate:
+          channel: stable
+          version: latest
+      license_path: ../delivery.license
+      chef_org: delivery
+      enterprise_name: demo-ent
+
+runners:
+  servers:
+    runner-1.lxc:
+      products:
+        chefdk:     # downloaded only
+          channel: stable
+          version: latest
+
+nodes:
+  chef_server_url: https://chef.lxc/organizations/demo
+  validation_client_name: demo-validator
+  # comment out or remove the validation_key path to use chef-server keys generated by dev-lxc
+  validation_key: # /path/for/ORG-validator.pem
+  servers:
+    node-1.lxc:
+      products:
+        chef:
+          channel: stable
+          version: latest
+
+```
+
+The dev-lxc.yml config file is very customizable. You can add or remove mounts, products or servers,
+change ip addresses, server names, the base_container and more.
+
+As you can see there are six server types represented by six servers.
+
+1. chef-server - chef.lxc
+2. compliance - compliance.lxc
+3. supermarket - supermarket.lxc
+4. automate - automate.lxc
+5. runners - runner-1.lxc
+6. nodes - node-1.lxc
+
+#### Global Settings
+
+The global settings used by each of the server types are `enable_build_snapshots`, the `base_container`, `memory_per_server`, a list of `mounts` and a list of `ssh-keys`. These settings are described in the config comments.
+
+Be sure to set `base_container` in the `dev-lxc.yml` to an existing container's name.  
+This container will be cloned to create each container in the cluster.  
+If you don't already have a container to use as a `base_container` then you can follow the instructions in the  
+[Create a dev-lxc Base Container section](https://github.com/jeremiahsnapp/dev-lxc#create-a-dev-lxc-base-container) to create one.
+
+#### Server Specific Settings
+
+It is possible to define different values for `enable_build_snapshots`, `base_container`, `memory_per_server`, `mounts` or `ssh-keys` for a particular server type or even for a particular server as you can see in the following snippet.
+
+```
+nodes:
+  base_container: b-ubuntu-1404
+  servers:
+    node-1.lxc:
+      base_container: b-centos-6
+    node-2.lxc:
+```
+
+IP addresses from the range 10.0.3.150 - 254 can be assigned to the servers. If an IP address
+is not specified then a dynamic IP address is assigned when the server starts.
+
+#### mixlib-install Library Automatically Manages a Cache of Product Packages
+
+dev-lxc uses the [mixlib-install](https://github.com/chef/mixlib-install) library to download Chef products
+to a cache in `/var/dev-lxc` in the host instance. This cache is automatically mounted into each server when it starts.
+
+A list of Chef products to be installed can be defined for each server
+using [product names that mixlib-install understands](https://github.com/chef/mixlib-install/blob/master/PRODUCT_MATRIX.md).
+
+The channel and version of the product can be defined also.
+
+Channel can be `current`, `stable` or `unstable` with `stable` as the default.
+Version can be `latest` or a version number with `latest` as the default.
+
+For example, the following specifies the `current` channel and version `0.16.1` of the `chefdk` product.
+
+```
+nodes:
+  servers:
+    node-1.lxc:
+      products:
+        chefdk:
+          channel: current
+          version: 0.16.1
+```
+
+The `package_source` setting can be used to specify a package file on disk.
+
+```
+nodes:
+  servers:
+    node-1.lxc:
+      products:
+        chefdk:
+          package_source: /root/chefdk_0.16.1-1_amd64.deb
+```
+
+#### Chef Server Orgs/Users
+
+When defining a Chef Server you can include organizations and users that will be automatically created and associated accordingly.
+
+#### Specify Chef Server Predefined Full and Partial Configurations
+
+The following options work for a standalone Chef Server, the backend and frontends of a tier Chef Server cluster and the frontends of a chef-backend HA Chef Server cluster.
+
+The `chef-server.rb` option can be used to fill a Chef server's chef-server.rb with predefined content from a file.
+
+The `chef-server.rb_partials` option can be used to append predefined content from multiple files to a Chef server's chef-server.rb file.
+
+```
+servers:
+  chef.lxc:
+    chef-server.rb: /path/to/a/full/configuration/file
+    chef-server.rb_partials:
+      - /path/to/a/partial/configuration/file
+      - /path/to/another/partial/configuration/file
+    ipaddress: 10.0.3.203
+    products:
+      chef-server:
+        channel: stable
+        version: latest
+```
+
+#### Specify Automate Server Predefined Full and Partial Configurations
+
+The `delivery.rb` option can be used to fill an Automate server's delivery.rb with predefined content from a file.
+
+The `delivery.rb_partials` option can be used to append predefined content from multiple files to an Automate server's delivery.rb file.
+
+```
+servers:
+  automate.lxc:
+    delivery.rb: /path/to/a/full/configuration/file
+    delivery.rb_partials:
+      - /path/to/a/partial/configuration/file
+      - /path/to/another/partial/configuration/file
+    ipaddress: 10.0.3.200
+    products:
+      automate:
+        channel: stable
+        version: latest
+```
+
+#### Automatic Integration Between Servers
+
+dev-lxc knows how to automatically configure Chef Server standalone, Chef Server tier topology,
+Chef Server HA 2.0 as well as Chef Automate, Chef Client, Analytics, Compliance and Supermarket.
+
+If a Chef Automate server, Compliance server, Analytics server or Supermarket server is defined in the same config file as
+a Chef Server then each server will automatically be integrated with that Chef Server.
+
+If a node server with Chef Client or Chef DK installed is defined in the same config file as
+a Chef Server then the Chef Client will automatically be configured to use that Chef Server.
+
+Alternatively, values for `chef_server_url`, `validation_client_name` and `validation_key` can
+be set in the config file either for all nodes or for each individual node.
+
+```
+nodes:
+  chef_server_url: https://chef.lxc/organizations/demo
+  validation_client_name: demo-validator
+  # comment out or remove the validation_key path to use chef-server keys generated by dev-lxc
+  validation_key: # /path/to/org/validation/key
+  servers:
+    node-1.lxc:
+      products:
+        chef:
+```