ezt

Name

ezt -- EZtorrent - a wrapper for BitTorrent

Synopsis

ezt [-c configdir] [-f facility] [start | stop | restart]

ezt {-h}

ezt [-c configdir] {create} [nickname] [torrentdir] [filedir] [servername] [port]

USAGE

ezt automates the process of publishing content with BitTorrent. With ezt, distributing files with BitTorrent is a simple three-step process:

  1. Running "ezt create" to create and initialize a pair of directories: the file directory where files will be placed, for distributing with BitTorrent; and a torrent directory - a web server directory where .torrent metainfo files will be placed, and can be accessed by BitTorrent clients.

  2. Copying some files to the file directory.

  3. Running "ezt start".

ezt now runs as a background daemon process. It takes care of generating all necessary .torrent files, starting a tracker, and starting a seeder process for each .torrent. More files can be added/removed to/from the file directory at any time. "ezt restart" sends a signal to the ezt daemon process to reread the file directory, create any .torrents for newly added files, remove any .torrents of newly removed files, and start or stop any required seeder processes.

It is also possible to create more than one pair of file/torrent directories. ezt runs a separate tracker for each directory, and "ezt" takes of starting and stopping the tracker and its corresponding seeders, where appropriate.

NOTE:

It is highly recommended to have a separate userid for EZtorrent only, and run ezt as that userid, so that ezt's daemon process runs standalone. ezt does not require the services of a shell; ezt's userid can be a shell-less account with blocked password, with the only means of access being su from root.

NOTE:

"ezt create" needs to create a pair of directories: the file directory, which can be anywhere; and a torrent directory which should be somewhere that's accessible over the web (typically somewhere in /var/www/html). File permissions need to allow ezt to do that.

BitTorrent overview

This section gives an introduction to basic BitTorrent concepts. Although EZtorrent does most of the grunge work by itself, a basic understanding of how BitTorrent works is still helpful.

BitTorrent clients do not download files from a central server, but from each other. Files are divided into small parts, then BitTorrent clients connect to each other and download the parts that they do not have, and simultaneously upload parts of the file that they already have, but the other BitTorrent clients do not have.

A small ".torrent" file must be prepared in advance. This is a very small file that's put up on a web site. The ".torrent" file contains some summary information about the file, and the address, or the URL of the "tracker".

A tracker is a process that all BitTorrent clients connect to. It tells all BitTorrent clients how to find each other; it tracks all clients that connect to it and tells them where to find other clients that have other parts of the file. A single tracker process can coordinate multiple .torrent downloads.

A "seeder" is required to publish new files with BitTorrent. The seeder is required to solve the "chicken and the egg" situations. As mentioned previously, BitTorrent clients download files from each other. When a new .torrent is published on a web site, for a new file, obviously this file has not yet been downloaded by any BitTorrent client, so BitTorrent clients that want this file have nowhere to go to.

A seeder is a BitTorrent client that already has the file. It connects to the tracker and announces that it already has the entire file. Other BitTorrent clients then connect to the seeder to begin downloading the initial parts of the file. A seeder process should continue to run even after BitTorrent clients begin downloading the file. In actual practice, a seeder process should remain running as long as the original .torrent can be downloaded from the web site, and as long as its tracker is running.

Therefore, here are the steps that must occur in order to publish files with BitTorrent:

  1. Create .torrent metainfo for each file.

  2. Start a tracker process.

  3. Start a seeder for each .torrent file.

EZtorrent takes care of all of the above. Just place the individual files in a designated directory, then EZtorrent takes over, creating the .torrent files, starting the tracker, and the seeders.

OPTIONS

-c configdir

configdir is a directory that contains symbolic links to all defined torrent directories. "ezt create" adds a symbolic link to the new torrent directory it creates. "ezt start" reads all symbolic links from configdir, and starts a tracker for each linked directory.

To stop a tracker, remove its symbolic link from configdir and run "ezt restart" (if a ezt is already running). After the tracker and all seeders stop, the linked torrent directory and its corresponding file directory can be removed.

-h

ezt uses a default configdir if the -c option is not specified. The default configdir is set when EZtorrent is installed. The -h option displays EZtorrent's copyright and the location of the default configdir (usually /usr/local/etc/torrents or /etc/torrents).

-f facility

ezt's daemon process generates log messages, which are sent to the system's syslog daemon. -f sets the log messages' "facility" name, which determines where syslog actually records the messages. The default facility for ezt is "daemon". Use the -f option to set a different name. The names of legal syslog facility names are: auth, authpriv, console, cron, daemon, ftp, kern, lpr, mail, news, security, user, uucp, local0, local1, local2, local3, local4, local5, local6, and local7.

NOTE:

The actual list of possible facility names varies between different systems. Consult your system documentation for a list of allowed facility names.

Creating new torrent directories

"ezt create" creates a pair of directories for distributing files with BitTorrent. ezt will prompt for the following parameters. Alternatively, specify these parameters on the command line, in the given order:

nickname

A unique name for this pair of directories. This is the name of the symbolic link to the torrent directory in configdir.

torrentdir

ezt automatically creates .torrent files in this directory. torrentdir should be web-accessible, it's typically somewhere in /var/www/html.

ezt creates this directory, and installs a tracker.info file, which is a configuration file used by ezt.

filedir

ezt creates this directory. ezt runs BitTorrent to create a .torrent for everything placed in this directory (except for files that end in .info) and puts them in torrentdir. Removing a file in this directory causes ezt to remove the corresponding .torrent file, the next time ezt starts or restarts.

servername

The DNS name of this server. It must be explicitly specified. "ezt start" runs a tracker on this server, and BitTorrent clients need the tracker's address, to connect to it.

port

The TCP port number the tracker for this torrentdir will listen on. A different port number must be picked for every torrentdir. Any port number can be used that's not already used by some other application. The minimum port number is 1024, the maximum port number depends on the system (usually it's at least 30000). Ports 1-1023 are also available if ezt is invoked by root (not recommended).

The tracker.info file

"ezt create" installs a small file in torrentdir called "tracker.info". It's a small text configuration file; its initial contents will already be set by ezt. Manual adjustments may be made with any text editor. The following settings may appear in this configuration file. Each setting appears on a separate line:

filedir=directory

directory is where files distributed with BitTorrent may be found. This is a required setting.

port=n

This required setting gives the TCP port number the tracker will use.

trackerurl=url

This required setting is placed in every .torrent file, and gives the tracker's URL, so that BitTorrent clients can find it.

args=args

This optional setting gives any additional arguments to BitTorrent's tracker. ezt starts the tracker automatically, and provides the --allowed_dir, --port, and --dfile arguments to BitTorrent's tracker (--dfile's dump file will always be "tracker.dump" in the same torrentdir). Give any additional parameters in the args setting. Example:

args=--socket_timeout 5 --close_with_rst 1

See BitTorrent's documentation for the available tracker options.

Starting and stopping EZtorrent

The "ezt start" command starts EZtorrent as a background daemon process. ezt reads all defined torrent directories from configdir, updates the .torrent files according to the contents of the corresponding filedir, starts a BitTorrent tracker for each torrent directory, and starts a seeder BitTorrent client process for each .torrent client.

"ezt" by itself starts EZtorrent as a foreground process in the terminal. All messages from ezt will not be sent to syslog, but to the terminal. This is useful for diagnostic purposes.

NOTE:

On some systems ezt will not respond to the CTRL-C interrupt from the terminal. Use a different terminal window to find the ezt process, and send it a SIGINT or SIGTERM (ezt catches the signal and will forward the signal to all BitTorrent child processes it started).

"ezt start", or "ezt" has no effect if ezt is already running. ezt obtains a lock file in configdir, and terminates immediately if the lock file is already held by another ezt process for the same configdir. It's possible to have more than one ezt process running, by using the -c option to give a different configdir to each one (but there's really no good reason to do so, since ezt is perfectly capable of keeping the tabs on multiple torrent directories).

ezt will not become aware of any changes to the contents of all the torrent and file directories until it's restarted. "ezt restart" signals the existing, background ezt process. It checks everything, updates whatever needs to be updated, starts whatever new processes need to be started, and stop whatever processes are no longer needed. Finally, "ezt stop" terminates the existing ezt background daemon process, and all of its children processes.

NOTE:

It will take about two minutes for everything to settle down. ezt's initial attempt to start the seeders will probably fail. ezt starts the BitTorrent tracker with the "--allowed_dir" option. At least as of BitTorrent 4.0, its tracker scans for new .torrent files only once a minute. The tracker will refuse the connection attempt from the seeders of freshly-minted .torrent files, because the tracker hasn't refreshed its internal list of allowed .torrents yet.

ezt will log these errors. When a tracker or a seeder process fails, ezt automatically restarts it, after a moderate delay. It may take two or three attempts to start a new seeder. This is normal.

Optional .info files

An optional filename.info file may exist for every filename in filedir. Use any text editor to create this short configuration file. It's a small text configuration file; its initial contents will already be set by ezt. Manual adjustments may be made with any text editor. The following settings may appear in this configuration file. Each setting appears on a separate line:

args=arguments

This setting gives any additional parameters for creating a .torrent for the corresponding file. ezt takes care of the "--target" parameter, and this setting gives any additional parameters. See BitTorrent's documentation for a list of available parameters and options. Example:

args=--piece_size_pow2 16

seeder_args=arguments

This setting gives any additional parameters for the seeder process (btdownloadheadless.py). ezt supplies the torrent's name and the file's name (the --save_as parameter). See BitTorrent's documentation for a list of available parameters and options. Example:

seeder_args=--max_upload_rate 50 --snub_time 15