From 7baebf38238328df0485da81d067e6c68ed49953 Mon Sep 17 00:00:00 2001 From: Ralph Castain Date: Mon, 18 Sep 2023 07:28:42 -0600 Subject: [PATCH] Touchup for backport Signed-off-by: Ralph Castain --- config/prte_config_files.m4 | 3 +- configure.ac | 2 +- docs/Makefile.am | 2 +- docs/_templates/configurator.html | 313 ++++++++++++++++++++++++++++++ docs/configuration.rst | 128 ++++++++++++ docs/man/man1/index.rst | 1 - docs/man/man1/psched.1.rst | 29 --- src/include/Makefile.am | 45 +++-- src/tools/prte_info/components.c | 4 +- src/tools/prte_info/prte_info.c | 2 +- 10 files changed, 469 insertions(+), 60 deletions(-) create mode 100644 docs/_templates/configurator.html create mode 100644 docs/configuration.rst delete mode 100644 docs/man/man1/psched.1.rst diff --git a/config/prte_config_files.m4 b/config/prte_config_files.m4 index 69226df6df..750484975e 100644 --- a/config/prte_config_files.m4 +++ b/config/prte_config_files.m4 @@ -4,7 +4,7 @@ # Copyright (c) 2016-2020 Intel, Inc. All rights reserved. # Copyright (c) 2019 Research Organization for Information Science # and Technology (RIST). All rights reserved. -# Copyright (c) 2022 Nanook Consulting. All rights reserved. +# Copyright (c) 2022-2023 Nanook Consulting. All rights reserved. # $COPYRIGHT$ # # Additional copyrights may follow @@ -18,7 +18,6 @@ AC_DEFUN([PRTE_CONFIG_FILES],[ AC_CONFIG_FILES([ src/Makefile src/etc/Makefile - src/include/Makefile src/util/Makefile src/util/hostfile/Makefile src/tools/pcc/Makefile diff --git a/configure.ac b/configure.ac index 40a46e322a..7a25a4a8a4 100644 --- a/configure.ac +++ b/configure.ac @@ -25,7 +25,7 @@ # Copyright (c) 2016-2017 IBM Corporation. All rights reserved. # Copyright (c) 2018-2022 Amazon.com, Inc. or its affiliates. # All Rights reserved. -# Copyright (c) 2021-2022 Nanook Consulting. All rights reserved. +# Copyright (c) 2021-2023 Nanook Consulting. All rights reserved. # Copyright (c) 2021 FUJITSU LIMITED. All rights reserved. # Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. # $COPYRIGHT$ diff --git a/docs/Makefile.am b/docs/Makefile.am index 2ad4607b61..00ec63b6b8 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -2,6 +2,7 @@ # Copyright (c) 2022-2023 Cisco Systems, Inc. All rights reserved. # Copyright (c) 2023 Jeffrey M. Squyres. All rights reserved. # +# Copyright (c) 2023 Nanook Consulting. All rights reserved. # $COPYRIGHT$ # # Additional copyrights may follow @@ -60,7 +61,6 @@ PRTE_MAN1 = \ prted.1 \ prterun.1 \ prun.1 \ - psched.1 \ pterm.1 PRTE_MAN5 = \ diff --git a/docs/_templates/configurator.html b/docs/_templates/configurator.html new file mode 100644 index 0000000000..6a8b006060 --- /dev/null +++ b/docs/_templates/configurator.html @@ -0,0 +1,313 @@ +{% extends "layout.html" %} +{% set title = 'PRRTE DVM Configuration Tool' %} +{% block body %} + + + + + + +PRRTE DVM Configuration Tool + + + + + + +
+

PRRTE Version v{{ release }} DVM Configuration Tool

+

This configuration tool is intended to help system administrators create +a PRRTE configuration file that sets important configuration parameters.

+ +

While every attempt is made to maintain compatibility of the PRRTE +configuration tool and options across versions, we recommend that the +configuration file be built using the tool distributed with the version +being installed on your cluster. Some parameters will be set to default +values, but you can manually edit the resulting prte.conf file as desired +for greater flexibility. See the PRRTE documentation at https://docs.prrte.org, +or your locally generated docs (if available), for more +details about the configuration parameters for this version.

+ +

Note that while PRRTE daemons create log files and other files as needed, +they treat the lack of parent directories (e.g., the specified "DVMTempDir") +as a fatal error. This prevents the daemons from running if critical file +systems are not mounted.

+ +

After you have filled in the fields of interest, use the +"Submit" button on the bottom of the page to display the resulting +prte.conf file. It will appear on your web browser. Save the file +in text format as prte.conf for use by the DVM. + +

NOTE: Hostname values should not be specified as fully qualified domain +names (e.g. use foo rather than foo.bar.com). +

+ +

NOTE: This configuration file must be installed as prte.conf in the +etc directory under the PRRTE installation location on all nodes in your cluster. +For example, if PRRTE was installed in /prrte, then the configuration file +must be stored as /prrte/etc/prte.conf so that all prted daemons can find it. +

+ +

Supported Options

+The following options are supported by PRRTE v{{ release }}. + +

Bootstrap Options

+ +ClusterName: +
+The name of the cluster upon which the DVM is executing. This is used by PRRTE +to form the namespace for the DVM daemons, which is taken as -prte-dvm. +Using different names for each of your clusters is important if you use a single +database to record information from multiple PRRTE-managed clusters. +
+
+ +DVMControllerHost: +
+The host upon which the DVM controller will be executing. The prted that +finds itself booting onto this host will declare itself to be the system controller +and will initialize itself accordingly. +
+
+ +DVMControllerPort: +
+The TCP port upon which the +DVM controller will be listening for connections from its prted daemons +on the remaining system nodes. +
+
+ +PRTEDPort: +
+The TCP port upon which each +prted daemon will be listening for connections from its peer daemons +on the other system nodes. +
+
+ +DVMNodes: +
+Provides a regular expression +identifying the nodes that upon which user applications can run. IP addresses can +be provided in place of hostnames if desired.The regular expression can consist of +a simple comma-delimited list of hostnames, or a comma-delimited list of hostname +ranges (e.g., "linux0,linux[2-10]"), or a PMIx "native" regular expression. +
+
+ + +

Operational Options

+ +DVMTempDir: +
+The temporary directory that the +DVM daemons and controller are to use as the base for their session directories. +Working files/directories for the DVM will be placed under this location. +
+
+ +SessionTmpDir: +
+The temporary directory that +the DVM daemons are to use as the base for session directories for all +application sessions. Working files for each session will be placed under +this location, separated out into a directory for each session. +
+
+ +

Logging Options

+ +ControllerLogJobState: +
+ + +
+Directs the DVM +controller to log each DVM-launched job state transition. Log entry includes +the namespace of the job, the state to which it is transitioning, and the +date/time stamp when the transition was ordered. +
+
+ +ControllerLogProcState: +
+ + +
+Directs the DVM +controller to log each process (in a DVM-launched job) state transition. +Log entry includes the namespace and rank of the process, the state to +which it is transitioning, and the date/time stamp when the transition was +ordered. +
+
+ +ControllerLogPath: +
+Path to where the logs are to be written. If a relative path is provided, +then the directory will be created under the DVMTempDir location. The +path defaults to the specified SessionTmpDir in the absence of any input +to this field. The log filename is formatted as prtectrlr--log. +
+
+ +PRTEDLogJobState: +
+ + +
+Directs each prted +in the DVM to log each DVM-launched job state transition. Log entry includes +the namespace of the job, the state to which it is transitioning, and the +date/time stamp when the transition was ordered. +
+
+ +PRTEDLogProcState: +
+ + +
+Directs each prted +in the DVM to log each process (in a DVM-launched job) state transition. +Log entry includes the namespace and rank of the process, the state to +which it is transitioning, and the date/time stamp when the transition was +ordered. +
+
+ +PRTEDLogPath: +
+Path to where the logs are to be written. If a relative path is provided, +then the directory will be created under the DVMTempDir location. The +path defaults to the specified SessionTmpDir in the absence of any input +to this field. The log filename is formatted as prted--log. + +
+
+ + +
+{% endblock %} diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000000..f5eb58cdc9 --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,128 @@ +PRRTE DVM Configuration +======================= + +The PMIx Reference RunTime Environment (PRRTE) can be instantiated +as a Distributed Virtual Machine (DVM) in two ways. First, the +``prte`` command can be executed at a shell prompt. This will discover +the available resources (either from hostfile or as allocated by a +resource manager) and start a PRRTE shepherd daemon (:ref:`prted(1) +`) on each of the indicated nodes. + +The other method, however, is to bootstrap the DVM at time of cluster +startup. Bootstrapping PRRTE allows the DVM to serve as the system-level +runtime, providing a full-service PMIx environment to sessions under +its purview. Integration to an appropriately enabled scheduler can +provide a full workload managed environment for users. + +Establishing the DVM using the bootstrap method requires that a PRRTE +configuration file be created and made available on every node of the +cluster at node startup. The configuration file provides necessary +information for establishing the communication infrastructure between +the DVM controller and the compute node daemons. It also provides a +means for easily defining DVM behavior for options such as logging, +system-level prolog and epilog scripts for each session, and other +PRRTE features. + +The configuration file can be manually created or can be created using +the `PRRTE configuration tool `_. +Manual creation can best be done +by editing the example configuration file (``/src/etc/prte.conf``). +This file contains all the supported configuration options, with all +entries commented out. Simply uncomment the options of interest and +set them to appropriate values. The file will be installed into the +final ``/etc`` when ``make install`` is performed. + +Configuration Options +--------------------- + +The following options are supported by PRRTE |prte_ver|. +While we make every effort to maintain compatibility with prior versions, +we recommend that you check options when installing new versions to +see what may have changed and/or been added. We also recommend that +you use the `PRRTE DVM configurator `_ for the +version you are using to ensure that it is fully compatible. + +Bootstrap Options +^^^^^^^^^^^^^^^^^ +``ClusterName= (default: "cluster")`` is the name of the cluster upon +which the DVM is executing. This is used by PRRTE to form the namespace +for the DVM daemons, which is taken as ``-prte-dvm``. +Using different names for each of your clusters is important if you use a single +database to record information from multiple PRRTE-managed clusters. + +``DVMControllerHost=`` is the host upon which the DVM controller +will be executing. The ``prted`` that finds itself booting onto this host +will declare itself to be the system controller and will initialize itself +accordingly. + +``DVMControllerPort= (default: 7817)`` is the TCP port upon which the +DVM controller will be listening for connections from its ``prted`` daemons +on the remaining system nodes. + +``PRTEDPort= (default: none)`` provides a regular expression +identifying the nodes that upon which user applications can run. IP addresses can +be provided in place of hostnames if desired.The regular expression can consist of +a simple comma-delimited list of hostnames, or a comma-delimited list of hostname +ranges (e.g., "linux0,linux[2-10]"), or a PMIx "native" regular expression. + + +Operational Options +^^^^^^^^^^^^^^^^^^^ +``DVMTempDir= (default: /tmp)`` is the temporary directory that the +DVM daemons and controller are to use as the base for their session directories. +Working files/directories for the DVM will be placed under this location. + +``SessionTmpDir= (default: DVMTempDir)`` is the temporary directory that +the DVM daemons are to use as the base for session directories for all +application sessions. Working files for each session will be placed under +this location, separated out into a directory for each session. + +Logging Options +^^^^^^^^^^^^^^^ +``ControllerLogJobState= (default: false)`` directs the DVM +controller to log each DVM-launched job state transition. Log entry includes +the namespace of the job, the state to which it is transitioning, and the +date/time stamp when the transition was ordered. + +``ControllerLogProcState= (default: false)`` directs the DVM +controller to log each process (in a DVM-launched job) state transition. +Log entry includes the namespace and rank of the process, the state to +which it is transitioning, and the date/time stamp when the transition was +ordered. + +``ControllerLogPath= (default: DVMTempDir)`` is the path to where the logs are to +be written. If a relative path is provided, +then the directory will be created under the ``DVMTempDir`` location. The +path defaults to the specified SessionTmpDir in the absence of any input +to this field. The log filename is formatted as ``prtectrlr--log<``. + +``PRTEDLogJobState= (default: false)`` directs each ``prted`` +in the DVM to log each DVM-launched job state transition. Log entry includes +the namespace of the job, the state to which it is transitioning, and the +date/time stamp when the transition was ordered. + +``PRTEDLogProcState= (default: false)`` directs each ``prted`` +in the DVM to log each process (in a DVM-launched job) state transition. +Log entry includes the namespace and rank of the process, the state to +which it is transitioning, and the date/time stamp when the transition was +ordered. + +``PRRTEDLogPath= (default: DVMTempDir)`` is the path to where the logs are to +be written. If a relative path is provided, +then the directory will be created under the ``DVMTempDir`` location. The +path defaults to the specified SessionTmpDir in the absence of any input +to this field. The log filename is formatted as ``prted--log<``. + + +Configurator Tool +----------------- + +The `PRRTE configuration tool `_ contains all the supported options in an +easy-to-use form. Once you have filled out the desired entries, the +"submit" button will show the resulting configuration file on the +browser window |mdash| a simple "copy/paste" operation into your target +configuration file will yield the final result. diff --git a/docs/man/man1/index.rst b/docs/man/man1/index.rst index da27174695..a1d2e7beb0 100644 --- a/docs/man/man1/index.rst +++ b/docs/man/man1/index.rst @@ -9,5 +9,4 @@ Commands (section 1) prted.1.rst prterun.1.rst prun.1.rst - psched.1.rst pterm.1.rst diff --git a/docs/man/man1/psched.1.rst b/docs/man/man1/psched.1.rst deleted file mode 100644 index 81e4ee9ed6..0000000000 --- a/docs/man/man1/psched.1.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _man1-psched: - -psched -====== - -psched |mdash| submit job to PRRTE - -SYNOPSIS --------- - -.. code:: sh - - shell$ psched ...options... - -DESCRIPTION ------------ - -``psched`` submits a job to the PMIx Reference Runtime Environment -(PRRTE). - -Extensive help documentation for this command is provided through -``psched --help [topic]``. - -At least for now, that content is not available in man page form. -Pull requests to add all the content (via repeatable infrastructure) -would be greatly appreciated. - -.. seealso:: - :ref:`prte(1) ` diff --git a/src/include/Makefile.am b/src/include/Makefile.am index fc06585d5c..5500238df2 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am @@ -12,7 +12,7 @@ # All rights reserved. # Copyright (c) 2010-2020 Cisco Systems, Inc. All rights reserved # Copyright (c) 2014-2020 Intel, Inc. All rights reserved. -# Copyright (c) 2021 Nanook Consulting. All rights reserved. +# Copyright (c) 2021-2023 Nanook Consulting. All rights reserved. # $COPYRIGHT$ # # Additional copyrights may follow @@ -20,28 +20,27 @@ # $HEADER$ # -headers = constants.h \ - types.h \ - frameworks.h \ - hash_string.h \ - prefetch.h \ - prte_config_top.h \ - prte_config_bottom.h \ - prte_portable_platform.h \ - prte_portable_platform_real.h \ - prte_stdint.h \ - prte_stdatomic.h \ - prte_socket_errno.h \ - align.h +# This makefile.am does not stand on its own - it is included from src/Makefile.am -nodist_headers = \ - prte_config.h \ - version.h +headers += \ + include/constants.h \ + include/types.h \ + include/prte_frameworks.h \ + include/hash_string.h \ + include/prefetch.h \ + include/prte_config_top.h \ + include/prte_config_bottom.h \ + include/prte_portable_platform.h \ + include/prte_portable_platform_real.h \ + include/prte_stdint.h \ + include/prte_stdatomic.h \ + include/prte_socket_errno.h \ + include/align.h -EXTRA_DIST = $(headers) +nodist_headers += \ + include/prte_config.h \ + include/version.h -if WANT_INSTALL_HEADERS -prtedir = $(prteincludedir) -nobase_dist_prte_HEADERS = $(headers) -nobase_nodist_prte_HEADERS = $(nodist_headers) -endif +libprrte_la_SOURCES += \ + $(headers) \ + include/prte_frameworks.c diff --git a/src/tools/prte_info/components.c b/src/tools/prte_info/components.c index 9381361dce..57ea13c6d0 100644 --- a/src/tools/prte_info/components.c +++ b/src/tools/prte_info/components.c @@ -16,7 +16,7 @@ * Copyright (c) 2015 Research Organization for Information Science * and Technology (RIST). All rights reserved. * Copyright (c) 2018-2020 Intel, Inc. All rights reserved. - * Copyright (c) 2021-2022 Nanook Consulting. All rights reserved. + * Copyright (c) 2021-2023 Nanook Consulting. All rights reserved. * $COPYRIGHT$ * * Additional copyrights may follow @@ -42,7 +42,7 @@ #include "src/util/pmix_printf.h" #include "src/util/pmix_show_help.h" -#include "src/include/frameworks.h" +#include "src/include/prte_frameworks.h" #include "src/mca/prteinstalldirs/prteinstalldirs.h" diff --git a/src/tools/prte_info/prte_info.c b/src/tools/prte_info/prte_info.c index 6b3a64d87b..6dfc0bdf8a 100644 --- a/src/tools/prte_info/prte_info.c +++ b/src/tools/prte_info/prte_info.c @@ -56,7 +56,7 @@ #include "src/util/pmix_show_help.h" #include "constants.h" -#include "src/include/frameworks.h" +#include "src/include/prte_frameworks.h" #include "src/include/version.h" #include "src/runtime/prte_locks.h"