From 0b332fd81b94061c9389b7cad15f4149f9852ef8 Mon Sep 17 00:00:00 2001 From: "Mark A. Grondona" Date: Mon, 13 Dec 2021 08:38:01 -0800 Subject: [PATCH] fixup: flux-uri manpage --- doc/man1/flux-uri.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/doc/man1/flux-uri.rst b/doc/man1/flux-uri.rst index 7431b2aac534..679efa5d2f86 100644 --- a/doc/man1/flux-uri.rst +++ b/doc/man1/flux-uri.rst @@ -20,8 +20,9 @@ fully-resolved, native Flux URIs. Processes running within a Flux instance will have the ``FLUX_URI`` environment variable set to a native URI which :man3:`flux_open` will -use by default. Therefore, there is usually no need to specify a URI when -connecting to the enclosing instance. However, connecting to a _different_ +use by default, with fallback to a compiled-in native URI for the system +instance of Flux. Therefore, there is usually no need to specify a URI when +connecting to the enclosing instance. However, connecting to a *different* Flux instance will require discovery of the fully-resolved URI for that instance. @@ -32,7 +33,8 @@ parts passed to a plugin which implements the resolution method. As a convenience, if *TARGET* is specified with no scheme, then the scheme is assumed to be ``jobid``. This allows ``flux uri`` to be used to look -up the URI for a Flux instance running as a job with: +up the URI for a Flux instance running as a job in the current enclosing +instance with: :: @@ -58,10 +60,10 @@ OPTIONS ======= **-remote** - Return the _remote_ (``ssh://``) equivalent of the resolved URI. + Return the *remote* (``ssh://``) equivalent of the resolved URI. **--local** - Return the _local_ (``local://``) equivalent of the resulved URI. + Return the *local* (``local://``) equivalent of the resulved URI. Warning: the resulting URI may be invalid for the current system if the network host specified by an ``ssh`` URI is not the current host. @@ -82,8 +84,10 @@ jobid:ID[/ID...] pid:PID This scheme attempts to read the ``FLUX_URI`` value from the process id *PID* using ``/proc/PID/environ``. If *PID* refers to a ``flux-broker``, - then a child of the broker is used instead in order to obtain the - URI for that broker (instead of its parent) + then the scheme reads ``FLUX_URI`` from the broker's initial program or + another child process since ``FLUX_URI`` in the broker's environment + would refer to *its* parent (or may not be set at all in the case of a + test instance started with ``flux start --test-size=N``). slurm:JOBID This scheme makes a best-effort to resolve the URI of a Flux instance @@ -120,14 +124,13 @@ Get the URI of a nested job: .. note:: With the ``jobid`` resolver, ``?local`` only needs to be placed on the last component of the jobid "path" or hierarchy. This will resolve - each URI in turn as a local URI, so it is only useful if all jobs - are actually running on the local system. + each URI in turn as a local URI. Get the URI of a local flux-broker :: - $ flux uri pid:$(pidof flux-broker | cut -d' ' -f1) + $ flux uri pid:$(pidof -s flux-broker) local:///tmp/flux-sLuBkZ/local-0 Get the URI for a Flux instance running as a Slurm job: