Control API reference

RADKit Control will allow you to programmatically retrieve, modify and update RADKit service components. That is, if you have a running RADKit Service, RADKit Control can make it manageable over the network, as an alternative to the WebUI.

RADKit Control provides two different interfaces - a CLI and a Python API. The goal of this document is to describe RADKit Control Python API and show you how you might use it. For details on the Control CLI, see Control CLI.

When you are done here, you will be able to use RADKit API to have control over the components below individually and in bulk:

Devices, remote users, labels, admins can be managed (added, updated, deleted).
The Service itself can be managed.

We are exposing now a ControlAPI which wraps AsyncControlAPI and exposes same set of methods but synchronous. All the API calls are happening in a dedicated thread where event loop is running.

The purpose of this design is to provide a more familiar and straightforward programming model for users who are more comfortable with synchronous programming.

Note

Much of RADKit Control power comes from following a Pydantic model. When data is validated against a Pydantic model, if any errors or inconsistencies are detected, Pydantic raises detailed validation errors that clearly indicate the problems and their locations.

Note

Some functions require a component id or uuid, if you are not sure about any user, device, label identifier for carrying out a certain operation, list function and its cli equivalent can show you the needed ids.

Warning

Avoid hardcoding device types (e.g. “IOS_XE”, “ISE” etc.). Instead use DeviceType.IOS_XE, DeviceType.ISE, … .

Before getting started, to disable TLS verification using ControlAPI please follow the example below:

#!/usr/bin/env python

from getpass import getpass

from radkit_service.control_api import *

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: "),
    http_client_kwargs=dict(verify=False),
) as service:
    ...

User operations 

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Note

You might come across CustomSecretStr From an external point of view, this is a plain string password for users login. CustomSecretStr internally wraps this String so passwords are never leaked.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.get_remote_user( username: str, ) → APIResult[list[StoredRemoteUser]]

This function will have RADKit control get all the information stored on RADKit Service for a certain remote user.

Parameters:: username – The username of the remote user you are interested in.
Returns:: APIResult object, which is a list of StoredRemoteUser (see Remote users) objects for more information.

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    result = service.get_remote_user("john.doe@example.com")

ControlAPI.list_remote_users() → APIResult[list[StoredRemoteUser]]

This function will have radkit-control list all the remote users existing on the RADKit service.

Returns:: a list of StoredRemote user objects (see Remote users). Each user is represented by a dictionary with all the user attributes.

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI
with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    result = service.list_remote_users()

ControlAPI.create_remote_user( username: str, full_name: str = '', description: str = '', labels: Sequence[int | str] | None = None, activate: ActivateForever | ActivateMinutes | Deactivate = ActivateForever(), connection_mode_cloud_active: bool = True, connection_mode_direct_active: bool = True, connection_mode_direct_sso_active: bool = True, ) → APIResult[StoredRemoteUser]

This function will have radkit-control create a new remote user on the RADKit service. Validated against NewRemoteUser model (see Remote users).

Parameters:

username – The email of the remote user (mandatory).
full_name – The full name of the remote user (optional).
description – A description of the remote user (optional).
labels – A set of labels associated with the remote user (optional).
activate – An activation configuration for the remote user (default: ActivateForever()).
connection_mode_cloud_active – Whether the user can connect via cloud SSO (optional)
connection_mode_direct_active – Whether the user can connect via direct connection (optional)
connection_mode_direct_sso_active – Whether the user can connect via direct SSO (optional)

Returns:

APIResult: The result of the API call, containing the created StoredRemoteUser object. (see Remote users) objects for more information.

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI
from radkit_service.webserver.models.users import NewRemoteUser
with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    service.create_remote_user(username="mom@cisco.com")

ControlAPI.create_remote_users( users: Sequence[NewRemoteUser], ) → BulkResult[StoredRemoteUser]

This function will have radkit-control create multiple users.

Parameters:: users – A sequence of NewRemoteUser objects representing the attributes of the remote users (see Remote users).
Returns:: BulkResult[StoredRemoteUser]: The result of the bulk API call, containing a list of created StoredRemoteUser objects (see Remote users).

ControlAPI.update_remote_user( username: str, new_username: str | DontUpdate = DontUpdate(dontUpdate=True), full_name: str | DontUpdate = DontUpdate(dontUpdate=True), description: str | DontUpdate = DontUpdate(dontUpdate=True), replace_labels: Sequence[int | str] | None = None, add_labels: Sequence[int | str] | None = None, remove_labels: Sequence[int | str] | None = None, activate: ActivateForever | ActivateMinutes | Deactivate | DontUpdate = DontUpdate(dontUpdate=True), connection_mode_cloud_active: bool | DontUpdate = DontUpdate(dontUpdate=True), connection_mode_direct_active: bool | DontUpdate = DontUpdate(dontUpdate=True), connection_mode_direct_sso_active: bool | DontUpdate = DontUpdate(dontUpdate=True), ) → APIResult[StoredRemoteUser]

The method first performs some sanity checks on the parameters to ensure they are valid (see Remote users). Then it will have radkit-control update the user’s attributes based on the parameters passed identified by its username.

Parameters:

username – The username of the remote user to be updated (mandatory).
new_username – The new username to set (optional).
full_name – The new full name to set (optional).
description – The new description to set (optional).
replace_labels – A set of labels to replace the existing labels (optional).
add_labels – A set of labels to add to the existing labels (optional).
remove_labels – A set of labels to remove from the existing labels (optional).
activate – An activation configuration to set (optional).
connection_mode_cloud_active – Whether the user can connect via cloud SSO (optional)
connection_mode_direct_active – Whether the user can connect via direct connection (optional)
connection_mode_direct_sso_active – Whether the user can connect via direct SSO (optional)

Returns:

[StoredRemoteUser]: The result of the bulk API call, containing a StoredRemoteUser object (see Remote users).

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    result = service.update_remote_user("jane.smith@example.com",full_name="Rey Reynolds")

ControlAPI.update_remote_users( users: Sequence[UpdateRemoteUser], ) → BulkResult[StoredRemoteUser]

The method first performs some sanity checks on the parameters to ensure they are valid (see Remote users). Then it will have radkit-control update multiple users’ attributes based on the parameters passed identified by username.

Parameters:: users – A sequence of UpdateRemoteUser objects representing the changes for each remote user (see Remote users).
Returns:: BulkResult The result of the bulk API call, containing updated StoredRemoteUser objects (see Remote users).

ControlAPI.delete_remote_user( username: str, ) → APIResult[str]

This function will have radkit-control delete a specific remote user on the RADKit service identified by the username.

Parameters:: username – The String username of the remote user to be updated.
Returns:: APIResult[str] to show how the operation went.

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI
with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    service.delete_remote_user("john.doe@example.com")

ControlAPI.delete_remote_users( usernames: Collection[str], ) → BulkResult[str]

This function will have radkit-control delete multiple users based on a given iterable.

Parameters:: usernames – A collection of usernames to delete as strings.
Returns:: BulkResult[str] resembling how the operation went.

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI
my_list = ["tac.support@cisco.com", "jane.smith@example.com"]
with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    service.delete_remote_users(my_list)

Device operations 

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Note

You might come across CustomSecretStr From an external point of view, this is a plain string password for credentials. CustomSecretStr internally wraps this String so passwords are never leaked.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.list_devices( exclude_metadata: bool = False, ) → APIResult[list[StoredDeviceWithMetadata] | list[StoredDevice]]

This function will have radkit-control list all the devices existing on the RADKit service with their associated parameters.

Parameters:: exclude_metadata – If True, don’t include the metadata field in the response (optional).
Returns:: A list of all StoredDeviceWithMetadata objects (see Devices). Each entry is a dictionary containing all the device details (name, management ip address, configured protocols, activation status,…etc)

ControlAPI.get_device( device_uuid: str, ) → APIResult[list[StoredDeviceWithMetadata] | list[StoredDevice]]

This function will have radkit-control get a certain device existing on the RADKit service with its associated parameters identified by its UUID.

Parameters:: device_uuid – unique identifier for the device as a string.
Returns:: A list of all StoredDeviceWithMetadata objects (see Devices) containing all the device details (name, management ip address, configured protocols, activation status,…etc).

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    result = service.get_device("69393a5c-6cc0-42c4-9567-10eb9de08bf2")

ControlAPI.create_device( device: NewDevice, ) → APIResult[StoredDeviceWithMetadata]

This function will have radkit-control create a new device on the RADKit service. Your input is validated with pydantic model and clear error messages are shown if there is a validation error.

Parameters:: device – Takes a NewDevice object. From NewDevice object parameters see (see Devices).
Returns:: [StoredDeviceWithMetadata]: The result of the bulk API call, containing the device created in the form StoredDeviceWithMetadata object. (see Devices).

ControlAPI.create_devices( devices: Sequence[NewDevice], ) → BulkResult[StoredDeviceWithMetadata]

This function will have radkit-control create multiple devices on the service.

Parameters:: devices – A sequence of NewDevice objects: representing the devices to create. (see Devices).
Returns:: [StoredDeviceWithMetadata] bulk result. (see Devices).

Example that instantely creates 10,000 devices:

from getpass import getpass
from math import floor

from radkit_common.types import DeviceType
from radkit_service.control_api import ControlAPI
from radkit_service.webserver.models.devices import NewDevice

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    devices = []
    for i in range(10000):
        device = NewDevice(
            name=f"new-test-device-{i}",
            host=f"2.{floor(i/(256*256))}.{floor(i/256)}.{i%256}",
            deviceType=DeviceType.IOS_XE
        )
        devices.append(device)

    print(f"creating {len(devices)} devices")
    result = service.create_devices(devices)

ControlAPI.update_device( device: UpdateDevice, ) → APIResult[StoredDeviceWithMetadata]

This function will have radkit-control update a device with all the parameters specified in the device dictionary. Any parameter which is not updated will remain as it is.

Parameters:: device – Takes a UpdateDevice object to understand more on what it expects (see Devices).
Returns:: [StoredDeviceWithMetadata]: The result of the bulk API call, containing a StoredDeviceWithMetadata object. (see Devices)

ControlAPI.update_devices( devices: Sequence[UpdateDevice], ) → BulkResult[StoredDeviceWithMetadata | StoredDevice]

This function will have radkit-control update multiple devices with all the parameters specified in the device dictionary. Any parameter which is not updated will remain as it is.

Parameters:: devices – A sequence of UpdateDevice objects (see Devices) to understand more on what it expects (see Devices).
Returns:: [StoredDeviceWithMetadata]: The result of the bulk API call, containing a StoredDeviceWithMetadata object. (see Devices)

ControlAPI.delete_device( device_uuid: Annotated[UUID, UuidVersion(uuid_version=4)] | str, ) → APIResult[Annotated[UUID, UuidVersion]]

This function will have radkit-control delete a certain device existing on the RADKit service identified by its UUID.

Parameters:: device_uuid – string unique identifier for the device.
Returns:: API call result.

ControlAPI.delete_devices( device_ids: Collection[Annotated[UUID, UuidVersion(uuid_version=4)]], ) → BulkResult[Annotated[UUID, UuidVersion]]

This function will have radkit-control delete multiple devices existing on the RADKit service identified by their UUID.

Parameters:: device_ids – A collection of UUIDs of the devices to delete.
Returns:: Bulk result object containing a list of UUID4 values.

ControlAPI.import_devices( device_uuid: Annotated[UUID, UuidVersion(uuid_version=4)] | str, tag: str | None = None, ) → APIResult[int]

Import and/or synchronize devices from external source.

Parameters:: device_uuid – UUID of the device to import devices from
Returns:: number of processed devices

ControlAPI.list_device_types() → APIResult[dict[DeviceType, str]]: List device types id to display name.

Example script that uses get_device and update_device:

#!/usr/bin/env python

from getpass import getpass

from radkit_service.control_api import *
from time import time

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    print("Getting device list")
    devices = service.list_devices().get_result()

    devices = [device for device in devices if "test-device-" in device.name]

    print(f"Identified {len(devices)} devices")

    now = time()
    new_description = f"modified {now}"
    for i in range(len(devices)):
        devices[i].description = new_description

    print("Sending to RADKit Service")
    service.update_devices(devices)

Example script that uses metadata in NewDevice creation:

#!/usr/bin/env python

from getpass import getpass
from math import floor

from radkit_common.utils.formatting import to_canonical_name
from radkit_common.utils.ssl import create_public_ssl_context
from radkit_common.types import DeviceType
from radkit_service.control_api import ControlAPI
from radkit_service.webserver.models.devices import MetaDataEntry, NewDevice, NewTerminal

from stopwatch import StopWatch

password = getpass()

verify = create_public_ssl_context(verify=False, use_obsolete_ciphers=False)

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=password,
    http_client_kwargs=dict(verify=verify)
) as service:
    stopwatch = StopWatch()

    devices = []
    for i in range(20000):
        hostname = f"new test-device_{i}"
        canonical_name = to_canonical_name(hostname)
        terminal = NewTerminal(
            username="admin",
            password="Cisco123",
        )
        metadata = [
            MetaDataEntry(key="original-hostname", value=hostname),
            MetaDataEntry(key="index", value=str(i))
        ]
        device = NewDevice(
            name=canonical_name,
            host=f"2.{floor(i/(256*256))}.{floor(i/256)}.{i%256}",
            deviceType=DeviceType.IOS_XE,
            terminal=terminal,
            metaData=metadata,
            enabled=True,
        )
        devices.append(device)

    print(f"creating {len(devices)} devices")
    stopwatch.start()
    result = service.create_devices(devices)
    stopwatch.stop()
    stopwatch.print_delta(f"devices created in ")

Note

In the example above, we used to_canonical_name() function that transforms a random name into a name RADKit can accept.

Label operations 

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.list_labels() → APIResult[list[StoredLabel]]

This function will have radkit-control list all labels existing on the RADKit service.

Returns:: A list of StoredLabel objects (see Labels) the device access labels known by this RADKit Service.

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    print("Getting labels list")
    service.list_labels()

ControlAPI.create_labels( labels: Sequence[NewLabel], ) → BulkResult[StoredLabel]

This function will have radkit-control create multiple labels on RADKit service .

Parameters:: labels – A sequence of NewLabel objects. (see Labels) for NewLabel attributes.
Returns:: [StoredLabel]: The result of the API call, containing a StoredLabel object. (see Labels)

ControlAPI.update_labels( labels: Sequence[UpdateLabel], ) → BulkResult[StoredLabel]

This function will have radkit-control update multiple labels. Anything you do not specify will default to not be updated.

Parameters:: labels – A sequence of UpdateLabel objects. (see Labels)
Returns:: [StoredLabel]: The result of the API call, containing a StoredLabel object. (see Labels)

Note

list_labels and its cli equivalent can show you the label ids.

ControlAPI.delete_labels( label_ids: Collection[int], ) → BulkResult[StoredLabel]

This function will have radkit-control deletes multiple labels on the RADKit service identified by their id.

Parameters:: label_ids – A collection of label IDs to delete as integers.
Returns:: [StoredLabel]: The result of the API call, containing a StoredLabel object. (see Labels)

Note

list_labels and its cli equivalent can show you the label ids.

Example:

#!/usr/bin/env python

from getpass import getpass
from radkit_service.control_api import ControlAPI

my_labels = [2, 4]

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    service.delete_labels(my_labels)

Returns:: BulkResult[StoredLabel]: The bulk result containing a StoredLabel object. (see Labels)

Admin operations 

Includes listing, creation, update, delete also in bulk with JSON and CSV support.

Note

You might come across CustomSecretStr From an external point of view, this is a plain string password for admin login. CustomSecretStr internally wraps this String so passwords are never leaked.

Warning

Combining create, update, delete in the same JSON or CSV is not supported. Users are invited to split their files in order to run different operations separately. This also applies to optional fields.

ControlAPI.list_admins() → APIResult[list[StoredAdmin]]

This function will have radkit-control list all admins on a RADKit service.

Returns:: a list of all StoredAdmin objects. Each user is represented by a dictionary with all the user attributes. (see Remote users)

ControlAPI.get_admin( admin_name: str, ) → APIResult[list[StoredAdmin]]

This function will have radkit-control get a certain admin details identified by the admin name.

Parameters:: admin_name – String of the admin name.
Returns:: StoredAdmin object with details like username, email, fullname and description of this chosen admin. (see Remote users)

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    result = service.get_admin("superadmin")

ControlAPI.create_admin( enabled: bool, admin_name: str, password: CustomSecretStr, email: str, full_name: str, description: str, ) → APIResult[StoredAdmin]

This function will have radkit-control create an admin user. Must be done before any other command can be executed. Takes a user name and a password as argument. If “initial” is True, consider this user as the very first admin user. This causes the request to NOT be authenticated and only works if this is truly the first user in the system. (see Remote users)

Parameters:

enabled – Boolean value indicating if admin is active or not.
admin_name – String representing the admin name (mandatory).
password – String representing the password. The password must meet the following criteria: at least 8 characters, 1 lowercase letter, 1 uppercase letter, 1 digit, and 1 symbol (mandatory).
email – String representing the email address (optional).
full_name – String representing the full name (optional).
description – String representing the description (optional).

Returns:

APIResult[StoredAdmin] (see Remote users)

Example:

#!/usr/bin/env python

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
) as service:
    result = service.create_admin(
        "iamadmin",
        "Verysecret123!",
        "email@example.com",
        "Full_name",
        "description"
    )
    print(result)

ControlAPI.create_admins( admins: Sequence[NewAdmin], ) → BulkResult[StoredAdmin]

This function will have radkit-control create multiple admins with all the parameters specified in the admin dictionary.

Parameters:: admins – A sequence of NewAdmin objects. Check the parameters above for NewAdmin attributes.
Returns:: BulkResult[StoredAdmin] (see Remote users)

ControlAPI.update_admin( admin_name: str, email: str | DontUpdate = DontUpdate(dontUpdate=True), full_name: str | DontUpdate = DontUpdate(dontUpdate=True), description: str | DontUpdate = DontUpdate(dontUpdate=True), ) → APIResult[StoredAdmin]

This function will have radkit-control update a certain admin identified by its admin name.

Parameters:

admin_name – The username of the admin to be updated (mandatory).
email – The new email address to set (optional). Don’t provide a value to keep the original one.
full_name – The new full name to set (optional). Don’t provide a value to keep the original one.
description – The new description to set (optional). Don’t provide a value to keep the original one.

Returns:

The result of the API call, containing the updated StoredAdmin object. (see Remote users)

Note

There is no password update and no admin_name update for an Admin using update through Control.

ControlAPI.update_admins( admins: Sequence[UpdateAdmin], ) → BulkResult[StoredAdmin]

This function will have radkit-control update multiple admins with various attributes.

Parameters:: admins – A sequence of UpdateAdmin objects representing the attributes of the admins. (see Remote users).
Returns:: The result of the API call, containing the updated StoredAdmin objects in bulk. (see Remote users).

ControlAPI.delete_admin( admin_name: str, ) → APIResult[str]

This function will have radkit-control delete an admin user at your own risk.

Parameters:: admin_name – String with the name of admin to be deleted.
Returns:: Result of API call as a string.

Example:

#!/usr/bin/env python

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    service.delete_admin("iamadmin")

ControlAPI.delete_admins( usernames: Collection[str], ) → BulkResult[str]

This function will have radkit-control delete multiple admins.

Parameters:: usernames – A collection of admin_names to delete as strings.
Returns:: Bulk result API call as strings.

Example:

#!/usr/bin/env python

from getpass import getpass
from radkit_service.control_api import ControlAPI

admins = [
    "admin1",
    "admin2",
    "admin3",
]

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    service.delete_admins(admins)

ControlAPI.change_password( username: str, new_password: CustomSecretStr, old_password: CustomSecretStr, ) → APIResult[StoredAdmin]

This function will have radkit-control change an admin users password. Takes a username, Old password, and New password as an argument. (see Remote users)

Parameters:

username – String representing the usern name (mandatory).
old_password – String representing the old password (optional).
new_password – String representing the new password. The password must meet the following criteria: at least 8 characters, 1 lowercase letter, 1 uppercase letter, 1 digit, and 1 symbol (mandatory).

Returns:

APIResult[StoredAdmin] (see Remote users)

Example:

from getpass import getpass
from radkit_service.control_api import ControlAPI

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=getpass("Password: ")
)  as service:
    result = service.change_password("superadmin","MynewPassword123!", "MyoldPassword123!")
    print(result)

Service operations 

Includes initial bootstrap, enroll, get_service_status, stop, reset, get version, settings.

ControlAPI.init_bootstrap_admin( password: CustomSecretStr, ) → APIResult[StoredAdmin]: This function will have radkit-control get up the very first admin user. Must be done before any other command can be executed. Takes a user name and a password as argument.

Note

No authentication required for this API, obviously since we are creating the first admin user.

ControlAPI.enroll_service( otp: str, timeout: int = 30, ) → APIResult[str]

This function will have radkit-control enroll the service.

Parameters:

otp – The One-Time Password string.
timeout – An optional parameter of type int with a default value of 30. It represents the timeout duration in seconds for the enrollment process. If no value is provided when calling the function, it will default to 30.

Returns:

The result of the enrollment process, containing the enrollment status and any associated data.

ControlAPI.get_service_status() → APIResult[Status]: This function will have radkit-control retrieve the RADKit Service status.

ControlAPI.stop_service() → APIResult[str]: This function will have radkit-control stop the service when there is superadmin user created already.

ControlAPI.stop_service_unauthenticated() → APIResult[str]: This function will have radkit-control stop the service when there is no superadmin user created yet.

ControlAPI.get_service_version() → APIResult[str]: This function will have radkit-control get the version of the running service.

ControlAPI.system_reset_service() → APIResult[str]: This function will have radkit-control remove serial number file and client certificates.

ControlAPI.set_settings( settings: Sequence[SettingChange], ) → BulkResult[APISettingInfo]

This function will have radkit-control set the settings for the service. (see Settings)

Returns:: The result of the API call, the list of Setting object (see Settings).

ControlAPI.get_settings( settings: Collection[str] = (), ui_visible: bool = False, ) → APIResult[list[APISettingInfo]]

This function will have radkit-control retrieve the current settings of the RADKit service.

Returns:: The result of the API call, containing the service settings as a dictionary (see Settings).

Data types 

In RADKit ControlAPI functions you will encounter objects that are either returned or taken as parameters mostly for data validation purposes. In this section, we will explain the users, devices, labels and settings models:

Remote users 

Represents the Remote User model and Admin model and it includes representation of remote user data and admin data which is the reference for validation of data used for ControlAPI functions in separate classes depending on the kind of operation.

Warning

There is no password update and no newUsername for Admins using UpdateAdmin through the API .

pydantic model radkit_service.control_api.StoredRemoteUser

Bases: RADKitBaseModel

Data model for an existing remote user. See NewRemoteUser for more information about the fields listed below.

field username: str [Required]

field fullname: str [Required]

field description: str [Required]

field timeSliceMinutes: PositiveInt | None = None

field expirationTimestamp: AwareDatetime | None = None

field labels: Set[int] [Required]

field accessToken: AnnotatedCustomSecretStr = CustomSecretStr('')

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

field connectionModeCloudActive: bool [Required]: Specifies if given user can connect to the service through the cloud.

field connectionModeDirectActive: bool [Required]: Specifies if given user can connect to the service directly.

field connectionModeDirectSsoActive: bool [Required]: Specifies if given user can connect to the service directly with the identity confirmed by the cloud.

field externalAuth: StoredExternalAuth | None = None: External authentication configuration.

classmethod from_db_user( db: ServiceDB, user: DbRemoteUser, ) → StoredRemoteUser: Convert DbRemoteUser to StoredRemoteUser instance.

pydantic model radkit_service.control_api.NewRemoteUser

Bases: RADKitBaseModel

Data model for creating a new remote user.

field username: EmailStr [Required]: The remote user’s email address.

field fullname: str [Required]: The remote user’s full name.

field description: str [Required]: The remote user’s description.

field timeSliceMinutes: PositiveInt | None = None: Optional. The duration in minutes that the remote user can be granted remote access for. After this time is expired, the user will be automatically disabled. If this field is omitted, remote access will have to be managed manually by enabling/disabling the user.

field expirationTimestamp: Annotated[AwareDatetime | None, AfterValidator(ensure_utc)] = None

Optional. The absolute time at which the user’s remote access will be revoked.

Constraints:

func = <function ensure_utc at 0x7f884186dd00>

field labels: Sequence[int | str] [Optional]: Optional. A sequence of integers or strings representing the labels associated with the remote user.

field accessToken: CustomSecretStr | None = None

Optional. Access token for E2EE session verification. An access token will automatically be generated if none was given.

Validated by:

validate_access_token

field connectionModeCloudActive: bool = True: Specifies if given user can connect to the service through the cloud.

field connectionModeDirectActive: bool = True: Specifies if given user can connect to the service directly.

field connectionModeDirectSsoActive: bool = True: Specifies if given user can connect to the service directly with the identity confirmed by the cloud.

field externalAuth: NewExternalAuth | None = None: External authentication configuration.

pydantic model radkit_service.control_api.NewRemoteUsers

Bases: RADKitRootModel[list[NewRemoteUser]]

A list of NewRemoteUser entries for bulk remote user creation.

field root: list[NewRemoteUser] [Required]

Constraints:

max_length = 1000

pydantic model radkit_service.control_api.UpdateRemoteUser

Bases: RADKitBaseModel

Data model for updating an existing remote user entry. See NewRemoteUser for more information about the fields listed below.

field username: EmailStr [Required]: The current email address for the remote user.

field newUsername: UpdateField[EmailStr] = DontUpdate(dontUpdate=True): Optional. The new email address for the remote user, if the user is to be renamed.

field fullname: UpdateField[str] = DontUpdate(dontUpdate=True)

field description: UpdateField[str] = DontUpdate(dontUpdate=True)

field expirationTimestamp: UpdateField[Annotated[AwareDatetime | None, AfterValidator(ensure_utc)] | None] = DontUpdate(dontUpdate=True)

field timeSliceMinutes: UpdateField[PositiveInt | None] = DontUpdate(dontUpdate=True)

field labelUpdate: UpdateLabelSet [Optional]: Optional. The labels to be added/removed/replaced on the remote users, as integers or strings. See UpdateLabelSet for details.

field accessToken: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True)

Validated by:

validate_access_token

field connectionModeCloudActive: UpdateField[bool] = DontUpdate(dontUpdate=True): Specifies if given user can connect to the service through the cloud.

field connectionModeDirectActive: UpdateField[bool] = DontUpdate(dontUpdate=True): Specifies if given user can connect to the service directly.

field connectionModeDirectSsoActive: UpdateField[bool] = DontUpdate(dontUpdate=True): Specifies if given user can connect to the service directly with the identity confirmed by the cloud.

field externalAuth: UpdateField[UpdateExternalAuth | None] = DontUpdate(dontUpdate=True): External authentication configuration.

pydantic model radkit_service.control_api.UpdateRemoteUsers

Bases: RADKitRootModel[list[UpdateRemoteUser]]

A list of UpdateRemoteUser entries for bulk remote user modification.

field root: list[UpdateRemoteUser] [Required]

Constraints:

max_length = 1000

pydantic model radkit_service.control_api.NewAdmin

Bases: RADKitBaseModel

Admin model to validate data used for Admin user creation.

field username: str [Required]

Admin username as a string. Example: myadmin

Constraints:

min_length = 1

Validated by:

validate_username

field email: Literal[''] | EmailStr [Required]: Admin email as a string.

field fullname: str [Required]: Admin full name.

field description: str [Required]: String description of admin.

field password: CustomSecretStr [Required]

From an external point of view, this is a plain string password for admin login. CustomSecretStr internally wraps this String so passwords are never leaked.

Validated by:

validate_password

field enabled: bool = False: Whether admin should be enabled (False by default).

pydantic model radkit_service.control_api.NewAdmins

Bases: RADKitRootModel[list[NewAdmin]]

Represents a list of NewAdmin objects. See NewAdmin data type for more information on the fields below.

field root: list[NewAdmin] [Required]

Constraints:

max_length = 1000

pydantic model radkit_service.control_api.UpdateAdmin

Bases: RADKitBaseModel

Admin model to validate data used for updates. Password update is optional.

field username: str [Required]

Stored original username to point at the correct admin, this field is required.

Constraints:

min_length = 1

field enabled: UpdateField[bool] = DontUpdate(dontUpdate=True): Whether admin should be enabled, if empty don’t update.

field email: UpdateField[Literal[''] | EmailStr] = DontUpdate(dontUpdate=True): New email to be updated, if empty don’t update.

field fullname: UpdateField[str] = DontUpdate(dontUpdate=True): New fullname to be updated, if empty don’t update.

field description: UpdateField[str] = DontUpdate(dontUpdate=True): New description to be updated, if empty don’t update.

pydantic model radkit_service.control_api.UpdateAdmins

Bases: RADKitRootModel[list[UpdateAdmin]]

Represents a list of UpdateAdmin objects. See UpdateAdmin data type for more information on the fields below.

field root: list[UpdateAdmin] [Required]

Constraints:

max_length = 1000

Devices 

class radkit_service.control_api.DeviceType

Bases: str, Enum

These are the device types used in the Service database as well as the Service and Control APIs. The Service WebUI shows user-friendly versions of these types; those “display types” can be found in the table below as well as in the output of the radkit-control device list-types subcommand.

Note

Changed in 1.6.0: CNBR and CNBROpsHub have been removed (obsolete); display types have been made consistent with official Cisco product names; Control subcommand radkit-control device list-types has been added.

Changed in 1.6.3: enum values have been harmonized (all-uppercase + underscore); database contents will be converted automatically on upgrade; make sure to update your Control scripts and CSV files if you do automated imports.

AIRE_OS = 'AIRE_OS': Display type: AireOS

APIC = 'APIC': Display type: APIC

ASA = 'ASA': Display type: ASA

BROADWORKS = 'BROADWORKS': Display type: BroadWorks

CATALYST_CENTER = 'CATALYST_CENTER': Display type: Catalyst Center

CEDGE = 'CEDGE': Display type: SD-WAN cEdge

CIMC = 'CIMC': Display type: CIMC

CISCO_AP_OS = 'CISCO_AP_OS': Display type: Cisco AP OS

CML = 'CML': Display type: CML

CMS = 'CMS': Display type: CMS

CPS = 'CPS': Display type: CPS (Cisco Policy Suite)

CROSSWORK = 'CROSSWORK': Display type: Crosswork

CSPC = 'CSPC': Display type: CSPC

CUCM = 'CUCM': Display type: CUCM

CVOS = 'CVOS': Display type: CVOS

CVP = 'CVP': Display type: CVP

ESA = 'ESA': Display type: ESA (Secure Email Gateway)

EXPRESSWAY = 'EXPRESSWAY': Display type: Expressway

FDM = 'FDM': Display type: FDM

FMC = 'FMC': Display type: FMC

FTD = 'FTD': Display type: FTD

GENERIC = 'GENERIC': Display type: Generic

HYPERFLEX = 'HYPERFLEX': Display type: HyperFlex

INTERSIGHT = 'INTERSIGHT': Display type: Intersight

IOS_XE = 'IOS_XE': Display type: IOS XE

IOS_XR = 'IOS_XR': Display type: IOS XR

ISE = 'ISE': Display type: ISE

LINUX = 'LINUX': Display type: Linux

NCS_2000 = 'NCS_2000': Display type: NCS-2000

NEXUS_DASHBOARD = 'NEXUS_DASHBOARD': Display type: Nexus Dashboard

NSO = 'NSO': Display type: NSO

NX_OS = 'NX_OS': Display type: NX-OS

RADKIT_SERVICE = 'RADKIT_SERVICE': Display type: RADKit Service

ROUTED_PON = 'ROUTED_PON': Display type: Routed PON

SMA = 'SMA': Display type: SMA (Secure Email and Web Manager)

SPLUNK = 'SPLUNK': Display type: Splunk

STAR_OS = 'STAR_OS': Display type: StarOS

UCCE = 'UCCE': Display type: UCCE

UCS_MANAGER = 'UCS_MANAGER': Display type: UCS Manager

ULTRA_CORE_5G_AMF = 'ULTRA_CORE_5G_AMF': Display type: UCC 5G AMF Ops-Center

ULTRA_CORE_5G_PCF = 'ULTRA_CORE_5G_PCF': Display type: UCC 5G PCF Ops-Center

ULTRA_CORE_5G_SMF = 'ULTRA_CORE_5G_SMF': Display type: UCC 5G SMF Ops-Center

WAS = 'WAS': Display type: WAS (Secure Web Appliance)

WLC = 'WLC': Display type: WLC

VMANAGE = 'VMANAGE': Display type: SD-WAN vManage

pydantic model radkit_service.control_api.StoredDevice

Bases: RADKitBaseModel

Device model to represent data stored in DB. See NewDevice data type for more explanation of the fields below.

field uuid: UUID4 | None = None

field name: str [Required]

Constraints:

min_length = 1

field host: str [Required]

Constraints:

min_length = 1

field deviceType: DeviceType [Required]

field jumphostUuid: UUID4 | None = None

field enabled: bool = False

field forwardedTcpPorts: PortRanges [Optional]

field labels: set[int] [Required]

field description: str = ''

field sourceKey: str | None = None

field sourceDevUuid: UUID4 | None = None

field terminal: StoredTerminal | None = None

field netconf: StoredNetconf | None = None

field snmp: StoredSNMP | None = None

field swagger: StoredSwagger | None = None

field http: StoredHTTP | None = None

field deviceTemplateRef: StoredDeviceTemplateRef | None = None

pydantic model radkit_service.control_api.StoredDeviceWithMetadata

Bases: StoredDevice

Device model to represent data stored in DB. See NewDevice data type for more explanation of the fields below.

field metaData: list[MetaDataEntry] [Optional]

field uuid: UUID4 | None = None

field name: str [Required]

Constraints:

min_length = 1

field host: str [Required]

Constraints:

min_length = 1

field deviceType: DeviceType [Required]

field jumphostUuid: UUID4 | None = None

field enabled: bool = False

field forwardedTcpPorts: PortRanges [Optional]

field labels: set[int] [Required]

field description: str = ''

field sourceKey: str | None = None

field sourceDevUuid: UUID4 | None = None

field terminal: StoredTerminal | None = None

field netconf: StoredNetconf | None = None

field snmp: StoredSNMP | None = None

field swagger: StoredSwagger | None = None

field http: StoredHTTP | None = None

field deviceTemplateRef: StoredDeviceTemplateRef | None = None

pydantic model radkit_service.control_api.DeviceSummary

Bases: RADKitBaseModel

Device model to represent data stored in DB. See NewDevice data type for more explanation of the fields below.

field uuid: UUID4 | None = None: Unique identifier of the device to the API.

field name: str | None = None

The device name that appears in RADKit.

Constraints:

min_length = 1

field host: str | None = None

The management IP address or a hostname of the device on the network.

Constraints:

min_length = 1

field deviceType: DeviceType | None = None: Same as the list in the RADKit service UI, identifying the device type in the inventory. Example=”LINUX”.

pydantic model radkit_service.control_api.NewDevice

Bases: RADKitBaseModel

Device model to validate data used for device creation.

field name: str [Required]

The device name that will appear in RADKit. Must be unique.

Constraints:

min_length = 1

Validated by:

check_name_is_canonical
validate_provisioning_variant

field host: str [Required]

Takes a management IP address or a hostname of the device on the network.

Constraints:

min_length = 1

Validated by:

validate_hostname
validate_provisioning_variant

field deviceType: DeviceType [Required]

Same as the list in the RADKit service UI, identifying the device type in the inventory. Example=”LINUX”.

Validated by:

validate_provisioning_variant

field jumphostUuid: UUID4 | None = None

String Equivalent to the jumphost name on UI but for the API we use the unique identifier for the device. Default is none.

Validated by:

validate_provisioning_variant

field enabled: bool = False

Boolean (True, False) switch to enable/disable access to device. Default is True.

Validated by:

validate_provisioning_variant

field forwardedTcpPorts: PortRanges [Optional]

Identify a range for port forwarding capabilities, example: (‘1024-2047;3456;8000-9999’)

Validated by:

validate_provisioning_variant

field labels: Sequence[int | str] [Optional]

For associating label ids or names.

Validated by:

validate_provisioning_variant

field description: str = ''

String for adding a description to the device. Default is an empty string.

Validated by:

validate_provisioning_variant

field sourceKey: str | None = None

String identifier of device in external device store. Can be UUID. Default is none.

Validated by:

validate_provisioning_variant

field sourceDevUuid: UUID4 | None = None

String UUID of device from which device obtained (example: a CatalystCenter uuid as a source of device). Default is none.

Validated by:

validate_provisioning_variant

field metaData: Annotated[list[MetaDataEntry], reject_duplicate_metadata] [Optional]

A list of one key/value pair of device metadata. Default is none.

Constraints:

max_length = 200
func = <function reject_duplicates.<locals>.validator at 0x7f883c0f5260>

Validated by:

validate_provisioning_variant

field terminal: NewTerminal | None = None

Passing a New Terminal object to be associated with the device, documented at NewTerminal data type below

Validated by:

validate_provisioning_variant

field netconf: NewNetconf | None = None

Passing a New Netconf object to be associated with the device, documented at NewNetconf data type below

Validated by:

validate_provisioning_variant

field snmp: NewSNMP | None = None

Passing a New snmp object to be associated with the device, documented at NewSNMP data type below

Validated by:

validate_provisioning_variant

field swagger: NewSwagger | None = None

Passing a New swagger object to be associated with the device, documented at NewSwagger data type below

Validated by:

validate_provisioning_variant

field http: NewHTTP | None = None

Passing a New http object to be associated with the device, documented at NewHttp data type below

Validated by:

_model_validator
validate_provisioning_variant

field deviceTemplateRef: NewDeviceTemplateRef | None = None

Passing a device template ref used for device configuration.

Validated by:

validate_provisioning_variant

pydantic model radkit_service.control_api.UpdateDevice

Bases: RADKitBaseModel

Device model to validate data used for device updates.

field uuid: UUID4 [Required]

UUID to identify the device. This field is required for an update.

Constraints:

uuid_version = 4

Validated by:

validate_provisioning_variant

field name: UpdateField[NonEmptyString] = DontUpdate(dontUpdate=True)

The device name that will appear in RADKit, must be unique.

Validated by:

validate_name
validate_provisioning_variant

field host: UpdateField[NonEmptyString] = DontUpdate(dontUpdate=True)

Takes a management IP address or a hostname of the device on the network.

Validated by:

validate_hostname
validate_provisioning_variant

field deviceType: UpdateField[DeviceType] = DontUpdate(dontUpdate=True)

Same as the list in the RADKit service UI, identifying the device type in the inventory. Example=”LINUX”.

Validated by:

validate_provisioning_variant

field jumphostUuid: UpdateField[UUID | None] = DontUpdate(dontUpdate=True)

String Equivalent to the jumphost name on UI but for the API we use the unique identifier for the device.

Validated by:

validate_provisioning_variant

field enabled: UpdateField[bool] = DontUpdate(dontUpdate=True)

Boolean (True, False) switch to enable/disable access to device.

Validated by:

validate_provisioning_variant

field forwardedTcpPorts: UpdateField[PortRanges] = DontUpdate(dontUpdate=True)

Identify a range for port forwarding capabilities to be updated, example: (‘1027/15’)

Validated by:

validate_provisioning_variant

field labelUpdate: UpdateLabelSet [Optional]

Set of label ids to be updated.

Validated by:

validate_provisioning_variant

field description: UpdateField[str] = DontUpdate(dontUpdate=True)

String for adding a description to the device. Default is an empty string.

Validated by:

validate_provisioning_variant

field sourceKey: UpdateField[str | None] = DontUpdate(dontUpdate=True)

String identifier of device in external device store. Can be UUID.

Validated by:

validate_provisioning_variant

field sourceDevUuid: UpdateField[UUID | None] = DontUpdate(dontUpdate=True)

String UUID of device from which device obtained (example: a CatalystCenter uuid as a source of device).

Validated by:

validate_provisioning_variant

field metaDataUpdate: UpdateMetaDataSet [Optional]

A set of changes for device metadata.

Validated by:

validate_provisioning_variant

field terminal: UpdateField[UpdateTerminal | None] = DontUpdate(dontUpdate=True)

Passing an Update Terminal object to be associated with the device, documented at UpdateTerminal data type below

Validated by:

validate_provisioning_variant

field netconf: UpdateField[UpdateNetconf | None] = DontUpdate(dontUpdate=True)

Passing an Update Netconf object to be associated with the device, documented at UpdateNetconf data type below

Validated by:

validate_provisioning_variant

field snmp: UpdateField[UpdateSNMP | None] = DontUpdate(dontUpdate=True)

Passing an Update SNMP object to be associated with the device, documented at UpdateSNMP data type below

Validated by:

validate_provisioning_variant

field swagger: UpdateField[UpdateSwagger | None] = DontUpdate(dontUpdate=True)

Passing an Update Swagger object to be associated with the device, documented at UpdateSwagger data type below

Validated by:

validate_provisioning_variant

field http: UpdateField[UpdateHTTP | None] = DontUpdate(dontUpdate=True)

Passing an Update HTTP object to be associated with the device, documented at UpdateHTTP data type below

Validated by:

validate_provisioning_variant

field deviceTemplateRef: UpdateDeviceTemplateRef | None = None

Passing am Update Device Template Ref object to be associated with the device, documented at UpdateDeviceTemplateRef data type below

Validated by:

validate_provisioning_variant

pydantic model radkit_service.control_api.StoredTerminal

Bases: RADKitBaseModel

Terminal model used to represent resource stored in DB. See NewTerminal data type for more explanation of the fields below.

field connectionMethod: ConnectionMethod [Required]

field port: int [Required]

field username: str [Required]

field enableSet: bool [Required]

field useInsecureAlgorithms: bool [Required]

field jumphost: bool [Required]

field useTunnelingIfJumphost: bool [Required]

field provisioningVariant: ProvisioningVariant = ProvisioningVariant.DEFAULT

field capabilities: frozenset[TerminalCapabilities] = frozenset({TerminalCapabilities.DOWNLOAD, TerminalCapabilities.EXEC, TerminalCapabilities.INTERACTIVE, TerminalCapabilities.UPLOAD})

pydantic model radkit_service.control_api.NewTerminal

Bases: RADKitBaseModel

Terminal model used for resource creation.

field connectionMethod: Literal[ConnectionMethod.SSH, ConnectionMethod.TELNET, ConnectionMethod.SSHPUBKEY, ConnectionMethod.TELNET_NO_AUTH] = ConnectionMethod.SSH: Takes a string value from the ConnectionMethod enum, for example: “SSH” or “TELNET”. Default is SSH.

field port: int = 22

Integer representing a port of terminal connection. Default is 22.

Validated by:

validate_port_in_range

field username: str = '': String for the username that will be used in terminal connection to the device. Example: “device-username”. Default is an empty string.

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain String for the password that will be used in terminal connection. Default is none.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

field privateKeyPassword: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain string password for decrypting the private key. Default is none.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

field privateKey: AnnotatedCustomSecretStr = CustomSecretStr('')

String key. Supports keys in OPENSSH format. Default is none.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

Validated by:

validate_private_key

field enableSet: bool = False: Boolean. If True, the enable command will be sent after login, along with the enable password, on some device types. Default: False.

field enable: AnnotatedCustomSecretStr = CustomSecretStr('')

Password for entering enable/privileged mode on some device types. Default is none.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

field useInsecureAlgorithms: bool = False: Boolean for allowing usage of obselete/insecure SSH algorithms. Default is False.

field jumphost: bool = False: If True, device can act as a jumphost/tunnel. Otherwise, it cannot. Default is False.

field useTunnelingIfJumphost: bool = True: Boolean to use SSH tunneling when using this device as a jumphost (rather than autotyping a second ssh command at the terminal). Default is True.

field provisioningVariant: ProvisioningVariant = ProvisioningVariant.DEFAULT: Provisioning variant to prepare terminal connection.

field capabilities: frozenset[TerminalCapabilities] = frozenset({TerminalCapabilities.DOWNLOAD, TerminalCapabilities.EXEC, TerminalCapabilities.INTERACTIVE, TerminalCapabilities.UPLOAD}): Terminal capabilities.

pydantic model radkit_service.control_api.UpdateTerminal

Bases: UpdateModel

Terminal model used for resource update.

Password has to be optional. It allows API users to modify fields without a need to reenter password fields again.

If there are no credentials for the device it’s the API’s consumer responsibility to use the empty string as a value for them.

field connectionMethod: UpdateField[Literal[ConnectionMethod.SSH, ConnectionMethod.TELNET, ConnectionMethod.SSHPUBKEY, ConnectionMethod.TELNET_NO_AUTH]] = DontUpdate(dontUpdate=True): Takes a string value from the ConnectionMethod enum, for example: “SSH” or “TELNET”. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer representing a port of terminal connection. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): String for the username that will be used in terminal connection to the device. Example: “device-username”. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain String for the password that will be used in terminal connection. Default: don’t update.

field privateKeyPassword: CustomSecretStr = CustomSecretStr(''): Plain string password for decrypting the private key. Default: don’t update.

field privateKey: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True)

String key. Supports keys in OPENSSH format. Default: don’t update.

Validated by:

validate_private_key

field enableSet: UpdateField[bool] = DontUpdate(dontUpdate=True): Boolean. If True, the enable command will be sent after login, along with the enable password, on some device types. Default: don’t update.

field enable: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Password for entering enable/privileged mode on some device types. Default: don’t update.

field useInsecureAlgorithms: UpdateField[bool] = DontUpdate(dontUpdate=True): Boolean for allowing usage of obselete/insecure SSH algorithms. Default: don’t update.

field jumphost: UpdateField[bool] = DontUpdate(dontUpdate=True): If True, device can act as a jumphost/tunnel. Otherwise, it cannot. Default: don’t update.

field useTunnelingIfJumphost: UpdateField[bool] = DontUpdate(dontUpdate=True): Boolean to use SSH tunneling when using this device as a jumphost (rather than autotyping a second ssh command at the terminal). Default: don’t update.

field provisioningVariant: UpdateField[ProvisioningVariant] = DontUpdate(dontUpdate=True): Provisioning variant to prepare terminal connection.

field capabilities: UpdateField[frozenset[TerminalCapabilities]] = DontUpdate(dontUpdate=True): Terminal capabilities.

pydantic model radkit_service.control_api.StoredNetconf

Bases: RADKitBaseModel

Netconf model used to represent resource stored in DB. See NewNetconf datatype for more information on the fields below.

field port: int [Required]

field username: str [Required]

field useInsecureAlgorithms: bool [Required]

pydantic model radkit_service.control_api.NewNetconf

Bases: RADKitBaseModel

Netconf model used for resource creation.

field port: int = 830

Port for connection. 830 by default.

Validated by:

validate_port_in_range

field username: str = '': Connection credential username.

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain String for connection credential password.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

field useInsecureAlgorithms: bool = False: Boolean for allowing usage of obselete/insecure algorithms. Default is false.

pydantic model radkit_service.control_api.UpdateNetconf

Bases: UpdateModel

Netconf model used for resource update.

Passwords have to be optional. It allows API users to modify fields without a need to reenter password fields again.

If there are no credentials for the device it’s the API user’s responsibility to use the empty string as a value for them.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Port for connection. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): Connection credential username. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain String for connection credential password. Default: don’t update.

field useInsecureAlgorithms: UpdateField[bool] = DontUpdate(dontUpdate=True): Boolean for allowing usage of obselete/insecure algorithms. Default: don’t update.

pydantic model radkit_service.control_api.StoredSNMP

Bases: RADKitBaseModel

SNMP model used to represent resource stored in DB. See NewSNMP datatype for more information.

field version: int [Required]

Constraints:

ge = 1
le = 2

field port: int [Required]

pydantic model radkit_service.control_api.NewSNMP

Bases: RADKitBaseModel

SNMP model used for resource creation.

field version: int = 2

Integer representing the version of snmp, either 1 or 2. 2 by default.

Constraints:

ge = 1
le = 2

field port: int = 161

Integer representing the port of snmp. 161 by default.

Validated by:

validate_port_in_range

field communityString: AnnotatedCustomSecretStr = CustomSecretStr('')

String SNMP community string. Blank by default.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

pydantic model radkit_service.control_api.UpdateSNMP

Bases: UpdateModel

SNMP model used for resource update.

field version: UpdateField[SNMPVersion] = DontUpdate(dontUpdate=True): Integer representing the version of snmp, either 1 or 2. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer representing the port of snmp. Default: don’t update.

Validated by:

validate_port_in_range

field communityString: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): String SNMP community string. Default: don’t update.

pydantic model radkit_service.control_api.StoredSwagger

Bases: RADKitBaseModel

Swagger model used to represent resource stored in DB. See NewSwagger datatype for more information.

field schemaPath: str [Required]

field port: int [Required]

field username: str [Required]

field verify: bool | None = None

field useInsecureAlgorithms: bool [Required]

pydantic model radkit_service.control_api.NewSwagger

Bases: RADKitBaseModel

Swagger model used for resource creation.

field schemaPath: str = ''

Schema for swagger. Default is blank.

Validated by:

validate_schema_path_empty_or_starts_with_slash

field port: int = 443

Integer for specifying specific port. The default is 443.

Validated by:

validate_port_in_range

field username: str = '': Username credential for connecting to swagger. Default is blank.

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain string password credential for connecting to swagger. Default is blank.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

field verify: bool = True: If True, verify TLS certificate chain. Default is True.

field useInsecureAlgorithms: bool = False: Boolean for allowing usage of obselete/insecure algorithms. Default is False.

pydantic model radkit_service.control_api.UpdateSwagger

Bases: UpdateModel

Swagger model used for resource update.

Password has to be optional. It allows API users to modify field without a need to reenter password field again.

If there are no credentials for the device it’s the API user’s responsibility to use the empty string as a value for it.

field schemaPath: UpdateField[str] = DontUpdate(dontUpdate=True): Schema for swagger. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer for specifying specific port. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): Username credential for connecting to swagger. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain string password credential for connecting to swagger. Default: don’t update.

field verify: UpdateField[bool] = DontUpdate(dontUpdate=True): If True, verify TLS certificate chain. Default: don’t update.

field useInsecureAlgorithms: UpdateField[bool] = DontUpdate(dontUpdate=True): Boolean for allowing usage of obselete/insecure algorithms. Default: don’t update.

pydantic model radkit_service.control_api.StoredHTTP

Bases: RADKitBaseModel

HTTP model used to represent resource stored in DB.

field protocol: HTTPProtocol [Required]: Choosing connectivity Protocol the default is HTTPS.

field port: int [Required]: Integer for specifying specific port. The default is 443.

field username: str [Required]: Username credential for connecting to HTTP. Will not be updated if empty.

field verify: bool [Required]: If True, verify TLS certificate chain.

field useInsecureAlgorithms: bool [Required]: Boolean for allowing usage of obselete/insecure algorithms. Default is False.

field authenticationExtra: str | None = None: Optional type of authentication. Default depends on the device type. E.g. for ISE it is “Internal”.

pydantic model radkit_service.control_api.NewHTTP

Bases: RADKitBaseModel

HTTP model used for resource creation.

field protocol: HTTPProtocol = HTTPProtocol.HTTPS

Choosing connectivity Protocol. The default is HTTPS.

Validated by:

model_validator

field port: int = 443

Integer for specifying specific port. The default is 443.

Validated by:

model_validator
validate_port_in_range

field username: str = ''

Username credential for connecting to HTTP. Blank by default.

Validated by:

model_validator

field password: AnnotatedCustomSecretStr = CustomSecretStr('')

Plain string password credential for connecting to HTTP. Blank by default.

Constraints:

func = <function <lambda> at 0x7f8841ffdc60>
return_type = <class ‘str’>
when_used = json
json_schema = {‘type’: ‘string’}
mode = serialization

Validated by:

model_validator

field verify: bool = True

If True, verify TLS certificate chain. True by default.

Validated by:

model_validator

field useInsecureAlgorithms: bool = False

Boolean for allowing usage of obselete/insecure algorithms. Default is False.

Validated by:

model_validator

field authenticationExtra: str | None = None

Optional type of authentication. Default depends on the device type. E.g. for ISE it is “Internal”.

Validated by:

model_validator

pydantic model radkit_service.control_api.UpdateHTTP

Bases: UpdateModel

HTTP model used for resource update.

field protocol: UpdateField[HTTPProtocol] = DontUpdate(dontUpdate=True): Choosing connectivity Protocol. Default: don’t update.

field port: UpdateField[int] = DontUpdate(dontUpdate=True)

Integer for specifying specific port. Default: don’t update.

Validated by:

validate_port_in_range

field username: UpdateField[str] = DontUpdate(dontUpdate=True): Username credential for connecting to HTTP. Default: don’t update.

field password: UpdateField[AnnotatedCustomSecretStr] = DontUpdate(dontUpdate=True): Plain String password credential for connecting to HTTP. Default: don’t update.

field verify: UpdateField[bool] = DontUpdate(dontUpdate=True): If True, verify TLS certificate chain. Default: don’t update.

field useInsecureAlgorithms: UpdateField[bool] = DontUpdate(dontUpdate=True): Boolean for allowing usage of obselete/insecure algorithms. Default: don’t update.

field authenticationExtra: UpdateField[str | None] = DontUpdate(dontUpdate=True): Optional type of authentication. Default: don’t update.

pydantic model radkit_service.control_api.UpdateMetaDataSet

Bases: RADKitBaseModel

Data model for metadata to be added, removed or replaced on an entry in the DB.

field replace: Annotated[list[MetaDataEntry] | None, reject_duplicate_metadata] = None

Optional. A list of metadata entries to set. These will replace all metadata currently in place. May not be used together with add or remove.

Constraints:

max_length = 200
func = <function reject_duplicates.<locals>.validator at 0x7f883c0f5260>

Validated by:

check_add_remove_are_distinct
check_metadata_replace_xor_add_remove

field add: Annotated[list[MetaDataEntry], reject_duplicate_metadata] [Optional]

Optional. A list of metadata entries to be added to those currently in place, or changed. May be used together with remove.

Constraints:

max_length = 200
func = <function reject_duplicates.<locals>.validator at 0x7f883c0f5260>

Validated by:

check_add_remove_are_distinct
check_metadata_replace_xor_add_remove

field remove: list[str] [Optional]

Optional. A list of metadata keys to be removed from those currently in place. May be used together with add.

Validated by:

check_add_remove_are_distinct
check_metadata_replace_xor_add_remove

pydantic settings radkit_service.control_api.CatalystCenterImportSettings

Bases: BaseImportSettings

Data model for available import settings for Catalyst Center device type.

field import_terminal_credentials: bool = True (alias 'importTerminalCredentials'): Whether to import terminal credentials (defaults to True)

field import_http_credentials: bool = True (alias 'importHttpCredentials'): Whether to import HTTP credentials (defaults to True)

field import_snmp_credentials: bool = True (alias 'importSnmpCredentials'): Whether to import SNMP credentials (defaults to True)

field tag: str | None = None: Optional tag to filer the device inventory on

field import_nodes: bool = True (alias 'importCatalystCenterNodes'): Whether other nodes should be imported (defaults to True)

field import_cimc: bool = True (alias 'importCatalystCenterCimc'): Whether to import CIMC node(-s) (defaults to True)

field import_dr: bool = True (alias 'importCatalystCenterDr'): Whether to import Disaster Recovery node(-s) (defaults to True)

field nodes_source_address_type: IpSourceType = IpSourceType.MANAGEMENT (alias 'nodesSourceAddressType'): The type of the source address to choose when importing other nodes (defaults to ‘Management’)

pydantic settings radkit_service.control_api.CiscoAPICImportSettings

Bases: BaseImportSettings

Data model for available import settings for APIC device type.

field ip_source: IpSource | None = IpSource.OUT_OF_BAND (alias 'ipSource'): Source of the IP address: IN_BAND or OUT_OF_BAND (defaults to OUT_OF_BAND)

pydantic settings radkit_service.control_api.CSPCImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.CUCMImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.FMCImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.VManageImportSettings: Bases: BaseImportSettings

pydantic settings radkit_service.control_api.WLCImportSettings: Bases: BaseImportSettings

Labels 

pydantic model radkit_service.control_api.NewLabel

Bases: RADKitBaseModel

Label model to validate data used for creation.

field name: str [Required]

A string representing a label name. example=”SR12345”.

Constraints:

min_length = 1
max_length = 40

Validated by:

_validate_name_whitespace

field color: str = '#000000'

A string representing a color in HEX Code, example “#ff0000”.

Validated by:

_validate_css_color

pydantic model radkit_service.control_api.UpdateLabel

Bases: RADKitBaseModel

Label model to validate data used for updates

field id: int [Required]: A unique id for API calls to point to right label to be updated.

field name: UpdateField[NonEmptyLabel] = DontUpdate(dontUpdate=True)

A string representing a label name. example=”SR12345”, if empty don’t modify.

Validated by:

_validate_name_whitespace

field color: UpdateField[str] = DontUpdate(dontUpdate=True)

A string representing a color in HEX Code, example “#ff0000”. If empty don’t modify.

Validated by:

_validate_css_color

pydantic model radkit_service.control_api.StoredLabel

Bases: RADKitBaseModel

Label model to represent remote user data stored in DB in API. See NewLabel data type for more explanation of the fields below:

field id: int [Required]

field name: str [Required]

field color: str [Required]

classmethod from_db_label( label: DbLabel, ) → StoredLabel

pydantic model radkit_service.control_api.UpdateLabelSet

Bases: RADKitBaseModel

Data model for labels to be added, removed or replaced on an entry in the DB.

field replace: Sequence[int | str] | None = None

Optional. A sequence of integers or strings representing the labels to be affixed. These will replace any labels currently in place. May not be used together with add or remove.

Validated by:

check_labels_replace_xor_add_remove

field add: Sequence[int | str] [Optional]

Optional. A sequence of integers or strings representing the labels to be added to those currently in place. May be used together with remove.

Validated by:

check_labels_replace_xor_add_remove

field remove: Sequence[int | str] [Optional]

Optional. A sequence of integers or strings representing the labels to be removed from those currently in place. May be used together with add.

Validated by:

check_labels_replace_xor_add_remove

Settings 

pydantic model radkit_service.control_api.SettingChange

Bases: BaseModel

Requested settings changes to perform. If remove is set to True then value is ignored.

field setting: str [Required]

field layers: list[Literal['toml', 'api']] [Required]

Constraints:

min_length = 1
max_length = 2

field value: Any = None

field remove: bool = False

to_setting_change_param() → SettingChangeParam

pydantic model radkit_service.control_api.APISettingInfo

Bases: BaseModel

Setting detailed information.

field setting: str [Required]: Setting name

field effective_value: Annotated[Any, PlainSerializer(serialize_effective_value_helper, return_type=Any, when_used='json')] = None

Effective value of the setting

Constraints:

func = <function serialize_effective_value_helper at 0x7f883a300fe0>
return_type = typing.Any
when_used = json

field type: str [Required]: Type of the setting.

field value_source: Literal['default', 'toml', 'env', 'cli', 'api'] [Required]: Shows from which layer setting value was taken

field description: str [Required]: Short description of the setting.

field api_writable: bool [Required]: Boolean, if false, setting cannot be set via the api.

field api_persistent: bool [Required]: Boolean if false, setting cannot be saved to disk via the api.

field webui_visible: bool [Required]: Boolean, if true, the settings web interface will show this setting.

field layer_values: dict[Literal['default', 'toml', 'env', 'cli', 'api'], Annotated[Any, PlainSerializer(serialize_effective_value_helper, return_type=Any, when_used='json')]] [Required]: Shows how the setting was set

field layer_errors: dict[Literal['default', 'toml', 'env', 'cli', 'api'], str] [Required]: Shows the errors from layers

classmethod from_setting_info( setting_info: SettingInfo, ) → APISettingInfo