[Docs] Add service how-tos
This commit is contained in:
Calum Lind
parent
8b62e50eb8
commit
c1ba403d4e
|
|
@ -1,5 +1,11 @@
|
|||
# Changelog
|
||||
|
||||
## 2.0.4 (WIP)
|
||||
|
||||
### Documentation
|
||||
|
||||
- Add How-to guides about services.
|
||||
|
||||
## 2.0.3 (2019-06-12)
|
||||
|
||||
### Gtk UI
|
||||
|
|
|
|||
|
|
@ -2,4 +2,18 @@
|
|||
|
||||
A collection of guides covering common issues that might be encountered using Deluge.
|
||||
|
||||
## GTK UI
|
||||
|
||||
- [Set default torrent application](set-mime-type.md)
|
||||
|
||||
## 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.
|
||||
|
||||
- [Create systemd services for Linux](systemd-service.md)
|
||||
- [Create launchd services for macOS](launchd-service.md)
|
||||
- [Create NSSM services for Windows](nssm-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/
|
||||
|
|
@ -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/
|
||||
|
|
@ -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.:
|
||||
|
||||
```init
|
||||
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=)
|
||||
Loading…
Reference in New Issue