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
.. 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
Release history Release notifications | RSS feed
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)
Built Distribution
carml-0.0.6-py2-none-any.whl
(139.8 kB
view details)
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | fc620c800702376b6f5c74b0fc90f168735ec709a2b979eca658f479037622a6 |
|
MD5 | fbf6accfae1c63c015a65eb58ab759fc |
|
BLAKE2b-256 | 07331a371af40f0008bec0190445d1b3b847706145b0e1db1b59f204a9ca54a9 |
File details
Details for the file carml-0.0.6-py2-none-any.whl
.
File metadata
- Download URL: carml-0.0.6-py2-none-any.whl
- Upload date:
- Size: 139.8 kB
- Tags: Python 2
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 32911b4f0822b736130d0b0aaa1ff4438621109bf38198e0118772f03ea55d26 |
|
MD5 | b60f6b55d71713232781c4251807655d |
|
BLAKE2b-256 | 6de1f65faa53a2b29354b038a7366d1abef35cca7d5fa82dca086b3d19a2ee78 |