.. _man1-prte:

prte
====

.. include_body

prte |mdash| start a PRRTE distributed virtual machine (DVM)

SYNOPSIS
--------

.. code:: sh

   prte [options]

DESCRIPTION
-----------

``prte`` instantiates an instance of the PMIx Reference Runtime
Environment (PRRTE) distributed virtual machine (DVM). The ``prte``
process itself becomes the DVM controller; it starts a
:ref:`prted(1) <man1-prted>` daemon on each of the other nodes that
make up the DVM, and then waits to be given jobs to run |mdash| by
:ref:`prun(1) <man1-prun>`, by any other PMIx tool, or by an
application calling ``PMIx_Spawn``. The DVM persists until it is shut
down by :ref:`pterm(1) <man1-pterm>`.

The nodes of the DVM are those of the allocation the resource manager
granted, if any, narrowed by ``--host``, ``--hostfile`` and
``--default-hostfile``; see ``--hostfile`` below.

``prte`` does not launch an application itself: an executable given on
its command line is an error. Use :ref:`prterun(1) <man1-prterun>` to
start a DVM, run a single job in it, and shut it down again.

All of the text below is also available from the command itself:
``prte --help`` lists the options, and ``prte --help <option>`` prints
the full description of one.

DIRECTIVES AND QUALIFIERS
-------------------------

.. include:: /prrte-rst-content/detail-directive-syntax.rst

OPTIONS
-------

A value may follow its option either as the next argument or after an
``=`` (``--host a,b`` or ``--host=a,b``).

.. rubric:: General options

``-h`` | ``--help [<option>]``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Print the list of options, or the full help for the named option.

``-v`` | ``--verbose``
^^^^^^^^^^^^^^^^^^^^^^

Enable typical debug options.

``-V`` | ``--version``
^^^^^^^^^^^^^^^^^^^^^^

Print version and exit.

.. rubric:: Debug options

``--debug-daemons``
^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-debug-daemons.rst

``--debug-daemons-file``
^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-debug-daemons-file.rst

``--leave-session-attached``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-leave-session-attached.rst

``--display <directives>``
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-display.rst

``--no-aggregate-help``
^^^^^^^^^^^^^^^^^^^^^^^

Do not aggregate help output from multiple processes. PRRTE defaults to
aggregating messages generated by its "help" subsystem so that only one
is printed out per topic (along with the number of processes that
reported the same issue). This is done to avoid users receiving a flood
of one-per-process error messages, all containing the identical error
report. Setting this option turns off the aggregation, thereby allowing
the user to see duplicate reports from multiple processes.

.. rubric:: MCA parameters

``--prtemca <key> <value>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-prtemca.rst

``--pmixmca <key> <value>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-pmixmca.rst

``--tune <files>``
^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-tune.rst

.. rubric:: DVM options

``-H`` | ``--host <hosts>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-dash-host.rst

``--hostfile <filename>``
^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-dvm-hostfile.rst

``--default-hostfile <filename>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Specify a default hostfile.

Also see ``--hostfile``.

``--uniform-nodes``
^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-homo-nodes.rst

``--rtos <directives>`` | ``--runtime-options <directives>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Given to ``prte``, these runtime options apply to the DVM itself |mdash|
for example, ``--rtos show-progress`` reports progress while the DVM's
daemons start, which is useful on large systems.

.. include:: /prrte-rst-content/cli-runtime-options.rst

``--timeout <seconds>``
^^^^^^^^^^^^^^^^^^^^^^^

Timeout DVM startup if time exceeds the specified number of seconds.
The DVM startup will abort after the specified interval.

``--daemonize``
^^^^^^^^^^^^^^^

Daemonize the DVM daemons and controller into the background.

``--no-ready-msg``
^^^^^^^^^^^^^^^^^^

Do not print a DVM ready message.

``--system-server``
^^^^^^^^^^^^^^^^^^^

Start the DVM controller and its daemons as the system server on their
nodes.

``--set-sid``
^^^^^^^^^^^^^

Direct the DVM (controller and daemons) to separate from the current
session.

``--report-pid <arg>``
^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-report-pid.rst

``--report-uri <arg>``
^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-report-uri.rst

``--keepalive <fd>``
^^^^^^^^^^^^^^^^^^^^

Pipe for DVM controller to monitor |mdash| DVM will terminate upon
closure.

``--singleton <id>``
^^^^^^^^^^^^^^^^^^^^

DVM is being started by a singleton process (i.e., one not started by a
DVM) |mdash| the argument must be the PMIx ID of the singleton process
that started us.

``--launch-agent <executable>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Name of daemon executable used to start processes on remote nodes
(default: ``prted``). This is the executable the DVM controller shall
start on each remote node when establishing the DVM.

``--max-vm-size <size>``
^^^^^^^^^^^^^^^^^^^^^^^^

Maximum number of daemons to start |mdash| sets the maximum size of the
DVM.

``--prefix <dir>``
^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-prefix.rst

``--noprefix``
^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-noprefix.rst

``--pmix-prefix <dir>``
^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-pmix-prefix.rst

``--exec-agent <path>``
^^^^^^^^^^^^^^^^^^^^^^^

Executable to be used to start an application process. The resulting
command for starting an application process will be ``<path> app
<app-argv>``. The path may contain its own command line arguments.

Note that this can also be given as a runtime option (see ``--rtos``),
and that ``--rtos default-exec-agent`` returns the job to the system
default agent.

``-x <name>[=<value>]``
^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-x.rst

``--forward-signals <signals>``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-forward-signals.rst

``--allow-run-as-root``
^^^^^^^^^^^^^^^^^^^^^^^

.. include:: /prrte-rst-content/cli-allow-run-as-root.rst

DEPRECATED COMMAND LINE OPTIONS
-------------------------------

The following options are still accepted, but will be removed in a
future release; use the replacement shown.

``--machinefile <filename>``
   Synonym for ``--hostfile``.

``--show-progress``
   Replaced by ``--rtos show-progress``.

``--hetero-nodes``
   Has no effect beyond a warning: heterogeneous nodes are detected
   automatically. Give ``--uniform-nodes`` if the nodes are known to be
   identical.

``--debug``
   Has no effect; it is accepted, with a warning, so that old command
   lines still parse.

ENVIRONMENT
-----------

``PRTE_ALLOW_RUN_AS_ROOT``, ``PRTE_ALLOW_RUN_AS_ROOT_CONFIRM``
   When *both* are set to ``1``, permit execution as root |mdash| see
   ``--allow-run-as-root``.

``PRTE_MCA_<name>``, ``PMIX_MCA_<name>``
   Set the PRRTE or PMIx MCA parameter ``<name>``, as ``--prtemca`` and
   ``--pmixmca`` do on the command line.

EXIT STATUS
-----------

``prte`` exits with status 0 when the DVM is shut down normally (for
example, by :ref:`pterm(1) <man1-pterm>`), and non-zero if the DVM
could not be started or terminated abnormally.

EXAMPLES
--------

Start a DVM on the hosts listed in a hostfile, in the background, and
write the controller's URI to a file that tools can use to find it:

.. code:: sh

   shell$ prte --hostfile myhosts --report-uri dvm.uri --daemonize

Start a DVM whose jobs default to mapping without launching, so
placement can be explored with :ref:`prun(1) <man1-prun>`:

.. code:: sh

   shell$ prte --rtos donotlaunch --daemonize
   shell$ prun --display map -n 8 ./a.out

.. seealso::
   :ref:`prun(1) <man1-prun>`,
   :ref:`prterun(1) <man1-prterun>`,
   :ref:`pterm(1) <man1-pterm>`,
   :ref:`prted(1) <man1-prted>`,
   :ref:`prte_info(1) <man1-prte_info>`,
   :ref:`prte(5) <man5-prte>`
