diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb index 7a4b4d0a2..a44a1afc5 100644 --- a/website/docs/source/layouts/layout.erb +++ b/website/docs/source/layouts/layout.erb @@ -167,6 +167,7 @@ >File >Shell >Ansible + >CFEngine >Chef Solo >Chef Client >Docker diff --git a/website/docs/source/v2/provisioning/cfengine.html.md b/website/docs/source/v2/provisioning/cfengine.html.md new file mode 100644 index 000000000..9b2b8233a --- /dev/null +++ b/website/docs/source/v2/provisioning/cfengine.html.md @@ -0,0 +1,170 @@ +--- +page_title: "CFEngine Provisioner" +sidebar_current: "provisioning-cfengine" +--- + +# CFEngine Provisioner + +**Provisioner name: `cfengine`** + +The CFEngine provisioner allows you to provision the guest using +[CFEngine](http://www.cfengine.com/). It can set up both CFEngine +policy servers and clients. You can configure both the policy server +and the clients in a single +[multi-machine `Vagrantfile`](/v2/multi-machine/). + +
+

+ Warning: If you're not familiar with CFEngine and Vagrant already, + I recommend starting with the shell + provisioner. However, if you're comfortable with Vagrant + already, Vagrant is the best way to learn CFEngine. +

+
+ +Let us look at some common examples first. See the bottom of this +document for a comprehensive list of options. + +## Setting up a CFEngine server and client + +The CFEngine provisioner automatically installs the latest +[CFEngine Community packages](http://cfengine.com/cfengine-linux-distros) +on the VM, then configures and starts CFEngine according to your +specification. + +Configuring a VM as a CFEngine policy server is easy: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.am_policy_hub = true + end +end +``` + +The host will automatically be +[bootstrapped](https://cfengine.com/docs/3.5/manuals-architecture-networking.html#bootstrapping) +to itself to become a policy server. + +If you already have a working CFEngine policy server, you can get a +CFEngine client installed and bootstrapped by specifying its IP +address: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.policy_server_address = "10.0.2.15" + end +end +``` + +## Copying files to the VM + +If you have some policy or other files that you want to install by +default on a VM, you can use the `files_path` attribute: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.am_policy_hub = true + cf.files_path = "cfengine_files" + end + end +``` + +Everything under `cfengine_files/` in the Vagrant project directory +will be recursively copied under `/var/cfengine/` in the VM, on top of +its default contents. + +A common use case is to add your own files to +`/var/cfengine/masterfiles/` in the policy server. Assuming your extra +files are stored under `cfengine_files/masterfiles/`, the line shown +above will add them to the VM after CFEngine is installed, but before +it is bootstrapped. + +## Modes of operation + +The default mode of operation is `:bootstrap`, which results in +CFEngine being bootstrapped according to the information provided in +the `Vagrantfile`. You can also set `mode` to `:single_run`, which +will run `cf-agent` once on the host to execute the file specified in +the `run_file` parameter, but will not bootstrap it, so it will not be +executed periodically. + +The recommended mode of operation is `:bootstrap`, as you get the full +benefits of CFEngine when you have it running periodically. + +## Running a standalone file + +If you want to run a standalone file, you can specify the `run_file` +parameter. The file will be copied to the VM and executed on its own +using `cf-agent`. Note that the file needs to be a standalone policy, +including its own +[`body common control`](http://cfengine.com/docs/3.5/reference-components.html#common-control). + +The `run_file` parameter is mandatory if `mode` is set to +`:single_run`, but can also be specified when `mode` is set to +`:bootstrap` - in this case the file will be executed after the host +has been bootstrapped. + +## Full Alphabetical List of Configuration Options + +- `am_policy_hub` (boolean, default `false`) determines whether the VM will be + configured as a CFEngine policy hub (automaticaly bootstrapped to + its own IP address). You can combine it with `policy_server_address` + if the VM has multiple network interfaces and you want to bootstrap + to a specific one. +- `extra_agent_args` (string, default `nil`) can be used to pass + additional arguments to `cf-agent` when it is executed. For example, + you could use it to pass the `-I` or `-v` options to enable + additional output from the agent. +- `classes` (array, default `nil`) can be used to define additional + classes during `cf-agent` runs. These classes will be defined using + the `-D` option to `cf-agent`. +- `deb_repo_file` (string, default + `"/etc/apt/sources.list.d/cfengine-community.list"`) specifies the + file in which the CFEngine repository information will be stored in + Debian systems. +- `deb_repo_line` (string, default `"deb http://cfengine.com/pub/apt + $(lsb_release -cs) main"`) specifies the repository to use for + `.deb` packages. +- `files_path` (string, default `nil`) specifies a directory that will + be copied to the VM on top of the default + `/var/cfengine/` (the contents of `/var/cfengine/` will not + be replaced, the files will added to it). +- `force_bootstrap` (boolean, default `false`) specifies whether + CFEngine will be bootstrapped again even if the host has already + been bootstrapped. +- `install` (boolean or `:force`, default `true`) specifies whether + CFEngine will be installed on the VM if needed. If you set this + parameter to `:force`, then CFEngine will be reinstalled even if + it's already present on the machine. +- `mode` (`:bootstrap` or `:single_run`, default `:bootstrap`) + specifies whether CFEngine will be bootstrapped so that it executes + periodically, or will be run a single time. If `mode` is set to + `:single_run` you have to set `run_file`. +- `policy_server_address` (string, no default) specifies the IP + address of the policy server to which CFEngine will be + bootstrapped. If `am_policy_hub` is set to `true`, this parameter + defaults to the VM's IP address, but can still be set (for + example, if the VM has more than one network interface). +- `repo_gpg_key_url` (string, default + `"http://cfengine.com/pub/gpg.key"`) contains the URL to obtain the + GPG key used to verify the packages obtained from the repository. +- `run_file` (string, default `nil`) can be used to specify a file + inside the Vagrant project directory that will be copied to the VM + and executed once using `cf-agent`. This parameter is mandatory if + `mode` is set to `:single_run`, but can also be specified when + `mode` is set to `:bootstrap` - in this case the file will be + executed after the host has been bootstrapped. +- `upload_path` (string, default `"/tmp/vagrant-cfengine-file"`) + specifies the file to which `run_file` (if specified) will be copied + on the VM before being executed. +- `yum_repo_file` (string, default + `"/etc/yum.repos.d/cfengine-community.repo"`) specifies the file in + which the CFEngine repository information will be stored in RedHat + systems. +- `yum_repo_url` (string, default `"http://cfengine.com/pub/yum/"`) + specifies the URL of the repository to use for `.rpm` packages. +- `package_name` (string, default `"cfengine-community"`) specifies + the name of the package used to install CFEngine.