Install Chef Compliance Server¶
Warning
The standalone Chef Compliance server is deprecated. The standalone Chef Compliance server’s end-of-life date is December 31, 2018. Chef Automate 2 has all of the functionality of Chef Compliance Server and also includes newer out-of-the-box compliance profiles, an improved compliance scanner with total cloud scanning functionality, better visualizations, role-based access control and many other features not found in Chef Compliance Server.
To install the Chef Compliance server in a standalone on-premises configuration, first review the prerequisites and then follow the steps below. Chef Compliance may also be installed as an Amazon Machine Images (AMI) from the AWS Marketplace.
Note
This feature is included as part of the Chef Automate license agreement and is available via subscription.
Prerequisites¶
The Chef Compliance server has the following prerequisites:
- An x86_64 compatible system architecture; Red Hat Enterprise Linux and CentOS may require updates prior to installation
- A resolvable hostname that is specified using a FQDN or an IP address
- A connection to Network Time Protocol (NTP) to prevent clock drift
- Optional. A local user account under which services will run, a local user account for PostgreSQL, and a group account under which services will run. See /install_server_pre.html#uids-and-gids for more information
The following prerequisites apply to every installation of the Chef Compliance server.
Platforms¶
The following table lists the Foundational platforms for the Chef Compliance server:
Platform | Architecture | Version |
---|---|---|
CentOS | 6.x , 7.x |
|
Red Hat Enterprise Linux | 6.x , 7.x |
|
Ubuntu | 12.04 LTS , 14.04 LTS , 16.04 LTS |
Untested Platforms¶
Although you can audit many kinds of servers, the Chef Compliance server itself is not tested by Chef Software on the following platforms:
- Any Linux or UNIX distribution that is not listed as a supported platform
- Microsoft Windows
- 32-bit architectures
Standalone¶
The standalone installation of Chef Compliance server creates a working installation on a single server. This installation is also useful when you are installing Chef Compliance in a virtual machine, for proof-of-concept deployments, or as a part of a development or testing loop.
To install the Chef Compliance server:
Download the package from https://downloads.chef.io/compliance/.
Upload the package to the machine that will run the Chef Compliance server, and then record its location on the file system. The rest of these steps assume this location is in the
/tmp
directoryInstall the Chef Compliance package on the server, using the name of the package provided by Chef. These commands require
root
privileges.For Red Hat and CentOS 6:
$ rpm -Uvh /tmp/chef-compliance-<version>.rpm
For Ubuntu:
$ dpkg -i /tmp/chef-compliance-<version>.deb
After a few minutes, the Chef Compliance will be installed.
Run the following to start all of the services:
$ chef-compliance-ctl reconfigure
Note
Starting with Chef Compliance 1.1.9, the Chef MLSA must be accepted when reconfiguring the product. If the Chef MLSA has not already been accepted, the reconfigure process will prompt for a
yes
to accept it. Or runchef-compliance-ctl reconfigure --accept-license
to automatically accept the license.Access the Chef Compliance setup wizard. Build the URL by prepending
https://
and appending/#/setup
to the IP address or public hostname that was automatically assigned when the Amazon Machine Images (AMI) was launched. For example,https://<fqdn>/#/setup
.Run through the setup wizard, and then log in to the Chef Compliance web interface at
https://<fqdn>
using a current Chrome or Firefox browser. Internet Explorer is currently not supported.
AWS Marketplace¶
See the AWS Marketplace documentation for instructions on deploying the Compliance server Amazon Machine Image (AMI).
Configure SSL¶
The Chef Compliance server can be configured to use SSL certificates by adding the following settings in the server configuration file located at /etc/chef-compliance/chef-compliance.rb
:
Setting | Description |
---|---|
ssl['certificate'] |
The SSL certificate used to verify communication over HTTPS. |
ssl['certificate_key'] |
The certificate key used for SSL communication. |
and then setting their values to define the paths to the certificate and key.
For example:
ssl['certificate'] = "/etc/pki/tls/certs/your-host.crt"
ssl['certificate_key'] = "/etc/pki/tls/private/your-host.key"
Save the file, and then run the following command:
$ sudo chef-compliance-ctl reconfigure
Configuring WinRM¶
Chef Compliance also allows you to configure SSH and WinRM through the user interface. In the case of WinRM, you will need to perform additional steps from the command line to enable and verify the WinRM configuration of a node.
From CMD, start the WinRM service and load the default WinRM configuration.
c:\ winrm quickconfig
Verify whether a listener is running, and which ports are used. The default ports are 5985 for HTTP, and 5986 for HTTPS.
c:\ winrm enumerate winrm/config/listener
Enable basic authentication on the WinRM service. Run the following command to check whether basic authentication is allowed.
c:\ winrm get winrm/config/service
Run the following command to enable basic authentication on the WinRM service.
c:\ winrm set winrm/config/service/auth @{Basic="true"}
Note
PowerShell requires a slightly modified syntax:
PS:\ winrm set winrm/config/service/auth '@{Basic="true"}'
Run the following command to allow transfer of unencrypted data on the WinRM service.
c:\ winrm set winrm/config/service @{AllowUnencrypted="true"}
Enable Unencrypted client connections for the test winrm identity command to work.
c:\ winrm set winrm/config/client @{AllowUnencrypted="true"}
Run the following command to test the connection to the WinRM service.
c:\ winrm identify -r:http://NODE:5985 -auth:basic -u:USERNAME -p:PASSWORD -encoding:utf-8
Logging¶
The default directory where Chef Compliance is saving logs is: /var/log/chef-compliance/
. It contains a directory for each service, but you can follow all the logs with this command:
sudo chef-compliance-ctl tail
This command can also be run for an individual service by specifying the name of the service in the command. For example:
sudo chef-compliance-ctl tail core
Troubleshooting¶
The following section describes troubleshooting tips for Chef Compliance installations.
Setup Button Does Not Work¶
Reason
For security purposes the Chef Compliance setup wizard has a one hour timeout.
Resolution
Login using SSH to access the Chef Compliance instance.
$ ssh -i /path/to/ssh_key.pem <user>@<instance IP address>
Reconfigure Chef Compliance to restart the 60 minute setup timer.
$ chef-compliance-ctl reconfigure