百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
R

ruroco

> 编程语言
开源

Ruroco 是一款工具,可通过发送 UDP 数据包在服务器上执行命令。这些命令是在服务器端配置的,因此客户端不需要定义命令。

555 stars0 点赞3 次浏览
访问官网GitHub

工具介绍

Ruroco 是一款工具,可通过发送 UDP 数据包在服务器上执行命令。这些命令是在服务器端配置的,因此客户端不需要定义命令。

ruroco - Run Remote Command

ruroco is a tool that lets you execute commands on a server by sending UDP packets.

It triggers a pre-configured action on the server (open a firewall rule, restart a service, run a script) — it is not a tunnel or a VPN. There is no session, no connection, and no traffic carried: the client fires a single stateless packet and the server runs a whitelisted command. In other words, ruroco grants a capability to act without granting network access. See ruroco vs WireGuard / VPN for when that matters and when a plain VPN is the better choice.

the tool consist of 4 binaries:

  • ruroco-client: runs on your notebook/computer and sends the UDP packets
  • ruroco-client-ui: presents most of the functionality of ruroco-client in an easier to use user interface.
  • ruroco-server: receives the UDP packets and makes sure that they are valid
  • ruroco-commander: runs the command encoded by the data of the UDP packet if it's valid

The commands are configured on the server side, so the client does not define what is going to be executed, it only picks from existing commands.

Table of Contents

  • Installation
    • Client
    • Client UI
    • Server
    • Android
  • Security
  • Client UI usage
  • Client usage
    • gen
    • send
    • update
    • reseed
    • wizard
  • Server usage
  • Commander usage
  • Server config
  • Use cases
    • Triggering an action
    • Single packet authorization (SPA)
    • Enabling webservice
  • ruroco vs WireGuard / VPN
  • Troubleshooting
  • Architecture

Installation

Download binaries from the releases page or build them yourself by running

bash
make release

you can find the binaries in target/release/client, target/release/client_ui, target/release/server and target/release/commander

Client

Arch Linux (AUR)

bash
yay -S ruroco-client

Self-build

See make goal install_client. This builds the project and copies the client binary to /usr/local/bin/ruroco-client

Pre-build

Run the following script

bash
curl -Ls "$(curl -s https://api.github.com/repos/beac0n/ruroco/releases/latest | grep -oE 'https://[^"]*/client-v[0-9]+\.[0-9]+\.[0-9]+-x86_64-linux')" -o ~/.local/bin/ruroco-client 
chmod +x ~/.local/bin/ruroco-client
~/.local/bin/ruroco-client update --force

Client UI

Arch Linux (AUR)

bash
yay -S ruroco-client-ui

Server

Arch Linux (AUR)

bash
yay -S ruroco-server

After installing, generate a shared key, place it in /etc/ruroco/, and edit /etc/ruroco/config.toml.

Self-build

See make goal install_server, which

  • Builds the project
  • Copies the client binary to ~/.local/bin/
  • Copies the server binaries to /usr/local/bin/
  • Runs ruroco-client wizard
  • After running the make goal, you have to
    • generate a shared .key file and copy it to the right place
    • setup the config.toml
    • start the server with systemctl start ruroco.service. The wizard deliberately leaves it stopped until a .key exists, since a keyless server exits at startup and Restart=always would crash-loop it into systemd's start limit

Pre-build

Run the following script

bash
curl -Ls "$(curl -s https://api.github.com/repos/beac0n/ruroco/releases/latest | grep -oE 'https://[^"]*/client-v[0-9]+\.[0-9]+\.[0-9]+-x86_64-linux')" -o ~/.local/bin/ruroco-client 
chmod +x ~/.local/bin/ruroco-client
~/.local/bin/ruroco-client update --force
sudo ~/.local/bin/ruroco-client wizard

Android

See nix/android.nix, scripts/dev_ui_android.sh and scripts/release_android.sh

security

  • client sends UDP packet to server, server never responds to it -> port-scanning does not help an adversary
  • data sent from client to server is encrypted symmetrically with AES-256-GCM-SIV using a shared key (symmetric is a deliberate trade-off, see SECURITY.md)
  • client only defines command to execute, commands are saved on server in a root-only file the network-facing server process cannot read -> client can pick command but not define it
  • run server software in such a way so that it uses as little operating system rights as possible
  • replay protection by adding every packet that the server received to a blocklist

See SECURITY.md for the full threat model: in-scope attacks, accepted risks, key lifecycle (generation, rotation, revocation), and the supported-versions table.

client ui usage

bash
ruroco-client-ui

Use the Generate Key action (or ruroco-client gen) to produce a base64-encoded shared key. Copy that key into the server's .key files (see server config) and reuse the same string with ruroco-client send. You can save your key safely in a password manager or use secret-tool to store it in the local keyring, e.g. with secret-tool store --label="ruroco" token ruroco

client usage

commands

bash
ruroco-client
Usage: ruroco-client 

Commands:
  gen     Generate a shared AES key (base64 with embedded key id)
  send    Send a command to a specific address
  update  Update the client binary
  wizard  Run the wizard to set up the server side
  reseed  Reseed the replay-protection counter to the current timestamp
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

gen

bash
ruroco-client gen
Generate a shared AES key (base64 with embedded key id)

Usage: ruroco-client gen

Options:
  -h, --help  Print help

send

bash
ruroco-client send --help
…

Pass the path to a file holding the same base64 key string that you placed on the server (never the key itself on the command line: that would leak it via ps and shell history). Example:

bash
secret-tool lookup token ruroco > /run/user/$(id -u)/ruroco.key
ruroco-client send -a 127.0.0.1:80 -k /run/user/$(id -u)/ruroco.key -c default

update

bash
ruroco-client update --help
Update the client binary

Usage: ruroco-client update [OPTIONS]

Options:
  -f, --force                  Force update even if already on the latest version
  -v, --version       Target version to install (default: latest)
  -b, --bin-path     Directory where the binary is saved (default: same as current binary)
  -s, --server                 Update server-side binaries instead of the client
  -h, --help                   Print help

Every downloaded binary is verified against an Ed25519 signature before it is written to disk. The public key is embedded in the client at build time; releases are signed in CI with the matching private key. If the .sig asset is missing or the signature does not match, the update aborts and the existing binary is left untouched. As a result, the client can only update to releases that ship signatures (v0.14.0 and later).

reseed

bash
ruroco-client reseed

Resets the local replay-protection counter to the current nanosecond timestamp. Use this if the counter file is lost or corrupted, or after a system clock jump that would cause the server to reject packets.

The UI equivalent is the Reseed Counter button on the dashboard.

wizard

bash
ruroco-client wizard --help
Run the wizard to set up the server side

Usage: ruroco-client wizard [OPTIONS]

Options:
  -f, --force   Overwrite existing configuration files
  -h, --help    Print help

server usage

bash
ruroco-server --help
Usage: ruroco-server [OPTIONS]

Options:
  -c, --config   [default: /etc/ruroco/config.toml]
  -h, --help             Print help
  -V, --version          Print version

commander usage

bash
ruroco-commander --help
Usage: ruroco-commander [OPTIONS]

Options:
  -c, --config   [default: /etc/ruroco/config.toml]
  -h, --help             Print help
  -V, --version          Print version

server config

  1. run ruroco-client gen > ~/.config/ruroco/user.key to create a shared base64 key (includes key id)
  2. copy the same .key file to the server config dir (default /etc/ruroco/user.key); the server loads every *.key file there. It must be readable by the user the server runs as, so install it root:ruroco with mode 0640 (chown root:ruroco /etc/ruroco/user.key && chmod 640 /etc/ruroco/user.key). Leaving it root:root 0600 makes the server crash-loop on EACCES.
  3. add server config to /etc/ruroco/config.toml -> see config.toml. Same ownership as the key (root:ruroco, mode 0640): the commander reads it as root, the server as ruroco, and neither needs to write it
  4. add the commands to /etc/ruroco/commands.toml -> see commands.toml. This file is read only by the commander (root) and must be installed root-owned with mode 0600 so the unprivileged server process cannot read the command set.
  5. call ruroco-client send with -k ~/.config/ruroco/user.key so client and server share the identical key

use cases

ruroco's core job is to trigger a pre-configured action on the server. The strongest cases are the ones where there is no service to connect to at all — only something to make happen. The SPA example below (opening a port on demand) is the one shape of use case that overlaps with what a VPN can do; for why ruroco is still a distinct tool, see ruroco vs WireGuard / VPN.

triggering an action

The most VPN-orthogonal use of ruroco is firing a server-side action that has no "service" to reach: deploy, restart something, rotate a secret, run a backup. Configure the commands on the server:

toml
# /etc/ruroco/commands.toml (root-only, see chapter "server config")
[commands]
deploy = "/usr/local/bin/deploy.sh"
restart_app = "systemctl restart myapp"
run_backup = "/usr/local/bin/run-backup.sh"

then fire one from anywhere — including a CI runner, a cron job on another host, or a tap in the UI:

bash
ruroco-client send --address host.domain:80 --command deploy --key-file ~/.config/ruroco/user.key

There is no tunnel to bring up and no session to maintain: the client sends a single stateless packet and the command runs. A VPN cannot do this — it would only connect you so that you could then run the command yourself. And because the client can only pick from whitelisted command names (it never sees the command strings), a compromised client can fire those actions but gains no foothold on your network.

single packet authorization (SPA)

Any port you expose to the internet attracts brute-force and exploit traffic — and even a well-secured service is not 100% safe, see https://www.schneier.com/blog/archives/2024/04/xz-utils-backdoor.html or https://www.qualys.com/2024/07/01/cve-2024-6387/regresshion.txt

Blocking every port that does not need to be open at all times reduces that attack surface. But blocking a port completely makes the service behind it unreachable when you actually do need it.

This is where ruroco comes in: it can open a firewalled port for just a short while — only for the IP that asked — and close it again afterwards. A command can reference that IP via the $RUROCO_IP environment variable, which the commander substitutes before running the command:

toml
# /etc/ruroco/commands.toml (root-only, see chapter "server config")
[commands]
open_port = "ufw allow from $RUROCO_IP proto tcp to any port 8443"         # open the service for the requesting IP
clos

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言