transportal

transportal is a responsive web interface and server for the Transmission BitTorrent daemon. It is designed for both desktop and mobile browsers. transportal runs as a web server and communicates with Transmission using RPC requests. The server uses server-sent events to push updates to the browser.

Many features are still unimplemented or incomplete, but it works well for simple monitoring and torrent management.

Quick start

cargo install --git https://github.com/stevenengler/transportal.git

cat >config.toml <<EOF
[connection]
bind_address = "127.0.0.1:8080"
rpc_url_base = "http://localhost:9091"
rpc_url_path = "/transmission/rpc"
EOF

transportal config.toml

Limitations

Server-sent events are used to push updates to the browser. Server-sent events work best when using http/2, but unfortunately browsers only support http/2 over TLS connections. While transportal works when not using http/2, you will be limited to having only a few tabs open at a time. One workaround is to use a web proxy such as Nginx, which can add TLS to the connection with a self-signed certificate.

Configuration

Configuration files are specified in toml format.

[connection]

bind_address

Required

The socket address to bind the server to. Ex: 127.0.0.1:80 or unix:/home/user/transportal.sock.

bind_unix_perms

Default: 600

If binding to a unix socket, these octal permissions will be used for the socket file. The umask is ignored. Ex: 620.

rpc_url_base

Required

The URL base used to connect to Transmission's RPC server. Ex: http://127.0.0.1:9091.

rpc_url_path

Required

The URL path used to connect to Transmission's RPC server. Ex: /transmission/rpc. Must have a leading slash.

[security]

secure_cookie_attribute

Default: true

Whether the Secure attribute is set on cookies. If true, the browser must connect over HTTPS, localhost, or an onion service. Otherwise, authentication won't work correctly.

[performance]

poll_interval_ms

Default: 1000

The interval in milliseconds at which the server polls Transmission for each SSE connection.

Security

transportal is still in development, so not all security protections are complete.

XSS

Data from Transmission is used to populate the HTML. This data is generally escaped by the templating engine, but there are a few places that assume data such as timestamps and torrent hashes provided by Transmission are trustworthy. This will be improved in the future.

CSRF

The session cookie is configured with SameSite: Lax, meaning that authenticated endpoints should be protected against CSRF attacks unless the attack comes from the same site (which includes subdomains). The login form is not yet protected against CSRF attacks. These will be improved in the future.

Authentication

The provided username and password are stored in memory for the duration of the session in order to issue RPC requests to Transmission. The client is given a random 128-bit session cookie with the SameSite: Lax, HttpOnly, and Secure (unless disabled in the configuration options) attributes.

Technical details

The server uses axum to process HTTP requests. Transmission RPC calls are made using reqwest. HTML responses are rendered on the server using askama, and the webpage updates dynamically using htmx.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.