From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id C035DA0573 for ; Tue, 28 Jun 2022 22:24:09 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id B651540042; Tue, 28 Jun 2022 22:24:09 +0200 (CEST) Received: from NAM11-CO1-obe.outbound.protection.outlook.com (mail-co1nam11on2058.outbound.protection.outlook.com [40.107.220.58]) by mails.dpdk.org (Postfix) with ESMTP id 9405B40042 for ; Tue, 28 Jun 2022 22:24:08 +0200 (CEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Cp4NFDA40he0p7HgTvXqbxIvkkY0y5BjFg+P8jNIPMzwjXe3r+tJO1SJsUdDRsd7894qZ6Lmj3P0b8hWNBKAJgIJQX+8Awp95pAyKeiZ6yMEEMrqq5fES6aW7J+sigLaJnqkY6+dAIe8j7XSQKGlBNQsfJzp2jvcB2MGI+FBb74+EeMHtS1banfSTJlc1kwkdrjCskRvoMiCNEFHHHGx6hWRbT8ceHX7KFmxKe7Kimf7lNyee6MzSoi7RHwKDsSMtvXfclg/AbunOyA8yf/6JI03EcglbFZvLhhzzaXX+DOuuVFJmDesR0k07JQYVUyUHoNooWAN0i6xfcE1xdb4Jw== 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=g36kKsKU17OuTDwQ2AzjUpHNkS4VxqdxAqGbFxWg8aU=; b=Ixor/FGNuhJDpM6GJZe7ICP3+sf2vrio0PNiOqnLz9YvnP9ZN7Xs1pAtD6zjUNBaf2loH7STf59bIJ7dZliJzgHgmYsnHIQ1CmFtyAAVnKifjMzQoSNbRYWRezdIFGLW+Ncp9eZEIZ3Z93AVzNcmUA4kd/wI1T2VxtGmQyZl6f5O0L/yzpnlHvHTVNOfbrZkxitto4ldxHJDpG5Wf+mvRPABzH+7/YZASldQhvWJFbjqH2E7kqFeyGJuMQmw+JqEh5IidSXoDs6uzBzGrcMIu7HA+fBBVMtu2WbugrByOO+wgHNd56m9wMBRtkIhLsJ9SY43P8APIryon8zA65uVsw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 12.22.5.236) smtp.rcpttodomain=intel.com 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=g36kKsKU17OuTDwQ2AzjUpHNkS4VxqdxAqGbFxWg8aU=; b=M9Feus2SmBev3CdiXwwdbjC7fhGfcxkK3H2Q8E3PeMh4NTJVlSqMaBIFbNvcYWKH+Mmt7hUXeCiMqoarKNytGLDosDQiuc6t8X7h7i+OpShgGlBa2ydKDbjN5ZTnW5KNsA2NxRZ1jI5Eeyl6AZJNueVKPVVmos8z+YvRh3iSRbuNiW8ale4j3dmk+Me8r+aSQ7dryZA2CGtbRTeZ7UuEkX9zNKoRjBKo0kc+xBOfju+eL/HXDaCp3gaNjCZoDdThrAcoZGBkWg6tSR9gahE7zUJzOh+AhUzGvNCg2/rUnorawqxWuFmwCLyz9uyatmWQ/kNXBthLLkraqfua7Ynjdw== Received: from MW4PR03CA0223.namprd03.prod.outlook.com (2603:10b6:303:b9::18) by BN7PR12MB2740.namprd12.prod.outlook.com (2603:10b6:408:23::16) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5373.17; Tue, 28 Jun 2022 20:24:06 +0000 Received: from CO1NAM11FT040.eop-nam11.prod.protection.outlook.com (2603:10b6:303:b9:cafe::b8) by MW4PR03CA0223.outlook.office365.com (2603:10b6:303:b9::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5373.16 via Frontend Transport; Tue, 28 Jun 2022 20:24:06 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 12.22.5.236) 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.236 as permitted sender) receiver=protection.outlook.com; client-ip=12.22.5.236; helo=mail.nvidia.com; pr=C Received: from mail.nvidia.com (12.22.5.236) by CO1NAM11FT040.mail.protection.outlook.com (10.13.174.140) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384) id 15.20.5373.15 via Frontend Transport; Tue, 28 Jun 2022 20:24:06 +0000 Received: from rnnvmail202.nvidia.com (10.129.68.7) by DRHQMAIL109.nvidia.com (10.27.9.19) with Microsoft SMTP Server (TLS) id 15.0.1497.32; Tue, 28 Jun 2022 20:24:05 +0000 Received: from rnnvmail205.nvidia.com (10.129.68.10) by rnnvmail202.nvidia.com (10.129.68.7) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.26; Tue, 28 Jun 2022 13:24:04 -0700 Received: from nvidia.com (10.127.8.11) by mail.nvidia.com (10.129.68.10) with Microsoft SMTP Server id 15.2.986.26 via Frontend Transport; Tue, 28 Jun 2022 13:24:03 -0700 From: Dmitry Kozlyuk To: CC: Kevin Traynor , Bruce Richardson Subject: [PATCH 21.11] doc: add more instructions for running as non-root Date: Tue, 28 Jun 2022 23:24:00 +0300 Message-ID: <20220628202400.713098-1-dkozlyuk@nvidia.com> X-Mailer: git-send-email 2.25.1 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: 96d022c0-881f-49d6-834b-08da59442649 X-MS-TrafficTypeDiagnostic: BN7PR12MB2740:EE_ X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: =?us-ascii?Q?eZTqFlQskwRDFG0hB8MaIQzs1iAaP7s13u0BpnKEhbAkjyTunyzG0StaYxrC?= =?us-ascii?Q?NM3A3ZMQ9MVnTXqVITloy5UUSFapojnbSZ8y2THWea/j5BD7VTS3COmNxgk0?= =?us-ascii?Q?Xg8dM24cpVHNtsIsF5rzRMxDr6JyKivRjyqE+Ep2A1VQa4XGeWj8xDorQCsO?= =?us-ascii?Q?QeChH5zt9f90avq+KTykZ5KI5nDaZTf4vm6oxt8bmmA01nBhccvSxc8oOnm5?= =?us-ascii?Q?+/7T0/AeG+G7zCiwHC4GiaHsko3iqS+YsD0KIHwBVsKpSs6gnl9/5dHRt+2L?= =?us-ascii?Q?KtKQKloOSKwgDiW1QI7u2ZWa44O/uLqvY7UzjKrPF9g2lR+z8Bt5z1kH4VLi?= =?us-ascii?Q?YdNSqQ/a1KkWgANS/WNanTV9A308iwQM+zpF4XeDAR0kIs0hdnUVZDSuYfpS?= =?us-ascii?Q?PfAK1CzogR6J+4pW+8OgctLy9uvAE7EpkUbs1U94uhOwibTPZRZEBpdUsdG5?= =?us-ascii?Q?swU4dF752h8uSZMadwJItDJNUHc4XBRgO5iB8mokSpocjonf7hkGy4iBbuwT?= =?us-ascii?Q?EDJ+XZXQ7XClxrNKCMMtD0L0KX6JhuYhcRLzaZ/Zrgkn3gYdY0sRHpz5r+k1?= =?us-ascii?Q?KlADZjlWJc4b8S5CblDlpWLT/OfXan0u/dZBG9iAE5swSZKk1pCEeIra0L6A?= =?us-ascii?Q?mzs45BlAk7atG7lbGsNF6rp+yBLN72uQxGH+KCg8zcvW/cooYebDn7M6+zpV?= =?us-ascii?Q?diiAhpGAHDC68W5oTmZcyquHQSW+mke4sAueugSN3pqgF0gErPCaW8xOfU4T?= =?us-ascii?Q?MwuS17rNIkA+TrRrhrTbr5o/ypdRNIg9cWvPA0Yxd5VEGewDTFDpbzV04Ft8?= =?us-ascii?Q?sPstOsnIgoEnA4T0wNGTq1Btshg3x0ytEu0Lxswn0npdVL3DQwBenjW2dZH9?= =?us-ascii?Q?ETvnBGPGuvEUVGVw52w8Q4kfLelb6MPBgyFbczuDPQoPKbWaFo95prjxV+88?= =?us-ascii?Q?lptR9bbTnMHRnPw1T4hJIw=3D=3D?= X-Forefront-Antispam-Report: CIP:12.22.5.236; CTRY:US; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:mail.nvidia.com; PTR:InfoNoRecords; CAT:NONE; SFS:(13230016)(4636009)(376002)(346002)(136003)(39860400002)(396003)(40470700004)(46966006)(36840700001)(70586007)(186003)(426003)(47076005)(478600001)(40460700003)(336012)(2616005)(82310400005)(86362001)(1076003)(5660300002)(36756003)(55016003)(36860700001)(41300700001)(6286002)(40480700001)(6916009)(316002)(54906003)(2906002)(8676002)(8936002)(7696005)(26005)(356005)(82740400003)(83380400001)(70206006)(4326008)(81166007)(36900700001); DIR:OUT; SFP:1101; X-OriginatorOrg: Nvidia.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 28 Jun 2022 20:24:06.0096 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 96d022c0-881f-49d6-834b-08da59442649 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.236]; Helo=[mail.nvidia.com] X-MS-Exchange-CrossTenant-AuthSource: CO1NAM11FT040.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: BN7PR12MB2740 X-BeenThere: stable@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: patches for DPDK stable branches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: stable-bounces@dpdk.org [ upstream commit 979bb5d493fbbce77eaaf2b4a01ee98f93f76dd9 ] 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. Signed-off-by: Dmitry Kozlyuk Acked-by: Bruce Richardson --- Upstream commit references things missing from 21.11: new dpdk-hugepages.py options and memory mapping documentation. The script call replaced with a direct mount command. Documentation reference is dropped as non-essential. doc/guides/linux_gsg/enable_func.rst | 85 +++++++++++++++++++--------- 1 file changed, 58 insertions(+), 27 deletions(-) diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/enable_func.rst index 25f87f6b1a..7538d04d97 100644 --- a/doc/guides/linux_gsg/enable_func.rst +++ b/doc/guides/linux_gsg/enable_func.rst @@ -66,13 +66,62 @@ The application can then determine what action to take, if any, if the HPET is n 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 mount manually:: + + mount -t hugetlbfs -o pagesize=1G,uid=`id -u`,gid=`id -g` nodev $HOME/huge-1G + +In production environment, the OS can manage mount points +(`systemd example `_). + +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 `_. + +.. note:: + + Using ``vfio-pci`` kernel driver, if applicable, can eliminate the need + for physical addresses and therefore eliminate the permission requirements + described below. + +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 + +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 @@ -87,8 +136,10 @@ 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. +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: @@ -98,26 +149,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 ----------------------------------------------- -- 2.25.1