Observe Linux network activity, verify Qtap locally, and perform a carefully limited remote metrics test
Qtap is an open-source Linux eBPF agent that captures traffic flowing through the kernel and associates it with available process, container, host, user, and protocol context. This guide covers its documented Linux requirements, host installation, official Docker configuration, startup, metrics endpoints, verification, operations, and troubleshooting. After Qtap works locally, we show how a Localtonet HTTP tunnel can make the metrics listener publicly reachable without inbound router port forwarding or a public IP address. The documented Qtap listener has no established authentication, so direct publication must be treated as a temporary, closely supervised test unless you add a separately verified authentication or access-control layer. Qtap's maintainers describe the project as being in early development, so test upgrades and configuration changes before relying on them operationally.
📋 What's in this guide
How Qtap and Localtonet fit into this workflow
Qtap's canonical open-source repository describes an eBPF agent that captures traffic flowing through the Linux kernel. It attaches to TLS and SSL functions so supported data can be intercepted before encryption and after decryption, then passed to plugins with the context Qtap can determine, including process, container, host, user, and protocol information.
This observation model can support security auditing, network debugging, API development, third-party integration troubleshooting, protocol exploration, legacy-system investigation, and validation testing. Because Qtap can reveal data in its original form around TLS processing, it must be deployed only where you are authorized to inspect the relevant traffic.
This tutorial concerns the open-source qpoint-io/qtap project. Qpoint's current product landing page has been repurposed to describe a broader AI-agent operations product, so it should not be used as the technical authority for the open-source agent commands and metrics workflow documented here. Use the GitHub repository, its README, and files in that repository when validating Qtap behavior.
Qtap's role in this workflow is local observability. Localtonet's role is network reachability. Our client establishes an outbound connection from the Linux device to a Localtonet relay and, when an HTTP tunnel is running, provides a public HTTPS URL that forwards requests to the configured local HTTP target. Creating that reachability does not add authentication to the upstream service.
/metrics and agent-health metrics at /system/metrics on localhost port 10001.
Keep installation, local verification, and remote reachability as separate stages. First prove that Qtap starts successfully. Next prove that both metrics paths respond on the Linux host. Only then consider a remote test. This order makes failures easier to isolate and avoids exposing an endpoint before you know what it returns.
For the loopback target used in this tutorial, the Localtonet client should run directly on the Qtap host. A separate machine cannot use its own 127.0.0.1 address to reach Qtap because every machine has its own loopback interface. Containers and virtual machines can introduce the same namespace distinction.
Starting a plain Localtonet HTTP tunnel makes the configured service publicly reachable through its assigned URL. HTTPS protects traffic in transit to the tunnel edge, but it does not decide who is authorized to read Qtap's metrics. Possession of a URL, including a long or hard-to-guess URL, must not be treated as authentication.
Qtap also includes a built-in DevTools interface, but the project evidence used for this tutorial does not establish its listening address or port. Port 10001 is documented for the two metrics paths. We therefore do not guess a DevTools tunnel target.
Check the Linux prerequisites before installing Qtap
Confirm the operating-system, kernel, BTF, eBPF, and permission requirements before running the installer. A missing kernel facility can look like an application failure even though Qtap never had the capabilities needed to load or attach its eBPF programs.
| Requirement | Documented expectation | How to assess it |
|---|---|---|
| Operating system | A Linux host | Run uname -s and confirm that it reports Linux. |
| Kernel version | Linux kernel 5.10 or newer | Run uname -r and compare the active kernel with the requirement. |
| BPF Type Format | BTF must be enabled | Verify that /sys/kernel/btf/vmlinux exists. |
| eBPF | eBPF must be enabled on the host | Review the host's kernel configuration if Qtap reports BPF loading or attachment errors. |
| Privileges | Elevated host or container permissions | Use sudo for the host process or the documented Docker privileges and host integration. |
| Docker, if selected | A working Docker installation and permission to run the documented profile | Confirm that organizational controls permit privileged containers, host namespaces, host mounts, and root execution. |
| Temporary remote test | A Localtonet client on a device that can reach the service | For the documented loopback listener, place our client on the Qtap host and target 127.0.0.1:10001. |
Inspect the operating system and active kernel
uname -s
uname -rThe first command should identify Linux. The second prints the active kernel release. Qtap requires kernel 5.10 or newer. Distribution release labels are not a substitute for checking the running kernel because systems can use different kernel streams or continue running an older kernel until they are rebooted.
Verify BPF Type Format support
test -e /sys/kernel/btf/vmlinux && echo "BTF is available" || echo "BTF is not available at the documented path"
Qtap's repository identifies /sys/kernel/btf/vmlinux as the BTF check. If the file is missing, stop and investigate the kernel packages and configuration for your distribution. The package or replacement kernel needed varies between environments, so there is no safe universal package-manager command to provide here.
Plan for elevated access
The host workflow starts Qtap with sudo qtap. The official Docker example runs as root, uses privileged mode, adds BPF and system-administration capabilities, joins the host PID and network namespaces, mounts /sys and the Docker socket, and removes the memlock limit. These permissions are substantial because Qtap interacts with kernel and process facilities unavailable to an ordinary application.
Qtap can observe sensitive network content, including data around TLS processing. Install it only on systems where you are authorized to inspect traffic. Restrict host administration, review the software and deployment method according to your organization's policy, and do not place the agent on an untrusted multi-tenant host without an appropriate security assessment.
Install and run Qtap directly on the Linux host
Direct installation is the shortest documented path for evaluating Qtap on a compatible Linux system. The installer is fetched from get.qpoint.io and piped to a privileged shell. That pattern executes remotely retrieved code as root, so assess it under your normal software-review and change-management process before running it.
Confirm the host requirements
Verify Linux, kernel 5.10 or newer, BTF at /sys/kernel/btf/vmlinux, enabled eBPF support, and permission to use sudo.
Run the documented installer
Execute the official installation command shown below after completing any required review of the downloaded script and release.
Start Qtap with its documented defaults
Run sudo qtap and leave it running while you verify the metrics service from another terminal.
curl -s https://get.qpoint.io/install | sudo sh
sudo qtapWatch the terminal for startup messages and errors. If the process exits, investigate its output before moving on. Do not add flags copied from another release or an unofficial tutorial unless they are supported by the version you installed.
Optional temporary demo mode
Qtap also documents a temporary demo command that displays traffic in real time in the terminal:
curl -s https://get.qpoint.io/demo | sudo sh
Demo mode can help with an initial evaluation, but it is not the installed-agent workflow used by the remainder of this guide. For repeatable metrics verification, use the installation command and start the installed qtap binary.
The repository documents installation followed by sudo qtap. It does not establish a systemd unit name, configuration-file path, automatic-start policy, or Qtap-specific shutdown command for this workflow. Treat the foreground process as the verified startup method. Check the current repository and release documentation before designing production service management.
Run Qtap using the documented Docker configuration
Docker does not remove Qtap's need to interact deeply with the host. The repository's invocation uses root, privileged mode, host PID and network namespaces, added capabilities, host mounts, and an unlimited memlock setting. It must not be interpreted as an isolated or low-permission container profile.
Before using it, review Docker's primary documentation for runtime privileges and Linux capabilities and the host network driver. These references explain the Docker mechanisms involved. Qtap's repository remains the authority for the particular option set required by its documented example.
Validate the Linux host and Docker policy
Confirm kernel 5.10 or newer, BTF, enabled eBPF, a working Docker installation, and authorization to run a privileged container with host integration.
Start the official Qtap container image
Run the repository's documented command exactly as shown. It uses the v0 image tag, host networking and PIDs, required mounts, root execution, elevated capabilities, and informational logging.
Keep the attached container running during verification
Observe its output for startup or eBPF errors, then use a second host terminal to request both metrics paths. The documented command does not include detached mode or a restart policy.
docker run \
--user 0:0 \
--privileged \
--cap-add CAP_BPF \
--cap-add CAP_SYS_ADMIN \
--pid=host \
--network=host \
-v /sys:/sys \
-v /var/run/docker.sock:/var/run/docker.sock \
-e TINI_SUBREAPER=1 \
--ulimit=memlock=-1 \
us-docker.pkg.dev/qpoint-edge/public/qtap:v0 \
--log-level=info
Host networking is important to the verification workflow because the container shares the host network namespace. The documented service on localhost port 10001 can therefore be requested from the host. The host PID namespace, /sys mount, and Docker socket mount also give the container extensive visibility and control surfaces.
The available evidence does not establish a restricted alternative that retains full Qtap functionality. Removing privileges, mounts, capabilities, namespace sharing, or the memlock setting may stop process discovery or eBPF loading and attachment. If policy prohibits this model, do not weaken the command by trial and error and assume the result is equivalent. Use a controlled test host or obtain updated guidance from the Qtap project.
Verify both Qtap metrics endpoints locally
Local verification is the most important checkpoint in this tutorial. A tunnel cannot repair a Qtap process that failed to start, a missing kernel capability, or a metrics listener that is not responding. Run these requests on the same Linux host where Qtap is active:
curl http://localhost:10001/metrics
curl http://localhost:10001/system/metricsThe first path contains metrics that can be used to monitor activity on the system. The second contains metrics related to the health of the Qtap agent. Confirm that each request succeeds and returns a nonempty metrics payload appropriate to the installed version.
| Check | Purpose | What success establishes |
|---|---|---|
/metrics |
Activity metrics | The documented activity endpoint is responding locally. |
/system/metrics |
Qtap agent-health metrics | The documented agent-health endpoint is responding locally. |
| Qtap terminal or container output | Startup and runtime diagnostics | No visible BPF, permission, attachment, or runtime error is preventing operation. |
| Returned metric names and labels | Schema validation | Your dashboards and alerts can be designed against the version actually deployed. |
Generate authorized test traffic if activity is sparse
A quiet host may produce little observable application traffic. Generate an ordinary, authorized request from an application on that host and then request /metrics again. Do not send production secrets merely to create demonstration data.
Distinguish HTTP reachability from observation coverage
A successful HTTP response proves that the metrics server can be reached. It does not prove that every process, library, protocol, or desired transaction is being observed. Inspect Qtap's output and the returned series, then verify that the workload you care about is represented under the conditions you intend to monitor.
Treat the metric schema as version-specific
Qtap is in early development, and its maintainers state that APIs may change. Do not assume that every release exports an identical set of metric names or labels. Test dashboard queries, recording rules, and alerts against the exact version you plan to deploy.
Qtap includes examples/dashboards/qtap-http-overview.json. It can help you understand the expected visualization workflow. The project evidence used here does not define a complete Grafana installation, data-source configuration, or protected remote-scrape architecture, so those environment-specific steps are outside this tutorial.
Run a temporary Qtap metrics test through Localtonet
Proceed only after both metrics paths work locally and you have inspected what they disclose. A plain Localtonet HTTP tunnel creates a public route to the target service. The Qtap evidence does not document authentication for its metrics listener, and this tutorial does not claim a Localtonet access-control feature that would make the endpoint private.
If you have a separately verified authentication or access-control layer that sits in front of Qtap and is suitable for your environment, point the tunnel at that protected layer rather than directly at an unauthenticated listener. Its configuration is outside this tutorial because no particular reverse proxy, identity provider, collector, or Localtonet authorization option has been established by the supplied evidence.
If no such layer is available, use direct publication only as a brief, closely supervised connectivity test. Start the tunnel immediately before the test, do not distribute the URL, verify the required path, and stop the tunnel immediately afterward. Do not configure ongoing scraping or persistent exposure under this unprotected workflow.
Do not leave the evidenced Qtap metrics listener publicly reachable for ongoing use without a separately verified authentication or access-control layer. HTTPS encrypts transport but does not authorize callers. A generated subdomain, custom subdomain, custom domain, or hard-to-guess URL does not change this requirement.
The dashboard sequence below follows our documented HTTP tunnel flow while avoiding hardcoded client installation commands, relay codes, regions, plan availability, and custom-domain DNS instructions. Check the current Localtonet HTTP tunnel documentation and the live dashboard because available values and packaging can change.
Install and run the Localtonet client on the Qtap host
Use the current client for the host operating system. Keep it running on the Linux device that can reach Qtap at 127.0.0.1:10001. Obtain current installation details from our application and documentation rather than copying an unverified command.
Open the HTTP tunnel configuration and select a process type
Choose the HTTP tunnel family. Select Random Sub Domain, Custom Sub Domain, or Custom Domain as available for your account and current dashboard. These process types serve the target through a public HTTPS address. Confirm any availability or domain requirements in the current product.
Select the device authentication token
Choose the device-specific AuthToken for the Localtonet client running on the Qtap host. Never place the token in commands, screenshots, monitoring labels, dashboards, public repositories, or shared documentation.
Select an available relay server
Choose a currently available server or region from the live dashboard. Do not copy a hardcoded server code from a tutorial because availability can vary.
Enter the local IP address and port
Set the local target IP address to 127.0.0.1 and the port to 10001. This is the same listener you already verified locally. If you add an authenticated intermediary, use that protected service's verified local target instead.
Start the tunnel immediately before testing
Creating a tunnel does not start it. Press the Start button and wait for the selected client and tunnel to connect. The public route remains available only while the client is connected and the tunnel is running.
Request the required metrics path and stop the tunnel
For an unprotected test, request only the intended /metrics or /system/metrics path, confirm the result, and stop the tunnel immediately. Do not leave it running after the supervised test.
Append the same path used locally to the exact public HTTPS URL shown in the dashboard. If the dashboard displayed an illustrative address such as https://your-assigned-address.example, the conceptual URLs would be https://your-assigned-address.example/metrics and https://your-assigned-address.example/system/metrics. That hostname is not a real Localtonet address. Use only the URL assigned to your tunnel.
Do not assume the root path provides a dashboard. The evidenced interfaces are the two metrics paths. Also remember that a successful remote response verifies forwarding, not authorization. If anyone on the public internet can make the same request and receive the data, the endpoint is publicly accessible.
Protect the observability and tunnel boundaries
This deployment combines a highly privileged observability agent with an HTTP metrics service. Qtap's privileges determine what the agent can inspect on the host. A Localtonet tunnel determines how the HTTP target can be reached from the internet. Securing one boundary does not automatically secure the other.
Require real authorization for persistent exposure
Persistent remote collection requires a verified layer that authenticates or otherwise authorizes every caller before the request reaches Qtap. Select and validate that layer according to your environment, threat model, and collector. Confirm its behavior with unauthorized as well as authorized requests.
This article deliberately does not name a Localtonet access-control setting because none has been established by the supplied product evidence for this workflow. It also does not prescribe an unverified reverse-proxy configuration. If you cannot document how unauthorized requests are denied, do not keep the tunnel running.
Understand what HTTPS does and does not do
The HTTP tunnel's public address uses HTTPS, which protects traffic during transport to the tunnel edge. That is valuable, but it is not an identity check and does not make an unauthenticated upstream application private. URL secrecy is not a substitute for authentication, and changing from a generated subdomain to a custom domain does not add authorization by itself.
Protect the Qtap host
Restrict administrative access and keep the Linux kernel, Docker engine if used, Qtap, and the Localtonet client under normal patch and change-management procedures. The Docker deployment has broad host visibility through privileged mode, host namespaces, /sys, and the Docker socket. Do not allow untrusted users to control the container or replace its image.
Keep device tokens out of operational data
A Localtonet AuthToken identifies a client device and must remain private. Do not place it in Qtap labels, command examples, shell scripts committed to source control, container images, screenshots, alert annotations, or dashboard variables. The token is not part of a metrics URL and should never be sent to Qtap.
Review the actual exported data
Inspect the metric names and labels returned by your installed version before allowing remote access. Metrics can reveal operational information such as activity patterns, process context, service relationships, or health state. Make an exposure decision based on the actual payload rather than the generic word “metrics.”
Separate metrics from captured traffic
This tutorial exposes only the documented metrics listener. It does not claim that these paths return every captured payload, nor does it establish a remote interface for retrieving all observed traffic. Do not infer undocumented remote-data capabilities from Qtap's local observation model.
Operate and troubleshoot the complete setup
Use an inside-out diagnostic sequence
First confirm that Qtap is still running. Next confirm both local HTTP paths. Then confirm that the Localtonet client is connected. Finally verify that the tunnel is started, its target is correct, and the remote request includes the intended path. This sequence prevents a public connectivity symptom from hiding a local agent failure.
| Symptom | Likely area | What to check |
|---|---|---|
| Qtap exits during startup | Kernel support or permissions | Check the kernel version, BTF file, eBPF availability, elevated privileges, and exact process output. |
| Local port 10001 does not respond | Qtap process or listener | Confirm that sudo qtap or the Docker container is still running and inspect its output. |
/metrics responds but looks quiet |
Workload activity or observation coverage | Generate authorized application traffic and review Qtap output for attachment or discovery problems. |
| Docker reports BPF errors | Host capability or modified options | Recheck BTF, eBPF, kernel compatibility, privileges, capabilities, namespaces, mounts, and memlock configuration. |
| Local metrics work but the public URL does not | Localtonet target or lifecycle | Confirm that the device is connected, the target is 127.0.0.1:10001, and the tunnel has been started. |
| The public root URL has no useful output | Incorrect request path | Request /metrics or /system/metrics rather than assuming the root path is a user interface. |
| A client on another machine cannot reach localhost | Network-context mismatch | Run the Localtonet client on the Qtap host. Another machine's 127.0.0.1 refers to that other machine. |
| The endpoint is reachable without credentials | Missing authorization layer | Stop the tunnel. Add and verify appropriate protection before any persistent exposure. |
Confirm the foreground process is still running
The documented host command runs Qtap in the foreground. Closing its terminal or interrupting the process may remove the listener. The documented Docker command is also attached because it does not include -d. Check the relevant terminal before investigating the network.
Repeat local checks with the numeric loopback address
curl http://127.0.0.1:10001/metrics
curl http://127.0.0.1:10001/system/metrics
Using 127.0.0.1 mirrors the direct Localtonet target and removes local hostname resolution from the check. If these requests fail, stop investigating the tunnel until Qtap responds locally.
Recheck Docker command fidelity
Compare the running configuration with the documented invocation. Pay attention to --user 0:0, --privileged, both added capabilities, host PID and network modes, both mounts, TINI_SUBREAPER, and the memlock ulimit. Container-hardening tools and orchestration policies can reject or rewrite these options.
Verify tunnel state separately from tunnel existence
A saved tunnel configuration is not proof that the endpoint is online. The tunnel must be started, and its selected Localtonet client must remain connected. Qtap must also remain active. Failure of any one of these layers makes the remote path unavailable.
Plan upgrades conservatively
Qtap's early-development status means APIs, metrics, and documentation can change. Test a new release against your kernel, workload, dashboards, alert rules, and collection process before updating a monitored host. Record the version or image reference used by each environment. The documented Docker example uses the broad v0 tag, so do not assume its contents remain identical indefinitely.
Stop access as soon as testing ends
For the direct, unauthenticated workflow, stop the Localtonet tunnel immediately after the remote request is verified. Delete it as well if the configuration is no longer needed. Then stop Qtap according to how you launched it. For the documented foreground workflows, use the terminal's normal process-interruption mechanism. No Qtap-specific shutdown subcommand is established by the available evidence.
Frequently asked questions
What Linux kernel version does Qtap require?
Qtap documents Linux kernel 5.10 or newer. The host also needs BPF Type Format support, with /sys/kernel/btf/vmlinux present, and eBPF enabled. Check the active kernel with uname -r.
Which Qtap metrics endpoints are documented?
Qtap documents /metrics for system-activity metrics and /system/metrics for Qtap agent-health metrics. Both are documented on localhost port 10001.
Does Qtap document authentication for its metrics listener?
No authentication mechanism for the evidenced metrics listener is established by the project material used here. Do not assume one exists. Require a separately verified authentication or access-control layer for ongoing remote exposure.
Does a Localtonet HTTPS URL make the metrics private?
No. HTTPS protects transport, but it does not authenticate or authorize callers. A generated or hard-to-guess URL is not an access-control mechanism. Starting a plain HTTP tunnel creates public reachability to the configured service.
Can I use the direct tunnel for continuous metrics collection?
Not safely under the unprotected workflow shown here. Persistent use requires a separately verified layer that authenticates or authorizes each collector. Without such a layer, limit publication to a closely supervised test and stop the tunnel immediately afterward.
Should the Localtonet client run on the same host as Qtap?
Yes, that is the straightforward arrangement for Qtap's documented loopback listener. Run our client on the Qtap host and target 127.0.0.1:10001. Another machine's loopback address does not refer to the Qtap host.
Does creating a Localtonet tunnel make it active?
No. You must press the Start button after creating the tunnel. It remains reachable only while the selected client is connected and the tunnel is running. You can stop or delete it when it is no longer needed.
Can I tunnel Qtap's DevTools interface on port 10001?
This tutorial does not make that claim. Qtap includes a DevTools interface, but the project information used here does not establish its address or port. Port 10001 is evidenced for the two metrics paths only. Consult the current repository documentation before configuring another target.
Why does the Docker container need extensive privileges?
Qtap interacts with host kernel and process facilities for eBPF-based observation. Its documented command uses root, privileged mode, BPF and system-administration capabilities, host PID and network namespaces, host mounts, and an unlimited memlock setting. No equivalent restricted profile is established by the supplied evidence.
Can Localtonet fix a Qtap endpoint that does not work locally?
No. The tunnel forwards requests to the configured target. Qtap must already be running and responding at 127.0.0.1:10001. Verify both metrics paths locally before troubleshooting the tunnel.
Test a verified Qtap endpoint carefully with Localtonet
After both Qtap metrics paths respond locally, you can use our HTTP tunnel for a brief supervised connectivity test. If you need ongoing remote collection, place a separately verified authentication or access-control layer in front of the listener before starting persistent exposure.
Get Started Free →
