Core areas
Use the reference in this order when building a small diagnostic routine.
API reference / packet automation
Make packet tests repeatable.
The Tping API reference explains how to describe packet experiments, select protocol fields, capture responses, and turn a carefully scoped test into a scriptable workflow.
packet-lab / api-example
request = Packet.build(protocol="tcp"); request.set("flags", "syn"); request.set("dport", 443); result = request.send(target, count=3, timeout=2.0); for reply in result: record(reply.flags, reply.rtt) scope: authorized test environment
API reference
Describe the test, then inspect the result.
A useful interface keeps packet construction, transmission, and observation distinct. That separation makes scripts easier to review, adapt, and run within a documented boundary.
Keep each run legible.
Declare the protocol fields, constrain transmission, and save only the response data needed to answer the original question.
example.tping
test = packet(ip={"ttl":64}, tcp={"flags":"S", "dport":443}) run = send(test, target=lab_target, count=3, timeout=2) report(run.responses, fields=["flags", "rtt", "ttl"])
Field guide
Know what each control changes.
Packet-level options can affect routing, filtering, and endpoint behavior. The table below is a conceptual guide; exact names and capabilities depend on the implementation and operating system.
| Field | Purpose | Review before sending |
|---|---|---|
protocol | Selects the packet family or transport representation. | Confirm the test question and whether the target is in scope. |
flags | Expresses control bits such as a TCP connection state. | Consider how firewalls, hosts, and monitoring systems may respond. |
ttl | Sets the IP hop limit used during delivery. | Use conservative values when studying a known route. |
timeout | Limits how long the routine waits for an observation. | Separate a timeout from proof that a host is unavailable. |
count | Controls the number of transmitted packets. | Keep volume low and document any rate or scheduling limit. |
Script design
A small API workflow.
Good scripts answer one question at a time. They preserve enough context to interpret results without turning a diagnostic check into uncontrolled traffic.
Declare inputs
Record the target, protocol, fields, permissions, and expected observation before execution.
Validate locally
Check syntax, privileges, address formats, and safe transmission limits before opening the socket.
Run once
Start with the smallest useful count and capture timestamps, replies, and implementation details.
Explain output
Separate observed facts from interpretation, then preserve the script and scope notes together.
Responsible-use baselineUse the API only on systems you own or have explicit permission to assess. Keep examples inside an isolated lab whenever possible, and never place credentials or private packet captures in a report.
Troubleshooting
When a script does not behave as expected.
Packet results reflect local privileges, operating-system support, route policy, filtering, and the behavior of the remote endpoint.
Why does packet construction succeed but transmission fail?
Construction may require only local parsing, while transmission can require elevated privileges, a supported interface, a route, and permission from the operating system security policy.
Why is a timeout not proof of a blocked port?
A timeout can result from filtering, routing, congestion, endpoint policy, or an absent response path. Compare it with an authorized control test and document the uncertainty.
How should scripts handle missing replies?
Record the absence as an observation, keep the timeout and retry policy explicit, and avoid silently treating missing data as a positive or negative conclusion.
What should be logged for a reproducible run?
Keep the script version, platform, relevant privileges, target scope, packet fields, timing options, response summary, and any environmental changes.
Can the API examples be copied directly to every system?
No. Examples are conceptual references. Names, privileges, drivers, protocol support, and output formats can vary by platform and release.
Help improve the API record.
Send corrections, compatibility observations, and documentation questions. Do not include credentials, private captures, or confidential network details.