diff --git a/INSTALLATION.md b/INSTALLATION.md index 1ffac7b1..ff1d0448 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,651 +1,8 @@ -# NZBGet installation +## Platforms -This is a short documentation. For more information please -visit NZBGet home page at - https://nzbget.com +Articles below provide detailed information on manual compilation of NZBGet for specific platforms: -Contents --------- -1. About NZBGet -2. Supported OS -3. Prerequisites on POSIX -4. Installation on POSIX -5. Compiling on Windows -6. Configuration -7. Usage -8. Authors -9. Copyright -10. Contact - - -## 1. About NZBGet - -NZBGet is a binary newsgrabber, which downloads files from usenet -based on information given in nzb-files. NZBGet can be used in -standalone and in server/client modes. In standalone mode you -pass a nzb-file as parameter in command-line, NZBGet downloads -listed files and then exits. - -In server/client mode NZBGet runs as server in background. -Then you use client to send requests to server. The sample requests -are: download nzb-file, list files in queue, etc. - -There is also a built-in web-interface. The server has RPC-support -and can be controlled from third party applications too. - -Standalone-tool, server and client are all contained in only one -executable file "nzbget". The mode in which the program works -depends on command-line parameters passed to the program. - -## 2. Supported OS - -NZBGet is written in C++ and works on Windows, OS X, Linux and -most POSIX-conform OS'es. - -Clients and servers running on different OS'es may communicate with -each other. For example, you can use NZBGet as client on Windows to -control your NZBGet-server running on Linux. - -The download-section of NZBGet web-site provides binary files -for Windows, OS X and Linux. For most POSIX-systems you need to compile -the program yourself. - -If you have downloaded binaries you can just jump to section -"Configuration". - -## 3. Prerequisites on POSIX - -NZBGet is developed on a linux-system, but it runs on other -POSIX platforms. - -To build NZBGet you will need: - -For configuring and building: - - [CMake](https://cmake.org/) - - [GCC](https://gcc.gnu.org/) - - or - - [CLang](https://clang.llvm.org/) - -Libraries: - - [libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home) - - [Boost.JSON](https://www.boost.org/doc/libs/1_84_0/libs/json/doc/html/index.html) -> If you face issues with Boost.JSON on your system, you can skip it - CMake will take care of it. - -And the following libraries are optional: - - For curses-output-mode (enabled by default): - - [ncurses](https://invisible-island.net/ncurses) - - For encrypted connections (TLS/SSL): - - [OpenSSL](https://www.openssl.org) - - or - - [GnuTLS](https://gnutls.org) - - For gzip support in web-server and web-client (enabled by default): - - [zlib](https://www.zlib.net/) - - For tests: - - [Boost.Test](https://www.boost.org/doc/libs/1_84_0/libs/test/doc/html/index.html) - - For static code analysis: - - [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/) - -Please note that you also -need the developer packages for these libraries too, they package names -have often suffix "dev" or "devel". On other systems you may need to -download the libraries at the given URLs and compile them (see hints below). - -### Debian: -``` - apt install cmake build-essential libncurses-dev libssl-dev libxml2-dev zlib1g-dev libboost-json1.81-dev -``` - - For tests: -``` - apt install libboost-test1.81-dev -``` - - For static code analysis: -``` - apt install clang-tidy -``` -### FreeBSD: -``` - pkg install cmake ncurses openssl libxml2 zlib boost-libs -``` -### macOS: -``` - xcode-select --install - brew install cmake ncurses openssl libxml2 zlib boost -``` - -## 4. Installation on POSIX - -Installation from the source distribution archive (nzbget-VERSION.tar.gz): - - - Untar the nzbget-source: -``` - tar -zxf nzbget-VERSION.tar.gz -``` - - Change into nzbget-directory: -``` - cd nzbget-VERSION -``` - - Configure: -``` - mkdir build - cd build - cmake .. -``` - - In a case you don't have root access or want to install the program - in your home directory use the configure parameter -DCMAKE_INSTALL_PREFIX: -``` - cmake .. -DCMAKE_INSTALL_PREFIX=~/usr -``` - - Build, specifying (-j 8) how many CPU cores to use to speed up compilation: -``` - cmake --build . -j 8 -``` - - Install: -``` - cmake --install . -``` - - Uninstall: -``` - cmake --build . --target uninstall -``` - -### Configure-options ---------------------- -You may run configure with additional arguments: - - Enable tests: -``` - cmake .. -DENABLE_TESTS=ON -``` - - Enable Clang-Tidy static code analizer: -``` - cmake .. -DENABLE_CLANG_TIDY=ON -``` - - Disable ncurses. Use this option if you can not use ncurses. -``` - cmake .. -DDISABLE_CURSES=ON -``` - - Disable parcheck. Use this option if you have troubles when compiling par2-module. -``` - cmake .. -DDISABLE_PARCHECK=ON -``` - - Use GnuTLS. Use this option if you want to use GnuTLS instead of OpenSSL. -``` - cmake .. -DUSE_GNUTLS=ON -``` - - Disable TLS. Use this option if you can not neither OpenSSL nor GnuTLS. -``` - cmake .. -DDISABLE_TLS=ON -``` - - Disable gzip. Use this option if you can not use zlib. -``` - cmake .. -DDISABLE_GZIP=ON -``` - - Disable sigchld-handler. The disabling may be neccessary on 32-Bit BSD. -``` - cmake .. -DDISABLE_SIGCHLD_HANDLER=ON -``` - - For debug build. -``` - cmake .. -DCMAKE_BUILD_TYPE=Debug -``` - - To get a static binary, -``` - cmake .. -DENABLE_STATIC=ON -``` - `LIBS` and `INCLUDES` env variables can be useful for static linking, since CMake looks for shared libraries by default -``` - export LIBS="-lncurses -ltinfo -lboost_json -lxml2 -lz -lm -lssl -lcrypto -Wl,--whole-archive -lpthread -Wl,--no-whole-archive" - export INCLUDES="/usr/include/;/usr/include/libxml2/" - cmake .. -DENABLE_STATIC=ON -``` -## Building using autotools (deprecated) - - - configure it via -``` - autoreconf --install - ./configure -``` - (maybe you have to tell configure, where to find some libraries then is your friend! -``` - ./configure --help -``` - also see "Configure-options" later) - - - in a case you don't have root access or want to install the program - in your home directory use the configure parameter --prefix, e. g.: -``` - ./configure --prefix ~/usr -``` - - compile it via -``` - make -``` - - to install system wide become root via: -``` - su -``` - - install it via: -``` - make install -``` - - install configuration files into /etc via: -``` - make install-conf -``` - (you can skip this step if you intend to store configuration - files in a non-standard location) - -### Configure-options ---------------------- -You may run configure with additional arguments: - - --disable-curses - to make without curses-support. Use this option - if you can not use curses/ncurses. - - --disable-parcheck - to make without parcheck-support. Use this option - if you have troubles when compiling par2-module. - - --with-tlslib=(OpenSSL, GnuTLS) - to select which TLS/SSL library - should be used for encrypted server connections. - - --disable-tls - to make without TLS/SSL support. Use this option if - you can not neither OpenSSL nor GnuTLS. - - --disable-gzip - to make without gzip support. Use this option - if you can not use zlib. - - --enable-debug - to build in debug-mode, if you want to see and log - debug-messages. - -### Optional package: par-check -------------------------------- -NZBGet can check and repair downloaded files for you. For this purpose -it uses library par2. - -For your convenience the source code of libpar2 is integrated into -NZBGet’s source tree and is compiled automatically when you make NZBGet. - -In a case errors occur during this process the inclusion of par2-module -can be disabled using configure option "--disable-parcheck": -``` - ./configure --disable-parcheck -``` - -### Optional package: curses ----------------------------- -For curses-outputmode you need ncurses or curses on your system. -If you do not have one of them you can download and compile ncurses yourself. -Following configure-parameters may be useful: - - --with-libcurses-includes=/path/to/curses/includes - --with-libcurses-libraries=/path/to/curses/libraries - -If you are not able to use curses or ncurses or do not want them you can -make the program without support for curses using option "--disable-curses": -``` - ./configure --disable-curses -``` - -### Optional package: TLS -------------------------- -To enable encrypted server connections (TLS/SSL) you need to build the program -with TLS/SSL support. NZBGet can use two libraries: OpenSSL or GnuTLS. -Configure-script checks which library is installed and use it. If both are -available it gives the precedence to OpenSSL. You may override that with -the option --with-tlslib=(OpenSSL, GnuTLS). For example to build with GnuTLS: -``` - ./configure --with-tlslib= GnuTLS -``` - -Following configure-parameters may be useful: - - --with-libtls-includess=/path/to/gnutls/includes - --with-libtls-libraries=/path/to/gnutls/libraries - - --with-openssl-includess=/path/to/openssl/includes - --with-openssl-libraries=/path/to/openssl/libraries - -If none of these libraries is available you can make the program without -TLS/SSL support using option "--disable-tls": - - ./configure --disable-tls - -## 5. Compiling on Windows - -For configuring and building: - - [CMake](https://cmake.org/) - - [MS C++ Build tools](https://visualstudio.microsoft.com/downloads/?q=build+tools) - -To compile the program with TLS/SSL support you need OpenSSL: - - [OpenSSL](https://www.openssl.org) - -Also required are: - - [Zlib](https://gnuwin32.sourceforge.net/packages/zlib.htm) - - [libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home) - - [Boost.JSON](https://www.boost.org/doc/libs/1_84_0/libs/json/doc/html/index.html) - - [Boost.Optional](https://www.boost.org/doc/libs/1_84_0/libs/optional/doc/html/index.html) -For tests: - - [Boost.Test](https://www.boost.org/doc/libs/1_84_0/libs/test/doc/html/index.html) - -We recommend using [vcpkg](https://vcpkg.io/) to install dependencies: - -``` - vcpkg install openssl:-windows-static - vcpkg install libxml2:-windows-static - vcpkg install zlib:-windows-static - vcpkg install boost-json:-windows-static - vcpkg install boost-optional:-windows-static -``` - - For tests: -``` - vcpkg install boost-test:-windows-static -``` - - Configure: -``` - mkdir build - cd build - cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -A x64 -``` - - For Win32: -``` - cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x86-windows-static -A Win32 -``` - - For debug build: -``` - cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_BUILD_TYPE=Debug -``` - - If Debug: -``` - cmake --build . --config Debug -``` - -You may run configure with additional arguments: - - Enable tests: -``` - cmake .. -DENABLE_TESTS=ON -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -``` - - Disable TLS. Use this option if you can not neither OpenSSL nor GnuTLS. -``` - cmake .. -DDISABLE_TLS=ON -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -``` - -## 6. Configuration - -NZBGet needs a configuration file. - -An example configuration file is provided in "nzbget.conf", which -is installed into "/share/nzbget" (where depends on -system configuration and configure options - typically "/usr/local", -"/usr" or "/opt"). The installer adjusts the file according to your -system paths. If you have performed the installation step -"make install-conf" this file is already copied to "/etc" and -NZBGet finds it automatically. If you install the program manually -from a binary archive you have to copy the file from "/share/nzbget" -to one of the locations listed below. - -Open the file in a text editor and modify it accodring to your needs. - -You need to set at least the option "MAINDIR" and one news server in -configuration file. The file has comments on how to use each option. - -The program looks for configuration file in following standard -locations (in this order): - -On POSIX systems: - /nzbget.conf - ~/.nzbget - /etc/nzbget.conf - /usr/etc/nzbget.conf - /usr/local/etc/nzbget.conf - /opt/etc/nzbget.conf - -On Windows: - \nzbget.conf - -If you put the configuration file in other place, you can use command- -line switch "-c " to point the program to correct location. - -In special cases you can run program without configuration file using -switch "-n". You need to use switch "-o" to pass required configuration -options via command-line. - -## 7. Usage - -NZBGet can be used in either standalone mode which downloads a single file -or as a server which is able to queue up numerous download requests. - -TIP for Windows users: NZBGet is controlled via various command line -parameters. For easier using there is a simple shell script included -in "nzbget-shell.bat". Start this script from Windows Explorer and you will -be running a command shell with PATH adjusted to find NZBGet executable. -Then you can type all commands without full path to nzbget.exe. - -### Standalone mode: --------------------- - -nzbget - -### Server mode: ----------------- - -First start the nzbget-server: - - - in console mode: - - nzbget -s - - - or in daemon mode (POSIX only): - - nzbget -D - - - or as a service (Windowx only, firstly install the service with command - "nzbget -install"): - - net start NZBGet - -To stop server use: - - nzbget -Q - -TIP for POSIX users: with included script "nzbgetd" you can use standard -commands to control daemon: - - nzbgetd start - nzbgetd stop - etc. - -When NZBGet is started in console server mode it displays a message that -it is ready to receive download requests. In daemon mode it doesn't print any -messages to console since it runs in background. - -When the server is running it is possible to queue up downloads. This can be -done either in terminal with "nzbget -A " or by uploading -a nzb-file into server's monitor-directory (/nzb by default). - -To check the status of server start client and connect it to server: - - nzbget -C - -The client have three different (display) outputmodes, which you can select -in configuration file (on client computer) or in command line. Try them: - - nzbget -o outputmode=log -C - - nzbget -o outputmode=color -C - - nzbget -o outputmode=curses -C - -To list files in server's queue: - - nzbget -L - -It prints something like: - - [1] nzbname\filename1.rar (50.00 MB) - [2] nzbname\filename1.r01 (50.00 MB) - [3] another-nzb\filename3.r01 (100.00 MB) - [4] another-nzb\filename3.r02 (100.00 MB) - -This is the list of individual files listed within nzb-file. To print -the list of nzb-files (without content) add G-modifier to the list command: - - [1] nzbname (4.56 GB) - [2] another-nzb (4.20 GB) - -The numbers in square braces are ID's of files or groups in queue. -They can be used in edit-command. For example to move file with -ID 2 to the top of queue: - - nzbget -E T 2 - -or to pause files with IDs from 10 to 20: - - nzbget -E P 10-20 - -or to delete files from queue: - - nzbget -E D 3 10-15 20-21 16 - -The edit-command has also a group-mode which affects all files from the -same nzb-file. You need to pass an ID of the group. For example to delete -the whole group 1: - - nzbget -E G D 1 - -The switch "o" is useful to override options in configuration files. -For example: - - nzbget -o reloadqueue=no -o dupecheck=no -o parcheck=yes -s - -or: - - nzbget -o createlog=no -C - -### Running client & server on seperate machines: -------------------------------------------------- - -Since nzbget communicates via TCP/IP it's possible to have a server running on -one computer and adding downloads via a client on another computer. - -Do this by setting the "ControlIP" option in the nzbget.conf file to point to the -IP of the server (default is localhost which means client and server runs on -same computer) - -### Security warning --------------------- - -NZBGet communicates via unsecured socket connections. This makes it vulnerable. -Although server checks the password passed by client, this password is still -transmitted in unsecured way. For this reason it is highly recommended -to configure your Firewall to not expose the port used by NZBGet to WAN. - -If you need to control server from WAN it is better to connect to server's -terminal via SSH (POSIX) or remote desktop (Windows) and then run -nzbget-client-commands in this terminal. - -### Post processing scripts ---------------------------- - -After the download of nzb-file is completed nzbget can call post-processing -scripts, defined in configuration file. - -Example post-processing scripts are provided in directory "scripts". - -To use the scripts copy them into your local directory and set options -, and . - -For information on writing your own post-processing scripts please -visit NZBGet web site. - -### Web-interface ------------------ - -NZBGet has a built-in web-server providing the access to the program -functions via web-interface. - -To activate web-interface set the option "WebDir" to the path with -web-interface files. If you install using "make install-conf" as -described above the option is set automatically. If you install using -binary files you should check if the option is set correctly. - -To access web-interface from your web-browser use the server address -and port defined in NZBGet configuration file in options "ControlIP" and -"ControlPort". For example: - - http://localhost:6789/ - -For login credentials type username and the password defined by -options "ControlUsername" (default "nzbget") and "ControlPassword" -(default "tegbzn6789"). - -In a case your browser forget credentials, to prevent typing them each -time, there is a workaround - use URL in the form: - - http://localhost:6789/username:password/ - -Please note, that in this case the password is saved in a bookmark or in -browser history in plain text and is easy to find by persons having -access to your computer. - -## 8. Authors - -NZBGet is developed and maintained by Andrey Prygunkov -(hugbug@users.sourceforge.net). - -The original project was initially created by Sven Henkel -(sidddy@users.sourceforge.net) in 2004 and later developed by -Bo Cordes Petersen (placebodk@users.sourceforge.net) until 2005. -In 2007 the abandoned project was overtaken by Andrey Prygunkov. -Since then the program has been completely rewritten. - -NZBGet distribution archive includes additional components -written by other authors: - -Par2: - Peter Brian Clements - -Par2 library API: - Francois Lesueur - -jQuery: - John Resig - The Dojo Foundation - -Bootstrap: - Twitter, Inc - -Raphaël: - Dmitry Baranovskiy - Sencha Labs - -Elycharts: - Void Labs s.n.c. - -iconSweets: - Yummygum - -Boost: - Boost organization and wider Boost community - - -## 9. Copyright - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -The complete content of license is provided in file COPYING. - -Additional exemption: compiling, linking, and/or using OpenSSL is allowed. - -## 10. Contact - -If you encounter any problem, feel free to contact us - https://nzbget.com/contact/ + - [POSIX](docs/POSIX.md) + - [Windows](docs/WINDOWS.md) + - [Synology](synology/build-info.md) + - [QNAP](qnap/build-info.md) diff --git a/README.md b/README.md index 1e3f0037..990b6103 100644 --- a/README.md +++ b/README.md @@ -60,13 +60,18 @@ QNAP packages are available as native packages and buildroot packages. [QNAP rea [General instructions](INSTALLATION.md) -[Linux](linux/build-info.md) [macOS](osx/build-info.md) [Synology](synology/build-info.md) [QNAP](qnap/build-info.md) +## Extensions + - [V1 (NZBGet v22 and below)](docs/extensions/EXTENSIONS_LEGACY.md) + - [V2 (NZBGet v23 and above)](docs/extensions/EXTENSIONS.md) + +## Brief introduction on how to use NZBGet + - [How to use](docs/HOW_TO_USE.md) ## Contribution Contributions are very welcome - not only from developers, but from our users too - please don't hesitate to participate in [discussions](https://github.com/nzbgetcom/nzbget/discussions) or [create a new discussion](https://github.com/nzbgetcom/nzbget/discussions/new/choose) -For more information - see [Contributing](CONTRIBUTING.md). +For more information - see [Contributing](docs/CONTRIBUTING.md). ## Donate diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md diff --git a/docs/HOW_TO_USE.md b/docs/HOW_TO_USE.md new file mode 100644 index 00000000..e4d4d9b8 --- /dev/null +++ b/docs/HOW_TO_USE.md @@ -0,0 +1,208 @@ +## Configuration + +NZBGet needs a configuration file. + +An example configuration file is provided in "nzbget.conf", which +is installed into "``/share/nzbget" (where `` depends on +system configuration and configure options - typically "/usr/local", +"/usr" or "/opt"). The installer adjusts the file according to your +system paths. If you have performed the installation step +"make install-conf" this file is already copied to "``/etc" and +NZBGet finds it automatically. If you install the program manually +from a binary archive you have to copy the file from "``/share/nzbget" +to one of the locations listed below. + +Open the file in a text editor and modify it accodring to your needs. + +You need to set at least the option "MAINDIR" and one news server in +configuration file. The file has comments on how to use each option. + +The program looks for configuration file in following standard +locations (in this order): + +On POSIX systems: +``` +/nzbget.conf +~/.nzbget +/etc/nzbget.conf +/usr/etc/nzbget.conf +/usr/local/etc/nzbget.conf +/opt/etc/nzbget.conf +~/usr/etc/nzbget.conf +``` + +On Windows: +``` +\nzbget.conf +``` + +If you put the configuration file in other place, you can use command- +line switch "-c ``" to point the program to correct location. + +In special cases you can run program without configuration file using +switch "-n". You need to use switch "-o" to pass required configuration +options via command-line. + +## Usage + +NZBGet can be used in either standalone mode which downloads a single file +or as a server which is able to queue up numerous download requests. + +TIP for Windows users: NZBGet is controlled via various command line +parameters. For easier using there is a simple shell script included +in "nzbget-shell.bat". Start this script from Windows Explorer and you will +be running a command shell with PATH adjusted to find NZBGet executable. +Then you can type all commands without full path to nzbget.exe. + +### Standalone mode: +-------------------- +``` +nzbget +``` +### Server mode: +---------------- + +First start the nzbget-server: + + - in console mode: +``` +nzbget -s +``` + - or in daemon mode (POSIX only): +``` + nzbget -D +``` + - or as a service (Windowx only, firstly install the service with command "nzbget -install"): +``` + net start NZBGet +``` +To stop server use: +``` +nzbget -Q +``` +TIP for POSIX users: with included script "nzbgetd" you can use standard +commands to control daemon: +``` +nzbgetd start +nzbgetd stop +``` + +When NZBGet is started in console server mode it displays a message that +it is ready to receive download requests. In daemon mode it doesn't print any +messages to console since it runs in background. + +When the server is running it is possible to queue up downloads. This can be +done either in terminal with "nzbget -A " or by uploading +a nzb-file into server's monitor-directory (/nzb by default). + +To check the status of server start client and connect it to server: +``` +nzbget -C +``` +The client have three different (display) outputmodes, which you can select +in configuration file (on client computer) or in command line. Try them: +``` +nzbget -o outputmode=log -C +nzbget -o outputmode=color -C +nzbget -o outputmode=curses -C +``` +To list files in server's queue: +``` +nzbget -L +``` +It prints something like: +``` +[1] nzbname\filename1.rar (50.00 MB) +[2] nzbname\filename1.r01 (50.00 MB) +[3] another-nzb\filename3.r01 (100.00 MB) +[4] another-nzb\filename3.r02 (100.00 MB) +``` +This is the list of individual files listed within nzb-file. To print +the list of nzb-files (without content) add G-modifier to the list command: +``` +[1] nzbname (4.56 GB) +[2] another-nzb (4.20 GB) +``` +The numbers in square braces are ID's of files or groups in queue. +They can be used in edit-command. For example to move file with +ID 2 to the top of queue: +``` +nzbget -E T 2 +``` +or to pause files with IDs from 10 to 20: +``` +nzbget -E P 10-20 +``` +or to delete files from queue: +``` +nzbget -E D 3 10-15 20-21 16 +``` + +The edit-command has also a group-mode which affects all files from the +same nzb-file. You need to pass an ID of the group. For example to delete +the whole group 1: +``` +nzbget -E G D 1 +``` +The switch "o" is useful to override options in configuration files. +For example: +``` +nzbget -o reloadqueue=no -o dupecheck=no -o parcheck=yes -s +``` +or: +``` +nzbget -o createlog=no -C +``` + +### Running client & server on seperate machines: +------------------------------------------------- + +Since nzbget communicates via TCP/IP it's possible to have a server running on +one computer and adding downloads via a client on another computer. + +Do this by setting the "ControlIP" option in the nzbget.conf file to point to the +IP of the server (default is localhost which means client and server runs on +same computer) + +### Security warning +-------------------- + +NZBGet communicates via unsecured socket connections. This makes it vulnerable. +Although server checks the password passed by client, this password is still +transmitted in unsecured way. For this reason it is highly recommended +to configure your Firewall to not expose the port used by NZBGet to WAN. + +If you need to control server from WAN it is better to connect to server's +terminal via SSH (POSIX) or remote desktop (Windows) and then run +nzbget-client-commands in this terminal. + +### Web-interface +----------------- + +NZBGet has a built-in web-server providing the access to the program +functions via web-interface. + +To activate web-interface set the option "WebDir" to the path with +web-interface files. If you install using "make install-conf" as +described above the option is set automatically. If you install using +binary files you should check if the option is set correctly. + +To access web-interface from your web-browser use the server address +and port defined in NZBGet configuration file in options "ControlIP" and +"ControlPort". For example: +``` +http://localhost:6789/ +``` + +For login credentials type username and the password defined by +options "ControlUsername" (default `"nzbget"`) and "ControlPassword" +(default `"tegbzn6789"`). + +In a case your browser forget credentials, to prevent typing them each +time, there is a workaround - use URL in the form: +``` +http://localhost:6789/username:password/ +``` +Please note, that in this case the password is saved in a bookmark or in +browser history in plain text and is easy to find by persons having +access to your computer. diff --git a/docs/POSIX.md b/docs/POSIX.md new file mode 100644 index 00000000..6cf011b2 --- /dev/null +++ b/docs/POSIX.md @@ -0,0 +1,280 @@ +## To build NZBGet you will need: + + - For configuring and building: + - [CMake](https://cmake.org/) + - [GCC](https://gcc.gnu.org/) + + or + - [CLang](https://clang.llvm.org/) + + - Libraries: + - [libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home) + - [Boost.JSON](https://www.boost.org/doc/libs/1_84_0/libs/json/doc/html/index.html) + +> If you face issues with Boost.JSON on your system, you can skip it - CMake will take care of it. + +- And the following libraries are optional: + + - For curses-output-mode (enabled by default): + - [ncurses](https://invisible-island.net/ncurses) + + - For encrypted connections (TLS/SSL): + - [OpenSSL](https://www.openssl.org) + + or + - [GnuTLS](https://gnutls.org) + + - For gzip support in web-server and web-client (enabled by default): + - [zlib](https://www.zlib.net/) + + - For tests: + - [Boost.Test](https://www.boost.org/doc/libs/1_84_0/libs/test/doc/html/index.html) + + - For static code analysis: + - [Clang-Tidy](https://clang.llvm.org/extra/clang-tidy/) + +Please note that you also +need the developer packages for these libraries too, they package names +have often suffix "dev" or "devel". On other systems you may need to +download the libraries at the given URLs and compile them (see hints below). + +### Debian: +``` +apt install cmake build-essential libncurses-dev libssl-dev libxml2-dev zlib1g-dev libboost-json1.81-dev +``` + - For tests: +``` +apt install libboost-test1.81-dev +``` + - For static code analysis: +``` +apt install clang-tidy +``` +### FreeBSD: +``` +pkg install cmake ncurses openssl libxml2 zlib boost-libs +``` +### macOS: +``` +xcode-select --install +brew install cmake ncurses openssl libxml2 zlib boost +``` + +## 4. Installation on POSIX + +Installation from the source distribution archive (nzbget-VERSION.tar.gz): + + - Untar the nzbget-source: +``` +tar -zxf nzbget-VERSION.tar.gz +``` + - Change into nzbget-directory: +``` +cd nzbget-VERSION +``` + - Configure: +``` +mkdir build +cd build +cmake .. +``` + - In a case you don't have root access or want to install the program + in your home directory use the configure parameter -DCMAKE_INSTALL_PREFIX: +``` +cmake .. -DCMAKE_INSTALL_PREFIX=~/usr +``` + - Build, specifying (-j 8) how many CPU cores to use to speed up compilation: +``` +cmake --build . -j 8 +``` + - Install: +``` +cmake --install . +``` + - Uninstall: +``` +cmake --build . --target uninstall +``` + +### Configure-options +--------------------- +You may run configure with additional arguments: + - Enable tests: +``` +cmake .. -DENABLE_TESTS=ON +``` + - Enable Clang-Tidy static code analizer: +``` +cmake .. -DENABLE_CLANG_TIDY=ON +``` + - Disable ncurses. Use this option if you can not use ncurses. +``` +cmake .. -DDISABLE_CURSES=ON +``` + - Disable parcheck. Use this option if you have troubles when compiling par2-module. +``` +cmake .. -DDISABLE_PARCHECK=ON +``` + - Use GnuTLS. Use this option if you want to use GnuTLS instead of OpenSSL. +``` +cmake .. -DUSE_GNUTLS=ON +``` + - Disable TLS. Use this option if you can not neither OpenSSL nor GnuTLS. +``` +cmake .. -DDISABLE_TLS=ON +``` + - Disable gzip. Use this option if you can not use zlib. +``` +cmake .. -DDISABLE_GZIP=ON +``` + - Disable sigchld-handler. The disabling may be neccessary on 32-Bit BSD. +``` +cmake .. -DDISABLE_SIGCHLD_HANDLER=ON +``` + - For debug build. +``` +cmake .. -DCMAKE_BUILD_TYPE=Debug +``` + - To get a static binary, +``` +cmake .. -DENABLE_STATIC=ON +``` +`LIBS` and `INCLUDES` env variables can be useful for static linking, since CMake looks for shared libraries by default +``` +export LIBS="-lncurses -ltinfo -lboost_json -lxml2 -lz -lm -lssl -lcrypto -Wl,--whole-archive -lpthread -Wl,--no-whole-archive" +export INCLUDES="/usr/include/;/usr/include/libxml2/" +cmake .. -DENABLE_STATIC=ON +``` +## Cppcheck + - Install Cppcheck +``` +apt install cppcheck +``` + - Generate a compile database: +``` +cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON . +``` + - The file compile_commands.json is created in the current folder. Now run Cppcheck like this: +``` +cppcheck --project=compile_commands.json +``` + - To ignore certain folders you can use -i. This will skip analysis of source files in +the foo folder. +``` +cppcheck --project=compile_commands.json -ifoo +``` + +## Building using autotools (deprecated) + + - configure it via +``` +autoreconf --install./configure +``` + (maybe you have to tell configure, where to find some libraries then is your friend! +``` +./configure --help +``` + also see "Configure-options" later) + + - in a case you don't have root access or want to install the program + in your home directory use the configure parameter --prefix, e. g.: +``` +./configure --prefix ~/usr +``` + - compile it via +``` +make -j 4 +``` + - to install system wide become root via: +``` +su +``` + - install it via: +``` +make install +``` + - install configuration files into /etc via: +``` +make install-conf +``` +(you can skip this step if you intend to store configuration + files in a non-standard location) + +### Configure-options +--------------------- +You may run configure with additional arguments: + + - --disable-curses - to make without curses-support. Use this option + if you can not use curses/ncurses. + + - --disable-parcheck - to make without parcheck-support. Use this option + if you have troubles when compiling par2-module. + + - --with-tlslib=(OpenSSL, GnuTLS) - to select which TLS/SSL library + should be used for encrypted server connections. + + - --disable-tls - to make without TLS/SSL support. Use this option if + you can not neither OpenSSL nor GnuTLS. + + - --disable-gzip - to make without gzip support. Use this option + if you can not use zlib. + + - --enable-debug - to build in debug-mode, if you want to see and log + debug-messages. + +### Optional package: par-check +------------------------------- +NZBGet can check and repair downloaded files for you. For this purpose +it uses library par2. + +For your convenience the source code of libpar2 is integrated into +NZBGet’s source tree and is compiled automatically when you make NZBGet. + +In a case errors occur during this process the inclusion of par2-module +can be disabled using configure option "--disable-parcheck": +``` +./configure --disable-parcheck +``` + +### Optional package: curses +---------------------------- +For curses-outputmode you need ncurses or curses on your system. +If you do not have one of them you can download and compile ncurses yourself. +Following configure-parameters may be useful: + + - --with-libcurses-includes=/path/to/curses/includes + - --with-libcurses-libraries=/path/to/curses/libraries + +If you are not able to use curses or ncurses or do not want them you can +make the program without support for curses using option "--disable-curses": +``` +./configure --disable-curses +``` + +### Optional package: TLS +------------------------- +To enable encrypted server connections (TLS/SSL) you need to build the program +with TLS/SSL support. NZBGet can use two libraries: OpenSSL or GnuTLS. +Configure-script checks which library is installed and use it. If both are +available it gives the precedence to OpenSSL. You may override that with +the option --with-tlslib=(OpenSSL, GnuTLS). For example to build with GnuTLS: +``` +./configure --with-tlslib= GnuTLS +``` + +Following configure-parameters may be useful: + + - --with-libtls-includess=/path/to/gnutls/includes + - --with-libtls-libraries=/path/to/gnutls/libraries + + - --with-openssl-includess=/path/to/openssl/includes + - --with-openssl-libraries=/path/to/openssl/libraries + +If none of these libraries is available you can make the program without +TLS/SSL support using option "--disable-tls", but + some features of nzbget will stop working, such as Extension Manager: +``` +./configure --disable-tls +``` +## Known issues: +- does not compile on `armhf` hosts due to `yencode` library optimizations for vfp fpu hosts; diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md new file mode 100644 index 00000000..e309cdea --- /dev/null +++ b/docs/WINDOWS.md @@ -0,0 +1,87 @@ +## To build NZBGet you will need: + + - [CMake](https://cmake.org/) + - [MS C++ Build tools](https://visualstudio.microsoft.com/downloads/?q=build+tools#build-tools-for-visual-studio-2022) + - Download `Build Tools for Visual Studio 2022` and install it + - Select `Desktop development with C++` in the `Desktop & Mobile` section and install the necessary components: + - MSVC v143 - VS 2022 C++ x64/x86 build tools + - Windows 11 SDK + - C++ ATL for latest v143 build tools + - C++ MFC for latest v143 build tools + - Edit the `Path` enviroment variable and append the folder's path that contains the `MSBuild.exe` to it, e.g.: + + `C:\Users\asus\AppData\Local\Programs\Microsoft VS Code\bin\` + +To compile the program with TLS/SSL support you need OpenSSL: + - [OpenSSL](https://www.openssl.org) + +Also required are: + - [Zlib](https://gnuwin32.sourceforge.net/packages/zlib.htm) + - [libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home) + - [Boost.JSON](https://www.boost.org/doc/libs/1_84_0/libs/json/doc/html/index.html) + - [Boost.Optional](https://www.boost.org/doc/libs/1_84_0/libs/optional/doc/html/index.html) + +For tests: + - [Boost.Test](https://www.boost.org/doc/libs/1_84_0/libs/test/doc/html/index.html) + +We recommend using [vcpkg](https://vcpkg.io/) to install dependencies: + - Clone the repository to the recommended `C:\` disk: +``` +git clone --depth 1 https://github.com/microsoft/vcpkg.git +``` + - Run the `bootstrap` script: +``` +.\vcpkg\bootstrap-vcpkg.bat +``` + - Edit the `Path` enviroment variable and append the folder's path: `C:\vcpkg` + - Install all the dependencies: +``` +vcpkg install openssl:x64-windows-static +vcpkg install libxml2:x64-windows-static +vcpkg install zlib:x64-windows-static +vcpkg install boost-json:x64-windows-static +vcpkg install boost-optional:x64-windows-static +``` + - For tests: +``` +vcpkg install boost-test:x64-windows-static +``` + +For `Win32`, instead of `:x64-windows-static`, use `:x86-windows-static`. + + - Configure: +``` +mkdir build +cd build +cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -A x64 +``` + - Or for Win32: +``` +cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x86-windows-static -A Win32 +``` + - Release build: +``` +cmake --build . --config Release +``` + - Or for debug build: +``` +cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_BUILD_TYPE=Debug +``` + - Debug build: +``` +cmake --build . --config Debug +``` + - Now, you can find the binary in the `Release/Debug` directory. + + +You may run configure with additional arguments: + - Enable tests: +``` +cmake .. -DENABLE_TESTS=ON -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static +``` + - Disable TLS. Use this option if you can not use OpenSSL but + some features of nzbget will stop working, such as Extension Manager: + +``` +cmake .. -DDISABLE_TLS=ON -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static +``` diff --git a/docs/extensions/EXTENSIONS.md b/docs/extensions/EXTENSIONS.md new file mode 100644 index 00000000..e9af6792 --- /dev/null +++ b/docs/extensions/EXTENSIONS.md @@ -0,0 +1,365 @@ +## About + +The core functionality of NZBGet can be extended using extensions. +NZBGet provides documented entry points for extensions. +On certain events the extensions are executed, they receive information about event, +do certain work and can communicate with NZBGet to give it instructions for further processing. + +## Installation + +### Using the Extension Manager + +On the `SETTINGS` page you can easily find `EXTENSION MANAGER` +and use it to install the extensions you need. Make sure that the internet connection is working +and the path to the `7z` in `UNPACK->SevenZipCmd`(required for unpacking the extensions) is correct. +The list of available extensions can be found in the +[nzbget-extensions](https://github.com/nzbgetcom/nzbget-extensions) repository. + +### Manually, for your custom extensions + +Option `ScriptDir` defines the location of extensions. +To make an extension available in NZBGet put the extension into this directory. +Then go to settings tab in web-interface (if you were already on settings +tab switch to downloads tab and then back to settings +tab to reread the list of available extensions from the disk). + +Menu at the left of page should list all extensions found in `ScriptDir`. +Select an extension to review or change its options (if it has any). + +## Writing extension + +In general, an extension consists of 2 files: `manifest.json` - +with all the meta-data describing the extension +and the `executable` file, like `main.py`. + +`manifest.json` example: +```json +{ + "main": "main.py", + "name": "EMail", + "homepage": "https://github.com/nzbgetcom/Extension-EMail", + "kind": "POST-PROCESSING", + "displayName": "My EMail Extension", + "version": "2.0.0", + "author": "John Doe", + "license": "GNU", + "about": "Sends E-Mail notification.", + "queueEvents": "", + "requirements": [ + "This script requires Python3.8 to be installed on your system." + ], + "description": ["This script sends E-Mail notification when the job is done."], + "options": [ + { + "name": "Server", + "displayName": "Server", + "value": "smtp.gmail.com", + "description": ["SMTP server host."], + "select": [] + }, + { + "name": "Port", + "displayName": "Port", + "value": 25, + "description": ["SMTP server port (1-65535)"], + "select": [1, 65535] + }, + { + "name": "SendMail", + "displayName": "SendMail", + "value": "Always", + "description": ["When to send the message."], + "select": ["Always", "OnFailure"] + }, + ], + "commands": [ + { + "name": "ConnectionTest", + "action": "Send Test E-Mail", + "displayName": "ConnectionTest", + "description": ["To check connection parameters click the button."] + } + ], + "taskTime": "" +} +``` + +### `"main"` + +The name of the executable file. +For example: `main.py`, `main.exe`, `MyExt.sh`. + +### `"name"` + +The extension name, identifier and prefix needed to +save the extension configuration options to `nzbget.conf`. + +### `"homepage"` + +Just a link to the repository where the extension lives. + +### `"kind"` + +Depending on the purpose of the extension, can be: +``` +"kind": "POST-PROCESSING" +"kind": "SCAN" +"kind": "QUEUE" +"kind": "SCHEDULER" +"kind": "FEED" +``` + +If the extension can be used for multiple purposes the `kind` can be mixed, for example: +``` +"kind": "SCAN/QUEUE" +``` + +More information about extension kinds can be found at: + - [POST-PROCESSING](POST-PROCESSING.md) + - [SCAN](SCAN.md) + - [QUEUE](QUEUE.md) + - [SCHEDULER](SCHEDULER.md) + - [FEED](FEED.md) + +### `"displayName"` + +The name that will be displayed in the web interface. + +### `"version"` + +Extension version. + +### `"author"` + +Author's name. + +### `"license"` + +Extension license. + +### `"about"` + +Brief description of the extension. + +### `"description"` + +For more detailed description of the extension. + +### `"queueEvents"` + +To describe the events that could be used by the extension, e.g.: + +```json +"queueEvents": "NZB_ADDED, NZB_DOWNLOADED" +``` + +More information can be found at [QUEUE](QUEUE.md). + +### "`requirements"` + +To describe the list of requirements, e.g.: + +```json +"requirements": [ + "This script requires Python3.8+ to be installed on your system." +], +``` + +### `"options"` + +Let’s say we are writing an extension to send E-Mail notification. +The user needs to configure the extension with options such as SMTP-Server host, +port, login and password. To avoid hard-coding of these data in the extension +NZBGet allows the extension to define the required options. +The options are then made available on the settings page for user to configure. + +In the provided `manifest.json` example we defined three options: + +```json +"options": [ + { + "name": "Server", + "displayName": "Server", + "value": "smtp.gmail.com", + "description": ["SMTP server host."], + "select": [] + }, + { + "name": "Port", + "displayName": "Port", + "value": 25, + "description": ["SMTP server port (1-65535)"], + "select": [1, 65535] + }, + { + "name": "SendMail", + "displayName": "SendMail", + "value": "Always", + "description": ["When to send the message."], + "select": ["Always", "OnFailure"] + }, +], +``` + +When the user saves settings in web-interface the extension configuration +options are saved to NZBGet configuration file using the extension name as prefix. For example: +``` +EMail:Server=smtp.gmail.com +EMail:Port=25 +``` + +Extension configuration options are passed using env-vars with prefix `NZBPO_`. +There are two env-vars for each option: + - one env-var with the name exactly as defined by pp-option; + - another env-var with the name written in UPPER CASE and with + special characters replaced with underscores. + +For example, for pp-option `Server.Name` two env-vars are passed: +`NZBPO_Server.Name` and `NZBPO_SERVER_NAME`. + +> In a case the user has installed the extension but have not saved the configuration, the options are not saved to +configuration file yet. The extension will not get the options passed. +This is a situation your extension must handle. You can either use a default settings or terminate the extension with +a proper message asking the user to check and save configuration in web-interface. + +Example (python): +```python +required_options = ('NZBPO_FROM', 'NZBPO_TO', 'NZBPO_SERVER', 'NZBPO_PORT', 'NZBPO_ENCRYPTION', +'NZBPO_USERNAME', 'NZBPO_PASSWORD', 'NZBPO_FILELIST', 'NZBPO_BROKENLOG', 'NZBPO_POSTPROCESSLOG') +for optname in required_options: +if (not optname in os.environ): + print('[ERROR] Option %s is missing in configuration file. Please check script settings' % optname[6:]) + sys.exit(POSTPROCESS_ERROR) +``` + +### `"commands"` + +Sometimes it may be helpful to be able to execute extension extensions from settings page. +For example pp-extension EMail could use a button "Send test email". For other extensions something like +"Validate settings" or "Cleanup database" may be useful too. + +Starting from v19 it is possible to put buttons on the extension settings page. The buttons are defined as +part of extension configuration, almost similar to extension configuration options: +```json +"commands": [ + { + "name": "ConnectionTest", + "action": "Send Test E-Mail", + "displayName": "ConnectionTest", + "description": ["To check connection parameters click the button."] + } +], +``` + +This example creates a button with text "Send Test E-Mail" and description +"To check connection parameters click the button.". + +When user presses the button NZBGet executes the extension in a special context passing +button name via env. var NZBCP_COMMAND. +The extension can check if it runs in command mode by examining this variable (python example): +```python +# Exit codes used by NZBGet +COMMAND_SUCCESS=93 +COMMAND_ERROR=94 + +# Check if the script is executed from settings page with a custom command +command = os.environ.get('NZBCP_COMMAND') +test_mode = command == 'ConnectionTest' +if command != None and not test_mode: + print('[ERROR] Invalid command ' + command) + sys.exit(COMMAND_ERROR) + +if test_mode: + print('[INFO] Test connection...') + sys.exit(COMMAND_SUCCESS) + +