Opened 21 months ago

Last modified 19 months ago

#23277 new enhancement

ApplicationControlSocket: the way for apps to control Tor

Reported by: yurivict271 Owned by:
Priority: Medium Milestone: Tor: unspecified
Component: Core Tor/Tor Version: Tor: unspecified
Severity: Normal Keywords:
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:



When third party apps need to control Tor (most likely to create onions), they always face the choice of how to do this right. There are several options: 1. to start as root, connect to Tor, and setuid 2. to use the control port 9051, this will sometimes require password or cookie to authenticate 3. to run under group _tor and use control socket, reading auth-cookie or supplying password.

These choices come up for all apps that need to control Tor, but which are otherwise unrelated to Tor. Lack of clear recipe as of what should they choose to do and the complexity involved in this decision give rise to random behaviors, unsafe practices, etc.

Proposed solution:

New torrc instruction ApplicationControlSocket:

ApplicationControlSocket group_name /path/to/app/socket (cookie:/path/to/app/cookie_auth_file|hash:16:XXXXX...)


  • group_name: UNIX group name this instruction applies to
  • /path/to/app/socket: path where Tor will create the UNIX socket
  • (cookie:/path/to/app/cookie_auth_file|hash:16:XXXXX...): either the path to auth-cookie file, or hashed password.

Every application that needs to control Tor runs as its own group. This group has this instruction in torrc that enables it to control Tor.

Tor will create a special control socket just for this group. Optionally, Tor will create the auth-cookie file. Tor will check credentials of incoming connections, and will reject any connection not coming from the process with this specific group, or when the user is not a member of this group. Tor will make permissions on socket and auth-cookie files like this: ----rw---- _tor:{group_name}.



  • Easy to use and understand
  • Apps will have no need to make choices and reinvent the wheel
  • This will be a standard, suggested way
  • Reduces the chance to have unsafe setups
  • Eliminates the need to have the potentially unsafe control port 9051


  • Some effort to implement


Only applicable to OSes where UNIX sockets are available: Linux, BSD, MacOS, SunOS. Probably not on Windows.

Examples of apps:

  • ZeroNet (can run with its own group zeronet)
  • Tox (can require user to be a member of tox group allowed to control Tor)
  • RetroShare (can require user to be a member of group retroshare)

Alternatively, UI apps can share the group, ex. require the user to be a member of 'tor-controllers', and share one ApplicationControlSocket instruction.

Child Tickets

Change History (4)

comment:1 Changed 21 months ago by cypherpunks

Component: - Select a componentCore Tor/Tor

comment:2 Changed 21 months ago by nickm

Milestone: Tor: unspecified

To clarify -- this is a proposal for a new interface for opening controlport sockets, but actually any new features in how they can be opened?

comment:3 Changed 21 months ago by yurivict271

This is a new feature suggestion.

comment:4 Changed 19 months ago by yurivict271


The feature is that the user that needs third-party apps to access Tor can add this line, and this app will cleanly gain access to the tor control UNIX socket.

For example, ZeroNet server works under it's own group, but needs to control Tor.


Note: See TracTickets for help on using tickets.