diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-10 21:38:38 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-10 21:38:38 +0000 |
commit | 2e2851dc13d73352530dd4495c7e05603b2e520d (patch) | |
tree | 622b9cd8e5d32091c9aa9e4937b533975a40356c /docs/source/how-to | |
parent | Initial commit. (diff) | |
download | deluge-ba36a3baaa52c6e8dc58a724548d75d3db6e8ef9.tar.xz deluge-ba36a3baaa52c6e8dc58a724548d75d3db6e8ef9.zip |
Adding upstream version 2.1.2~dev0+20240219.upstream/2.1.2_dev0+20240219upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | docs/source/how-to/index.md | 27 | ||||
-rw-r--r-- | docs/source/how-to/launchd-service.md | 50 | ||||
-rw-r--r-- | docs/source/how-to/nssm-service.md | 38 | ||||
-rw-r--r-- | docs/source/how-to/set-mime-type.md | 24 | ||||
-rw-r--r-- | docs/source/how-to/systemd-service.md | 205 |
5 files changed, 344 insertions, 0 deletions
diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md new file mode 100644 index 0000000..7005a34 --- /dev/null +++ b/docs/source/how-to/index.md @@ -0,0 +1,27 @@ +# How-to guides + +A collection of guides covering common issues that might be encountered using Deluge. + +## GTK UI + +```{toctree} +:titlesonly: + +Set default torrent application <set-mime-type> +``` + +## Deluge as a service + +Services are used to start applications on system boot and leave them running +in the background. They will also stop the application nicely on system +shutdown and automatically restart them if they crash. + +The Deluge daemon deluged and Web UI deluge-web can both be run as services. + +```{toctree} +:titlesonly: + +Create systemd services for Linux <systemd-service> +Create launchd services for macOS <launchd-service> +Create NSSM services for Windows <nssm-service> +``` diff --git a/docs/source/how-to/launchd-service.md b/docs/source/how-to/launchd-service.md new file mode 100644 index 0000000..53c21be --- /dev/null +++ b/docs/source/how-to/launchd-service.md @@ -0,0 +1,50 @@ +# How to create launchd services for macOS + +The following launchd script uses a separate user deluge, this is optional +but recommended for security. To create a new deluge user follow the +[Apple help] steps. + +The paths to `deluged` and `deluge-web` assumes installation using [Homebrew] +and will need modified if using other installation methods e.g. `Deluge.app`. + +## Daemon (deluged) service + +Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluged.plist` +containing the following: + +```{eval-rst} +.. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluged.plist + :language: xml +``` + +Set the service to load on startup and then start it: + +```console +sudo launchctl load -w /Library/LaunchDaemons/org.deluge-torrent.deluged.plist +sudo launchctl start org.deluge-torrent.deluged +``` + +## Web UI (deluge-web) service + +Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluge-web.plist` +containing the following: + +```{eval-rst} +.. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluge-web.plist + :language: xml +``` + +Set the service to load on startup and then start it: + +```console +sudo launchctl load -w /Library/LaunchDaemons/org.deluge-torrent.deluge-web.plist +sudo launchctl start org.deluge-torrent.deluge-web +``` + +## Logging + +Logging is enabled by default in the above script, error level, and can be +modified as required. + +[apple help]: https://support.apple.com/en-gb/guide/mac-help/mtusr001/mac +[homebrew]: https://brew.sh/ diff --git a/docs/source/how-to/nssm-service.md b/docs/source/how-to/nssm-service.md new file mode 100644 index 0000000..1e39bf4 --- /dev/null +++ b/docs/source/how-to/nssm-service.md @@ -0,0 +1,38 @@ +# How to create NSSM services for Windows + +Download [NSSM] and read their usage page about installing. + +In order for the services to be stopped properly, use the debug application +versions (ending in `-debug.exe`). + +## Daemon (deluged) service + +Create a `deluged` service: + +```console +nssm install deluged +``` + +The following are minimum UI changes required for the service to work: + +``` +Path: C:\Program Files\Deluge\deluged-debug.exe +Arguments: -c C:\config_location +``` + +## Web UI (deluge-web) service + +```console +nssm install deluge-web +``` + +``` +Path: C:\Program Files\Deluge\deluge-web-debug.exe +Arguments: -c C:\config_location +``` + +If Web UI is not accessible outside your machine (if you're running +Deluge from a home server), you have to whitelist Deluge in your Windows +Firewall for the `deluge-web` and `deluge-web-debug` executable. + +[nssm]: http://nssm.cc/ diff --git a/docs/source/how-to/set-mime-type.md b/docs/source/how-to/set-mime-type.md new file mode 100644 index 0000000..29bad15 --- /dev/null +++ b/docs/source/how-to/set-mime-type.md @@ -0,0 +1,24 @@ +# How to set Deluge as default torrent application + +## Check registered MIME types + + gio mime application/x-bittorrent + gio mime x-scheme-handler/magnet + +## Set Deluge as default for MIME types + + gio mime x-scheme-handler/magnet deluge.desktop + gio mime application/x-bittorrent deluge.desktop + +## Troubleshooting + + update-mime-database ~/.local/share/mime + update-desktop-database ~/.local/share/applications + +### XDG Check + + xdg-mime query default x-scheme-handler/magnet + +## References + +<https://help.gnome.org/admin/system-admin-guide/stable/mime-types-custom-user.html.en> diff --git a/docs/source/how-to/systemd-service.md b/docs/source/how-to/systemd-service.md new file mode 100644 index 0000000..611ecc1 --- /dev/null +++ b/docs/source/how-to/systemd-service.md @@ -0,0 +1,205 @@ +# How to create systemd services for Linux + +This guide walks you through setting up Deluge systemd services on Linux. + +Ensure Deluge daemon `deluged` and Web UI `deluge-web` are installed. Use +`which` to check installation paths and if necessary modify the service +file `ExecStart` lines to point to alternative paths. + +## Create a service specific user + +For security it is best to run a service with a specific user and group. +You can create one using the following command: + +```console +sudo adduser --system --gecos "Deluge Service" --disabled-password --group --home /var/lib/deluge deluge +``` + +This creates a new system user and group named `deluge` with no login access +and home directory `/var/lib/deluge` which will be the default location for the +config files. + +In addition you can add to the `deluge` group any users you wish to be able to +easily manage or access files downloaded by Deluge, for example: + +```console +sudo adduser <username> deluge +``` + +## Daemon (deluged) service + +Create the file `/etc/systemd/system/deluged.service` containing the following: + +```{eval-rst} +.. literalinclude:: ../../../packaging/systemd/deluged.service + :language: ini +``` + +### User configuration + +To run the service using the previously created user e.g. `deluge`, first +create the service configuration directory: + +```console +sudo mkdir /etc/systemd/system/deluged.service.d/ +``` + +Then create a user file `/etc/systemd/system/deluged.service.d/user.conf` with +the following contents: + +```{eval-rst} +.. literalinclude:: ../../../packaging/systemd/user.conf + :language: ini +``` + +### Start deluged service + +Now enable it to start up on boot, start the service and verify it is running: + +```console +sudo systemctl enable /etc/systemd/system/deluged.service +sudo systemctl start deluged +sudo systemctl status deluged +``` + +### Umask for deluged downloaded files + +The `umask` in the service file can be modified to determine access to files +downloaded by deluged (also applies to logging files). Some useful access +values are detailed as follows: + +- `000` - full access for all users and groups. +- `007` - only user and group that `deluged` is running as (e.g. `deluge`) + with no access from any other accounts. +- `002` - user and group `deluged` is running as with read-only for all other + accounts. +- `022` - user `deluged` is running as with read-only for all other accounts. + +The service for `deluged` must be stopped and started instead of just restarted +after changes. + +## Web UI (deluge-web) service + +Create the file `/etc/systemd/system/deluge-web.service` containing the following: + +```{eval-rst} +.. literalinclude:: ../../../packaging/systemd/deluge-web.service + :language: ini +``` + +### User configuration + +To run the service using the previously created user e.g. `deluge`, first +create the service configuration directory: + +``` +sudo mkdir /etc/systemd/system/deluge-web.service.d/ +``` + +Then create a user file `/etc/systemd/system/deluge-web.service.d/user.conf` with +the following contents: + +```{eval-rst} +.. literalinclude:: ../../../packaging/systemd/user.conf + :language: ini +``` + +### Start deluge-web service + +Now enable it to start up on boot, start the service and verify it is running: + +```console +sudo systemctl enable /etc/systemd/system/deluge-web.service +sudo systemctl start deluge-web +sudo systemctl status deluge-web +``` + +## Service logging + +Create a log directory for Deluge and give the service user (e.g. `deluge`), full access: + +```console +sudo mkdir -p /var/log/deluge +sudo chown -R deluge:deluge /var/log/deluge +sudo chmod -R 750 /var/log/deluge +``` + +The deluge log directory is now configured so that user `deluge` has full +access, group `deluge` read only and everyone else denied access. The `umask` +specified in the services sets the permission of new log files. + +Enable logging in the service files by editing the `ExecStart` line, appending +`-l` and `-L` options: + +``` +ExecStart=/usr/bin/deluged -d -l /var/log/deluge/daemon.log -L warning +``` + +``` +ExecStart=/usr/bin/deluge-web -d -l /var/log/deluge/web.log -L warning +``` + +See `deluged -h` for all available log-levels. + +Restart the services: + +```console +sudo systemctl daemon-reload +sudo systemctl restart deluged +sudo systemctl restart deluge-web +``` + +### Log rotation + +To enable log rotation append `--logrotate` to the above `ExecStart` lines. + +## Conditionally start deluged for mount points + +If you have a USB disk drive or network drive that may not be immediately +available on boot or disconnected at random then you may want the `deluged` +service to wait for mount point to be ready before starting. If they are +unmounted or disconnected then `deluged` is stopped. When they become available +again `deluged` is started. + +Ensure you have added the correct drive details to `fstab` or equivalent so +they are mounted at boot. + +List the available drive mounts: + +```console +sudo systemctl -t mount +``` + +Look for your mount point in the `Description` column. Mounts are formatted +similar to the mount point with `-`s replacing `/`s in the path. +e.g.: `media-xyz.mount` + +Modify the `[Unit]` section of the `deluged.service` script by adding the +details below, substituting `xyz.mount` for the mount you want the service +to depend on: + +```ini +[Unit] +Description=Deluge Bittorrent Client Daemon +# Start after network and specified mounts are available. +After=network-online.target xyz.mount +Requires=xyz.mount +# Stops deluged if mount points disconnect +BindsTo=xyz.mount +``` + +For multiple mount points add a space between additional entries. e.g.: + +```ini +After=network-online.target xyz.mount abc.mount def.mount +``` + +Modify the `[Install]` section to ensure the deluged service is started when +the mount point comes back online: + +```ini +[Install] +WantedBy=multi-user.target xyz.mount +``` + +Reference: [systemd.unit](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequiresMountsFor=) |