Skip to main content

A command-line tool to query and control a running Tor. Based on txtorcon + Twisted.

Project description

.. carml documentation


.. toctree::
:maxdepth: 2

.. warning:: This is early-Alpha code. "Release early, release often"
gives you a chance to try things out at the expense of the very
real possibility of **serious, anonymity-destroying bugs!** (Please
report them using github)


carml
=====

``carml`` is a command-line tool to query and control a running Tor
(including Tor Browser Bundle). You can do things like:

* list and remove streams and circuits;
* monitor stream, circuit and address-map events;
* watch for any Tor event and print it (or many) out;
* monitor bandwidth;
* run any Tor control-protocol command;
* pipe through common Unix tools like ``grep``, ``less``, ``cut``, etcetera;
* download TBB through Tor, with pinned certs and signature checking;
* ...even spit out and run ``xplanet`` configs (with router/circuit markers)!

It is written in Python and uses Tor's control-port via the `txtorcon
library <https://txtorcon.readthedocs.org>`_.

**Documentation at:** `carml.rtfd.org <https://carml.readthedocs.org/en/latest/>`_

In some ways, ``carml`` started as a dumping-ground for things I
happened to make Tor do at least once from Python code. Are there
things you wish you could easily make Tor do from the command-line?
File an enhancement bug at GitHub!

``carml`` is also easy to extend, even with system- or `virtualenv
<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_- installed
packages.

Feedback is appreciated -- pull-requests and bug-reports (including
feature enhancements) welcome `at GitHub
<https://github.com/meejah/carml>`_ or you can contact me in `#tor-dev
on OFTC <irc://irc.oftc.net/tor-dev>`_ or via *meejah at meejah dot
ca* with the public-key contained in the source.

**I'm happy to accept a new logo** if it is open-licensed somehow;
obviously I'm no logo-designer ;)


Some Quick Examples
-------------------

.. sourcecode:: shell-session

(venv)meejah@machine:~$ carml circ --list
Connected to a Tor version "0.2.4.21 (git-c5a648cc6f218339)" (status: recommended).
Circuits:
809: BUILT 29 minutes ago carmlfake0->~Unnamed->lobstertech
810: BUILT 29 minutes ago ~carmelfake1->~toxiroxi->~SECxFreeBSD64
811: BUILT 5 minutes ago carmelfake2->torpidsDEinterwerk->~rainbowwarrior
813: BUILT 24 seconds ago carmlfake0->~arkhaios1->~IPredator
(venv)meejah@machine:~$ carml circ --delete 810
Connected to a Tor version "0.2.4.21 (git-c5a648cc6f218339)" (status: recommended).
Deleting circuit "810"...
...circuit 172 gone.
(venv)meejah@machine:~$ echo "hello world" | carml pastebin --once
12 bytes to share.
Launching Tor: connected.
People using Tor Browser Bundle can find your paste at (once the descriptor uploads):

http://ok2byooigb4v53be.onion

If you wish to keep the hidden-service keys, they're in (until we shut down):
/dev/shm/tortmp6eHPg4
Awaiting descriptor upload...
Descriptor uploaded; hidden-service should be reachable.
Mon Jul 21 13:54:38 2014: Serving request to User-Agent "curl/7.37.0".
Shutting down.
(venv)meejah@machine:~$ carml downloadbundle --extract
Getting recommended versions from "https://check.torproject.org/RecommendedTBBVersions".
3.6.3-Linux, 3.6.3-MacOS, 3.6.3-Windows
tor-browser-linux64-3.6.3_en-US.tar.xz.asc: already exists, so not downloading.
tor-browser-linux64-3.6.3_en-US.tar.xz: already exists, so not downloading.
gpg: Signature made Fri 25 Jul 2014 11:20:02 AM MDT using RSA key ID 63FEE659
gpg: Good signature from "Erinn Clark <erinn@torproject.org>"
gpg: aka "Erinn Clark <erinn@debian.org>"
gpg: aka "Erinn Clark <erinn@double-helix.org>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 8738 A680 B84B 3031 A630 F2DB 416F 0610 63FE E659
Signature is good.
Extracting "tor-browser-linux64-3.6.3_en-US.tar.xz"...
decompressing...
20% extracted
40% extracted
60% extracted
80% extracted
100% extracted
Tor Browser Bundle downloaded and extracted.
To run:
./tor-browser_en-US/start-tor-browser


License
-------

``carml`` is public domain. See `unlicense.org
<http://unlicense.org/>`_ for more information.

.. toctree::
:maxdepth: 2

installation
commands
development
howtos

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

carml-0.0.6.tar.gz (122.1 kB view details)

Uploaded Source

Built Distribution

carml-0.0.6-py2-none-any.whl (139.8 kB view details)

Uploaded Python 2

File details

Details for the file carml-0.0.6.tar.gz.

File metadata

  • Download URL: carml-0.0.6.tar.gz
  • Upload date:
  • Size: 122.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for carml-0.0.6.tar.gz
Algorithm Hash digest
SHA256 fc620c800702376b6f5c74b0fc90f168735ec709a2b979eca658f479037622a6
MD5 fbf6accfae1c63c015a65eb58ab759fc
BLAKE2b-256 07331a371af40f0008bec0190445d1b3b847706145b0e1db1b59f204a9ca54a9

See more details on using hashes here.

File details

Details for the file carml-0.0.6-py2-none-any.whl.

File metadata

File hashes

Hashes for carml-0.0.6-py2-none-any.whl
Algorithm Hash digest
SHA256 32911b4f0822b736130d0b0aaa1ff4438621109bf38198e0118772f03ea55d26
MD5 b60f6b55d71713232781c4251807655d
BLAKE2b-256 6de1f65faa53a2b29354b038a7366d1abef35cca7d5fa82dca086b3d19a2ee78

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page