veeam.py

#! /usr/bin/env python3
# -*- coding: utf-8; py-indent-offset: 4 -*-
#
# Author:  Linuxfabrik GmbH, Zurich, Switzerland
# Contact: info (at) linuxfabrik (dot) ch
#          https://www.linuxfabrik.ch/
# License: The Unlicense, see LICENSE file.

# https://github.com/Linuxfabrik/lib/blob/main/CONTRIBUTING.md

"""This library interacts with the Veeam Enterprise Manager API.
Credits go to https://github.com/surfer190/veeam/blob/master/veeam/client.py."""

__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
__version__ = '2026082501'

import base64

from . import txt, url


def get_token(args):
    """
    Authenticate against the Veeam API and retrieve a session token.

    This function logs into the Veeam Backup REST API by sending a POST request with basic
    authentication. It returns allowed methods and the `X-RestSvcSessionId` token used for further
    API requests.

    Parameters
    ----------
    args : object
        An argument object containing:

          - `URL` (`str`): Base URL of the Veeam API.
          - `USERNAME` (`str`): API Username.
          - `PASSWORD` (`str`): API Password.
          - `INSECURE` (`bool`): Whether to disable SSL verification.
          - `NO_PROXY` (`bool`): Whether to ignore proxy settings.
          - `PROXY` (`str`, optional): Proxy to reach the target through, overriding the
            proxy the environment names.
          - `TIMEOUT` (`int`): Request timeout in seconds.

    Returns
    -------
    tuple (bool, dict or str)
        - `success` (`bool`): Whether authentication was successful.
        - `result` (`dict`): Result dictionary containing session token on success, error otherwise.

    Notes
    -----
    - The session token `X-RestSvcSessionId` is extracted from the HTTP response headers.
    - If authentication fails or no token is found, returns an error message.

    Examples
    --------
    >>> get_token(args)
    (True, {'X-RestSvcSessionId': 'zwiw....'})
    """

    uri = f'{args.URL.rstrip("/")}/api/sessionMngr/?v=latest'
    auth = f'{args.USERNAME}:{args.PASSWORD}'
    encoded_auth = txt.to_text(base64.b64encode(txt.to_bytes(auth)))

    headers = {
        'Authorization': f'Basic {encoded_auth}',
        'Accept': 'application/json',
    }

    # The Veeam logon endpoint expects a POST as a pure verb: no request body. Sending any body
    # makes lib.url.fetch() add a Content-Type (e.g. application/x-www-form-urlencoded), which
    # the endpoint rejects with "415 Unsupported Media Type". Force POST explicitly so the
    # request stays bodyless, matching a plain `curl --request POST`.
    success, result = url.fetch_json(
        uri,
        header=headers,
        method='POST',
        extended=True,
        insecure=args.INSECURE,
        no_proxy=args.NO_PROXY,
        proxy=getattr(args, 'PROXY', None),
        timeout=args.TIMEOUT,
    )

    if not success:
        return success, result

    if not result:
        return False, f'There was no result from {uri}.'

    # lib.url lower-cases all response header names (RFC 9110, section 5.1).
    token = result.get('response_header', {}).get('x-restsvcsessionid')
    if not token:
        return False, 'Something went wrong, maybe user is unauthorized.'

    result['X-RestSvcSessionId'] = token
    return True, result