""" AUTHOR: Khushal P Soonderji DATE: Monday, 10th Feb., 2025. OBJECTIVE: To handle all MikroTik configuration from one place. REFERENCES: N/A DOWNLOADS: N/A """ import datetime # ***************************************************************************************************************** # ***** **** # *** IMPORT *** # ***** **** # ***************************************************************************************************************** # To make sibling directories accessible for imports: import sys sys.path.append(".") sys.path.append("..") # My async utils: from utils_v2.string import json from utils_v2.date_time import date_time from utils_v2.database.async_mysql_v2 import AsyncMySQL from utils_v2.database.async_mongo_v2 import AsyncMongo from utils_v2.cache.async_redis_cache_v2 import AsyncRedisCache # Controllers: from controllers_v2.core.software import CoreSoftwareController # To make very controlled API calls: from utils_v2.rest.controllers.async_base import AsyncREST from utils_v2.rest.models.api_call import ApiResponse # Models: from models.software.mikrotik.auth import ( MikroTikPPPoE1000Auth, MikroTikHotspot1000Auth, MikroTikAuthResponse ) from models.software.mikrotik.configure import ( MikroTikConfigAttemptResponse, MikroTikRollBackAttemptResponse ) # To work with IP Addresses: import ipaddress # To work with datatypes: from typing import List, Any # To make HTTP requests: import httpx # to work with MongoDB: from bson.objectid import ObjectId # To make abstract classes: from abc import ABC, abstractmethod # Misc: import math # ***************************************************************************************************************** # ***** **** # *** MACROS / ONE-TIME INIT *** # ***** **** # ***************************************************************************************************************** # --- Nothing Yet # ***************************************************************************************************************** # ***** **** # *** VARIABLES *** # ***** **** # ***************************************************************************************************************** # --- Nothing Yet # ***************************************************************************************************************** # ***** **** # *** FUNCTIONS *** # ***** **** # ***************************************************************************************************************** # --- Nothing Yet # ***************************************************************************************************************** # ***** **** # *** CLASSES *** # ***** **** # ***************************************************************************************************************** class MikroTikController(CoreSoftwareController, ABC): # ┏┓┓ ┓┏ # ┃ ┃┏┓┏┏ ┃┃┏┓┏┓┏ # ┗┛┗┗┻┛┛ ┗┛┗┻┛ ┛ SERVICE_TYPE = "mikrotik" # ┏┓ # ┃ ┏┓┏┓┏╋┏┓┓┏┏╋┏┓┏┓ # ┗┛┗┛┛┗┛┗┛ ┗┻┗┗┗┛┛ def __init__( self, cache: AsyncRedisCache = None, http_client: httpx.AsyncClient = None, alert_url: str = None, base_filter: dict = None, debug: bool = True, debug_prefix: str = "MikroTik (C) | ", debug_only_errors: bool = True ): """ This is the foundational controller for all MikroTik services. This is built on top of the core message controller, and, in turn, all individual MikroTik client controllers must be built on top of this. :param cache: The object to use for caching results from database calls. :param http_client: The HTTP client to use to make REST-ful API calls. :param base_filter: The basic filter that will be applied to all fetching/updating queries. WARNING: THE BASE FILTER WILL ALWAYS BE APPLIED AUTOMATICALLY. SET THIS UP WISELY. :param debug: Whether, or not, you would like to print debugging messages: :param debug_prefix: The prefix to print with the debugging messages. :param debug_only_errors: Whether you would like to print only error messages or all messages. :return: None. """ # Prepare the combined base filter: mikrotik_filter = {} for k, v in (base_filter or {}).items(): mikrotik_filter[k] = v mikrotik_filter["serviceType"] = self.SERVICE_TYPE # Invoke the parent's constructor: CoreSoftwareController.__init__( self, cache = cache, alert_url = alert_url, http_client = http_client, base_filter = mikrotik_filter, debug = debug, debug_prefix = debug_prefix, debug_only_errors = debug_only_errors ) # Init a variable in a parent: self._service_type = self.SERVICE_TYPE # For controlled REST-ful calls: self._rest = AsyncREST( http_client = http_client, debug = debug, debug_prefix = debug_prefix, debug_only_errors = debug_only_errors ) # ┓┏ ┓ # ┣┫┏┓┃┏┓┏┓┏┓┏ # ┛┗┗ ┗┣┛┗ ┛ ┛ # ┛ @staticmethod def get_mikrotik_url( mikrotik_ip: str, path: str, port_no: int | str = None, use_https: bool = True ) -> str: """ Simply creates the base URL for hitting the MikroTik server. :param mikrotik_ip: The IP address of the MikroTik device. :param path: The path of the REST API to hit. :param port_no: The port no. to hit the MikroTik device on. :param use_https: Whether to use HTTPS, or HTTP. :return: The Base URL string. """ base_url = r"https://" if use_https else r"http://" base_url += mikrotik_ip if port_no is not None: base_url += f":{port_no}" base_url += "/rest" if not path.startswith("/"): path = "/" + path return base_url + path @staticmethod def split_ipv4_range_among_targets( start_ip: ipaddress.IPv4Address | str, end_ip: ipaddress.IPv4Address | str, targets: List ) -> List[dict]: """ Divides the IPv4 range over the list of VLAN ids. :param start_ip: The first IP in the full pool (range). :param end_ip: The last IP in the full pool (range). :param targets: The list of targets (need not be sequential or ordered) like VLAN ids. :return: A list of dicts that describes the subnet for each target. """ # Parse the inputs: start_ip_obj = start_ip if isinstance(start_ip, ipaddress.IPv4Address) else ipaddress.IPv4Address(start_ip) end_ip_obj = end_ip if isinstance(end_ip, ipaddress.IPv4Address) else ipaddress.IPv4Address(end_ip) target_count = len(targets) # Calculate the total number of IPs in the range: total_ips = int(end_ip_obj) - int(start_ip_obj) + 1 # Calculate the no. of IPs each VLAN gets, # and add three because we need IPs for network, gateway and broadcast: ips_per_target = math.ceil(total_ips / target_count) + 3 # Generate subnets for each VLAN: subnets = [] current_ip = start_ip_obj for target in targets: # Calculate the network address for the current VLAN: subnet_network = ipaddress.IPv4Network(f"{current_ip}/{32 - ips_per_target.bit_length()}", strict = False) # Check for overlap with the parent network: subnet_start_ip_obj = subnet_network.network_address subnet_end_ip_obj = subnet_network.broadcast_address if subnet_start_ip_obj <= end_ip_obj: # Add the calculated subnet to the list: subnets.append({ "target": target, "network": str(subnet_network), "size": int(2 ** (32 - subnet_network.prefixlen)), "startIp": str(subnet_start_ip_obj), "endIp": str(subnet_end_ip_obj) }) # Update the current IP for the next subnet current_ip = ipaddress.IPv4Address(int(subnet_network.broadcast_address) + 1) # Done here: return subnets @staticmethod def create_comment_json( created_by: str, created_ts: datetime.datetime = None, roll_back_config: dict = None ) -> str: """ To create a JSON string that can be put as a comment in any step to later identify the work that was done and have some hint about how to roll it back if needed. :param created_by: A hint to put to identify which process/tool created this comment/config/process. :param created_ts: The datetime (preferably UTC) when this comment was created. :param roll_back_config: The original config that can be used when rolling back. :return: The comment string to be used. """ # Create the JSON: comment_json = { "createdBy": created_by, "createdTs": (created_ts or date_time.get_current_utc_date_time(as_string = False)).timestamp(), "rollbackConfig": roll_back_config } # Return a string: return json.to_string(comment_json, no_space = True) @staticmethod def parse_comment_json(comment: str) -> dict | list | None: """ Tries to parse a comment as if it were a JSON string. :param comment: The comment string. :return: The dict/list parsed form the JSON, or a null value of the input was not a valid JSON string. """ # Start with a null value: parsed = None # Try to parse the comment as if it were a JSON string: try: parsed = json.from_string(comment) except: parsed = None # Done here: return parsed # ┏┓ # ┗┓┓┏┏╋┏┓┏┳┓ # ┗┛┗┫┛┗┗ ┛┗┗ # ┛ async def get_system_resource( self, mikrotik_ip: str, username: str, password: str, port_no: int | str = None, use_https: bool = True ) -> ApiResponse: """ To get a summary of the hardware resources available in the MikroTik device. This also becomes a great way to quickly check if any given device is valid, and up and running. :param mikrotik_ip: The IP address of the MikroTik device. :param username: The username to get access to the MikroTik device. :param password: The password to get access to the MikroTik device. :param port_no: The port no. to hit the MikroTik device on. :param use_https: Whether to use HTTPS, or HTTP. :return: A structured API response. """ # Make the API call: api_response = await self._rest.get( url = self.get_mikrotik_url( mikrotik_ip = mikrotik_ip, path = r"/system/resource", port_no = port_no, use_https = use_https ), auth = httpx.BasicAuth( username = username, password = password ) ) # Done here: return api_response # ┳ ┏ # ┃┏┓╋┏┓┏┓╋┏┓┏┏┓┏ # ┻┛┗┗┗ ┛ ┛┗┻┗┗ ┛ async def list_interfaces( self, mikrotik_ip: str, username: str, password: str, port_no: int | str = None, use_https: bool = True ): """ To enlist all the physical connectivity interfaces available on the MikroTik device. :param mikrotik_ip: The IP address of the MikroTik device. :param username: The username to get access to the MikroTik device. :param password: The password to get access to the MikroTik device. :param port_no: The port no. to hit the MikroTik device on. :param use_https: Whether to use HTTPS, or HTTP. :return: A structured API response. """ # Make the API call: api_response = await self._rest.get( url = self.get_mikrotik_url( mikrotik_ip = mikrotik_ip, path = r"/interface", port_no = port_no, use_https = use_https ), auth = httpx.BasicAuth( username = username, password = password ) ) # Done here: return api_response async def update_interface( self, mikrotik_ip: str, username: str, password: str, interface_id: str, port_no: int | str = None, use_https: bool = True, name: str = None, disabled: bool = False, comment: str = None ): """ To update an interface's configuration. :param mikrotik_ip: The IP address of the MikroTik device. :param username: The username to get access to the MikroTik device. :param password: The password to get access to the MikroTik device. :param interface_id: The id of the interface that you'd like to modify. :param port_no: The port no. to hit the MikroTik device on. :param use_https: Whether to use HTTPS, or HTTP. :param name: The new name for the interface. :param disabled: Whether, or not, you'd like to disable the interface. :param comment: A note that you'd like to attach to the entry. It'll then be available in the listing API. :return: A structured API response. """ # Prepare the JSON to give to the API: input_json = { k: v for k, v in { "name": name, "disabled": disabled, "comment": comment }.items() if v is not None } # Make the API call: api_response = await self._rest.patch( url = self.get_mikrotik_url( mikrotik_ip = mikrotik_ip, path = f"/interface/{interface_id}", port_no = port_no, use_https = use_https ), auth = httpx.BasicAuth( username = username, password = password ), json = input_json ) # Done here: return api_response # ┏┓ ┓ # ┣┫┓┏╋┣┓ # ┛┗┗┻┗┛┗ @abstractmethod async def save_auth( self, sql_conn: AsyncMySQL, mongo_data_conn: AsyncMongo, mikrotik_auth: MikroTikPPPoE1000Auth | MikroTikHotspot1000Auth ) -> MikroTikAuthResponse: """ Checks if a particular set of incoming credentials give access to a valid server and then stores the credentials. :param sql_conn: The database connection to use to perform this task. :param mongo_data_conn: The database connection to use to perform this task. :param mikrotik_auth: The set of credentials as received from the UI/API. :return: A structured response to indicate what happened during authorization. """ pass # ┏┓ ┏• # ┃ ┏┓┏┓╋┓┏┓ # ┗┛┗┛┛┗┛┗┗┫ # ┛ @abstractmethod async def roll_back( self, mikrotik_auth: MikroTikPPPoE1000Auth | MikroTikHotspot1000Auth ) -> MikroTikRollBackAttemptResponse: """ The rolling-back to the original state (as best as possible) in case the configurations fails midway after completing some no. of steps. :param mikrotik_auth: The set of credentials as received from the UI/API. :return: A structured response to indicate what happened during the configuration attempt. """ pass @abstractmethod async def configure( self, mikrotik_auth: MikroTikPPPoE1000Auth | MikroTikHotspot1000Auth ) -> MikroTikConfigAttemptResponse: """ Run the configuration steps for the system. :param mikrotik_auth: The set of credentials as received from the UI/API. :return: A structured response to indicate what happened during the configuration attempt. """ pass # ***************************************************************************************************************** # ***** **** # *** MAIN PROGRAM *** # ***** **** # ***************************************************************************************************************** if __name__ == "__main__": pass