python-bareos
=============
`python-bareos` is a Python module to access a https://www.bareos.com backup system.
Packages for `python-bareos` are included in the Bareos core distribution and available via https://pypi.org/.
Documentation is available at https://docs.bareos.org/DeveloperGuide/PythonBareos.html
.. note::
By default, the Bareos Director (>= 18.2.4)
uses TLS-PSK when communicating through the network.
The Python (https://github.com/python/cpython) core module ``ssl``
does support TLS-PSK only since Python >= 3.13.
The section `Transport Encryption (TLS-PSK)`_ describes
how to use TLS-PSK and about the limitations.
For testing this module can also be used without TLS.
Preparations
============
Create some named consoles for testing:
.. code-block:: shell-session
root@host:~# bconsole
*configure add console name=user1 password=secret profile=operator TlsEnable=no
*configure add console name=user-tls password=secret profile=operator
This creates a console user with name `user1` and the profile `operator`.
The `operator` profile is a default profile that comes with the Bareos Director.
It does allow most commands, but deny some dangerous commands (see ``show profile=operator``),
so it is well suited for this purpose.
Futhermore, TLS enforcement is disabled for this console user.
For testing with TLS-PSK, we also create the user `user-tls`.
Examples
========
Calling bareos-director console commands
----------------------------------------
.. code:: python
>>> import bareos.bsock
>>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user1', password='secret')
>>> print(directorconsole.call('help').decode("utf-8"))
This creates a console connection to a Bareos Director.
This connection can be used to `call` commands.
These are the same commands as available via ``bconsole``.
To connect to the default console instead, omit the `name` parameter:
.. code:: python
>>> directorconsole = bareos.bsock.DirectorConsole(address='localhost', port=9101, password='defaultconsolepassword')
The result of the call method is a ``bytes`` object. In most cases, it has to be decoded to UTF-8.
Simple version of the bconsole in Python
----------------------------------------
.. code:: python
>>> import bareos.bsock
>>> directorconsole = bareos.bsock.DirectorConsole(address='localhost', port=9101, password='secret')
>>> directorconsole.interactive()
Or use the ``bconsole.py`` script:
.. code-block:: shell-session
bconsole.py --debug --name=user1 --password=secret localhost
Use JSON objects of the API mode 2
----------------------------------
Requires: Bareos >= 15.2
The class `DirectorConsoleJson` is inherited from `DirectorConsole`
and uses the Director Console API mode 2 (JSON).
For general information about API mode 2 and what data structures to expect,
see https://docs.bareos.org/DeveloperGuide/api.html#api-mode-2-json
Example:
.. code:: python
>>> import bareos.bsock
>>> directorconsole = bareos.bsock.DirectorConsoleJson(address='localhost', port=9101, password='secret')
>>> pools = directorconsole.call('list pools')
>>> for pool in pools["pools"]:
... print(pool["name"])
...
Scratch
Incremental
Full
Differential
The results the the `call` method is a ``dict`` object.
In case of an error, an exception, derived from `bareos.exceptions.Error` is raised.
Example:
.. code:: python
>>> directorconsole.call("test it")
Traceback (most recent call last):
...
bareos.exceptions.JsonRpcErrorReceivedException: failed: test it: is an invalid command.
.. _section-python-bareos-tls-psk:
Transport Encryption (TLS-PSK)
==============================
Since Bareos >= 18.2.4, Bareos supports TLS-PSK (Transport-Layer-Security Pre-Shared-Key) to secure its network connections and uses this by default.
Unfortunately the Python core module ``ssl`` does support TLS-PSK only with Python >= 3.13.
For some older versions of Python,
the extra module ``sslpsk`` (see https://github.com/drbild/sslpsk) offers limited support.
Fallback To Unencrypted Connections
-----------------------------------
Normally `DirectorConsole` tries to connect using the latest known protocol version.
In order to allow connections in more environments,
the `DirectorConsole` can fall back to older protocol versions.
Specify `protocolversion = None` (or 0 as command line argument) to enable automatic fall back.
If connecting via TLS-PSK fails, it falls back to the old, unencrypted protocol version.
Depending on your bareos-director configuration, unencrypted connections will be accepted:
.. code:: python
>>> import bareos.bsock
/.../bareos/bsock/lowlevel.py:39: UserWarning: Connection encryption via TLS-PSK is not available (TLS-PSK is not available in the ssl module and the extra module sslpsk is not installed).
>>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user-tls', password='secret', protocolversion=None)
socket error: Conversation terminated (-4)
Failed to connect using protocol version 2. Trying protocol version 1.
>>> print(directorconsole.call('help').decode("utf-8"))
To enforce a encrypted connection, use the ``tls_psk_require=True`` parameter:
.. code:: python
>>> import bareos.bsock
/.../bareos/bsock/lowlevel.py:39: UserWarning: Connection encryption via TLS-PSK is not available, as the module sslpsk is not installed.
>>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user-tls', password='secret', tls_psk_require=True)
Traceback (most recent call last):
...
bareos.exceptions.ConnectionError: TLS-PSK is required, but not available.
In this case, an exception is raised, if the connection can not be established via TLS-PSK.
sslpsk
------
The extra module `sslpsk` (see https://github.com/drbild/sslpsk)
extends the core module `ssl` by TLS-PSK.
At the time of writing, the lasted version installable via pip is 1.0.0 (https://pypi.org/project/sslpsk/),
which is not working with Python >= 3.
For using `python-bareos` with TLS-PSK with
Python >= 3 and Python <= 3.9
the latest version must by installed manually.
At the time of writing, even the latest version
(https://github.com/drbild/sslpsk/commit/d88123a75786953f82f5e25d6c43d9d9259acb62)
does not support Python >= 3.10.
However, Python >= 3.13 has direct support for TLS-PSK in the core `ssl` module.
Installing the `sslpsk` module manually:
.. code:: shell
git clone https://github.com/drbild/sslpsk.git
cd sslpsk
python setup.py build
python setup.py install
`python-bareos` will detect, that `sslpsk` is available and will use it automatically.
This can be verified by following command:
.. code:: python
>>> import bareos.bsock
>>> bareos.bsock.DirectorConsole.is_tls_psk_available()
True
Another limitation of the current `sslpsk` version is,
that it is not able to autodetect the TLS protocol version to use.
In order to use it, specify ``tls_version`` with an appropriate protocol version.
In most cases this should be ``tls_version=ssl.PROTOCOL_TLSv1_2``,
like in the following example:
.. code:: python
>>> import ssl
>>> import bareos.bsock
>>> directorconsole = bareos.bsock.DirectorConsoleJson(address='localhost', user='user-tls', password='secret', tls_version=ssl.PROTOCOL_TLSv1_2)
>>> print(directorconsole.call('help').decode("utf-8"))
Raw data
{
"_id": null,
"home_page": "https://github.com/bareos/bareos/",
"name": "python-bareos",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "bareos",
"author": "Bareos Team",
"author_email": "packager@bareos.com",
"download_url": "https://files.pythonhosted.org/packages/c0/ae/b41518dc4f277d676bb2fd068664585687dbc173b532e32ecfbaf4f8162d/python_bareos-24.0.0.tar.gz",
"platform": null,
"description": "python-bareos\n=============\n\n`python-bareos` is a Python module to access a https://www.bareos.com backup system.\n\nPackages for `python-bareos` are included in the Bareos core distribution and available via https://pypi.org/.\n\nDocumentation is available at https://docs.bareos.org/DeveloperGuide/PythonBareos.html\n\n\n.. note::\n\n By default, the Bareos Director (>= 18.2.4)\n uses TLS-PSK when communicating through the network.\n\n The Python (https://github.com/python/cpython) core module ``ssl``\n does support TLS-PSK only since Python >= 3.13.\n The section `Transport Encryption (TLS-PSK)`_ describes\n how to use TLS-PSK and about the limitations.\n For testing this module can also be used without TLS.\n\n\nPreparations\n============\n\nCreate some named consoles for testing:\n\n.. code-block:: shell-session\n\n root@host:~# bconsole\n *configure add console name=user1 password=secret profile=operator TlsEnable=no\n *configure add console name=user-tls password=secret profile=operator\n\n\nThis creates a console user with name `user1` and the profile `operator`.\nThe `operator` profile is a default profile that comes with the Bareos Director.\nIt does allow most commands, but deny some dangerous commands (see ``show profile=operator``),\nso it is well suited for this purpose.\nFuthermore, TLS enforcement is disabled for this console user.\n\nFor testing with TLS-PSK, we also create the user `user-tls`.\n\n\nExamples\n========\n\nCalling bareos-director console commands\n----------------------------------------\n\n.. code:: python\n\n >>> import bareos.bsock\n >>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user1', password='secret')\n >>> print(directorconsole.call('help').decode(\"utf-8\"))\n\nThis creates a console connection to a Bareos Director.\nThis connection can be used to `call` commands.\nThese are the same commands as available via ``bconsole``.\n\nTo connect to the default console instead, omit the `name` parameter:\n\n.. code:: python\n\n >>> directorconsole = bareos.bsock.DirectorConsole(address='localhost', port=9101, password='defaultconsolepassword')\n\nThe result of the call method is a ``bytes`` object. In most cases, it has to be decoded to UTF-8.\n\n\n\nSimple version of the bconsole in Python\n----------------------------------------\n\n.. code:: python\n\n >>> import bareos.bsock\n >>> directorconsole = bareos.bsock.DirectorConsole(address='localhost', port=9101, password='secret')\n >>> directorconsole.interactive()\n\nOr use the ``bconsole.py`` script:\n\n.. code-block:: shell-session\n\n bconsole.py --debug --name=user1 --password=secret localhost\n\n\nUse JSON objects of the API mode 2\n----------------------------------\n\nRequires: Bareos >= 15.2\n\nThe class `DirectorConsoleJson` is inherited from `DirectorConsole`\nand uses the Director Console API mode 2 (JSON).\n\nFor general information about API mode 2 and what data structures to expect,\nsee https://docs.bareos.org/DeveloperGuide/api.html#api-mode-2-json\n\nExample:\n\n.. code:: python\n\n >>> import bareos.bsock\n >>> directorconsole = bareos.bsock.DirectorConsoleJson(address='localhost', port=9101, password='secret')\n >>> pools = directorconsole.call('list pools')\n >>> for pool in pools[\"pools\"]:\n ... print(pool[\"name\"])\n ...\n Scratch\n Incremental\n Full\n Differential\n\n\nThe results the the `call` method is a ``dict`` object.\n\nIn case of an error, an exception, derived from `bareos.exceptions.Error` is raised.\n\nExample:\n\n\n.. code:: python\n\n >>> directorconsole.call(\"test it\")\n Traceback (most recent call last):\n ...\n bareos.exceptions.JsonRpcErrorReceivedException: failed: test it: is an invalid command.\n\n\n\n.. _section-python-bareos-tls-psk:\n\nTransport Encryption (TLS-PSK)\n==============================\n\nSince Bareos >= 18.2.4, Bareos supports TLS-PSK (Transport-Layer-Security Pre-Shared-Key) to secure its network connections and uses this by default.\n\nUnfortunately the Python core module ``ssl`` does support TLS-PSK only with Python >= 3.13.\nFor some older versions of Python,\nthe extra module ``sslpsk`` (see https://github.com/drbild/sslpsk) offers limited support.\n\nFallback To Unencrypted Connections\n-----------------------------------\n\nNormally `DirectorConsole` tries to connect using the latest known protocol version.\nIn order to allow connections in more environments,\nthe `DirectorConsole` can fall back to older protocol versions.\nSpecify `protocolversion = None` (or 0 as command line argument) to enable automatic fall back.\nIf connecting via TLS-PSK fails, it falls back to the old, unencrypted protocol version.\nDepending on your bareos-director configuration, unencrypted connections will be accepted:\n\n.. code:: python\n\n >>> import bareos.bsock\n /.../bareos/bsock/lowlevel.py:39: UserWarning: Connection encryption via TLS-PSK is not available (TLS-PSK is not available in the ssl module and the extra module sslpsk is not installed).\n >>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user-tls', password='secret', protocolversion=None)\n socket error: Conversation terminated (-4)\n Failed to connect using protocol version 2. Trying protocol version 1.\n >>> print(directorconsole.call('help').decode(\"utf-8\"))\n\n\nTo enforce a encrypted connection, use the ``tls_psk_require=True`` parameter:\n\n.. code:: python\n\n >>> import bareos.bsock\n /.../bareos/bsock/lowlevel.py:39: UserWarning: Connection encryption via TLS-PSK is not available, as the module sslpsk is not installed.\n >>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user-tls', password='secret', tls_psk_require=True)\n Traceback (most recent call last):\n ...\n bareos.exceptions.ConnectionError: TLS-PSK is required, but not available.\n\n\nIn this case, an exception is raised, if the connection can not be established via TLS-PSK.\n\nsslpsk\n------\n\nThe extra module `sslpsk` (see https://github.com/drbild/sslpsk)\nextends the core module `ssl` by TLS-PSK.\n\nAt the time of writing, the lasted version installable via pip is 1.0.0 (https://pypi.org/project/sslpsk/),\nwhich is not working with Python >= 3.\n\nFor using `python-bareos` with TLS-PSK with\nPython >= 3 and Python <= 3.9\nthe latest version must by installed manually.\nAt the time of writing, even the latest version\n(https://github.com/drbild/sslpsk/commit/d88123a75786953f82f5e25d6c43d9d9259acb62)\ndoes not support Python >= 3.10.\nHowever, Python >= 3.13 has direct support for TLS-PSK in the core `ssl` module.\n\nInstalling the `sslpsk` module manually:\n\n.. code:: shell\n\n git clone https://github.com/drbild/sslpsk.git\n cd sslpsk\n python setup.py build\n python setup.py install\n\n`python-bareos` will detect, that `sslpsk` is available and will use it automatically.\nThis can be verified by following command:\n\n.. code:: python\n\n >>> import bareos.bsock\n >>> bareos.bsock.DirectorConsole.is_tls_psk_available()\n True\n\nAnother limitation of the current `sslpsk` version is,\nthat it is not able to autodetect the TLS protocol version to use.\n\nIn order to use it, specify ``tls_version`` with an appropriate protocol version.\nIn most cases this should be ``tls_version=ssl.PROTOCOL_TLSv1_2``,\nlike in the following example:\n\n.. code:: python\n\n >>> import ssl\n >>> import bareos.bsock\n >>> directorconsole = bareos.bsock.DirectorConsoleJson(address='localhost', user='user-tls', password='secret', tls_version=ssl.PROTOCOL_TLSv1_2)\n >>> print(directorconsole.call('help').decode(\"utf-8\"))\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "Client library and tools for Bareos console access.",
"version": "24.0.0",
"project_urls": {
"Homepage": "https://github.com/bareos/bareos/"
},
"split_keywords": [
"bareos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6fef8f51a7e853e261f220d9fd951139ef5b93b7cb3b3e6d17e12f8460ba6928",
"md5": "33d236af90d3736448b96c85fb2e002a",
"sha256": "0e0e19a0cfe54260bb1b8711890e806da5ae5650d6b4cb60e8a23e7b7a924183"
},
"downloads": -1,
"filename": "python_bareos-24.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "33d236af90d3736448b96c85fb2e002a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 56107,
"upload_time": "2024-12-16T17:12:13",
"upload_time_iso_8601": "2024-12-16T17:12:13.437477Z",
"url": "https://files.pythonhosted.org/packages/6f/ef/8f51a7e853e261f220d9fd951139ef5b93b7cb3b3e6d17e12f8460ba6928/python_bareos-24.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c0aeb41518dc4f277d676bb2fd068664585687dbc173b532e32ecfbaf4f8162d",
"md5": "b32875b0234bf5ab8e18d637976cc886",
"sha256": "fee25b9e738ba2f3762064d7834ca7c8d91d60696cd47ed8ace6f8fb5cb58587"
},
"downloads": -1,
"filename": "python_bareos-24.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b32875b0234bf5ab8e18d637976cc886",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 37218,
"upload_time": "2024-12-16T17:12:15",
"upload_time_iso_8601": "2024-12-16T17:12:15.972759Z",
"url": "https://files.pythonhosted.org/packages/c0/ae/b41518dc4f277d676bb2fd068664585687dbc173b532e32ecfbaf4f8162d/python_bareos-24.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-16 17:12:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bareos",
"github_project": "bareos",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-bareos"
}
JSON
