Merge pull request #99 from jleivo/master

Feat/ssh hardening

README.md

@@ -1,142 +1,170 @@
-# rffmpeg
+
+
+<p align="center">
+<img alt="License: GPLv3+" src="https://img.shields.io/github/license/joshuaboniface/rffmpeg"/>
+<img alt="Code Style: Black" src="https://img.shields.io/badge/code%20style-black-000000.svg"/>
+<a href="https://matrix.to/#/#rffmpeg:matrix.org">
+<img alt="Chat on Matrix" src="https://img.shields.io/matrix/rffmpeg:matrix.org.svg?logo=matrix"/>
+</a>
+<a href="https://www.patreon.com/joshuaboniface">
+<img alt="Support me on Patreon" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fshieldsio-patreon.vercel.app%2Fapi%3Fusername%3Djoshuaboniface%26type%3Dpatrons&style=flat"/>
+</a>
+<a href="https://github.com/sponsors/joshuaboniface">
+<img alt="Support me on GitHub" src="https://img.shields.io/github/sponsors/joshuaboniface?label=GitHub%20Sponsors">
+</a>
+</p>
 
 `rffmpeg` is a remote FFmpeg wrapper used to execute FFmpeg commands on a remote server via SSH. It is most useful in situations involving media servers such as Jellyfin (our reference user), where one might want to perform transcoding actions with FFmpeg on a remote machine or set of machines which can better handle transcoding, take advantage of hardware acceleration, or distribute transcodes across multiple servers for load balancing.
 
 ## Quick usage
 
-1. Install the required Python 3 dependencies `yaml` and `subprocess` (`sudo apt install python3-yaml python3-subprocess` in Debian).
+1. Install the required Python 3 dependencies: `click`, `yaml` and `subprocess` (`sudo apt install python3-click python3-yaml python3-subprocess` in Debian) and optionally install `psycopg2` with `sudo apt install python3-psycopg2` for Postgresql support.
 
 1. Create the directory `/etc/rffmpeg`.
 
-1. Copy the `rffmpeg.yml.sample` file to `/etc/rffmpeg/rffmpeg.yml` and edit it to suit your needs.
+1. Optionally, copy the `rffmpeg.yml.sample` file to `/etc/rffmpeg/rffmpeg.yml` and edit it to suit your needs.
 
-1. Install `rffmpeg.py` somewhere useful, for instance at `/usr/local/bin/rffmpeg.py`.
+1. Install `rffmpeg` somewhere useful, for instance at `/usr/local/bin/rffmpeg`.
 
-1. Create symlinks for the command names `ffmpeg` and `ffprobe` to `rffmpeg.py`, for example `sudo ln -s /usr/local/bin/rffmpeg.py /usr/local/bin/ffmpeg` and `sudo ln -s /usr/local/bin/rffmpeg.py /usr/local/bin/ffprobe`.
+1. Create symlinks for the command names `ffmpeg` and `ffprobe` to `rffmpeg`, for example `sudo ln -s /usr/local/bin/rffmpeg /usr/local/bin/ffmpeg` and `sudo ln -s /usr/local/bin/rffmpeg /usr/local/bin/ffprobe`.
 
-1. Set your media program to use `rffmpeg.py` via the symlink names created above, instead of any other `ffmpeg` binary.
+1. Initialize the database and add a target host, for example `sudo rffmpeg init && rffmpeg add myhost.domain.tld`.
+
+1. Set your media program to use `rffmpeg` via the `ffmpeg` symlink name created above, instead of any other `ffmpeg` binary.
 
 1. Profit!
 
-For more detailed instructions, including what must be done to ensure data can be passed between the servers, please see [the SETUP guide](SETUP.md).
+`rffmpeg` does require a little bit more configuration to work properly however. For a comprehensive installation tutorial based on a reference setup, please see [the SETUP guide](docs/SETUP.md).
 
-## rffmpeg options and caveats
+**NOTE** Jellyfin 10.10.x and newer require an additional `TMPDIR` environment variable set to somewhere exported to the remote machine, or these paths will not work properly. Edit your Jellyfin startup/service configuration to set that. See the setup guide for more details.
 
-The `rffmpeg.yml.sample` is self-documented for the most part. Some additional important information you might need is presented below.
+## Setup and Usage
 
-### Remote hosts
+### The `rffmpeg` Configuration file
 
-rffmpeg supports setting multiple hosts. It keeps state in `/run/shm/rffmpeg` of all running processes, and these state files are used during rffmpeg's initialization in order to determine the optimal target host. rffmpeg will run through these hosts sequentially, choosing the one with the fewest running rffmpeg jobs. This helps distribute the transcoding load across multiple servers, and can also provide redundancy if one of the servers is offline - rffmpeg will detect if a host is unreachable and set it "bad" for the remainder of the run, thus skipping it until the process completes.
+`rffmpeg` will look at `/etc/rffmpeg/rffmpeg.yml` (or a path specified by the `RFFMPEG_CONFIG` environment variable) for a configuration file. If it doesn't find one, defaults will be used instead. You can use this file to override many configurable default values to better fit your environment. The defaults should be sensible for anyone using [Jellyfin](https://jellyfin.org) and following the [SETUP guide](SETUP.md).
 
-Hosts can also be assigned weights (see `rffmpeg.yml.sample` for an example) that allow the host to take on that many times the number of active processes versus weight-1 hosts. The `rffmpeg` process does a floor division of the number of active processes on a host with that host weight to determine its "weighted [process] count", which is then used instead to determine the lease-loaded host to use. Note that `rffmpeg` does not take into account actual system load, etc. when determining which host to use; it treats each running command equally regardless of how intensive it actually is.
+The example configuration file at `rffmpeg.yml.sample` shows all available options; this file can be copied as-is to the above location and edited to suit your needs; simply uncomment any lines you want to change. Note that if you do specify a file, you *must* ensure that all top-level categories are present or it will error out.
 
-#### Host lists
+**NOTE:** If you are running into problems with `rffmpeg`, you must use the config file to adjust `logging` -> `debug` to `true` to obtain more detailed logs before requesting help.
 
-Hosts are specified as a YAML list in the relevant section of `rffmpeg.yml`, with one list entry per target. A single list entry can be specfied in one of two ways. Either a direct list value of the hostame/IP:
+Each option has an explanatory comment above it detailing its purpose.
 
-```
-- myhostname.domain.tld
-```
+Since the configuration file is YAML, ensure that you do not use "Tab" characters inside of it, only spaces.
 
-Or as a fully expanded `name:`/`weight:` pair.
+### CLI interface to `rffmpeg`
 
-```
-- name: myhostname.domain.tld
-  weight: 2
-```
+`rffmpeg` is a [Click](https://click.palletsprojects.com)-based application; thus, all commands have a `-h` or `--help` flag to show usage and additional options that may be specified.
 
-The first, direct list value formatting implies `weight: 1`. Examples of both styles can be found in the same configuration.
+### Initializing `rffmpeg`
 
-You can get creative with this list, especially since `rffmpeg` always checks the list in order to find the next available host. For an example of a complex setup, if you had 3 hosts, and wanted 1+2+2 processes, the following would be the default way to acheive this:
+After first installing `rffmpeg`, you must initialize the database with the `rffmpeg init` command.
 
-```
-- name: host1
-  weight: 1
-- name: host2
-  weight: 2
-- name: host3
-  weight: 2
-```
+Note that by default, `sudo`/root privilege is required for this command to create the required data paths, but afterwards, `rffmpeg` can be run by anyone in the configured group (by default the `sudo` group). You can bypass the `sudo` requirement with the `--no-root` command, for example when running in a rootless container; this will require the running user to have write permissions to the state and database parent directories, and will not perform any permissions modifications on the resulting files.
 
-This would however spread processes out like this, which might work well, but might not for some usecases:
+### Viewing Status
 
-```
-proc1: host1
-proc2: host2
-proc3: host2
-proc4: host3
-proc5: host3
-proc6: host1
-etc.
-```
+Once installed and initialized, you can see the status of the `rffmpeg` system with the `rffmpeg status` command. This will show all configured target hosts, their states, and any active commands being run.
 
-You could instead specify the hosts like this:
+### Adding or Removing Target Hosts
 
-```
-- host1
-- host2
-- host3
-- host2
-- host3
-```
+To add a target host, use the `rffmpeg add` command. You must add at least one target host for `rffmpeg` to be useful. This command takes the optional `-w`/`--weight` flag to adjust the weight of the target host (see below). A host can also be added more than once for a pseudo-weight, but this is an advanced usage.
 
-Which would instead give a process spread like:
+To remove a target host, use the `rffmpeg remove` command. This command takes either a target host name/IP, which affects all instances of that name, or a specific host ID. Removing an in-use target host will not terminate any running processes, though it may result in undefined behaviour within `rffmpeg`. Before removing a host it is best to ensure there is nothing using it.
 
-```
-proc1: host1
-proc2: host2
-proc3: host3
-proc4: host2
-proc5: host3
-proc6: host1
-etc.
-```
+### Viewing the Logfile
 
-Experiment with the ordering based on your load and usecase.
+The `rffmpeg` CLI offers a convenient way to view the log file. Use `rffmpeg log` to view the entire logfile in the default pager (usually `less`), or use `rffmpeg log -f` to follow any new log entries after that point (like `tail -0 -f`).
 
-#### Localhost and fallback
+## Important Considerations
 
-If one of the hosts in the config file is called "localhost", rffmpeg will run locally without SSH. This can be useful if the local machine is also a powerful transcoding device.
+### Localhost and Fallback
 
-In addition, rffmpeg will fall back to "localhost" should it be unable to find any working remote hosts. This helps prevent situations where rffmpeg cannot be run due to none of the remote host(s) being available.
+If one of the configured target hosts is called `localhost` or `127.0.0.1`, `rffmpeg` will run the `ffmpeg`/`ffprobe` commands locally without SSH. This can be useful if the local machine is also a powerful transcoding device, but you still want to offload some transcoding jobs to other machines.
 
-In both cases, note that, if hardware acceleraton is configured, it *must* be available on the local host as well, or the `ffmpeg` commands will fail. There is no easy way around this without rewriting flags, and this is currently out-of-scope for `rffmpeg`. You should always use a lowest-common-denominator approach when deciding on what additional option(s) to enable, such that any configured host can run any process.
+In addition, `rffmpeg` will fall back to `localhost` automatically, even if it is not explicitly configured, should it be unable to find any working remote hosts. This helps prevent situations where `rffmpeg` cannot be run due to none of the remote host(s) being available.
 
-The exact path to the local `ffmpeg` and `ffprobe` binaries can be overridden in the configuration, should their paths not match those of the remote system(s). If these options are not specified, the remote paths are used.
+The exact path to the local `ffmpeg` and `ffprobe` binaries can be overridden in the configuration, should their paths not match those of the remote system(s).
 
-### Terminating rffmpeg
+### Hardware Acceleration
 
-When running rffmpeg manually, *do not* exit it with `Ctrl+C`. Doing so will likely leave the `ffmpeg` process running on the remote machine. Instead, enter `q` and a newline ("Enter") into the rffmpeg process, and this will terminate the entire command cleanly. This is the method that Jellyfin uses to communicate the termination of an `ffmpeg` process.
+Note that if hardware acceleration is configured in the calling application, **the exact same hardware acceleration modes must be available on all configured hosts, and, for fallback to work, the local host as well**, or the `ffmpeg` commands will fail.
+
+This is an explicit requirement, and there is no easy way around this without rewriting the passed arguments, which is explicitly out-of-scope for `rffmpeg` (see the FAQ entry below about mangling arguments).
+
+You should always use a lowest-common-denominator approach when deciding what hardware acceleration option(s) to enable, such that any configured host can run any process, or accept that fallback will not work if all remote hosts are unavailable.
+
+### Target Host Selection
+
+When more than one target host is present, `rffmpeg` uses the following rules to select a target host. These rules are evaluated each time a new `rffmpeg` alias process is spawned based on the current state (actively running processes, etc.).
+
+1. Any hosts marked `bad` are ignored.
+
+1. All remaining hosts are iterated through in an indeterminate order (Python dictionary with root key as the host ID). For each host:
+
+   a. If the host is not `localhost`/`127.0.0.1`, it is tested to ensure it is reachable (responds to `ffmpeg -version` over SSH). If it is not reachable, it is marked `bad` for the duration of this processes' runtime and skipped.
+
+   b. If the host is `idle` (has no running processes), it is immediately chosen and the iteration stops.
+
+   c. If the host is `active` (has at least one running process), it is checked against the host with the current fewest number of processes, adjusted for host weight. If it has the fewest, it takes over this role.
+
+1. Once all hosts have been iterated through, at least one host should have been chosen: either the first `idle` host, or the host with the fewest number of active processes. `rffmpeg` will then begin running against this host. If no valid target host was found, `localhost` is used (see section [Localhost and Fallback](#localhost-and-fallback) above).
+
+### Target Host Weights and Duplicated Target Hosts
+
+When adding a host to `rffmpeg`, a weight can be specified. Weights are used during the calculation of the fewest number of processes among hosts. The actual number of processes running on the host is floor divided (rounded down to the nearest divisible integer) by the weight to give a "weighted count", which is then used in the determination. This option allows one host to take on more processes than other nodes, as it will be chosen as the "least busy" host more often.
+
+For example, consider two hosts: `host1` with weight 1, and `host2` with weight 5. `host2` would have its actual number of processes floor divided by `5`, and thus any number of processes under `5` would count as `0`, any number of processes between `5` and `10` would count as `1`, and so on, resulting in `host2` being chosen over `host1` even if it had several processes. Thus, `host2` would on average handle 5x more `ffmpeg` processes than `host1` would.
+
+Host weighting is a fairly blunt instrument, and only becomes important when many simultaneous `ffmpeg` processes/transcodes are occurring at once across at least 2 remote hosts, and where the target hosts have significantly different performance profiles. Generally leaving all hosts at weight 1 would be sufficient for most use-cases.
+
+Furthermore, it is possible to add a host of the same name more than once in the `rffmpeg add` command. This is functionally equivalent to setting the host with a higher weight, but may have some subtle effects on host selection beyond what weight alone can do; this is probably not worthwhile but is left in for the option.
+
+### `bad` Hosts
+
+As mentioned above under [Target Host Selection](#target-host-selection), a host can be marked `bad` if it does not respond to an `ffmpeg -version` command in at least 1 second if it is due to be checked as a target for a new `rffmpeg` alias process. This can happen because a host is offline, unreachable, overloaded, or otherwise unresponsive.
+
+Once a host is marked `bad`, it will remain so for as long as the `rffmpeg` process that marked it `bad` is running. This can last anywhere from a few seconds (library scan processes, image extraction) to several tens of minutes (a long video transcode). During this time, any new `rffmpeg` processes that start will see that the host is marked as `bad` and thus skip it for target selection. Once the marking `rffmpeg` process completes or is terminated, the `bad` status of that host will be cleared, allowing the next run to try it again. This strikes a balance between always retrying known-unresponsive hosts over and over (and thus delaying process startup), and ensuring that hosts will eventually be retried.
+
+If for some reason all configured hosts are marked `bad`, fallback will be engaged; see the above section [Localhost and Fallback](#localhost-and-fallback) for details on what occurs in this situation. An explicit `localhost` host entry cannot be marked `bad`.
 
 ## FAQ
 
-### Why did you make rffmpeg?
+### Why did you make `rffmpeg`?
 
-My virtualization setup (multiple 1U nodes with lots of live migration/failover) didn't lend itself well to passing a GPU into my Jellyfin VM, but I wanted to offload transcoding because doing 4K HEVC transcodes with a CPU performs horribly. I happened to have another machine (my "base" remote headless desktop/gaming server) which had a GPU, so I wanted to find a way to offload the transcoding to it. I came up with `rffmpeg` as a simple wrapper to the `ffmpeg` and `ffprobe` calls that Jellyfin (and Emby, and likely other media servers too) makes which would run them on that host instead. After finding it quite useful myself, I released it publicly as GPLv3 software so that others may benefit as well!
+My virtualization setup (multiple 1U nodes with lots of live migration/failover) didn't lend itself well to passing a GPU into my Jellyfin VM, but I wanted to offload transcoding because doing 4K HEVC transcodes with a CPU performs horribly. I happened to have another machine (my "base" remote headless desktop/gaming server) which had a GPU, so I wanted to find a way to offload the transcoding to it. I came up with `rffmpeg` as a simple wrapper to the `ffmpeg` and `ffprobe` calls that Jellyfin (and Emby, and likely other media servers too) makes which would run them on that host instead. After finding it quite useful myself, I released it publicly as GPLv3 software so that others may benefit as well! It has since received a lot of feedback and feature requests from the community, leading to the tool as it exists today.
 
 ### What supports `rffmpeg`?
 
 This depends on what "layer" you're asking at.
 
-* Media Servers: Jellyfin is officially supported; Emby seems to work fine, with caveats (see [Issue #10](https://github.com/joshuaboniface/rffmpeg/issues/10)); no others have been tested to my knowledge
-* Operating Systems (source): Debian and its derivatives (Ubuntu, Linux Mint, etc.) should all work perfectly; other Linux operating systems should work fine too as the principles are the same; MacOS should work since it has an SSH client built in; Windows might work if it has an SSH client installed
-* Operating Systems (target): Any Linux system which [`jellyfin-ffmpeg`](https://github.com/jellyfin/jellyfin-ffmpeg) supports, which is currently just Debian and Ubuntu; Windows *might* work if you can get an SSH server running on it (see [Issue #17](https://github.com/joshuaboniface/rffmpeg/issues/17))
-* Install Methods for Jellyfin: Native packages/installers/archives are recommended; Docker containers can be made to work by exporting the `/config` path (see [the setup guide](SETUP.md)) but this is slightly more difficult and is not explicitly covered in the guide
-* Install Methods for `rffmpeg`: Direct installation is recommended; a [Docker container to act as an ffmpeg transcode target](https://github.com/BasixKOR/rffmpeg-docker) has been created by @BasixKOR
+* Media Servers: Jellyfin is officially supported; Emby seems to work fine, with caveats (see [Issue #10](https://github.com/joshuaboniface/rffmpeg/issues/10)); no others have been tested to my knowledge.
+* Operating Systems (source): Debian and its derivatives (Ubuntu, Linux Mint, etc.) should all work perfectly; other Linux operating systems should work fine too as the principles are the same; MacOS should work since it has an SSH client built in; Windows will not work as `rffmpeg` depends on some POSIX assumptions internally.
+* Operating Systems (target): Any Linux system which [`jellyfin-ffmpeg`](https://github.com/jellyfin/jellyfin-ffmpeg) supports, which is currently just Debian and Ubuntu; Windows *might* work if you can get an SSH server running on it (see [Issue #17](https://github.com/joshuaboniface/rffmpeg/issues/17)).
+* Install Methods for Jellyfin: Native packages/installers/archives are recommended; a set of [Jellyfin Docker containers integrating `rffmpeg`](https://github.com/Shadowghost/jellyfin-rffmpeg) has been created by [@Shadowghost](https://github.com/Shadowghost). In addition to this special docker image you can use linuxserver's image with [this mod](https://github.com/linuxserver/docker-mods/tree/jellyfin-rffmpeg).
+* Install Methods for `rffmpeg`: Direct installation is recommended; a [Docker container to act as an ffmpeg transcode target](https://github.com/aleksasiriski/rffmpeg-worker) has been created by [@aleksasiriski](https://github.com/aleksasiriski) as well as [another](https://github.com/BasixKOR/rffmpeg-docker) by [@BasixKOR](https://github.com/BasixKOR).
+* OUTDATED Cloud: [HCloud Rffmpeg](https://github.com/aleksasiriski/hcloud-rffmpeg) script made to read rffmpeg database and spin up more transcode nodes in Hetzner Cloud.
+* Kubernetes: A short guide and example yaml files are available [here](https://github.com/aleksasiriski/rffmpeg-worker/tree/main/Kubernetes).
 
 ### Can `rffmpeg` mangle/alter FFMPEG arguments?
 
-Explicitly *no*. `rffmpeg` is not designed to interact with the arguments that the media server passes to `ffmpeg`/`ffprobe` at all, nor will it. This is an explicit design decision due to the massive complexity of FFMpeg - to do this, I would need to create a mapping of just about every possible FFMpeg argument, what it means, and when to turn it on or off, which is way out of scope.
+Explicitly *no*. `rffmpeg` is not designed to interact with the arguments that the media server passes to `ffmpeg`/`ffprobe` at all, nor will it.
 
-This has a number of side effects:
+This is an explicit design decision due to the massive complexity of FFmpeg. FFmpeg has a very large number of possible arguments, many of which are position-dependent or dependent on other arguments elsewhere in the chain. To implement argument mangling, we would need to be aware of every possible FFmpeg argument, exactly how each argument maps to each other argument, and be able to dynamically parse and update arguments based on this. As should hopefully be quite obvious, this is a massive undertaking and not something that I have any desire to implement or manage in such a (relatively) simple utility.
 
- * `rffmpeg` does not know whether hardware acceleration is turned on or not (see above caveats about localhost and fallback)
- * `rffmpeg` does not know what media is playing or where it's outputting files to, and cannot alter these paths
- * `rffmpeg` cannot turn on or off special `ffmpeg` options depending on the host selected
+This has a number of effects:
+
+ * `rffmpeg` cannot adjust any `ffmpeg` options based on the host selected.
+ * `rffmpeg` does not know whether hardware acceleration is turned on or not (see above caveats under [Hardware Acceleration](#hardware-acceleration)), or what type(s) of hardware acceleration are active.
+ * `rffmpeg` does not know what media file(s) is is handling or where it's outputting files to, and cannot alter these paths.
+
+Thus it is imperative that you set up your entire system correctly for `rffmpeg` to work using a "least-common-denominator" approach as required. Please see the [SETUP guide](SETUP.md) for more information.
 
 ### Can `rffmpeg` do Wake-On-LAN or other similar options to turn on a transcode server?
 
-Right now, no. I've thought about implementing this more than once (most recently, in response to [Issue #21](https://github.com/joshuaboniface/rffmpeg/issues/21)) but ultimately I've never though this was worth the complexity and delays in spwaning that it would add to the tool. That issue does provide one example of a workaround wrapper script that could accomplish this, but I don't see it being a part of the actual tool itself.
+Explicitly *no*, though the linuxserver.io [docker mod](https://github.com/linuxserver/docker-mods/tree/jellyfin-rffmpeg) does support this.
+
+I've thought about implementing this more than once (most recently, in response to [Issue #21](https://github.com/joshuaboniface/rffmpeg/issues/21)) but ultimately I do not believe this is worth the complexity and delays it would introduce when spawning processes. That issue does provide one example of a workaround wrapper script that could accomplish this, but I do not plan for it to be a part of `rffmpeg` itself.
 
 ### I'm getting an error, help!
 
@@ -144,20 +172,28 @@ First, run though the setup guide again and make sure that everything is set up
 
 If the problem persists, please check the [closed issues](https://github.com/joshuaboniface/rffmpeg/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed) and see if it's been reported before (if it's regarding Emby and you get an "error 127", see [Issue #10](https://github.com/joshuaboniface/rffmpeg/issues/10)).
 
-If it hasn't, please open a new issue. Ensure you:
+If it hasn't, you can [ask in our chat](https://matrix.to/#/#rffmpeg:matrix.org) or open a new issue. Ensure you:
 
-1. Use a descriptive and useful title that quickly explains the problem.
+1. Enable debug logging in `rffmpeg.yml` (`logging` -> `debug` to `true`) and re-run any failing or incorrect command(s) to obtain debug-level logs for analysis.
 
-1. Clearly explain in the body of the issue your setup, what is going wrong, and what you expect should be happening. Don't fret if English isn't your first language or anything like that, as long as you are trying to be clear that's what counts!
+1. For issues, use a descriptive and useful title that quickly explains the problem.
 
-1. Include your `rffmpeg.log` and Jellyfin/Emby `ffmpeg-transcode-*.txt` logs.
+1. Clearly explain (in the body of the issue or in your chat message) your setup, what is going wrong, and what you expect should be happening. Don't fret if English isn't your first language or anything like that, as long as you are trying to be clear that's what counts!
+
+1. Include your `rffmpeg.log` and Jellyfin/Emby transcode logs as these are absolutely critical in determining what is going on. Use triple-backticks ("```") to enclose logs inline, both in chat and in issues.
 
 I will probably ask clarifying questions as required; please be prepared to run test commands, etc. as requested and paste the output.
 
-### I found a bug/flaw and fixed or, or made a feature improvement; can I share it?
+### I found a bug/flaw and fixed it, or made a feature improvement; can I share it?
 
-Absolutely - I'm happy to take pull requests. Though please refer to the "Can `rffmpeg` mangle/alter FFMPEG arguments?" entry above; unless it's really good work with a very explicitly defined limitation, I probably don't want to go down that route, but I'm more than willing to look at what you've done and consider it on its merits.
+Absolutely - I'm happy to take pull requests for just about any bugfix or improvement. There is one exception: please refer to the "Can `rffmpeg` mangle/alter FFMPEG arguments?" entry above; unless it's really good work with a very explicitly defined limitation, I probably don't want to go down that route, but I'm more than willing to look at what you've done and consider it on its merits.
 
 ### Can you help me set up my server?
 
-I'm always happy to help, though please ensure you try to follow the setup guide first. I can be found [on Matrix](https://matrix.to/#/@joshuaboniface:bonifacelabs.ca) or via email at `joshua@boniface.me`. Please note though that I may be unresponsive sometimes, though I will get back to you eventually I promise! Please don't open Issues here about setup problems; the Issue tracker is for bugs or feature requests instead.
+I'm always happy to help, though please ensure you try to follow the setup guide first - that's why I wrote it! Support can be found [on Matrix](https://matrix.to/#/#rffmpeg:matrix.org) or via email at `joshua@boniface.me`. Please note though that I may be unresponsive sometimes, though I will get back to you eventually I promise! Please don't open Issues here about setup problems; the Issue tracker is for bugs or feature requests instead.
+
+### `rffmpeg-go` - forked project
+
+NOTICE: project was archived in Oct 27, 2024.
+
+There's also a [fork of this script written in Go](https://github.com/aleksasiriski/rffmpeg-go) with semver tags and binaries available, as well as docker images for both the [script](https://github.com/aleksasiriski/rffmpeg-go/pkgs/container/rffmpeg-go) and [Jellyfin](https://github.com/aleksasiriski/jellyfin-rffmpeg).

SETUP.md

@@ -1,242 +0,0 @@
-# Example Setup Guide
-
-This example setup is the one I use for `rffmpeg` with Jellyfin. It uses 2 servers: a media server running Jellyfin called `jellyfin1`, and a remote transcode server called `transcode1`. Both systems run Debian GNU/Linux, though the commands below should also work on Ubuntu. Throughout this guide I assume you are running as an unprivileged user with `sudo` privileges.
-
-This guide is provided as a basic starting point - there are myriad possible combinations of systems, and I try to keep `rffmpeg` quite flexible. Feel free to experiment.
-
-## Set up the media server (`jellyfin1`)
-
-1. Install Jellyfin (or similar FFMPEG-using media server) on your machine. This guide assumes you're using native `.deb` packages.
-
-1. Make note of the Jellyfin service user's details, specifically the UID and any groups (and GIDs) it is a member of; this will be needed later on.
-
-   ```
-   jellyfin1 $ id jellyfin
-   uid=110(jellyfin) gid=117(jellyfin) groups=117(jellyfin)
-   ```
-
-1. Make note of the Jellyfin data path; this will be needed later on. By default when using native OS packages, this is `/var/lib/jellyfin`. If you choose to move this directory, do so now (I personally use `/srv/jellyfin` but this guide will assume the default).
-
-   To make life easier below, you can store this in a variable that I will reference frequently later:
-
-   ```
-   jellyfin1 $ export jellyfin_data_path="/var/lib/jellyfin"
-   transcode1 $ export jellyfin_data_path="/var/lib/jellyfin"
-   ```
-
-   The important subdirectories for `rffmpeg`'s operation are:
-
-   * `transcodes/`: used to store on-the-fly transcoding files, and configurable separately in Jellyfin but with `rffmpeg` I recommend leaving it at the default location under the data path.
-   * `data/subtitles/`: used to store on-the-fly extracted subtitles so that they can be reused later.
-   * `.ssh/`: This doesn't exist yet but will after the next step.
-
-1. Create an SSH keypair to use for `rffmpeg`'s login to the remote server. For ease of use with the following steps, use the Jellyfin service user (`jellyfin`) to create the keypair and store it under its home directory (the Jellyfin data path above). I use `rsa` here but you can substitute `ed25519` instead (avoid `dsa` and `ecdsa` for reasons I won't get into here). Once done, copy the public key to `authorized_keys` which will be used to authenticate the key later.
- 
-   ```
-   jellyfin1 $ sudo -u jellyfin mkdir ${jellyfin_data_path}/.ssh
-   jellyfin1 $ sudo chmod 700 ${jellyfin_data_path}/.ssh
-   jellyfin1 $ export keytype="rsa"
-   jellyfin1 $ sudo -u jellyfin ssh-keygen -t ${keytype} -f ${jellyfin_data_path}/.ssh/id_${keytype}
-   jellyfin1 $ sudo -u jellyfin cp -a ${jellyfin_data_path}/.ssh/id_${keytype}.pub ${jellyfin_data_path}/.ssh/authorized_keys
-   ```
-
-1. Scan and save the SSH host key of the transcode server(s), to avoid a prompt later:
-
-   ```
-   jellyfin1 $ ssh-keyscan transcode1 | sudo -u jellyfin tee -a ${jellyfin_data_path}/.ssh/known_hosts
-   ```
-
-   * **NOTE:** Ensure you use the exact name here that you will use in `rffmpeg.yml` in the next step. If this is an FQDN (e.g. `jellyfin1.mydomain.tld`) or an IP (e.g. `192.168.0.101`) instead of a short name, use that instead in this command, or repeat it for every possible option (it doesn't hurt).
-
-1. Install the required dependencies of `rffmpeg`:
-
-   ```
-   jellyfin1 $ sudo apt -y install python3-yaml
-   jellyfin1 $ sudo apt -y install python3-subprocess
-   ```
-
-   Note: On some Ubuntu versions, `python3-subprocess` does not exist, and should instead be part of the Python standard library. Skip installing this package if it can't be found.
-
-1. Clone the `rffmpeg` repository somewhere ont he system, then install the `rffmpeg` binary, make it executable, and prepare symlinks for the command names `ffmpeg` and `ffprobe` to it. I recommend storing these in `/usr/local/bin` for simplicity.
-
-   ```
-   jellyfin1 $ git clone https://github.com/joshuaboniface/rffmpeg  # or download the files manually
-   jellyfin1 $ sudo cp rffmpeg/rffmpeg.py /usr/local/bin/rffmpeg.py
-   jellyfin1 $ sudo chmod +x /usr/local/bin/rffmpeg.py
-   jellyfin1 $ sudo ln -s /usr/local/bin/rffmpeg.py /usr/local/bin/ffmpeg
-   jellyfin1 $ sudo ln -s /usr/local/bin/rffmpeg.py /usr/local/bin/ffprobe
-   ```
-
-1. Create a directory for the `rffmpeg` configuration at `/etc/rffmpeg`, then copy `rffmpeg.yml.sample` to `/etc/rffmpeg/rffmpeg.yml` and edit it to suit your needs.
-   ```
-   jellyfin1 $ sudo mkdir -p /etc/rffmpeg
-   jellyfin1 $ sudo cp rffmpeg/rffmpeg.yml.sample /etc/rffmpeg/rffmpeg.yml
-   jellyfin1 $ sudo $EDITOR /etc/rffmpeg/rffmpeg.yml  # edit it to suit your needs
-   ```
-
-   Generally, if you're following this guide exactly, the only part that needs to be modified is the `rffmpeg` -> `remote` -> `hosts` section, where you define the target hosts. For more detail on weights, see the main [README.md](README.md#remote-hosts).
-
-1. Install the NFS kernel server. We will use NFS to export the various required directories so the transcode machine can read from and write to them.
-
-   ```
-   jellyfin1 $ sudo apt -y install nfs-kernel-server
-   ```
-
-1. Create an `/etc/exports` configuration. What to put here can vary a lot, but here are some important points:
-
-   * Always export the `${jellyfin_data_path}` in full. Advanced users might be able to export the required subdirectories individually, but I find this to be not worth the hassle.
-   * Note the security options of NFS. It will limit mounts to the IP addresses specified. If your home network is secure, you can use the entire network, e.g. `192.168.0.0/24`, but I would recommend determining the exact IP of your transcode server(s) and use them explicitly, e.g. for this example `192.168.0.101` and `192.168.0.102`.
-   * The `sync` option is very important here. Jellyfin (and presumably Emby) determines that the next chunk is ready by waiting on inotifies in this directory (I think). Thus, we'd want the client to always do an `fsync` call after every write or the server might miss chunks which results in poor playback performance.
-   * For the above reason, it's also very important that you export *from* the Jellyfin server and not from the transcode server.
-   * If your media is local to the Jellyfin server (and not otherwise mounted via a remote filesystems like NFS, Samba, CephFS, etc.), also add an export for it as well.
-
-   An example `/etc/exports` file would look like this:
-
-   ```
-   # /etc/exports: the access control list for filesystems which may be exported
-   #               to NFS clients.  See exports(5).
-   #
-   # Other examples removed
-
-   # jellyfin_data_path   first host                                                  second host, etc.
-   /var/lib/jellyfin      192.168.0.101/32(rw,sync,no_subtree_check,no_root_squash)   192.168.0.102(rw,sync,no_subtree_check,no_root_squash) 
-   ```
-
-1. Reload the exports file and ensure the NFS server is properly exporting it now:
-
-   ```
-   jellyfin1 $ sudo exportfs -arfv
-   jellyfin1 $ sudo exportfs
-   /var/lib/jellyfin   192.168.0.101/32
-   /var/lib/jellyfin   192.168.0.102/32
-   ```
-
-## Set up the transcode server (`transcode1`)
-
-1. Install and configure anything you need for hardware transcoding, if applicable. For example GPU drivers if using a GPU for transcoding.
-
-   * **NOTE:** Make sure you understand the caveats of using hardware transcoding with `rffmpeg` from the main README if you do decide to go this route.
-
-1. Install the `jellyfin-ffmpeg` (Jellyfin <= 10.7.7) or `jellyfin-ffmpeg5` (Jellyfin >= 10.8.0) package; follow the same steps as you would to install Jellyfin on the media server, only don't install `jellyfin` (and `jellyfin-server`/`jellyfin-web`) itself, just `jellyfin-ffmpeg[5]`.
-
-1. Install the NFS client utilities:
-
-   ```
-   transcode1 $ sudo apt install -y nfs-common
-   ```
-
-1. Create the Jellyfin service user and its default group; ensure you use the exact same UID and GID values you found in the beginning of the last section and adjust the example here to match yours:
-
-   ```
-   transcode1 $ sudo groupadd --gid 117 jellyfin
-   transcode1 $ sudo useradd --uid 110 --gid jellyfin --shell /bin/bash --no-create-home --home-dir ${jellyfin_data_path} jellyfin
-   ```
-
-   * **NOTE:** For some hardware acceleration, you might need to add this user to additional groups. For example `--groups video,render`.
-
-   * **NOTE:** The UID and GIDs here are dynamic; on the `jellyfin1` machine, they would have been created at install time with the next available ID in the range 100-199 (at least in Debian/Ubuntu). However, this means that the exact UID of your Jellyfin service user might not be available on your transcode server, depending on what packages are installed and in what order. If there is a conflict, you must adjust user IDs on one side or the other so that they match on both machines. You can use `sudo usermod` to change a user's ID if required.
-
-1. Create the Jellyfin data directory at the same location as on the media server, and set it immutable so that it won't be written to if the NFS mount goes down:
-
-   ```
-   transcode1 $ sudo mkdir ${jellyfin_data_path}
-   transcode1 $ sudo chattr +i ${jellyfin_data_path}
-   ```
-
-   * Don't worry about permissions here; the mount will set those.
-
-1. Create the NFS client mount. There are two main ways to do this:
-
-   * Use the traditional `/etc/fstab` by adding a new entry like so, replacing the paths and hostname as required, and then mounting it:
-
-   ```
-   transcode1 $ echo "jellyfin1:${jellyfin_data_path} ${jellyfin_data_path} nfs defaults,vers=3,sync" | sudo tee -a /etc/fstab
-   transcode1 $ sudo mount ${jellyfin_data_path}
-   ```
-
-   * Use a SystemD `mount` unit, which is a newer way of doing mounts with SystemD. I personally prefer this method as I find it easier to set up automatically, but this is up to preference. An example based on mine would be:
-
-   ```
-   transcode1 $ cat /etc/systemd/system/var-lib-jellyfin.mount
-   [Unit]
-   Description = NFS volume for Jellyfin data directory
-   Requires = network-online.target
-   After = network-online.target
-
-   [Mount]
-   type = nfs
-   What = jellyfin1:/var/lib/jellyfin
-   Where = /var/lib/jellyfin
-   Options = _netdev,sync,vers=3
-
-   [Install]
-   WantedBy = remote-fs.target
-   ```
-
-   Once the unit file is created, you can then reload the unit list and mount it:
-
-   ```
-   transcode1 $ sudo systemctl daemon-reload
-   transcode1 $ sudo systemctl start var-lib-jellyfin.mount
-   ```
-
-   Note that mount units are fairly "new" and can be a bit finicky, be sure to read the SystemD documentation if you get stuck! Generally for new users, I'd recommend the `/etc/fstab` method instead.
-
-1. Mount your media directories in the same location(s) as on the media server. If you exported them via NFS from your media server, use the process above only for those directories instead.
-
-## Test the setup
-
-1. On the media server, verify that SSH as the Jellyfin service user is working as expected to each transcoding server:
-
-   ```
-   jellyfin1 $ sudo -u jellyfin ssh -i ${jellyfin_data_path}/.ssh/id_rsa jellyfin@transcode1 uname -a
-   Linux transcode1 [...]
-   ```
-
-1. Validate that `rffmpeg` itself is working by calling its `ffmpeg` and `ffprobe` aliases with the `-version` option:
-
-   ```
-   jellyfin1 $ sudo -u jellyfin /usr/local/bin/ffmpeg -version
-   ffmpeg version 5.0.1-Jellyfin Copyright (c) 2000-2022 the FFmpeg developers
-   built with gcc 10 (Debian 10.2.1-6)
-   [...]
-   jellyfin1 $ sudo -u jellyfin /usr/local/bin/ffprobe -version
-   ffprobe version 5.0.1-Jellyfin Copyright (c) 2007-2022 the FFmpeg developers
-   built with gcc 10 (Debian 10.2.1-6)
-   [...]
-   ```
-
-As long as these steps work, all further steps should as well.
-
-## Configure Jellyfin
-
-1. In the Hamburger Menu -> Administration -> Dashboard, navigate to Playback.
-
-1. Configure any hardware acceleration you require and have set up on the remote server(s).
-
-1. Under "FFmpeg path:", enter `/usr/local/bin/ffmpeg`.
-
-1. Save the settings.
-
-1. Try to play a movie that requires transcoding, and verify that everything is working as expected.
-
-## NOTE for NVEnv/NVDec HWA
-
-If you are using NVEnv/NVDec, it's probably a good idea to symlink the `.nv` folder inside the Jellyfin user's homedir (i.e. `/var/lib/jellyfin/.nv`) to somewhere outside of the NFS volume on both sides. For example:
-
-   ```
-   jellyfin1  $ sudo mv /var/lib/jellyfin/.nv /var/lib/nvidia-cache  # or "sudo mkdir /var/lib/nvidia-cache" and "sudo chown jellyfin /var/lib/nvidia-cache" if it does not yet exist
-   jellyfin1  $ sudo ln -s /var/lib/nvidia-cache /var/lib/jellyfin/.nv
-   transcode1 $ sudo mkdir /var/lib/nvidia-cache
-   transcode1 $ sudo chown jellyfin /var/lib/nvidia-cache
-   transcode1 $ ls -alh /var/lib/jellyfin
-   [...]
-   lrwxrwxrwx  1 root     root         17 Jun 11 15:51 .nv -> /var/lib/nvidia-cache
-   [...]
-   ```
-
-Be sure to adjust these paths to match your Jellyfin setup. The name of the target doesn't matter too much, as long as `.nv` inside the homedir is symlinked to it and it is owned by the `jellyfin` service user.
-
-This is because some functions of FFMpeg's NVEnc/NVDec stack - specifically the `scale_cuda` and `tonemap_cuda` filters - leverage this directory to cache their JIT codes, and this can result in very slow startup times and very poor transcoding performance due to NFS locking issues. See https://developer.nvidia.com/blog/cuda-pro-tip-understand-fat-binaries-jit-caching/ for further information.
-
-Alternatively, based on that link, you might also be able to experiment with the environment variables that control the JIT caching to move it somewhere else, but this has not been tested by the author. Feel free to experiment and find the best solution for your setup.

docs/HARDENING

@@ -0,0 +1,92 @@
+
+*NOTICE* Do not do these tasks until you have a verified working solution
+
+These were tested and validated on Ubuntu 24.04 LTS, 2025-11-03
+
+# Hardening
+
+- Access for jellyfin user will be limited to jellyfin1 server only
+- Commands that jellyfin user can run will be limited to ffmpeg only
+- Commands run by jellyfin user will be logged
+    - (optional) Logs stored in separate log file
+
+## Prerequisites
+
+- static IP on the jellyfin1 server
+
+## Configure SSH server
+
+SSH server configuration is formed out of two files
+
+1. `10-jellyfin-limits.conf` - SSH config
+2. `limited-wrapper.sh` or `limited-wrapper.py` - a script to limit what commands can be run
+
+### 10-jellyfin-limits.conf
+
+This config file does few things
+- allows only jellyfin user to SSH from jellyfin server
+- limits jellyfin user login options to be only from jellyfin server
+- limits the commands jellyfin user can run to `limited-wrapper.py`
+
+1. Copy `10-jellyfin-limits.conf` to `/etc/ssh/sshd_config.d`
+2. Update the IP of the jellyfin server to the file
+3. Restart ssh
+    ```bash
+    sudo systemctl restart ssh
+    ```
+
+### limited-wrapper.sh and limited-wrapper.py
+
+This file analyses what commands are being run over SSH and limits them
+to the ones we defined.
+
+1. Update the ALLOWED list to match your `ffmpeg` file locations in the script
+2. Copy the script to `/usr/local/bin/limited-wrapper.py` and allow only root to modify it
+    ```bash
+    sudo chwon root:root /usr/local/bin/limited-wrapper.py &&\
+    sudo chmod 755 /usr/local/bin/limited-wrapper.py
+    ```
+### Test configuration
+
+1. Login to your jellyfin1 server and run
+    ```bash
+    sudo -u jellyfin ssh jellyfin@transcode1 /usr/bin/ffmpeg
+    ```
+   command should succeed and print out ffmpeg info
+
+2. Run a command that should fail
+
+    ```bash
+    sudo -u jellyfin ssh jellyfin@transcode1 uname -a
+    ```
+    command should fail and you should see `ERROR: command not allowed.`
+
+
+### Troubleshooting
+
+#### Permission denied (publickey)
+
+1. check your auth.log
+you should see the IP you are connecting from, make sure it is the same as in your `10-jellyfin-limits.conf` -file.
+
+## Logging
+
+All commands run by the jellyfin user are logged to standard syslog (via logger). They can be extracted to their own file.
+
+### rsyslog config
+
+File `limited-wrapper-log.conf` creates a rsyslog config to redirect the log entries to a separate file
+
+1. Update the `limited-wrapper-log.conf` file with the log file name you want. Default is `/var/log/jellyfin_commands.log`
+2. Copy the file to /etc/rsyslog.d/
+3. Correct the file rights
+    ```bash
+    sudo chown root:root /etc/rsyslog.d/limited-wrapper-log.conf &&\
+    sudo chmod 644 /etc/rsyslog.d/limited-wrapper-log.conf
+    ```
+4. Create the log file
+    ```bash
+    sudo touch /var/log/jellyfin_commands.log &&\
+    sudo chown syslog:adm /var/log/jellyfin_commands.log &&\
+    sudo chmod 664 /var/log/jellyfin_commands.log
+    ```

docs/SETUP.md

@@ -0,0 +1,339 @@
+# Example Setup Guide
+
+This example setup is the one I use for `rffmpeg` with Jellyfin. It uses 2 servers: a media server running Jellyfin called `jellyfin1`, and a remote transcode server called `transcode1`. Both systems run Debian GNU/Linux, though the commands below should also work on Ubuntu. Throughout this guide I assume you are running as an unprivileged user with `sudo` privileges (i.e. in the group `sudo`). Basic knowledge of Linux CLI usage is assumed. Whenever a verbatim command is specified, it will be prefixed by the relevant host to run it on (either `jellyfin1` or `transcode1`) and then a `$` prompt indicator. Any command output is usually not shown unless it is relevant.
+
+This guide is provided as a basic starting point - there are myriad possible combinations of systems, and I try to keep `rffmpeg` quite flexible. Feel free to experiment.
+
+## Set up the media server (`jellyfin1`)
+
+### Basic Setup
+
+1. Install Jellyfin (or similar FFMPEG-using media server) on your machine. This guide assumes you're using native `.deb` packages.
+
+1. Make note of the Jellyfin service user's details, specifically the UID and any groups (and GIDs) it is a member of; this will be needed later on.
+
+#### jellyfin1
+   ```bash
+   id jellyfin
+   # should output 
+   # uid=110(jellyfin) gid=117(jellyfin) groups=117(jellyfin)
+   ```
+
+1. Make note of the Jellyfin data path; this will be needed later on. By default when using native OS packages, this is `/var/lib/jellyfin`. If you choose to move this directory, do so now (I personally use `/srv/jellyfin` but this guide will assume the default).
+
+   To make life easier below, you can store this in a variable that I will reference frequently later:
+
+   ```bash
+   export jellyfin_data_path="/var/lib/jellyfin"
+   export jellyfin_cache_path="/var/cache/jellyfin"
+   ```
+
+   The important subdirectories for `rffmpeg`'s operation are:
+
+   * `$jellyfin_cache_path/`: Used to store cached extracted data.
+   * `$jellyfin_cache_path/transcodes/`: Used to store on-the-fly transcoding files, and configurable separately in Jellyfin but with `rffmpeg` I recommend leaving it at the default location under the cache path.
+   * `$jellyfin_data_path/data/subtitles/`: Used to store on-the-fly extracted subtitles so that they can be reused later.
+   * `$jellyfin_data_path/.ssh/`: This doesn't exist yet but will after the next step.
+
+   **NOTE:** On Docker, these directories are different. The main data directory (our `jellyfin_data_path`) is `/config`, and the cache directory is separate at `/cache`. Both must be exported and mounted on targets for proper operation.
+
+   **NOTE:** On Jellyfin 10.10.x and newer, temporary transient files were moved into the system temporary storage path (on Linux, usually `/tmp`). This will break rffmpeg for certain tasks that use these files, for instance trickplay generation. To restore the previous behaviour, ensure you set the `TMPDIR` environment variable for your Jellyfin service to a path under the data path above, for example `/var/lib/jellyfin/temp`, and create this directory with correct ownership and permissions.
+
+1. Create an SSH keypair to use for `rffmpeg`'s login to the remote server. For ease of use with the following steps, use the Jellyfin service user (`jellyfin`) to create the keypair and store it under its home directory (the Jellyfin data path above). I use `rsa` here but you can substitute `ed25519` instead (avoid `dsa` and `ecdsa` for reasons I won't get into here). Once done, copy the public key to `authorized_keys` which will be used to authenticate the key later.
+
+   ```bash
+   export keytype="rsa" &&\
+   sudo -u jellyfin mkdir ${jellyfin_data_path}/.ssh &&\
+   sudo chmod 700 ${jellyfin_data_path}/.ssh &&\
+   sudo -u jellyfin ssh-keygen -t ${keytype} -f ${jellyfin_data_path}/.ssh/id_${keytype} &&\
+   sudo -u jellyfin cp -a ${jellyfin_data_path}/.ssh/id_${keytype}.pub ${jellyfin_data_path}/.ssh/authorized_keys
+   ```
+
+   It is important that you do not alter the permissions under this `.ssh` directory or this can cause SSH to fail later. The SSH *must* occur as the `jellyfin` user for this to work.
+
+1. Scan and save the SSH host key of the transcode server(s), to avoid a prompt later:
+
+   ```bash
+   ssh-keyscan transcode1 | sudo -u jellyfin tee -a ${jellyfin_data_path}/.ssh/known_hosts
+   ```
+
+   * **NOTE:** Ensure you use the exact name here that you will use in `rffmpeg`. If this is an FQDN (e.g. `jellyfin1.mydomain.tld`) or an IP (e.g. `192.168.0.101`) instead of a short name, use that instead in this command, or repeat it for every possible option (it doesn't hurt).
+
+### `rffmpeg` Setup
+
+1. Install the required Python3 dependencies of `rffmpeg`:
+
+   ```bash
+   sudo apt -y install python3-yaml python3-click python3-subprocess
+   ```
+
+   * **NOTE:** On some Ubuntu versions, `python3-subprocess` does not exist, and should instead be part of the Python standard library. Skip installing this package if it can't be found.
+
+2. Clone the `rffmpeg` repository somewhere onto the system, then install the `rffmpeg` binary, make it executable, and prepare symlinks for the command names `ffmpeg` and `ffprobe` to it. I recommend storing these in `/usr/local/bin` for simplicity and so that they are present on the default `$PATH` for most users.
+
+   ```bash
+   git clone https://github.com/joshuaboniface/rffmpeg # or download the files manually
+   sudo cp rffmpeg/rffmpeg /usr/local/bin/rffmpeg &&\
+   sudo chmod +x /usr/local/bin/rffmpeg &&\
+   sudo ln -s /usr/local/bin/rffmpeg /usr/local/bin/ffmpeg &&\
+   sudo ln -s /usr/local/bin/rffmpeg /usr/local/bin/ffprobe
+   ```
+
+3. Optional: Create a directory for the `rffmpeg` configuration at `/etc/rffmpeg`, then copy `rffmpeg.yml.sample` to `/etc/rffmpeg/rffmpeg.yml` and edit it to suit your needs if required. Generally, if you're following this guide exactly, you will not need to install this file or adjust anything in in it. If you do require help though, I require debug logging to be enabled via the configuration file, so it's probably best to get this out of the way when installing `rffmpeg`:
+
+   ```bash
+   sudo mkdir -p /etc/rffmpeg &&\
+   sudo cp rffmpeg/rffmpeg.yml.sample /etc/rffmpeg/rffmpeg.yml &&\
+   sudo $EDITOR /etc/rffmpeg/rffmpeg.yml  # if required
+   ```
+
+5. Initialize `rffmpeg` (note the `sudo` command) and add at the target host to it. You can add other hosts now or later, and set weights of hosts, if required; for full details see the [main README](../README.md) or run `rffmpeg --help` to view the CLI help menu.
+
+   ```bash
+   sudo rffmpeg init --yes &&\
+   rffmpeg add --weight 1 transcode1
+   ```
+
+### NFS Setup
+
+* **WARNING:** This guide assumes your hosts are on the same private local network. It is not recommended to run NFS over the Internet as it is unencrypted, and any rffmpeg connection will be very bandwidth-intensive. If you must have both systems in separate networks, consider other remote filesystems like SSHFS in such cases as these will offer greater privacy and robustness.
+
+1. Install the NFS kernel server. We will use NFS to export the various required directories so the transcode machine can read from and write to them.
+
+   ```bash
+   sudo apt -y install nfs-kernel-server
+   ```
+
+2. Create an `/etc/exports` configuration. What to put here can vary a lot, but here are some important points:
+
+   * Always export the `${jellyfin_data_path}` in full. Advanced users might be able to export the required subdirectories individually, but I find this to be not worth the hassle.
+   * Note the security options of NFS. It will limit mounts to the IP addresses specified. If your home network is secure, you can use the entire network, e.g. `192.168.0.0/24`, but I would recommend determining the exact IP of your transcode server(s) and use them explicitly, e.g. for this example `192.168.0.101` and `192.168.0.102`.
+   * If your `transcodes` directory is not on a **native Linux filesystem** (i.e. external to Jellyfin, such as on a NAS exported by NFS, SMB, etc.), then you may experience delays of ~15-60s when playback starts. This is because NFS uses a file attribute cache that in most applications greatly increases performance, however for this usecase it causes a delay in Jellyfin seeing the `.ts` files. The solution for this is to reduce the NFS cache time by adding `sync` and `actimeo=1` to your NFS mount(s) (command or fstab), which will set the NFS file attribute cache to 1 second (reducing the NFS delay to ~1-2 seconds). This time can be further reduced to 0 by setting the `noac` option, but this is not normally recommended because it will negatively impact the performance other NFS applications. Verify that your mount added the `actimeo=1` parameter correctly by checking `mount` or `cat /proc/mounts`, which will show `sync,acregmin=1,acregmax=1,acdirmin=1,acdirmax=1` as parameters for your `transcodes` mount. 
+   * If your media is local to the Jellyfin server (and not already mountable on the transcode host(s) via a remote filesystems like NFS, Samba, CephFS, etc.), also add an export for it as well.
+
+   An example `/etc/exports` file would look like this:
+
+   ```text
+   # /etc/exports: the access control list for filesystems which may be exported
+   #               to NFS clients.  See exports(5).
+   #
+   # Other examples removed
+
+   # jellyfin_data_path   first host                                                  second host, etc.
+   /var/lib/jellyfin      192.168.0.101/32(rw,sync,no_subtree_check,no_root_squash)   192.168.0.102/32(rw,sync,no_subtree_check,no_root_squash)
+   # jellyfin_cache_path  first host                                                  second host, etc.
+   /var/cache/jellyfin    192.168.0.101/32(rw,sync,no_subtree_check,no_root_squash)   192.168.0.102/32(rw,sync,no_subtree_check,no_root_squash)
+   # Local media path if required
+   /srv/mymedia           192.168.0.101/32(rw,sync,no_subtree_check,no_root_squash)   192.168.0.102/32(rw,sync,no_subtree_check,no_root_squash)
+   ```
+
+3. Reload the exports file and ensure the NFS server is properly exporting it now:
+
+   ```bash
+   sudo exportfs -arfv
+   sudo exportfs
+   ```
+   should output something like
+   ```text
+   /var/lib/jellyfin   192.168.0.101/32
+   /var/lib/jellyfin   192.168.0.102/32
+   /var/cache/jellyfin 192.168.0.101/32
+   /var/cache/jellyfin 192.168.0.102/32
+   ```
+
+## Set up the transcode server (`transcode1`)
+
+setup the temporary convenience variables
+
+```bash
+export jellyfin_data_path="/var/lib/jellyfin"
+export jellyfin_cache_path="/var/cache/jellyfin"
+```
+
+1. Install and configure anything you need for hardware transcoding, if applicable. For example GPU drivers if using a GPU for transcoding.
+
+   * **NOTE:** Make sure you understand the caveats of using hardware transcoding with `rffmpeg` from [the main README](../README.md#hardware-acceleration).
+
+2. Install the correct `jellyfin-ffmpeg` package for your version of Jellyfin; check which version is installed on your `jellyfin1` system with `dpkg -l | grep jellyfin-ffmpeg`, then install that version on this host too; follow the same steps as you would to install Jellyfin on the media server, only don't install `jellyfin` (and `jellyfin-server`/`jellyfin-web`) itself, just the `jellyfin-ffmpeg` of the required version.
+
+   in jellyfin1
+   ```bash
+   dpkg -l | grep jellyfin-ffmpeg
+   #   ii  jellyfin-ffmpeg6                     6.0.1-8-bookworm                        amd64        Tools for transcoding, streaming and playing of multimedia files
+   ```
+   in transcode1
+   ```bash
+   sudo apt -y install curl gnupg &&\
+   curl -fsSL https://repo.jellyfin.org/ubuntu/jellyfin_team.gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/jellyfin.gpg &&\
+   echo "deb [arch=$( dpkg --print-architecture )] https://repo.jellyfin.org/$( awk -F'=' '/^ID=/{ print $NF }' /etc/os-release ) $( awk -F'=' '/^VERSION_CODENAME=/{ print $NF }' /etc/os-release ) main" | sudo tee /etc/apt/sources.list.d/jellyfin.list &&\
+   sudo apt update &&\
+   sudo apt install -y jellyfin-ffmpeg6
+   ```
+
+3. Install the NFS client utilities:
+
+   ```bash
+   sudo apt install -y nfs-common
+   ```
+
+4. Create the Jellyfin service user and its default group; ensure you use the exact same UID and GID values you found in the beginning of the last section and adjust the example here to match yours:
+
+   ```bash
+   sudo groupadd --gid 117 jellyfin &&\
+   sudo useradd --uid 110 --gid jellyfin --shell /bin/bash --no-create-home --home-dir ${jellyfin_data_path} jellyfin
+   ```
+
+   * **NOTE:** For some hardware acceleration, you might need to add this user to additional groups. For example `--groups video,render`.
+
+   * **NOTE:** The UID and GIDs here are dynamic; on the `jellyfin1` machine, they would have been selected automatically at install time with the next available ID in the range 100-199 (at least in Debian/Ubuntu). However, this means that the exact UID of your Jellyfin service user might not be available on your transcode server, depending on what packages are installed and in what order. If there is a conflict, you must adjust user IDs on one side or the other so that they match on both machines. You can use `sudo usermod` to change a user's ID if required.
+
+5. Create the Jellyfin directories at the same location as on the media server, and set it immutable so that it won't be written to if the NFS mount goes down:
+
+   ```bash
+   for file in ${jellyfin_data_path} ${jellyfin_cache_path}; do
+      sudo mkdir ${file} &&\
+      sudo chattr +i ${file}
+   done
+   ```
+
+   * **NOTE:** Don't worry about permissions here; the mount will set those.
+
+6. Create the NFS client mount. There are two main ways to do this:
+
+   * Use the traditional `/etc/fstab` by adding a new entry like so, replacing the paths and hostname as required, and then mounting it:
+
+      ```bash
+      echo "jellyfin1:${jellyfin_data_path} ${jellyfin_data_path} nfs defaults,vers=3,sync" | sudo tee -a /etc/fstab &&\
+      echo "jellyfin1:${jellyfin_cache_path} ${jellyfin_cache_path} nfs defaults,vers=3,sync" | sudo tee -a /etc/fstab &&\
+      sudo mount ${jellyfin_data_path} &&\
+      sudo mount ${jellyfin_cache_path}
+      ```
+
+   * Use a SystemD `mount` unit, which is a newer way of doing mounts with SystemD. I personally prefer this method as I find it easier to set up automatically, but this is up to preference. An example based on mine would be:
+
+      ```
+      transcode1 $ cat /etc/systemd/system/var-lib-jellyfin.mount
+      [Unit]
+      Description = NFS volume for Jellyfin data directory
+      Requires = network-online.target
+      After = network-online.target
+
+      [Mount]
+      type = nfs
+      What = jellyfin1:/var/lib/jellyfin
+      Where = /var/lib/jellyfin
+      Options = _netdev,sync,vers=3
+
+      [Install]
+      WantedBy = remote-fs.target
+      ```
+
+      ```
+      transcode1 $ cat /etc/systemd/system/var-cache-jellyfin.mount
+      [Unit]
+      Description = NFS volume for Jellyfin cache directory
+      Requires = network-online.target
+      After = network-online.target
+
+      [Mount]
+      type = nfs
+      What = jellyfin1:/var/cache/jellyfin
+      Where = /var/cache/jellyfin
+      Options = _netdev,sync,vers=3
+
+      [Install]
+      WantedBy = remote-fs.target
+      ```
+
+      Once the unit file is created, you can then reload the unit list and mount it:
+
+      ```bash
+      sudo systemctl daemon-reload &&\
+      sudo systemctl enable --now var-lib-jellyfin.mount &&\
+      sudo systemctl enable --now var-cache-jellyfin.mount
+      ```
+
+      Note that mount units are fairly "new" and can be a bit finicky, be sure to read the SystemD documentation if you get stuck! Generally for new users, I'd recommend the `/etc/fstab` method instead.
+
+    **NOTE:** Don't forget about `actimeo=1` here if you need it!
+
+7. Mount your media directories in the **same location(s)** as on the media server. If you exported them via NFS from your media server, use the process above only for those directories instead.
+
+## Test the setup
+
+1. On the media server, verify that SSH as the Jellyfin service user is working as expected to each transcoding server:
+
+   ```bash
+   sudo -u jellyfin ssh -i ${jellyfin_data_path}/.ssh/id_rsa jellyfin@transcode1 uname -a
+   # Linux transcode1 [...]
+   ```
+
+1. Validate that `rffmpeg` itself is working by calling its `ffmpeg` and `ffprobe` aliases with the `-version` option:
+
+   ```bash
+   sudo -u jellyfin /usr/local/bin/ffmpeg -version
+   # ffmpeg version 5.0.1-Jellyfin Copyright (c) 2000-2022 the FFmpeg developers
+   # built with gcc 10 (Debian 10.2.1-6)
+   # [...]
+   sudo -u jellyfin /usr/local/bin/ffprobe -version
+   # ffprobe version 5.0.1-Jellyfin Copyright (c) 2007-2022 the FFmpeg developers
+   # built with gcc 10 (Debian 10.2.1-6)
+   # [...]
+   ```
+
+As long as these steps work, all further steps should as well. If one of these *doesn't* work, double-check all previous steps and confirm that everything is set up right.
+
+## Configure Jellyfin to use `rffmpeg`
+
+**NOTE**: With Jellyfin 10.8.13 and newer, the ability to configure the `ffmpeg` path has been removed from the WebUI due to major security concerns. You must follow this method to change it.
+
+1. On the `jellyfin1` system, edit `/etc/default/jellyfin`:
+
+   ```bash
+   sudo $EDITOR /etc/default/jellyfin
+   ```
+
+1. Change the value of `JELLYFIN_FFMPEG_OPT` to be `--ffmpeg=/usr/local/bin/ffmpeg` (the `rffmpeg` alias name `ffmpeg` in whatever path you installed `rffmpeg` to).
+
+1. On Jellyfin 10.10.x or newer, add `TMPDIR=$jellyfin_cache_path/temp`, for instance `TMPDIR=/var/cache/jellyfin/temp`, to ensure this is properly synchronized over the network.
+
+1. Save the file and restart Jellyfin:
+
+   ```bash
+   sudo systemctl restart jellyfin
+   ```
+
+If you wish to use hardware transcoding, you must also enable it in Jellyfin's WebUI:
+
+1. Navigate to Hamburger Menu -> Administration -> Dashboard, navigate to Playback.
+
+1. Configure any hardware acceleration you require and have set up on the remote server(s).
+
+1. Save the settings.
+
+Now, run `rffmpeg log -f` on the `jellyfin1` machine and try to play a video that requires transcoding. You should see `rffmpeg` spawn a process on the `jellyfin1` machine, which then begins running the `ffmpeg` process on the `transcode1` machine, writing data to the configured paths, and playback should begin normally. If anything doesn't work, double-check all previous steps and confirm that everything is set up right.
+
+## NOTE for NVEnv/NVDec Hardware Acceleration
+
+If you are using NVEnv/NVDec, you will need to symlink the `.nv` folder inside the Jellyfin user's homedir (i.e. `/var/lib/jellyfin/.nv`) to somewhere outside of the NFS volume on both the Jellyfin and transcoding hosts. For example:
+
+on jellyfin1
+   ```bash
+   sudo mv /var/lib/jellyfin/.nv /var/lib/nvidia-cache  # or "sudo mkdir /var/lib/nvidia-cache" and "sudo chown jellyfin /var/lib/nvidia-cache" if it does not yet exist
+   sudo ln -s /var/lib/nvidia-cache /var/lib/jellyfin/.nv
+   ```
+   on transcode1
+   ```bash
+   sudo mkdir /var/lib/nvidia-cache
+   sudo chown jellyfin /var/lib/nvidia-cache
+   ls -alh /var/lib/jellyfin
+   #[...]
+   #lrwxrwxrwx  1 root     root         17 Jun 11 15:51 .nv -> /var/lib/nvidia-cache
+   #[...]
+   ```
+
+Be sure to adjust these paths to match your Jellyfin setup. The name of the target doesn't matter too much, as long as `.nv` inside the homedir is symlinked to it and it is owned by the `jellyfin` service user.
+
+This is because some functions of FFMpeg's NVEnc/NVDec stack - specifically the `scale_cuda` and `tonemap_cuda` filters - leverage this directory to cache their JIT codes, and this can result in very slow startup times and very poor transcoding performance due to NFS locking issues. See https://developer.nvidia.com/blog/cuda-pro-tip-understand-fat-binaries-jit-caching/ for further information.
+
+Alternatively, based on that link, you might also be able to experiment with the environment variables that control the JIT caching to move it somewhere else, but this has not been tested by the author. Feel free to experiment and find the best solution for your setup.

hardening/10-jellyfin-limits.conf

@@ -0,0 +1,13 @@
+# Limit jellyfin access
+# IPJELLYFIN is our Jellyfin server
+
+Match Address IPJELLYFIN
+    AllowUsers jellyfin@IPJELLYFIN
+
+Match User jellyfin, Address IPJELLYFIN
+    AllowUsers jellyfin@IPJELLYFIN
+    ForceCommand /usr/local/bin/limited-wrapper.py
+    PermitTTY no
+    X11Forwarding no
+    AllowAgentForwarding no
+    AllowTcpForwarding no

hardening/limited-wrapper-log.conf

@@ -0,0 +1,3 @@
+# Match the tag *including* the trailing colon
+:syslogtag, startswith, "limited-wrapper" /var/log/jellyfin_commands.log
+& stop

hardening/limited-wrapper.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""limited-wrapper.py
+
+Author: GPT-OSS:120b
+Version: 1.1.0
+Date: 2025-11-03
+
+Python 3 implementation of the limited-wrapper.sh script.
+It restricts SSH command execution to a whitelist of allowed binaries
+and logs activity either to the console (interactive) or to syslog.
+
+History
+   1.0.0 - 2025-11-03, initial version
+
+"""
+
+import os
+import sys
+import shlex
+import logging
+import logging.handlers
+from typing import List
+
+# ---------------------------------------------------------------------------
+# Logging utilities
+# ---------------------------------------------------------------------------
+
+def _setup_logger() -> logging.Logger:
+    logger = logging.getLogger("limited-wrapper.py")
+    logger.setLevel(logging.DEBUG)  # Capture all levels; handlers will filter
+    # Ensure no duplicate handlers if the module is reloaded
+    logger.handlers.clear()
+
+    if sys.stdout.isatty():
+        # Interactive TTY – simple console output without timestamp or level prefix
+        console = logging.StreamHandler(sys.stdout)
+        console.setLevel(logging.INFO)
+        console.setFormatter(logging.Formatter("%(message)s"))
+        logger.addHandler(console)
+    else:
+        # Non‑interactive – forward to syslog. Let syslog generate its own timestamp,
+        # hostname, and program identifier (the logger name). No extra formatter is
+        # needed to avoid adding the PID or duplicate timestamps.
+        try:
+            syslog = logging.handlers.SysLogHandler(address="/dev/log")
+        except OSError:
+            # Fallback for systems without /dev/log (e.g., macOS)
+            syslog = logging.handlers.SysLogHandler(address=("localhost", 514))
+        syslog.setLevel(logging.DEBUG)
+        # Prefix with logger name (script tag) to match original format
+        syslog.setFormatter(logging.Formatter("%(name)s: %(message)s"))
+        logger.addHandler(syslog)
+    return logger
+
+_logger = _setup_logger()
+
+
+def log_msg(level: str, *msg: str) -> None:
+    """Log a message with an explicit level prefix.
+
+    The original Bash implementation prefixed the log line with the level
+    (e.g. ``DEBUG`` or ``INFO``) before sending it to syslog. To preserve that
+    format we construct ``full_msg = f"{level.upper()} {text}"`` and log the
+    resulting string. This ensures syslog entries look like:
+    ``limited-wrapper.sh: DEBUG <message>`` while interactive console output
+    remains readable.
+    """
+    text = " ".join(msg)
+    level = level.upper()
+    full_msg = f"{level} {text}"
+    if level == "DEBUG":
+        _logger.debug(full_msg)
+    elif level == "INFO":
+        _logger.info(full_msg)
+    elif level in ("WARN", "WARNING"):
+        _logger.warning(full_msg)
+    elif level == "ERROR":
+        _logger.error(full_msg)
+    else:
+        _logger.info(full_msg)
+
+
+def log_debug(*msg: str) -> None:
+    log_msg("DEBUG", *msg)
+
+
+def log_info(*msg: str) -> None:
+    log_msg("INFO", *msg)
+
+
+def log_warn(*msg: str) -> None:
+    log_msg("WARN", *msg)
+
+
+def log_error(*msg: str) -> None:
+    log_msg("ERROR", *msg)
+
+# ---------------------------------------------------------------------------
+# Whitelist of absolute paths to allowed binaries
+# ---------------------------------------------------------------------------
+ALLOWED: List[str] = [
+    "/usr/bin/ffmpeg",
+    "/usr/bin/ffprobe",
+    "/usr/local/bin/ffmpeg",
+    "/usr/local/bin/ffprobe",
+    "/usr/lib/jellyfin-ffmpeg/ffmpeg",
+    "/usr/lib/jellyfin-ffmpeg/ffprobe",
+]
+
+
+def main() -> None:
+    req_cmd = os.getenv("SSH_ORIGINAL_COMMAND", "")
+    if not req_cmd:
+        # No command supplied – show the whitelist and exit successfully
+        print("You may run only: " + " ".join(ALLOWED))
+        sys.exit(0)
+
+    # Parse the command string respecting shell quoting (handles spaces in arguments)
+    # Using shlex.split provides proper handling of quoted arguments, unlike the
+    # original bash script which split on whitespace only.
+    try:
+        args = shlex.split(req_cmd, posix=True)
+    except ValueError as e:
+        log_error(f"Failed to parse SSH_ORIGINAL_COMMAND: {e}")
+        print("ERROR: could not parse command.")
+        sys.exit(1)
+
+    if not args:
+        log_error("Empty command after parsing.")
+        print("ERROR: empty command.")
+        sys.exit(1)
+
+    bin_path = os.path.realpath(args[0])
+    log_debug(f"Checking for bin {bin_path}")
+
+    if bin_path in ALLOWED:
+        log_info(f"Running command {req_cmd}")
+        # Ensure the argument list uses the resolved binary path as argv[0]
+        args[0] = bin_path
+        # Replace the current process with the requested command without PATH lookup
+        os.execv(bin_path, args)
+        # execv only returns on failure
+        log_error(f"Failed to exec {req_cmd}")
+        sys.exit(1)
+    else:
+        log_error(f"Not allowed {req_cmd}")
+        print("ERROR: command not allowed.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

hardening/limited-wrapper.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail   # safer defaults
+
+# Author: Juha Leivo
+# Version: 1.1.0
+# Date: 2025-11-03
+#
+# Prevent unauthorized SSH command execution by allowing only a limited set of binaries.
+#
+# History
+#   1.0.0 - 2025-11-02, initial version
+#   1.1.0 - 2025-11-03, moved to use logging 1.0.0
+
+# Function to log messages both to TTY and to a logfile in syslog format
+# Ref logging.sh version 1.0.0
+log_msg() {
+    local level="$1"
+    shift
+    # Concatenate all arguments into a single string
+    local msg="$*"
+
+    # Map level to syslog priority
+    local prio="notice"
+    case "$level" in
+        INFO)   prio="info" ;;
+        WARN)   prio="warning" ;;
+        ERROR)  prio="err" ;;
+        DEBUG)  prio="debug" ;;
+        *)      prio="notice"
+                msg="$level $msg" ;;
+    esac
+
+    if [ -t 1 ]; then
+        # Interactive TTY: print plain message without level prefix
+        echo "$msg"
+    else
+        # Non‑interactive: send to syslog
+    logger -p user.$prio -t "$(basename "$0")" "$level $msg"
+    fi
+}
+
+log_debug() { log_msg DEBUG "$@"; }
+log_info()  { log_msg INFO  "$@"; }
+log_warn()  { log_msg WARN  "$@"; }
+log_error() { log_msg ERROR "$@"; }
+# ------------------------------------------------------------------
+# Whitelist of absolute paths to allowed binaries
+ALLOWED=(
+    /usr/bin/ffmpeg
+    /usr/bin/ffprobe
+    /usr/local/bin/ffmpeg
+    /usr/local/bin/ffprobe
+    /usr/lib/jellyfin-ffmpeg/ffmpeg
+    /usr/lib/jellyfin-ffmpeg/ffprobe
+)
+
+# ------------------------------------------------------------------
+REQ_CMD="${SSH_ORIGINAL_COMMAND:-}"
+if [[ -z "$REQ_CMD" ]]; then
+    echo "You may run only: ${ALLOWED[*]}"
+    exit 0
+fi
+
+# Split the command into an array preserving quoting
+read -r -a ARGS <<<"$REQ_CMD"
+BIN="${ARGS[0]}"
+
+# Resolve symlinks if possible
+if command -v realpath >/dev/null; then
+    BIN=$(realpath -m "$BIN")
+else
+    BIN=$(readlink -f "$BIN" 2>/dev/null || echo "$BIN")
+fi
+
+log_debug "Checking for bin $BIN"
+
+# Whitelist check
+for ok in "${ALLOWED[@]}"; do
+    if [[ "$BIN" == "$ok" ]]; then
+    log_info "Running command $REQ_CMD"
+        eval "exec $REQ_CMD"
+    fi
+done
+
+log_error "Not allowed $REQ_CMD"
+echo "ERROR: command not allowed." # For SSH to show the error on client
+exit 1

rffmpeg.py

@@ -1,386 +0,0 @@
-#!/usr/bin/env python3
-
-# rffmpeg.py - Remote FFMPEG transcoding for Jellyfin
-#
-#    Copyright (C) 2019-2020  Joshua M. Boniface <joshua@boniface.me>
-#
-#    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 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 General Public License for more details.
-#
-#    You should have received a copy of the GNU General Public License
-#    along with this program.  If not, see <https://www.gnu.org/licenses/>.
-#
-###############################################################################
-#
-# rffmpeg works as a drop-in replacement to an existing ffmpeg binary. It is
-# used to launch ffmpeg commands on a remote machine via SSH, while passing
-# in any stdin from the calling environment. Its primary usecase is to enable
-# a program such as Jellyfin to distribute its ffmpeg calls to remote machines
-# that might be better suited to transcoding or processing ffmpeg.
-#
-# rffmpeg uses a configuration file, by default at `/etc/rffmpeg/rffmpeg.yml`,
-# to specify a number of settings that the processes will use. This includes
-# the remote system(s) to connect to, temporary directories, SSH configuration,
-# and other settings.
-#
-###############################################################################
-
-###############################################################################
-# Imports and helper functions
-###############################################################################
-
-import logging
-import os
-import re
-import signal
-import subprocess
-import sys
-
-import yaml
-
-log = logging.getLogger("rffmpeg")
-
-
-###############################################################################
-# Configuration parsing
-###############################################################################
-
-# Get configuration file
-default_config_file = "/etc/rffmpeg/rffmpeg.yml"
-config_file = os.environ.get("RFFMPEG_CONFIG", default_config_file)
-
-# Parse the configuration
-with open(config_file, "r") as cfgfile:
-    try:
-        o_config = yaml.load(cfgfile, Loader=yaml.BaseLoader)
-    except Exception as e:
-        log.error("ERROR: Failed to parse configuration file: %s", e)
-        exit(1)
-
-try:
-    config = {
-        "state_tempdir": o_config["rffmpeg"]["state"]["tempdir"],
-        "state_filename": o_config["rffmpeg"]["state"]["filename"],
-        "state_contents": o_config["rffmpeg"]["state"]["contents"],
-        "log_to_file": o_config["rffmpeg"]["logging"]["file"],
-        "logfile": o_config["rffmpeg"]["logging"]["logfile"],
-        "remote_hosts": o_config["rffmpeg"]["remote"]["hosts"],
-        "remote_user": o_config["rffmpeg"]["remote"]["user"],
-        "remote_args": o_config["rffmpeg"]["remote"]["args"],
-        "pre_commands": o_config["rffmpeg"]["commands"]["pre"],
-        "ffmpeg_command": o_config["rffmpeg"]["commands"]["ffmpeg"],
-        "ffprobe_command": o_config["rffmpeg"]["commands"]["ffprobe"],
-    }
-except Exception as e:
-    log.error("ERROR: Failed to load configuration: %s is missing", e)
-    exit(1)
-
-# Handle the fallback configuration using get() to avoid failing
-config["ssh_command"] = o_config["rffmpeg"]["commands"].get("ssh", "ssh")
-config["remote_persist_time"] = int(o_config["rffmpeg"]["remote"].get("persist", 0))
-config["state_persistdir"] = o_config["rffmpeg"]["state"].get("persistdir", '/run/shm')
-config["fallback_ffmpeg_command"] = o_config["rffmpeg"]["commands"].get("fallback_ffmpeg", config["ffmpeg_command"])
-config["fallback_ffprobe_command"] = o_config["rffmpeg"]["commands"].get("fallback_ffprobe", config["ffprobe_command"])
-
-# Parse CLI args (ffmpeg command line)
-all_args = sys.argv
-cli_ffmpeg_args = all_args[1:]
-
-# Get PID
-current_statefile = config["state_tempdir"] + "/" + config["state_filename"].format(pid=os.getpid())
-
-log.info("Starting rffmpeg %s: %s", os.getpid(), " ".join(all_args))
-
-
-def get_target_host():
-    """
-    Determine the optimal target host
-    """
-    log.info("Determining target host")
-
-    # Ensure the state directory exists or create it
-    if not os.path.exists(config["state_tempdir"]):
-        os.makedirs(config["state_tempdir"])
-
-    # Check for existing state files
-    state_files = os.listdir(config["state_tempdir"])
-
-    # Read each statefile to determine which hosts are bad or in use
-    bad_hosts = list()
-    active_hosts = list()
-    for state_file in state_files:
-        with open(config["state_tempdir"] + "/" + state_file, "r") as statefile:
-            contents = statefile.readlines()
-            for line in contents:
-                if re.match("^badhost", line):
-                    bad_hosts.append(line.split()[1])
-                    log.info("Found bad host mark from rffmpeg process %s for host '%s'", re.findall(r"[0-9]+", state_file)[0], line.split()[1])
-                else:
-                    active_hosts.append(line.split()[0])
-                    log.info("Found running rffmpeg process %s against host '%s'", re.findall(r"[0-9]+", state_file)[0], line.split()[0])
-
-    # Get the remote hosts list from the config
-    remote_hosts = list()
-    for host in config["remote_hosts"]:
-        if type(host) is str or host.get("name", None) is None:
-            host_name = host
-        else:
-            host_name = host.get("name")
-
-        if type(host) is str or host.get("weight", None) is None:
-            host_weight = 1
-        else:
-            host_weight = int(host.get("weight"))
-
-        remote_hosts.append({ "name": host_name, "weight": host_weight, "count": 0, "weighted_count": 0, "bad": False })
-
-
-    # Remove any bad hosts from the remote_hosts list
-    for bhost in bad_hosts:
-        for idx, rhost in enumerate(remote_hosts):
-            if bhost == rhost["name"]:
-                remote_hosts[idx]["bad"] = True
-
-    # Find out which active hosts are in use
-    for idx, rhost in enumerate(remote_hosts):
-        # Determine process counts in active_hosts
-        count = 0
-        for ahost in active_hosts:
-            if ahost == rhost["name"]:
-                count += 1
-        remote_hosts[idx]["count"] = count
-
-    # Reweight the host counts by floor dividing count by weight
-    for idx, rhost in enumerate(remote_hosts):
-        if rhost["bad"]:
-            continue
-        if rhost["weight"] > 1:
-            remote_hosts[idx]["weighted_count"] = rhost["count"] // rhost["weight"]
-        else:
-            remote_hosts[idx]["weighted_count"] = rhost["count"]
-
-    # Select the host with the lowest weighted count (first host is parsed last)
-    lowest_count = 999
-    target_host = None
-    for rhost in remote_hosts:
-        if rhost["bad"]:
-            continue
-        if rhost["weighted_count"] < lowest_count:
-            lowest_count = rhost["weighted_count"]
-            target_host = rhost["name"]
-
-    if not target_host:
-        log.warning("Failed to find a valid target host - using local fallback instead")
-        target_host = "localhost"
-
-    # Write to our state file
-    with open(current_statefile, "a") as statefile:
-        statefile.write(config["state_contents"].format(host=target_host) + "\n")
-
-    log.info("Selected target host '%s'", target_host)
-    return target_host
-
-
-def bad_host(target_host):
-    log.info("Setting bad host %s", target_host)
-
-    # Rewrite the statefile, removing all instances of the target_host that were added before
-    with open(current_statefile, "r+") as statefile:
-        new_statefile = statefile.readlines()
-        statefile.seek(0)
-        for line in new_statefile:
-            if target_host not in line:
-                statefile.write(line)
-        statefile.truncate()
-
-    # Add the bad host to the statefile
-    # This will affect this run, as well as any runs that start while this one is active; once
-    # this run is finished and its statefile removed, however, the host will be retried again
-    with open(current_statefile, "a") as statefile:
-        statefile.write("badhost " + config["state_contents"].format(host=target_host) + "\n")
-
-
-def setup_remote_command(target_host):
-    """
-    Craft the target command
-    """
-    rffmpeg_ssh_command = list()
-    rffmpeg_ffmpeg_command = list()
-
-    # Add SSH component
-    rffmpeg_ssh_command.append(config["ssh_command"])
-    rffmpeg_ssh_command.append("-q")
-
-    # Set our connection timeouts, in case one of several remote machines is offline
-    rffmpeg_ssh_command.extend([ "-o", "ConnectTimeout=1" ])
-    rffmpeg_ssh_command.extend([ "-o", "ConnectionAttempts=1" ])
-    rffmpeg_ssh_command.extend([ "-o", "StrictHostKeyChecking=no" ])
-    rffmpeg_ssh_command.extend([ "-o", "UserKnownHostsFile=/dev/null" ])
-
-    # Use SSH control persistence to keep sessions alive for subsequent commands
-    persist_time = config["remote_persist_time"]
-    if persist_time > 0:
-        rffmpeg_ssh_command.extend([ "-o", "ControlMaster=auto" ])
-        rffmpeg_ssh_command.extend([ "-o", "ControlPath={}/ssh-%r@%h:%p".format(config["state_persistdir"]) ])
-        rffmpeg_ssh_command.extend([ "-o", "ControlPersist={}".format(persist_time) ])
-
-    for arg in config["remote_args"]:
-        if arg:
-            rffmpeg_ssh_command.append(arg)
-
-    # Add user+host string
-    rffmpeg_ssh_command.append("{}@{}".format(config["remote_user"], target_host))
-    log.info("Running as %s@%s", config["remote_user"], target_host)
-
-    # Add any pre command
-    for cmd in config["pre_commands"]:
-        if cmd:
-            rffmpeg_ffmpeg_command.append(cmd)
-
-    # Prepare our default stdin/stdout/stderr (normally, stdout to stderr)
-    stdin = sys.stdin
-    stdout = sys.stderr
-    stderr = sys.stderr
-
-    # Verify if we're in ffmpeg or ffprobe mode
-    if "ffprobe" in all_args[0]:
-        rffmpeg_ffmpeg_command.append(config["ffprobe_command"])
-        stdout = sys.stdout
-    else:
-        rffmpeg_ffmpeg_command.append(config["ffmpeg_command"])
-
-    # Determine if version, encorders, or decoders is an argument; if so, we output stdout to stdout
-    # Weird workaround for something Jellyfin requires...
-    specials = ["-version", "-encoders", "-decoders", "-hwaccels", "-filters", "-h"]
-    if any(item in specials for item in cli_ffmpeg_args):
-        stdout = sys.stdout
-
-    # Parse and re-quote any problematic arguments
-    for arg in cli_ffmpeg_args:
-        # Match bad shell characters: * ' ( ) whitespace
-        if re.search("[*'()\s|\[\]]", arg):
-            rffmpeg_ffmpeg_command.append('"{}"'.format(arg))
-        else:
-            rffmpeg_ffmpeg_command.append("{}".format(arg))
-
-    return rffmpeg_ssh_command, rffmpeg_ffmpeg_command, stdin, stdout, stderr
-
-
-def run_command(rffmpeg_ssh_command, rffmpeg_ffmpeg_command, stdin, stdout, stderr):
-    """
-    Execute the command using subprocess
-    """
-    rffmpeg_command = rffmpeg_ssh_command + rffmpeg_ffmpeg_command
-    p = subprocess.run(
-        rffmpeg_command, shell=False, bufsize=0, universal_newlines=True, stdin=stdin, stderr=stderr, stdout=stdout
-    )
-    returncode = p.returncode
-
-    return returncode
-
-
-def run_local_ffmpeg():
-    """
-    Fallback call to local ffmpeg
-    """
-    rffmpeg_ffmpeg_command = list()
-
-    # Prepare our default stdin/stdout/stderr (normally, stdout to stderr)
-    stdin = sys.stdin
-    stdout = sys.stderr
-    stderr = sys.stderr
-
-    # Verify if we're in ffmpeg or ffprobe mode
-    if "ffprobe" in all_args[0]:
-        rffmpeg_ffmpeg_command.append(config["fallback_ffprobe_command"])
-        stdout = sys.stdout
-    else:
-        rffmpeg_ffmpeg_command.append(config["fallback_ffmpeg_command"])
-
-    # Determine if version, encorders, or decoders is an argument; if so, we output stdout to stdout
-    # Weird workaround for something Jellyfin requires...
-    specials = ["-version", "-encoders", "-decoders", "-hwaccels", "-filters", "-h"]
-    if any(item in specials for item in cli_ffmpeg_args):
-        stdout = sys.stdout
-
-    # Parse and re-quote any problematic arguments
-    for arg in cli_ffmpeg_args:
-        rffmpeg_ffmpeg_command.append("{}".format(arg))
-
-    log.info("Local command: %s", " ".join(rffmpeg_ffmpeg_command))
-
-    return run_command([], rffmpeg_ffmpeg_command, stdin, stdout, stderr)
-
-
-def run_remote_ffmpeg(target_host):
-    rffmpeg_ssh_command, rffmpeg_ffmpeg_command, stdin, stdout, stderr = setup_remote_command(target_host)
-    log.info("Remote command: %s '%s'", " ".join(rffmpeg_ssh_command), " ".join(rffmpeg_ffmpeg_command))
-
-    return run_command(rffmpeg_ssh_command, rffmpeg_ffmpeg_command, stdin, stdout, stderr)
-
-
-def cleanup(signum="", frame=""):
-    # Remove the current statefile
-    try:
-        os.remove(current_statefile)
-    except FileNotFoundError:
-        pass
-
-
-def main():
-    signal.signal(signal.SIGTERM, cleanup)
-    signal.signal(signal.SIGINT, cleanup)
-    signal.signal(signal.SIGQUIT, cleanup)
-    signal.signal(signal.SIGHUP, cleanup)
-
-    log_to_file = config.get("log_to_file", False)
-    if log_to_file:
-        logfile = config.get("logfile")
-        logging.basicConfig(
-            filename=logfile, level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
-        )
-    else:
-        logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
-
-    log.info("Starting rffmpeg PID %s", os.getpid())
-
-    # Main process loop; executes until the ffmpeg command actually runs on a reachable host
-    returncode = 1
-    while True:
-        target_host = get_target_host()
-        if target_host == "localhost":
-            returncode = run_local_ffmpeg()
-            break
-        else:
-            returncode = run_remote_ffmpeg(target_host)
-
-            # A returncode of 255 means that the SSH process failed;
-            # ffmpeg does not throw this return code (https://ffmpeg.org/pipermail/ffmpeg-user/2013-July/016245.html)
-            if returncode == 255:
-                log.info(
-                    "SSH failed to host %s with retcode %s: marking this host as bad and retrying",
-                    target_host,
-                    returncode,
-                )
-                bad_host(target_host)
-            else:
-                # The SSH succeeded, so we can abort the loop
-                break
-
-    cleanup()
-    if returncode == 0:
-        log.info("Finished rffmpeg PID %s with return code %s", os.getpid(), returncode)
-    else:
-        log.error("Finished rffmpeg PID %s with return code %s", os.getpid(), returncode)
-    exit(returncode)
-
-
-if __name__ == "__main__":
-    main()

rffmpeg.yml.sample

@@ -1,67 +1,83 @@
 ---
-# Example configuration file for rffmpeg
+# Configuration file for rffmpeg
+#
 # Copy this sample to /etc/rffmpeg/rffmpeg.yml and replace the various attributes
 # with the values for your environment. For more details please see the README.
+#
+# Any commented value represents the default. Uncomment and alter as required.
 
 rffmpeg:
-    # rffmpeg state configuration - YOU SHOULD NOT ALTER THESE
-    state:
-        # Temporary directory to store state
-        tempdir: "/run/shm/rffmpeg"
-
-        # Filename format for state instance files
-        filename: "instance_{pid}.pid"
-
-        # Contents of the state instance file
-        contents: "{host}"
-
-        # Temporary directory to store SSH persistence sockets
-        persistdir: "/run/shm"
-
     # Logging configuration
     logging:
-        # Enable or disable file logging
-        file: true
+        # Enable or disable file logging.
+        #log_to_file: true
 
-        # Log messages to this file - ensure the user running rffmpeg can write to it
-        logfile: "/var/log/jellyfin/rffmpeg.log"
+        # Log messages to this file.
+        # Ensure the user running rffmpeg can write to this directory.
+        #logfile: "/var/log/jellyfin/rffmpeg.log"
+        
+        # Use a Jellyfin-logging compatible dated log format, e.g. "20221223_rffmpeg.log"
+        # Supersedes the "logfile" directive above
+        #datedlogfiles: false
+        
+        # Use this base directory for Jellyfin-logging compatible dated log files if you enable "datedlogfiles"
+        # Set this to your Jellyfin logging directory if it differs from the default
+        #datedlogdir: "/var/log/jellyfin/"
+
+        # Show debugging messages
+        #debug: false
+
+    # Directory configuration
+    directories:
+        # Persistent directory to store state database.
+        #state: "/var/lib/rffmpeg"
+
+        # Temporary directory to store SSH persistence sockets.
+        #persist: "/run/shm"
+
+        # The user who should own the state directory and database.
+        # This should normally be the user who normally runs rffmpeg commands (i.e. the media
+        # server service user).
+        #owner: jellyfin
+
+        # The group who should own the state directory and database (an administrative group).
+        # Use this group to control who is able to run "rffmpeg" management commands; users in
+        # this group will have unlimited access to the tool to add/remove hosts, view status, etc.
+        #group: sudo
 
     # Remote (SSH) configuration
     remote:
-        # A YAML list of remote hosts to connect to; either direct list or name/weight supported
-        hosts:
-            - localhost
-            - name: gpu1
-              weight: 2   # Relative to any non-weighted hosts which have weight 1
+        # The remote SSH user to connect as.
+        #user: jellyfin
 
-        # The remote SSH user to connect as
-        user: jellyfin
-
-        # How long to persist SSH sessions (0 to disable)
-        persist: 300
-
-        # A YAML list of additional SSH arguments (e.g. private keys),
-        # one line per space-separated argument element.
-        args: 
-            - "-i"
-            - "/var/lib/jellyfin/.ssh/id_rsa"
+        # How long to persist SSH sessions; 0 to disable SSH persistence.
+        #persist: 300
 
+        # A YAML list of additional SSH arguments (e.g. private keys).
+        # One entry line per space-separated argument element.
+        #args: 
+        #    - "-i"
+        #    - "/var/lib/jellyfin/id_rsa"
 
     # Remote command configuration
     commands:
-        # By default rffmpeg uses $PATH to find the "ssh" program; use this option to set a full path
-        # to an SSH binary if you want to override the default.
-        ssh: "ssh"
+        # The path (either full or in $PATH) to the default SSH binary.
+        #ssh: "/usr/bin/ssh"
 
-        # A YAML list of prefixes to the ffmpeg command (e.g. sudo, nice, etc.),
-        # one line per space-separated command element.
-        pre:
-            - ""
+        # A YAML list of prefixes to the ffmpeg command (e.g. sudo, nice, etc.).
+        # One entry line per space-separated command element.
+        #pre:
+        #    - ""
 
-        # The (remote) ffmpeg and ffprobe command binary paths
-        ffmpeg: "/usr/lib/jellyfin-ffmpeg/ffmpeg"
-        ffprobe: "/usr/lib/jellyfin-ffmpeg/ffprobe"
+        # The (remote) ffmpeg and ffprobe command binary paths.
+        #ffmpeg: "/usr/lib/jellyfin-ffmpeg/ffmpeg"
+        #ffprobe: "/usr/lib/jellyfin-ffmpeg/ffprobe"
 
-        # An optional local fallback ffmpeg and ffprobe, if you wish this to be different from the above paths
+        # Optional local fallback ffmpeg and ffprobe binary paths, if different from the above.
         #fallback_ffmpeg: "/usr/lib/jellyfin-ffmpeg/ffmpeg"
         #fallback_ffprobe: "/usr/lib/jellyfin-ffmpeg/ffprobe"
+
+        # Optional additions to special flags that output to stdout instead of stderr. This isn't an override.
+        #special_flags:
+        #   - "-muxers"
+        #   - "-fp_format"