- Blog
- Ansible community forum
- Documentation

Community.Routeros Collection Docs

# community.routeros.api_info module – Retrieve information from API

Note

This module is part of the community.routeros collection (version 2.19.0).

It is not included in `ansible-core`. To check whether it is installed, run `ansible-galaxy collection list`.

To install it, use: `ansible-galaxy collection install community.routeros`. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: `community.routeros.api_info`.

New in community.routeros 2.2.0

## Synopsis

- Allows to retrieve information for a path using the API.

- This can be used to backup a path to restore it with the community.routeros.api_modify module.

- Entries are normalized, dynamic and builtin entries are not returned. Use the `handle_disabled` and `hide_defaults` options to control normalization, the `include_dynamic` and `include_builtin` options to also return dynamic resp. builtin entries, and use `unfiltered` to return all fields including counters.

- Note that this module is still heavily in development, and only supports some paths. If you want to support new paths, or think you found problems with existing paths, please first create an issue in the community.routeros Issue Tracker.

## Requirements

The below requirements are needed on the host that executes this module.

- librouteros

- Python >= 3.6 (for librouteros)

## Parameters

Parameter | Comments
--- | ---
ca_path path added in community.routeros 1.2.0 | PEM formatted file that contains a CA certificate to be used for certificate validation. See also `validate_cert_hostname`. Only used when `tls=true` and `validate_certs=true`.
encoding string added in community.routeros 2.1.0 | Use the specified encoding when communicating with the RouterOS device. Default is `ASCII`. Note that `UTF-8` requires librouteros 3.2.1 or newer. Default: `"ASCII"`
force_no_cert boolean added in community.routeros 2.4.0 | Set to `true` to connect without a certificate when `tls=true`. See also `validate_certs`. Note: this forces the use of anonymous Diffie-Hellman (ADH) ciphers. The protocol is susceptible to Man-in-the-Middle attacks, because the keys used in the exchange are not authenticated. Instead of simply connecting without a certificate to “make things work” have a look at `validate_certs` and `ca_path`. Choices: `false` ← (default) `true`
handle_disabled string | How to handle unset values. `exclamation` prepends the keys with `!` in the output with value `null`. `null-value` uses the regular key with value `null`. `omit` omits these values from the result. Choices: `"exclamation"` ← (default) `"null-value"` `"omit"`
hide_defaults boolean | Whether to hide default values. Choices: `false` `true` ← (default)
hostname string / required | RouterOS hostname API.
include_builtin boolean added in community.routeros 2.4.0 | Whether to include builtin values. By default, they are not returned, and the `builtin` keys are omitted. If set to `true`, they are returned as well, and the `builtin` keys are returned as well. Choices: `false` ← (default) `true`
include_dynamic boolean | Whether to include dynamic values. By default, they are not returned, and the `dynamic` keys are omitted. If set to `true`, they are returned as well, and the `dynamic` keys are returned as well. Choices: `false` ← (default) `true`
include_read_only boolean added in community.routeros 2.10.0 | Whether to include read-only fields. By default, they are not returned. Choices: `false` ← (default) `true`
password string / required | RouterOS user password.
path string / required | Path to query. An example value is `ip address`. This is equivalent to running `/ip address print` in the RouterOS CLI. Choices: `"caps-man aaa"` `"caps-man access-list"` `"caps-man channel"` `"caps-man configuration"` `"caps-man datapath"` `"caps-man manager"` `"caps-man manager interface"` `"caps-man provisioning"` `"caps-man security"` `"certificate settings"` `"interface bonding"` `"interface bridge"` `"interface bridge mlag"` `"interface bridge port"` `"interface bridge port-controller"` `"interface bridge port-extender"` `"interface bridge settings"` `"interface bridge vlan"` `"interface detect-internet"` `"interface eoip"` `"interface ethernet"` `"interface ethernet poe"` `"interface ethernet switch"` `"interface ethernet switch port"` `"interface gre"` `"interface gre6"` `"interface l2tp-server server"` `"interface list"` `"interface list member"` `"interface ovpn-client"` `"interface ovpn-server server"` `"interface ppp-client"` `"interface pppoe-client"` `"interface pppoe-server server"` `"interface pptp-server server"` `"interface sstp-server server"` `"interface vlan"` `"interface vrrp"` `"interface wifi"` `"interface wifi aaa"` `"interface wifi access-list"` `"interface wifi cap"` `"interface wifi capsman"` `"interface wifi channel"` `"interface wifi configuration"` `"interface wifi datapath"` `"interface wifi interworking"` `"interface wifi provisioning"` `"interface wifi security"` `"interface wifi steering"` `"interface wifiwave2"` `"interface wifiwave2 aaa"` `"interface wifiwave2 access-list"` `"interface wifiwave2 cap"` `"interface wifiwave2 capsman"` `"interface wifiwave2 channel"` `"interface wifiwave2 configuration"` `"interface wifiwave2 datapath"` `"interface wifiwave2 interworking"` `"interface wifiwave2 provisioning"` `"interface wifiwave2 security"` `"interface wifiwave2 steering"` `"interface wireguard"` `"interface wireguard peers"` `"interface wireless"` `"interface wireless align"` `"interface wireless cap"` `"interface wireless security-profiles"` `"interface wireless sniffer"` `"interface wireless snooper"` `"iot modbus"` `"ip accounting"` `"ip accounting web-access"` `"ip address"` `"ip arp"` `"ip cloud"` `"ip cloud advanced"` `"ip dhcp-client"` `"ip dhcp-client option"` `"ip dhcp-relay"` `"ip dhcp-server"` `"ip dhcp-server config"` `"ip dhcp-server lease"` `"ip dhcp-server matcher"` `"ip dhcp-server network"` `"ip dhcp-server option"` `"ip dhcp-server option sets"` `"ip dns"` `"ip dns adlist"` `"ip dns static"` `"ip firewall address-list"` `"ip firewall connection tracking"` `"ip firewall filter"` `"ip firewall layer7-protocol"` `"ip firewall mangle"` `"ip firewall nat"` `"ip firewall raw"` `"ip firewall service-port"` `"ip hotspot service-port"` `"ip ipsec identity"` `"ip ipsec peer"` `"ip ipsec policy"` `"ip ipsec profile"` `"ip ipsec proposal"` `"ip ipsec settings"` `"ip neighbor discovery-settings"` `"ip pool"` `"ip proxy"` `"ip route"` `"ip route rule"` `"ip route vrf"` `"ip service"` `"ip settings"` `"ip smb"` `"ip socks"` `"ip ssh"` `"ip tftp settings"` `"ip traffic-flow"` `"ip traffic-flow ipfix"` `"ip traffic-flow target"` `"ip upnp"` `"ip upnp interfaces"` `"ip vrf"` `"ipv6 address"` `"ipv6 dhcp-client"` `"ipv6 dhcp-server"` `"ipv6 dhcp-server option"` `"ipv6 firewall address-list"` `"ipv6 firewall filter"` `"ipv6 firewall mangle"` `"ipv6 firewall nat"` `"ipv6 firewall raw"` `"ipv6 nd"` `"ipv6 nd prefix"` `"ipv6 nd prefix default"` `"ipv6 route"` `"ipv6 settings"` `"mpls"` `"mpls interface"` `"mpls ldp"` `"mpls ldp accept-filter"` `"mpls ldp advertise-filter"` `"mpls ldp interface"` `"port firmware"` `"port remote-access"` `"ppp aaa"` `"ppp profile"` `"ppp secret"` `"queue interface"` `"queue simple"` `"queue tree"` `"queue type"` `"radius"` `"radius incoming"` `"routing bgp aggregate"` `"routing bgp connection"` `"routing bgp instance"` `"routing bgp network"` `"routing bgp peer"` `"routing bgp template"` `"routing filter"` `"routing filter num-list"` `"routing filter rule"` `"routing filter select-rule"` `"routing id"` `"routing igmp-proxy"` `"routing igmp-proxy interface"` `"routing mme"` `"routing ospf area"` `"routing ospf area range"` `"routing ospf instance"` `"routing ospf interface-template"` `"routing ospf static-neighbor"` `"routing pimsm instance"` `"routing pimsm interface-template"` `"routing rip"` `"routing ripng"` `"routing rule"` `"routing table"` `"snmp"` `"snmp community"` `"system clock"` `"system clock manual"` `"system health settings"` `"system identity"` `"system leds settings"` `"system logging"` `"system logging action"` `"system note"` `"system ntp client"` `"system ntp client servers"` `"system ntp server"` `"system package update"` `"system resource irq rps"` `"system routerboard settings"` `"system scheduler"` `"system script"` `"system upgrade mirror"` `"system ups"` `"system watchdog"` `"tool bandwidth-server"` `"tool e-mail"` `"tool graphing"` `"tool graphing interface"` `"tool graphing resource"` `"tool mac-server"` `"tool mac-server mac-winbox"` `"tool mac-server ping"` `"tool netwatch"` `"tool romon"` `"tool sms"` `"tool sniffer"` `"tool traffic-generator"` `"user"` `"user aaa"` `"user group"` `"user settings"`
port integer | RouterOS api port. If `tls` is set, port will apply to TLS/SSL connection. Defaults are `8728` for the HTTP API, and `8729` for the HTTPS API.
restrict list / elements=dictionary added in community.routeros 2.18.0 | Restrict output to entries matching the following criteria.
field string / required | The field whose values to restrict.
invert boolean | Invert the condition. This affects `restrict[].match_disabled`, `restrict[].values`, and `restrict[].regex`. Choices: `false` ← (default) `true`
match_disabled boolean | Whether disabled or not provided values should match. Choices: `false` ← (default) `true`
regex string | A regular expression matching values of the field to limit to. Note that all values will be converted to strings before matching. It is not possible to match disabled values with regular expressions. Set `restrict[].match_disabled=true` if you also want to match disabled values.
values list / elements=any | The values of the field to limit to. Note that the types of the values are important. If you provide a string `"0"`, and librouteros converts the value returned by the API to the integer `0`, then this will not match. If you are not sure, better include both variants: both the string and the integer.
timeout integer added in community.routeros 2.3.0 | Timeout for the request. Default: `10`
tls aliases: ssl boolean | If is set TLS will be used for RouterOS API connection. Choices: `false` ← (default) `true`
unfiltered boolean | Whether to output all fields, and not just the ones supported as input for community.routeros.api_modify. Unfiltered output can contain counters and other state information. Choices: `false` ← (default) `true`
username string / required | RouterOS login user.
validate_cert_hostname boolean added in community.routeros 1.2.0 | Set to `true` to validate hostnames in certificates. See also `validate_certs`. Only used when `tls=true` and `validate_certs=true`. Choices: `false` ← (default) `true`
validate_certs boolean added in community.routeros 1.2.0 | Set to `false` to skip validation of TLS certificates. See also `validate_cert_hostname`. Only used when `tls=true`. Note: instead of simply deactivating certificate validations to “make things work”, please consider creating your own CA certificate and using it to sign certificates used for your router. You can tell the module about your CA certificate with the `ca_path` option. Choices: `false` `true` ← (default)

## Attributes

Attribute | Support | Description
--- | --- | ---
action_group | Action group: community.routeros.api | Use `group/community.routeros.api` in `module_defaults` to set defaults for this module.
check_mode | Support: full This action does not modify state. | Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode | Support: N/A This action does not modify state. | Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.
platform | Platform: RouterOS | Target OS/families that can be operated against.

## See Also

See also

community.routeros.api

  Ansible module for RouterOS API.

community.routeros.api_facts

  Collect facts from remote devices running MikroTik RouterOS using the API.

community.routeros.api_find_and_modify

  Find and modify information using the API.

community.routeros.api_modify

  Modify data at paths with API.

How to connect to RouterOS devices with the RouterOS API

  How to connect to RouterOS devices with the RouterOS API

## Examples

    ---
    - name: Get IP addresses
      community.routeros.api_info:
        hostname: "{{ hostname }}"
        password: "{{ password }}"
        username: "{{ username }}"
        path: ip address
      register: ip_addresses

    - name: Print data for IP addresses
      ansible.builtin.debug:
        var: ip_addresses.result

    - name: Get IP addresses
      community.routeros.api_info:
        hostname: "{{ hostname }}"
        password: "{{ password }}"
        username: "{{ username }}"
        path: ip address
      register: ip_addresses

    - name: Print data for IP addresses
      ansible.builtin.debug:
        var: ip_addresses.result

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Description
--- | ---
result list / elements=dictionary | A list of all elements for the current path. Returned: always Sample: `[{".id": "*1", "actual-interface": "bridge", "address": "192.168.88.1/24", "comment": "defconf", "disabled": false, "dynamic": false, "interface": "bridge", "invalid": false, "network": "192.168.88.0"}]`

### Authors

- Felix Fontein (@felixfontein)

### Collection links

- Issue Tracker
- Repository (Sources)
- Ask for help (RouterOS)
- Submit a bug report
- Request a feature
- Communication