forked from nyxnor/tor-ctrl
/
tor-ctrl.8
165 lines (164 loc) · 4.88 KB
/
tor-ctrl.8
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "tor-ctrl" "8" "September 2069" "Interact with Tor\[aq]s controller via command line tool" ""
.hy
.SH NAME
.PP
tor-ctrl(8) - Interact with Tor\[aq]s controller via command line tool
.SH SYNOPSIS
.PP
\f[B]tor-ctrl\f[R] [\f[B]-wq\f[R]] [\f[B]-s\f[R] \f[I]socket\f[R]]
[\f[B]-p\f[R] \f[I]pwd\f[R]] [\f[B]-t\f[R] \f[I]time\f[R]]
[[\f[B]-c\f[R]|\f[B]--\f[R]] \f[I]command\f[R]]
.SH DESCRIPTION
.PP
\f[B]tor-ctrl\f[R] is a commandline tool for executing commands on
tor\[aq]s controller.
.PP
The following configuration lines must be inserted to your torrc and tor
reloaded to apply the changes.
.PP
In order to get this to work, define the socket that will control the
tor process, can be a tcp socket \f[I]ControlPort 9051\f[R] or a unix
domain socket \f[I]ControlSocket /path/to/socket\f[R].
.PP
To secure the controller, you must setup and authentication method,
which can be a cookie \f[I]CookieAuthentication 1\f[R] or if you want a
fixed password, hash a password with \f[I]echo
\[dq]HashedControlPassword $(tor --hash-password yourpassword)\[dq]\f[R]
and use the same output given.
.SH OPTIONS
.TP
[\f[B]-c\f[R]|\f[B]--\f[R]] [\f[I]command\f[R]]
command to execute.
If the command option is \f[I]-c\f[R], you must \[dq]quote\[dq] your
command.
If the command option is \f[I]--\f[R], option parsing will stop, meaning
that any option specified after it won\[aq]t be parsed, the benefit is
that it becomes unnecessary to quote your command.
To use different commands together, you must make shell escape to a new
line with \f[I]\[rs]\[rs]n\f[R].
.TP
\f[B]-s\f[R] [\f[I]socket\f[R]]
Tor\[aq]s control socket.
Accept \f[I]tcp socket\f[R] in the format
[\f[I]addr:\f[R]]\f[I]port\f[R] (examples: 9051, 127.0.0.1:9051).
Accept \f[I]unix domain socket\f[R] in the following format
[\f[I]unix:\f[R]]\f[I]path\f[R] (examples: /run/tor/control,
unix:/run/tor/control).
(Default: 9051).
.TP
\f[B]-p\f[R] [\f[I]pwd\f[R]]
Use password instead of tor\[aq]s cookie.
(Default: not used).
.TP
\f[B]-t\f[R] [\f[I]time\f[R]]
sleep [var] seconds after each command sent.
(Default for socat/nc: 0 second, Default for telnet: 1 second).
.TP
\f[B]-w\f[R]
Wait for confirmation with an enter pressed to end the connection after
sending the command.
Useful when you want to be warned about events, example is when the
command is \f[I]SETEVENTS STREAM\f[R] (Default: not set)
.TP
\f[B]-q\f[R]
Quiet mode.
(Default: not set).
.SH DEBUGGING OPTIONS
.TP
\f[B]-d\f[R]
Debug mode.
The shell shall write to standard error a trace for each command after
it expands the command and before it executes it.
(Default: not set).
.TP
\f[B]-r\f[R]
Dry-run mode.
Show what would be done, without sending commands to the controller.
(Default: not set).
.SH EXIT CODES
.TP
\f[B]0\f[R]
Success.
.TP
\f[B]>0\f[R]
Fail.
.SH EXAMPLES
.PP
Check your tor software version:
.IP
.nf
\f[C]
tor-ctrl GETINFO version
\f[R]
.fi
.PP
Get your SocksPort configuration and check where tor is listening for
socks connections:
.IP
.nf
\f[C]
tor-ctrl -s 9051 -p foobar -- GETCONF SocksPort \[rs]\[rs]n GETINFO net/listeners/socks\[rs]\[dq]
\f[R]
.fi
.PP
Set bandwidth rate:
.IP
.nf
\f[C]
tor-ctrl -q SETCONF bandwidthrate=1mb
\f[R]
.fi
.PP
For setting the bandwidth for specific times of the day, I suggest
calling tor-ctrl via cron.
e.g: set the bandwidth to 100kb at 07:00 and to 1mb at 22:00.
You can use notations like 1mb, 1kb or the number of bytes:
.IP
.nf
\f[C]
0 22 * * * /path/to/tor-ctrl -c \[dq]SETCONF bandwidthrate=1mb\[dq]
0 7 * * * /path/to/tor-ctrl -c \[dq]SETCONF bandwidthrate=100kb\[dq]
\f[R]
.fi
.SH WWW
.PP
https://gitweb.torproject.org/torspec.git/tree/control-spec.txt
.SH DISCLAIMER
.PP
This package is produced independently of, and carries no guarantee
from, The Tor Project.
.SS SEE ALSO
.PP
tor(1)
.SH LICENSE
.PP
Copyright (c) 2007 by Stefan Behte
.PP
Portion Copyright (C) 2013 - 2020 ENCRYPTED SUPPORT LP
<adrelanos@riseup.net>
.PP
Portion Copyright (C) 2021 - 2022 nyxnor <nyxnor@protonmail.com>
.PP
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
.PP
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
with this program.
If not, see <https://www.gnu.org/licenses/>.
.PP
On Debian systems, the full text of the GNU General Public License
version 3 can be found in the file
\[ga]/usr/share/common-licenses/GPL-3\[aq].
.SH AUTHORS
tor-ctrl was written by Stefan Behte (stefan.behte\[at]gmx.net), later
developed by and Patrick Schleizer (adrelanos\[at]riseup.net) and
further improved by nyxnor (nyxnor\[at]protonmail.com).