Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: eeb421923d
Fetching contributors…

Cannot retrieve contributors at this time

88 lines (71 sloc) 19.333 kB
{
"name": "chef",
"description": "Installs and configures Chef for chef-client and chef-server",
"long_description": "BOOTSTRAP CHANGES\n=================\n\nThe `bootstrap` cookbook's recipes for configuring a RubyGem installation of Chef have been merged into this cookbook. Do not use the `bootstrap` cookbook on versions of Chef after 0.8.2.\n\n bootstrap::client -> chef::bootstrap_client\n bootstrap::server -> chef::bootstrap_server\n\nBe aware of the following changes to this cookbook.\n\n* Bootstrap no longer generates a random password for the webui admin user. The default password is displayed on the webui login page and should be changed immediately after logging in.\n* Server configuration now has a setting for the cookbook tarballs. See the server.rb.erb template.\n* We now set the signing key/cert locations and set owner / group. See the server.rb.erb template.\n* The validation client name is configurable. See the attributes.\n\nThe client service setup has been moved from the `chef::bootstrap_client` recipe into its own recipe, `chef::client_service`. This is to improve use with Knife bootstrap which already configures the client configuration file.\n\nDESCRIPTION\n===========\n\nThis cookbook is used to configure the system to be a Chef Client or a Chef Server. It is a complex cookbook, please read this entire document to understand how it works. For more information on how Chef itself works, see the [Chef Wiki](http://wiki.opscode.com)\n\nREQUIREMENTS\n============\n\nChef 0.8.16 or later is required.\n\nChef 0.9.0 or later is required to use the `chef.init_style` attribute value `init`, in order to have the init scripts available.\n\nPlatform\n--------\n\nIf using this cookbook to manage a Chef Server system that was installed from Debian/Ubuntu packages, note that in the packages, the configuration files are split up for server.rb, solr.rb and webui.rb, and the `chef::server` recipe may not work as desired.\n\nA recent version of Ubuntu or Debian is recommended for the Chef Server.\n\n* Ubuntu 9.10/10.04\n* Debian testing/unstable\n\nThese versions have newer versions of CouchDB and RabbitMQ packaged.\n\n`chef::client` is tested on Ubuntu 8.04+, Debian 5.0, CentOS 5.x, Fedora 10+, OpenBSD 4.6, FreeBSD 7.1 and Gentoo.\n\n`chef::bootstrap_client` is tested on the above. OpenSolaris 11 is also tested, but there's a bug in Ohai that requires some manual intervention (OHAI-122).\n\n`chef::server` is tested on Ubuntu 8.04+, Debian 5.0.\n\n`chef::bootstrap_server` is tested on Ubuntu 8.04+, Debian 5.0.\n\nClient\n------\n\n`runit` cookbook is suggested for RubyGems installation. No other cookbooks are required for clients.\n\nServer\n------\n\nThe `chef::bootstrap_server` recipe uses the following other cookbooks from Opscode.\n\n* couchdb\n* `rabbitmq_chef`\n* openssl\n* zlib\n* xml\n* java\n\nThe `chef::server_proxy` recipe uses the following cookbook:\n\n* apache2\n\nATTRIBUTES\n==========\n\nThe attributes for configuring the `chef` cookbook are under the `chef` namespace on the node, i.e., `@node[:chef]` or `@node.chef`.\n\nWhen using the bootstrap recipe, set the desired attributes using a JSON file. See \"BOOTSTRAPPING\" for examples.\n\numask\n-----\n\nSets the umask for files created by the server process via `Chef::Config[:umask]` in `/etc/chef/server.rb`\n\n`url_type`\n----------\n\nSet up the URLs the client should connect to with this. Default is `http`, which tells the client to connect to `http://server:4000`. If you set up your chef-server to use an SSL front-end for example with `chef::server_proxy`, set this to `https` for clients and the URLs will be `https://server/`.\n\nBy default the only URL config setting for Chef 0.8.x+ is `Chef::Config[:chef_server_url]`. The other older URLs are still supported so you can split out the various functions of the Chef Server, but configuration of those is outside the scope of this cookbook.\n\n`init_style`\n------------\n\nSpecifies the init style to use. Possible values:\n\n* runit - uses runit to set up the service. Logs will be in `/etc/sv/chef-client/log/main`. Default value for this attribute.\n* init - uses init scripts that are included in the `chef` gem. Logs will be in `/var/log/chef`. Only usable with debian/ubuntu and red hat family distributions.\n* daemontools - uses daemontools to set up the service. Logs will be in `/etc/sv/chef-client/log/main`.\n* bluepill - uses bluepill to set up the service.\n* bsd - Prints a message with the chef-client command to use in rc.local.\n\nIf your platform doesn't have a `runit` package or if the cookbook doesn't detect it, but you still want to use runit, set `init_style` to `none` and install runit separately. You may need to configure the runit services separately.\n\nUsing the `init` value for this attribute will retrieve the init scripts that are distributed with the Chef gem.\n\nThis cookbook does not yet support Upstart for Ubuntu/Debian, but that is planned for a future release, and will be specified via this attribute.\n\npath\n----\n\nThis is the base location where Chef will store data and other artifacts. Default `/srv/chef` for RubyGems installed systems. If using Chef packages for your platform, the location preference varies. The default on Debian and Red Hat based systems is a filesystem hiearchy standard (FHS) suggestion. Some other locations you may consider, by platform:\n\nDebian and Red Hat based Linux distros (Ubuntu, CentOS, Fedora, etc):\n\n* `/var/lib/chef`\n\nAny BSD and Gentoo:\n\n* `/var/chef`\n\n`run_path`\n----------\n\nLocation for pidfiles on systems using init scripts. Default `/var/run/chef`.\n\nIf `init_style` is `init`, this is used, and should match what the init script itself uses for the PID files.\n\n`cache_path`\n------------\n\nLocation where the client will cache cookbooks and other data. Default is `cache` underneath the `chef[:path]` location. Linux distributions adhering to the FHS prefer `/var/cache/chef` instead.\n\nBase directory for data that is easily regenerated such as cookbook tarballs (`Chef::Config[:cookbook_tarballs]`) on the server, downloaded cookbooks on the client, etc. See the config templates.\n\n`backup_path`\n-------------\n\nLocation where backups of files, corresponds to the `file_backup_path` location. Defaults to `backup` under `chef[:path]` location. Set to `false` to use the old behavior which stores the backup files in the same directory as the target.\n\nFHS location suggestion: `/var/lib/chef/backup`.\n\n`serve_path`\n------------\n\nUsed by the Chef server as the base location to \"serve\" cookbooks, roles and other assets. Default is `/srv/chef`.\n\n`server_version`\n----------------\n\nVersion of Chef to install for the server. Used by the `server_proxy` recipe to set the location of the DocumentRoot of the WebUI. Automatically determined via ohai's `chef_packages[:chef][:version]` by default.\n\n`client_version`\n----------------\n\nVersion of Chef to install for the client. Used to display a log message about the location of the init scripts when `init_style` is `init`, and can be used to upgrade `chef` gem with the `chef::bootstrap_client` recipe. Automatically determined via ohai's `chef_packages[:chef][:version]` by default.\n\n`client_interval`\n-----------------\n\nNumber of seconds to run chef-client periodically. Default `1800` (30 minutes).\n\n`client_splay`\n--------------\n\nSplay interval to randomly add to interval. Default `20`.\n\n`log_dir`\n---------\n\nWhen `init_style` is `init`, this directory needs to be created. The default is `/var/log/chef`.\n\n`client_log`, `indexer_log`, `server_log`\n-----------------------------------------\n\nThese options are deprecated to reduce complexity and potential confusion.\n\n`server_port`\n-------------\n\nPort for the Server API service to listen on. Default `4000`.\n\n`webui_port`\n------------\n\nPort for the Server WebUI service to listen on. Default `4040`.\n\n`webui_enabled`\n---------------\n\nAs of version 0.8.x+, the WebUI part of the Chef Server is optional, and disabled by default. To enable it, set this to true.\n\n`server_fqdn`\n-------------\n\nFully qualified domain name of the server. Default is `chef.domain` where domain is detected by Ohai. You should configure a DNS entry for your Chef Server.\n\nOn servers, this specifies the URL the server expects to use by default `Chef::Config[:chef_server_url]`, plus it is used in the `server_ssl_req` as the canonical name (CN) and in `server_proxy` for the vhost name.\n\nOn clients, this specifies the URL the client uses to connect to the server as `Chef::Config[:chef_server_url]`.\n\n`server_url`\n------------\n\nFull URI for the Chef Server. Used for `chef_server_url` config setting. The default value combines the attributes `chef.url_type`, `chef.server_fqdn` and `chef.server_port`, creating for example \"http://chef.example.com:4000\". If you are using the Opscode Platform, set this to \"https://api.opscode.com/organizations/ORGNAME\", where ORGNAME is your organization's simple string name.\n\nSERVER PROXY\n------------\n\nThe following attributes are used by the `server_proxy.rb` recipe, and are stored in the `server_proxy.rb` attributes file.\n\n`doc_root`\n----------\n\nDocumentRoot for the WebUI. Also gets set in the vhost for the API, but it is not used since the vhost merely proxies to the server on port 4000.\n\n`server_ssl_req`\n----------------\n\nUsed by the `server_proxy` recipe, this attribute can be used to set up a self-signed SSL certificate automatically using OpenSSL. Fields:\n\n* C: country (two letter code)\n* ST: state/province\n* L: locality or city\n* O: organization\n* OU: organizational unit\n* CN: canonical name, usually the fully qualified domain name of the server (FQDN)\n* emailAddress: contact email address\n\nThis attribute is now in the `server_proxy.rb` attributes file, as it is specific to that context.\n\n`server_proxy.css_expire_hours`\n-------------------------------\n\nSets expiration time for CSS in the WebUI.\n\n`server_proxy.js_expire_hours`\n------------------------------\n\nSets expiration time for JavaScript in the WebUI.\n\nRECIPES AND USAGE\n=================\n\nThis section describes the recipes in the cookbook and how to use them in your environment.\n\nBOOTSTRAPPING\n-------------\n\nThe first two recipes described are for \"bootstrapping\" a system to be a Chef Client or Chef Server, respectively. Only use these recipes with RubyGems installations of Chef.\n\nThese recipes are typically used with chef-solo using a JSON file of attributes and a run list, and a solo config file. For more information see [Bootstrap Chef RubyGems Installation](http://wiki.opscode.com/display/chef/Bootstrap+Chef+RubyGems+Installation) on the Chef Wiki.\n\n`bootstrap_client`\n------------------\n\nONLY FOR RUBYGEMS INSTALLATIONS. Do not use this recipe if you installed Chef from packages for your platform.\n\nUse this recipe to \"bootstrap\" a client so it can connect to a Chef Server. This recipe does the following:\n\n* Ensures the gem installed matches the version desired (`client_version` attribute).\n* Includes the `chef::client_service` recipe to ensure that `chef-client` is running as a service.\n* Sets up some directories for Chef to use.\n* Creates the client configuration file `/etc/chef/client.rb` based on the configuration passed via JSON.\n\nFor configuring a new client to connect to the Opscode Platform:\n\n {\n \"chef\": {\n \"server_url\": \"https://api.opscode.com/organizations/ORGNAME\"\n },\n \"run_list\": \"recipe[chef::bootstrap_client]\"\n }\n\nFor configuring a new client to connect to a local Chef Server:\n\n {\n \"chef\": {\n \"server_url\": \"http://chef.example.com:4000\"\n },\n \"run_list\": \"recipe[chef::bootstrap_client]\"\n }\n\nThis is the minimal JSON to use for the client configuration. See the ATTRIBUTES section above for more options.\n\n`bootstrap_server`\n------------------\n\nONLY FOR RUBYGEMS INSTALLATIONS. Do not use this recipe if you installed Chef from packages for your platform.\n\nUse this recipe to \"bootstrap\" a system to become a Chef Server. This recipe does the following:\n\n* Includes the `chef::bootstrap_client` recipe to configure itself to be its own client.\n* Installs CouchDB from package or source depending on the platform.\n* Installs Java for the `chef-solr` search engine.\n* Installs RabbitMQ (`rabbitmq_chef` cookbook) for the `chef-solr-indexer` consumer.\n* Installs all the Server-related Gems.\n* Creates the server configuration file `/etc/chef/server.rb` based on the configuration passed via JSON.\n* Sets up some directories for the server to use.\n* Sets up the `chef-server`, `chef-solr`, `chef-solr-indexer` services depending on the `init_style` attribute (see above).\n\nMinimal JSON to use for the server configuration:\n\n {\n \"chef\": {\n \"server_url\": \"http://localhost.localdomain:4000\",\n },\n \"run_list\": \"recipe[chef::bootstrap_server]\"\n }\n\nNote that the `chef-server-webui` is optional and can be enabled if desired by adding this to the JSON under \"chef\":\n\n \"webui_enabled\": true\n\nclient\n------\n\nThe client recipe is used to manage the configuration of an already-installed and configured Chef client. It can be used after a RubyGems installation bootstrap (per above), or with clients that were installed from platform packaging.\n\nThe recipe itself manages the `/etc/chef/client.rb` config file based on the attributes in this cookbook. When the client config is updated, the recipe will also reread the configuration during the Chef run, so the current Chef run can be dynamically changed.\n\nThis recipe does not manage the `chef-client` service. It is assumed to have been set up and started from the `bootstrap_client` recipe above, or from OS / distribution packaging. The `chef-client` service should not be restarted as a result of `/etc/chef/client.rb` changing, as that can cause the current process running the client to be restarted, having unpredictable results.\n\n`client_service`\n----------------\n\nUse this recipe on systems that should have a `chef-client` daemon running, such as when Knife bootstrap was used to install Chef on a new system.\n\nThis recipe sets up the `chef-client` service depending on the `init_style` attribute (see above). It is included by the `chef::bootstrap_client` recipe.\n\ndefault\n-------\n\nThere is no spoon :-).\n\n`delete_validation`\n-------------------\n\nUse this recipe to delete the validation certificate (default `/etc/chef/validation.pem`) when using a `chef-client` after the client has been validated and authorized to connect to the server.\n\nBeware if using this on your Chef Server. First copy the validation.pem certificate file to another location, such as your knife configuration directory (`~/.chef`) or [Chef Repository](http://wiki.opscode.com/display/chef/Chef+Repository).\n\nserver\n------\n\nThe server recipe includes the `chef::client` recipe above.\n\nThe recipe itself manages the services and the Server config file `/etc/chef/server.rb`. See above under Platform requirements for cavaet when running Chef Server installed via Debian/Ubuntu packages. Changes to the recipe to manage additional templates may be required.\n\nThe following services are managed:\n\n* chef-solr\n* chef-solr-indexer\n* chef-server\n* chef-webui (if installed)\n\nChanges to the `/etc/chef/server.rb` will trigger a restart of these services.\n\nSince the Chef Server itself typically runs the CouchDB service for the data store, the recipe will do a compaction on the Chef database and all the views associated with the Chef Server. These compactions only occur if the database/view size is more than 100Mb. It will use the configured CouchDB URL, which is `http://localhost:5984` by default. The actual value used for the CouchDB server is from the `Chef::Config[:couchdb_url]`, so this can be dynamically changed.\n\n`server_proxy`\n--------------\n\nThis recipe sets up an Apache2 VirtualHost to proxy HTTPS for the Chef Server API and WebUI.\n\nThe API will be proxied on port 443. If the `chef-serer-webui` is installed, it will be proxied on port 444. The recipe dynamically creates the OpenSSL certificate based on the `chef.server_ssl_req` attribute. It uses some additional configuration for Apache to improve performance of the webui. The virtual host template is `chef_server.conf.erb`. The DocumentRoot setting is used for the WebUI, but not the API, and is set with the attribute `chef.doc_root`.\n\nTEMPLATES\n=========\n\n`chef_server.conf.erb`\n----------------------\n\nVirtualHost file used by Apache2 in the `chef::server_proxy` recipe.\n\nclient.rb.erb\n-------------\n\nConfiguration for the client, lands in `/etc/chef/client.rb`.\n\nserver.rb.erb\n-------------\n\nConfiguration for the server and server components, lands in `/etc/chef/server.rb`. See above regarding Debian/Ubuntu packaging config files when using packages to install Chef.\n\n`sv-*run.erb`\n-------------\n\nVarious runit \"run\" scripts for the Chef services that get configured when `init_style` is \"runit\".\n\nLICENSE AND AUTHORS\n===================\n\n* Author: Joshua Timberman <joshua@opscode.com>\n* Author: Joshua Sierles <joshua@37signals.com>\n\n* Copyright 2008-2010, Opscode, Inc\n* Copyright 2009, 37signals\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\n",
"maintainer": "Opscode, Inc.",
"maintainer_email": "cookbooks@opscode.com",
"license": "Apache 2.0",
"platforms": {
"ubuntu": [
],
"debian": [
],
"redhat": [
],
"centos": [
],
"fedora": [
],
"freebsd": [
],
"openbsd": [
]
},
"dependencies": {
"runit": [
],
"bluepill": [
],
"daemontools": [
],
"couchdb": [
],
"rabbitmq_chef": [
],
"apache2": [
],
"openssl": [
],
"zlib": [
],
"xml": [
],
"java": [
]
},
"recommendations": {
},
"suggestions": {
},
"conflicting": {
},
"providing": {
},
"replacing": {
},
"attributes": {
},
"groupings": {
},
"recipes": {
"chef": "Default recipe is empty, use one of the other recipes.",
"chef::client": "Sets up a client to talk to a chef-server",
"chef::client_service": "Sets up a client daemon to run periodically",
"chef::bootstrap_client": "Set up rubygem installed chef client",
"chef::delete_validation": "Deletes validation.pem after client registers",
"chef::server": "Configures a chef API server as a merb application",
"chef::bootstrap_server": "Set up rubygem installed chef server",
"chef::server_proxy": "Configures Apache2 proxy for API and WebUI"
},
"version": "0.99.0"
}
Jump to Line
Something went wrong with that request. Please try again.