Technical Notes — aria2 1.37.0 documentation (2024)

  • Technical Notes
  • View page source

This document describes additional technical information of aria2. Theexpected audience is developers.

Control File (*.aria2) Format

The control file uses a binary format to store progress information ofa download. Here is the diagram for each field:

 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1+---+-------+-------+-------------------------------------------+|VER| EXT |INFO |INFO HASH ... ||(2)| (4) |HASH | (INFO HASH LENGTH) || | |LENGTH | || | | (4) | |+---+---+---+-------+---+---------------+-------+---------------+|PIECE |TOTAL LENGTH |UPLOAD LENGTH |BIT- |BITFIELD ... ||LENGTH | (8) | (8) |FIELD | (BITFIELD || (4) | | |LENGTH | LENGTH) || | | | (4) | |+-------+-------+-------+-------+-------+-------+---------------+|NUM |INDEX |LENGTH |PIECE |PIECE BITFIELD ... ||IN- | (4) | (4) |BIT- | (PIECE BITFIELD LENGTH) ||FLIGHT | | |FIELD | ||PIECE | | |LENGTH | || (4) | | | (4) | |+-------+-------+-------+-------+-------------------------------+ ^ ^ | | +-------------------------------------------------------+ Repeated in (NUM IN-FLIGHT) PIECE times
VER (VERSION): 2 bytes

Should be either version 0(0x0000) or version 1(0x0001). Inversion 1, all multi-byte integers are saved in network byteorder(big endian). In version 0, all multi-byte integers are savedin host byte order. aria2 1.4.1 can read both versions and onlywrites a control file in version 1 format. version 0 support willbe disappear in the future version.

EXT (EXTENSION): 4 bytes

If LSB is 1(i.e. EXT[3]&1 == 1), aria2 checks whether the savedInfoHash and current downloading one are the same. If they are notthe same, an exception is thrown. This is called "infoHashCheck"extension.

INFO HASH LENGTH: 4 bytes

The length of InfoHash that is located after this field. If"infoHashCheck" extension is enabled, if this value is 0, then anexception is thrown. For http/ftp downloads, this value should be0.

INFO HASH: (INFO HASH LENGTH) bytes

BitTorrent InfoHash.

PIECE LENGTH: 4 bytes

The length of the piece.

TOTAL LENGTH: 8 bytes

The total length of the download.

UPLOAD LENGTH: 8 bytes

The uploaded length in this download.

BITFIELD LENGTH: 4 bytes

The length of bitfield.

BITFIELD: (BITFIELD LENGTH) bytes

This is the bitfield which represents current download progress.

NUM IN-FLIGHT PIECE: 4 bytes

The number of in-flight pieces. These piece is not marked'downloaded' in the bitfield, but it has at least one downloadedchunk.

The following 4 fields are repeated in (NUM IN-FLIGHT PIECE)times.

INDEX: 4 bytes

The index of the piece.

LENGTH: 4 bytes

The length of the piece.

PIECE BITFIELD LENGTH: 4 bytes

The length of bitfield of this piece.

PIECE BITFIELD: (PIECE BITFIELD LENGTH) bytes

The bitfield of this piece. The each bit represents 16KiB chunk.

DHT routing table file format

aria2 saves IPv4 DHT routing table in${XDG_CACHE_HOME}/aria2/dht.dat and IPv6 DHT routing table in${XDG_CACHE_HOME}/aria2/dht6.dat by default unless${HOME}/.aria2/dht.dat and ${HOME}/.aria2/dht.dat are present.

dht.dat and dht6.dat files use same binary encoding and havefollowing fields. All multi byte integers are in network byteorder. RSV (RESERVED) fields are reserved for future use. For nowthey should be all zeros:

 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1+---+-+-----+---+---------------+---------------+---------------+|MGC|F| RSV |VER| MTIME | RSV |LOCAL NODE ID :|(2)|M| (3) |(2)| (8) | (8) | (20) :| |T| | | | | :+---+-+---+-----+-------+-------+-------+-------+---------------+:LOCAL NODE ID | RSV | NUM | RSV |: (continued) | (4) | NODE | (4) |: | | (4) | |+-+-------------+-------+-------+-+-----+-------+---------------+|P| RSV |COMPACT PEER INFO| RSV | <-+|L| (7) | (PLEN) | (24 - PLEN) | ||E| | | | ||N| | | | |+-+-------------+-----------------+-----+-------+---------------+ || NODE ID | RSV | || (20) | (4) | <-----------------++---------------------------------------+-------+ Repeated in (NUM NODE) times.
MGC (MAGIC): 2 bytes

It must be 0xa1 0xa2.

FMT (FORMAT ID): 1 byte

The format ID should be 0x02.

VER (VERSION): 2 bytes

The version number should be 0x00 0x03.

MTIME: 8 bytes

This is the time when aria2 saved the file. The value is the timesince the Epoch(1970/1/1 00:00:00) in 64 bits integer.

LOCALNODE ID: 20 bytes

Node ID of the client.

NUM NODE: 4 bytes

The number of nodes the routing table has. NUM NODE nodeinformation follows.

The data of NUM NODE node will follow. The node information arestored in the following fields. They are repeated in NUM NODEtimes.

PLEN (COMPACT PEER INFO LENGTH): 1 byte

The length of compact peer info. For IPv4 DHT, it must be 6. ForIPv6 DHT, it must be 18.

COMPACT PEER INFO: (PLEN) bytes

The address and port of peer in compact peer format.

NODE ID: 20 bytes

The node ID of this node.

Technical Notes — aria2 1.37.0 documentation (2024)
Top Articles
Latest Posts
Recommended Articles
Article information

Author: Nathanael Baumbach

Last Updated:

Views: 6175

Rating: 4.4 / 5 (75 voted)

Reviews: 90% of readers found this page helpful

Author information

Name: Nathanael Baumbach

Birthday: 1998-12-02

Address: Apt. 829 751 Glover View, West Orlando, IN 22436

Phone: +901025288581

Job: Internal IT Coordinator

Hobby: Gunsmithing, Motor sports, Flying, Skiing, Hooping, Lego building, Ice skating

Introduction: My name is Nathanael Baumbach, I am a fantastic, nice, victorious, brave, healthy, cute, glorious person who loves writing and wants to share my knowledge and understanding with you.