Skip to content

Latest commit

 

History

History
161 lines (105 loc) · 6.59 KB

README.rst

File metadata and controls

161 lines (105 loc) · 6.59 KB
Raw

magneticod

Autonomous BitTorrent DHT crawler and metadata fetcher.

magneticod is the daemon that crawls the BitTorrent DHT network in the background to discover info hashes and fetches metadata from the peers. It uses SQLite 3 that is built-in your Python 3.x distribution to persist data.

Installation

Requirements

  • Python 3.5 or above.

    WARNING:

    Python 3.6.0 and 3.6.1 suffer from a bug (issue #29714) that causes magneticod to fail. As it is an interpreter bug that I have no control on, please make sure that you are not using any of those Python 3 versions to run magneticod.

  • Decent Internet access (IPv4)

    magneticod uses UDP protocol to communicate with the nodes in the DHT network, and TCP to communicate with the peers while fetching metadata. Please make sure you have a healthy connection; you can confirm this by checking at the connection status indicator of your BitTorrent client: if it does not indicate any error, magneticod should just work fine.

Instructions

  1. Download the latest version of magneticod from PyPI using pip3:

    pip3 install magneticod --user

  2. Add installation path to the $PATH; append the following line to your ~/.profile if you are using bash

    export PATH=$PATH:~/.local/bin

    or if you are on macOS and using bash, (assuming that you are using Python 3.5):

    export PATH="${PATH}:${HOME}/Library/Python/3.5/bin/"

  3. Activate the changes to $PATH (again, if you are using bash):

    source ~/.profile

  4. Confirm that it is running:

    magneticod

    Within maximum 5 minutes (and usually under a minute) magneticod will discover a few torrents! This, of course, depends on your bandwidth, and your network configuration (existence of a firewall, misconfigured NAT, etc.).

  5. (only for systemd users, skip the rest of the steps and proceed to the Using section if you are not a systemd user or want to use a different solution)

    Download the magneticod systemd service file (at magneticod/systemd/magneticod.service) and change the tilde symbol with the path of your home directory, and the PORT_NUMBER with the preferred port number. For example, if my username is bora and I prefer the port 64879, this line

    ExecStart=~/.local/bin/magneticod magneticod --node-addr 0.0.0.0:PORT_NUMBER

    should become this:

    ExecStart=/home/bora/.local/bin/magneticod --node-addr 0.0.0.0:64879

    Here, tilde (~) is replaced with /home/bora and the PORT_NUMBER with 64879. Run echo ~ to see the path of your own home directory, if you do not already know. Port numbers above 1000 typically do not require special permissions.

  6. Copy the magneticod systemd service file to your local systemd configuration directory:

    cp magneticod.service ~/.config/systemd/user/

    You might need to create intermediate directories (.config, systemd, and user) if not exists.

  7. (Optional, requires root) Disable iptables for a specified port:

    iptables -I OUTPUT -t raw -p udp --sport PORT_NUMBER -j NOTRACK
iptables -I PREROUTING -t raw -p udp --dport PORT_NUMBER -j NOTRACK

    This is to prevent excessive number of EPERM "Operation not permitted" errors, which also has a negative impact on the performance.

  8. Start magneticod:

    systemctl --user enable magneticod --now

    magneticod should now be running under the supervision of systemd and it should also be automatically started whenever you boot your machine.

    You can check its status and most recent log entries using the following command:

    systemctl --user status magneticod

    To stop magneticod, issue the following:

    systemctl --user stop magneticod

Suggestion:

Keep magneticod running so that when you finish installing magneticow, database will be populated and you can see some results.

Using

magneticod does not require user interference to operate, once it starts running. Hence, there is no "user manual", although you should beware of these points:

  1. Network Usage:

    magneticod does not have any built-in rate limiter yet, and it will literally suck the hell out of your bandwidth. Unless you are running magneticod on a separate machine dedicated for it, you might want to consider starting it manually only when network load is low (e.g. when you are at work or sleeping at night).

  2. Pre-Alpha Bugs:

    magneticod is supposed to work "just fine", but as being at pre-alpha stage, it's likely that you might find some bugs. It will be much appreciated if you can report those bugs, so that magneticod can be improved. See the next sub-section for how to mitigate the issue if you are not using systemd.

Automatic Restarting

Due to minor bugs at this stage of its development, magneticod should be supervised by another program to be ensured that it's running, and should be restarted if not. systemd service file supplied by magneticod implements that, although (if you wish) you can also use a much more primitive approach using GNU screen (which comes pre-installed in many GNU/Linux distributions):

  1. Start screen session named magneticod:

    screen -S magneticod

  2. Run magneticod forever:

    until magneticod; do echo "restarting..."; sleep 5; done;

    This will keep restarting magneticod after five seconds in case if it fails.

  3. Detach the session by pressing Ctrl+A and after Ctrl+D.

  4. If you wish to see the logs, or to kill magneticod, screen -r magneticod will attach the original screen session back. magneticod will exit gracefully upon keyboard interrupt (Ctrl+C) [SIGINT].

Database

magneticod uses SQLite 3 that is built-in by default in almost all Python distributions. appdirs package is used to determine user data directory, which is often ~/.local/share/magneticod. magneticod uses write-ahead logging for its database, so there might be multiple files while it is operating, but database.sqlite3 is the main database where every torrent metadata is stored.

License

All the code is licensed under AGPLv3, unless otherwise stated in the source specific source. See COPYING file in magnetico directory for the full license text.

Dedicated to Cemile Binay, in whose hands I thrived.

Bora M. ALPER <[email protected]>