From: Dmitry Kozlyuk <dkozlyuk@nvidia.com>
To: <dev@dpdk.org>
Cc: <stable@dpdk.org>, Anatoly Burakov <anatoly.burakov@intel.com>
Subject: [PATCH v3 3/5] doc: give specific instructions for running as non-root
Date: Fri, 24 Jun 2022 11:48:15 +0300 [thread overview]
Message-ID: <20220624084817.63145-4-dkozlyuk@nvidia.com> (raw)
In-Reply-To: <20220624084817.63145-1-dkozlyuk@nvidia.com>
The guide to run DPDK applications as non-root in Linux
did not provide specific instructions to configure the required access
and did not explain why each bit is needed.
The latter is important because running as non-root
is one of the ways to tighten security and grant minimal permissions.
Cc: stable@dpdk.org
Signed-off-by: Dmitry Kozlyuk <dkozlyuk@nvidia.com>
---
doc/guides/linux_gsg/enable_func.rst | 89 +++++++++++++------
.../prog_guide/env_abstraction_layer.rst | 2 +
2 files changed, 64 insertions(+), 27 deletions(-)
diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
index 1df3ab0255..0b57417c94 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -13,13 +13,63 @@ Enabling Additional Functionality
Running DPDK Applications Without Root Privileges
-------------------------------------------------
-In order to run DPDK as non-root, the following Linux filesystem objects'
-permissions should be adjusted to ensure that the Linux account being used to
-run the DPDK application has access to them:
+The following sections describe generic requirements and configuration
+for running DPDK applications as non-root.
+There may be additional requirements documented for some drivers.
-* All directories which serve as hugepage mount points, for example, ``/dev/hugepages``
+Hugepages
+~~~~~~~~~
-* If the HPET is to be used, ``/dev/hpet``
+Hugepages must be reserved as root before running the application as non-root,
+for example::
+
+ sudo dpdk-hugepages.py --reserve 1G
+
+If multi-process is not required, running with ``--in-memory``
+bypasses the need to access hugepage mount point and files within it.
+Otherwise, hugepage directory must be made accessible
+for writing to the unprivileged user.
+A good way for managing multiple applications using hugepages
+is to mount the filesystem with group permissions
+and add a supplementary group to each application or container.
+
+One option is to use the script provided by this project::
+
+ export HUGEDIR=$HOME/huge-1G
+ mkdir -p $HUGEDIR
+ sudo dpdk-hugepages.py --mount --directory $HUGEDIR --owner `id -u`:`id -g`
+
+In production environment, the OS can manage mount points
+(`systemd example <https://github.com/systemd/systemd/blob/main/units/dev-hugepages.mount>`_).
+
+The ``hugetlb`` filesystem has additional options to guarantee or limit
+the amount of memory that is possible to allocate using the mount point.
+Refer to the `documentation <https://www.kernel.org/doc/Documentation/vm/hugetlbpage.txt>`_.
+
+If the driver requires using physical addresses (PA),
+the executable file must be granted additional capabilities:
+
+* ``SYS_ADMIN`` to read ``/proc/self/pagemaps``
+* ``IPC_LOCK`` to lock hugepages in memory
+
+.. code-block:: console
+
+ setcap cap_ipc_lock,cap_sys_admin+ep <executable>
+
+If physical addresses are not accessible,
+the following message will appear during EAL initialization::
+
+ EAL: rte_mem_virt2phy(): cannot open /proc/self/pagemap: Permission denied
+
+It is harmless in case PA are not needed.
+
+.. note::
+
+ Using ``vfio-pci`` kernel driver, if applicable, can eliminate the need
+ for physical addresses and therefore reduce the permission requirements.
+
+Resource Limits
+~~~~~~~~~~~~~~~
When running as non-root user, there may be some additional resource limits
that are imposed by the system. Specifically, the following resource limits may
@@ -34,8 +84,13 @@ need to be adjusted in order to ensure normal DPDK operation:
The above limits can usually be adjusted by editing
``/etc/security/limits.conf`` file, and rebooting.
-Additionally, depending on which kernel driver is in use, the relevant
-resources also should be accessible by the user running the DPDK application.
+See `Hugepage Mapping <hugepage_mapping>`_
+section to learn how these limits affect EAL.
+
+Device Control
+~~~~~~~~~~~~~~
+
+If the HPET is to be used, ``/dev/hpet`` permissions must be adjusted.
For ``vfio-pci`` kernel driver, the following Linux file system objects'
permissions should be adjusted:
@@ -45,26 +100,6 @@ permissions should be adjusted:
* The directories under ``/dev/vfio`` that correspond to IOMMU group numbers of
devices intended to be used by DPDK, for example, ``/dev/vfio/50``
-.. note::
-
- The instructions below will allow running DPDK with ``igb_uio`` or
- ``uio_pci_generic`` drivers as non-root with older Linux kernel versions.
- However, since version 4.0, the kernel does not allow unprivileged processes
- to read the physical address information from the pagemaps file, making it
- impossible for those processes to be used by non-privileged users. In such
- cases, using the VFIO driver is recommended.
-
-For ``igb_uio`` or ``uio_pci_generic`` kernel drivers, the following Linux file
-system objects' permissions should be adjusted:
-
-* The userspace-io device files in ``/dev``, for example, ``/dev/uio0``, ``/dev/uio1``, and so on
-
-* The userspace-io sysfs config and resource files, for example for ``uio0``::
-
- /sys/class/uio/uio0/device/config
- /sys/class/uio/uio0/device/resource*
-
-
Power Management and Power Saving Functionality
-----------------------------------------------
diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst
index 5f0748fba1..70fa099d30 100644
--- a/doc/guides/prog_guide/env_abstraction_layer.rst
+++ b/doc/guides/prog_guide/env_abstraction_layer.rst
@@ -228,6 +228,8 @@ Normally, these options do not need to be changed.
can later be mapped into that preallocated VA space (if dynamic memory mode
is enabled), and can optionally be mapped into it at startup.
+.. _hugepage_mapping:
+
Hugepage Mapping
^^^^^^^^^^^^^^^^
--
2.25.1
next prev parent reply other threads:[~2022-06-24 8:48 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <20220607234949.2311884-1-dkozlyuk@nvidia.com>
2022-06-07 23:49 ` [PATCH 3/4] " Dmitry Kozlyuk
2022-06-08 0:03 ` Stephen Hemminger
2022-06-07 23:49 ` [PATCH 4/4] doc: update instructions for running as non-root for MLX5 Dmitry Kozlyuk
2022-06-08 0:13 ` Stephen Hemminger
2022-06-17 11:26 ` Dmitry Kozlyuk
[not found] ` <20220617112508.3823291-1-dkozlyuk@nvidia.com>
2022-06-17 11:25 ` [PATCH v2 3/4] doc: give specific instructions for running as non-root Dmitry Kozlyuk
2022-06-17 16:38 ` Bruce Richardson
2022-06-20 6:10 ` Dmitry Kozlyuk
2022-06-20 8:37 ` Bruce Richardson
2022-06-24 8:49 ` Dmitry Kozlyuk
2022-06-17 11:25 ` [PATCH v2 4/4] doc: update instructions for running as non-root for MLX5 Dmitry Kozlyuk
[not found] ` <20220624084817.63145-1-dkozlyuk@nvidia.com>
2022-06-24 8:48 ` Dmitry Kozlyuk [this message]
2022-06-24 9:09 ` [PATCH v3 3/5] doc: give specific instructions for running as non-root Bruce Richardson
2022-06-24 8:48 ` [PATCH v3 4/5] doc: update instructions for running as non-root for MLX5 Dmitry Kozlyuk
[not found] ` <20220624131956.75160-1-dkozlyuk@nvidia.com>
2022-06-24 13:19 ` [PATCH v4 3/5] doc: give specific instructions for running as non-root Dmitry Kozlyuk
2022-06-24 13:19 ` [PATCH v4 4/5] doc: update instructions for running as non-root for MLX5 Dmitry Kozlyuk
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220624084817.63145-4-dkozlyuk@nvidia.com \
--to=dkozlyuk@nvidia.com \
--cc=anatoly.burakov@intel.com \
--cc=dev@dpdk.org \
--cc=stable@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).