The following items are new for Chef server 12.3: - **Nginx stub_status module is enabled** The Nginx `stub_status` module is enabled by default and may be viewed at the `/nginx_status` endpoint. The settings for this module are configurable. - **RabbitMQ queue tuning** New settings for managing RabbitMQ queues allow the size of the queue used by Chef Analytics to be configured, including settings for the queue length monitor and for tuning the rabbitmq-management plugin. ## Nginx stub_status Module The following configuration settings are new and enable the Nginx `stub_status` module: `nginx['enable_stub_status']` : Enables the Nginx `stub_status` module. See `nginx['stub_status']['allow_list']`, `nginx['stub_status']['listen_host']`, `nginx['stub_status']['listen_port']`, and `nginx['stub_status']['location']`. Default value: `true`. `nginx['stub_status']['allow_list']` : The IP address on which accessing the `stub_status` endpoint is allowed. Default value: `["127.0.0.1"]`. `nginx['stub_status']['listen_host']` : The host on which the Nginx `stub_status` module listens. Default value: `"127.0.0.1"`. `nginx['stub_status']['listen_port']` : The port on which the Nginx `stub_status` module listens. Default value: `"9999"`. `nginx['stub_status']['location']` : The name of the Nginx `stub_status` endpoint used to access data generated by the Nginx `stub_status` module. Default value: `"/nginx_status"`. ## RabbitMQ Queues If the RabbitMQ queue that is used by Chef Analytics stops consuming messages, the Chef server data partition will fill up and may affect the overall performance of the Chef server application itself. The settings for the RabbitMQ queue are tunable, including for queue length monitoring, queue capacity, maximum number of messages that can be in the queue before messages are dropped, the point at which messages are dropped, for settings used by the rabbitmq-management plugin, and so on. The following settings may be used for tuning RabbitMQ queues used by Chef Analytics and the Chef server: `rabbitmq['analytics_max_length']` : The maximum number of messages that can be queued before RabbitMQ automatically drops messages from the front of the queue to make room for new messages. Default value: `10000`. `rabbitmq['drop_on_full_capacity']` : Specify if messages will stop being sent to the RabbitMQ queue when it is at capacity. Default value: `true`. `rabbitmq['management_enabled']` : Specify if the rabbitmq-management plugin is enabled. Default value: `true`. `rabbitmq['management_password']` : The rabbitmq-management plugin password. Default value: `'chefrocks'`. `rabbitmq['management_port']` : The rabbitmq-management plugin port. Default value: `15672`. `rabbitmq['management_user']` : The rabbitmq-management plugin user. Default value: `'rabbitmgmt'`. `rabbitmq['prevent_erchef_startup_on_full_capacity']` : Specify if the Chef server will start when the monitored RabbitMQ queue is full. Default value: `false`. `rabbitmq['queue_at_capacity_affects_overall_status']` : Specify if the `_status` endpoint in the Chef server API will fail if the monitored queue is at capacity. Default value: `false`. `rabbitmq['queue_length_monitor_enabled']` : Specify if the queue length monitor is enabled. Default value: `true`. `rabbitmq['queue_length_monitor_millis']` : The frequency (in milliseconds) at which the length of the RabbitMQ queue is checked. Default value: `30000`. `rabbitmq['queue_length_monitor_timeout_millis']` : The timeout (in milliseconds) at which calls to the queue length monitor will stop if the Chef server is overloaded. Default value: `5000`. `rabbitmq['queue_length_monitor_queue']` : The RabbitMQ queue that is observed by queue length monitor. Default value: `'alaska'`. `rabbitmq['queue_length_monitor_vhost']` : The virtual host for the RabbitMQ queue that is observed by queue length monitor. Default value: `'/analytics'`. `rabbitmq['rabbit_mgmt_http_cull_interval']` : The maximum cull interval (in seconds) for the HTTP connection pool that is used by the rabbitmq-management plugin. Default value: `60`. `rabbitmq['rabbit_mgmt_http_init_count']` : The initial worker count for the HTTP connection pool that is used by the rabbitmq-management plugin. Default value: `25`. `rabbitmq['rabbit_mgmt_http_max_age']` : The maximum connection worker age (in seconds) for the HTTP connection pool that is used by the rabbitmq-management plugin. Default value: `70`. `rabbitmq['rabbit_mgmt_http_max_connection_duration']` : The maximum connection duration (in seconds) for the HTTP connection pool that is used by the rabbitmq-management plugin. Default value: `70`. `rabbitmq['rabbit_mgmt_http_max_count']` : The maximum worker count for the HTTP connection pool that is used by the rabbitmq-management plugin. Default value: `100`. `rabbitmq['rabbit_mgmt_ibrowse_options']` : An array of comma-separated key-value pairs of ibrowse options for the HTTP connection pool that is used by the rabbitmq-management plugin. Default value: `'{connect_timeout, 10000}'`. `rabbitmq['rabbit_mgmt_timeout']` : The timeout for the HTTP connection pool that is used by the rabbitmq-management plugin. Default value: `30000`. `rabbitmq['ssl_versions']` : The SSL versions used by the rabbitmq-management plugin. (See [RabbitMQ TLS Support](https://www.rabbitmq.com/ssl.html) for more details.) Default value: `['tlsv1.2', 'tlsv1.1']`. ## What's New The following items are new for Chef server 12.2: - **Solr to Solr4 settings** Built-in transition for Apache Solr memory and JVM settings from Enterprise Chef to Chef server version 12. - **Configurable Postgresql** Postgresql can be configured for an external database. - **New endpoints for the Chef server API** Endpoints have been added to the Chef server API: `DELETE /policy_groups`. - **New subcommmands for chef-server-ctl** Use the `backup` and `restore` subcommmands to back up and restore Chef server data. Use the `psql` subcommmand to log into a PostgreSQL database that is associated with a service running in the Chef server configuration. - **New options for chef-server-ctl reindex** The `reindex` subcommand has new options: `--all-orgs` (reindex all organizations), `--disable-api` (disable the Chef server API during reindexing), `--with-timing` (print timing information), and `--wait` (wait for reindex queue to clear before exiting). ## Solr =\> Solr 4 Changes Chef server version 12 is upgraded to Apache Solr 4. If Apache Solr options were added to the private-chef.rb file under `opscode_solr` for Enterprise Chef, those configuration options are now stored under `opscode_solr4` in the chef-server.rb file for Chef server version 12. Some `opscode_solr` settings are imported automatically, such as heap, new size, and Java options, but many settings are ignored. If your Enterprise Chef configuration is highly tuned for Apache Solr, review [these configuration settings](/server/config_rb_server_optional_settings/#opscode-solr4) before re-tuning Apache Solr for Chef server version 12. ## External PostgreSQL The following diagram highlights the specific changes that occur when PostgreSQL is configured and managed independently of the Chef server configuration. image The following table describes the components in an external PostgreSQL configuration that are different from the default configuration of the Chef server:
Component Description
Chef Server The Chef server configuration file is updated to point to an independently configured set of servers for PostgreSQL.

PostgreSQL

PostgreSQL is the data storage repository for the Chef server.

This represents the independently configured set of servers that are running PostgreSQL and are configured to act as the data store for the Chef server.
**Note:** The following `chef-server-ctl` subcommands for managing services are disabled when an external PostgreSQL database is configured for the Chef server: `hup`, `int`, `kill`, `once`, `restart`, `start`, `stop`, `tail`, and `term`. ## Settings Use the following configuration settings in the chef-server.rb file to configure PostgreSQL for use with the Chef server:
Setting Description
postgresql['db_superuser'] Required when postgresql['external'] is set to true. The PostgreSQL user name. This user must be granted either the CREATE ROLE and CREATE DATABASE permissions in PostgreSQL or be granted SUPERUSER permission. This user must also have an entry in the host-based authentication configuration file used by PostgreSQL (traditionally named pg_hba.conf). Default value: 'superuser_userid'.
postgresql['db_superuser_password'] Required when postgresql['external'] is set to true. The password for the user specified by postgresql['db_superuser']. Default value: 'the password'.
postgresql['external'] Required. Set to true to run PostgreSQL external to the Chef server. Must be set once only on a new installation of the Chef server before the first chef-server-ctl reconfigure command is run. If this is set after a reconfigure or set to false, any reconfigure of the Chef server will return an error. Default value: false.
postgresql['port'] Optional when postgresql['external'] is set to true. The port on which the service is to listen. The port used by PostgreSQL if that port is not 5432. Default value: 5432.
postgresql['vip'] Required when postgresql['external'] is set to true. The virtual IP address. The host for this IP address must be online and reachable from the Chef server via the port specified by postgresql['port']. Set this value to the IP address or hostname for the machine on which external PostgreSQL is located when postgresql['external'] is set to true.
## Backup / Restore Use the following commands to manage backups of Chef server data, and then to restore those backups. ## backup The `backup` subcommand is used to back up all Chef server data. This subcommand: - Requires rsync to be installed on the Chef server prior to running the command - Requires a `chef-server-ctl reconfigure` prior to running the command - Should not be run in a Chef server configuration with an external PostgreSQL database; [use knife ec backup](https://github.com/chef/knife-ec-backup) instead - Puts the initial backup in the `/var/opt/chef-backup` directory as a tar.gz file; move this backup to a new location for safe keeping **Options** This subcommand has the following options: `-y`, `--yes` : Use to specify if the Chef server can go offline during tar.gz-based backups. **Syntax** This subcommand has the following syntax: ```bash chef-server-ctl backup ``` ## restore The `restore` subcommand is used to restore Chef server data from a backup that was created by the `backup` subcommand. This subcommand may also be used to add Chef server data to a newly-installed server. This subcommand: - Requires rsync to be installed on the Chef server prior to running the command - Requires a `chef-server-ctl reconfigure` prior to running the command - Should not be run in a Chef server configuration with an external PostgreSQL database; [use knife ec backup](https://github.com/chef/knife-ec-backup) instead **Options** This subcommand has the following options: `-c`, `--cleanse` : Use to remove all existing data on the Chef server; it will be replaced by the data in the backup archive. `-d DIRECTORY`, `--staging-dir DIRECTORY` : Use to specify that the path to an empty directory to be used during the restore process. This directory must have enough disk space to expand all data in the backup archive. **Syntax** This subcommand has the following syntax: ```bash chef-server-ctl restore PATH_TO_BACKUP (options) ``` **Examples** ```bash chef-server-ctl restore /path/to/tar/archive.tar.gz ``` ## psql The `psql` subcommand is used to log into the PostgreSQL database associated with the named service. This subcommand: - Uses `psql` (the interactive terminal for PostgreSQL) - Has read-only access by default - Is the recommended way to interact with any PostgreSQL database that is part of the Chef server - Automatically handles authentication **Syntax** This subcommand has the following syntax: ```bash chef-server-ctl psql SERVICE_NAME (options) ``` **Options** This subcommand has the following options: `--write` : Use to enable write access to the PostgreSQL database. ## reindex Options This subcommand has the following options: `-a`, `--all-orgs` : Use to reindex all organizations on the Chef server. This option will override any organization specified as part of the command, i.e. `chef-server-ctl reindex ORG_NAME -a` will reindex all organizations and not just the specified organization. `-d`, `--disable-api` : Use to disable the Chef server API to prevent writes during reindexing. `-t`, `--with-timing` : Use to print timing information for the reindex processes. `-w`, `--wait` : Use to wait for the reindexing queue to clear before exiting. This option only works when run on a standalone Chef server, or on a primary backend Chef server within a legacy tier or DRBD HA system. This option should not be used on a HA frontend. ## Chef server API Endpoints The following endpoints have been added to the Chef server API: ## /policy_groups/NAME The `/policy_groups` endpoint has the following methods: `GET`. ### DELETE The `DELETE` method is used to delete a policy group that is stored on the Chef server. This method has no parameters. **Request** ```none DELETE /organizations/NAME/policy_groups/NAME ``` **Response** The response returns the policy details and is similar to: ```javascript { "uri": "https://chef.example/organizations/org1/policy_groups/dev", "policies": { "aar": { "revision_id": "95040c199302c85c9ccf1bcc6746968b820b1fa25d92477ea2ec5386cd58b9c5" }, "jenkins": { "revision_id": "613f803bdd035d574df7fa6da525b38df45a74ca82b38b79655efed8a189e073" } } } ``` **Response Codes**
Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user or client who made the request could not be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
403 Forbidden. The user who made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
## /policies/NAME The `/policies/NAME` endpoint has the following methods: `DELETE` and `GET`. These endpoints enables the management of policies as they relate to a specific policy group. ### GET The `GET` method is used to return a policy document. This method has no parameters. **Request** ```none GET /organizations/NAME/policies/NAME ``` **Response** The response is similar to: ```none xxxxx ``` **Response Codes**
Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user or client who made the request could not be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
403 Forbidden. The user who made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
### DELETE The `DELETE` method is used to delete a policy. This method has no parameters. **Request** ```none DELETE /organizations/NAME/policies/NAME ``` **Response** The response returns the policy details and is similar to: ```javascript { "revisions": { "37f9b658cdd1d9319bac8920581723efcc2014304b5f3827ee0779e10ffbdcc9": {}, "95040c199302c85c9ccf1bcc6746968b820b1fa25d92477ea2ec5386cd58b9c5": {}, "d81e80ae9bb9778e8c4b7652d29b11d2111e763a840d0cadb34b46a8b2ca4347": {} } } ``` **Response Codes**
Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user or client who made the request could not be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
403 Forbidden. The user who made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
## /policies/NAME/revisions The `/roles` endpoint has the following methods: `POST`. ### POST The `POST` method is used to create a new policy revision. This method has no parameters. **Request** ```none POST /organizations/NAME/policies/NAME/revisions ``` with a request body similar to: ```none xxxxx ``` **Response** The response is similar to: ```none xxxxx ``` **Response Codes**
Response Code Description
201 OK. The request was successful.
400 Bad request. The contents of the request are not formatted correctly.
401 Unauthorized. The user or client who made the request could not be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
403 Forbidden. The user who made the request is not authorized to perform the action.
409 Conflict. The object already exists.
413 Request entity too large. A request may not be larger than 1000000 bytes.
## /policies/NAME/revisions/ID The `/policies/NAME/revisions/ID` endpoint has the following methods: `DELETE` and `GET`. ### GET The `GET` method is used to return a policy document for a specific policy revision. This method has no parameters. **Request** ```none GET /organizations/NAME/GROUP/policies/NAME/revisions/ID ``` **Response** The response is similar to: ```javascript { "revision_id": "37f9b658cdd1d9319bac8920581723efcc2014304b5f3827ee0779e10ffbdcc9", "name": "aar", "run_list": [ "recipe[aar::default]" ], "cookbook_locks": { "aar": { "version": "0.1.0", "identifier": "29648fe36333f573d5fe038a53256e23733618aa", "dotted_decimal_identifier": "11651043203167221.32604909279531813.121098535835818", "source": "cookbooks/aar", "cache_key": null, "scm_info": { "scm": "git", "remote": null, "revision": "a2c8cbb24a08625921d753cde36e8320465116c3", "working_tree_clean": false, "published": false, "synchronized_remote_branches": [] }, "source_options": { "path": "cookbooks/aar" } }, "apt": { "version": "2.7.0", "identifier": "16c57abbd056543f7d5a15dabbb03261024a9c5e", "dotted_decimal_identifier": "6409580415309396.17870749399956400.55392231660638", "cache_key": "apt-2.7.0-supermarket.chef.io", "origin": "https://supermarket.chef.io/api/v1/cookbooks/apt/versions/2.7.0/download", "source_options": { "artifactserver": "https://supermarket.chef.io/api/v1/cookbooks/apt/versions/2.7.0/download", "version": "2.7.0" } } }, "default_attributes": {}, "override_attributes": {}, "solution_dependencies": { "Policyfile": [ [ "aar", ">= 0.0.0" ], [ "apt", "= 2.7.0" ], ], "dependencies": { "apt (2.7.0)": [], "aar (0.1.0)": [ [ "apt", ">= 0.0.0" ] ] } } } ``` **Response Codes**
Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user or client who made the request could not be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
403 Forbidden. The user who made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.
### DELETE The `DELETE` method is used to delete a policy document for a specific policy revision. This method has no parameters. **Request** ```none DELETE /organizations/NAME/GROUP/policies/NAME/revisions/ID ``` **Response** The response returns the policy details and is similar to: ```javascript { "revision_id": "37f9b658cdd1d9319bac8920581723efcc2014304b5f3827ee0779e10ffbdcc9", "name": "aar", "run_list": [ "recipe[aar::default]" ], "cookbook_locks": { "aar": { "version": "0.1.0", "identifier": "29648fe36333f573d5fe038a53256e23733618aa", "dotted_decimal_identifier": "11651043203167221.32604909279531813.121098535835818", "source": "cookbooks/aar", "cache_key": null, "scm_info": { "scm": "git", "remote": null, "revision": "a2c8cbb24a08625921d753cde36e8320465116c3", "working_tree_clean": false, "published": false, "synchronized_remote_branches": [] }, "source_options": { "path": "cookbooks/aar" } }, "apt": { "version": "2.7.0", "identifier": "16c57abbd056543f7d5a15dabbb03261024a9c5e", "dotted_decimal_identifier": "6409580415309396.17870749399956400.55392231660638", "cache_key": "apt-2.7.0-supermarket.chef.io", "origin": "https://supermarket.chef.io/api/v1/cookbooks/apt/versions/2.7.0/download", "source_options": { "artifactserver": "https://supermarket.chef.io/api/v1/cookbooks/apt/versions/2.7.0/download", "version": "2.7.0" } } }, "default_attributes": {}, "override_attributes": {}, "solution_dependencies": { "Policyfile": [ [ "aar", ">= 0.0.0" ], [ "apt", "= 2.7.0" ], ], "dependencies": { "apt (2.7.0)": [], "aar (0.1.0)": [ [ "apt", ">= 0.0.0" ] ] } } } ``` **Response Codes**
Response Code Description
200 OK. The request was successful.
401 Unauthorized. The user or client who made the request could not be authenticated. Verify the user/client name, and that the correct key was used to sign the request.
403 Forbidden. The user who made the request is not authorized to perform the action.
404 Not found. The requested object does not exist.