Usage¶
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:
test
├── 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, requiredHandle backward/forward compatibility.
- timeout
- type: int, default 30In 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 setThe 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, requiredBootTorrent 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, requiredIPv4 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, requiredEnable the build-in DHCP server
- user
- type: stringSwitch to this user when dropping root privileges.
- interface
- type: string, required, default eth0Interface on which the DHCP server should run.
- bind_interfaces
- type: boolean, default: trueUseful when the interface can go up/down or change addresses during runtime.
- dhcp_range
- type: string, default: “192.168.1.50,192.168.1.150,12h”Range of IPs the DHCP server will provide with the lease time for each IP.
- enable_tftp
- type: boolean, default: trueEnable 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: trueUsed to enable/disable the tracker
- port
- type: int, required if Opentracker is enabled, default: 10001Port 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: falseEnable LPD on clients.
- enable_peer_exchange
- type: boolean, required, default: trueEnable Peer Exchange (PEX) protocol. Can improve download speeds if only LPD is enabled.
- console_log_level
- type: string, requiredvalid values: debug, info, notice, warn or errorCan 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, requiredThe friendly name to display for the OS.
- method
- type: string, requiredThe 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, requiredThe name of the kernel file.
- initrd
- type: string, requiredThe name of the initrd file.
- cmdline
- type: cmdlineKernel cmdline to append to the kernel.
Fields for Qemu-x86_64
- args
- type: string, requiredThis 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, requiredThis is the path to binary relative to the base directory of the OS
- binargs
- type: stringThese 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:
- Create a new directory.
- Drop OS related files into the directory.
- 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:
- Create a new directory.
- Drop OS related files into the directory.
- 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:
- Create a new directory.
- Drop the ISO file into the directory.
- 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:
- Create a new directory.
- Drop the files and binary into the directory.
- 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¶
Note:
- 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
root
# 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
user
$ 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.