ceph/doc/install/get-packages.rst

   1 ==============
   2  Get Packages
   3 ==============
   4
   5 To install Ceph and other enabling software, you need to retrieve packages from
   6 the Ceph repository. Follow this guide to get packages; then, proceed to the
   7 `Install Ceph Object Storage`_.
   8
   9
  10 Getting Packages
  11 ================
  12
  13 There are two ways to get packages:
  14
  15 - **Add Repositories:** Adding repositories is the easiest way to get packages,
  16   because package management tools will retrieve the packages and all enabling
  17   software for you in most cases. However, to use this approach, each
  18   :term:`Ceph Node` in your cluster must have internet access.
  19
  20 - **Download Packages Manually:** Downloading packages manually is a convenient
  21   way to install Ceph if your environment does not allow a :term:`Ceph Node` to
  22   access the internet.
  23
  24
  25 Requirements
  26 ============
  27
  28 All Ceph deployments require Ceph packages (except for development). You should
  29 also add keys and recommended packages.
  30
  31 - **Keys: (Recommended)** Whether you add repositories or download packages
  32   manually, you should download keys to verify the packages. If you do not get
  33   the keys, you may encounter security warnings. There are two keys: one for
  34   releases (common) and one for development (programmers and QA only). Choose
  35   the key that suits your needs. See `Add Keys`_ for details.
  36
  37 - **Ceph: (Required)** All Ceph deployments require Ceph release packages,
  38   except for deployments that use development packages (development, QA, and
  39   bleeding edge deployments only). See `Add Ceph`_ for details.
  40
  41 - **Ceph Development: (Optional)** If you are developing for Ceph, testing Ceph
  42   development builds, or if you want features from the bleeding edge of Ceph
  43   development, you may get Ceph development packages. See
  44   `Add Ceph Development`_ for details.
  45
  46 - **Apache/FastCGI: (Optional)** If you are deploying a
  47   :term:`Ceph Object Storage` service, you must install Apache and FastCGI.
  48   Ceph provides Apache and FastCGI builds that are identical to those available
  49   from Apache, but with 100-continue support. If you want to enable
  50   :term:`Ceph Object Gateway` daemons with 100-continue support, you must
  51   retrieve Apache/FastCGI packages from the Ceph repository.
  52   See `Add Apache/FastCGI`_ for details.
  53
  54
  55 If you intend to download packages manually, see Section `Download Packages`_.
  56
  57
  58 Add Keys
  59 ========
  60
  61 Add a key to your system's list of trusted keys to avoid a security warning. For
  62 major releases (e.g., ``hammer``, ``jewel``) and development releases
  63 (``release-name-rc1``, ``release-name-rc2``), use the ``release.asc`` key. For
  64 development testing packages, use the ``autobuild.asc`` key (developers and
  65 QA).
  66
  67
  68 APT
  69 ---
  70
  71 To install the ``release.asc`` key, execute the following::
  72
  73         wget -q -O- 'https://download.ceph.com/keys/release.asc' | sudo apt-key add -
  74
  75
  76 To install the ``autobuild.asc`` key, execute the following
  77 (QA and developers only)::
  78
  79         wget -q -O- 'https://download.ceph.com/keys/autobuild.asc' | sudo apt-key add -
  80
  81
  82 RPM
  83 ---
  84
  85 To install the ``release.asc`` key, execute the following::
  86
  87         sudo rpm --import 'https://download.ceph.com/keys/release.asc'
  88
  89 To install the ``autobuild.asc`` key, execute the following
  90 (QA and developers only)::
  91
  92         sudo rpm --import 'https://download.ceph.com/keys/autobuild.asc'
  93
  94
  95 Add Ceph
  96 ========
  97
  98 Release repositories use the ``release.asc`` key to verify packages.
  99 To install Ceph packages with the Advanced Package Tool (APT) or
 100 Yellowdog Updater, Modified (YUM), you must add Ceph repositories.
 101
 102 You may find releases for Debian/Ubuntu (installed with APT) at::
 103
 104         https://download.ceph.com/debian-{release-name}
 105
 106 You may find releases for CentOS/RHEL and others (installed with YUM) at::
 107
 108         https://download.ceph.com/rpm-{release-name}
 109
 110 The major releases of Ceph are summarized at:
 111
 112     http://docs.ceph.com/docs/master/releases/
 113
 114 Every second major release is considered Long Term Stable (LTS). Critical
 115 bugfixes are backported to LTS releases until their retirement. Since retired
 116 releases are no longer maintained, we recommend that users upgrade their
 117 clusters regularly - preferably to the latest LTS release.
 118
 119 The most recent LTS release is Jewel (10.2.x).
 120
 121 .. tip:: For international users: There might be a mirror close to you where download Ceph from. For more information see: `Ceph Mirrors`_.
 122
 123 Debian Packages
 124 ---------------
 125
 126 Add a Ceph package repository to your system's list of APT sources. For newer
 127 versions of Debian/Ubuntu, call ``lsb_release -sc`` on the command line to
 128 get the short codename, and replace ``{codename}`` in the following command. ::
 129
 130         sudo apt-add-repository 'deb https://download.ceph.com/debian-jewel/ {codename} main'
 131
 132 For early Linux distributions, you may execute the following command::
 133
 134         echo deb https://download.ceph.com/debian-jewel/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 135
 136 For earlier Ceph releases, replace ``{release-name}`` with the name  with the
 137 name of the Ceph release. You may call ``lsb_release -sc`` on the command  line
 138 to get the short codename, and replace ``{codename}`` in the following command.
 139 ::
 140
 141         sudo apt-add-repository 'deb https://download.ceph.com/debian-{release-name}/ {codename} main'
 142
 143 For older Linux distributions, replace ``{release-name}`` with the name of the
 144 release::
 145
 146         echo deb https://download.ceph.com/debian-{release-name}/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 147
 148 Ceph on ARM processors requires Google's memory profiling tools (``google-perftools``).
 149 The Ceph repository should have a copy at
 150 https://download.ceph.com/packages/google-perftools/debian. ::
 151
 152         echo deb https://download.ceph.com/packages/google-perftools/debian  $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/google-perftools.list
 153
 154
 155 For development release packages, add our package repository to your system's
 156 list of APT sources.  See `the testing Debian repository`_ for a complete list
 157 of Debian and Ubuntu releases supported. ::
 158
 159         echo deb https://download.ceph.com/debian-testing/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 160
 161 .. tip:: For international users: There might be a mirror close to you where download Ceph from. For more information see: `Ceph Mirrors`_.
 162
 163 RPM Packages
 164 ------------
 165
 166 For major releases, you may add a Ceph entry to the ``/etc/yum.repos.d``
 167 directory. Create a ``ceph.repo`` file. In the example below, replace
 168 ``{ceph-release}`` with  a major release of Ceph (e.g., ``hammer``, ``jewel``,
 169 etc.) and ``{distro}`` with your Linux distribution (e.g., ``el7``, etc.).  You
 170 may view https://download.ceph.com/rpm-{ceph-release}/ directory to see which
 171 distributions Ceph supports. Some Ceph packages (e.g., EPEL) must take priority
 172 over standard packages, so you must ensure that you set
 173 ``priority=2``. ::
 174
 175         [ceph]
 176         name=Ceph packages for $basearch
 177         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/$basearch
 178         enabled=1
 179         priority=2
 180         gpgcheck=1
 181         gpgkey=https://download.ceph.com/keys/release.asc
 182
 183         [ceph-noarch]
 184         name=Ceph noarch packages
 185         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/noarch
 186         enabled=1
 187         priority=2
 188         gpgcheck=1
 189         gpgkey=https://download.ceph.com/keys/release.asc
 190
 191         [ceph-source]
 192         name=Ceph source packages
 193         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/SRPMS
 194         enabled=0
 195         priority=2
 196         gpgcheck=1
 197         gpgkey=https://download.ceph.com/keys/release.asc
 198
 199
 200 For development release packages, you may specify the repository
 201 for development releases instead. ::
 202
 203         [ceph]
 204         name=Ceph packages for $basearch/$releasever
 205         baseurl=https://download.ceph.com/rpm-testing/{distro}/$basearch
 206         enabled=1
 207         priority=2
 208         gpgcheck=1
 209         gpgkey=https://download.ceph.com/keys/release.asc
 210
 211         [ceph-noarch]
 212         name=Ceph noarch packages
 213         baseurl=https://download.ceph.com/rpm-testing/{distro}/noarch
 214         enabled=1
 215         priority=2
 216         gpgcheck=1
 217         gpgkey=https://download.ceph.com/keys/release.asc
 218
 219         [ceph-source]
 220         name=Ceph source packages
 221         baseurl=https://download.ceph.com/rpm-testing/{distro}/SRPMS
 222         enabled=0
 223         priority=2
 224         gpgcheck=1
 225         gpgkey=https://download.ceph.com/keys/release.asc
 226
 227
 228 For specific packages, you may retrieve them by specifically downloading the
 229 release package by name. Our development process generates a new release of Ceph
 230 every 3-4 weeks. These packages are faster-moving than the major releases.
 231 Development packages have new features integrated quickly, while still
 232 undergoing several weeks of QA prior to release.
 233
 234 The repository package installs the repository details on your local system for
 235 use with ``yum``. Replace ``{distro}`` with your Linux distribution, and
 236 ``{release}`` with the specific release of Ceph::
 237
 238     su -c 'rpm -Uvh https://download.ceph.com/rpms/{distro}/x86_64/ceph-{release}.el7.noarch.rpm'
 239
 240 You can download the RPMs directly from::
 241
 242      https://download.ceph.com/rpm-testing
 243
 244 .. tip:: For international users: There might be a mirror close to you where download Ceph from. For more information see: `Ceph Mirrors`_.
 245
 246
 247 Add Ceph Development
 248 ====================
 249
 250 Development repositories use the ``autobuild.asc`` key to verify packages.
 251 If you are developing Ceph and need to deploy and test specific Ceph branches,
 252 ensure that you remove repository entries for major releases first.
 253
 254
 255 Debian Packages
 256 ---------------
 257
 258 We automatically build Debian and Ubuntu packages for current
 259 development branches in the Ceph source code repository.  These
 260 packages are intended for developers and QA only.
 261
 262 Add our package repository to your system's list of APT sources, but
 263 replace ``{BRANCH}`` with the branch you'd like to use (e.g., chef-3,
 264 wip-hack, master).  See `the gitbuilder page`_ for a complete
 265 list of distributions we build. ::
 266
 267         echo deb http://gitbuilder.ceph.com/ceph-deb-$(lsb_release -sc)-x86_64-basic/ref/{BRANCH} $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 268
 269
 270 RPM Packages
 271 ------------
 272
 273 For current development branches, you may add a Ceph entry to the
 274 ``/etc/yum.repos.d`` directory. Create a ``ceph.repo`` file. In the example
 275 below, replace ``{distro}`` with your Linux distribution (e.g., ``el7``), and
 276 ``{branch}`` with the name of the branch you want to install. ::
 277
 278
 279         [ceph-source]
 280         name=Ceph source packages
 281         baseurl=http://gitbuilder.ceph.com/ceph-rpm-{distro}-x86_64-basic/ref/{branch}/SRPMS
 282         enabled=0
 283         gpgcheck=1
 284         gpgkey=https://download.ceph.com/keys/autobuild.asc
 285
 286
 287 You may view http://gitbuilder.ceph.com directory to see which distributions
 288 Ceph supports.
 289
 290
 291 Add Apache/FastCGI
 292 ==================
 293
 294 Ceph Object Gateway works with ordinary Apache and FastCGI libraries. However,
 295 Ceph builds Apache and FastCGI packages that support 100-continue. To use the
 296 Ceph Apache and FastCGI packages, add them to your repository.
 297
 298
 299 Debian Packages
 300 ---------------
 301
 302 Add our Apache and FastCGI packages to your system's list of APT sources if you intend to
 303 use 100-continue. ::
 304
 305         echo deb http://gitbuilder.ceph.com/apache2-deb-$(lsb_release -sc)-x86_64-basic/ref/master $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph-apache.list
 306         echo deb http://gitbuilder.ceph.com/libapache-mod-fastcgi-deb-$(lsb_release -sc)-x86_64-basic/ref/master $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph-fastcgi.list
 307
 308
 309 RPM Packages
 310 ------------
 311
 312 You may add a Ceph entry to the ``/etc/yum.repos.d`` directory. Create a
 313 ``ceph-apache.repo`` file. In the example below, replace ``{distro}`` with your
 314 Linux distribution (e.g., ``el7``).  You may view http://gitbuilder.ceph.com
 315 directory to see which distributions Ceph supports.
 316 ::
 317
 318
 319         [apache2-ceph-noarch]
 320         name=Apache noarch packages for Ceph
 321         baseurl=http://gitbuilder.ceph.com/apache2-rpm-{distro}-x86_64-basic/ref/master
 322         enabled=1
 323         priority=2
 324         gpgcheck=1
 325         gpgkey=https://download.ceph.com/keys/autobuild.asc
 326
 327         [apache2-ceph-source]
 328         name=Apache source packages for Ceph
 329         baseurl=http://gitbuilder.ceph.com/apache2-rpm-{distro}-x86_64-basic/ref/master
 330         enabled=0
 331         priority=2
 332         gpgcheck=1
 333         gpgkey=https://download.ceph.com/keys/autobuild.asc
 334
 335
 336 Repeat the forgoing process by creating a ``ceph-fastcgi.repo`` file. ::
 337
 338         [fastcgi-ceph-basearch]
 339         name=FastCGI basearch packages for Ceph
 340         baseurl=http://gitbuilder.ceph.com/mod_fastcgi-rpm-{distro}-x86_64-basic/ref/master
 341         enabled=1
 342         priority=2
 343         gpgcheck=1
 344         gpgkey=https://download.ceph.com/keys/autobuild.asc
 345
 346         [fastcgi-ceph-noarch]
 347         name=FastCGI noarch packages for Ceph
 348         baseurl=http://gitbuilder.ceph.com/mod_fastcgi-rpm-{distro}-x86_64-basic/ref/master
 349         enabled=1
 350         priority=2
 351         gpgcheck=1
 352         gpgkey=https://download.ceph.com/keys/autobuild.asc
 353
 354         [fastcgi-ceph-source]
 355         name=FastCGI source packages for Ceph
 356         baseurl=http://gitbuilder.ceph.com/mod_fastcgi-rpm-{distro}-x86_64-basic/ref/master
 357         enabled=0
 358         priority=2
 359         gpgcheck=1
 360         gpgkey=https://download.ceph.com/keys/autobuild.asc
 361
 362
 363 Download Packages
 364 =================
 365
 366 If you are attempting to install behind a firewall in an environment without internet
 367 access, you must retrieve the packages (mirrored with all the necessary dependencies)
 368 before attempting an install.
 369
 370 Debian Packages
 371 ---------------
 372
 373 Ceph requires additional additional third party libraries.
 374
 375 - libaio1
 376 - libsnappy1
 377 - libcurl3
 378 - curl
 379 - libgoogle-perftools4
 380 - google-perftools
 381 - libleveldb1
 382
 383
 384 The repository package installs the repository details on your local system for
 385 use with ``apt``. Replace ``{release}`` with the latest Ceph release. Replace
 386 ``{version}`` with the latest Ceph version number. Replace ``{distro}`` with
 387 your Linux distribution codename. Replace ``{arch}`` with the CPU architecture.
 388
 389 ::
 390
 391         wget -q https://download.ceph.com/debian-{release}/pool/main/c/ceph/ceph_{version}{distro}_{arch}.deb
 392
 393
 394 RPM Packages
 395 ------------
 396
 397 Ceph requires additional additional third party libraries.
 398 To add the EPEL repository, execute the following::
 399
 400    sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
 401
 402 Ceph requires the following packages:
 403
 404 - snappy
 405 - leveldb
 406 - gdisk
 407 - python-argparse
 408 - gperftools-libs
 409
 410
 411 Packages are currently built for the RHEL/CentOS7 (``el7``) platforms.  The
 412 repository package installs the repository details on your local system for use
 413 with ``yum``. Replace ``{distro}`` with your distribution. ::
 414
 415     su -c 'rpm -Uvh https://download.ceph.com/rpm-jewel/{distro}/noarch/ceph-{version}.{distro}.noarch.rpm'
 416
 417 For example, for CentOS 7  (``el7``)::
 418
 419     su -c 'rpm -Uvh https://download.ceph.com/rpm-jewel/el7/noarch/ceph-release-1-0.el7.noarch.rpm'
 420
 421 You can download the RPMs directly from::
 422
 423         https://download.ceph.com/rpm-jewel
 424
 425
 426 For earlier Ceph releases, replace ``{release-name}`` with the name
 427 with the name of the Ceph release. You may call ``lsb_release -sc`` on the command
 428 line to get the short codename. ::
 429
 430         su -c 'rpm -Uvh https://download.ceph.com/rpm-{release-name}/{distro}/noarch/ceph-{version}.{distro}.noarch.rpm'
 431
 432
 433
 434
 435 .. _Install Ceph Object Storage: ../install-storage-cluster
 436 .. _the testing Debian repository: https://download.ceph.com/debian-testing/dists
 437 .. _the gitbuilder page: http://gitbuilder.ceph.com
 438 .. _Ceph Mirrors: ../mirrors