175 lines
7.2 KiB
Markdown
175 lines
7.2 KiB
Markdown
---
|
|
layout: "docs"
|
|
page_title: "CFEngine Provisioner"
|
|
sidebar_current: "provisioning-cfengine"
|
|
description: |-
|
|
The Vagrant CFEngine provisioner allows you to provision the guest using
|
|
CFEngine. 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.
|
|
---
|
|
|
|
# CFEngine Provisioner
|
|
|
|
**Provisioner name: `cfengine`**
|
|
|
|
The Vagrant CFEngine provisioner allows you to provision the guest using
|
|
[CFEngine](https://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`](/docs/multi-machine/).
|
|
|
|
<div class="alert alert-warning">
|
|
<strong>Warning:</strong> If you are not familiar with CFEngine and Vagrant already,
|
|
it is recommended to start with the <a href="/docs/provisioning/shell.html">shell
|
|
provisioner</a>. However, if you are comfortable with Vagrant
|
|
already, Vagrant is the best way to learn CFEngine.
|
|
</div>
|
|
|
|
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](https://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`](https://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 (automatically 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 https://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 is 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
|
|
`"https://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 `"https://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.
|