magneticod

========== 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 <http://bugs.python.org/issue29714>_) 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 ::

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

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

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

3. Activate the changes to $PATH: ::

   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 <systemd/magneticod.service>_) and change the tilde symbol with the path of your home directory. For example, if my username is bora, this line ::

   ExecStart=~/.local/bin/magneticod
   

   should become this: ::

   ExecStart=/home/bora/.local/bin/magneticod
   

   Here, tilde (~) is replaced with /home/bora. Run echo ~ to see the path of your own home directory, if you do not already know.

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. Start magneticod: ::

   systemctl --user start magneticod
   

   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 <https://pypi.python.org/pypi/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 [e-mail]