Ansibug

https://jborean93.github.io/ansibug/
Admin
Ansibug is a Python-based Debug Adapter Protocol (DAP) implementation designed to provide a...
Tokens:9,815
Snippets:28
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### 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"
```
Tokens:
Raw