Add more comments

src/freenas/usr/local/libexec/ipa_ctl.py

@@ -198,37 +198,22 @@ def collapse_key(entry, key):
     return entry[key]
 
 
-def parse_host_entry(entry):
+def parse_ldap_result(entry):
     output = {}
     for key in entry.keys():
         output[key] = collapse_key(entry, key)
 
     return output
 
 
-def parse_rpc_find_response(res):
-    if res['count'] == 0:
-        return None
-
-    return [parse_host_entry(entry) for entry in res['result']]
-
-
-def find_host(hostname: str):
-    return parse_rpc_find_response(api.Command.host_find(hostname))
-
-
-def find_service(hostname: str, service_name: str):
-    return parse_rpc_find_response(api.Command.service_find(f'{service_name}/{hostname}'))
-
-
 def add_service(hostname: str, service_name: str):
     res = api.Command.service_add(f'{service_name}/{hostname}')
     return res['value']
 
 
 def del_service(hostname: str, service_name: str):
     res = api.Command.service_del(f'{service_name}/{hostname}')
-    return res['value']
+    return {'service': res['value'][0]}
 
 
 def del_service_smb(hostname: str, realm: str):
@@ -324,23 +309,30 @@ def get_smb_service_keytab_and_password(hostname: str, realm: str):
     kt_resp = get_keytab(principal, get_password=True)
     api.Command.service_mod(principal, addattr='ipaNTHash=MagicRegen')
 
-    return kt_resp
+    return kt_resp | {'service': principal}
 
 
 def get_service_keytab(hostname, service, force=False):
     """
     Get a base64-encoded kerberos keytab for the specified
     service name for the specified hostname.
+
+    return dictionary as follows:
+    ```
+    {
+      "keytab": <base64 string>,
+      "service": "nfs"
+    }
+    ```
     """
-    entry = find_service(hostname, service)
-    if entry is None:
+    try:
+        entry = api.Command.service_show(f'{service}/{hostname}')['result']
+    except errors.NotFound:
         add_service(hostname, service)
-        entry = find_service(hostname, service)
-
-    if entry[0]['has_keytab'] and not force:
-        raise RuntimeError
+        entry = api.Command.service_show(f'{service}/{hostname}')['result']
 
-    return get_keytab(entry[0]['krbprincipalname']) | {'service': service}
+    principal = parse_ldap_result(entry)['krbprincipalname']
+    return get_keytab(principal) | {'service': principal}
 
 
 def has_ticket_assert():
@@ -489,15 +481,54 @@ def main():
                     ipa_config.get('global', 'realm')
                 )
             case IpaOperation.SET_NFS_PRINCIPAL.name:
+                """
+                resp is formatted as follows:
+
+                ```
+                {
+                  "keytab": <base64 string>,
+                  "service": "nfs/[email protected]"
+                }
+                ```
+                """
                 resp = get_service_keytab(
                     ipa_config.get('global', 'host'),
                     'nfs'
                 )
             case IpaOperation.DEL_NFS_PRINCIPAL.name:
+                """
+                resp is formatted as follows:
+
+                ```
+                {
+                  "service": "nfs/[email protected]"
+                }
+                ```
+                """
                 resp = del_service(
                     ipa_config.get('global', 'host'), 'nfs'
                 )
             case IpaOperation.SET_SMB_PRINCIPAL.name:
+                """
+                resp is formatted as follows:
+
+                ```
+                {
+                  "keytab": <base64 string>,
+                  "password": <random string>,
+                  "domain_info": [
+                    {
+                      "netbios_name": "WALKERDOM",
+                      "domain_sid": "S-1-5-21-3696504179-2855309571-923743039",
+                      "domain_name": "walkerdom.test",
+                      "range_id_min": 565200000,
+                      "range_id_max": 565399999
+                    }
+                  ],
+                  "service": "cifs/[email protected]"
+                }
+                ```
+                """
                 if not (domain_info := retrieve_domain_information(api)):
                     print(
                         'No configured trust controller detected '