Tor 控制协议信号列表

信号是 Tor 控制器发往 Tor 本身(OP)的命令。其基于 TCP 协议实现,格式为:

"SIGNAL" SP Signal CRLF

Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" / "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" /         "CLEARDNSCACHE" / "HEARTBEAT" / "ACTIVE" / "DORMANT"

但是诸如 Stem 等框架已经对其进行封装,只需要简单使用controller.signal(Signal.NEWNYM)便可一键切换电路

协议原文

查看英文原文

3.7. SIGNAL

Sent from the client to the server. The syntax is:

"SIGNAL" SP Signal CRLF

Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" / "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" / "CLEARDNSCACHE" / "HEARTBEAT" / "ACTIVE" / "DORMANT"

The meaning of the signals are:

  • RELOAD -- Reload: reload config items.
  • SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately. If it's an OR, close listeners and exit after ShutdownWaitLength seconds.
  • DUMP -- Dump stats: log information about open connections and circuits.
  • DEBUG -- Debug: switch all open logs to loglevel debug.
  • HALT -- Immediate shutdown: clean up and exit now.
  • CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames.
  • NEWNYM -- Switch to clean circuits, so new application requests don't share any circuits with old ones. Also clears the client-side DNS cache. (Tor MAY rate-limit its response to this signal.)
  • HEARTBEAT -- Make Tor dump an unscheduled Heartbeat message to log.
  • DORMANT -- Tell Tor to become "dormant". A dormant Tor will try to avoid CPU and network usage until it receives user-initiated network request. (Don't use this on relays or hidden services yet!)
  • ACTIVE -- Tell Tor to stop being "dormant", as if it had received a user-initiated network request.

The server responds with "250 OK" if the signal is recognized (or simply closes the socket if it was asked to close immediately), or "552 Unrecognized signal" if the signal is unrecognized.

Note that not all of these signals have POSIX signal equivalents. The ones that do are as below. You may also use these POSIX names for the signal that have them.

  • RELOAD: HUP
  • SHUTDOWN: INT
  • HALT: TERM
  • DUMP: USR1
  • DEBUG: USR2

[SIGNAL DORMANT and SIGNAL ACTIVE were added in 0.4.0.1-alpha.]

从客户端发送到服务端的信号,语法是

"SIGNAL" SP Signal CRLF

Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" / "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" / "CLEARDNSCACHE" / "HEARTBEAT" / "ACTIVE" / "DORMANT"

信号有如下内容,以及含义为:

  • RELOAD: 重新加载配置项
  • SHUTDOWN: 控制关机(如果服务端是 OP,则退出;如果服务端是 OR,则关闭,并在关闭后ShutdownWaitLength秒后退出)
  • DUMP: 存储打开的连接和电路的连接的日志信息
  • HALT: 清理数据并立即退出
  • CLEARDNSCACHE: 忘记服务器缓存的所有主机和客户端
  • NEWNYM: 切换到新的干净电路,这样新的应用请求不会与旧的应用共享电路,同时还会清除 DNS 缓存(Tor可能会限制对该信号响应的速率)
  • HEARTBEAT: 让 Tor 将一个计划外的心跳消息存储到日志中
  • DORMANT: 要求 Tor 开始休眠,不再消耗 CPU、网络等资源,直到用户发起网络请求(如果将 Tor 用于中继节点或隐藏服务,则会导致服务下线)
  • ACTIVE: 要求休眠的 Tor 继续工作,仿佛收到了一个用户的网络请求

如果信号被识别,服务器响应250 OK(但如果是要求关闭 Tor 的信号,则会简单地关闭套接字);如果信号未被识别,则会回复552 Unrecognized signal

需要注意的是,这里的信号与 POSIX 无关。但部分存在类似的类似的功能:

  • RELOAD - HUP
  • SHUTDOWN - INT
  • HALT - TERM
  • DUMP - USR1
  • DEBUG - USR2

其中,休眠和激活信号在 0.4.0.1-alpha 后加入