/ 
App-ReslirpTunnel-0.02
River stage zero No dependents
/ reslirp-tunnel

NAME

reslirp-tunnel - A script to set up a reSLIRP tunnel over SSH for remote connections

SYNOPSIS

reslirp-tunnel [options] [remote_host] =head1 DESCRIPTION

reslirp-tunnel establishes a reSLIRP tunnel to a specified remote host using SSH. It enables users to configure various networking options and manages IP routing rules along with DNS resolution configuration, greatly simplifying the setup process for a reSLIRP tunnel.

The program is designed to be executed by a non-root user. It automatically invokes sudo in the background, which typically prompts the user for a password to perform privileged operations.

Also, the program is intended to be run on Linux system using systemd.

OPTIONS

-C, --reslirp-cmd, --reslirp-command command

Specify the reSLIRP command to be used.

By default, it uses C:\Program Files\reSLIRP\reslirp.ext. When the remote Operating System is Windows and reslirp otherwise.

-s, --ssh-cmd, --ssh-command command

Specify the SSH command to be used.

-R, --remote-os os

Specify the remote operating system.

When not given, reslirp-tunnel would try to autodetect the remote Operating System running some commands over the SSH channel.

-S, --remote-shell shell

Specify the remote shell.

reslirp-tunnel also tries to autodetect the remote shell when it is not explicitly given using this flag.

-n, --remote-network network

Specify the remote network (defaults to 10.0.2.0/24).

-m, --remote-netmask netmask

Specify the remote netmask (defaults to 255.255.255.0).

-g, --remote-gw gateway

Specify the remote gateway (defaults to 10.0.2.2).

-d, --remote-dns dns

Specify the remote DNS (defaults to 10.0.2.3).

-a, --local-ip ip

Specify the local IP (defaults to 10.0.2.30).

-i, --tap-device device

Specify the tap device.

By default, reslirp-tunnel will use the first tap device available.

-s, --ssh-arg arg

Specify additional SSH arguments.

-r, --reslirp-arg arg

Specify additional reslirp arguments.

-E, --log-to-stderr

Log to standard error.

-L, --log-file file

Specify the log file (by default logs to a file in ~/.local/state/reslirp-tunnel/logs).

-D, --log-level level

Specify the log level (debug, info, warn, error).

-l, --remote-user user

Specify the remote user used for logging in.

-p, --remote-port port

Specify the remote port (defaults to 22).

-F, --forward-dns-ssh dns=remote_iface

Resolves the given domain using the remote DNS server attached to the given interface in the remote machine.

This is useful for resolving using the DNS provided by a VPN client running in the target machine.

-N, --route-net, --route-network ipv4/<mask>

Route the traffics to the given network through the reSLIRP tunnel.

-h, --route-host, --route-host-local host
-H, --route-host-dns host
-W, --route-host-ssh host

When one or more hosts are given using any of these options, the script changes the local network configuration so that traffic going to the given machines is routed through the reSLIRP tunnel.

The difference between these options is how the script resolves the hostnames:

--route-host, --route-host-local

Resolves the host locally using the OS resolver.

--route-host-dns

Resolves the host using the remote DNS provided by reSLIRP which forwards the request to any configured DNS server. Though, note that this doesn't usually work when the remote hosts runs Windows.

--route-host-ssh

Resolves the host using commands run on the remote machine through the SSH connection. Effectively, this approach resolves the names using the resolver configuration in the remote machine.

The addresses are resolved at launch time and then cached in a local DNS server set up by reslirp-tunnel. The configuration of systemd resolver is also adjusted so that the DNS service is used for those hosts.

Finally, a set of IP rules are also added for directing the traffic through the tunnel.

-f, --run-in-foreground

By default, reslirp-tunnel detaches from the terminal once the slave sudo process begins and the SSH connection is established. This option disables that behavior.

--dont-close-stdio

Preserve standard input/output.

By default, when reslirp-tunnel forks itself into the background, it closes its standard input and output channels. This can complicate matters by preventing error messages from being printed afterward. Enabling this option ensures that the standard input/output channels remain open.

EXAMPLES

reslirp-tunnel --route-net=10.0.0.0/8 --forward-dns-ssh=windows.net localhost:4022

UNDER THE HOOD

Those are the actions performed under the hood by reslirp-tunnel:

  1. Initiates a slave process using sudo to carry out privileged operations.

  2. Establishes an SSH connection to the designated remote host.

  3. Forks itself into the background and closes its standard input and output channels.

  4. Creates a tap device.

  5. Executes reSLIRP on the remote machine, linking it to the tap device through an SSH channel.

  6. If necessary, retrieves information about the remote machine's network configuration by executing commands over the SSH channel.

  7. If necessary, starts a local DNS server (dnsmasq) linked to the tap device, configuring it to serve the various hosts and domains specified on the command line.

  8. Adds all required routes to direct IP traffic through the tunnel, in accordance with the provided command line parameters.

  9. If something goes wrong, or the process receives a signal, it cleans up, waiting for the child processes to exit and terminates.

    Note that IP routes and DNS configurations are attached to the tap device, so they are automatically removed when the device is deleted.

COPYRIGHT AND LICENSE

Copyright (C) 2025 by Salvador Fandiño (sfandino@yahoo.com).

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.38.2 or, at your option, any later version of Perl 5 you may have available.