{"id":7833,"library":"unicon-plugins","title":"Unicon Connection Library Plugins","description":"Unicon Plugins is a component of the Cisco pyATS framework, providing extensible platform support and services for the Unicon Connection Library. It enables unified command-line interface (CLI) connection experiences to various network devices, leveraging expect-like programming for multi-vendor support and seamless handling of CLI modes. Originally developed internally by Cisco, it was open-sourced in late 2017 through Cisco DevNet. The current version is 26.3, with releases typically aligning with the pyATS framework's frequent updates, often on a monthly or bi-monthly cadence.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/unicon.plugins","tags":["network automation","cisco","pyats","cli","plugins","network devices","telnet","ssh","serial"],"install":[{"cmd":"pip install unicon unicon-plugins","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"This package is the plugin component of Unicon and requires the main unicon library for core functionality.","package":"unicon"},{"reason":"Required for configuration and data handling.","package":"pyyaml"},{"reason":"Used for formatted output in some utilities.","package":"PrettyTable"},{"reason":"Required for secure communication (e.g., SSH). Version 43.0 or higher is specified.","package":"cryptography"}],"imports":[{"note":"Unicon plugins extend the base unicon.Connection class. Users interact with the Connection object from the 'unicon' package, and the relevant plugins are automatically loaded based on device OS/platform.","symbol":"Connection","correct":"from unicon import Connection"}],"quickstart":{"code":"import os\nfrom unicon import Connection\n\n# Example: Connecting to an IOS XE device\n# In a real scenario, device details and credentials would typically come from a pyATS testbed YAML file.\n# For a quick start, we'll simulate a direct connection.\n\nhostname = os.environ.get('DEVICE_HOSTNAME', 'your_device_ip_or_hostname')\nusername = os.environ.get('DEVICE_USERNAME', 'admin')\npassword = os.environ.get('DEVICE_PASSWORD', 'Cisco123')\nenable_password = os.environ.get('DEVICE_ENABLE_PASSWORD', 'Cisco123')\n\n# Instantiate a connection object for an IOSXE device\n# The 'os' argument directs Unicon to load the appropriate plugin.\n# Other parameters like 'platform' and 'model' can further refine plugin selection.\ntry:\n    print(f\"Attempting to connect to {hostname} (OS: iosxe)...\")\n    connection = Connection(\n        hostname=hostname,\n        os='iosxe',\n        start=['ssh {username}'], # Specifies how to start the connection\n        log_file='unicon_connection.log', # Optional: logs interaction\n        init_exec_commands=['terminal length 0', 'terminal width 0'], # Initial commands to run\n        custom_callbacks={\n            'password': lambda: password,\n            'enable_password': lambda: enable_password\n        }\n    )\n    \n    connection.connect()\n    print(f\"Successfully connected to {hostname}\")\n    \n    # Execute a command\n    output = connection.execute('show version')\n    print(\"\\n--- show version output ---\\n\")\n    print(output[:500]) # Print first 500 characters of output\n    print(\"\\n---------------------------\")\n    \n    # Configure the device (example - requires 'configure' service for the plugin)\n    # config_commands = ['interface Loopback100', 'description Test Loopback']\n    # print(f\"\\nAttempting to configure: {config_commands}\")\n    # connection.configure(config_commands)\n    # print(\"Configuration applied.\")\n    \nexcept Exception as e:\n    print(f\"Connection failed: {e}\")\nfinally:\n    if 'connection' in locals() and connection.is_connected():\n        connection.disconnect()\n        print(f\"Disconnected from {hostname}\")","lang":"python","description":"This quickstart demonstrates how to establish a basic CLI connection to a network device using `unicon.Connection`, leveraging the plugins to handle device-specific interactions. It uses environment variables for credentials, which is a common practice in automation. For a real environment, device details are typically managed via a pyATS Testbed YAML file."},"warnings":[{"fix":"Upgrade your Python environment to version 3.7 or newer.","message":"Support for Python 3.6 ended in April 2022. Users must migrate to Python versions 3.7, 3.8, 3.9, or 3.10 as pyATS (and thus Unicon Plugins) no longer supports 3.6.","severity":"breaking","affected_versions":"<= 22.5"},{"fix":"Ensure your device definitions (e.g., in pyATS testbed YAML) are accurate and reflect the exact OS, platform, and model of your network devices. Consult Unicon's supported platforms documentation.","message":"Accurate specification of 'os', 'platform', and 'model' is crucial for Unicon to load the most precise connection plugin. Incorrect or generic values might lead to fallback plugins, potentially causing unexpected behavior or missing device-specific features.","severity":"gotcha","affected_versions":"All"},{"fix":"Update your device configurations to use a currently supported 'fxos' plugin instead of 'fxos/ftd'.","message":"The 'fxos/ftd' plugin has been deprecated. Users should transition to using other available 'fxos' plugins for FTD devices.","severity":"deprecated","affected_versions":"All"},{"fix":"Follow the Unicon plugin development guidelines, starting with cloning existing plugin examples to ensure correct structure and mandatory files are in place.","message":"When developing new plugins, ensure all mandatory files (like `__init__.py`) are present and correctly structured within your plugin folder. Missing or improperly defined files can prevent auto-discovery and loading of your custom plugin.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify all credentials (username, password, enable password) are correct. Ensure they are correctly passed through environment variables, directly in the script, or via a pyATS testbed file. Check device logs for authentication failures.","cause":"Incorrect credentials (username, password, or enable password) provided for the device, or the device is configured to reject too many login attempts.","error":"unicon.core.errors.UniconAuthenticationError: Too many password retries"},{"fix":"Install the `unicon` package: `pip install unicon`.","cause":"The core `unicon` package, which `unicon-plugins` depends on, has not been installed in your Python environment.","error":"ImportError: No module named 'unicon'"},{"fix":"Examine the Unicon connection log (`log_file` parameter in `Connection`) for detailed interaction. This can reveal unexpected prompts, command rejections, or authentication issues at intermediate states. Adjust dialogs or credentials accordingly.","cause":"This often occurs when Unicon cannot transition the device through its expected CLI states (e.g., from user exec mode to privileged exec mode or configuration mode), possibly due to unexpected prompts, command failures, or missing credentials for state transitions. It's a high-level error often caused by underlying issues.","error":"unicon.core.errors.StateMachineError: Failed while bringing device to \"any\" state"},{"fix":"Check the command(s) being sent for syntax errors on the target device. Review the connection log for any unexpected output or error messages from the device. Adjust the command, add appropriate dialogs, or increase service timeouts if necessary.","cause":"A specific service (e.g., `execute`, `configure`, `monitor`) failed during execution, likely due to a command being rejected by the device, an unexpected prompt, or a timeout.","error":"unicon.core.errors.SubCommandFailure: <service_name> service failed to execute command(s)"}]}