traceroute – Trace the route to a network host using AIX traceroute

Synopsis

This module traces the route that IP packets take to reach a destination host on AIX systems.

It launches UDP probe packets with incrementing time-to-live (TTL) values and listens for ICMP responses from gateways.

The module supports all major traceroute flags available on AIX and allows recording output to a file.

It is intended for network testing, measurement, and management purposes.

Requirements

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

  • AIX >= 7.1

  • Root or appropriate network privileges may be required for certain operations

Parameters

host (True, str, None)

The destination host name or IP address to trace the route to.

This is the target host for which the network path will be determined.

Can be specified as a hostname (e.g., google.com) or IP address (e.g., 8.8.8.8).

max_ttl (optional, int, None)

Maximum number of hops (time-to-live) to trace (-m flag).

Determines how many network hops the traceroute will attempt before stopping.

Each hop represents a router or gateway in the path to the destination.

Default is 30 hops if not specified.

numeric (optional, bool, False)

Display hop addresses numerically only, without performing DNS lookups (-n flag).

When enabled, speeds up the traceroute by skipping reverse DNS resolution.

Useful when DNS is slow or unavailable, or when you only need IP addresses.

port (optional, int, None)

Base UDP port number to use for probe packets (-p flag).

The traceroute command uses sequential port numbers starting from this base value.

Each probe increments the port number to help identify responses.

Default is 33434 if not specified.

queries (optional, int, None)

Number of probe packets to send per hop (-q flag).

Determines how many probes are sent at each TTL level to measure round-trip time.

More queries provide better statistics but increase network load and execution time.

Default is 3 probes per hop if not specified.

bypass_routing (optional, bool, False)

Bypass the normal routing tables and send probe packets directly to a host on an attached network (-r flag).

This option forces packets to be sent directly without consulting the routing table.

Only works for hosts on directly attached networks (same subnet).

Returns an error if the specified host is not on a directly attached network.

Useful for testing local network connectivity or debugging routing issues.

debug (optional, bool, False)

Enable socket-level debugging for detailed network operation information (-d flag).

Provides low-level debugging output about socket operations and packet handling.

Useful for troubleshooting network issues or understanding packet flow.

Generates verbose output that may be difficult to interpret without networking knowledge.

source_address (optional, str, None)

Use the specified IP address as the source address in outgoing probe packets (-s flag).

Forces the source IP address to be different from the default interface address.

Useful on hosts with multiple network interfaces to control which interface is used.

The specified IP address must be configured on one of the machine’s network interfaces.

Returns an error if the IP address is not found on any local interface.

tos (optional, int, None)

Set the Type-Of-Service (TOS) value in probe packets (-t flag).

TOS is a field in the IP header that indicates the desired quality of service.

Valid range is 0 to 255 (decimal integer).

Different TOS values may result in different routing paths through the network.

Common useful values include 16 (minimize delay), 8 (maximize throughput), 4 (maximize reliability), and 2 (minimize cost).

Default is 0 (normal service) if not specified.

verbose (optional, bool, False)

Enable verbose output to receive all ICMP packets, not just TIME_EXCEEDED and PORT_UNREACHABLE (-v flag).

Displays additional information about ICMP packets received during the trace.

Useful for detailed network diagnostics and understanding all responses from intermediate hops.

May produce significantly more output than the standard traceroute.

wait_time (optional, int, None)

Time in seconds to wait for a response to each probe packet (-w flag).

Determines how long the traceroute waits before considering a probe as timed out.

Longer wait times may be necessary for slow or congested networks.

Shorter wait times speed up the traceroute but may miss legitimate responses.

Default is 3 seconds if not specified.

packet_size (optional, int, None)

Size of the probe packet in bytes.

Allows testing with different packet sizes to identify MTU issues or size-dependent routing.

Larger packets may be fragmented or dropped on networks with smaller MTU values.

Default packet size is determined by the MTU of the outgoing network interface if not specified.

Typical values range from 40 bytes (minimum) to 1500 bytes (standard Ethernet MTU).

recorded_output (optional, str, None)

File path where the traceroute command output will be recorded.

If specified, both stdout and stderr from the traceroute command are written to this file.

The directory path must exist or will be created automatically.

Useful for logging, auditing, or later analysis of network paths.

concatenated_output (optional, bool, False)

Controls whether to append to or overwrite the output file specified in recorded_output.

When true, new output is appended to the existing file content.

When false, the file is overwritten with new output.

Only used when recorded_output parameter is specified.

Useful for collecting multiple traceroute results in a single log file.

Notes

Note

Examples

- name: Basic traceroute
  ibm.power_aix.traceroute:
    host: google.com

- name: Traceroute with numeric output and max hops
  ibm.power_aix.traceroute:
    host: 8.8.8.8
    numeric: true
    max_ttl: 20

- name: Record traceroute output
  ibm.power_aix.traceroute:
    host: example.com
    recorded_output: /tmp/traceroute.log
    concatenated_output: true

- name: Traceroute using specific interface
  ibm.power_aix.traceroute:
    host: 192.168.1.1
    verbose: true

- name: Traceroute with custom packet size and wait time
  ibm.power_aix.traceroute:
    host: example.com
    packet_size: 512
    wait_time: 5
    queries: 5

Return Values

msg (always, str, )

Execution message.

rc (always, int, )

Return code.

stdout (always, str, )

Standard output.

stderr (always, str, )

Standard error.

cmd (always, str, )

Executed traceroute command.

Status

Authors

  • AIX Development Team (@vivekpandeyibm)