From a3f4d595f171f770ca72a0bfa814fa34561e3d0b Mon Sep 17 00:00:00 2001 From: John Wilkins Date: Wed, 30 May 2012 13:48:04 -0700 Subject: doc: Added pools and authentication. Signed-off-by: John Wilkins --- doc/config-cluster/authentication.rst | 122 ++++++++++++++++++++++++++++++++++ doc/config-cluster/index.rst | 2 + doc/config-cluster/pools.rst | 42 ++++++++++++ 3 files changed, 166 insertions(+) create mode 100644 doc/config-cluster/authentication.rst create mode 100644 doc/config-cluster/pools.rst (limited to 'doc') diff --git a/doc/config-cluster/authentication.rst b/doc/config-cluster/authentication.rst new file mode 100644 index 00000000000..98811024f37 --- /dev/null +++ b/doc/config-cluster/authentication.rst @@ -0,0 +1,122 @@ +================ + Authentication +================ + +Default users and pools are suitable for initial testing purposes. For test bed +and production environments, you should create users and assign pool access to +the users. For user management, see the `ceph-authtool`_ command for details. + +Enabling Authentication +----------------------- +In the ``[global]`` settings of your ``ceph.conf`` file, you must enable +authentication for your cluster. :: + + [global] + auth supported = cephx + +The valid values are ``cephx`` or ``none``. If you specify ``cephx``, you should +also specify the keyring's path. We recommend using the ``/etc/ceph`` directory. +Provide a ``keyring`` setting in ``ceph.conf`` like this:: + + [global] + auth supported = cephx + keyring = /etc/ceph/keyring.bin + +If there is no keyring in the path, generate one. + +Generating a Keyring +-------------------- +To generate a keyring in the default location, use the ``ceph-authtool`` and +specify the same path you specified in the ``[global]`` section of your +``ceph.conf`` file. For example:: + + sudo ceph-authtool --create-keyring /etc/ceph/keyring.bin + +Specify Keyrings for each Daemon +-------------------------------- +In your ``ceph.conf`` file under the daemon settings, you must also specify the +keyring directory and keyring name. The metavariable ``$name`` resolves +automatically. :: + + [mon] + keyring = /etc/ceph/keyring.$name + + [osd] + keyring = /etc/ceph/keyring.$name + + [mds] + keyring = /etc/ceph/keyring.$name + +Generate a Key +-------------- +Keys enable a specific user to access the monitor, metadata server and cluster +according to capabilities assigned to the key. To generate a key for a user, +you must specify specify a path to the keyring and a username. Replace +the ``{keyring/path}`` and ``{username}`` below. :: + + sudo ceph-authtool {keyring/path} -n client.{username} --gen-key + +For example:: + + sudo ceph-authtool /etc/ceph/keyring.bin -n client.whirlpool --gen-key + +.. note: User names are associated to user types, which include ``client`` + ``admin``, ``osd``, ``mon``, and ``mds``. In most cases, you will be + creating keys for ``client`` users. + +List Keys +--------- +To see a list of keys in a keyring, execute the following:: + + sudo ceph-authtool /etc/ceph/keyring.bin --list + +A keyring will display the user, the user's key, and the capabilities +associated to the user's key. + +Add Capabilities to a Key +------------------------- +To add capabilities to a key, you must specify the username, and a capability +for at least one of the monitor, metadata server and OSD. You may add more than +one capability when executing the ``ceph-authtool`` command. Replace the +``{usertype.username}``, ``{daemontype}`` and ``{capability}`` below:: + + sudo ceph-authtool -n {usertype.username} --cap {daemontype} {capability} + +For example:: + + ceph-authtool -n client.whirlpool --cap mds 'allow' --cap osd 'allow rw pool=swimmingpool' --cap mon 'allow r' /etc/ceph/keyring.bin + +Add the Keys to your Cluster +---------------------------- +Once you have generated keys and added capabilities to the keys, add each of the +keys to your cluster. Replace the ``{usertype.username}`` below. :: + + sudo ceph auth add {usertype.username} -i /etc/ceph/keyring.bin + +For example:: + + sudo ceph auth add client.whirlpool -i /etc/ceph/keyring.bin + +To list the keys in your cluster, execute the following:: + + sudo ceph auth list + +The ``client.admin`` Key +------------------------ +Each Ceph command you execute on the command line assumes that you are +the ``client.admin`` default user. When running Ceph with ``cephx`` enabled, +you need to have a ``client.admin`` key to run ``ceph`` commands. + +.. important: To continue to run Ceph commands on the command line with + ``cephx`` enabled, you need to create a key for the ``client.admin`` + user, and create a secret file under ``/etc/ceph``. + +:: + + sudo ceph-authtool /etc/ceph/keyring.bin -n client.admin --gen-key + sudo ceph-authtool -n client.admin --cap mds 'allow' --cap osd 'allow *' --cap mon 'allow *' /etc/ceph/keyring.bin + sudo ceph auth add client.admin -i /etc/ceph/keyring.bin + + +.. _ceph-authtool: http://ceph.com/docs/master/man/8/ceph-authtool/ + \ No newline at end of file diff --git a/doc/config-cluster/index.rst b/doc/config-cluster/index.rst index 271d89ba48a..1fbe0d8c485 100644 --- a/doc/config-cluster/index.rst +++ b/doc/config-cluster/index.rst @@ -28,3 +28,5 @@ instance (a single context). Deploy Config deploying-ceph-with-mkcephfs Deploy with Chef + Storage Pools + Authentication diff --git a/doc/config-cluster/pools.rst b/doc/config-cluster/pools.rst new file mode 100644 index 00000000000..156b22de5b4 --- /dev/null +++ b/doc/config-cluster/pools.rst @@ -0,0 +1,42 @@ +=============== + Storage Pools +=============== + +Ceph stores data in 'pools' within the OSDs. When you first deploy a cluster +without specifying pools, Ceph uses the default pools for storing data. +To organize data into pools, see the `rados`_ command for details. + +You can list, create, and remove pools. You can also view the pool utilization +statistics. + +List Pools +---------- +To list your cluster's pools, execute:: + + rados lspools + +The default pools include: + +- ``data`` +- ``metadata`` +- ``rbd`` + +Create a Pool +------------- +To create a pool, execute:: + + rados mkpool {pool_name} + +Remove a Pool +------------- +To remove a pool, execute:: + + rados rmpool {pool_name} + +Show Pool Stats +--------------- +To show a pool's utilization statistics, execute:: + + rados df + +.. _rados: http://ceph.com/docs/master/man/8/rados/ \ No newline at end of file -- cgit v1.2.1