cookbooks/yum/README.md

   1 yum Cookbook
   2 ============
   3
   4 The Yum cookbook exposes the `yum_globalconfig` and `yum_repository`
   5 resources that allows a user to both control global behavior and make
   6 individual Yum repositories available for use. These resources aim to
   7 allow the user to configure all options listed in the `yum.conf` man
   8 page, found at http://linux.die.net/man/5/yum.conf
   9
  10 NOTES
  11 -----
  12 WARNING: Yum cookbook version 3.0.0 and above contain non-backwards
  13 compatible breaking changes and will not work with cookbooks written
  14 against the 2.x and 1.x series. Changes have been made to the
  15 yum_repository resource, and the yum_key resource has been eliminated
  16 entirely. Recipes have been eliminated and moved into their own
  17 cookbooks. Please lock yum to the 2.x series in your Chef environments
  18 until all dependent cookbooks have been ported.
  19
  20 Requirements
  21 ------------
  22 * Chef 11 or higher
  23 * Ruby 1.9 (preferably from the Chef full-stack installer)
  24 * RHEL5, RHEL6, or other platforms within the family
  25
  26 Resources/Providers
  27 -------------------
  28 ### yum_repository
  29 This resource manages a yum repository configuration file at
  30 /etc/yum.repos.d/`repositoryid`.repo. When the file needs to be
  31 repaired, it calls yum-makecache so packages in the repo become
  32 available to the next resource.
  33
  34 #### Example
  35 ``` ruby
  36 # add the Zenoss repository
  37 yum_repository 'zenoss' do
  38   description "Zenoss Stable repo"
  39   baseurl "http://dev.zenoss.com/yum/stable/"
  40   gpgkey 'http://dev.zenoss.com/yum/RPM-GPG-KEY-zenoss'
  41   action :create
  42 end
  43
  44 # add the EPEL repo
  45 yum_repository 'epel' do
  46   description 'Extra Packages for Enterprise Linux'
  47   mirrorlist 'http://mirrors.fedoraproject.org/mirrorlist?repo=epel-6&arch=$basearch'
  48   gpgkey 'http://dl.fedoraproject.org/pub/epel/RPM-GPG-KEY-EPEL-6'
  49   action :create
  50 end
  51 ```
  52
  53 ``` ruby
  54 # delete CentOS-Media repo
  55 yum_repository 'CentOS-Media' do
  56   action :delete
  57 end
  58 ```
  59
  60 #### Actions
  61 - `:create` - creates a repository file and builds the repository listing
  62 - `:delete` - deletes the repository file
  63
  64 #### Parameters
  65 * `baseurl` -  Must be a URL to the directory where the yum repository's
  66   'repodata' directory lives. Can be an http://, ftp:// or file://
  67   URL. You can specify multiple URLs in one baseurl statement.
  68 * `cost` - relative cost of accessing this repository. Useful for
  69   weighing one repo's packages as greater/less than any other.
  70   defaults to 1000
  71 * `description` - Maps to the 'name' parameter in a repository .conf.
  72   Descriptive name for the repository channel. This directive must be
  73   specified.
  74 * `enabled` - Either `true` or `false`. This tells yum whether or not use this repository.
  75 * `enablegroups` -  Either `true` or `false`. Determines whether yum
  76   will allow the use of package groups for this repository. Default is
  77   `true` (package groups are allowed).
  78 * `exclude` - List of packages to exclude from updates or installs. This
  79   should be a space separated list in a single string. Shell globs using wildcards (eg. *
  80   and ?) are allowed.
  81 * `failovermethod` - Either 'roundrobin' or 'priority'.
  82 * `fastestmirror_enabled` - Either `true` or `false`
  83 * `gpgcheck` - Either `true` or `false`. This tells yum whether or not
  84   it should perform a GPG signature check on packages. When this is
  85   set in the [main] section it sets the default for all repositories.
  86   The default is `true`.
  87 * `gpgkey` - A URL pointing to the ASCII-armored GPG key file for the
  88   repository. This option is used if yum needs a public key to verify
  89   a package and the required key hasn't been imported into the RPM
  90   database. If this option is set, yum will automatically import the
  91   key from the specified URL.
  92 * `http_caching` - Either 'all', 'packages', or 'none'. Determines how
  93   upstream HTTP caches are instructed to handle any HTTP downloads
  94   that Yum does. Defaults to 'all'
  95 * `includepkgs` -  Inverse of exclude. This is a list of packages you
  96   want to use from a repository. If this option lists only one package
  97   then that is all yum will ever see from the repository. Defaults to
  98   an empty list.
  99 * `keepalive` - Either `true` or `false`. This tells yum whether or not
 100   HTTP/1.1 keepalive should be used with this repository.
 101 * `max_retries` - Set the number of times any attempt to retrieve a file
 102   should retry before returning an error. Setting this to '0' makes
 103   yum try forever. Default is '10'.
 104 * `metadata_expire` - Time (in seconds) after which the metadata will
 105   expire. So that if the current metadata downloaded is less than this
 106   many seconds old then yum will not update the metadata against the
 107   repository. If you find that yum is not downloading information on
 108   updates as often as you would like lower the value of this option.
 109   You can also change from the default of using seconds to using days,
 110   hours or minutes by appending a d, h or m respectively. The default
 111   is 6 hours, to compliment yum-updatesd running once an hour. It's
 112   also possible to use the word "never", meaning that the metadata
 113   will never expire. Note that when using a metalink file the metalink
 114   must always be newer than the metadata for the repository, due to
 115   the validation, so this timeout also applies to the metalink file.
 116 * `mirrorlist` - Specifies a URL to a file containing a list of
 117   baseurls. This can be used instead of or with the baseurl option.
 118   Substitution variables, described below, can be used with this
 119   option. As a special hack is the mirrorlist URL contains the word
 120   "metalink" then the value of mirrorlist is copied to metalink (if
 121   metalink is not set)
 122 * `mirror_expire` - Time (in seconds) after which the mirrorlist locally
 123   cached will expire. If the current mirrorlist is less than this many
 124   seconds old then yum will not download another copy of the
 125   mirrorlist, it has the same extra format as metadata_expire. If you
 126   find that yum is not downloading the mirrorlists as often as you
 127   would like lower the value of this option.
 128 * `mirrorlist_expire` - alias for mirror_expire
 129 * `priority` - When the yum-priorities plug-in is enabled, you set
 130   priorities on repository entries, where N is an integer from 1 to 99. The
 131   default priority for repositories is 99.
 132 * `proxy` - URL to the proxy server that yum should use.
 133 * `proxy_username` -  username to use for proxy
 134 * `proxy_password` - password for this proxy
 135 * `report_instanceid` - Report instance ID when using Amazon Linux AMIs
 136   and repositories
 137 * `repositoryid` - Must be a unique name for each repository, one word.
 138   Defaults to name attribute.
 139 * `source` - Use a custom template source instead of the default one
 140   in the yum cookbook
 141 * `sslcacert` - Path to the directory containing the databases of the
 142   certificate authorities yum should use to verify SSL certificates.
 143   Defaults to none - uses system default
 144 * `sslclientcert` - Path to the SSL client certificate yum should use to
 145   connect to repos/remote sites Defaults to none.
 146 * `sslclientkey` - Path to the SSL client key yum should use to connect
 147   to repos/remote sites Defaults to none.
 148 * `sslverify` - Either `true` or `false`. Determines if yum will verify SSL certificates/hosts. Defaults to `true`
 149 * `timeout` - Number of seconds to wait for a connection before timing
 150   out. Defaults to 30 seconds. This may be too short of a time for
 151   extremely overloaded sites.
 152
 153 ### yum_globalconfig
 154 This renders a template with global yum configuration parameters. The
 155 default recipe uses it to render `/etc/yum.conf`. It is flexible
 156 enough to be used in other scenarios, such as building RPMs in
 157 isolation by modifying `installroot`.
 158
 159 #### Example
 160 ``` ruby
 161 yum_globalconfig '/my/chroot/etc/yum.conf' do
 162   cachedir '/my/chroot/etc/yum.conf'
 163   keepcache 'yes'
 164   debuglevel '2'
 165   installroot '/my/chroot'
 166   action :create
 167 end
 168 ```
 169
 170 #### Parameters
 171 `yum_globalconfig` can take most of the same parameters as a
 172 `yum_repository`, plus more, too numerous to describe here. Below are
 173 a few of the more commonly used ones. For a complete list, please
 174 consult the `yum.conf` man page, found here:
 175 http://linux.die.net/man/5/yum.conf
 176
 177 * `cachedir` - Directory where yum should store its cache and db
 178   files. The default is '/var/cache/yum'.
 179 * `keepcache` - Either `true` or `false`. Determines whether or not
 180   yum keeps the cache of headers and packages after successful
 181   installation. Default is `true` (keep files)
 182 * `debuglevel` - Debug message output level. Practical range is 0-10.
 183   Default is '2'.
 184 * `exclude` - List of packages to exclude from updates or installs.
 185   This should be a space separated list. Shell globs using wildcards
 186   (eg. * and ?) are allowed.
 187 * `installonlypkgs` = List of package provides that should only ever
 188   be installed, never updated. Kernels in particular fall into this
 189   category. Defaults to kernel, kernel-bigmem, kernel-enterprise,
 190   kernel-smp, kernel-debug, kernel-unsupported, kernel-source,
 191   kernel-devel, kernel-PAE, kernel-PAE-debug.
 192 * `logfile` - Full directory and file name for where yum should write
 193   its log file.
 194 * `exactarch` -  Either `true` or `false`. Set to `true` to make 'yum update' only
 195   update the architectures of packages that you have installed. ie:
 196   with this enabled yum will not install an i686 package to update an
 197   x86_64 package. Default is `true`
 198 * `gpgcheck` - Either `true` or `false`. This tells yum whether or not
 199   it should perform a GPG signature check on the packages gotten from
 200   this repository.
 201
 202 Recipes
 203 -------
 204 * `default` - Configures `yum_globalconfig[/etc/yum.conf]` with values
 205   found in node attributes at `node['yum']['main']`
 206
 207 Attributes
 208 ----------
 209 The following attributes are set by default
 210
 211 ``` ruby
 212 default['yum']['main']['cachedir'] = '/var/cache/yum/$basearch/$releasever'
 213 default['yum']['main']['keepcache'] = false
 214 default['yum']['main']['debuglevel'] = nil
 215 default['yum']['main']['exclude'] = nil
 216 default['yum']['main']['logfile'] = '/var/log/yum.log'
 217 default['yum']['main']['exactarch'] = nil
 218 default['yum']['main']['obsoletes'] = nil
 219 default['yum']['main']['installonly_limit'] = nil
 220 default['yum']['main']['installonlypkgs'] = nil
 221 default['yum']['main']['installroot'] = nil
 222 ```
 223
 224 Related Cookbooks
 225 -----------------
 226 Recipes from older versions of this cookbook have been moved
 227 individual cookbooks. Recipes for managing platform yum configurations
 228 and installing specific repositories can be found in one (or more!) of
 229 the following cookbook.
 230
 231 * yum-centos
 232 * yum-fedora
 233 * yum-amazon
 234 * yum-epel
 235 * yum-elrepo
 236 * yum-repoforge
 237 * yum-ius
 238 * yum-percona
 239 * yum-pgdg
 240
 241 Usage
 242 -----
 243 Put `depends 'yum'` in your metadata.rb to gain access to the
 244 yum_repository resource.
 245
 246 License & Authors
 247 -----------------
 248 - Author:: Eric G. Wolfe
 249 - Author:: Matt Ray (<matt@getchef.com>)
 250 - Author:: Joshua Timberman (<joshua@getchef.com>)
 251 - Author:: Sean OMeara (<someara@getchef.com>)
 252
 253 ```text
 254 Copyright:: 2011 Eric G. Wolfe
 255 Copyright:: 2013 Chef
 256
 257 Licensed under the Apache License, Version 2.0 (the "License");
 258 you may not use this file except in compliance with the License.
 259 You may obtain a copy of the License at
 260
 261     http://www.apache.org/licenses/LICENSE-2.0
 262
 263 Unless required by applicable law or agreed to in writing, software
 264 distributed under the License is distributed on an "AS IS" BASIS,
 265 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 266 See the License for the specific language governing permissions and
 267 limitations under the License.
 268 ```