.. _slurm-authentication:

Authentication
==============

To connect to a production SLURM server, you must provide the SLURM REST URL, user name, and a valid access token.

Using Python Parameters
-----------------------

With the Executor Context
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from pyslurmutils.concurrent.futures import SlurmRestExecutor

    with SlurmRestExecutor(
        url=url,                               # SLURM REST URL
        renewal_url=renewal_url,               # Optional: instead of token
        user_name=user_name,                   # Optional: SLURM user name
        token=token,                           # Optional: SLURM access token
        api_version=api_version,               # Optional: SLURM REST API version
        ...
    ) as executor:
        future = executor.submit(..)

With a Client Class
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from pyslurmutils.client import SlurmScriptRestClient
    from pyslurmutils.client import SlurmPyConnRestClient
    from pyslurmutils.client import SlurmBaseRestClient

    # Works for any of the above classes:
    client = SlurmBaseRestClient(
        url=url,                               # SLURM REST URL
        renewal_url=renewal_url,               # Optional: instead of token
        user_name=user_name,                   # Optional: SLURM user name
        token=token,                           # Optional: SLURM access token
        api_version=api_version,               # Optional: SLURM REST API version
        ...
    )

Using Environment Variables
---------------------------

You can also configure authentication by setting environment variables.

Option 1 — Use a Pre-Generated Token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run the following commands **on a SLURM host** to generate and export a token:

.. code-block:: bash

    export SLURM_URL="https://<domain>:<port>"
    export SLURM_TOKEN="$(scontrol token lifespan=3600)"
    export SLURM_USER="${USER}"         # Optional
    export SLURM_API_VERSION="v0.0.41"  # Optional

.. note::

   The ``scontrol`` command must be executed on a machine that is part of the SLURM cluster.

Option 2 — Automatic Token Renewal via ``pyslurmutils``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you prefer, let ``pyslurmutils`` automatically obtain and renew tokens.

Slurm client
++++++++++++

If the local host is a Slurm client (i.e. has the ``scontrol`` command) it is
sufficient to define these environment variables:

.. code-block:: bash

    export SLURM_URL="https://<domain>:<port>"
    export SLURM_USER="${USER}"         # Optional
    export SLURM_API_VERSION="v0.0.41"  # Optional

SSH access to Slurm client
++++++++++++++++++++++++++

If the local host is not a Slurm client but has SSH access to a Slurm client,
define the SSH URL to the Slurm client using the `SLURM_RENEWAL_URL` environment variable:

.. code-block:: bash

    export SLURM_URL="https://<domain>:<port>"
    export SLURM_RENEWAL_URL="ssh://<domain>:<port>"
    export SLURM_USER="${USER}"         # Optional
    export SLURM_API_VERSION="v0.0.41"  # Optional

.. important::

   - Passwordless SSH access (e.g., via SSH keys) to the host specified by ``SLURM_RENEWAL_URL`` is required.
   - The ``scontrol`` command must be available on that host.