Migrate Port Forwarding to Outbound Tunnels

How outbound tunnels change the connectivity model

An inbound port-forwarding design begins at the network perimeter. A router or firewall listens on a public address and port, translates incoming traffic, and delivers it to an internal address and port. The application therefore depends on its own listener, the public address, network address translation rules, firewall policy, and any upstream provider restrictions.

With Localtonet, our client application runs on a device that can reach the local service and establishes an outbound connection to a Localtonet relay server. A running tunnel then provides a public URL or a public host and port, depending on the tunnel type. The local service does not need inbound router port forwarding, firewall changes for inbound forwarding, VPN setup for public access, or its own public IP address.

This is an architectural migration rather than a one-for-one conversion of firewall syntax. The public destination changes, availability depends on the Localtonet client and tunnel lifecycle, and monitoring must cover both the application and its access path. A successful migration requires identifying every consumer, checking protocol behavior, updating dependencies, validating the replacement endpoint, and removing the legacy path only after the new route is proven.

Inventory every listener before changing the network

Begin with the current ingress configuration rather than only a list of known applications. Router rules and firewall objects often reveal forgotten development systems, temporary vendor access, duplicated ports, and services whose original owner has left the team. Treat every forwarding rule as an item that must be explained, migrated, intentionally retained, or removed.

Build a migration register with one row per externally reachable service. Record the current public address and port, transport protocol, translated internal address and port, application owner, technical owner, expected consumers, authentication method, availability requirement, and rollback contact. If one rule covers a port range, split it into individual application dependencies wherever possible. A broad range should not automatically become a broad tunnel design.

Confirm the real local destination

A firewall rule can outlive the service it once forwarded. Verify that the destination process is listening and that an authorized local client can complete a meaningful transaction. A successful TCP connection alone does not establish application health. For a web application, retrieve a representative page or health endpoint. For a database or message broker, perform a safe authenticated query or handshake. For UDP, send a request that should produce a response, log record, metric, or other observable application event.

Record whether the service listens only on loopback, on a specific LAN address, or on all interfaces. If the Localtonet client will run on the same host, a loopback target may be suitable. If it will run on another device, the service must be reachable from that device over the local network. Do not broaden a listener merely for convenience without reviewing the resulting LAN exposure.

Discover hidden dependencies

Search deployment variables, configuration repositories, monitoring systems, callback settings, partner documentation, DNS records, mobile applications, desktop clients, and automation scripts for the old public address or hostname. Include allowlists, certificate assumptions, health checks, and hardcoded ports. A simple forwarding rule can support many downstream dependencies.

Identify applications that embed addresses, advertise internal endpoints, open secondary connections, negotiate dynamic ports, or require a port range. The availability of a TCP or UDP tunnel does not guarantee that every higher-level protocol will operate through one public endpoint. Test these behaviors explicitly and retain the original route until representative clients pass.

Prepare the account, host, service, and migration plan

Complete these prerequisites before installing the client or creating public access. The goal is to remove avoidable uncertainty from the migration window.

Supported installation paths

Current Localtonet documentation provides downloads for Windows on 64-bit, 32-bit, and ARM systems; Linux on x64, ARM, ARM64, and MUSL variants; macOS on x64 and ARM64; Docker; and Android. The documentation also includes a Termux ARM64 path for running the console client on Android. OpenWrt packages are marked experimental and have firmware, architecture, storage, and memory requirements, so they should not be treated as interchangeable with standard Linux packages.

Choose the platform path that matches the actual client device. The detailed commands below are specifically for supported Linux DEB or RPM packages. They do not apply to Windows, macOS, Docker, Android, Termux, or OpenWrt. For those platforms, use the matching instructions and download on the current Localtonet installation documentation.

Linux package requirements

Installable Linux DEB and RPM packages are currently documented for x64 and ARM64. The packaged service requires systemd 247 or newer and OpenSSL 3. Documented compatible examples include Debian 12, Ubuntu 22.04 or newer, and RHEL 9. Confirm the operating system release, CPU architecture, systemd version, and OpenSSL version before downloading a package.

Map each workload to the correct tunnel family

Choose the tunnel type from observed behavior, not from the number in the existing firewall rule. A familiar port can carry an unexpected protocol, while custom applications often use nonstandard ports.

HTTP and HTTPS applications

Select HTTP when the local workload is a web application or HTTP API. HTTP tunnels support Random Sub Domain, Custom Sub Domain, and Custom Domain process types, which serve the content at a public HTTPS address. A generated address is useful for isolated migration testing because it avoids changing the production hostname before validation.

Test sign-in, sign-out, redirects, callback URLs, API methods, uploads, downloads, and browser policies tied to the hostname. Applications can generate absolute links or enforce allowed-host lists. Those settings may need deliberate adjustment. See the Localtonet HTTP tunnel documentation for the current HTTP-specific workflow.

Custom-domain DNS requirements should be checked against the current dashboard and documentation before cutover. Do not copy DNS values from an older environment or infer them from another tunnel provider.

TCP, UDP, combined transport, and TLS

Use TCP for a continuous raw TCP stream rather than an HTTP application. Validate it with the supported application client and a least-privileged account. A socket-open test proves basic reachability, but not authentication, negotiation, queries, transfers, or session stability.

UDP needs application-level evidence because it has no TCP-style connection establishment. Confirm that requests reach the service and that responses or expected server-side events occur. If the application uses both TCP and UDP, validate each independently before testing any fallback behavior. Do not combine unrelated services merely because they use the same port number.

For TLS workloads, record where TLS is expected, which hostname clients use, what certificate they expect, and how trust is evaluated. Perform a full client handshake and application transaction. Do not infer certificate provisioning or TLS termination behavior that has not been established for the selected configuration.

Install and start the Localtonet client

The following is a complete installation and startup path for the currently documented Linux DEB and RPM packages. Download the package that matches the host architecture before running the relevant commands. Keep token entry out of shared terminal recordings and documentation.

Debian or Ubuntu commands

Use the filename matching the downloaded architecture. The example below shows x64.

sudo apt install ./localtonet-linux-x64.deb
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service

On ARM64, the package filename is localtonet-linux-arm64.deb. The AuthToken, validation, service, and journal commands remain the same.

Fedora or RHEL commands

The example below shows the x64 package.

sudo dnf install ./localtonet-linux-x64.rpm
sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service

On ARM64, use localtonet-linux-arm64.rpm. Do not paste the token itself into these commands. The token belongs in the protected file described above.

Upgrade the packaged Linux client

To upgrade, download and install the new matching DEB or RPM package using the same package manager. The documented package workflow preserves the configuration. Restart the standard tunnel service after installation:

sudo systemctl restart localtonet.service
sudo journalctl -u localtonet.service

Re-run the configuration check when investigating configuration or authentication problems, and review the journal after upgrades. Plan the restart as a service change because active tunnels depend on the connected client.

Run a local preflight before public exposure

Installation success does not prove that the application is ready to tunnel. Perform this preflight from the exact device running the Localtonet client before creating or starting a public endpoint.

Create and start the protocol-appropriate tunnel

Keep the existing forwarding rule available during controlled testing unless policy requires otherwise. Parallel availability lets the team compare both routes and preserves a practical rollback option.

Validate the public endpoint in parallel

Keep the existing forwarded endpoint available while a restricted tester group uses the Localtonet endpoint. This separates tunnel validation from final decommissioning and preserves rollback while evidence is collected.

Test from outside the local network

Use an authorized client on an external network. Confirm that the test is not reaching the old endpoint through cached DNS, split-horizon resolution, a hosts-file entry, or an existing private route. Use the assigned Localtonet public URL or host and port exactly as recorded.

Test the application, not only the port

Define acceptance checks as user or system outcomes. An HTTP test may require sign-in, a state-changing operation, a download, and sign-out. A TCP service may require authentication and a representative command. A UDP service needs an observable request and response or verified server-side event.

Include negative tests. Invalid credentials should fail, unauthorized users should not gain additional access, and requests to unavailable resources should behave normally. A migration is incomplete if normal traffic succeeds but access controls have changed unexpectedly.

Exercise lifecycle failures

During an approved test window, stop the tunnel and confirm that monitoring detects the outage. Start it again and verify recovery. If client-host restart is part of the intended operating model, test that procedure as well. These checks show whether responders can distinguish a stopped tunnel from an unhealthy application.

Localtonet provides platform-wide Token/Tunnel webhooks for selected Token Groups. They send Connected and Disconnected state changes with an identifier, action date, type, and status. These lifecycle events are separate from File Server file-event webhooks. See the Localtonet webhook documentation for the platform-wide webhook model.

Record who ran each test, from which network, with which supported client version, and at what time. Keep sanitized application evidence without exposing credentials or device tokens. Require both the application owner and tunnel owner to approve the result.

Cut over consumers and preserve rollback

Change one dependency at a time where practical. Start with internal testers or a low-risk consumer, move representative automated integrations, and then migrate the wider user population. Track adoption explicitly rather than assuming that a documentation or DNS change moved every client.

Define rollback triggers in advance

Useful triggers include authentication failure for supported clients, inability to complete a critical transaction, unacceptable error volume, missing UDP responses, certificate validation failure, or monitoring that cannot distinguish tunnel state from application health. Define who can order rollback and how long the team will troubleshoot before restoring the prior route.

During parallel operation, rollback normally means returning affected consumers to the known working endpoint while keeping the new tunnel available for diagnosis. Avoid changing the legacy firewall rule in the same window unless necessary. Simultaneous network changes make fault isolation harder.

Retire inbound rules only after evidence is complete

Confirm that every known consumer has moved, monitoring targets the new endpoint, operational ownership is assigned, and the rollback window has ended. Search again for references to the old address, hostname, and port.

Remove or disable the narrowest relevant firewall and network address translation objects through the normal change process. Test the old endpoint externally and confirm that it no longer reaches the service. Then test the Localtonet endpoint again to prove that removing the inbound rule did not affect the application or another dependency.

Update network diagrams, service records, incident procedures, monitoring targets, and owner information. Mark the former address and rule as retired so future responders can understand why the architecture changed and why the rollback path was intentionally closed.

Operate tunnels as production dependencies

After cutover, availability depends on the application, its host and local route, the Localtonet client, the selected device identity, the running tunnel, and the consumer’s path to the public endpoint. Operations should reflect the whole chain.

Monitor in layers

Use a local application-aware check for the listener and core behavior. Use an external synthetic check for the public path and a representative transaction. Track client and tunnel connection state separately. Token/Tunnel webhooks can report lifecycle changes, but a Connected event does not prove that the application is healthy.

Assign lifecycle ownership

Every production tunnel should have a service owner, client-device owner, escalation path, and review date. Record whether it is permanent, scheduled, or temporary. When the service is decommissioned, stop and delete the corresponding tunnel rather than leaving an unused public configuration.

Control configuration and software changes

Treat changes to the local target, tunnel family, relay selection, public endpoint, application authentication, client package, and host operating system as service changes. Re-run the relevant local and external checks after each one. On packaged Linux systems, inspect the service journal after client upgrades and restart the service as documented.

Keep an auditable register

Preserve the migration inventory as an operational record. Update it when a tunnel changes, an owner leaves, credentials rotate, or a service moves. Record the public endpoint, local target, protocol, device owner, relay choice, and lifecycle state, but never store the device AuthToken or application secrets.

Choose between a public tunnel and VPN Manager

Standard Localtonet tunneling and VPN Manager solve different problems. HTTP, TCP, UDP, combined UDP/TCP, TLS, and File Server configurations expose specific resources through public endpoints. VPN Manager creates a private mesh network with granular firewall rules and can bridge local LANs. Standard tunneling is not a VPN.

If external users or systems need one specific public service, use the corresponding tunnel and protect the application appropriately. If approved devices need private network membership or LAN-to-LAN access, evaluate Localtonet VPN Manager. Do not publish a collection of internal ports as a substitute for designing private connectivity.

Troubleshoot migration failures systematically

Diagnose the path from the inside out. This separates application failures, local routing problems, client-service issues, tunnel lifecycle errors, and external client problems.

1. Verify the local application

Confirm that the process is running and listening on the expected address, port, and transport. Complete the application-aware local test. If it fails, repair the application before changing the tunnel.

2. Test from the Localtonet client device

If the application is on another host, run the same test from the exact client device. A successful test from an administrator workstation does not prove that the Localtonet host has the same route, DNS result, or firewall permission.

3. Check the client configuration and service

On packaged Linux installations, confirm that the AuthToken file exists in the expected location and remains protected with mode 600. Run the configuration check again, inspect localtonet.service, and review its journal. Never paste the AuthToken into diagnostic output.

sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config
sudo systemctl status localtonet.service
sudo journalctl -u localtonet.service

4. Confirm device connectivity and tunnel state

Verify that the intended device is authenticated and connected, that the correct tunnel is associated with it, and that the tunnel has been started. Creation alone does not make the endpoint available.

5. Recheck protocol classification

A TCP listener is not automatically an HTTP application, and an application using both TCP and UDP is not fully validated through one path. If TLS is involved, check hostname and trust expectations instead of treating every handshake failure as generic reachability loss.

6. Test externally with the real client

Use a supported client outside the local network. Check for stale DNS, a copied space, incorrect port, cached configuration, or a client still using the legacy endpoint. For UDP, rely on expected application behavior or server-side evidence rather than a TCP-style port test.

7. Compare the old and new routes

During parallel validation, run the same transaction against both endpoints with equivalent credentials and settings. If only the new path fails, compare hostnames, certificates, redirects, allowlists, and protocol assumptions. If both fail, investigate the application or a shared local dependency.

8. Roll back when the agreed limit is reached

If a critical acceptance criterion fails and the troubleshooting window expires, execute the documented rollback. Preserve sanitized evidence, return consumers to the known working route, and schedule another controlled test. Do not open broad firewall access or disable authentication to force the migration through.

Frequently asked questions