python-bareos 23.0.2__tar.gz → 23.0.4__tar.gz

{python-bareos-23.0.2 → python_bareos-23.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-bareos
-Version: 23.0.2
+Version: 23.0.4
 Summary: Client library and tools for Bareos console access.
 Home-page: https://github.com/bareos/bareos/
 Author: Bareos Team
@@ -15,30 +15,29 @@ Classifier: Topic :: System :: Archiving :: Backup
 Requires-Python: >=3.6
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
-Provides-Extra: tls-psk
-Requires-Dist: sslpsk; extra == "tls-psk"
 Provides-Extra: configfile
 Requires-Dist: configargparse; extra == "configfile"
 
 python-bareos
 =============
 
-`python-bareos` is a Python module to access a http://www.bareos.org backup system.
+`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.
+   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 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 ``python-bareos`` with TLS-PSK
-   and about the limitations.
+   how to use TLS-PSK and about the limitations.
+   For testing this module can also be used without TLS.
 
 
 Preparations
@@ -55,12 +54,13 @@ Create some named consoles for testing:
 
 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``),
+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
 ========
 
@@ -96,7 +96,7 @@ Simple version of the bconsole in Python
    >>> directorconsole = bareos.bsock.DirectorConsole(address='localhost', port=9101, password='secret')
    >>> directorconsole.interactive()
 
-Or use the included ``bconsole.py`` script:
+Or use the ``bconsole.py`` script:
 
 .. code-block:: shell-session
 
@@ -129,9 +129,10 @@ Example:
    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.
+In case of an error, an exception, derived from `bareos.exceptions.Error` is raised.
 
 Example:
 
@@ -152,26 +153,30 @@ 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).
+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
 -----------------------------------
 
-In order to work in most cases, even if ``sslpsk`` is not available,
-the `DirectorConsole` uses a fallback.
+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.
-In this case, a warning is issued, but the connection will work nevertheless:
+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, as the module sslpsk is not installed.
-   >>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user-tls', password='secret')
+   /.../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
@@ -180,8 +185,9 @@ To enforce a encrypted connection, use the ``tls_psk_require=True`` parameter:
    /.../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.
+   ...
+   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.
 
@@ -191,10 +197,18 @@ 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.
+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.
 
-If `python-bareos` should use TLS-PSK with Python >= 3,
-the latest version must by installed manually:
+Installing the `sslpsk` module manually:
 
 .. code:: shell
 

python_bareos-23.0.4/README.rst

@@ -0,0 +1,8 @@
+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

python_bareos-23.0.4/bareos/VERSION.txt

@@ -0,0 +1 @@
+23.0.4

{python-bareos-23.0.2 → python_bareos-23.0.4}/bareos/bsock/__init__.py

@@ -1,6 +1,6 @@
 #   BAREOS - Backup Archiving REcovery Open Sourced
 #
-#   Copyright (C) 2016-2020 Bareos GmbH & Co. KG
+#   Copyright (C) 2016-2024 Bareos GmbH & Co. KG
 #
 #   This program is Free Software; you can redistribute it and/or
 #   modify it under the terms of version three of the GNU Affero General Public
@@ -17,17 +17,18 @@
 #   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 #   02110-1301, USA.
 
-"""Module to access a http://www.bareos.org backup system.
+"""Module to access a https://www.bareos.com backup system.
 
 .. note::
 
-   By default, the Bareos Director (>= 18.2.4) uses TLS-PSK when communicating through the network.
+   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 this module should be used without TLS.
+   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
@@ -44,7 +45,7 @@ Create some named consoles for testing:
 
 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``),
+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.
 
@@ -119,6 +120,7 @@ Example:
    Full
    Differential
 
+
 The results the the `call` method is a ``dict`` object.
 
 In case of an error, an exception, derived from :py:class:`bareos.exceptions.Error` is raised.
@@ -142,22 +144,25 @@ 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).
+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
 -----------------------------------
 
-In order to work in most cases, even if ``sslpsk`` is not available,
-the `DirectorConsole` uses a fallback.
+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.
-In this case, a warning is issued, but the connection will work nevertheless:
+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, as the module sslpsk is not installed.
-   >>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user-tls', password='secret')
+   /.../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"))
@@ -172,7 +177,7 @@ To enforce a encrypted connection, use the ``tls_psk_require=True`` parameter:
    >>> 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.
+   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.
@@ -183,10 +188,18 @@ 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.
+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.
 
-If `python-bareos` should use TLS-PSK with Python >= 3,
-the latest version must by installed manually:
+Installing the `sslpsk` module manually:
 
 .. code:: shell
 

{python-bareos-23.0.2 → python_bareos-23.0.4}/bareos/bsock/directorconsole.py

@@ -68,7 +68,7 @@ class DirectorConsole(LowLevel):
         group.add_argument(
             "--name",
             default="*UserAgent*",
-            help='use this to access a specific Bareos director named console. Otherwise it connects to the default console ("*UserAgent*").',
+            help='use this to access a specific Bareos director named console. Otherwise it connects to the default console ("%(default)s").',
             dest="BAREOS_name",
         )
 
@@ -83,7 +83,7 @@ class DirectorConsole(LowLevel):
         group.add_argument(
             "--port",
             default=9101,
-            help="Bareos Director network port.",
+            help="Bareos Director network port. Default: %(default)s.",
             dest="BAREOS_port",
         )
 
@@ -91,7 +91,7 @@ class DirectorConsole(LowLevel):
         group.add_argument(
             "--address",
             default="localhost",
-            help="Bareos Director network address.",
+            help="Bareos Director network address. Default: %(default)s.",
             dest="BAREOS_address",
         )
 
@@ -104,9 +104,11 @@ class DirectorConsole(LowLevel):
 
         group.add_argument(
             "--protocolversion",
-            default=ProtocolVersions.last,
             type=int,
-            help="Specify the Bareos console protocol version. Default: %(default)s (current).",
+            choices=set(protocolversion.value for protocolversion in ProtocolVersions)
+            | set([0]),
+            default=ProtocolVersions.last.value,
+            help="Specify the Bareos console protocol version (0: auto-detect, %(default)s: latest). Default: %(default)s.",
             dest="BAREOS_protocolversion",
         )
 
@@ -124,7 +126,7 @@ class DirectorConsole(LowLevel):
 
         group.add_argument(
             "--tls-psk-require",
-            help="Allow only encrypted connections. Default: False.",
+            help="Allow only encrypted connections. Default: %(default)s.",
             action="store_true",
             dest="BAREOS_tls_psk_require",
         )
@@ -192,7 +194,7 @@ class DirectorConsole(LowLevel):
         if tls_version is not None:
             self.tls_version = tls_version
         self.identity_prefix = "R_CONSOLE"
-        if protocolversion is not None:
+        if protocolversion is not None and protocolversion > 0:
             self.requested_protocol_version = int(protocolversion)
             self.protocol_messages.set_version(self.requested_protocol_version)
         self.connect(

{python-bareos-23.0.2 → python_bareos-23.0.4}/bareos/bsock/lowlevel.py

@@ -46,17 +46,26 @@ from bareos.util.bareosbase64 import BareosBase64
 from bareos.util.password import Password
 import bareos.exceptions
 
-# Try to load the sslpsk module,
-# with implement TLS-PSK (Transport Layer Security - Pre-Shared-Key)
-# on top of the ssl module.
-# If it is not available, we continue anyway,
+# The ssl module support TLS-PSK (Transport Layer Security - Pre-Shared-Key)
+# since Python >= 3.13.
+# For some older Python versions, the TLS-PSK functionality
+# can be added by the sslpsk module,
+# with implement TLS-PSK on top of the ssl module.
+# If it is also not available, we continue anyway,
 # but don't use TLS-PSK.
-try:
-    import sslpsk
-except ImportError:
-    warnings.warn(
-        "Connection encryption via TLS-PSK is not available, as the module sslpsk is not installed."
-    )
+if not getattr(ssl, "HAS_PSK", False):
+
+    def format_warning_short(message, category, filename, lineno, line=""):
+        return f"{category.__name__}: {message}\n"
+
+    warnings.formatwarning = format_warning_short
+    try:
+        import sslpsk
+    except ImportError:
+        warnings.warn(
+            "Connection encryption via TLS-PSK is not available "
+            "(not available in 'ssl' and extra module 'sslpsk' is not installed)."
+        )
 
 
 class LowLevel(object):
@@ -182,7 +191,7 @@ class LowLevel(object):
         if self.tls_psk_require:
             if not self.is_tls_psk_available():
                 raise bareos.exceptions.ConnectionError(
-                    "TLS-PSK is required, but sslpsk module not loaded/available."
+                    "TLS-PSK is required, but not available."
                 )
             if not self.tls_psk_enable:
                 raise bareos.exceptions.ConnectionError(
@@ -267,23 +276,32 @@ class LowLevel(object):
         else:
             raise bareos.exceptions.ConnectionError("No password provided.")
         self.logger.debug("identity = {0}, password = {1}".format(identity, password))
-        try:
-            self.socket = sslpsk.wrap_socket(
-                client_socket,
-                ssl_version=self.tls_version,
-                ciphers="ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH",
-                psk=(password, identity),
-                server_side=False,
-            )
-        except ssl.SSLError as e:
-            # raise ConnectionError(
-            #     "failed to connect to host {0}, port {1}: {2}".format(self.address, self.port, str(e)))
-            # Using a general raise keep more information about the type of error.
-            raise
+        ciphers = "ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH"
+
+        if getattr(ssl, "HAS_PSK", False):
+            context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+            context.check_hostname = False
+            context.set_ciphers(ciphers)
+            context.set_psk_client_callback(lambda hint: (identity, password))
+            self.socket = context.wrap_socket(client_socket, server_side=False)
+        else:
+            try:
+                self.socket = sslpsk.wrap_socket(
+                    client_socket,
+                    ssl_version=self.tls_version,
+                    ciphers=ciphers,
+                    psk=(password, identity),
+                    server_side=False,
+                )
+            except ssl.SSLError as e:
+                # raise ConnectionError(
+                #     "failed to connect to host {0}, port {1}: {2}".format(self.address, self.port, str(e)))
+                # Using a general raise to keep more information about the type of error.
+                raise
         return True
 
     def get_tls_psk_identity(self):
-        """Bareos TLS-PSK excepts the identiy is a specific format."""
+        """Bareos TLS-PSK excepts the identity is a specific format."""
         name = str(self.name)
         if isinstance(self.name, bytes):
             name = self.name.decode("utf-8")
@@ -294,8 +312,8 @@ class LowLevel(object):
 
     @staticmethod
     def is_tls_psk_available():
-        """Checks if we have all required modules for TLS-PSK."""
-        return "sslpsk" in sys.modules
+        """Checks if TLS-PSK is available."""
+        return getattr(ssl, "HAS_PSK", False) or ("sslpsk" in sys.modules)
 
     def get_protocol_version(self):
         """Get the Bareos Console protocol version that is used.
@@ -524,7 +542,7 @@ class LowLevel(object):
         msg = self.recv_submsg(length)
         return msg
 
-    def recv_msg(self, regex=b"^\d\d\d\d OK.*$"):
+    def recv_msg(self, regex=b"^\\d\\d\\d\\d OK.*$"):
         """Receive a full message.
 
         It retrieves messages (header + message text),

{python-bareos-23.0.2 → python_bareos-23.0.4}/bareos/bsock/protocolversions.py

@@ -1,6 +1,6 @@
 #   BAREOS - Backup Archiving REcovery Open Sourced
 #
-#   Copyright (C) 2019-2021 Bareos GmbH & Co. KG
+#   Copyright (C) 2019-2024 Bareos GmbH & Co. KG
 #
 #   This program is Free Software; you can redistribute it and/or
 #   modify it under the terms of version three of the GNU Affero General Public
@@ -21,8 +21,10 @@
 Bareos Protocol Versions.
 """
 
+from enum import IntEnum
 
-class ProtocolVersions(object):
+
+class ProtocolVersions(IntEnum):
     """
     Bareos Protocol Versions.
     """

{python-bareos-23.0.2 → python_bareos-23.0.4}/bareos/bsock/tlsversionparser.py

@@ -1,6 +1,6 @@
 #   BAREOS - Backup Archiving REcovery Open Sourced
 #
-#   Copyright (C) 2020-2021 Bareos GmbH & Co. KG
+#   Copyright (C) 2020-2024 Bareos GmbH & Co. KG
 #
 #   This program is Free Software; you can redistribute it and/or
 #   modify it under the terms of version three of the GNU Affero General Public
@@ -57,7 +57,7 @@ class TlsVersionParser:
     def add_argument(self, argparser):
         argparser.add_argument(
             "--tls-version",
-            help="Use a specific TLS protocol version.",
+            help="Use a specific TLS protocol version (only used with the sslpsk module).",
             action=ArgParserTlsVersionAction,
             choices=OrderedDict(sorted(self.tls_version_options.items())),
             dest="BAREOS_tls_version",

{python-bareos-23.0.2 → python_bareos-23.0.4}/bareos/util/argparse.py

@@ -24,6 +24,8 @@ Uses configargparse, if available,
 otherwise, falls back to argparse.
 """
 
+from pprint import pformat
+
 HAVE_CONFIG_ARG_PARSE_MODULE = False
 try:
     import configargparse as argparse
@@ -42,3 +44,9 @@ class ArgumentParser(argparse.ArgumentParser):
             self.add_argument(
                 "-c", "--config", is_config_file=True, help="Config file path."
             )
+
+    def format_values(self):
+        try:
+            return super().format_values()
+        except AttributeError:
+            return pformat(vars(self.parse_args()))

{python-bareos-23.0.2 → python_bareos-23.0.4}/bin/bareos-fd-connect.py

@@ -58,6 +58,6 @@ if __name__ == "__main__":
         sys.exit(1)
     logger.debug("authentication successful")
     if args.command:
-        print(bsock.call(args.command))
+        print(bsock.call(args.command).decode("utf-8"))
     else:
         bsock.interactive()

{python-bareos-23.0.2 → python_bareos-23.0.4}/python_bareos.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-bareos
-Version: 23.0.2
+Version: 23.0.4
 Summary: Client library and tools for Bareos console access.
 Home-page: https://github.com/bareos/bareos/
 Author: Bareos Team
@@ -15,30 +15,29 @@ Classifier: Topic :: System :: Archiving :: Backup
 Requires-Python: >=3.6
 Description-Content-Type: text/x-rst
 License-File: LICENSE.txt
-Provides-Extra: tls-psk
-Requires-Dist: sslpsk; extra == "tls-psk"
 Provides-Extra: configfile
 Requires-Dist: configargparse; extra == "configfile"
 
 python-bareos
 =============
 
-`python-bareos` is a Python module to access a http://www.bareos.org backup system.
+`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.
+   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 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 ``python-bareos`` with TLS-PSK
-   and about the limitations.
+   how to use TLS-PSK and about the limitations.
+   For testing this module can also be used without TLS.
 
 
 Preparations
@@ -55,12 +54,13 @@ Create some named consoles for testing:
 
 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``),
+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
 ========
 
@@ -96,7 +96,7 @@ Simple version of the bconsole in Python
    >>> directorconsole = bareos.bsock.DirectorConsole(address='localhost', port=9101, password='secret')
    >>> directorconsole.interactive()
 
-Or use the included ``bconsole.py`` script:
+Or use the ``bconsole.py`` script:
 
 .. code-block:: shell-session
 
@@ -129,9 +129,10 @@ Example:
    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.
+In case of an error, an exception, derived from `bareos.exceptions.Error` is raised.
 
 Example:
 
@@ -152,26 +153,30 @@ 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).
+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
 -----------------------------------
 
-In order to work in most cases, even if ``sslpsk`` is not available,
-the `DirectorConsole` uses a fallback.
+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.
-In this case, a warning is issued, but the connection will work nevertheless:
+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, as the module sslpsk is not installed.
-   >>> directorconsole=bareos.bsock.DirectorConsole(address='localhost', port=9101, name='user-tls', password='secret')
+   /.../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
@@ -180,8 +185,9 @@ To enforce a encrypted connection, use the ``tls_psk_require=True`` parameter:
    /.../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.
+   ...
+   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.
 
@@ -191,10 +197,18 @@ 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.
+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.
 
-If `python-bareos` should use TLS-PSK with Python >= 3,
-the latest version must by installed manually:
+Installing the `sslpsk` module manually:
 
 .. code:: shell
 

{python-bareos-23.0.2 → python_bareos-23.0.4}/python_bareos.egg-info/requires.txt

@@ -1,6 +1,3 @@
 
-[TLS-PSK]
-sslpsk
-
 [configfile]
 configargparse

{python-bareos-23.0.2 → python_bareos-23.0.4}/setup.py

@@ -47,6 +47,21 @@ def get_version():
     return __version__
 
 
+def get_long_description():
+    base_dir = os.path.abspath(os.path.dirname(__file__))
+    with open("README.rst") as readme_file:
+        description = readme_file.read()
+    with open(os.path.join(base_dir, "bareos", "bsock", "__init__.py")) as bsock_file:
+        bsock_content = bsock_file.read().strip()
+    # bsock_description = re.sub(r'.*"""(.*?)""".*', r'\1', bsock_content, flags=re.DOTALL)
+    bsock_description = re.sub(
+        ":py:class:",
+        "",
+        re.sub(r'.*(\.\. note::.*?)""".*', r"\n\n\1", bsock_content, flags=re.DOTALL),
+    )
+    return description + bsock_description
+
+
 setup(
     name="python-bareos",
     version=get_version(),
@@ -60,11 +75,11 @@ setup(
     # What does your project relate to?
     keywords="bareos",
     description="Client library and tools for Bareos console access.",
-    long_description=open("README.rst").read(),
+    long_description=get_long_description(),
     long_description_content_type="text/x-rst",
     # RHEL7: python-3.6
     python_requires=">=3.6",
-    extras_require={"TLS-PSK": ["sslpsk"], "configfile": ["configargparse"]},
+    extras_require={"configfile": ["configargparse"]},
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "License :: OSI Approved :: GNU Affero General Public License v3",

python-bareos-23.0.2/README.rst

@@ -1,205 +0,0 @@
-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"))

python-bareos-23.0.2/bareos/VERSION.txt

@@ -1 +0,0 @@
-23.0.2