### Install Ansibug Python Library Source: https://jborean93.github.io/ansibug/index Installs the ansibug Python library using pip. This is a prerequisite for using ansibug with a DAP client. ```Shell python -m pip install ansibug ``` -------------------------------- ### Start Ansibug Listener with TLS Source: https://jborean93.github.io/ansibug/remote_debugging This command starts an Ansibug listener process with TLS enabled. It specifies the server certificate and key file, and the listening address. This configuration is used for secure communication between the Ansibug server and clients. ```bash python -m ansibug \ listen \ --wrap-tls \ --tls-cert ansibug.pem \ --addr tcp:// \ main.yml ``` -------------------------------- ### Run ansibug Debug Adapter Source: https://jborean93.github.io/ansibug/protocol_details This command starts the ansibug debug adapter, which listens for DAP messages over standard input and output. It's the primary way to initiate debugging sessions with ansibug. ```Shell python -m ansibug dap ``` -------------------------------- ### Ansibug: Example of Static Import Handling Source: https://jborean93.github.io/ansibug/stepping This example demonstrates how Ansibug handles static imports (`import_tasks`). When stepping out of a task included via `import_tasks`, it exits the entire play because the import is resolved statically and not part of the debugger's known stack. ```yaml # main.yml - name: task 1 import_tasks: file: tasks.yml - name: task 2 ping: # tasks.yml - name: task 3 # Currently stopped here ping: ``` -------------------------------- ### Ansible Module Options Example Source: https://jborean93.github.io/ansibug/variables This snippet demonstrates how module options are exposed and templated by Ansibug. It shows the 'path' and 'state' options for a file module, illustrating the final values after Jinja2 templating. ```YAML - file: path: /tmp/directory state: absent ``` -------------------------------- ### Get Help in ansibug Source: https://jborean93.github.io/ansibug/repl You can access help messages within the ansibug debug console. Use `!--help` to see the general help message for the repl, or `!command --help` to get specific help for a particular command. ```ansibug !--help ``` ```ansibug !set_option --help ``` -------------------------------- ### Ansibug Listener Command Source: https://jborean93.github.io/ansibug/index The `ansibug` module can be run as a listener for debugging Ansible playbooks. The `--addr` argument allows specifying the listening socket address, with various formats for Unix Domain Sockets (UDS) and TCP connections. Entries marked 'Listen Only' are for starting a listener, while others can be used for attaching. ```bash python -m ansibug listen --addr uds:// python -m ansibug listen --addr uds://filename python -m ansibug listen --addr uds:/tmp/filename python -m ansibug listen --addr uds:///tmp/filename python -m ansibug listen --addr tcp:// python -m ansibug listen --addr tcp://:0 python -m ansibug listen --addr tcp://:1234 python -m ansibug listen --addr tcp://hostname:1234 python -m ansibug listen --addr tcp://192.168.1.1:1234 python -m ansibug listen --addr tcp://[2001::1]:1234 ``` -------------------------------- ### Ansibug Variable Setting Example Source: https://jborean93.github.io/ansibug/variables Illustrates how to set string and variable values in Ansibug. Setting a string requires quotes to ensure it's treated as a literal, while setting a variable evaluates the variable's content. ```Python # Example of setting a string value # ansibug will wrap this with quotes automatically # 'string value' -> "'string value'" # Example of setting a variable value # ansibug will evaluate 'foo' and set the variable to its value # foo -> "{{ foo }}" ``` -------------------------------- ### Ansible: Ping task after adding host Source: https://jborean93.github.io/ansibug/threads_and_frames Shows a scenario where a `ping` task is executed after a host has been dynamically added. The example illustrates that the `ping` task will run on the newly added host in the subsequent play. ```yaml plays: - name: Play 1 hosts: all tasks: - name: Add host3 add_host: name: host3 groups: webservers - name: Play 2 hosts: webservers tasks: - name: Ping all webservers ping: ``` -------------------------------- ### Ansibug Watch Expression Example Source: https://jborean93.github.io/ansibug/variables Demonstrates setting a watch expression in Ansibug to monitor variable changes across task steps. The expression is automatically templated, and users should avoid wrapping it in quotes. ```Python # Example of setting a watch expression for 'foo' # Do not wrap the expression in quotes, e.g., "foo", not "'foo'" # The expression 'foo' will be evaluated on each step. ``` -------------------------------- ### Remove Module Option with ansibug Source: https://jborean93.github.io/ansibug/repl The `!remove_option` or `!ro` command is used to remove a module option from the current Ansible task. You specify the option name after the command. For example, `!remove_option data`. ```ansibug !remove_option data ``` ```ansibug !ro data ``` -------------------------------- ### Ansibug Logging Configuration Source: https://jborean93.github.io/ansibug/index Logging can be enabled for both the DA Server and Debuggee sides of Ansibug. For the DA Server, use `--log-file` and `--log-level` with the `python -m ansibug dap` command. For the Debuggee side during launch, these options are passed to the `python -m ansibug listen` command. ```bash python -m ansibug dap --log-file /path/to/server.log --log-level debug python -m ansibug listen --log-file /tmp/ansibug-debuggee.log --log-level debug ``` -------------------------------- ### Generate Test TLS Certificates with OpenSSL Source: https://jborean93.github.io/ansibug/remote_debugging This snippet demonstrates how to generate test TLS certificates for Ansibug using OpenSSL. It covers creating a Certificate Authority (CA), a server certificate and key, and a client certificate and key. The process includes generating private keys, certificate signing requests, self-signing certificates, and combining certificates with their respective private keys for use with Ansibug. ```bash openssl ecparam \ -name secp384r1 \ -genkey \ -noout \ -out ansibug-ca.key openssl req \ -new \ -x509 \ -out ansibug-ca.pem \ -key ansibug-ca.key \ -days 365 \ -subj "/CN=Ansibug CA" openssl ecparam \ -name secp384r1 \ -genkey \ -noout \ -out ansibug.key openssl req \ -new \ -x509 \ -out ansibug.pem \ -key ansibug.key \ -days 365 \ -subj "/CN=ansibug" \ -addext "subjectAltName = DNS:localhost,IP:127.0.0.1" \ -CA ansibug-ca.pem \ -CAkey ansibug-ca.key openssl ecparam \ -name secp384r1 \ -genkey \ -noout \ -out ansibug-client.key openssl req \ -new \ -x509 \ -out ansibug-client.pem \ -key ansibug-client.key \ -days 365 \ -subj "/CN=My Client" \ -addext "extendedKeyUsage = clientAuth" \ -CA ansibug-ca.pem \ -CAkey ansibug-ca.key rm ansibug-ca.key cat ansibug.key >> ansibug.pem cat ansibug-client.key >> ansibug-client.pem rm ansibug.key rm ansibug-client.key ``` -------------------------------- ### Ansibug Debuggee Logging Launch Arguments Source: https://jborean93.github.io/ansibug/index To enable logging for the debuggee side when launching Ansibug, you can specify `logFile` and `logLevel` within the launch configuration JSON. ```json { "logFile": "/tmp/ansibug-debuggee.log", "logLevel": "debug" } ``` -------------------------------- ### Ansibug Debugger Attach Configuration Source: https://jborean93.github.io/ansibug/index When attaching a debug client to an Ansibug listener, you can specify either the `processId` or the `address`. If `processId` is used, the client will look up the address details. The `address` argument can be a socket address, and optional arguments like `connectTimeout`, `useTls`, `tlsVerification`, and `pathMappings` can be provided. ```json { "processId": 30011 } { "address": "tcp://localhost:34419" } { "address": "tcp://localhost:34419", "connectTimeout": 10.0, "useTls": true, "tlsVerification": "none", "pathMappings": [ { "localRoot": "/path/to/local/project", "remoteRoot": "/path/to/remote/project" } ] } ``` -------------------------------- ### Ansibug Listen Mode (Random Port) Source: https://jborean93.github.io/ansibug/remote_debugging Launches the ansibug library in listen mode, binding to a randomly available TCP port to accept debugger connections. It specifies the playbook file to be debugged. ```python python -m ansibug listen \ --addr tcp://\ /home/ansible/playbooks/ansible-apache/main.yml ``` -------------------------------- ### Ansibug Listen Mode (Specific Port) Source: https://jborean93.github.io/ansibug/remote_debugging Launches the ansibug library in listen mode, binding to a specific TCP port (e.g., 1234) to accept debugger connections. It also specifies the playbook file to be debugged. ```python python -m ansibug listen \ --addr tcp://:1234\ /home/ansible/playbooks/ansible-apache/main.yml ``` -------------------------------- ### Ansibug Client Attach Configuration with TLS Source: https://jborean93.github.io/ansibug/remote_debugging This JSON configuration is used by an Ansibug client to attach to a listening process over a TLS-enabled connection. It specifies the address of the listener, enables TLS, and provides the path to the CA certificate for verification. This ensures secure and verified communication. ```json { "type": "attach", "address": "tcp://listening-host:12345", "wrapTls": true, "tlsVerification": "ansibug-ca.pem" } ``` -------------------------------- ### Set Module Option with ansibug Source: https://jborean93.github.io/ansibug/repl Similar to `!set_hostvar`, the `!set_option` command adds or sets module options for the current task. The format is `!set_option option_name expression`. Quoting is necessary for options with spaces, and expressions are templated. Literal string values should be quoted. ```ansibug !set_option my_option "some_value" ``` ```ansibug !set_option "option with space" "another value" ``` -------------------------------- ### Ansible Playbook with Block, Rescue, and Always Source: https://jborean93.github.io/ansibug/breakpoints This Ansible playbook illustrates a `block` structure with `rescue` and `always` clauses. Breakpoints cannot be set directly on the `block` line; they will snap back to the previous task or the first line of the block. ```yaml - block: # Cannot set a breakpoint here - name: task 1 ping: rescue: # Will snapback to 'task 1' - name: task 2 ping: always: # Will snapback to 'task 2' - name: task 3 ping: ``` -------------------------------- ### Ansible: Dynamically add a host Source: https://jborean93.github.io/ansibug/threads_and_frames Demonstrates how to dynamically add a host to the Ansible inventory during a play using the `add_host` module. This allows for the inclusion of new hosts in subsequent tasks or plays. ```yaml tasks: - name: Add a new host add_host: name: host3 groups: webservers ansible_host: 192.168.1.103 ``` -------------------------------- ### Ansible Playbook with Roles Source: https://jborean93.github.io/ansibug/breakpoints This Ansible playbook demonstrates the structure for including roles, which is a scenario where line breakpoints cannot be set on the role entries themselves. ```yaml - hosts: localhost roles: - role1 - role2 ``` -------------------------------- ### Template Expression with ansibug Source: https://jborean93.github.io/ansibug/repl The `!template` command evaluates an expression and returns its value. If no command is specified, `!template` is used by default. This is useful for testing templates and ensuring expected output. Expressions can include Python/Jinja2 data structures. ```ansibug !template {{ my_variable | to_nice_yaml }} ``` ```ansibug {{ my_variable | to_nice_yaml }} ``` -------------------------------- ### Ansibug Attach Configuration Source: https://jborean93.github.io/ansibug/remote_debugging A JSON configuration object used by the local debug client to attach to a remote ansibug listener. It specifies the remote address and defines path mappings between local and remote file systems for breakpoint synchronization. ```json { "request": "attach", "address": "tcp://remote-host:1234", "pathMappings": [ { "localRoot": "/home/my-user/dev/ansible-apache/", "remoteRoot": "/home/ansible/playbooks/ansible-apache/" } ] } ``` -------------------------------- ### Ansible Playbook with Imports Source: https://jborean93.github.io/ansibug/breakpoints This Ansible playbook showcases the use of `import_playbook`, `import_role`, and `import_tasks`. Line breakpoints are not supported on these import statements. ```yaml - import_playbook: play.yml - hosts: localhost tasks: - import_role: name: role1 - import_tasks: file: tasks.yml ``` -------------------------------- ### Configure Path Mappings in Ansible Debug Configuration Source: https://jborean93.github.io/ansibug/remote_debugging Specifies how to configure `pathMappings` in an Ansible debug configuration. This is crucial for remote attach scenarios where local and remote file paths differ. The configuration uses a list of objects, each containing `localRoot` and `remoteRoot` to define equivalent paths. ```json { "pathMappings": [ { "localRoot": "/home/local/dev/project/", "remoteRoot": "/usr/local/share/project/" } ] } ``` -------------------------------- ### Ansible: Refresh inventory Source: https://jborean93.github.io/ansibug/threads_and_frames Illustrates the use of `meta: refresh_inventory` to dynamically update the Ansible inventory. This is useful for adding or removing hosts based on external conditions or dynamic inventory scripts. ```yaml tasks: - name: Refresh inventory meta: refresh_inventory ``` -------------------------------- ### Set Host Variable with ansibug Source: https://jborean93.github.io/ansibug/repl The `!set_hostvar` command allows adding or setting host variables within the Ansible task. The format is `!set_hostvar varname expression`. Variables with spaces in their names should be quoted. The expression is templated before being set. ```ansibug !set_hostvar my_variable "some value" ``` ```ansibug !set_hostvar "variable with space" "another value" ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.