From: Rishabh Dave Date: Tue, 7 Jan 2020 11:03:16 +0000 (+0530) Subject: doc/cephfs: rename doc/cephfs/kernel.rst & doc/cephfs/fuse.rst X-Git-Tag: v15.1.0~131^2~2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=f6ea1ca36f07f5399247c36fc16cef259849e9bb;p=ceph.git doc/cephfs: rename doc/cephfs/kernel.rst & doc/cephfs/fuse.rst Rename to mount-using-kernel.rst and mount-using-fuse.rst respectively so that it's easier to find them in doc/cephfs directory. Signed-off-by: Rishabh Dave --- diff --git a/doc/cephfs/fuse.rst b/doc/cephfs/fuse.rst deleted file mode 100644 index 1b1fe0c4fd31..000000000000 --- a/doc/cephfs/fuse.rst +++ /dev/null @@ -1,131 +0,0 @@ -======================== - Mount CephFS using FUSE -======================== - -Prerequisite ------------- -Before mounting CephFS, ensure that the client host (where CephFS has to be -mounted and used) has a copy of the Ceph configuration file (i.e. -``ceph.conf``) and a keyring of the CephX user that has CAPS for the Ceph MDS. -Both of these files must be present on the host where the Ceph MON resides. - -#. Generate a minimal conf for the client host. The conf file should be - placed at ``/etc/ceph``:: - - # on client host - mkdir /etc/ceph - ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf - - Alternatively, you may copy the conf file. But the method which generates - the minimal config is usually sufficient. For more information, see - :ref:`bootstrap-options`. - -#. Ensure that the conf has appropriate permissions:: - - chmod 644 /etc/ceph/ceph.conf - -#. Create the CephX user and get its secret key:: - - ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring - - In above command, replace ``cephfs`` with the name of your CephFS, ``foo`` - by the name you want for your CephX user and ``/`` by the path within your - CephFS for which you want to allow access to the client host and ``rw`` - stands for both read and write permissions. Alternatively, you may copy the - Ceph keyring from the MON host to client host at ``/etc/ceph`` but creating - a keyring specific to the client host is better. While creating a CephX - keyring/client, using same client name across multiple machines is perfectly - fine. - -.. note:: If you get 2 prompts for password while running above any of 2 above - command, run ``sudo ls`` (or any other trivial command with sudo) - immediately before these commands. - -#. Ensure that the keyring has appropriate permissions:: - - chmod 600 /etc/ceph/ceph.client.foo.keyring - -Synopsis --------- -In general, the command to mount CephFS via FUSE looks like this:: - - ceph-fuse {mountpoint} {options} - -Mounting CephFS ---------------- -To FUSE-mount the Ceph file system, use the ``ceph-fuse`` command:: - - mkdir /mnt/mycephfs - ceph-fuse --id foo /mnt/mycephfs - -Option ``-id`` passes the name of the CephX user whose keyring we intend to -use for mounting CephFS. In the above command, it's ``foo``. You can also use -``-n`` instead, although ``--id`` is evidently easier:: - - ceph-fuse -n client.foo /mnt/mycephfs - -In case the keyring is not present in standard locations, you may pass it -too:: - - ceph-fuse --id foo -k /path/to/keyring /mnt/mycephfs - -You may pass the MON's socket too, although this is not mandatory:: - - ceph-fuse --id foo -m 192.168.0.1:6789 /mnt/mycephfs - -You can also mount a specific directory within CephFS instead of mounting -root of CephFS on your local FS:: - - ceph-fuse --id foo -r /path/to/dir /mnt/mycephfs - -If you have more than one FS on your Ceph cluster, use the option -``--client_mds_namespace`` to mount the non-default FS:: - - ceph-fuse --id foo --client_mds_namespace mycephfs2 /mnt/mycephfs2 - -You may also add a ``client_mds_namespace`` setting to your ``ceph.conf`` - -Unmounting CephFS ------------------ - -Use ``umount`` to unmount CephFS like any other FS:: - - umount /mnt/mycephfs - -.. tip:: Ensure that you are not within the file system directories before - executing this command. - -Persistent Mounts ------------------ - -To mount CephFS as a file system in user space, add the following to ``/etc/fstab``:: - - #DEVICE PATH TYPE OPTIONS - none /mnt/mycephfs fuse.ceph ceph.id={user-ID}[,ceph.conf={path/to/conf.conf}],_netdev,defaults 0 0 - -For example:: - - none /mnt/mycephfs fuse.ceph ceph.id=myuser,_netdev,defaults 0 0 - none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.conf=/etc/ceph/foo.conf,_netdev,defaults 0 0 - -Ensure you use the ID (e.g., ``myuser``, not ``client.myuser``). You can pass -any valid ``ceph-fuse`` option to the command line this way. - -To mount a subdirectory of the CephFS, add the following to ``/etc/fstab``:: - - none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.client_mountpoint=/path/to/dir,_netdev,defaults 0 0 - -``ceph-fuse@.service`` and ``ceph-fuse.target`` systemd units are available. -As usual, these unit files declare the default dependencies and recommended -execution context for ``ceph-fuse``. After making the fstab entry shown above, -run following commands:: - - systemctl start ceph-fuse@/mnt/mycephfs.service - systemctl enable ceph-fuse.target - systemctl enable ceph-fuse@-mnt-mycephfs.service - -See :ref:`User Management ` for details on CephX user management and `ceph-fuse`_ -manual for more options it can take. For troubleshooting, see -:ref:`ceph_fuse_debugging`. - -.. _ceph-fuse: ../../man/8/ceph-fuse/#options diff --git a/doc/cephfs/index.rst b/doc/cephfs/index.rst index 221842b6a299..b3d550d0ea17 100644 --- a/doc/cephfs/index.rst +++ b/doc/cephfs/index.rst @@ -50,9 +50,11 @@ file system if the back-end deployment technology supports it (see as needed `. Finally, to mount CephFS on your client nodes, setup a :doc:`FUSE mount -` or :doc:`kernel mount `. Additionally, a -command-line shell utility is available for interactive access or scripting via -the :doc:`cephfs-shell `. +` or :doc:`kernel mount +`. + +Additionally, a command-line shell utility is available for interactive +access or scripting via the :doc:`cephfs-shell `. .. raw:: html @@ -103,8 +105,8 @@ Mounting CephFS Client Configuration Settings Client authentication - Mount CephFS using Kernel Driver - Mount CephFS using FUSE + Mount CephFS using Kernel Driver + Mount CephFS using FUSE Use the CephFS Shell Supported Features of Kernel Driver Manual: ceph-fuse <../../man/8/ceph-fuse> diff --git a/doc/cephfs/kernel.rst b/doc/cephfs/kernel.rst deleted file mode 100644 index 5a3caa10c97d..000000000000 --- a/doc/cephfs/kernel.rst +++ /dev/null @@ -1,136 +0,0 @@ -================================= - Mount CephFS using Kernel Driver -================================= - -Prerequisite ------------- -Before mounting CephFS, copy the Ceph configuration file and keyring for the -CephX user that has CAPS to mount MDS to the client host (where CephFS will be -mounted and used) from the host where Ceph Monitor resides. Please note that -it's possible to mount CephFS without conf and keyring, but in that case, you -would have to pass the MON's socket and CephX user's secret key manually to -every mount command you run. - -#. Generate a minimal conf file for the client host and place it at a - standard location:: - - # on client host - mkdir /etc/ceph - ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf - - Alternatively, you may copy the conf file. But the above method creates a - conf with minimum details which is better. - -#. Ensure that the conf file has appropriate permissions:: - - chmod 644 /etc/ceph/ceph.conf - -#. Create a CephX user and get its secret key:: - - ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring - - In above command, replace ``cephfs`` with the name of your CephFS, ``foo`` - by the name you want for CephX user and ``/`` by the path within your - CephFS for which you want to allow access to the client and ``rw`` stands - for, both, read and write permissions. Alternatively, you may copy the Ceph - keyring from the MON host to client host at ``/etc/ceph`` but creating a - keyring specific to the client host is better. - -.. note:: If you get 2 prompts for password while running above any of 2 above - command, run ``sudo ls`` (or any other trivial command with sudo) - immediately before these commands. - -#. Ensure that the keyring has appropriate permissions:: - - chmod 600 /etc/ceph/ceph.client.foo.keyring - -#. ``mount.ceph`` helper is installed with Ceph packages. If for some reason - installing these packages is not feasible and/or ``mount.ceph`` is not - present on the system, you can still mount CephFS, but you'll need to - explicitly pass the monitor addreses and CephX user keyring. To verify that - it is installed, do:: - - stat /sbin/mount.ceph - -Synopsis --------- -In general, the command to mount CephFS via kernel driver looks like this:: - - mount -t ceph {device-string}:{path-to-mounted} {mount-point} -o {key-value-args} {other-args} - -Mounting CephFS ---------------- -On Ceph clusters, CephX is enabled by default. Use ``mount`` command to -mount CephFS with the kernel driver:: - - mkdir /mnt/mycephfs - mount -t ceph :/ /mnt/mycephfs -o name=foo - -The key-value argument right after option ``-o`` is CephX credential; -``name`` is the username of the CephX user we are using to mount CephFS. The -default value for ``name`` is ``guest``. - -The kernel driver also requires MON's socket and the secret key for the CephX -user. In case of the above command, ``mount.ceph`` helper figures out these -details automatically by finding and reading Ceph conf file and keyring. In -case you don't have these files on the host where you're running mount -command, you can pass these details yourself too:: - - mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs -o name=foo,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== - -Passing a single MON socket in above command works too. A potential problem -with the command above is that the secret key is left in your shell's command -history. To prevent that you can copy the secret key inside a file and pass -the file by using the option ``secretfile`` instead of ``secret``:: - - mount -t ceph :/ /mnt/mycephfs -o name=foo,secretfile=/etc/ceph/foo.secret - -Ensure the permissions on the secret key file are appropriate (preferably, -``600``). - -In case CephX is disabled, you can omit ``-o`` and the list of key-value -arguments that follow it:: - - mount -t ceph :/ /mnt/mycephfs - -To mount a subtree of the CephFS root, append the path to the device string:: - - mount -t ceph :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs - -If you have more than one file system on your Ceph cluster, you can mount the -non-default FS on your local FS as follows:: - - mount -t ceph :/ /mnt/mycephfs2 -o name=fs,mds_namespace=mycephfs2 - -Unmounting CephFS ------------------ -To unmount the Ceph file system, use the ``umount`` command as usual:: - - umount /mnt/mycephfs - -.. tip:: Ensure that you are not within the file system directories before - executing this command. - -Persistent Mounts ------------------- - -To mount CephFS in your file systems table as a kernel driver, add the -following to ``/etc/fstab``:: - - [{ipaddress}:{port}]:/ {mount}/{mountpoint} ceph [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] - -For example:: - - :/ /mnt/ceph ceph name=admin,noatime,_netdev 0 2 - -The default for the ``name=`` parameter is ``guest``. If the ``secret`` or -``secretfile`` options are not specified then the mount helper will attempt to -find a secret for the given ``name`` in one of the configured keyrings. - -See `User Management`_ for details on CephX user management and mount.ceph_ -manual for more options it can take. For troubleshooting, see -:ref:`kernel_mount_debugging`. - -.. _fstab: ../fstab/#kernel-driver -.. _User Management: ../../rados/operations/user-management/ -.. _mount.ceph: ../../man/8/mount.ceph/ diff --git a/doc/cephfs/mount-using-fuse.rst b/doc/cephfs/mount-using-fuse.rst new file mode 100644 index 000000000000..1b1fe0c4fd31 --- /dev/null +++ b/doc/cephfs/mount-using-fuse.rst @@ -0,0 +1,131 @@ +======================== + Mount CephFS using FUSE +======================== + +Prerequisite +------------ +Before mounting CephFS, ensure that the client host (where CephFS has to be +mounted and used) has a copy of the Ceph configuration file (i.e. +``ceph.conf``) and a keyring of the CephX user that has CAPS for the Ceph MDS. +Both of these files must be present on the host where the Ceph MON resides. + +#. Generate a minimal conf for the client host. The conf file should be + placed at ``/etc/ceph``:: + + # on client host + mkdir /etc/ceph + ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf + + Alternatively, you may copy the conf file. But the method which generates + the minimal config is usually sufficient. For more information, see + :ref:`bootstrap-options`. + +#. Ensure that the conf has appropriate permissions:: + + chmod 644 /etc/ceph/ceph.conf + +#. Create the CephX user and get its secret key:: + + ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring + + In above command, replace ``cephfs`` with the name of your CephFS, ``foo`` + by the name you want for your CephX user and ``/`` by the path within your + CephFS for which you want to allow access to the client host and ``rw`` + stands for both read and write permissions. Alternatively, you may copy the + Ceph keyring from the MON host to client host at ``/etc/ceph`` but creating + a keyring specific to the client host is better. While creating a CephX + keyring/client, using same client name across multiple machines is perfectly + fine. + +.. note:: If you get 2 prompts for password while running above any of 2 above + command, run ``sudo ls`` (or any other trivial command with sudo) + immediately before these commands. + +#. Ensure that the keyring has appropriate permissions:: + + chmod 600 /etc/ceph/ceph.client.foo.keyring + +Synopsis +-------- +In general, the command to mount CephFS via FUSE looks like this:: + + ceph-fuse {mountpoint} {options} + +Mounting CephFS +--------------- +To FUSE-mount the Ceph file system, use the ``ceph-fuse`` command:: + + mkdir /mnt/mycephfs + ceph-fuse --id foo /mnt/mycephfs + +Option ``-id`` passes the name of the CephX user whose keyring we intend to +use for mounting CephFS. In the above command, it's ``foo``. You can also use +``-n`` instead, although ``--id`` is evidently easier:: + + ceph-fuse -n client.foo /mnt/mycephfs + +In case the keyring is not present in standard locations, you may pass it +too:: + + ceph-fuse --id foo -k /path/to/keyring /mnt/mycephfs + +You may pass the MON's socket too, although this is not mandatory:: + + ceph-fuse --id foo -m 192.168.0.1:6789 /mnt/mycephfs + +You can also mount a specific directory within CephFS instead of mounting +root of CephFS on your local FS:: + + ceph-fuse --id foo -r /path/to/dir /mnt/mycephfs + +If you have more than one FS on your Ceph cluster, use the option +``--client_mds_namespace`` to mount the non-default FS:: + + ceph-fuse --id foo --client_mds_namespace mycephfs2 /mnt/mycephfs2 + +You may also add a ``client_mds_namespace`` setting to your ``ceph.conf`` + +Unmounting CephFS +----------------- + +Use ``umount`` to unmount CephFS like any other FS:: + + umount /mnt/mycephfs + +.. tip:: Ensure that you are not within the file system directories before + executing this command. + +Persistent Mounts +----------------- + +To mount CephFS as a file system in user space, add the following to ``/etc/fstab``:: + + #DEVICE PATH TYPE OPTIONS + none /mnt/mycephfs fuse.ceph ceph.id={user-ID}[,ceph.conf={path/to/conf.conf}],_netdev,defaults 0 0 + +For example:: + + none /mnt/mycephfs fuse.ceph ceph.id=myuser,_netdev,defaults 0 0 + none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.conf=/etc/ceph/foo.conf,_netdev,defaults 0 0 + +Ensure you use the ID (e.g., ``myuser``, not ``client.myuser``). You can pass +any valid ``ceph-fuse`` option to the command line this way. + +To mount a subdirectory of the CephFS, add the following to ``/etc/fstab``:: + + none /mnt/mycephfs fuse.ceph ceph.id=myuser,ceph.client_mountpoint=/path/to/dir,_netdev,defaults 0 0 + +``ceph-fuse@.service`` and ``ceph-fuse.target`` systemd units are available. +As usual, these unit files declare the default dependencies and recommended +execution context for ``ceph-fuse``. After making the fstab entry shown above, +run following commands:: + + systemctl start ceph-fuse@/mnt/mycephfs.service + systemctl enable ceph-fuse.target + systemctl enable ceph-fuse@-mnt-mycephfs.service + +See :ref:`User Management ` for details on CephX user management and `ceph-fuse`_ +manual for more options it can take. For troubleshooting, see +:ref:`ceph_fuse_debugging`. + +.. _ceph-fuse: ../../man/8/ceph-fuse/#options diff --git a/doc/cephfs/mount-using-kernel-driver.rst b/doc/cephfs/mount-using-kernel-driver.rst new file mode 100644 index 000000000000..5a3caa10c97d --- /dev/null +++ b/doc/cephfs/mount-using-kernel-driver.rst @@ -0,0 +1,136 @@ +================================= + Mount CephFS using Kernel Driver +================================= + +Prerequisite +------------ +Before mounting CephFS, copy the Ceph configuration file and keyring for the +CephX user that has CAPS to mount MDS to the client host (where CephFS will be +mounted and used) from the host where Ceph Monitor resides. Please note that +it's possible to mount CephFS without conf and keyring, but in that case, you +would have to pass the MON's socket and CephX user's secret key manually to +every mount command you run. + +#. Generate a minimal conf file for the client host and place it at a + standard location:: + + # on client host + mkdir /etc/ceph + ssh {user}@{mon-host} "sudo ceph config generate-minimal-conf" | sudo tee /etc/ceph/ceph.conf + + Alternatively, you may copy the conf file. But the above method creates a + conf with minimum details which is better. + +#. Ensure that the conf file has appropriate permissions:: + + chmod 644 /etc/ceph/ceph.conf + +#. Create a CephX user and get its secret key:: + + ssh {user}@{mon-host} "sudo ceph fs authorize cephfs client.foo / rw" | sudo tee /etc/ceph/ceph.client.foo.keyring + + In above command, replace ``cephfs`` with the name of your CephFS, ``foo`` + by the name you want for CephX user and ``/`` by the path within your + CephFS for which you want to allow access to the client and ``rw`` stands + for, both, read and write permissions. Alternatively, you may copy the Ceph + keyring from the MON host to client host at ``/etc/ceph`` but creating a + keyring specific to the client host is better. + +.. note:: If you get 2 prompts for password while running above any of 2 above + command, run ``sudo ls`` (or any other trivial command with sudo) + immediately before these commands. + +#. Ensure that the keyring has appropriate permissions:: + + chmod 600 /etc/ceph/ceph.client.foo.keyring + +#. ``mount.ceph`` helper is installed with Ceph packages. If for some reason + installing these packages is not feasible and/or ``mount.ceph`` is not + present on the system, you can still mount CephFS, but you'll need to + explicitly pass the monitor addreses and CephX user keyring. To verify that + it is installed, do:: + + stat /sbin/mount.ceph + +Synopsis +-------- +In general, the command to mount CephFS via kernel driver looks like this:: + + mount -t ceph {device-string}:{path-to-mounted} {mount-point} -o {key-value-args} {other-args} + +Mounting CephFS +--------------- +On Ceph clusters, CephX is enabled by default. Use ``mount`` command to +mount CephFS with the kernel driver:: + + mkdir /mnt/mycephfs + mount -t ceph :/ /mnt/mycephfs -o name=foo + +The key-value argument right after option ``-o`` is CephX credential; +``name`` is the username of the CephX user we are using to mount CephFS. The +default value for ``name`` is ``guest``. + +The kernel driver also requires MON's socket and the secret key for the CephX +user. In case of the above command, ``mount.ceph`` helper figures out these +details automatically by finding and reading Ceph conf file and keyring. In +case you don't have these files on the host where you're running mount +command, you can pass these details yourself too:: + + mount -t ceph 192.168.0.1:6789,192.168.0.2:6789:/ /mnt/mycephfs -o name=foo,secret=AQATSKdNGBnwLhAAnNDKnH65FmVKpXZJVasUeQ== + +Passing a single MON socket in above command works too. A potential problem +with the command above is that the secret key is left in your shell's command +history. To prevent that you can copy the secret key inside a file and pass +the file by using the option ``secretfile`` instead of ``secret``:: + + mount -t ceph :/ /mnt/mycephfs -o name=foo,secretfile=/etc/ceph/foo.secret + +Ensure the permissions on the secret key file are appropriate (preferably, +``600``). + +In case CephX is disabled, you can omit ``-o`` and the list of key-value +arguments that follow it:: + + mount -t ceph :/ /mnt/mycephfs + +To mount a subtree of the CephFS root, append the path to the device string:: + + mount -t ceph :/subvolume/dir1/dir2 /mnt/mycephfs -o name=fs + +If you have more than one file system on your Ceph cluster, you can mount the +non-default FS on your local FS as follows:: + + mount -t ceph :/ /mnt/mycephfs2 -o name=fs,mds_namespace=mycephfs2 + +Unmounting CephFS +----------------- +To unmount the Ceph file system, use the ``umount`` command as usual:: + + umount /mnt/mycephfs + +.. tip:: Ensure that you are not within the file system directories before + executing this command. + +Persistent Mounts +------------------ + +To mount CephFS in your file systems table as a kernel driver, add the +following to ``/etc/fstab``:: + + [{ipaddress}:{port}]:/ {mount}/{mountpoint} ceph [name=username,secret=secretkey|secretfile=/path/to/secretfile],[{mount.options}] + +For example:: + + :/ /mnt/ceph ceph name=admin,noatime,_netdev 0 2 + +The default for the ``name=`` parameter is ``guest``. If the ``secret`` or +``secretfile`` options are not specified then the mount helper will attempt to +find a secret for the given ``name`` in one of the configured keyrings. + +See `User Management`_ for details on CephX user management and mount.ceph_ +manual for more options it can take. For troubleshooting, see +:ref:`kernel_mount_debugging`. + +.. _fstab: ../fstab/#kernel-driver +.. _User Management: ../../rados/operations/user-management/ +.. _mount.ceph: ../../man/8/mount.ceph/