NAME

remperl - run Perl scripts on remote machines over any pipe transport

SYNOPSIS

remperl [options] HOST script.pl [script-args...]
remperl [options] HOST [-mMOD] [-MMOD] -e CODE [script-args...]
remperl --pipe-cmd [options] COMMAND script.pl [script-args...]

HOST accepts: hostname, user@hostname, ssh://[user@]host[:port].

DESCRIPTION

remperl connects to a remote Perl interpreter through an arbitrary pipe command, bootstraps a self-contained protocol client on the remote end, and executes Perl code there. STDOUT and STDERR from the remote script are relayed in real time; local STDIN is forwarded on demand.

When --serve-modules is enabled, any module not found in the remote's own @INC is fetched transparently from the local machine. The remote machine needs no pre-installed dependencies beyond a bare Perl interpreter.

For the library interface, see Remote::Perl.

OPTIONS

--rsh=EXECUTABLE

SSH-like command to use (default: ssh). Invoked as EXECUTABLE HOST perl.

--pipe-cmd

Treat the first positional argument as a complete pipe command instead of a hostname. The command is interpreted by sh -c, so quoting and environment variable assignments work as expected.

-e CODE

Evaluate CODE on the remote side instead of running a script file. Multiple -e options are accumulated and joined with newlines, just like perl -e.

-mMODULE

-MMODULE

Load MODULE before running code, following the same rules as perl -m and perl -M. -m imports nothing (use MODULE ()); -M imports defaults (use MODULE). -M-MODULE becomes no MODULE. An = suffix works as in Perl: -MModule=a,b becomes use Module split(/,/,q{a,b}).

Only valid with -e; using -m/-M with a script file is an error. May be specified multiple times.

-w

Enable warnings on the remote side (sets $^W = 1), equivalent to perl -w.

--stdin-file=FILE

Read remote STDIN from FILE instead of local STDIN.

--stdin-str=STRING

Use STRING verbatim as remote STDIN. Mutually exclusive with --stdin-file.

--window-size=N

Initial flow-control credit per stream in bytes (default: 65536).

--serve-modules

Enable module serving: missing modules are fetched from the local machine's @INC on demand. Disabled by default. Use --no-serve-modules to explicitly disable.

--inc-local=PATH

Prepend PATH to the local @INC used when serving modules. May be specified multiple times. When --serve-restrict-paths is active, --inc-local paths are automatically added to the set of allowed paths.

--no-system-inc

When serving modules, search only --inc-local directories and not the system @INC. Has no effect unless --serve-modules is also set.

--serve-restrict-paths

Restrict module serving to a set of allowed directories. A module found in @INC is denied unless its real path falls under one of the allowed directories. The allowed set consists of all --serve-allow paths plus all --inc-local paths. If no allowed directories are configured, nothing is served.

--serve-allow=PATH

Add PATH to the set of allowed directories for --serve-restrict-paths. May be specified multiple times. Implies --serve-restrict-paths.

--tmpfile

Enable do-file execution mode, which is required for scripts that use __DATA__ sections. The strategy is chosen automatically: linux (O_TMPFILE, no directory entry) is tried first, falling back to perl (open('+>', undef)). Use --no-tmpfile to explicitly disable.

--tmpfile-mode=STRATEGY

Override the do-file strategy. Implies --tmpfile. STRATEGY may be one of:

auto Try linux, perl, named -- in that order (same as bare --tmpfile).

linux Use O_TMPFILE (Linux 3.11+).

perl Use open('+>', undef). Requires /proc/self/fd (Linux) or /dev/fd (FreeBSD, macOS) to be available on the remote; on FreeBSD this means fdescfs must be mounted.

named Use File::Temp; the file persists until the remote script exits. Required if the script reopens __FILE__ or passes its path to child processes.

off Explicitly disable do-file mode (same as --no-tmpfile).

--no-data-warn

Suppress the warning emitted when a script contains __DATA__ but --tmpfile is not set.

--version

Print the version and exit.

--help

Print this message and exit.

EXAMPLES

Run a script on a remote host:

remperl hostx myscript.pl

Pass user@hostname directly to ssh:

remperl alice@hostx myscript.pl

Evaluate inline code:

remperl hostx -e 'use Some::Module; print Some::Module->greet'

Pass arguments to the remote script:

remperl hostx myscript.pl arg1 arg2 "arg three"

Pipe stdin to the remote script:

echo "hello" | remperl hostx myscript.pl

Use a custom ssh-like executable:

remperl --rsh=my-ssh hostx myscript.pl

Use an arbitrary pipe command (Docker, kubectl, etc.):

remperl --pipe-cmd 'docker exec -i mycontainer perl' myscript.pl
remperl --pipe-cmd 'kubectl exec -i mypod -- perl' myscript.pl
remperl --pipe-cmd 'nice ssh hostx perl' myscript.pl

SECURITY

Authentication and access control are the transport's responsibility (SSH keys, container permissions, etc.).

Module serving (--serve-modules) is disabled by default. When enabled, the remote side can request any module by filename; the local side searches @INC and returns the source. Path traversal sequences (..) in module filenames are rejected. Only enable module serving with endpoints you trust or when the exposure of your local @INC contents is acceptable.

REQUIREMENTS

Perl 5.36 or later on the local machine. Perl 5.10 or later on the remote machine. No non-core modules required on either side.

NOTES

__DATA__ sections require --tmpfile. Without it, code before __DATA__ runs correctly but <DATA> reads return nothing, and a warning is printed. __END__ stops parsing as usual regardless.

CAVEATS

Scripts that use FindBin will cause module serving to break for their dependencies: FindBin sets $Bin to the remote executor's temporary script path rather than the original script's directory, so any relative use lib "$Bin/..." entries in @INC point at non-existent locations and the module server cannot find the modules there.

SEE ALSO

Remote::Perl -- the library interface.

AUTHOR

Pied Crow <crow@cpan.org>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Remote::Perl

perl -MCPAN -e shell
install Remote::Perl