From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 76605A0548;
Wed, 8 Jun 2022 01:50:26 +0200 (CEST)
Received: from [217.70.189.124] (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id F3F5C4281C;
Wed, 8 Jun 2022 01:50:13 +0200 (CEST)
Received: from NAM12-DM6-obe.outbound.protection.outlook.com
(mail-dm6nam12on2064.outbound.protection.outlook.com [40.107.243.64])
by mails.dpdk.org (Postfix) with ESMTP id EA9D24282C;
Wed, 8 Jun 2022 01:50:11 +0200 (CEST)
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none;
b=GIhoXC9n+DYo8yhd9BgeMujzLe3spZpu6WsqN55TkVTEBLQ8ckidWbttDyAMSykLgwN4Mv1i99lua2tjktkO16OgAlNe3r1cpp/xoD74FGT9rQT0T2fwcV0rHCp5NKaJfC3YyrRakuAw/l+t2Av/5tsmonfGWhNiLUJoF2JW6vewz5oyXbusjGEy6r1nv8VaXiz3xbddfDGwSVmYpCjkAFwejNMOEC/iUNk+lt3h/XSSIHqawvCUFSfhFe+7wMaawivvQJuUEXL2/+el1OkujwkFkdMlHhpgi3x7iei9jmVYzEz58KeQr+9KN/vWQR1gIR4sh18C4IIWpVvcSn3bIw==
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com;
s=arcselector9901;
h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1;
bh=wHCqUhzeCVapD2LVSejVk6W2BRC+YjLSZmu7rAZEwdU=;
b=Pg7T+tfGUKk9VtYQn9rp8PcOliolt2B2Sj3TSW1rxmyB8hiK9Ib+U4GhIhGSGekG+87LzlxD2zvYy7qKr/dngSnAgzy7ivcl+B37zIExvSbL1PSXSnB9a68zEKrzMwSzUA1O+6Q8xcYQWnDtbwJDwOEJ2jitVtc9M9Z9Mik9TP97BYMRvm1h8jKE0P8Es5neKoSmJn/ZKkxKAa0UDVWdA8RlbM2Td+okLJsesrmlhC2h2m7sUMEP4yg2NCB4yKPH7Yr/nkXOeZ8r8qx4t530D2rJ5crlt7oqgbiyGsRAwLou0LlN4s9FaE5hg6nLXPsvfAeZXAQ2iy7hf1M9z7Ev+A==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is
12.22.5.235) smtp.rcpttodomain=dpdk.org smtp.mailfrom=nvidia.com; dmarc=pass
(p=reject sp=reject pct=100) action=none header.from=nvidia.com; dkim=none
(message not signed); arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=Nvidia.com;
s=selector2;
h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck;
bh=wHCqUhzeCVapD2LVSejVk6W2BRC+YjLSZmu7rAZEwdU=;
b=R5jMfUb2C2WryYpLysaxh6eYTcFcr3oJixYNLxCNk1tNs9uQU8HXff5TmROJEICBgcMazmHTNa/oCdUaRgQrO2+4RCsyCSELvxgs//wqmbpT8BnIB4csXca06HWT+LOCDKUBM/6l2mDcNpW594yY5nw+XBN43swbu3oUJLkfkXeIWiJq/w7pwgL1pj8VJ/dYRx2WJVFCdJkXOaNBzPoA++hK1cxBe6uYBHInaJCMEqQcWgf8n0cda7YsfKuHln3AxruuoFs3smvZHywIonCuKuPz0c/H2k81yvndsqR5vqlOPCxTcZpI6yGk6EJirQysssru8IH0NqOKnanr7JRNjg==
Received: from BN8PR04CA0061.namprd04.prod.outlook.com (2603:10b6:408:d4::35)
by BL1PR12MB5239.namprd12.prod.outlook.com (2603:10b6:208:315::24)
with Microsoft SMTP Server (version=TLS1_2,
cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5332.12; Tue, 7 Jun
2022 23:50:06 +0000
Received: from BN8NAM11FT031.eop-nam11.prod.protection.outlook.com
(2603:10b6:408:d4:cafe::3b) by BN8PR04CA0061.outlook.office365.com
(2603:10b6:408:d4::35) with Microsoft SMTP Server (version=TLS1_2,
cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5314.16 via Frontend
Transport; Tue, 7 Jun 2022 23:50:05 +0000
X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 12.22.5.235)
smtp.mailfrom=nvidia.com; dkim=none (message not signed)
header.d=none;dmarc=pass action=none header.from=nvidia.com;
Received-SPF: Pass (protection.outlook.com: domain of nvidia.com designates
12.22.5.235 as permitted sender) receiver=protection.outlook.com;
client-ip=12.22.5.235; helo=mail.nvidia.com; pr=C
Received: from mail.nvidia.com (12.22.5.235) by
BN8NAM11FT031.mail.protection.outlook.com (10.13.177.25) with Microsoft SMTP
Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384) id
15.20.5314.12 via Frontend Transport; Tue, 7 Jun 2022 23:50:05 +0000
Received: from drhqmail202.nvidia.com (10.126.190.181) by
DRHQMAIL107.nvidia.com (10.27.9.16) with Microsoft SMTP Server (TLS) id
15.0.1497.32; Tue, 7 Jun 2022 23:50:02 +0000
Received: from drhqmail203.nvidia.com (10.126.190.182) by
drhqmail202.nvidia.com (10.126.190.181) with Microsoft SMTP Server
(version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id
15.2.986.22; Tue, 7 Jun 2022 16:50:02 -0700
Received: from nvidia.com (10.127.8.11) by mail.nvidia.com (10.126.190.182)
with Microsoft SMTP Server id 15.2.986.22 via Frontend Transport; Tue, 7 Jun
2022 16:50:01 -0700
From: Dmitry Kozlyuk <dkozlyuk@nvidia.com>
To: <dev@dpdk.org>
CC: Thomas Monjalon <thomas@monjalon.net>, <stable@dpdk.org>, Anatoly Burakov
<anatoly.burakov@intel.com>
Subject: [PATCH 3/4] doc: give specific instructions for running as non-root
Date: Wed, 8 Jun 2022 02:49:48 +0300
Message-ID: <20220607234949.2311884-4-dkozlyuk@nvidia.com>
X-Mailer: git-send-email 2.25.1
In-Reply-To: <20220607234949.2311884-1-dkozlyuk@nvidia.com>
References: <20220607234949.2311884-1-dkozlyuk@nvidia.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
X-EOPAttributedMessage: 0
X-MS-PublicTrafficType: Email
X-MS-Office365-Filtering-Correlation-Id: 287b4185-2611-4d0f-de6b-08da48e0729d
X-MS-TrafficTypeDiagnostic: BL1PR12MB5239:EE_
X-LD-Processed: 43083d15-7273-40c1-b7db-39efd9ccc17a,ExtAddr
X-Microsoft-Antispam-PRVS: <BL1PR12MB523955A01208B4F8CA243D64B9A59@BL1PR12MB5239.namprd12.prod.outlook.com>
X-MS-Exchange-SenderADCheck: 1
X-MS-Exchange-AntiSpam-Relay: 0
X-Microsoft-Antispam: BCL:0;
X-Microsoft-Antispam-Message-Info: cKH2UZp0V3DoUhOaTbJ3qnvtz6JpXoxHN3bfyNWzKqLV+/d/+sCph48xg37t1ZpfykVfyfk8G+qKWlpmcm3gh5JNsuFrsXrTaTNVsy+009+M74MriC2+SCVFudpgfAdVCKLNqFKiup2GT/NhWUEltShD/ndctG0OCvzdL8y1/ypwH2FYONdnMdLYiXSg9F67fSFZrFCHPnZ7+sIQ0WMSsy41rvmLzqM0/Wbj5icouHcU/4Q05gfTEFbRkaXpcDFIomRvquURsNHDhU70qBq3jpkj/dQ3+J/XUbCU2aMsFg3GdUUJyPuArtxTNedFeppS7OlYtCkWdhy9kwkq4IVb21KOtKnyz9XXVv0Qvif+AJXUteoHe31DJyS+h9xtaL8bp2sq5NuRBT4kn4il6LBvQ72daqgPc/2SSEuyYodtR+OXF74Zo1JZr8VxoRvezoZ5pHQgyOTWL6rCjWwCBn+rGtmMtpwDM8wVd0f7EUXcIw53bHIvs/3viRmKuG1GMIuyjzq9pfPAWT7/al3FD5VnXgM7CSyH8zaBRbR0j5rwPoidYklciwOfsR949xi0ZT9hp6Zmm66UsIwnXW/imk9xL67PBRWSxqByBgpNKzT3EfeKUbR40R7S9k4nwHlrihfpNl8wLrj2nVfphCrGxZIAzq21hkJFiTOHFZk5XeACGZZQQmP0eSzqS2WuHTnyQXm1AXYAnx+cE8QwyCF/NuMq0g==
X-Forefront-Antispam-Report: CIP:12.22.5.235; CTRY:US; LANG:en; SCL:1; SRV:;
IPV:NLI; SFV:NSPM; H:mail.nvidia.com; PTR:InfoNoRecords; CAT:NONE;
SFS:(13230001)(4636009)(36840700001)(46966006)(40470700004)(83380400001)(47076005)(426003)(336012)(8676002)(86362001)(186003)(36860700001)(70586007)(70206006)(1076003)(2616005)(26005)(6286002)(2906002)(7696005)(316002)(356005)(5660300002)(54906003)(6916009)(55016003)(6666004)(36756003)(4326008)(81166007)(82310400005)(508600001)(40460700003)(8936002)(36900700001);
DIR:OUT; SFP:1101;
X-OriginatorOrg: Nvidia.com
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 07 Jun 2022 23:50:05.7294 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: 287b4185-2611-4d0f-de6b-08da48e0729d
X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=43083d15-7273-40c1-b7db-39efd9ccc17a; Ip=[12.22.5.235];
Helo=[mail.nvidia.com]
X-MS-Exchange-CrossTenant-AuthSource: BN8NAM11FT031.eop-nam11.prod.protection.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Anonymous
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL1PR12MB5239
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
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 | 53 ++++++++++++++++---
.../prog_guide/env_abstraction_layer.rst | 2 +
2 files changed, 49 insertions(+), 6 deletions(-)
diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst
index 1df3ab0255..c6975ce8bf 100644
--- a/doc/guides/linux_gsg/enable_func.rst
+++ b/doc/guides/linux_gsg/enable_func.rst
@@ -13,13 +13,46 @@ 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 runing 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, for example::
+
+ export HUGEDIR=$HOME/huge-1G
+ mkdir -p $HUGEDIR
+ sudo dpdk-hugepages.py --mount --directory $HUGEDIR --owner `id -u`:`id -g`
+
+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.
+
+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,7 +67,15 @@ 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
+See `Hugepage Mapping <hugepage_mapping>`_
+secton to learn how these limits affect EAL.
+
+Device Control
+~~~~~~~~~~~~~~
+
+If the HPET is to be used, ``/dev/hpet`` permissions must be adjusted.
+
+Depending on which kernel driver is in use, the relevant
resources also should be accessible by the user running the DPDK application.
For ``vfio-pci`` kernel driver, the following Linux file system objects'
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