Adding a new entry to the QBittorrentBot configuration file involves several steps:
+
+
Clone the repository: git clone https://github.com/ch3p4ll3/QBittorrentBot.git
+
+
Navigate to the folder: src/configs
+
+
Modify the pydantic class:
+Identify the pydantic class where the new entry should be added.
+Add a new attribute to the class to represent the new entry.
+
+
Create a validation function (if necessary):
+If the new entry requires additional validation beyond the type provided by pydantic, create a validation function.
+The validation function should inspect the value of the new entry and check for any constraints or rules that need to be enforced.
+
+
Add the new entry to the config file:
+Open the configuration file (usually config.json).
+Add a new property to the configuration object for the new entry.
+Set the value of the new property to the desired initial value.
+
+
Update the convert_type_from_string function (if necessary):
+If the new entry type requires a custom conversion from a string representation, add the conversion function to the utils file.
+The function should take a string representation of the new entry type and return the corresponding data type.
+
+
Update the bot code (if necessary):
+If the new entry is being used by the bot code, update the relevant parts of the code to handle the new entry type and its values.
+
+
Build the docker image
+
+
Start the docker container
+
+
+
You can now use the bot with the new entry, have fun🥳
Adding a new client manager to QBittorrentBot involves creating a new class that implements the ClientManager interface. This interface defines the methods that the bot uses to interact with the client, such as adding, removing, pausing, and resuming torrents.
+
To do this you need to follow a couple of steps:
+
+
Clone the repository locally using the command: git clone https://github.com/ch3p4ll3/QBittorrentBot.git
+
Navigate to the folder src/client_manager
+
Create a new file for your client manager class. Name the file something like <client>_manager.py. For example, if you are writing a manager for utorrent the name will be utorrent_manager.py
+
Define your client manager class. The class should inherit from the ClientManager class and implement all of its methods. For example, the utorrent_manager.py file might look like this:
+
+
+
from typing import Union, List
+from .client_manager import ClientManager
+
+
+class UtorrentManager(ClientManager):
+ @classmethod
+ def add_magnet(cls, magnet_link: Union[str, List[str]], category: str = None) -> None:
+ # Implement your code to add a magnet to the utorrent client
+ pass
+
+ @classmethod
+ def add_torrent(cls, file_name: str, category: str = None) -> None:
+ # Implement your code to add a torrent to the utorrent client
+ pass
+...
+
+
+
Navigate to the src/configs/ folder and edit the enums.py file by adding to the ClientTypeEnum class an enum for your client. For example, if we wanted to add a manager for utorrent the class would become like this:
Return to the src/client_manager folder and edit the client_repo.py file by adding to the dictionary named repositories an entry associating the newly created enum with the new manager. Example:
Register your client manager in the config file. The config file is a JSON file that defines the configuration for the QBittorrentBot. You can add your new client manager to the client section of the config file. For example, the config file might look like this:
QBittorrentBot provides a user role management system to control access to different actions and functionalities within the bot. The system defines three roles: Reader, Manager, and Admin, each with increasing permissions and capabilities.
+
+
+ #
+ Reader
+
+
+
The Reader role grants basic access to view the list of active torrents and inspect the details of individual torrents. Users with the Reader role can view the torrent name, download speed, upload speed, progress, and file size. They can also view the category to which each torrent belongs.
+
+
+ #
+ Manager
+
+
+
The Manager role extends the Reader role with additional permissions, allowing users to perform actions beyond mere observation. Manager-level users can download new torrents by sending magnet links or torrent files to the bot. They can also add or edit categories to organize their torrents effectively. Additionally, Manager users can set torrent priorities, enabling them to manage the download order and prioritize specific torrents. Moreover, they can pause or resume ongoing downloads, providing flexibility in managing their torrent activity.
+
+
+ #
+ Admin
+
+
+
The Admin role, the most privileged, grants the user full control over the bot's functionalities. In addition to the capabilities of the Manager role, Admin users can remove torrents from their download lists, eliminating unwanted downloads. They can also remove categories, streamlining their torrent organization structure. And, as the highest-level role, Admin users have the authority to edit the bot's configuration files, modifying its settings and behavior.
+
This role management system ensures that users are granted access appropriate to their needs and responsibilities. Readers can observe and manage their torrent activity, Managers can perform more extensive actions, and Admins have full control over the bot's operation. This structure enhances security and prevents unauthorized users from modifying configuration files or deleting torrents.
QBittorrentBot is a Telegram bot that allows you to control your qBittorrent downloads from within the Telegram app. It can add torrents, manage your torrent list, and much more.
+
+
+ #
+ What are the benefits of using QBittorrentBot?
+
+
+
There are several benefits to using QBittorrentBot, including:
+
+
Convenience: You can control your torrents from anywhere, without having to open the qBittorrent app.
+
Efficiency: You can manage your torrents without switching between apps.
+
Organization: You can categorize your torrents for better organization and accessibility.
+
Docker Support: You can deploy and manage the bot seamlessly using Docker containers.
+
+
+
+ #
+ How do I add QBittorrentBot to my Telegram account?
+
+
+
Follow this guide to start using QBittorrentBot
+
+
+
+
+
+ Getting Started
+
+
+ ../getting_started/
+
+
+
+
+
+
+ #
+ How do I edit the configuration for the QBittorrentBot?
+
+
+
The QBittorrentBot configuration file is located at config.json. This file stores the bot's settings, such as the connection details for the qBittorrent client, the API IDs and hashes, and the list of authorized users. To edit the configuration file, you can open it in a text editor and make the necessary changes.
+
+
+ #
+ How do I check the status of my torrents?
+
+
+
You can check the status of your torrents by using the list torrents button. This command will display a list of all your active torrents, including their name, status, progress, and download/upload speed.
+
+
+ #
+ What is the difference between a magnet link and a torrent file?
+
+
+
A magnet link is a URI scheme that allows you to download a torrent without having to download the entire torrent file. A torrent file is a file that contains metadata about the torrent, such as the filename, file size, and number of pieces.
+
+
+ #
+ What are the different user roles available in QBittorrentBot?
+
+
+
QBittorrentBot supports three user roles: Reader, Manager, and Admin. Each role has different permissions, as follows:
+
+
Reader: Can view lists of active torrents and view individual torrent details.
+
Manager: Can perform all Reader actions, plus add/edit categories, set torrent priorities, and pause/resume downloads.
+
Admin: Can perform all Manager actions, plus remove torrents, remove categories, and edit configs.
+
+
+
+ #
+ How do I change the user role for a user?
+
+
+
You can change the user role for a user by editing the config.json file. Open the file and find the user's entry. Change the role field to the desired role (e.g., "reader", "manager", or "admin"). Save the file and restart the bot or, if you are an admin you can reload the configuration from the bot.
+
+
+ #
+ How do I install QBittorrentBot on my server?
+
+
+
You can install QBittorrentBot on your server using Docker. First, install Docker on your server. Then, create a Docker image from the QBittorrentBot Dockerfile. Finally, run the Docker image to start the bot.
+
+
+ #
+ How do I add a new manager to my QBittorrentBot?
+
+
+
Please follow this guide
+
+
+
+
+
+ Add new client manager
+
+
+ ../advanced/add_new_client_manager/
+
+
+
+
+
+
+ #
+ How do I add a new entry to the QBittorrentBot configuration file?
+
+
+
Please follow this guide
+
+
+
+
+
+ Add new entries in configuration file
+
+
+ ../advanced/add_entries_configuration/
+
+
+
+
+
+
+ #
+ How do I contribute to the development of QBittorrentBot?
+
+
+
QBittorrentBot is an open-source project. You can contribute to the development by reporting bugs, suggesting improvements, or submitting pull requests. The project's code is hosted on GitHub.
The configuration file serves as a central repository for all the necessary information that the QBittorrentBot needs to operate effectively. It defines the connection parameters, credentials, and user settings that the bot utilizes to interact with the qBittorrent server and Telegram API.
+
Below you can find an example of the configuration file:
Here's a brief overview of the configuration file and its key sections:
+
+
Clients Section: Establishes the connection details for the qBittorrent server, including the hostname, port number, username, and password. This enables the bot to interact with the qBittorrent server and manage torrents.
+
+
Telegram Section: Contains the bot token, API ID, and API hash, which are essential for authenticating the bot with the Telegram API. These credentials allow the bot to communicate with the Telegram server and receive user commands. Click here to find out how to retrive your API ID and API Hash
+
+
Users Section: Lists the authorized users of the QBittorrentBot, along with their Telegram user IDs, notification preferences, and user roles. This section defines the users who can interact with the bot, receive notifications, and manage torrents.
+
+
+
+
+ #
+ Client
+
+
+
This section defines the configuration for the qBittorrent client that the bot will be interacting with.
+
+
+
+
+
Name
+
Type
+
Value
+
+
+
+
+
type
+
ClientTypeEnum
+
The type of client.
+
+
+
host
+
IPvAnyAddress
+
The IP address of the qBittorrent server.
+
+
+
port
+
int
+
The port number of the qBittorrent server.
+
+
+
user
+
str
+
The username for the qBittorrent server.
+
+
+
password
+
str
+
The password for the qBittorrent server.
+
+
+
+
+
+
+ #
+ Telegram
+
+
+
This section defines the configuration for the Telegram bot that the QBittorrentBot will be communicating with.
+
+
+
+
+
Name
+
Type
+
Value
+
+
+
+
+
bot_token
+
str
+
The bot token for the QBittorrentBot. This is a unique identifier that is used to authenticate the bot with the Telegram API.
+
+
+
api_id
+
int
+
The API ID for the QBittorrentBot. This is a unique identifier that is used to identify the bot to the Telegram API.
+
+
+
api_hash
+
str
+
The API hash for the QBittorrentBot. This is a string of characters that is used to verify the authenticity of the bot's requests to the Telegram API.
+
+
+
+
+
+
+ #
+ Users
+
+
+
This section defines the list of users who are authorized to use the QBittorrentBot. Each user is defined by their Telegram user ID, whether or not they should be notified about completed torrents, and their role.
+
+
+
+
+
Name
+
Type
+
Value
+
+
+
+
+
user_id
+
int
+
The Telegram user ID of the user. This is a unique identifier that is used to identify the user to the Telegram API.
+
+
+
notify
+
bool
+
Whether or not the user should be notified about new torrents.
+
+
+
role
+
UserRolesEnum
+
The role of the user.
+
+
+
+
+
+
+ #
+ Enums
+
+
+
+
+ #
+ ClientTypeEnum
+
+
+
+
+
+
+
Name
+
Type
+
Value(to be used in json)
+
+
+
+
+
QBittorrent
+
str
+
qbittorrent
+
+
+
+
+
+
+ #
+ UserRolesEnum
+
+
+
+
+
+
+
Name
+
Type
+
Value(to be used in json)
+
Remarks
+
+
+
+
+
Reader
+
str
+
reader
+
Can perform only reading operations(view torrents)
+
+
+
Manager
+
str
+
manager
+
Can perform only managing operations(view torrents + can download files + can add/edit categories + set torrent priority + can stop/start downloads)
+
+
+
Administrator
+
str
+
administrator
+
Can perform all operations (Manager + remove torrent + remove category + edit configs)
+
+
+
+
+
+
+ #
+ Other types
+
+
+
+
+ #
+ IPvAnyAddress
+
+
+
This type allows either an IPv4Address or an IPv6Address
In order to start using the bot, you must first create a folder where the bot will fish for settings and where it will save logs
+
For example: let's create a folder called QBittorrentBot in the home of the user user. The path to the folder will then be /home/user/docker/QBittorrentBot.
+
Before starting the bot you need to place the configuration file in this folder. You can rename the config.json.template file to config.json and change the parameters as desired. Go here to read more about the configuration file.
+
Once that is done you can start the bot using docker, you can use either docker or docker compose.
+
+
+Docker
+
Open your terminal and execute the following command to start the bot container:
+
docker run -d -v /home/user/docker/QBittorrentBot:/app/config:rw --name qbittorrent-bot ch3p4ll3/qbittorrent-bot:latest
+
+
+Docker compose
+
Create a file named docker-compose.yml inside a directory with the following content:
Much has changed with the new version, especially the management of the configuration file. Some fields have been added, while others have changed names, so first check that you have all the fields in the json with the correct name.
+
+
+ #
+ New fields
+
+
+
Two new fields were introduced: type and role in the client and users sections, respectively.
+
The type field determines the type of torrent client you want to use(currently only qbittorrent is supported, so its value must be qbittorrent)
+
The role field, on the other hand, determines the role of a particular user. Currently there are 3 roles:
There are 2 changes to the field names, the first is the name of the qbittorrent section which has been renamed to client. While the second is the ip field inside che client section which has been renamed to host
QBittorrentBot is a Telegram bot that allows you to control your qBittorrent downloads from your Telegram account.
+
This means that you can add, remove, pause, resume, and delete torrents, as well as view a list of your active downloads, all without having to open the qBittorrent application.
+
+
+
+
+
+
+
+
Warning
+
A lot has changed from version 2, if you have any errors, please take a look here.
+
+
+
+
+
+ #
+ Features
+
+
+
Here are some of the things you can do with QBittorrentBot:
+
+
Add torrents: You can add torrents to your qBittorrent download queue by sending magnet links or torrent files to the bot.
+
List active downloads: You can get a list of your current downloads, including their progress, status, and estimated completion time.
+
Pause/Resume downloads: You can pause or resume ongoing downloads with a single command.
+
Delete torrents: You can remove unwanted downloads from your queue with a single command.
+
Add/Remove/Edit categories: You can categorize your torrents for better organization and accessibility.
+
Edit settings: You can edit user and torrent client settings directly from the bot
+
Check client connection: You can check the connection with the client directly from the bot
+
+
+
+ #
+ Benefits
+
+
+
Here are some of the benefits of using QBittorrentBot:
+
+
Security: You can add multiple users who have access to the bot and each of them can have different permissions(reader, manager, administrator)
+
Convenience: You can manage your torrents from anywhere, as long as you have your Telegram app with you.
+
Efficiency: You don't have to switch between apps to control your torrents.
+
Organization: You can categorize your torrents for better organization and accessibility.
+
Docker support: You can deploy and manage the bot seamlessly using Docker for enhanced isolation, security, and flexibility.
+
+
QBittorrentBot is an open-source project, so you can contribute to its development if you want to make it even more powerful and user-friendly.
+ 
+ 
+ 
+ 
+