ceph/doc/install/get-packages.rst

   1 .. _packages:
   2
   3 ==============
   4  Get Packages
   5 ==============
   6
   7 To install Ceph and other enabling software, you need to retrieve packages from
   8 the Ceph repository.
   9
  10 There are three ways to get packages:
  11
  12 - **Cephadm:** Cephadm can configure your Ceph repositories for you
  13   based on a release name or a specific Ceph version.  Each
  14   :term:`Ceph Node` in your cluster must have internet access.
  15
  16 - **Configure Repositories Manually:** You can manually configure your
  17   package management tool to retrieve Ceph packages and all enabling
  18   software.  Each :term:`Ceph Node` in your cluster must have internet
  19   access.
  20
  21 - **Download Packages Manually:** Downloading packages manually is a convenient
  22   way to install Ceph if your environment does not allow a :term:`Ceph Node` to
  23   access the internet.
  24
  25 Install packages with cephadm
  26 =============================
  27
  28 #. Download the cephadm script::
  29
  30     curl --silent --remote-name --location https://github.com/ceph/ceph/raw/octopus/src/cephadm/cephadm
  31     chmod +x cephadm
  32
  33 #. Configure the Ceph repository based on the release name::
  34
  35      ./cephadm add-repo --release nautilus
  36
  37    For Octopus (15.2.0) and later releases, you can also specify a specific
  38    version::
  39
  40      ./cephadm add-repo --version 15.2.1
  41
  42    For development packages, you can specify a specific branch name::
  43
  44      ./cephadm add-repo --dev my-branch
  45
  46 #. Install the appropriate packages.  You can install them using your
  47    package management tool (e.g., APT, Yum) directly, or you can also
  48    use the cephadm wrapper.  For example::
  49
  50      ./cephadm install ceph-common
  51
  52
  53 Configure Repositories Manually
  54 ===============================
  55
  56 All Ceph deployments require Ceph packages (except for development). You should
  57 also add keys and recommended packages.
  58
  59 - **Keys: (Recommended)** Whether you add repositories or download packages
  60   manually, you should download keys to verify the packages. If you do not get
  61   the keys, you may encounter security warnings.
  62
  63 - **Ceph: (Required)** All Ceph deployments require Ceph release packages,
  64   except for deployments that use development packages (development, QA, and
  65   bleeding edge deployments only).
  66
  67 - **Ceph Development: (Optional)** If you are developing for Ceph, testing Ceph
  68   development builds, or if you want features from the bleeding edge of Ceph
  69   development, you may get Ceph development packages.
  70
  71
  72
  73 Add Keys
  74 --------
  75
  76 Add a key to your system's list of trusted keys to avoid a security warning. For
  77 major releases (e.g., ``luminous``, ``mimic``, ``nautilus``) and development releases
  78 (``release-name-rc1``, ``release-name-rc2``), use the ``release.asc`` key.
  79
  80
  81 APT
  82 ~~~
  83
  84 To install the ``release.asc`` key, execute the following::
  85
  86         wget -q -O- 'https://download.ceph.com/keys/release.asc' | sudo apt-key add -
  87
  88
  89 RPM
  90 ~~~
  91
  92 To install the ``release.asc`` key, execute the following::
  93
  94         sudo rpm --import 'https://download.ceph.com/keys/release.asc'
  95
  96 Ceph Release Packages
  97 ---------------------
  98
  99 Release repositories use the ``release.asc`` key to verify packages.
 100 To install Ceph packages with the Advanced Package Tool (APT) or
 101 Yellowdog Updater, Modified (YUM), you must add Ceph repositories.
 102
 103 You may find releases for Debian/Ubuntu (installed with APT) at::
 104
 105         https://download.ceph.com/debian-{release-name}
 106
 107 You may find releases for CentOS/RHEL and others (installed with YUM) at::
 108
 109         https://download.ceph.com/rpm-{release-name}
 110
 111 For Octopus and later releases, you can also configure a repository for a
 112 specific version ``x.y.z``.  For Debian/Ubuntu packages::
 113
 114   https://download.ceph.com/debian-{version}
 115
 116 For RPMs::
 117
 118   https://download.ceph.com/rpm-{version}
 119
 120 The major releases of Ceph are summarized at: :ref:`ceph-releases-general`
 121
 122 .. tip:: For non-US users: There might be a mirror close to you where
 123          to download Ceph from. For more information see: `Ceph Mirrors`_.
 124
 125 Debian Packages
 126 ~~~~~~~~~~~~~~~
 127
 128 Add a Ceph package repository to your system's list of APT sources. For newer
 129 versions of Debian/Ubuntu, call ``lsb_release -sc`` on the command line to
 130 get the short codename, and replace ``{codename}`` in the following command. ::
 131
 132         sudo apt-add-repository 'deb https://download.ceph.com/debian-luminous/ {codename} main'
 133
 134 For early Linux distributions, you may execute the following command::
 135
 136         echo deb https://download.ceph.com/debian-luminous/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 137
 138 For earlier Ceph releases, replace ``{release-name}`` with the name  with the
 139 name of the Ceph release. You may call ``lsb_release -sc`` on the command  line
 140 to get the short codename, and replace ``{codename}`` in the following command.
 141
 142 ::
 143
 144         sudo apt-add-repository 'deb https://download.ceph.com/debian-{release-name}/ {codename} main'
 145
 146 For older Linux distributions, replace ``{release-name}`` with the name of the
 147 release::
 148
 149         echo deb https://download.ceph.com/debian-{release-name}/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 150
 151 For development release packages, add our package repository to your system's
 152 list of APT sources.  See `the testing Debian repository`_ for a complete list
 153 of Debian and Ubuntu releases supported. ::
 154
 155         echo deb https://download.ceph.com/debian-testing/ $(lsb_release -sc) main | sudo tee /etc/apt/sources.list.d/ceph.list
 156
 157 .. tip:: For non-US users: There might be a mirror close to you where
 158          to download Ceph from. For more information see: `Ceph Mirrors`_.
 159
 160
 161 RPM Packages
 162 ~~~~~~~~~~~~
 163
 164 RHEL
 165 ^^^^
 166
 167 For major releases, you may add a Ceph entry to the ``/etc/yum.repos.d``
 168 directory. Create a ``ceph.repo`` file. In the example below, replace
 169 ``{ceph-release}`` with  a major release of Ceph (e.g., ``luminous``, ``mimic``, ``nautilus``,
 170 etc.) and ``{distro}`` with your Linux distribution (e.g., ``el7``, etc.).  You
 171 may view https://download.ceph.com/rpm-{ceph-release}/ directory to see which
 172 distributions Ceph supports. Some Ceph packages (e.g., EPEL) must take priority
 173 over standard packages, so you must ensure that you set
 174 ``priority=2``. ::
 175
 176         [ceph]
 177         name=Ceph packages for $basearch
 178         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/$basearch
 179         enabled=1
 180         priority=2
 181         gpgcheck=1
 182         gpgkey=https://download.ceph.com/keys/release.asc
 183
 184         [ceph-noarch]
 185         name=Ceph noarch packages
 186         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/noarch
 187         enabled=1
 188         priority=2
 189         gpgcheck=1
 190         gpgkey=https://download.ceph.com/keys/release.asc
 191
 192         [ceph-source]
 193         name=Ceph source packages
 194         baseurl=https://download.ceph.com/rpm-{ceph-release}/{distro}/SRPMS
 195         enabled=0
 196         priority=2
 197         gpgcheck=1
 198         gpgkey=https://download.ceph.com/keys/release.asc
 199
 200
 201 For specific packages, you may retrieve them by downloading the release package
 202 by name. Our development process generates a new release of Ceph every 3-4
 203 weeks. These packages are faster-moving than the major releases.  Development
 204 packages have new features integrated quickly, while still undergoing several
 205 weeks of QA prior to release.
 206
 207 The repository package installs the repository details on your local system for
 208 use with ``yum``. Replace ``{distro}`` with your Linux distribution, and
 209 ``{release}`` with the specific release of Ceph::
 210
 211     su -c 'rpm -Uvh https://download.ceph.com/rpms/{distro}/x86_64/ceph-{release}.el7.noarch.rpm'
 212
 213 You can download the RPMs directly from::
 214
 215      https://download.ceph.com/rpm-testing
 216
 217 .. tip:: For non-US users: There might be a mirror close to you where
 218          to download Ceph from. For more information see: `Ceph Mirrors`_.
 219
 220 openSUSE Leap 15.1
 221 ^^^^^^^^^^^^^^^^^^
 222
 223 You need to add the Ceph package repository to your list of zypper sources. This can be done with the following command ::
 224
 225     zypper ar https://download.opensuse.org/repositories/filesystems:/ceph/openSUSE_Leap_15.1/filesystems:ceph.repo
 226
 227 openSUSE Tumbleweed
 228 ^^^^^^^^^^^^^^^^^^^
 229
 230 The newest major release of Ceph is already available through the normal Tumbleweed repositories.
 231 There's no need to add another package repository manually.
 232
 233
 234 Ceph Development Packages
 235 -------------------------
 236
 237 If you are developing Ceph and need to deploy and test specific Ceph branches,
 238 ensure that you remove repository entries for major releases first.
 239
 240
 241 DEB Packages
 242 ~~~~~~~~~~~~
 243
 244 We automatically build Ubuntu packages for current development branches in the
 245 Ceph source code repository.  These packages are intended for developers and QA
 246 only.
 247
 248 Add the package repository to your system's list of APT sources, but
 249 replace ``{BRANCH}`` with the branch you'd like to use (e.g.,
 250 wip-hack, master).  See `the shaman page`_ for a complete
 251 list of distributions we build. ::
 252
 253     curl -L https://shaman.ceph.com/api/repos/ceph/{BRANCH}/latest/ubuntu/$(lsb_release -sc)/repo/ | sudo tee /etc/apt/sources.list.d/shaman.list
 254
 255 .. note:: If the repository is not ready an HTTP 504 will be returned
 256
 257 The use of ``latest`` in the url, means it will figure out which is the last
 258 commit that has been built. Alternatively, a specific sha1 can be specified.
 259 For Ubuntu Xenial and the master branch of Ceph, it would look like::
 260
 261     curl -L https://shaman.ceph.com/api/repos/ceph/master/53e772a45fdf2d211c0c383106a66e1feedec8fd/ubuntu/xenial/repo/ | sudo tee /etc/apt/sources.list.d/shaman.list
 262
 263
 264 .. warning:: Development repositories are no longer available after two weeks.
 265
 266 RPM Packages
 267 ~~~~~~~~~~~~
 268
 269 For current development branches, you may add a Ceph entry to the
 270 ``/etc/yum.repos.d`` directory. The `the shaman page`_ can be used to retrieve the full details
 271 of a repo file. It can be retrieved via an HTTP request, for example::
 272
 273     curl -L https://shaman.ceph.com/api/repos/ceph/{BRANCH}/latest/centos/7/repo/ | sudo tee /etc/yum.repos.d/shaman.repo
 274
 275 The use of ``latest`` in the url, means it will figure out which is the last
 276 commit that has been built. Alternatively, a specific sha1 can be specified.
 277 For CentOS 7 and the master branch of Ceph, it would look like::
 278
 279     curl -L https://shaman.ceph.com/api/repos/ceph/master/53e772a45fdf2d211c0c383106a66e1feedec8fd/centos/7/repo/ | sudo tee /etc/apt/sources.list.d/shaman.list
 280
 281
 282 .. warning:: Development repositories are no longer available after two weeks.
 283
 284 .. note:: If the repository is not ready an HTTP 504 will be returned
 285
 286 Download Packages Manually
 287 --------------------------
 288
 289 If you are attempting to install behind a firewall in an environment without internet
 290 access, you must retrieve the packages (mirrored with all the necessary dependencies)
 291 before attempting an install.
 292
 293 Debian Packages
 294 ~~~~~~~~~~~~~~~
 295
 296 Ceph requires additional third party libraries.
 297
 298 - libaio1
 299 - libsnappy1
 300 - libcurl3
 301 - curl
 302 - libgoogle-perftools4
 303 - google-perftools
 304 - libleveldb1
 305
 306
 307 The repository package installs the repository details on your local system for
 308 use with ``apt``. Replace ``{release}`` with the latest Ceph release. Replace
 309 ``{version}`` with the latest Ceph version number. Replace ``{distro}`` with
 310 your Linux distribution codename. Replace ``{arch}`` with the CPU architecture.
 311
 312 ::
 313
 314         wget -q https://download.ceph.com/debian-{release}/pool/main/c/ceph/ceph_{version}{distro}_{arch}.deb
 315
 316
 317 RPM Packages
 318 ~~~~~~~~~~~~
 319
 320 Ceph requires additional additional third party libraries.
 321 To add the EPEL repository, execute the following::
 322
 323    sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
 324
 325 Ceph requires the following packages:
 326
 327 - snappy
 328 - leveldb
 329 - gdisk
 330 - python-argparse
 331 - gperftools-libs
 332
 333
 334 Packages are currently built for the RHEL/CentOS7 (``el7``) platforms.  The
 335 repository package installs the repository details on your local system for use
 336 with ``yum``. Replace ``{distro}`` with your distribution. ::
 337
 338     su -c 'rpm -Uvh https://download.ceph.com/rpm-luminous/{distro}/noarch/ceph-{version}.{distro}.noarch.rpm'
 339
 340 For example, for CentOS 7  (``el7``)::
 341
 342     su -c 'rpm -Uvh https://download.ceph.com/rpm-luminous/el7/noarch/ceph-release-1-0.el7.noarch.rpm'
 343
 344 You can download the RPMs directly from::
 345
 346         https://download.ceph.com/rpm-luminous
 347
 348
 349 For earlier Ceph releases, replace ``{release-name}`` with the name
 350 with the name of the Ceph release. You may call ``lsb_release -sc`` on the command
 351 line to get the short codename. ::
 352
 353         su -c 'rpm -Uvh https://download.ceph.com/rpm-{release-name}/{distro}/noarch/ceph-{version}.{distro}.noarch.rpm'
 354
 355
 356
 357 .. _the testing Debian repository: https://download.ceph.com/debian-testing/dists
 358 .. _the shaman page: https://shaman.ceph.com
 359 .. _Ceph Mirrors: ../mirrors