Saimon/create array with all drives (#124)

Features:
1) Create an array using all available drives if no drive was specified
2) Support modfiying the Portal's time zone
3) List templates by name
4) Configure template auto assignment policy
5) Support managing the Portal's SSL certificate (import, export)
6) Support SNMP configuration APIs, unittests and docs

Technical improvements:
* Add docs for auto template assignment, SSL certificates and timezone
* Use from X import Y when needed
* Use rsplit with maxsplit 1 when getting the last value
* Use "with" when reading from files
* __all__ definitions - no need to map str method to strings

Author: saimonation

cterasdk/core/enum.py

@@ -459,3 +459,26 @@ class Platform:
     Linux = 'LinuxX86'
     Windows = 'WindowsX86'
     OSX = 'OSxX86'
+
+
+class TemplateCriteria:
+    """
+    Configuration Template Auto Assignment Rule Builder Criterias
+
+    :ivar str Type: Device type
+    :ivar str OperatingSystem: Operating system
+    :ivar str Version: Installed software version
+    :ivar str Hostname: Hostname
+    :ivar str Name: Device name
+    :ivar str Owner: Device owner username
+    :ivar str Plan: Plan name
+    :ivar str Groups: Device owner local or domain groups
+    """
+    Type = 'DeviceType'
+    OperatingSystem = 'OperatingSystem'
+    Version = 'InstalledSoftwareVersion'
+    Hostname = 'Hostname'
+    Name = 'DeviceName'
+    Owner = 'OwnerUsername'
+    Plan = 'Plan'
+    Groups = 'ownerGroups'

cterasdk/core/settings.py

@@ -0,0 +1,35 @@
+import logging
+
+from .base_command import BaseCommand
+
+
+class Settings(BaseCommand):
+    """
+    Portal Settings APIs
+
+    :ivar cterasdk.core.settings.GlobalSettings global_settings: Object holding the Portal Global Settings APIs
+    """
+
+    def __init__(self, portal):
+        super().__init__(portal)
+        self.global_settings = GlobalSettings(self._portal)
+
+
+class GlobalSettings(BaseCommand):
+
+    def get_timezone(self):
+        """
+        Get timezone
+        """
+        return self._portal.get('/settings/timezone')
+
+    def set_timezone(self, timezone):
+        """
+        Set timezone
+
+        :param str timezone: Timezone
+        """
+        logging.getLogger().info('Updating timezone. %s', {'timezone': timezone})
+        response = self._portal.put('/settings/timezone', timezone)
+        logging.getLogger().info('Updated timezone. %s', {'timezone': timezone})
+        return response

cterasdk/core/ssl.py

@@ -0,0 +1,110 @@
+import logging
+from zipfile import ZipFile
+
+from .base_command import BaseCommand
+from ..lib import FileSystem, X509Certificate, TempfileServices, create_certificate_chain
+
+
+class SSL(BaseCommand):
+    """
+    Portal SSL Certificate APIs
+    """
+
+    def __init__(self, portal):
+        super().__init__(portal)
+        self._filesystem = FileSystem.instance()
+
+    def get(self):
+        """
+        Retrieve details of the current installed SSL certificate
+
+        :return cterasdk.common.object.Object: An object including the SSL certificate details
+        """
+        logging.getLogger().info('Retrieving SSL certificate')
+        response = self._portal.get('/settings/ca')
+        logging.getLogger().info('Retrieved SSL certificate')
+        return response
+
+    @property
+    def thumbprint(self):
+        """
+        Get the SHA1 thumbprint of the Portal SSL certificate
+        """
+        return self.get().thumbprint
+
+    def export(self, destination=None):
+        """
+        Export the Portal SSL Certificate to a ZIP archive
+
+        :param str,optional destination:
+         File destination, defaults to the default directory
+        """
+        directory, filename = self._filesystem.split_file_directory_with_defaults(destination, 'certificate.zip')
+        logging.getLogger().info('Exporting SSL certificate.')
+        handle = self._portal.openfile('/admin/preview/exportCertificate', use_file_url=True)
+        filepath = self._filesystem.save(directory, filename, handle)
+        logging.getLogger().info('Exported SSL certificate. %s', {'filepath': filepath})
+        return filepath
+
+    def create_zip_archive(self, private_key, *certificates):
+        """
+        Create a ZIP archive that can be imported to CTERA Portal
+
+        :param str private_key: A path to the PEM-encoded private key file
+        :param list[str] certificates: A list of paths of the PEM-encoded certificate files
+        """
+        tempdir = TempfileServices.mkdir()
+
+        key_basename = 'private.key'
+        private_keyfile = self._filesystem.copyfile(private_key, FileSystem.join(tempdir, key_basename))
+
+        cert_basename = 'certificate'
+        certificates = [X509Certificate.from_file(certificate) for certificate in certificates]
+        certificate_chain = create_certificate_chain(*certificates)
+
+        certificate_chain_zip_archive = None
+        if certificate_chain:
+            certificate_chain_zip_archive = FileSystem.join(tempdir, '{}.zip'.format(cert_basename))
+            with ZipFile(certificate_chain_zip_archive, 'w') as zip_archive:
+                zip_archive.write(private_keyfile, key_basename)
+                for idx, certificate in enumerate(certificate_chain):
+                    filename = '{}{}.crt'.format(cert_basename, idx if idx > 0 else '')
+                    filepath = FileSystem.join(tempdir, filename)
+                    self._filesystem.write(filepath, certificate.pem_data)
+                    zip_archive.write(filepath, filename)
+
+        return certificate_chain_zip_archive
+
+    def import_from_zip(self, zipfile):
+        """
+        Import an SSL Certificate to CTERA Portal from a ZIP archive
+
+        :param str zipfile: A zip archive including the private key and SSL certificate chain
+        """
+        return self._import_certificate(zipfile)
+
+    def import_from_chain(self, private_key, *certificates):
+        """
+        Import an SSL Certificate to CTERA Portal from a chain
+
+        :param str private_key: A path to the PEM-encoded private key file
+        :param list[str] certificates: A list of paths to the PEM-encoded certificates
+        """
+        zipflie = self.create_zip_archive(private_key, *certificates)
+        return self.import_from_zip(zipflie)
+
+    def _import_certificate(self, zipfile):
+        info = self._filesystem.get_local_file_info(zipfile)
+        logging.getLogger().info('Uploading SSL certificate.')
+        with open(zipfile, 'rb') as fd:
+            response = self._portal.upload(
+                '/settings/importCertificate',
+                dict(
+                    name='upload',
+                    certificate=(info['name'], fd, info['mimetype'][0])
+                )
+            )
+            if not isinstance(response, str):
+                logging.getLogger().error('Failed uploading SSL certificate. %s', {'reason': response.msg})
+            logging.getLogger().info('Uploaded SSL certificate.')
+            self._portal.startup.wait()

cterasdk/core/templates.py

@@ -1,6 +1,6 @@
 import logging
 
-from ..common import union, parse_base_object_ref, ApplicationBackupSet, Object
+from ..common import union, parse_base_object_ref, ApplicationBackupSet, PolicyRuleConverter, Object
 from ..exception import CTERAException
 from .base_command import BaseCommand
 from . import query
@@ -113,15 +113,35 @@ def _create_template_firmware(platform, base_object_ref):
         param.firmware = base_object_ref
         return param
 
-    def list_templates(self, include=None):
+    def by_name(self, names, include=None):
+        """
+        Get Templates by their names
+
+        :param list[str],optional names: List of names of templates
+        :param list[str],optional include: List of fields to retrieve, defaults to ['name']
+        :param list[cterasdk.core.query.FilterBuilder],optional filters: List of additional filters, defaults to None
+
+        :return: Iterator for all matching Templates
+        :rtype: cterasdk.lib.iterator.Iterator
+        """
+        filters = [query.FilterBuilder('name').eq(name) for name in names]
+        return self.list_templates(include, filters)
+
+    def list_templates(self, include=None, filters=None):
         """
         List Configuration Templates.\n
         To retrieve templates, you must first browse the tenant, using: `GlobalAdmin.portals.browse()`
 
         :param list[str],optional include: List of fields to retrieve, defaults to ``['name']``
+        :param list[],optional filters: List of additional filters, defaults to None
         """
         include = union(include or [], Templates.default)
-        param = query.QueryParamBuilder().include(include).build()
+        builder = query.QueryParamBuilder().include(include)
+        if filters:
+            for query_filter in filters:
+                builder.addFilter(query_filter)
+            builder.orFilter((len(filters) > 1))
+        param = builder.build()
         return query.iterator(self._portal, '/deviceTemplates', param)
 
     def delete(self, name):
@@ -168,6 +188,51 @@ def remove_default(self, name, wait=False):
 
 class TemplateAutoAssignPolicy(BaseCommand):
 
+    def get_policy(self):
+        """
+        Get templates auto assignment policy
+        """
+        return self._portal.execute('', 'getAutoAssignmentRules')
+
+    def set_policy(self, rules, apply_default=None, default=None, apply_changes=True):
+        """
+        Set templates auto assignment policy
+
+        :param list[cterasdk.common.types.PolicyRule] rules: List of policy rules
+        :param bool,optional apply_default: If no match found, apply default template. If not passed, the current config will be kept
+        :param str,optional default: Name of a template to assign if no match found. Ignored unless the ``apply_default`` is set to ``True``
+        :param bool,optional apply_changes: Apply changes upon update, defaults to ``True``
+        """
+        templates = {rule.assignment for rule in rules}
+        if default:
+            templates.add(default)
+        templates = list(templates)
+        portal_templates = {template.name: template for template in self._portal.templates.by_name(templates, ['baseObjectRef'])}
+
+        not_found = [template for template in templates if template not in portal_templates.keys()]
+        if not_found:
+            logging.getLogger().error('Could not find one or more templates. %s', {'templates': not_found})
+            raise CTERAException('Could not find one or more templates', None, templates=not_found)
+
+        policy = self.get_policy()
+
+        if apply_default is False:
+            policy.defaultTemplate = None
+        elif apply_default is True and default:
+            policy.defaultTemplate = portal_templates.get(default).baseObjectRef
+
+        policy_rules = [PolicyRuleConverter.convert(rule, 'DeviceTemplateAutoAssignmentRule', 'template',
+                        portal_templates.get(rule.assignment).baseObjectRef) for rule in rules]
+        policy.deviceTemplatesAutoAssignmentRules = policy_rules
+
+        response = self._portal.execute('', 'setAutoAssignmentRules', policy)
+        logging.getLogger().info('Set templates auto assignment rules.')
+
+        if apply_changes:
+            self.apply_changes(True)
+
+        return response
+
     def apply_changes(self, wait=False):
         """
         Apply provisioning changes.\n

cterasdk/core/types.py

@@ -2,7 +2,7 @@
 from collections import namedtuple
 from ..common import DateTimeUtils, StringCriteriaBuilder, ListCriteriaBuilder, Object
 
-from .enum import PortalAccountType, CollaboratorType, FileAccessMode, PlanCriteria, BucketType, LocationType
+from .enum import PortalAccountType, CollaboratorType, FileAccessMode, PlanCriteria, TemplateCriteria, BucketType, LocationType
 
 
 CloudFSFolderFindingHelper = namedtuple('CloudFSFolderFindingHelper', ('name', 'owner'))
@@ -230,6 +230,43 @@ def comment():
         return StringCriteriaBuilder(PlanCriteriaBuilder.Type, PlanCriteria.Comment)
 
 
+class TemplateCriteriaBuilder:
+
+    Type = 'DeviceCriteria'
+
+    @staticmethod
+    def type():
+        return ListCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.Type)
+
+    @staticmethod
+    def os():
+        return StringCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.OperatingSystem)
+
+    @staticmethod
+    def version():
+        return StringCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.Version)
+
+    @staticmethod
+    def hostname():
+        return StringCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.Hostname)
+
+    @staticmethod
+    def name():
+        return StringCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.Name)
+
+    @staticmethod
+    def owner():
+        return StringCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.Owner)
+
+    @staticmethod
+    def plan():
+        return StringCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.Plan)
+
+    @staticmethod
+    def groups():
+        return StringCriteriaBuilder(TemplateCriteriaBuilder.Type, TemplateCriteria.Groups)
+
+
 class Bucket:
 
     def __init__(self, bucket, driver):

cterasdk/edge/array.py

@@ -11,22 +11,23 @@ class Array(BaseCommand):
     def get(self, name=None):
         """
         Get Array. If an array name was not passed as an argument, a list of all arrays will be retrieved
+
         :param str,optional name: Name of the array
         """
         return self._gateway.get('/config/storage/arrays' + ('' if name is None else ('/' + name)))
 
-    def add(self, array_name, level, members):
+    def add(self, array_name, level, members=None):
         """
         Add a new array
 
         :param str array_name: Name for the new array
         :param RAIDLevel level: RAID level
-        :param list(str) members: Members of the array
+        :param list(str) members: Members of the array. If not specified, the system will try to create an array using all available drives
         """
         param = Object()
         param.name = array_name
         param.level = level
-        param.members = members
+        param.members = [drive.name for drive in self._gateway.drive.get_status()] if members is None else members
 
         try:
             logging.getLogger().info("Creating a storage array.")

cterasdk/edge/config.py

@@ -55,14 +55,7 @@ def export(self, destination=None):
          File destination, defaults to the default directory
         """
         default_filename = self._gateway.host() + datetime.now().strftime('_%Y-%m-%dT%H_%M_%S') + '.xml'
-        directory = filename = None
-        if destination:
-            directory, filename = self._filesystem.split_file_directory(destination)
-            if not filename:
-                filename = default_filename
-        else:
-            directory = self._filesystem.get_dirpath()
-            filename = default_filename
+        directory, filename = self._filesystem.split_file_directory_with_defaults(destination, default_filename)
         logging.getLogger().info('Exporting configuration. %s', {'host': self._gateway.host()})
         handle = self._gateway.openfile('/export')
         filepath = FileSystem.instance().save(directory, filename, handle)