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