Install Chef Compliance Server

[edit on GitHub]

_images/chef_automate_full.png

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:

  1. Download the package from https://downloads.chef.io/compliance/.

  2. 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 directory

  3. Install 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.

  4. 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 run chef-compliance-ctl reconfigure --accept-license to automatically accept the license.

  5. 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.

  6. 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.

  1. From CMD, start the WinRM service and load the default WinRM configuration.

    c:\ winrm quickconfig
    
  2. 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
    
  3. Enable basic authentication on the WinRM service. Run the following command to check whether basic authentication is allowed.

    c:\ winrm get winrm/config/service
    
  4. 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"}'

  5. Run the following command to allow transfer of unencrypted data on the WinRM service.

    c:\ winrm set winrm/config/service @{AllowUnencrypted="true"}
    
  6. Enable Unencrypted client connections for the test winrm identity command to work.

    c:\ winrm set winrm/config/client @{AllowUnencrypted="true"}
    
  7. 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

  1. Login using SSH to access the Chef Compliance instance.

    $ ssh -i /path/to/ssh_key.pem <user>@<instance IP address>
    
  2. Reconfigure Chef Compliance to restart the 60 minute setup timer.

    $ chef-compliance-ctl reconfigure