scrapli Documentation

Many network devices require interacting with different privilege levels or 'modes' (e.g., moving from user EXEC mode to global configuration mode). Scrapli allows you to define these modes within your device definitions (or custom definitions) so you can switch between them to send inputs at the appropriate level.

To use this feature, ensure your device definition includes the necessary mode transitions, then use the CLI or API to target specific modes during your session.

libscrapli is designed for high efficiency across synchronous and asynchronous environments:

• Internal Read Loop: libscrapli runs a dedicated pthread for a "read loop" that constantly consumes data from the transport and stages it into a queue.
• Non-blocking Transports: Transports use epoll/kqueue to await readable data without blocking.
• Consumption Patterns:
  • Python (async/await): Operations are queued and pollable via an operation ID. Python awaits these by selecting on a file descriptor that notifies when an operation is complete.
  • Go: Natively asynchronous via the Go runtime.
  • Python (sync): Operations are polled on an interval with a simple backoff timer.

This architecture allows for cancellable reads and efficient resource usage regardless of whether the consumer is using synchronous or asynchronous patterns.

Scrapli uses transports to handle the actual sending and receiving of data to/from a server. There are three supported transports:

• telnet: A custom telnet driver (written in Zig) used for connecting to CLI devices via telnet.
• bin: The default transport for non-telnet connections. It is a pty-wrapper around a binary (typically /bin/ssh). This provides native support for OpenSSH features like ProxyJump, ControlPersist, ciphers, and key exchanges. The binary can be swapped for other tools like docker exec or serial port binaries.
• ssh2: A Zig wrapper around libssh2 with OpenSSL crypto. It does not require OpenSSH to be installed, making it ideal for containerized environments, though it only exposes minimum libssh2 features.

The read_with_callbacks method allows you to handle device interactions by triggering specific function calls based on the content received during a read operation. This is particularly useful for:

• Connecting to device consoles during boot up.
• Zero-touch-provisioning (ZTP) workflows.
• Tailing logs or other long-running outputs.
• Triggering specific logic immediately when certain patterns appear in the stream.

The Cli object provides several methods to send inputs (data/commands) to a network device. Depending on your use case, you can send a single input, multiple inputs, or inputs loaded from a file.

Available methods:

• send_input: Sends a single input.
• send_inputs: Sends multiple inputs.
• send_inputs_from_file: Sends inputs read from a file.

The scrapli.lib package contains the libscrapli shared objects required for operation. While these files are not stored in version control, they are populated during wheel installation or sdist installation.

If you are developing scrapli or want to use it directly from source, you must build the shared object for your specific platform. Running pip install . or pip install -e . will build the shared object and place it in the scrapli.lib directory.

# For standard installation
pip install .

# For editable development installation
pip install -e .

For simple semi-interactive device prompts—such as confirmation requests when writing a configuration or deleting a file—you can use the basic interaction handling capabilities provided by Scrapli. This approach is intended for straightforward scenarios where the device expects a simple response to a prompt.

For more complex or elaborate interactive scenarios (e.g., multi-step dialogues or conditional logic), use the read_with_callbacks method instead.