Blog Docs Roadmap GitHub
July 18, 2022

Client restructuring and API

Table of contents

Wireleap v0.6.0 is a major update to the client, with a brand new controller including a REST API, splitting out the SOCKSv5 forwarder, and other internal changes and improvements. As such, there are a number of changes users should be aware of.

Please note, this is a backwards incompatible release.

What’s new

Architecture and flow: Almost the entire client has been restructured. The below diagram shows the new structure and flow.

flowchart LR subgraph Management webui subgraph CLI cmd intercept exec[exec scripts] end end subgraph Apps subgraph specific apps_socks([Auto configued]) apps_ld_preload([LD Preload]) apps_socks2([User configured]) end subgraph all apps_if_tun([All apps]) end end subgraph Backplane subgraph Controller subgraph Socket socket_api["/api"] socket_broker["/broker"] end subgraph API api[api] end subgraph Broker tunnel_broker %%key_broker %%relay_broker end end subgraph Forwarders subgraph SOCKS socks_d[daemon] end subgraph TUN tun_if[/tun device/] tun_d[daemon] end end end routes[(Routing Table)] cmd-->|HTTP REST|socket_api webui-->|HTTP REST|socket_api socket_api-->API exec-->apps_socks intercept-->apps_ld_preload specific-->|SOCKSv5|socks_d SOCKS-->|H2C|socket_broker all-.->|if tun|routes routes-->|TCP/UDP|tun_if tun_if<-->|IP packets|tun_d tun_d-->|H2C|socket_broker socket_broker-->Broker tunnel_broker-->|WL H2C|wire{{wire}}

Controller: The controller provides two main endpoints, /api and /broker, providing the API and connection broker functionality, as well as manages all “backplane” components such as the forwarders.

REST API: The controller provides a REST API based on the Client API specification. This opens the door for GUI’s, web frontends, and custom integrations.

For example, here is an early proof-of-concept:

poc screenshots

Webroot: In preparation for web frontends, a new folder in the wireleap home directory has been added. The controller will serve the contents of this folder at its root. This removes the need for a web frontend to supply its own webserver, as well as removing the need for the API to support CORS (cross-origin resource sharing).

CLI commands: Some commands have been added, some removed, and others changed. Where applicable, the existing CLI commands have been updated to communicate with the new API.

JSON output: All CLI commands output JSON responses. In the future, more output options will most likely be added.

Active circuit: It is now possible to see which relays are being used in the active circuit, without needing to parse the logs.

$ wireleap status | jq -r '.broker.active_circuit'
[
  "wireleap://relay1.example.com:443/wireleap",
  "wireleap://relay3.example.com:13495"
]

Daemon state: The controller API now reports daemon state being one of active inactive activating deactivating failed unknown. With these new states, the previous 2 second delay has been removed.

Forwarders: The SOCKSv5 forwarder has been split out into its own binary, and is no longer started by default, instead it is now optional. Controlling the SOCKS forwarder is now similar to that of the TUN forwarder. Note, exec and intercept require the the SOCKS forwarder.

- wireleap start
+ wireleap start
+ wireleap socks start

The controller needs to be active in order to start forwarders, and will refuse to be stopped if any forwarders are active.

If you’re new to Wireleap and want to try the new client, take it for a spin on Libre, the free Wireleap relay network, powered by the community and supporters of the Wireleap project. It is free to use, provided for the purposes of casual usage, testing, and community feedback.

Upgrade guide

Please refer to the notable changes for changes you should be aware of. For more details on the changes introduced, please refer to the command line changes and configuration changes below.

The 0.6.0 release includes an automatic migration, meaning no manual changes to the config.json are required when performing the upgrade.

wireleap tun stop
wireleap stop

sudo rm $HOME/wireleap/wireleap_tun
wireleap upgrade

wireleap start
wireleap status

Once upgraded and the controller is active, start the forwarder depending on how you would like to route traffic. Traffic can be routed via wireleap either for specific applications via the SOCKSv5 forwarder, or for all traffic on the system via the TUN forwarder.

# routing specific traffic (SOCKSv5)
wireleap socks start

# routing all traffic (TUN)
sudo chown 0:0 $HOME/wireleap/wireleap_tun
sudo chmod u+s $HOME/wireleap/wireleap_tun
wireleap tun start

Changes

Notable changes

We take stability very seriously and have worked hard to minimize the amount of changes most users will need to be aware of. But, there are changes that most users should be aware of:

# the socks forwarder is no longer started automatically (req. for exec/intercept)
- wireleap start
+ wireleap start
+ wireleap socks start

# accesskeys are now managed with the sub-command, e.g.,
- wireleap import https://...
+ wireleap accesskeys import https://...

# the circuit hops configuration has changed, e.g.,
- wireleap config circuit.hops 2
+ wireleap config broker.circuit.hops 2

# the circuit whitelist configuration has changed, e.g.,
- wireleap config circuit.whitelist "wireleap://relay1.example.com"
+ wireleap config broker.circuit.whitelist "wireleap://relay1.example.com"

# the socks fowarder address in the config has changed, e.g.,
- curl --proxy socks5h://$(wireleap config address.socks) ifconfig.co
+ curl --proxy socks5h://$(wireleap config forwarders.socks.address) ifconfig.co

Command line changes

The below should provide a high level overview of the command line changes introduced in the 0.6.0 release.

 $ wireleap help
 Usage: wireleap COMMAND [OPTIONS]

 Commands:
   help          Display this help message or help on a command
   init          Initialize wireleap home directory
   config        Get or set wireleap configuration settings

-  import        Import accesskeys JSON and set up associated contract
-  servicekey    Trigger accesskey activation (accesskey.use_on_demand=false)
+  accesskeys    Manage accesskeys

-  start         Start wireleap daemon (SOCKSv5/connection broker)
-  status        Report wireleap daemon status
-  reload        Reload wireleap daemon configuration
-  restart       Restart wireleap daemon
-  stop          Stop wireleap daemon
-  log           Show wireleap logs
+  start         Start wireleap controller daemon
+  status        Report wireleap controller daemon status
+  reload        Reload wireleap controller daemon configuration
+  restart       Restart wireleap controller daemon
+  stop          Stop wireleap controller daemon
+  log           Show wireleap controller daemon logs

-  tun           Control tun device
+  tun           Control TUN device forwarder

+  socks         Control SOCKSv5 proxy forwarder
-  intercept     Run executable and redirect connections to wireleap daemon
-  exec          Execute script from scripts directory
+  intercept     Run executable and redirect connections (req. SOCKS forwarder)
+  exec          Execute script from scripts directory (req. SOCKS forwarder)

   upgrade       Upgrade wireleap to the latest version per directory
   rollback      Undo a partially completed upgrade
-  info          Display some info and stats
   version       Show version and exit

 Run 'wireleap help COMMAND' for more information on a command.

Configuration changes

The broker and forwarders are now configured under their respective namespaces, and the controller’s address being top-level.

 $ wireleap help config
 Usage: wireleap config [KEY [VALUE]]

 Get or set wireleap configuration settings

 Keys:
-  timeout                        (str)  Dial timeout duration
-  contract                       (str)  Service contract associated with accesskeys
-  address.socks                  (str)  SOCKS5 proxy address of wireleap daemon
-  address.h2c                    (str)  H2C proxy address of wireleap daemon
-  address.tun                    (str)  TUN device address (not loopback)
-  circuit.hops                   (int)  Number of relay hops to use in a circuit
-  circuit.whitelist              (list) Whitelist of relays to use
-  accesskey.use_on_demand        (bool) Activate accesskeys as needed
+  address                        (str)  Controller address
+  broker.address                 (str)  Override default broker address
+  broker.accesskey.use_on_demand (bool) Activate accesskeys as needed
+  broker.circuit.timeout         (str)  Dial timeout duration
+  broker.circuit.hops            (int)  Number of relays to use in a circuit
+  broker.circuit.whitelist       (list) Relay addresses to use in circuit
+  forwarders.socks.address       (str)  SOCKSv5 proxy address
+  forwarders.tun.address         (str)  TUN device address (not loopback)

 To unset a key, specify `null` as the value

Default port changes

The broker (previously configured under address.h2c with the default port of 13492) is now managed under the controller. By default it is served using the controller URI /broker, but can be configured under a unix socket if desired. The controller default port is 13490.

The default TUN device port has changed from 13493 to 13492. The default SOCKSv5 port of 13491 has not changed.

- address.h2c               (default: 127.0.0.1:13492)
+ address                   (default: 127.0.0.1:13490)

- address.socks             (default: 127.0.0.1:13491)
+ forwarders.socks.address  (default: 127.0.0.1:13491)

- address.tun               (default: 10.13.49.0:13493)
+ forwarders.tun.address    (default: 10.13.49.0:13492)

Changelog

common (0.3.6)

  • Client restructuring-related changes:

    • cli: capitalize options help text
    • status: use Error() in WriteTo()
    • h2conn: wrap h2-native errors passed from Read()
    • client: improve PerformRequestOnce error message
    • client: use non-deferred body close & replacement
    • status: add NoContent 204 status (HTTP 204 No Content)
    • client: allow customizing retry logic
    • status: do not escape html when marshaling
    • client: add PerformOnce (no retries)
    • status: add ErrNotImplemented (HTTP 501 Not Implemented)
    • cli: unpack wireleap_socks with correct mode

  • Includes interface versions:

    • clientcontract v0.1.0
    • clientdir v0.2.0
    • clientrelay v0.2.0
    • contractps v0.1.0
    • psauth v0.1.0
    • relaycontract v0.1.0
    • relaydir v0.2.0
    • relayrelay v0.2.0

wireleap (0.6.0)

  • Depends on wireleap/common v0.3.6.

  • wireleap client restructuring:

    • wireleap_socks is now a separate binary
    • wireleap split into broker & REST API controller
    • REST API implemented according to spec
    • REST API controller listens on TCP or Unix socket
    • Accesskey related subcommands now grouped under accesskeys subcommand
    • Accesskey import now requires proper URL as input (file:// or https://)
    • All CLI commands except exec and intercept now use the API
    • All CLI commands except start require wireleap API to be running
    • completion.bash updated to match new CLI
    • Config file format changed:
      • contract made obsolete by contract.json
      • address split into address and broker.address
      • address.h2c is now address
      • circuit moved under broker.circuit
      • timeout moved under broker.circuit.timeout
      • new forwarders section with socks and tun
      • address.socks moved under forwarders.socks.address
      • address.tun moved under forwarders.tun.address
      • migration to new config file format added

Version

0.6.0