/ 
App-ReslirpTunnel-0.05
/ reslirp-tunnel

NAME

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

SYNOPSIS

reslirp-tunnel [options] ssh_target

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.

OPTIONS

-C, --reslirp-command command

Specify command to be use on the remote host to run reSLIRP.

By default, it uses C:\Program Files\reSLIRP\reslirp.exe for Windows systems and reslirp otherwise.

-r, --reslirp-arg arg

Specify additional reslirp arguments.

-s, --ssh-command command

Specify the SSH command to be used locally.

-l, --ssh-user user

Specify the remote user used for logging in.

-p, --ssh-port port

Specify the remote port (defaults to 22).

-s, --ssh-arg arg

Specify additional SSH arguments.

-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 given using this flag explicitly.

-n, --remote-network network/mask

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

-m, --remote-gw ip

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.

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

Resolve 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 ipv4/mask

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

-h, --route-host ipv4[=hostname]

Route the specified IP address through the reSLIRP tunnel. An optional hostname may also be provided, which will be added to the DNS configuration to ensure that the name resolves to the given IP address.

-O, --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:

local

Resolves the host locally using the OS resolver.

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.

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.

This is what you want most of the time!

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.

-E, --log-to-stderr

Log to standard error.

-L, --log-file file

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

-D, --log-level level

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

-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.

-P, --profile profile_name

Load a profile from the configuration file.

EXAMPLES

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

CONFIGURATION FILE

On startutp reslirp-tunnel reads the configuration file at ~/.config/reslirp-tunnel.yaml.

Several profiles can be defined in this file. If one called default exists it is used to set the configuration.

Additional profiles can be loaded with the command line option --profile.

Example Configuration File

profiles:
  default:
     run-in-foreground: 0
     dont-close-stdio: 1
     log-level: debug

  daily-planet:
    ssh-host: localhost
    ssh-port: 5022
    ssh-user: llane
    route-nets:
      - 10.0.0.0/8
    forward-dnss-ssh:
      - daily-planet.com
      - krypton.org

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.

Note also that, so far, reslirp-tunnel only works in Linux systems. If you need support for other operating systems, please let me know.

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.