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: :doc:`/releases`.
 111
 112 Every second major release is considered Long Term Stable (LTS). Critical
 113 bugfixes are backported to LTS releases until their retirement. Since retired
 114 releases are no longer maintained, we recommend that users upgrade their
 115 clusters regularly - preferably to the latest LTS release.
 116
 117 The most recent LTS release is Jewel (10.2.x).
 118
 119 .. tip:: For international users: There might be a mirror close to you where download Ceph from. For more information see: `Ceph Mirrors`_.
 120
 121 Debian Packages
 122 ---------------
 123
 124 Add a Ceph package repository to your system's list of APT sources. For newer
 125 versions of Debian/Ubuntu, call ``lsb_release -sc`` on the command line to
 126 get the short codename, and replace ``{codename}`` in the following command. ::
 127
 128         sudo apt-add-repository 'deb https://download.ceph.com/debian-jewel/ {codename} main'
 129
 130 For early Linux distributions, you may execute the following command::
 131
 132         echo deb https://download.ceph.com/debian-jewel/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 133
 134 For earlier Ceph releases, replace ``{release-name}`` with the name  with the
 135 name of the Ceph release. You may call ``lsb_release -sc`` on the command  line
 136 to get the short codename, and replace ``{codename}`` in the following command.
 137 ::
 138
 139         sudo apt-add-repository 'deb https://download.ceph.com/debian-{release-name}/ {codename} main'
 140
 141 For older Linux distributions, replace ``{release-name}`` with the name of the
 142 release::
 143
 144         echo deb https://download.ceph.com/debian-{release-name}/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 145
 146 Ceph on ARM processors requires Google's memory profiling tools (``google-perftools``).
 147 The Ceph repository should have a copy at
 148 https://download.ceph.com/packages/google-perftools/debian. ::
 149
 150         echo deb https://download.ceph.com/packages/google-perftools/debian  $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/google-perftools.list
 151
 152
 153 For development release packages, add our package repository to your system's
 154 list of APT sources.  See `the testing Debian repository`_ for a complete list
 155 of Debian and Ubuntu releases supported. ::
 156
 157         echo deb https://download.ceph.com/debian-testing/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 158
 159 .. tip:: For international users: There might be a mirror close to you where download Ceph from. For more information see: `Ceph Mirrors`_.
 160
 161 RPM Packages
 162 ------------
 163
 164 For major releases, you may add a Ceph entry to the ``/etc/yum.repos.d``
 165 directory. Create a ``ceph.repo`` file. In the example below, replace
 166 ``{ceph-release}`` with  a major release of Ceph (e.g., ``hammer``, ``jewel``,
 167 etc.) and ``{distro}`` with your Linux distribution (e.g., ``el7``, etc.).  You
 168 may view https://download.ceph.com/rpm-{ceph-release}/ directory to see which
 169 distributions Ceph supports. Some Ceph packages (e.g., EPEL) must take priority
 170 over standard packages, so you must ensure that you set
 171 ``priority=2``. ::
 172
 173         [ceph]
 174         name=Ceph packages for $basearch
 175         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/$basearch
 176         enabled=1
 177         priority=2
 178         gpgcheck=1
 179         gpgkey=https://download.ceph.com/keys/release.asc
 180
 181         [ceph-noarch]
 182         name=Ceph noarch packages
 183         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/noarch
 184         enabled=1
 185         priority=2
 186         gpgcheck=1
 187         gpgkey=https://download.ceph.com/keys/release.asc
 188
 189         [ceph-source]
 190         name=Ceph source packages
 191         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/SRPMS
 192         enabled=0
 193         priority=2
 194         gpgcheck=1
 195         gpgkey=https://download.ceph.com/keys/release.asc
 196
 197
 198 For development release packages, you may specify the repository
 199 for development releases instead. ::
 200
 201         [ceph]
 202         name=Ceph packages for $basearch/$releasever
 203         baseurl=https://download.ceph.com/rpm-testing/{distro}/$basearch
 204         enabled=1
 205         priority=2
 206         gpgcheck=1
 207         gpgkey=https://download.ceph.com/keys/release.asc
 208
 209         [ceph-noarch]
 210         name=Ceph noarch packages
 211         baseurl=https://download.ceph.com/rpm-testing/{distro}/noarch
 212         enabled=1
 213         priority=2
 214         gpgcheck=1
 215         gpgkey=https://download.ceph.com/keys/release.asc
 216
 217         [ceph-source]
 218         name=Ceph source packages
 219         baseurl=https://download.ceph.com/rpm-testing/{distro}/SRPMS
 220         enabled=0
 221         priority=2
 222         gpgcheck=1
 223         gpgkey=https://download.ceph.com/keys/release.asc
 224
 225
 226 For specific packages, you may retrieve them by specifically downloading the
 227 release package by name. Our development process generates a new release of Ceph
 228 every 3-4 weeks. These packages are faster-moving than the major releases.
 229 Development packages have new features integrated quickly, while still
 230 undergoing several weeks of QA prior to release.
 231
 232 The repository package installs the repository details on your local system for
 233 use with ``yum``. Replace ``{distro}`` with your Linux distribution, and
 234 ``{release}`` with the specific release of Ceph::
 235
 236     su -c 'rpm -Uvh https://download.ceph.com/rpms/{distro}/x86_64/ceph-{release}.el7.noarch.rpm'
 237
 238 You can download the RPMs directly from::
 239
 240      https://download.ceph.com/rpm-testing
 241
 242 .. tip:: For international users: There might be a mirror close to you where download Ceph from. For more information see: `Ceph Mirrors`_.
 243
 244
 245 Add Ceph Development
 246 ====================
 247
 248 Development repositories use the ``autobuild.asc`` key to verify packages.
 249 If you are developing Ceph and need to deploy and test specific Ceph branches,
 250 ensure that you remove repository entries for major releases first.
 251
 252
 253 Debian Packages
 254 ---------------
 255
 256 We automatically build Debian and Ubuntu packages for current
 257 development branches in the Ceph source code repository.  These
 258 packages are intended for developers and QA only.
 259
 260 Add our package repository to your system's list of APT sources, but
 261 replace ``{BRANCH}`` with the branch you'd like to use (e.g., chef-3,
 262 wip-hack, master).  See `the gitbuilder page`_ for a complete
 263 list of distributions we build. ::
 264
 265         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
 266
 267
 268 RPM Packages
 269 ------------
 270
 271 For current development branches, you may add a Ceph entry to the
 272 ``/etc/yum.repos.d`` directory. Create a ``ceph.repo`` file. In the example
 273 below, replace ``{distro}`` with your Linux distribution (e.g., ``el7``), and
 274 ``{branch}`` with the name of the branch you want to install. ::
 275
 276
 277         [ceph-source]
 278         name=Ceph source packages
 279         baseurl=http://gitbuilder.ceph.com/ceph-rpm-{distro}-x86_64-basic/ref/{branch}/SRPMS
 280         enabled=0
 281         gpgcheck=1
 282         gpgkey=https://download.ceph.com/keys/autobuild.asc
 283
 284
 285 You may view http://gitbuilder.ceph.com directory to see which distributions
 286 Ceph supports.
 287
 288
 289 Add Apache/FastCGI
 290 ==================
 291
 292 Ceph Object Gateway works with ordinary Apache and FastCGI libraries. However,
 293 Ceph builds Apache and FastCGI packages that support 100-continue. To use the
 294 Ceph Apache and FastCGI packages, add them to your repository.
 295
 296
 297 Debian Packages
 298 ---------------
 299
 300 Add our Apache and FastCGI packages to your system's list of APT sources if you intend to
 301 use 100-continue. ::
 302
 303         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
 304         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
 305
 306
 307 RPM Packages
 308 ------------
 309
 310 You may add a Ceph entry to the ``/etc/yum.repos.d`` directory. Create a
 311 ``ceph-apache.repo`` file. In the example below, replace ``{distro}`` with your
 312 Linux distribution (e.g., ``el7``).  You may view http://gitbuilder.ceph.com
 313 directory to see which distributions Ceph supports.
 314 ::
 315
 316
 317         [apache2-ceph-noarch]
 318         name=Apache noarch packages for Ceph
 319         baseurl=http://gitbuilder.ceph.com/apache2-rpm-{distro}-x86_64-basic/ref/master
 320         enabled=1
 321         priority=2
 322         gpgcheck=1
 323         gpgkey=https://download.ceph.com/keys/autobuild.asc
 324
 325         [apache2-ceph-source]
 326         name=Apache source packages for Ceph
 327         baseurl=http://gitbuilder.ceph.com/apache2-rpm-{distro}-x86_64-basic/ref/master
 328         enabled=0
 329         priority=2
 330         gpgcheck=1
 331         gpgkey=https://download.ceph.com/keys/autobuild.asc
 332
 333
 334 Repeat the forgoing process by creating a ``ceph-fastcgi.repo`` file. ::
 335
 336         [fastcgi-ceph-basearch]
 337         name=FastCGI basearch packages for Ceph
 338         baseurl=http://gitbuilder.ceph.com/mod_fastcgi-rpm-{distro}-x86_64-basic/ref/master
 339         enabled=1
 340         priority=2
 341         gpgcheck=1
 342         gpgkey=https://download.ceph.com/keys/autobuild.asc
 343
 344         [fastcgi-ceph-noarch]
 345         name=FastCGI noarch packages for Ceph
 346         baseurl=http://gitbuilder.ceph.com/mod_fastcgi-rpm-{distro}-x86_64-basic/ref/master
 347         enabled=1
 348         priority=2
 349         gpgcheck=1
 350         gpgkey=https://download.ceph.com/keys/autobuild.asc
 351
 352         [fastcgi-ceph-source]
 353         name=FastCGI source packages for Ceph
 354         baseurl=http://gitbuilder.ceph.com/mod_fastcgi-rpm-{distro}-x86_64-basic/ref/master
 355         enabled=0
 356         priority=2
 357         gpgcheck=1
 358         gpgkey=https://download.ceph.com/keys/autobuild.asc
 359
 360
 361 Download Packages
 362 =================
 363
 364 If you are attempting to install behind a firewall in an environment without internet
 365 access, you must retrieve the packages (mirrored with all the necessary dependencies)
 366 before attempting an install.
 367
 368 Debian Packages
 369 ---------------
 370
 371 Ceph requires additional additional third party libraries.
 372
 373 - libaio1
 374 - libsnappy1
 375 - libcurl3
 376 - curl
 377 - libgoogle-perftools4
 378 - google-perftools
 379 - libleveldb1
 380
 381
 382 The repository package installs the repository details on your local system for
 383 use with ``apt``. Replace ``{release}`` with the latest Ceph release. Replace
 384 ``{version}`` with the latest Ceph version number. Replace ``{distro}`` with
 385 your Linux distribution codename. Replace ``{arch}`` with the CPU architecture.
 386
 387 ::
 388
 389         wget -q https://download.ceph.com/debian-{release}/pool/main/c/ceph/ceph_{version}{distro}_{arch}.deb
 390
 391
 392 RPM Packages
 393 ------------
 394
 395 Ceph requires additional additional third party libraries.
 396 To add the EPEL repository, execute the following::
 397
 398    sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
 399
 400 Ceph requires the following packages:
 401
 402 - snappy
 403 - leveldb
 404 - gdisk
 405 - python-argparse
 406 - gperftools-libs
 407
 408
 409 Packages are currently built for the RHEL/CentOS7 (``el7``) platforms.  The
 410 repository package installs the repository details on your local system for use
 411 with ``yum``. Replace ``{distro}`` with your distribution. ::
 412
 413     su -c 'rpm -Uvh https://download.ceph.com/rpm-jewel/{distro}/noarch/ceph-{version}.{distro}.noarch.rpm'
 414
 415 For example, for CentOS 7  (``el7``)::
 416
 417     su -c 'rpm -Uvh https://download.ceph.com/rpm-jewel/el7/noarch/ceph-release-1-0.el7.noarch.rpm'
 418
 419 You can download the RPMs directly from::
 420
 421         https://download.ceph.com/rpm-jewel
 422
 423
 424 For earlier Ceph releases, replace ``{release-name}`` with the name
 425 with the name of the Ceph release. You may call ``lsb_release -sc`` on the command
 426 line to get the short codename. ::
 427
 428         su -c 'rpm -Uvh https://download.ceph.com/rpm-{release-name}/{distro}/noarch/ceph-{version}.{distro}.noarch.rpm'
 429
 430
 431
 432
 433 .. _Install Ceph Object Storage: ../install-storage-cluster
 434 .. _the testing Debian repository: https://download.ceph.com/debian-testing/dists
 435 .. _the gitbuilder page: http://gitbuilder.ceph.com
 436 .. _Ceph Mirrors: ../mirrors