python-bareos
=============
`python-bareos` is a Python module to access a http://www.bareos.org 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.
Unfortunately the Python core module ``ssl``
does not support TLS-PSK.
For testing ``python-bareos`` should be used without TLS.
The section `Transport Encryption (TLS-PSK)`_ describes
how to use ``python-bareos`` with TLS-PSK
and about the limitations.
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. It only 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 included ``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.
Unfortenatly, the Python core module `ssl` does not support TLS-PSK.
There is limited support by the extra module `sslpsk` (see https://github.com/drbild/sslpsk).
Fallback To Unencrypted Connections
-----------------------------------
In order to work in most cases, even if ``sslpsk`` is not available,
the `DirectorConsole` uses a fallback.
If connecting via TLS-PSK fails, it falls back to the old, unencrypted protocol version.
In this case, a warning is issued, but the connection will work nevertheless:
.. 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')
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 sslpsk module not loaded/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.
If `python-bareos` should use TLS-PSK with Python >= 3,
the latest version must by installed 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": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "bareos",
"author": "Bareos Team",
"author_email": "packager@bareos.com",
"download_url": "https://files.pythonhosted.org/packages/30/2b/536271c36c649c6f83ab7a065399b7c7dd7a1bbc6345747c589d5609810b/python-bareos-23.0.2.tar.gz",
"platform": null,
"description": "python-bareos\n=============\n\n`python-bareos` is a Python module to access a http://www.bareos.org 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.. note::\n\n By default, the Bareos Director (>= 18.2.4) uses TLS-PSK when communicating through the network.\n\n Unfortunately the Python core module ``ssl``\n does not support TLS-PSK.\n For testing ``python-bareos`` should be used without TLS.\n The section `Transport Encryption (TLS-PSK)`_ describes\n how to use ``python-bareos`` with TLS-PSK\n and about the limitations.\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. It only 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\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 included ``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\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\nUnfortenatly, the Python core module `ssl` does not support TLS-PSK.\nThere is limited support by the extra module `sslpsk` (see https://github.com/drbild/sslpsk).\n\nFallback To Unencrypted Connections\n-----------------------------------\n\nIn order to work in most cases, even if ``sslpsk`` is not available,\nthe `DirectorConsole` uses a fallback.\nIf connecting via TLS-PSK fails, it falls back to the old, unencrypted protocol version.\nIn this case, a warning is issued, but the connection will work nevertheless:\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')\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\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 sslpsk module not loaded/available.\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/), which is not working with Python >= 3.\n\nIf `python-bareos` should use TLS-PSK with Python >= 3,\nthe latest version must by installed 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": "23.0.2",
"project_urls": {
"Homepage": "https://github.com/bareos/bareos/"
},
"split_keywords": [
"bareos"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae4fe2d21c49313461d0b1c46c92206e78c1ad397ba3e8b0592f295fb046d029",
"md5": "19e8eeb9d877ec7fe69c7a8641830e09",
"sha256": "e4c7475b10418a788994ef25625f1da01e1aabc0a9d7f4ae7cbca385d934c5c4"
},
"downloads": -1,
"filename": "python_bareos-23.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "19e8eeb9d877ec7fe69c7a8641830e09",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 55211,
"upload_time": "2024-02-28T13:22:01",
"upload_time_iso_8601": "2024-02-28T13:22:01.424461Z",
"url": "https://files.pythonhosted.org/packages/ae/4f/e2d21c49313461d0b1c46c92206e78c1ad397ba3e8b0592f295fb046d029/python_bareos-23.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "302b536271c36c649c6f83ab7a065399b7c7dd7a1bbc6345747c589d5609810b",
"md5": "1cb88a0c668e7519e0f252a4cc6c7f5c",
"sha256": "b11ace255493d6f3f9589738541e39b086c3f464b81db5120e61e80a5569f77e"
},
"downloads": -1,
"filename": "python-bareos-23.0.2.tar.gz",
"has_sig": false,
"md5_digest": "1cb88a0c668e7519e0f252a4cc6c7f5c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 36368,
"upload_time": "2024-02-28T13:22:03",
"upload_time_iso_8601": "2024-02-28T13:22:03.096668Z",
"url": "https://files.pythonhosted.org/packages/30/2b/536271c36c649c6f83ab7a065399b7c7dd7a1bbc6345747c589d5609810b/python-bareos-23.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-28 13:22:03",
"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
