Skip to main content

Crate lyrebird

Crate lyrebird 

Source
Expand description

§Lyrebird - Pluggable Transport Proxy Applications

This crate provides a PT-manager loop usable as a library (lyrebird::run()) or as a standalone binary that implements the Tor pluggable-transport spec on top of the ptrs interface.

Stability: the public API is unstable and subject to change without notice; do not rely on this crate for security-critical applications. The server-side path is incomplete and gated behind the experimental-server cargo feature — it must not be enabled in production.

§Lyrebird Pluggable Transport Bridge

[‘lyrebird’] provides an executable program designed to manage the calling interface used by the Tor libraries when launching pluggable transports (see pt-spec.txt).

... [tor_client] <---> [pt_client] <====> [pt_bridge] <---> [tor_orport] ...

Usage info:

Tunnel Tor SOCKS5 traffic through pluggable transport connections

Usage: lyrebird [OPTIONS]

Options:
      --enable-logging         Log to {TOR_PT_STATE_LOCATION}/obfs4proxy.log
      --log-level <LOG_LEVEL>  Log Level (ERROR/WARN/INFO/DEBUG/TRACE) [default: ERROR]
      --unsafe-logging         Disable the address scrubber on logging
  -h, --help                   Print help
  -V, --version                Print version

§Installation

To install:

cargo install lyrebird

This installs in the configured Rust location (i.e. $HOME/.cargo/bin). You may wish to copy ./lyrebird to a permanent location (e.g. /usr/local/bin).

Client side torrc configuration:

ClientTransportPlugin obfs4 exec /usr/local/bin/lyrebird

Bridge side torrc configuration:

# Act as a bridge relay.
BridgeRelay 1

# Enable the Extended ORPort
ExtORPort auto

# Use lyrebird to provide the obfs4 protocol.
ServerTransportPlugin obfs4 exec /usr/local/bin/lyrebird

# (Optional) Listen on the specified address/port for obfs4 connections as
# opposed to picking a port automatically.
#ServerTransportListenAddr obfs4 0.0.0.0:443

§Tips and tricks

  • On modern Linux systems it is possible to have lyrebird bind to reserved ports (<=1024) even when not running as root by granting the CAP_NET_BIND_SERVICE capability with setcap:

    # setcap 'cap_net_bind_service=+ep' /usr/local/bin/lyrebird

  • The autogenerated obfs4 bridge parameters are placed in DataDir/pt_state/obfs4_state.json. To ease deployment, the client side bridge line is written to DataDir/pt_state/obfs4_bridgeline.txt.

Functions§

arg_string_from_creds
Reconstruct the PT-spec argument string from the SOCKS5 USERNAME/PASSWORD fields, mirroring Go lyrebird rfc1929.go:88-100.
resolve_target_addr
Resolve a fast_socks5::util::TargetAddr to a concrete SocketAddr. Ip(_) variants pass through; Domain variants always fail because the PT spec forbids the transport from doing DNS — that’s the calling Tor client’s responsibility.
run
Run the lyrebird pluggable transport. Expects the standard TOR_PT_* environment variables set by the parent process (arti / tor) and speaks the PT-managed-transport protocol on stdin/stdout.