Command line tool for setting up stream for communication from the Tor Controller's (client) to a Tor process (server). The client send commands using TCP sockets or Unix-domain sockets and receive replies from the server.
This package is produced independently of, and carries no guarantee from, The Tor Project.
tor-ctrl was created by Stefan Behte, later developed by Patrick Schleizer and further improved by nyxnor.
ControlPort/ControlSocket: the following socket types are accepted to connect to the controller:
- Unix-domain socket, specified as
[unix:]path - TCP socket, specified as
[addr:]port
Autodetects the socket by reading the tor configuration. If still unknown, will try TCP socket 127.0.0.1:9051.
Authentication methods:
SAFECOOKIE(on the work, help wanted)- COOKIE - discover it by sending PROTOCOLINFO, so no need to specify the file.
- HASHEDPASSWORD - needs to be specifiedo on the command line
The configuration lines below must be set inside your tor configuration file (torrc).
This will be the socket that allows those connections to control the Tor process. Choose between ControlPort and ControlSocket (setting both means either control can be used).
TCP socket:
ControlPort 9051Unix domain socket:
ControlSocket /var/run/tor/control
## or
#ControlPort unix:/var/lib/tor/controlThis is will be the method you will authenticate to the controller. Choose between CookieAuthentication and HashedControlPassword (Setting both authentication methods means either method is sufficient to authenticate to Tor)
Cookie:
CookieAuthentication 1Password
Change YOUR_PASSOWRD, but maintain it double quoted)
printf '%s\n' "HashedControlPassword $(tor --hash-password "YOUR_PASSOWRD")"
the result of the above operation should be used as the configuration line.
If you have made any changes to the tor run commands file (torrc), you will need to send a HUP signal to tor as root to apply the new configuration:
pkill -sighup tor
## or
#ps -o user,pid,command -A | grep -E "/usr/bin/tor|/usr/local/bin/tor"
#kill -hup PID_FROM_ABOVEIf you have tor running with SandBox 1, you will need to restart tor.
At least one of each item is necessary:
- Networking tool: nc/socat/telnet
- Hex converter: xxd/hexdump/od
Install the script and the manual:
sudo ./configure.sh installInstall developer scripts:
sudo apt install -y devscriptsInstall build dependencies.
sudo mk-build-deps --remove --installIf that did not work, have a look in debian/control file and manually install all packages listed under Build-Depends and Depends.
Build the package without signing it (not required for personal use) and install it.
sudo dpkg-buildpackage -b --no-signThe package can be found in the parent folder. Install the package:
sudo dpkg -i ../tor-ctrl_*.debDelete temporary debhelper files in package source folder as well as debhelper artifacts:
sudo rm -rf *-build-deps_*.buildinfo *-build-deps_*.changes \
debian/*.debhelper.log debian/*.substvars \
debian/.debhelper debian/files \
debian/debhelper-build-stamp debian/tor-ctrlDelete debhelper artifacts from the parent folder (including the .deb file):
sudo rm -f ../tor-ctrl_*.deb ../tor-ctrl_*.buildinfo ../tor-ctrl_*.changesIt is required to read the tor manual and the control-spec.
Read tor-ctrl's manual:
man tor-ctrlSee usage:
tor-ctrl -hGet the tor user configured on tor configuration files:
tor-ctrl GETCONF UserGet the username under which the tor process is running:
tor-ctrl GETINFO process/pidGet process id belonging to the main tor process:
tor-ctrl GETINFO process/pidSwitch to clean circuits:
tor-ctrl SIGNAL NEWNYMGet your circuits (raw):
tor-ctrl GETINFO circuit-statusThat is not very clean to read, too much information, so lets organize it:
tor-ctrl-circuitStart listening for streams:
tor-ctrl -w SETEVENTS STREAMFrom another terminal, connect via Tor to where you wish
curl -x socks5h://127.0.0.1:9050 https://check.torproject.org/api/ipReturn to the script and and watch the streams. Use the interrupt signal (Ctrl+C) to stop.
And if we could see the streams and to which circuit they are attached to and what is their target?
tor-ctrl-streamFrom another terminal, connect via Tor to where you wish:
curl -x socks5h://127.0.0.1:9050 github.comReturn to the script and use the interrupt signal (Ctrl+C) to print out the stream events received.
tor-ctrl can connect to any Tor socket, even to the Tor Browser Bundle socket.
Open Tor Browser but don't connect to the network yet. The default socket is 127.0.0.1:9151, so specify it when running tor-ctrl:
tor-ctrl-stream -s 9151Note: On Whonix-Gateway, there is no need to specify the socket, it will be auto-detected.
Connect to the network, you will watch every stream that is made. Browse to any website you'd like to visit.
If you plan to share your streams because you saw some unwanted connections being made, don't forget to use the -z option, so circuits paths are not shown.
If you receive permission denied, probably you are not running tor-ctrl with the user that can connect to tor's controller socket, which is the tor user in some cases.
On Tails:
sudo -u debian-tor tor-ctrl GETINFO versionOn OpenBSD:
doas -u _tor tor-ctrl GETINFO versionIf the response is unexpected, run with option -r to get the information that will be used to connect to tor's controller. If they are correct, use option -d to debug the script and be very verbose.
Warning: You should review the information before posting on a issue, because it can contain the authentication string (password and cookie hex) and the control host, in the case the host is external (not localhost), anyone with both information will be able to authenticate to your controller. If you haven't set the authentication method and the control host is external and shared, this is far worse as there is no authentication string, so strongly recommended to configure an authentication method for your controller.