The following prerequisites apply to every installation of the Chef server.
The following table lists the Foundational platforms for the Chef server:
Platform | Architecture | Version |
---|---|---|
CentOS |
5.x , 6.x , 7.x
| |
Oracle Linux |
5.x , 6.x
| |
Red Hat Enterprise Linux |
5.x , 6.x , 7.x
| |
Ubuntu |
12.04 LTS , 14.04 LTS , 16.04 LTS
|
The following platforms are not tested by Chef Software:
Read the guidance around capacity planning for information about how to choose the right toplogy for the Chef server.
Before installing the Chef server, ensure that each machine has the following installed and configured properly:
In addition:
The installation process for the Chef server requires the use of at least two user and group identifiers (UIDs and GIDs). These are used to create the opscode
and opscode-pgsql
users and their default groups.
Note
The creation of required user and group identifiers is done automatically during the installation process for the Chef server; however, the following user and group accounts may be created in advance of installing the Chef server if specific UIDs and GIDs are preferred. The user and group must be created as a pair to satisfy reconfiguration requirements.
opscode
under which services will runopscode-pgsql
that is used by PostgreSQLopscode
and the other named opscode-pgsql
under which services will runWarning
If the UID and GID of opscode
and opscode-pgsql
do not match on both backend Chef server machines, a high availability configuration will not run correctly.
The embedded Chef server cookbooks can handle two cases:
opscode
and opscode-pgsql
user and group not found on the new serveropscode
and opscode-pgsql
user and group found on the new serverHaving only the group and not the corresponding users present during a chef-server-ctl reconfigure is unsupported and may lead to an error in the reconfiguration run.
To determine the current range of IDs, run the following command:
$ grep -E '(UID|GID)' /etc/login.defs
The defaults for CentOS and Red Hat Enterprise Linux systems look like this:
UID_MIN 500 UID_MAX 60000 GID_MIN 500 GID_MAX 60000
If the defaults have been changed for any reason, and if that change would result in less than 2 UID/GIDs being available to the useradd
program, edit /etc/login.defs
with changes to make at least 2 more UIDs and GIDs available for association. The currently used ID ranges for UIDs and GIDs can be found in /etc/passwd
and /etc/group
, respectively.
If the opscode
and opscode-pgsql
user and group identifiers exist prior to installing the Chef server, the Chef server installation process will use the existing identifiers instead of creating them.
On CentOS and Red Hat Enterprise Linux systems, SELinux is enabled in enforcing mode by default. The Chef server does not have a profile available to run under SELinux. In order for the Chef server to run, SELinux must be disabled or set to Permissive
mode.
To determine if SELinux is installed, run the following command:
$ getenforce
If a response other than "Disabled"
or "Permissive"
is returned, SELinux must be disabled.
To set SELinux to Permissive
mode, run:
$ setenforce Permissive
and then check the status:
$ getenforce
On Ubuntu systems, AppArmor is enabled in enforcing mode by default. Chef products do not have a profile available to run under AppArmor. In order for the Chef products to run, AppArmor must set to Complaining
mode or disabled.
To determine if AppArmor is installed, run the following command:
$ sudo apparmor_status
To install AppArmor, run the following command:
$ sudo apt-get install apparmor-utils —yes
If a response other than "0 processes are in enforce mode"
or "0 profiles are in enforce mode."
is returned, AppArmor must be set to Complaining
mode or disabled.
To set AppArmor to Complaining
mode, run:
$ sudo aa-complain /etc/apparmor.d/*
Or to disable AppArmor entirely, run:
$ sudo invoke-rc.d apparmor kill $ sudo update-rc.d -f apparmor remove
and then check the status:
$ sudo apparmor_status
On CentOS and Red Hat Enterprise Linux systems, the Apache Qpid daemon is installed by default. The Chef server uses RabbitMQ for messaging. Because both Apache Qpid and RabbitMQ share the same protocol, Apache Qpid must be disabled.
To determine if Apache Qpid is installed, run the following command:
$ rpm -qa | grep qpid
If Apache Qpid is installed, a response similar to the following is displayed:
$ qpid-cpp-server-0.12-6.el6.x86_64
To disable Apache Qpid run:
$ service qpidd stop
and then:
$ chkconfig --del qpidd
Periodic maintenance tasks are performed on the Chef server servers via cron and the /etc/cron.d
directory. With certain CentOS 6 configurations, an additional step is required to install crontab:
$ yum install crontabs
The Chef server requires an x86_64 compatible systems architecture. When the Chef server is installed on Red Hat Enterprise Linux or CentOS, run yum update
prior to installing the Chef server. This will ensure those platforms are fully compatible with this requirement.
The hostname for the Chef server may be specified using a FQDN or an IP address. This hostname must be resolvable. For example, a Chef server running in a production environment with a resolvable FQDN hostname can be added the DNS system. But when deploying Chef server into a testing environment, adding the hostname to the /etc/hosts
file is enough to ensure that hostname is resolvable.
FQDN Hostnames When the hostname for the Chef server is a FQDN be sure to include the domain suffix. For example, something like mychefserver.example.com
(and not something like mychefserver
).
IP Address Hostnames When the Chef server is run in IPv6 mode, a hostname specified using an IP address must also be bracketed ([ ]
) or the Chef server will not be able to recognize it as an IPv6 address. For example:
bookshelf['url'] "https://[2001:db8:85a3:8d3:1319:8a2e:370:7348]"
The api_fqdn
setting can be added to the private-chef.rb file (it is not there by default). When added, its value should be equal to the FQDN or IP address for the service URI used by the Chef server. Then configure the same value for the bookshelf['vip']
setting prior to installing the Chef server. For example: api_fqdn "chef.example.com"
or api_fqdn 123.45.67.890
.
Use the following sections to verify the hostnames that is used by the Chef server.
To verify if a hostname is a FQDN
To verify if a hostname is a FQDN, run the following command:
$ hostname
If the hostname is a FQDN, it will return something like:
$ mychefserver.example.com
If the hostname is not a FQDN, it must be configured so that it is one.
To verify the FQDN is all lowercase
To verify if the alphabetic parts of a FQDN are all lowercase, run the following command:
$ hostname -f | grep -E '^([[:digit:]]|[[:lower:]]|\.|-|_)+$' && echo yes
If the hostname is all lowercase, it will return something like:
mychefserver.example.com yes
If the hostname’s alphabetic parts are not all lowercase, it must be configured so that they are.
To verify a hostname is resolvable
To verify is a hostname is resolvable, run the following command:
$ hostname -f
If the hostname is resolvable, it will return something like:
$ mychefserver.example.com
To change a hostname
In some cases, the hostname for the Chef server needs to be updated. The process for updating a hostname varies, depending on the platform on which the Chef server will run. Refer to the manual for the platform or contact a local systems administrator for specific guidance for a specific platform. The following example shows how a hostname can be changed when running Red Hat or CentOS:
$ sudo hostname 'mychefserver.example.com'
and then:
$ echo "mychefserver.example.com" | sudo tee /etc/hostname
To add a hostname to /etc/hosts
If a hostname is not resolvable, refer to a local systems administrator for specific guidance on how to add the hostname to the DNS system. If the Chef server is being into a testing environment, just add the hostname to /etc/hosts
. The following example shows how a hostname can be added to /etc/hosts
when running Red Hat or CentOS:
$ echo -e "127.0.0.2 `hostname` `hostname -s`" | sudo tee -a /etc/hosts
The hostname for the Chef Analytics server may be specified using a FQDN or an IP address. This hostname must be resolvable. For example, a Chef Analytics server that is running in a production environment with a resolvable FQDN hostname can be added in the DNS system. But when deploying Chef Analytics into a testing environment, adding the hostname to the /etc/hosts
file is enough to ensure that hostname is resolvable.
myanalyticsserver.example.com
(and not something like myanalyticsserver
).The analytics_fqdn
setting must be added to the opscode-analytics.rb file (it is not there by default). Its value should be equal to the FQDN or IP address for the service URI used by the Chef Analytics server. For example: analytics_fqdn "chef-analytics.example.com"
or analytics_fqdn 123.45.67.890
.
Warning
The FQDN for the Chef Analytics server should not exceed 64 characters when using OpenSSL. OpenSSL requires the CN
in a certificate to be no longer than 64 characters. By default, Chef Analytics uses the FQDN of the server to determine the common name (CN
). If the FQDN of the Chef Analytics server is longer than 64 characters, the chef-server-ctl reconfigure
command will not fail, but an empty certificate file will be created. Nginx will not start if a certificate file is empty.
The Chef server server uses email to send notifications for various events:
Configure a local mail transfer agent on the Chef server using the steps appropriate for the platform on which the Chef server is running.
The Chef server requires that the systems on which it is running be connected to Network Time Protocol (NTP), as the Chef server is particularly sensitive to clock drift. For Red Hat and CentOS 6:
$ yum install ntp
or:
$ chkconfig ntpd on
or:
$ service ntpd start
For Ubuntu:
$ apt-get install ntp
The Chef server server requires that every node that is under management by Chef also have an accurate clock that is synchronized very closely with the clock on the Chef server. If the clocks are not synchronized closely, the authentication process may fail when the clocks are out-of-sync by more than 15 minutes. A failure will trigger a 401 Unauthorized
response similar to:
[Tue, 01 Nov 2011 16:55:23 -0700] INFO: *** Chef 11.X.X *** [Tue, 01 Nov 2011 16:55:23 -0700] INFO: Client key /etc/chef/client.pem is not present - registering [Tue, 01 Nov 2011 16:55:24 -0700] INFO: HTTP Request Returned 401 Unauthorized: Failed to authenticate as ORGANIZATION-validator. Synchronize the clock on your host. [Tue, 01 Nov 2011 16:55:24 -0700] FATAL: Stacktrace dumped to /var/chef/cache/chef-stacktrace.out [Tue, 01 Nov 2011 16:55:24 -0700] FATAL: Net::HTTPServerException: 401 "Unauthorized"
In this situation, re-synchronize the system clocks with the Network Time Protocol (NTP) server, and then re-run the chef-client.
By default, accounts required by the Chef server are created during setup. If your environment has restrictions on the creation of local user and group accounts that will prevent these accounts from being created automatically during setup, you will need to create these accounts.
Note
The Chef push jobs and Reporting premium features of the Chef server use the same user and group accounts as the Chef server.
The following group accounts are required:
Group Account | Description |
---|---|
opscode | The group name under which services will run. |
The following user accounts are required:
User Account | Description |
---|---|
opscode | The user name under which services will run. |
opscode-pgsql | The user name for PostgreSQL. (This is only required on the back end servers in a high availability setup.) |
© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs-archive.chef.io/release/server_12-8/install_server_pre.html