1 ========================
3 ========================
5 The ``cephx`` protocol is enabled by default. Cryptographic authentication has
6 some computational costs, though they should generally be quite low. If the
7 network environment connecting your client and server hosts is very safe and
8 you cannot afford authentication, you can turn it off. **This is not generally
11 .. note:: If you disable authentication, you are at risk of a man-in-the-middle
12 attack altering your client/server messages, which could lead to disastrous
15 For creating users, see `User Management`_. For details on the architecture
16 of Cephx, see `Architecture - High Availability Authentication`_.
22 There are two main scenarios for deploying a Ceph cluster, which impact
23 how you initially configure Cephx. Most first time Ceph users use
24 ``cephadm`` to create a cluster (easiest). For clusters using
25 other deployment tools (e.g., Chef, Juju, Puppet, etc.), you will need
26 to use the manual procedures or configure your deployment tool to
27 bootstrap your monitor(s).
32 When you deploy a cluster manually, you have to bootstrap the monitor manually
33 and create the ``client.admin`` user and keyring. To bootstrap monitors, follow
34 the steps in `Monitor Bootstrapping`_. The steps for monitor bootstrapping are
35 the logical steps you must perform when using third party deployment tools like
36 Chef, Puppet, Juju, etc.
39 Enabling/Disabling Cephx
40 ========================
42 Enabling Cephx requires that you have deployed keys for your monitors,
43 OSDs and metadata servers. If you are simply toggling Cephx on / off,
44 you do not have to repeat the bootstrapping procedures.
50 When ``cephx`` is enabled, Ceph will look for the keyring in the default search
51 path, which includes ``/etc/ceph/$cluster.$name.keyring``. You can override
52 this location by adding a ``keyring`` option in the ``[global]`` section of
53 your `Ceph configuration`_ file, but this is not recommended.
55 Execute the following procedures to enable ``cephx`` on a cluster with
56 authentication disabled. If you (or your deployment utility) have already
57 generated the keys, you may skip the steps related to generating keys.
59 #. Create a ``client.admin`` key, and save a copy of the key for your client
64 ceph auth get-or-create client.admin mon 'allow *' mds 'allow *' mgr 'allow *' osd 'allow *' -o /etc/ceph/ceph.client.admin.keyring
66 **Warning:** This will clobber any existing
67 ``/etc/ceph/client.admin.keyring`` file. Do not perform this step if a
68 deployment tool has already done it for you. Be careful!
70 #. Create a keyring for your monitor cluster and generate a monitor
75 ceph-authtool --create-keyring /tmp/ceph.mon.keyring --gen-key -n mon. --cap mon 'allow *'
77 #. Copy the monitor keyring into a ``ceph.mon.keyring`` file in every monitor's
78 ``mon data`` directory. For example, to copy it to ``mon.a`` in cluster ``ceph``,
83 cp /tmp/ceph.mon.keyring /var/lib/ceph/mon/ceph-a/keyring
85 #. Generate a secret key for every MGR, where ``{$id}`` is the MGR letter
89 ceph auth get-or-create mgr.{$id} mon 'allow profile mgr' mds 'allow *' osd 'allow *' -o /var/lib/ceph/mgr/ceph-{$id}/keyring
91 #. Generate a secret key for every OSD, where ``{$id}`` is the OSD number
95 ceph auth get-or-create osd.{$id} mon 'allow rwx' osd 'allow *' -o /var/lib/ceph/osd/ceph-{$id}/keyring
97 #. Generate a secret key for every MDS, where ``{$id}`` is the MDS letter
101 ceph auth get-or-create mds.{$id} mon 'allow rwx' osd 'allow *' mds 'allow *' mgr 'allow profile mds' -o /var/lib/ceph/mds/ceph-{$id}/keyring
103 #. Enable ``cephx`` authentication by setting the following options in the
104 ``[global]`` section of your `Ceph configuration`_ file
108 auth_cluster_required = cephx
109 auth_service_required = cephx
110 auth_client_required = cephx
113 #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details.
115 For details on bootstrapping a monitor manually, see `Manual Deployment`_.
122 The following procedure describes how to disable Cephx. If your cluster
123 environment is relatively safe, you can offset the computation expense of
124 running authentication. **We do not recommend it.** However, it may be easier
125 during setup and/or troubleshooting to temporarily disable authentication.
127 #. Disable ``cephx`` authentication by setting the following options in the
128 ``[global]`` section of your `Ceph configuration`_ file
132 auth_cluster_required = none
133 auth_service_required = none
134 auth_client_required = none
137 #. Start or restart the Ceph cluster. See `Operating a Cluster`_ for details.
140 Configuration Settings
141 ======================
147 .. confval:: auth_cluster_required
148 .. confval:: auth_service_required
149 .. confval:: auth_client_required
151 .. index:: keys; keyring
156 When you run Ceph with authentication enabled, ``ceph`` administrative commands
157 and Ceph Clients require authentication keys to access the Ceph Storage Cluster.
159 The most common way to provide these keys to the ``ceph`` administrative
160 commands and clients is to include a Ceph keyring under the ``/etc/ceph``
161 directory. For Octopus and later releases using ``cephadm``, the filename
162 is usually ``ceph.client.admin.keyring`` (or ``$cluster.client.admin.keyring``).
163 If you include the keyring under the ``/etc/ceph`` directory, you don't need to
164 specify a ``keyring`` entry in your Ceph configuration file.
166 We recommend copying the Ceph Storage Cluster's keyring file to nodes where you
167 will run administrative commands, because it contains the ``client.admin`` key.
169 To perform this step manually, execute the following::
171 sudo scp {user}@{ceph-cluster-host}:/etc/ceph/ceph.client.admin.keyring /etc/ceph/ceph.client.admin.keyring
173 .. tip:: Ensure the ``ceph.keyring`` file has appropriate permissions set
174 (e.g., ``chmod 644``) on your client machine.
176 You may specify the key itself in the Ceph configuration file using the ``key``
177 setting (not recommended), or a path to a keyfile using the ``keyfile`` setting.
180 :default: /etc/ceph/$cluster.$name.keyring,/etc/ceph/$cluster.keyring,/etc/ceph/keyring,/etc/ceph/keyring.bin
184 .. index:: signatures
189 Ceph performs a signature check that provides some limited protection
190 against messages being tampered with in flight (e.g., by a "man in the
193 Like other parts of Ceph authentication, Ceph provides fine-grained control so
194 you can enable/disable signatures for service messages between clients and
195 Ceph, and so you can enable/disable signatures for messages between Ceph daemons.
197 Note that even with signatures enabled data is not encrypted in
200 .. confval:: cephx_require_signatures
201 .. confval:: cephx_cluster_require_signatures
202 .. confval:: cephx_service_require_signatures
203 .. confval:: cephx_sign_messages
208 .. confval:: auth_service_ticket_ttl
210 .. _Monitor Bootstrapping: ../../../install/manual-deployment#monitor-bootstrapping
211 .. _Operating a Cluster: ../../operations/operating
212 .. _Manual Deployment: ../../../install/manual-deployment
213 .. _Ceph configuration: ../ceph-conf
214 .. _Architecture - High Availability Authentication: ../../../architecture#high-availability-authentication
215 .. _User Management: ../../operations/user-management