This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit 9f9e5d63d17ae5248f182e2626fcd6105753d4f5 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Thu Sep 13 09:46:50 2018 +0200 x2gobroker/utils.py: Provide/improve API documentation for our utility functions. --- x2gobroker/utils.py | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 98 insertions(+), 1 deletion(-) diff --git a/x2gobroker/utils.py b/x2gobroker/utils.py index 1811ebb..8f703db 100644 --- a/x2gobroker/utils.py +++ b/x2gobroker/utils.py @@ -17,6 +17,16 @@ # Free Software Foundation, Inc., # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. +"""\ +Here you find a collection of tools that are used by X2Go Session +Broker's code internally. + +Everything that is not directly related to specific broker code and +potentially reusable at other places in the code tree, is placed into +this module. + +""" + import os import sys import locale @@ -95,6 +105,9 @@ def compare_versions(version_a, op, version_b): :param version_b: another version string that is to be compared with <version_a> :type version_b: ``str`` + :returns: if the comparison is ``True`` or ``False`` + :rtype: ``bool`` + """ ### FIXME: this comparison is not reliable with beta et al. version strings @@ -107,6 +120,29 @@ def compare_versions(version_a, op, version_b): def normalize_hostnames(servers): """\ + Take a ``list`` or ``dict`` of servers and check if they match in + their domain part and strip the domain part finally off. + + E.g., for servers provided as a ``list`` (tuple would be ok, too:: + + ['server1', 'server2'] -> ['server1', server2'] + ['server1.domain1, 'server2.domain1'] -> ['server1', server2'] + ['server1.domain1, 'server2.domain2'] -> (['server1', server2'], ['domain1', 'domain2'] + + E.g., for servers provided as a ``dict``:: + + {'server1': <whatever-params>, 'server2': <whatever-params> } -> {'server1': <whatever-params>, 'server2': <whatever-params> } + + {'server1.domain1': <whatever-params>, 'server2.domain1': <whatever-params> } -> {'server1': <whatever-params>, 'server2': <whatever-params> } + + {'server1.domain1': <whatever-params>, 'server2.domain2': <whatever-params> } -> ({'server1': <whatever-params>, 'server2': <whatever-params> }, ['domain1', 'domain2'] + + :param servers: a ``list``, ``tuple`` or ``dict`` hash with either server hostnames as items or dictionary keys + :type servers: ``list``, ``tuple`` or ``dict`` + + :returns: a ``list`` or a ``dict`` with server domains stripped of the items / keys + :rtype: ``list``, ``dict`` or ``tuple`` + """ # test the data type of servers @@ -147,7 +183,22 @@ def normalize_hostnames(servers): return servers_normalized, subdomains def matching_hostnames(server_list_a, server_list_b): + """\ + Compare two list of servers, if they have matching hostnames. + + This function tries to smoothly ship around asymmetric usage of + FQDN hostnames and short hostnames in one list. + + :param server_list_a: list of servers + :type server_list_a: ``list`` of ``str`` + :param server_list_b: list of servers to compare the first list with + :type server_list_b: ``list`` of ``str`` + :returns: a sorted list of matching server hostnames (hostnames that + appear in both provided server lists. + :returns: ``list`` of ``str`` + + """ matching_hosts = [] ### NORMALIZE (=reduce to hostname only) server names (list A) if possible @@ -169,6 +220,24 @@ def matching_hostnames(server_list_a, server_list_b): return matching_hosts def drop_privileges(uid, gid): + """\ + Drop privileges from super-user root to given ``<uid>`` and ``<gid>``. + + Only works when run as root, if run with a non-super-user account, + ``None`` is returned. + + If privileges could be dropped, the environment's HOME variable is + adapted to the new user account's home directory path. + + Also, the umask of the account we dropped privileges to is set to + ``0o077``. + + :param uid: the user ID of the user account to drop privileges to + :type uid: ``str`` + :param gid: the group ID to drop privileges to + :type gid: ``str`` + + """ if os.getuid() != 0: # We're not root so, like, whatever dude return @@ -191,7 +260,28 @@ def drop_privileges(uid, gid): os.environ['HOME'] = pwd.getpwnam(uid).pw_dir def split_host_address(host, default_address=None, default_port=22): + """\ + Try to split a ``<host_addr>:<port>`` expression into hostname and port. + + This function is supposed to work with DNS hostnames, IPv4 and IPv6 + address. + + Both parts (<host_addr> and <port>) can be omitted in the given + ``host`` string. If so, ``default_address`` and ``default_port`` come + into play. + + :param host: an expression like ``<host_addr>:<port>`` (where either + the host address or the port can be optional) + :type host: ``str`` + :param default_address: a fallback host address to be used (default: None) + :type default_address: ``str`` + :param default_port: a fallback port to be used (default: 22) + :type default_port: ``int`` + :returns: a tuple of host address and port + :rtype: ``tuple(<host_addr>, <port>)`` + + """ if type(host) is int: host = str(host) # do some stripping first... @@ -244,7 +334,7 @@ def split_host_address(host, default_address=None, default_port=22): def portscan(addr, port=22): """\ - Performing a port scan to the requested hostname. + Perform a port scan to the requested hostname. :param addr: address (IPv4, IPv6 or hostname) of the host we want to probe @@ -252,6 +342,9 @@ def portscan(addr, port=22): :param port: port number (default: 22) :type port: ``int`` + :returns: ``True`` if the port is in use, else ``False`` (also on errors) + :rtype: ``bool`` + """ ip_proto = 0 try: @@ -289,6 +382,8 @@ def get_key_fingerprint(key): """\ Retrieve the host key fingerprint of the server to be validated. + :param key: a Python Paramik :class:`PKey`` object + :type key: ``PKey`` :returns: host key fingerprint :rtype: ``str`` @@ -300,6 +395,8 @@ def get_key_fingerprint_with_colons(key): Retrieve the (colonized) host key fingerprint of the server to be validated. + :param key: a Python Paramik :class:`PKey`` object + :type key: ``PKey`` :returns: host key fingerprint (with colons) :rtype: ``str`` -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git