After installation, a new binary named boottorrent should be available in your console. This program is your entry point and the way to interact with the system.

You can verify the installation by checking for the installed version inside your console.

$ boottorrent version
BootTorrent 0.1.0

Please make sure that you’ve activated the virtualenv and/or Python version where you’ve installed BootTorrent.

Available commands

  • init
    Initializes a new BootTorrent project.
    Check the Quick start guide for instructions on how to work with BootTorrent.
  • start
    Starts the BootTorrent process.
  • version
    Show the current installed version.

Initializing a BootTorrent env

Let’s create a directory (a dedicated env for BootTorrent) for keeping all the required files together. BootTorrent can set you up with a basic configuration with sane values for most variables.

For example to create a new env with the name test, execute:

$ boottorrent init test

This should create a new folder named test with the following structure:

├── Boottorrent.yaml
└── oss

Now, your environment is ready. Consider updating the Boottorrent.yaml files according to your hardware/software setup. Documentation for various parameters is included further in this document and inside the env.

Configuring BootTorrent

The Boottorrent.yaml file present in an environment is used to configure the internal working of BootTorrent. Available sections and parameters are as follows:

Section: boottorrent

This section stores configurations parameters that are related to the working of core system.

  • version
    type: int, required
    Handle backward/forward compatibility.
  • timeout
    type: int, default 30
    In case of multiple OSs, BootTorrent waits this long (seconds) for user input before booting default OS.
    If this value is 0, then the default OS will be started as soon as possible.
    If this value is negative, then the timer is disabled and BootTorrent will wait forever for user input.
  • default_os
    type: string, required if timeout is set
    The default choice in case of no input from user.
    Must be the name of a folder present in oss/ directory.
  • seed_time
    type: int, default 30, required
    BootTorrent seeds downloaded OS for at least this long (seconds) before loading.
    Ideal value: (image size / client interface speed) + BootTorrent boot time on client.
    If this value is 0 or negative, BootTorrent will load the OS as soon as possible.
  • host_ip
    type: string, required
    IPv4 of the host as visible to the clients.

Section: dnsmasq

Dnsmasq is used to provide a DHCP server and a TFTP server for the purpose of network boot to the clients. The parameters in this sections have one-to-one correlation with those of Dnsmasq. When in doubt, please visit it’s official documentation.

  • enable_dhcp
    type: boolean, required
    Enable the build-in DHCP server
  • user
    type: string
    Switch to this user when dropping root privileges.
  • interface
    type: string, required, default eth0
    Interface on which the DHCP server should run.
  • bind_interfaces
    type: boolean, default: true
    Useful when the interface can go up/down or change addresses during runtime.
  • dhcp_range
    type: string, default: “,,12h”
    Range of IPs the DHCP server will provide with the lease time for each IP.
  • enable_tftp
    type: boolean, default: true
    Enable build-in TFTP server.

Section: opentracker

Opentracker is a BitTorrent peer tracker that is designed to be fast and low on resource usage. It is used to accelerate peer/seed discovery in the network. Enabling Opentracker requires that you set host_ip field as well.

  • enable
    type: boolean, default: true
    Used to enable/disable the tracker
  • port
    type: int, required if Opentracker is enabled, default: 10001
    Port on which to run the tracker.

Section: aria2

Aria2 is used on client side to download files via torrents.

  • bt_enable_lpd
    type: boolean, required, default: false
    Enable LPD on clients.
  • enable_peer_exchange
    type: boolean, required, default: true
    Enable Peer Exchange (PEX) protocol. Can improve download speeds if only LPD is enabled.
  • console_log_level
    type: string, required
    valid values: debug, info, notice, warn or error
    Can be used to configure Aria2’s log level on the client.

Adding Operating Systems

Use the oss/ directory to store the files of the operating systems in their own sub-directories. Please add an additional config.yaml with relevant fields to all the subfolders. The fields allowed in the config.yaml file include:

Common fields

  • dispname
    type: string, required
    The friendly name to display for the OS.
  • method
    type: string, required
    The method via which the OS is to be loaded.
    Valid values include: [kexec bin bin-qemu-x86_64]

Fields for Linux/Kexec

  • kernel
    type: string, required
    The name of the kernel file.
  • initrd
    type: string, required
    The name of the initrd file.
  • cmdline
    type: cmdline
    Kernel cmdline to append to the kernel.

Fields for Qemu-x86_64

  • args
    type: string, required
    This string is directly passed to the Qemu binary as an argument and can include all the parameters accepted by Qemu.

Fields for bin

  • bin
    type: string, required
    This is the path to binary relative to the base directory of the OS
  • binargs
    type: string
    These are the CLI arguments passed to the binary.

Once you add an OS here, please also update your Boottorrent.yaml file accordingly.

Example: Adding a Linux based OS

With a compiled kernel (vmlinuz) and corresponding initrd (initramfs.img), the process is:

  1. Create a new directory.
  2. Drop OS related files into the directory.
  3. Add a file config.yaml with content (modify according to your needs):
dispname: TestOS # Friendly name to display
method: kexec
kernel: vmlinuz
initrd: initramfs.img
cmdline: break # cmdline for the new kernel

Example: Adding an OS that runs on Qemu

If you want to use a floppy disk image (test.img) with Qemu, the process is:

  1. Create a new directory.
  2. Drop OS related files into the directory.
  3. Add a file config.yaml with content (modify according to your needs):
dispname: TestOnQemu # Friendly name to display
method: bin-qemu-x86_64
args: "-fda test.img" # Arguments to pass to Qemu

Example: Adding an ISO file to BootTorrent

If you want to boot a guest OS from an ISO file (disc.iso), the process is:

  1. Create a new directory.
  2. Drop the ISO file into the directory.
  3. Add a file config.yaml with content (modify according to your needs):
dispname: ISOFile # Friendly name to display
method: bin-qemu-x86_64
args: "-cdrom disc.iso" # Arguments to pass to Qemu

Hint: You might want to enable KVM (“-accel kvm”) if you’re using Qemu as this will give you better performance. You can read full Qemu documentation for more information.

Example: Adding a binary to launch

You may want to do some housekeeping in the base environment before launching the OS. BootTorrent allows you to run a binary to take care of that on the nodes. To add a binary (named hello), the process is:

  1. Create a new directory.
  2. Drop the files and binary into the directory.
  3. Add a file config.yaml with content (modify according to your needs):
dispname: TestBin # Friendly name to display
method: bin
bin: hello
binargs: "<binary args>"

Start BootTorrent


  • Please be sure that other DHCP servers and/or TFTP servers are not running on your computer/network as they may conflict with BootTorrent.
  • Please make sure that the chosen ports are not being used by other applications.

BootTorrent requires superuser access to bind to DHCP+TFTP ports (because they are low-ports). You can provide proper permission by either of two methods:

With elevated shell

You can start a root shell (i.e sudo bash) and activate Python/Virtualenv in that shell.

Then, execute these commands on your computer:

# whoami
# source <virtualenv>/bin/activate # if you're using virtualenv
# boottorrent start

With setcap

setcap can be used to persistently set correct permissions to the dnsmasq binary like this:

$ sudo setcap CAP_NET_BIND_SERVICE,CAP_NET_RAW,CAP_NET_ADMIN=+ep /usr/bin/dnsmasq

Then, you can activate Python/Virtualenv in a console and execute these commands:

$ whoami
$ source <virtualenv>/bin/activate # if you're using virtualenv
$ boottorrent start

Note: You need not use sudo here as it will start the BootTorrent process inside another environment.

You can learn more details about the permissions on Capabilities man page.

Go ahead and try to network boot other machines. Look for an options with the names of added OSs and select your choice to start the booting process in clients.