This project is no longer maintained and is here for historical / archival purposes only.
I've developed a better tool for this sort of thing: https://github.com/cmars/oniongrok
ormesh helps you connect services through Tor.
Abstract away geography and network topologies.
Disregard container networking, NATs, firewall policies, possibly even traffic shaping and protocol filtering, if you throw bridges and obfsproxy into the mix.
Access services running almost anywhere, from just about anywhere else.
Tor is well-suited to traversing all kinds of networks between services and the clients that would consume them. Tor provides resilient network infrastructure with no single point of failure.
Tor hidden services can be deployed in a private, authenticated mode, which keeps services from being generally accessible.
ormesh helps manage the configuration and auth token exchange necessary to deploy a private backplane to connect infrastructure.
HTTP, email, messaging, sensors & actuators, home automation, and file synchronization are just some ideas to get you started.
In general, services that require little bandwidth or tolerate latency. With ormesh, they can be accessed without the hassle of setting up iptables, NAT port forwarding, VPNs, TLS, and without relying on central rendezvous servers.
ormesh is not a VPN in the conventional sense.
ormesh is not intended for operating unauthenticated anonymous hidden services. Anonymity is an interesting side-effect of building on Tor, but it is not a priority for ormesh, nor it is guaranteed for all use cases. Users are responsible for evaluating ormesh (and its Tor configuration) and deciding whether it meets security requirements and threat models.
Low-latency, high bandwidth applications may not perform well over ormesh's Tor configuration. Improvements here are possible (by trading anonymity for improved latency and network throughput) but not yet implemented.
Tor only routes TCP traffic.
Install Homebrew. Install Tor Browser. Then:
brew tap cmars/ormesh
brew install ormesh
ormesh operates the Tor executable that comes with Tor Browser.
Install Tor Browser. Then,
download an ormesh binary tarball release, extract and install
ormesh.exe into your %PATH%.
Like macOS, ormesh on Windows relies on Tor Browser. The Windows default config expects to find Tor Browser installed to the current user's Desktop.
Fair warning, I've not really tested much on Windows..
Read the script before running if you like. It will install ormesh to /usr/bin,
install Tor standalone from official torproject archives, setcap ormesh to
allow privileged port binding, and install ormesh as a systemd service.
curl https://git.io/vFN94 -sSfL | bash
sudo snap install --edge ormesh
The snap package does not work well for some use cases so it's considered experimental. I've had trouble installing into containers and binding to privileged ports.
docker run --name ormesh -d cmars/ormesh:0.2.0
Make it persistent and automatically start up:
docker run --name ormesh -d \
-v /srv/ormesh-config:/var/lib/ormesh cmars/ormesh:0.2.0
Download an ormesh binary tarball release or build from source:
Download and build ormesh:
go get -u github.com/cmars/ormesh
Export services running locally as Tor hidden services.
$ ormesh export add 22
$ ormesh export add 80
Export services on other hosts.
$ ormesh export add 192.168.1.19:8000
Each client gets an auth token string that grants access to the exported services. Without the auth token, the hidden service is not accessible.
This string should be securely sent to the user of my-MacBook:
$ ormesh client add my-MacBook
fl3scqcsbitwf7zb.onion x29A3kzv4hrYvBhTkPMV2h
The agent will operate Tor, implementing the configured export and client access policies.
$ ormesh agent run
On Linux, the agent will launch Tor and run it as a subprocess until interrupted or terminated.
On macOS and Windows, the agent will connect to the Tor process launched with the Tor Browser and exit after applying changes to the Tor configuration -- unless remote services are imported locally.
On the machine my-MacBook, start Tor Browser, and then add a remote using the
onion address and auth token displayed by client add above.
$ ormesh remote add my-server fl3scqcsbitwf7zb.onion x29A3kzv4hrYvBhTkPMV2h
$ ormesh remote show my-server
fl3scqcsbitwf7zb.onion
Display an ssh-config(5) stanza for the remote.
$ ormesh remote ssh-config my-server
Host my-server
ProxyCommand nc -X 5 -x localhost:9250 %h %p
Hostname fl3scqcsbitwf7zb.onion
Set up local port forwarding to remote services with imports. The agent will forward connections to local ports to the corresponding remote service until the process is interrupted or terminated.
Forward local port 10022 to port 22 on the remote:
$ ormesh import add website 22 127.0.0.1:10022
$ ormesh agent run
Listen on all addresses to create a public ingress to a remote service. Useful for circumventing inbound port blocks where the service is running. For example, you want to physically locate your email server in a mobile camper, your ISP blocks SMTP inbound, and your IP address changes often. Import your services from a cloud instance with a public IP and DNS.
$ ormesh agent privbind
$ ormesh import add mailinabox 25 0.0.0.0:25
$ ormesh import add mailinabox 587 0.0.0.0:587
$ ormesh agent run
$ ormesh agent run
Configuration changes made while the agent is running are applied immediately.
Display a systemd unit file that will run ormesh, from its current installed binary path.
$ ormesh agent systemd
[Unit]
Description=ormesh - onion-routed mesh
[Service]
ExecStart=/path/to/ormesh agent run
Restart=always
User=ubuntu
[Install]
WantedBy=default.target
The ormesh image supports configuration by environment variables:
docker run --name ormesh -d \
-e 'ORMESH_EXPORTS=80' \
-e 'ORMESH_CLIENTS=desktop;laptop' cmars/ormesh:0.2.0
will preconfigure ormesh to export 127.0.0.1:80 to clients named "desktop" and "laptop".
Display the client's onion address & auth cookie by "adding" them again
(client add is idempotent):
docker exec ormesh /ormesh client add desktop
Other configuration commands can be applied with docker exec while the
container is running, changes are applied immediately.
ormesh client add --qr my-phone
Displays a QR code in the terminal that Orbot can read, to import the client auth token. For best results, make sure your terminal is at least 80x40 and supports ANSI codes.
- Open Orbot.
- From the menu, choose: "Hidden Services" -> "Client cookies"
- From the menu, choose: "Read from QR" and then scan the QR code displayed in the terminal.
- Restart Orbot.
This authorizes Orbot to be able to connect to the hidden service.
The onion address can then be accessed from apps that connect through Tor. Orfox or "Apps VPN mode" for other applications.