network: override device names: suggest running update-initramfs

[pve-docs.git] / pve-storage-rbd.adoc

diff --git a/pve-storage-rbd.adoc b/pve-storage-rbd.adoc
index aa870edf5a4ca165514fd473832c1cc2a961f26d..5fe558a766b79d340743766f8da02d4d6377bb1d 100644 (file)
--- a/pve-storage-rbd.adoc
+++ b/pve-storage-rbd.adoc
@@ -1,3 +1,4 @@
+:fn-ceph-user-mgmt: footnote:cephusermgmt[Ceph user management {cephdocs-url}/rados/operations/user-management/]

 [[ceph_rados_block_devices]]
 Ceph RADOS Block Devices (RBD)
 ------------------------------
 [[ceph_rados_block_devices]]
 Ceph RADOS Block Devices (RBD)
 ------------------------------


@@ -8,7 +9,7 @@ endif::wiki[]
 
 Storage pool type: `rbd`
 
 
 Storage pool type: `rbd`
 

-http://ceph.com[Ceph] is a distributed object store and file system
+https://ceph.com[Ceph] is a distributed object store and file system

 designed to provide excellent performance, reliability and
 scalability. RADOS block devices implement a feature rich block level
 storage, and you get the following advantages:
 designed to provide excellent performance, reliability and
 scalability. RADOS block devices implement a feature rich block level
 storage, and you get the following advantages:


@@ -37,7 +38,7 @@ This backend supports the common storage properties `nodes`,
 monhost::
 
 List of monitor daemon IPs. Optional, only needed if Ceph is not running on the
 monhost::
 
 List of monitor daemon IPs. Optional, only needed if Ceph is not running on the

-PVE cluster.
+{pve} cluster.

 
 pool::
 
 
 pool::
 


@@ -45,7 +46,7 @@ Ceph pool name.
 
 username::
 
 
 username::
 

-RBD user ID. Optional, only needed if Ceph is not running on the PVE cluster.
+RBD user ID. Optional, only needed if Ceph is not running on the {pve} cluster.

 Note that only the user ID should be used. The "client." type prefix must be
 left out.
 
 Note that only the user ID should be used. The "client." type prefix must be
 left out.
 


@@ -69,22 +70,62 @@ TIP: You can use the `rbd` utility to do low-level management tasks.
 Authentication
 ~~~~~~~~~~~~~~
 
 Authentication
 ~~~~~~~~~~~~~~
 

-If you use `cephx` authentication, you need to copy the keyfile from your
-external Ceph cluster to a Proxmox VE host.
+NOTE: If Ceph is installed locally on the {pve} cluster, the following is done
+automatically when adding the storage.

 
 

-Create the directory `/etc/pve/priv/ceph` with
+If you use `cephx` authentication, which is enabled by default, you need to
+provide the keyring from the external Ceph cluster.

 
 

- mkdir /etc/pve/priv/ceph
+To configure the storage via the CLI, you first need to make the file
+containing the keyring available. One way is to copy the file from the external
+Ceph cluster directly to one of the {pve} nodes. The following example will
+copy it to the `/root` directory of the node on which we run it:

 
 

-Then copy the keyring
+----
+# scp <external cephserver>:/etc/ceph/ceph.client.admin.keyring /root/rbd.keyring
+----
+
+Then use the `pvesm` CLI tool to configure the external RBD storage, use the
+`--keyring` parameter, which needs to be a path to the keyring file that you
+copied.  For example:
+
+----
+# pvesm add rbd <name> --monhost "10.1.1.20 10.1.1.21 10.1.1.22" --content images --keyring /root/rbd.keyring
+----
+
+When configuring an external RBD storage via the GUI, you can copy and paste
+the keyring into the appropriate field.
+
+The keyring will be stored at
+
+----
+# /etc/pve/priv/ceph/<STORAGE_ID>.keyring
+----
+
+TIP: Creating a keyring with only the needed capabilities is recommend when
+connecting to an external cluster. For further information on Ceph user
+management, see the Ceph docs.footnoteref:[cephusermgmt,{cephdocs-url}/rados/operations/user-management/[Ceph User Management]]
+
+Ceph client configuration (optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Connecting to an external Ceph storage doesn't always allow setting
+client-specific options in the config DB on the external cluster. You can add a
+`ceph.conf` beside the Ceph keyring to change the Ceph client configuration for
+the storage.
+
+The ceph.conf needs to have the same name as the storage.
+
+----
+# /etc/pve/priv/ceph/<STORAGE_ID>.conf
+----

 
 

- scp <cephserver>:/etc/ceph/ceph.client.admin.keyring /etc/pve/priv/ceph/<STORAGE_ID>.keyring
+See the RBD configuration reference footnote:[RBD configuration reference
+{cephdocs-url}/rbd/rbd-config-ref/] for possible settings.

 
 

-The keyring must be named to match your `<STORAGE_ID>`. Copying the
-keyring generally requires root privileges.
+NOTE: Do not change these settings lightly. {PVE} is merging the
+<STORAGE_ID>.conf with the storage configuration.

 
 

-If Ceph is installed locally on the PVE cluster, this is done automatically by
-'pveceph' or in the GUI.

 
 Storage Features
 ~~~~~~~~~~~~~~~~
 
 Storage Features
 ~~~~~~~~~~~~~~~~