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 5763CA034C for ; Mon, 1 Aug 2022 14:19:33 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 43A114067B; Mon, 1 Aug 2022 14:19:33 +0200 (CEST) Received: from NAM10-DM6-obe.outbound.protection.outlook.com (mail-dm6nam10on2067.outbound.protection.outlook.com [40.107.93.67]) by mails.dpdk.org (Postfix) with ESMTP id BC7DE4014F for ; Mon, 1 Aug 2022 14:19:32 +0200 (CEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=UFWtQSBUl4o5ddTiS6iDgQrJaeZYuAWNXZMkyrZ6E6a40S1aEuJZjoKLjKgejWa6X78q1hz08DnxxNI5liiR/wkUpSgtwFxXKXx+9mpkTeYu49wNgvLqkC3E0szfNFH5n4tV46soC+9NmqRUc5pK09v5RHnyjCJIFJbuBd1V1O8xFj/JOMQCetKro2viY8IUpRUx2fgUZIqNGh3KKSIS7g1SkQEpyAtG1YLuF3mJsMkIB27uU5K59vsemHONhL9ngrK7zMXdu7sk5f4SRH89s3DEf3oN9guQxCLN5w1wsCZ4sGsAz1BuFnC5ewW2nW+jXM/fpCaz9TVD4IooTjX0RA== 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=IvoM1W2TLf5VfhiSPmf823rhhei5Ulr0fYs522QMfNI2Qb2+pCIjtf4k0AEojB1x1FI9Dgpcj6G9Wj5GK8xX4+Es6AwbvFiF9hgzqojU1J7h8kbwLMg9t/Fb+kUPxZHNiih8+g/QHHp6u5K5a6xApaX7T8jIbtI1NDP7II0Lis21qLmsqSQGuAzUVQ3jDsxCdvi1zMwE9Ob+MVem7Re3rnLphr6w6Y40ZW3V+qUQen4x+7/n8xY+JJAYLyPWIsKMWvSidlXQfpjLRmMDWoDeMo++1CUAyYfmjUTiQ52i+7UcoQwWugTrWjWTCkhN2s3OfdLKiaIS7w/tudUa5X4Yng== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass (sender ip is 12.22.5.234) 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=W9GTV7689dKefCc7i3QibezsIIhgZOcOrmVOIxxxlrjYWBOF/B1CO6xUSkyvYRC5I09MFy8XBuwEBQ7t2KRl3xOu2M+dzu0zr4V+HvRk7US4UECSob91uybsj1Soidv4bGP0KMjrbXBSSlCsD1LcTQAxtSUkVqjJjMpRwd3svtlSSoer4nq09ZQb6YFXco5OZsNlDc9Ul3lHA9W3pnLBl0nn4qW6Z2Oh3zTYCFHVxrQMHkFfcQ23wVhMiahxGVRCV9PhHWPX/3N3aGb/SOT3naBAesXykcaQbI8MGJG+m30iozwx6+7yIP351aQR5GNg8Jg78gYbUokS4LhLFJjRRw== Received: from MW4PR03CA0042.namprd03.prod.outlook.com (2603:10b6:303:8e::17) by MN2PR12MB2957.namprd12.prod.outlook.com (2603:10b6:208:100::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5482.11; Mon, 1 Aug 2022 12:19:30 +0000 Received: from CO1NAM11FT057.eop-nam11.prod.protection.outlook.com (2603:10b6:303:8e:cafe::92) by MW4PR03CA0042.outlook.office365.com (2603:10b6:303:8e::17) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.5482.12 via Frontend Transport; Mon, 1 Aug 2022 12:19:30 +0000 X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 12.22.5.234) 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.234 as permitted sender) receiver=protection.outlook.com; client-ip=12.22.5.234; helo=mail.nvidia.com; pr=C Received: from mail.nvidia.com (12.22.5.234) by CO1NAM11FT057.mail.protection.outlook.com (10.13.174.205) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384) id 15.20.5482.10 via Frontend Transport; Mon, 1 Aug 2022 12:19:29 +0000 Received: from rnnvmail201.nvidia.com (10.129.68.8) by DRHQMAIL101.nvidia.com (10.27.9.10) with Microsoft SMTP Server (TLS) id 15.0.1497.32; Mon, 1 Aug 2022 12:19:29 +0000 Received: from rnnvmail201.nvidia.com (10.129.68.8) by rnnvmail201.nvidia.com (10.129.68.8) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.26; Mon, 1 Aug 2022 05:19:28 -0700 Received: from nvidia.com (10.127.8.11) by mail.nvidia.com (10.129.68.8) with Microsoft SMTP Server id 15.2.986.26 via Frontend Transport; Mon, 1 Aug 2022 05:19:27 -0700 From: Dmitry Kozlyuk To: CC: "Xueming(Steven) Li" , Bruce Richardson Subject: [PATCH 20.11] doc: add more instructions for running as non-root Date: Mon, 1 Aug 2022 15:19:24 +0300 Message-ID: <20220801121924.2631663-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: 8f471620-859b-454a-ac50-08da73b8158f X-MS-TrafficTypeDiagnostic: MN2PR12MB2957: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?THVEMVWv3xIuhOgHKuBWi8ErF8p29cnNdp/imaOR4htlkHpcmX3k1d5CxV89?= =?us-ascii?Q?goioGXK54Tpm/oo35Pw585J1x11Z+rjnfjkj8YT0qa0Ch4zvBYREa1v8NFri?= =?us-ascii?Q?xIDrxi1cj/QTHvMEQYfOgCBZbiKnZWe+FYL1XbKKBWPd2Z5wwTFh92KvngRV?= =?us-ascii?Q?BvxDcmzn8BEH1ZW3BQPZFK4P3fRPMQPEzdsbgxylVoRnqecJ2lk6erzV0zZh?= =?us-ascii?Q?24phzrNzKkjLllZ71eMXrvnhBHzRT6qSz8qx9NQrxEpzgoeP+pShHOYePE0e?= =?us-ascii?Q?gkl2Ke3HB0wjo1HFEc7ma9S1e2YqcaEkKZl5o4BLEg+FU2pgFldbCTe4bc18?= =?us-ascii?Q?10wss+IJ0N4Jz+BLP4wdE5FVVaLSIBVQgUqwkQ27WvPU87s+dm1M+F0ELur6?= =?us-ascii?Q?CSJbrwvl6YLAmCtwUcCeRUrawm/OvG+3pgV1uvPl6gswwk3niFr/POcKADrg?= =?us-ascii?Q?6vKq6LXvkw+eOowwJFRuiMM+el1vI+xLY1wRlZYqPDG804v7CH/ltqfM78yI?= =?us-ascii?Q?D8OE/Myz1sN87DR09FWm/OgSCwgGtGChbnga26O9WU8xDTbTenpZZZx9CKiO?= =?us-ascii?Q?BG8yxLID4iynwG9EVdVDCKB0oOkuW+nF2SfvVvVFq5L8rRClO1WgG5obCR+w?= =?us-ascii?Q?GAqegeGmu0ASI8uqGgn1wRwcgvT6YRdv2E1HTG3AN+jV6WekYiNvwoksCl5p?= =?us-ascii?Q?X44zPH3GN//Upoyr+h81v5S+cjVwtzi4qYAgzg0Tk8+g0oEdYrNRCWyP/lEf?= =?us-ascii?Q?nOlbniAG/yAPVi4otDk9k+C02aSbVWzmdmumg1mJmLcvfRWJ69+mviMKRifK?= =?us-ascii?Q?zOBTTbhNnU0u8sXJF29szLdlQPqzm6FZi4Coyy/EkHo7Gfei2yFb2O7P4jZq?= =?us-ascii?Q?D/NG8Q5MOgnO0I8KD7temPQTpp//xnPJHpIc5EkLRpwPFmCI60kNuriqBsQB?= =?us-ascii?Q?NrsSKnM3ZfmYM7q52mIojw=3D=3D?= X-Forefront-Antispam-Report: CIP:12.22.5.234; CTRY:US; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:mail.nvidia.com; PTR:InfoNoRecords; CAT:NONE; SFS:(13230016)(4636009)(346002)(39860400002)(396003)(136003)(376002)(40470700004)(46966006)(36840700001)(186003)(47076005)(70586007)(55016003)(316002)(6916009)(36860700001)(54906003)(40480700001)(40460700003)(336012)(83380400001)(82740400003)(81166007)(426003)(4326008)(6286002)(478600001)(70206006)(5660300002)(82310400005)(8936002)(1076003)(8676002)(26005)(2906002)(7696005)(41300700001)(6666004)(36756003)(86362001)(2616005)(356005)(36900700001); DIR:OUT; SFP:1101; X-OriginatorOrg: Nvidia.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 01 Aug 2022 12:19:29.8166 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 8f471620-859b-454a-ac50-08da73b8158f 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.234]; Helo=[mail.nvidia.com] X-MS-Exchange-CrossTenant-AuthSource: CO1NAM11FT057.eop-nam11.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR12MB2957 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