DEV Community: vast cow

Streaming Video Over a Network with the Lowest Possible Latency Using FFmpeg + MediaMTX

vast cow — Tue, 11 Aug 2026 06:54:54 +0000

When you want to send video captured from an HDMI capture device or similar source to another PC on the same LAN, one issue that can be surprisingly significant is video latency.

If you simply encode the video as H.264 and stream it over the network, small amounts of buffering can occur at multiple stages, such as:

Capture
FFmpeg’s internal queues
Encoding
Multiplexing
Network transport
Player-side buffering
Decoding and display

As a result, the final latency can range from several hundred milliseconds to several seconds.

This time, we will build a low-latency streaming setup that minimizes buffering as much as possible using the following configuration:

V4L2 + ALSA → FFmpeg → MediaMTX → RTSP/UDP → ffplay

In the current FFmpeg documentation, nobuffer is defined as an option for reducing latency caused by buffering during input analysis, while low_delay is defined as a flag that forces low-delay operation.

Configuration

The setup used here looks like this:

HDMI input
   ↓
Capture device
 /dev/video0
   ↓
FFmpeg
  ├─ Video input via V4L2
  ├─ Audio input via ALSA
  ├─ H.264 encoding with Intel QSV
  ↓
RTSP / UDP
   ↓
MediaMTX
   ↓
LAN
   ↓
ffplay
   ↓
Display

Rather than having MediaMTX encode the video itself, we use it as an RTSP server that relays the stream.

MediaMTX is a media server that supports publishing and reading real-time video and audio streams, including RTSP, and it can also launch external commands as hooks.

This time, we will use its runOnDemand feature.

MediaMTX Configuration

The mediamtx.yml file is configured as follows:

paths:
  hdmi:
    runOnDemand: >-
      ffmpeg -hide_banner -y
      -loglevel warning
      -fflags nobuffer
      -flags low_delay
      -init_hw_device qsv=qsv
      -filter_hw_device qsv
      -thread_queue_size 4
      -f alsa
      -ac 2
      -ar 48000
      -i hw:1,0
      -thread_queue_size 1
      -f v4l2
      -input_format yuyv422
      -video_size 1920x1080
      -framerate 30
      -i /dev/video0
      -map 1:v:0
      -map 0:a:0
      -vf 'hwupload=extra_hw_frames=0,vpp_qsv=format=nv12'
      -c:v h264_qsv
      -preset veryfast
      -global_quality:v 35
      -async_depth 1
      -bf 0
      -g 30
      -c:a libopus -b:a 192k
      -f rtsp
      -rtsp_transport udp
      -muxdelay 0
      rtsp://127.0.0.1:8554/hdmi
    runOnDemandRestart: yes
    runOnDemandStartTimeout: 10s
    runOnDemandCloseAfter: 5s

At first glance, this may seem like a lot of options, but from a low-latency perspective, it becomes easier to understand if you break them down into a few key areas.

Start FFmpeg Only When Needed with `runOnDemand`

First, let’s look at the MediaMTX side.

runOnDemand: >-
  ffmpeg ...

runOnDemand is a feature that starts an external command when a client accesses the corresponding path.

In other words, it works like this:

Nobody is watching
↓
FFmpeg stopped

ffplay connects to /hdmi
↓
MediaMTX starts FFmpeg
↓
FFmpeg publishes to /hdmi
↓
Playback starts

The official MediaMTX documentation also describes runOnDemand as a mechanism that starts the specified command when a reader requests the path.

Because FFmpeg does not need to run continuously, this is convenient when you only want to use HDMI streaming when needed.

In addition, we use:

runOnDemandRestart: yes

so that if FFmpeg exits for some reason, it will be restarted. The current MediaMTX configuration reference also defines this option as a setting that restarts the command after it exits.

Minimize Input-Side Buffers

An important principle in low-latency streaming is:

Avoid “buffering first, processing later.”

For that reason, the FFmpeg command begins with:

-fflags nobuffer
-flags low_delay

`-fflags nobuffer`

-fflags nobuffer

This setting reduces latency caused by buffering during input stream analysis. The official FFmpeg documentation also describes it as an option for reducing latency caused by buffering during initial input analysis.

For real-time input, it is important to configure the pipeline in the following direction:

Avoid accumulating packets as much as possible
↓
Pass incoming data to the next processing stage immediately

`-flags low_delay`

-flags low_delay

As the name suggests, this flag configures codec processing for low latency. In FFmpeg, low_delay is defined as “Force low delay.”

Capture Video and Audio from Separate Devices

In this setup, audio is captured through ALSA:

-f alsa
-ac 2
-ar 48000
-i hw:1,0

while video is captured through V4L2:

-f v4l2
-input_format yuyv422
-video_size 1920x1080
-framerate 30
-i /dev/video0

From FFmpeg’s perspective, the inputs are therefore:

input 0 = ALSA
input 1 = V4L2

The output streams are explicitly selected with:

-map 1:v:0
-map 0:a:0

In other words:

Video → video 0 from input 1
Audio → audio 0 from input 0

Keep `thread_queue_size` Small

For the inputs, we specify:

-thread_queue_size 4

and:

-thread_queue_size 1

thread_queue_size determines how many packets read from an input device or other source FFmpeg may retain in its internal queue. The official FFmpeg documentation describes it, for inputs, as the maximum number of queued packets when reading from a device or file.

If you increase the queue size, behavior tends to become:

Processing stalls slightly
↓
Packets accumulate in the queue
↓
Frames are processed without being dropped

However, in low-latency applications, this can become a problem:

Processing cannot keep up
↓
Old video accumulates in the queue
↓
Displayed video falls further and further behind real time

For that reason, we use very small values here.

The design philosophy is:

Prioritize displaying video that is close to the current time over guaranteeing that no frame is ever dropped.

This is a very important concept in low-latency streaming.

Encode with Intel Quick Sync Video

If 1920×1080 30 fps video is encoded to H.264 in software, the CPU load itself can become a source of latency.

For that reason, we use Intel Quick Sync Video, commonly known as QSV.

-init_hw_device qsv=qsv
-filter_hw_device qsv

Then the video is uploaded to the QSV device and converted to NV12 with:

-vf 'hwupload=extra_hw_frames=0,vpp_qsv=format=nv12'

The encoder is:

-c:v h264_qsv

This allows the Intel GPU’s hardware encoder to handle H.264 encoding.

Reduce Encoder “Lookahead” as Well

This is where some of the most important low-latency settings appear.

-preset veryfast
-global_quality:v 35
-async_depth 1
-bf 0
-g 30

`-preset veryfast`

-preset veryfast

QSV presets include:

veryfast
faster
fast
medium
slow
slower
veryslow

In FFmpeg, the veryfast side prioritizes speed, while the veryslow side prioritizes quality.

For live streaming, rather than pushing encoding quality to the limit, we prioritize:

Encoding each frame quickly and sending it to the network.

That is why we choose veryfast.

`async_depth 1` Is Important

-async_depth 1

This setting also helps reduce latency.

QSV can improve throughput by processing multiple frames asynchronously.

However:

Process multiple frames in parallel

also means that multiple frames may exist inside the encoder at the same time.

The FFmpeg QSV documentation defines async_depth as a parameter related to the number of asynchronous operations, and for the QSV decoder it explicitly notes that increasing the value also increases latency.

For that reason, we reduce it to:

-async_depth 1

The goal is a simple pipeline:

Frame input
↓
Encode
↓
Output immediately

We prioritize latency over throughput.

Do Not Use B-Frames

For low-latency H.264, this setting is especially important:

-bf 0

When B-frames are used, encoding and decoding a frame may require referencing frames that occur later in time.

Conceptually, the structure may look like:

I P B B P

As a result, the encoder and decoder may need to reorder frames, which is unfavorable for low-latency use cases.

Therefore, we completely disable B-frames with:

-bf 0

Compression efficiency is sacrificed to some extent, but this is easier to handle in real-time applications.

Use a One-Second GOP

-g 30

This is another key setting.

Here, we use:

-framerate 30

so the frame rate is 30 fps.

Therefore:

30 frames ÷ 30 fps = 1 second

which means the GOP is divided at roughly one-second intervals.

In FFmpeg, -g specifies the GOP size.

Shortening the GOP slightly reduces compression efficiency, but it makes the stream easier to handle in situations such as:

Playback startup
Recovery after packet loss
Joining the stream mid-session

For low-latency applications, compression ratio is not the only concern. It is also important to catch up to the current video quickly.

`global_quality:v 35`

-global_quality:v 35

This sets the QSV quality level.

When global_quality:v is specified with h264_qsv, quality-based rate control such as ICQ may be used depending on the conditions. The FFmpeg QSV documentation states that the ICQ range is 1–51, with 1 being the highest quality.

In other words:

Smaller value
↓
Higher quality, larger data volume

Larger value
↓
Lower quality, smaller data volume

35 is fairly compression-oriented, so you can adjust it while monitoring network bandwidth and image quality.

For example, if you want better quality, you could lower it to:

-global_quality:v 28

and compare the result.

Audio Is Opus at 192 kbps

Audio is configured as:

-c:a libopus -b:a 192k

Compared with video, audio encoding has relatively low computational and bandwidth requirements, so we use Opus at 192 kbps.

However, for monitoring applications where you only need to see the video, you can remove audio with:

-an

to simplify the setup further.

Use UDP for RTSP

FFmpeg outputs to MediaMTX with:

-f rtsp
-rtsp_transport udp
-muxdelay 0
rtsp://127.0.0.1:8554/hdmi

For reducing latency, the key setting is:

-rtsp_transport udp

FFmpeg allows UDP, TCP, and other methods to be selected as the RTSP lower transport. With UDP, media is sent over UDP; with TCP, the data is interleaved inside the RTSP control channel.

Unlike TCP, UDP does not have a mechanism like:

Packet loss
↓
Wait for retransmission
↓
Subsequent processing also waits until the packet arrives

Therefore, it is well suited to real-time applications where the priority is:

Even if the image becomes slightly corrupted, do not wait for old video—show the current video instead.

Naturally, however, video may become corrupted in environments where packet loss is more likely, such as:

Wi-Fi
Congested LANs
Streaming over the internet

If reliability is more important, another option is:

-rtsp_transport tcp

Low latency and transmission reliability are a tradeoff.

`muxdelay 0`

We also specify:

-muxdelay 0

muxdelay is a delay-related parameter used on FFmpeg’s output side. The official FFmpeg RTSP sending example also includes a case using -muxdelay 0.1.

Here, we push it even further with:

-muxdelay 0

to configure the system so that:

As little time as possible is spent waiting to batch packets together.

Do Not Make MediaMTX Encode the Video

An important part of this setup is that FFmpeg publishes once to the local MediaMTX instance:

FFmpeg
↓
rtsp://127.0.0.1:8554/hdmi

Clients then access:

rtsp://x.x.x.x:8554/hdmi

In other words, MediaMTX acts as the relay point:

FFmpeg
   ↓
MediaMTX
   ↓
Multiple clients

With this configuration, individual clients do not need direct access to the capture device or encoder.

It is also easier to manage when distributing the stream to multiple devices.

Reduce Buffering on the ffplay Side as Well

Even if the sender is optimized for low latency, there is little benefit if the receiving player buffers one second of video before starting playback.

For that reason, ffplay is also configured as follows:

ffplay \
  -fflags nobuffer \
  -flags low_delay \
  -framedrop \
  -rtsp_transport udp \
  rtsp://x.x.x.x:8554/hdmi

`-fflags nobuffer`

As on the sending side, we specify:

-fflags nobuffer

to reduce latency caused by buffering during input analysis.

`-flags low_delay`

-flags low_delay

This also configures decoding for low-latency operation.

`-framedrop`

-framedrop

This is another important option for real-time applications.

ffplay provides the framedrop option, which allows video frames to be dropped when playback falls behind synchronization.

For low-latency use, instead of:

Faithfully displaying every single frame

it is more important to:

If processing falls behind, discard old frames
↓
Catch up to the current time

This setting sacrifices some visual continuity in order to prevent latency from increasing.

In Low-Latency Streaming, “Dropping” Is Important

Looking at all of these settings, there is a common philosophy:

Do not retain old data any longer than necessary.

In normal video playback, it is important to:

Avoid packet loss
Avoid dropping frames
Keep playback smooth

However, real-time video has different priorities.

For example, when displaying a game screen or camera feed, it may be more useful to show:

Video from around 100 ms ago, even if some frames are skipped

than to perfectly display:

Video from 3 seconds ago

For that reason, this setup reduces waiting time at every stage of the pipeline:

Small input queues
↓
No B-frames
↓
Reduced QSV asynchronous depth
↓
Reduced muxer waiting time
↓
UDP
↓
Reduced buffering in ffplay
↓
Drop frames if playback falls behind

Where Does Latency Occur?

When optimizing for low latency, you need to look at the entire pipeline, not just the network:

Capture
↓
Queue
↓
Filter
↓
Encode
↓
Mux
↓
Network
↓
Demux
↓
Decode
↓
Render

For example, even if LAN ping is:

1 ms

if you have:

Encoder: 100 ms
Player buffer: 500 ms

then improving the network further will not have much impact.

In fact, with real-time video:

Buffers inside the encoder, decoder, and player can sometimes contribute more latency than the network itself.

That is why this configuration uses so many low-latency options.

If You Want to Reduce Latency Even Further

If latency is still noticeable with this configuration, there are several additional things you can try.

First, ffplay’s RTSP reception uses a buffer for reordering UDP packets. The FFmpeg documentation states that packet reordering during UDP reception can be disabled by setting max_delay to 0.

For example, you can try:

ffplay \
  -fflags nobuffer \
  -flags low_delay \
  -framedrop \
  -rtsp_transport udp \
  -max_delay 0 \
  rtsp://x.x.x.x:8554/hdmi

However, this further reduces tolerance for out-of-order packets, so video may become unstable depending on network quality.

You can also reduce:

-g 30

to something like:

-g 15

However, shorter GOPs generally reduce compression efficiency.

Low-latency optimization always involves tradeoffs among:

Latency
Image quality
Bandwidth
Stability
CPU/GPU load

UDP Does Not Automatically Mean Low Latency

One important point to keep in mind is that:

UDP = always low latency

is not necessarily true.

UDP can help avoid retransmission delays, but if network quality is poor, you may instead see:

Packet loss
↓
Video corruption
↓
Wait until the next recoverable frame

Therefore, the ideal environment is something like:

Wired LAN + UDP

where packet loss is low and the network is stable.

In a Wi-Fi environment, it is better to test both UDP and TCP and compare:

Actual latency
Video corruption
Stability

Summary

In this setup, we built the following pipeline:

HDMI
↓
V4L2 / ALSA
↓
FFmpeg
↓
Intel QSV H.264
↓
RTSP / UDP
↓
MediaMTX
↓
LAN
↓
ffplay

The key to reducing latency is not simply using a fast encoder.

What matters is removing, as much as possible, the buffers at each stage that exist to:

“Hold a little data just in case.”

The main settings used here can be summarized as follows:

-fflags nobuffer
    Reduce input-side buffering

-flags low_delay
    Configure codecs for low latency

-thread_queue_size
    Keep capture input queues small

-c:v h264_qsv
    Encode H.264 quickly with Intel QSV

-preset veryfast
    Prioritize encoding speed

-async_depth 1
    Reduce the asynchronous processing depth inside QSV

-bf 0
    Disable B-frames

-g 30
    About a one-second GOP at 30 fps

-rtsp_transport udp
    Favor avoiding retransmission delays

-muxdelay 0
    Reduce waiting time in the muxer

-framedrop
    Drop old frames if playback falls behind

The important thing to understand about low-latency video streaming is that:

“Deliver every frame reliably” and “deliver the current video” are different goals.

For recording, not losing frames is important.

On the other hand, for real-time monitoring, remote control, game screens, camera surveillance, and similar applications, it is often more important to display the latest video even if a few frames are missing than to receive old video perfectly.

By tuning the capture, encoding, network, and player stages around that principle, you can achieve very low-latency video transmission even with RTSP.

FFmpeg + MediaMTXで映像をできるだけ低遅延にネットワーク配信する

HDMIキャプチャなどから取り込んだ映像をLAN内の別PCへ送りたいとき、意外と問題になるのが映像の遅延です。

普通にH.264へエンコードしてネットワーク配信すると、

キャプチャ
FFmpeg内部のキュー
エンコード
マルチプレクサ
ネットワーク
プレイヤー側のバッファ
デコード・表示

といった複数の段階で少しずつバッファリングされ、最終的には数百ms〜数秒の遅延になることがあります。

そこで今回は、

V4L2 + ALSA → FFmpeg → MediaMTX → RTSP/UDP → ffplay

という構成で、可能な限りバッファを減らした低遅延ストリーミングを構築します。

FFmpegの現行ドキュメントでも、nobuffer は入力解析時のバッファリングによる遅延を減らすためのオプション、low_delay は低遅延動作を強制するフラグとして定義されています。

構成

今回の構成は次のようになります。

HDMI入力
   ↓
キャプチャデバイス
 /dev/video0
   ↓
FFmpeg
  ├─ V4L2で映像入力
  ├─ ALSAで音声入力
  ├─ Intel QSVでH.264エンコード
  ↓
RTSP / UDP
   ↓
MediaMTX
   ↓
LAN
   ↓
ffplay
   ↓
画面表示

MediaMTXには映像そのものをエンコードさせるのではなく、RTSPサーバーとして中継を担当させます。

MediaMTXはRTSPを含むリアルタイム映像・音声ストリームのpublish/readに対応するメディアサーバーで、外部コマンドをhookとして起動することもできます。

今回はそのrunOnDemand機能を使います。

MediaMTXの設定

mediamtx.ymlを次のようにしています。

paths:
  hdmi:
    runOnDemand: >-
      ffmpeg -hide_banner -y
      -loglevel warning
      -fflags nobuffer
      -flags low_delay
      -init_hw_device qsv=qsv
      -filter_hw_device qsv
      -thread_queue_size 4
      -f alsa
      -ac 2
      -ar 48000
      -i hw:1,0
      -thread_queue_size 1
      -f v4l2
      -input_format yuyv422
      -video_size 1920x1080
      -framerate 30
      -i /dev/video0
      -map 1:v:0
      -map 0:a:0
      -vf 'hwupload=extra_hw_frames=0,vpp_qsv=format=nv12'
      -c:v h264_qsv
      -preset veryfast
      -global_quality:v 35
      -async_depth 1
      -bf 0
      -g 30
      -c:a libopus -b:a 192k
      -f rtsp
      -rtsp_transport udp
      -muxdelay 0
      rtsp://127.0.0.1:8554/hdmi
    runOnDemandRestart: yes
    runOnDemandStartTimeout: 10s
    runOnDemandCloseAfter: 5s

一見するとオプションがかなり多いですが、低遅延化という観点ではいくつかのポイントに分けて考えると分かりやすくなります。

`runOnDemand`で必要なときだけFFmpegを起動する

まずMediaMTX側です。

runOnDemand: >-
  ffmpeg ...

runOnDemandは、クライアントからそのpathへのアクセスが発生したときに外部コマンドを起動する機能です。

つまり、

誰も見ていない
↓
FFmpeg停止

ffplayから /hdmi に接続
↓
MediaMTXがFFmpegを起動
↓
FFmpegが /hdmi にpublish
↓
再生開始

という動作になります。

MediaMTX公式ドキュメントでも、runOnDemandに指定したコマンドはreaderからpathが要求されたタイミングで開始される仕組みになっています。

常時FFmpegを動かしておく必要がないため、HDMI配信を必要なときだけ使いたい場合に便利です。

さらに、

runOnDemandRestart: yes

としているので、FFmpegが何らかの理由で終了した場合にも再起動されます。現行のMediaMTX設定リファレンスにも、このオプションはコマンド終了時に再起動する設定として定義されています。

入力側のバッファを極力小さくする

低遅延ストリーミングで重要なのが、

「溜めてから処理する」のを避けること

です。

そのためFFmpegの冒頭で、

-fflags nobuffer
-flags low_delay

を指定しています。

`-fflags nobuffer`

-fflags nobuffer

は入力ストリーム解析時に発生するバッファリングによる遅延を減らすための設定です。FFmpeg公式ドキュメントでも、初期入力解析時のバッファリングによるレイテンシーを削減するオプションとされています。

リアルタイム入力では、

できるだけパケットを貯めない
↓
届いたデータをすぐ次の処理へ渡す

という方向に設定しておくことが重要です。

`-flags low_delay`

-flags low_delay

も名前の通り、コーデック処理を低遅延方向へ設定するためのフラグです。FFmpegではlow_delayが「Force low delay」と定義されています。

映像と音声を別デバイスから入力する

今回の構成では音声をALSA、

-f alsa
-ac 2
-ar 48000
-i hw:1,0

映像をV4L2、

-f v4l2
-input_format yuyv422
-video_size 1920x1080
-framerate 30
-i /dev/video0

から取り込んでいます。

したがってFFmpegから見ると入力は、

input 0 = ALSA
input 1 = V4L2

になります。

出力するストリームを、

-map 1:v:0
-map 0:a:0

と明示しています。

つまり、

映像 → input 1のvideo 0
音声 → input 0のaudio 0

です。

`thread_queue_size`を小さくする

入力にはそれぞれ、

-thread_queue_size 4

-thread_queue_size 1

を指定しています。

thread_queue_sizeは、入力デバイスなどから読み込んだパケットをFFmpeg内部で何個までキューに保持するかを決める設定です。FFmpeg公式ドキュメントでも、入力の場合はデバイスやファイルから読み込む際のqueued packetsの最大数と説明されています。

キューを大きくすると、

多少処理が詰まる
↓
キューへ蓄積
↓
フレームを捨てず処理

しやすくなります。

一方で低遅延用途では、

処理が追いつかない
↓
過去の映像がキューへ溜まる
↓
表示がどんどん現実時間から遅れる

という問題になります。

そのため今回はかなり小さい値にしています。

これは、

フレームを絶対に落とさないことより、現在時刻に近い映像を表示することを優先する

という設計です。

低遅延ストリーミングでは非常に重要な考え方です。

Intel Quick Sync Videoでエンコードする

1920×1080 30fpsの映像をH.264へソフトウェアエンコードすると、CPU負荷によっては処理そのものが遅延原因になります。

そこでIntel Quick Sync Video、いわゆるQSVを利用しています。

-init_hw_device qsv=qsv
-filter_hw_device qsv

そして映像を、

-vf 'hwupload=extra_hw_frames=0,vpp_qsv=format=nv12'

でQSV側へアップロードし、NV12へ変換します。

エンコーダーは、

-c:v h264_qsv

です。

これによってH.264エンコードをIntel GPUのハードウェアエンコーダーへ担当させます。

エンコーダーでも「先読み」を減らす

ここからが低遅延化の重要部分です。

-preset veryfast
-global_quality:v 35
-async_depth 1
-bf 0
-g 30

としています。

`-preset veryfast`

-preset veryfast

QSVのpresetは、

veryfast
faster
fast
medium
slow
slower
veryslow

という選択肢があり、FFmpegではveryfast側が速度優先、veryslow側が画質優先として定義されています。

ライブ配信ではエンコード品質を限界まで高めるより、

1フレームを素早くエンコードしてネットワークへ送る

ことを優先します。

そのためveryfastを選択しています。

`async_depth 1`が重要

-async_depth 1

も低遅延化に効く設定です。

QSVは複数フレームを非同期に処理することでスループットを高められます。

ただし、

複数フレームを並列処理

するということは、逆に言えばエンコーダー内部に複数フレームが存在することにもなります。

FFmpegのQSVドキュメントでもasync_depthは非同期処理数に関係するパラメータとして定義されており、QSV decoderについては値を増やすほどレイテンシーも増えると明記されています。

そこで、

-async_depth 1

まで下げています。

狙っているのは、

フレーム入力
↓
エンコード
↓
すぐ出力

という単純なパイプラインです。

スループットよりlatencyを優先しています。

Bフレームを使わない

低遅延H.264では、

-bf 0

が特に重要です。

Bフレームを使用すると、あるフレームをエンコード・デコードする際に未来側のフレームを参照することがあります。

概念的には、

I P B B P

のような構造です。

そのためエンコーダーやデコーダーでフレーム並び替えが必要になり、低遅延用途では不利になります。

そこで、

-bf 0

としてBフレームを完全に無効化しています。

圧縮効率は多少犠牲になりますが、リアルタイム用途ではこちらの方が扱いやすくなります。

GOPを1秒にする

-g 30

もポイントです。

今回は、

-framerate 30

なので30fpsです。

したがって、

30フレーム ÷ 30fps = 1秒

となり、おおよそ1秒ごとにGOPが区切られます。

FFmpegでは-gはGOP sizeを指定するパラメータです。

GOPを短くすると圧縮効率は多少悪くなりますが、

再生開始
パケットロス後の復帰
ストリームへの途中参加

といった場面で扱いやすくなります。

低遅延用途では圧縮率だけでなく、素早く現在の映像へ追いつけることも重要です。

`global_quality:v 35`

-global_quality:v 35

ではQSVの品質を指定しています。

h264_qsvでglobal_quality:vを指定すると、条件に応じてICQなどの品質ベースのレート制御が利用されます。FFmpegのQSVドキュメントではICQ時の範囲は1〜51で、1が最高品質とされています。

つまり、

小さい値
↓
高画質・大きなデータ量

大きい値
↓
低画質・小さなデータ量

という方向です。

35はかなり圧縮寄りの設定なので、ネットワーク帯域や画質を見ながら調整できます。

たとえば画質を上げるなら、

-global_quality:v 28

などへ下げて比較すると分かりやすいでしょう。

音声はOpus 192kbps

音声は、

-c:a libopus -b:a 192k

としています。

映像に比べれば音声エンコードの負荷や帯域は小さいため、Opus 192kbpsとしています。

ただし「映像だけ確認できればよい」という監視用途などでは音声を削除して、

-an

とすることで構成をさらに単純化できます。

RTSPはUDPを使う

FFmpegからMediaMTXへの出力は、

-f rtsp
-rtsp_transport udp
-muxdelay 0
rtsp://127.0.0.1:8554/hdmi

です。

低遅延化では、

-rtsp_transport udp

がポイントです。

FFmpegではRTSPのlower transportとしてUDPまたはTCPなどを選択できます。UDPの場合はUDP、TCPの場合はRTSP control channel内へインターリーブしてデータが流れます。

UDPにはTCPのような、

パケット消失
↓
再送待ち
↓
到着するまで後続処理も待つ

という仕組みがありません。

そのため、

多少映像が乱れてもよいので、古い映像を待たず現在の映像を出す

というリアルタイム用途と相性がよい方式です。

ただし当然ながら、

Wi-Fi
混雑したLAN
インターネット越し

などパケットロスが発生しやすい環境では映像が乱れる可能性があります。

逆に安定性を優先するなら、

-rtsp_transport tcp

という選択肢もあります。

低遅延と伝送の確実性はトレードオフです。

`muxdelay 0`

さらに、

-muxdelay 0

としています。

muxdelayはFFmpegの出力側で使用される遅延関連パラメータです。FFmpeg公式のRTSP送信例でも-muxdelay 0.1を指定した例があります。

今回はさらに攻めて、

-muxdelay 0

とし、

パケットをまとめるために待つ時間を極力発生させない

方向へ寄せています。

MediaMTX自身にはエンコードさせない

今回の構成で重要なのは、

FFmpeg
↓
rtsp://127.0.0.1:8554/hdmi

として、一度localhostのMediaMTXへpublishしていることです。

クライアントは、

rtsp://x.x.x.x:8554/hdmi

へアクセスします。

つまりMediaMTXは、

FFmpeg
   ↓
MediaMTX
   ↓
複数クライアント

という中継点になります。

この構成にすると、キャプチャデバイスやエンコーダーを各クライアントが直接触る必要がありません。

複数端末へ配信したい場合にも扱いやすくなります。

ffplay側でもバッファを削る

送信側を低遅延化しても、受信側のプレイヤーが映像を1秒溜めてから再生していたら意味がありません。

そこでffplay側も、

ffplay \
  -fflags nobuffer \
  -flags low_delay \
  -framedrop \
  -rtsp_transport udp \
  rtsp://x.x.x.x:8554/hdmi

としています。

`-fflags nobuffer`

送信側と同様に、

-fflags nobuffer

を指定し、入力解析時のバッファリングによるレイテンシーを減らします。

`-flags low_delay`

-flags low_delay

でデコードも低遅延方向へ設定します。

`-framedrop`

-framedrop

もリアルタイム用途では重要です。

ffplayでは、映像が同期から遅れた場合にvideo frameをdropできるオプションとしてframedropが用意されています。

低遅延用途では、

すべてのフレームを律儀に表示する

よりも、

処理が遅れたら古いフレームを捨てる
↓
現在時刻へ追いつく

ほうが重要です。

これは映像品質を多少犠牲にしてでも遅延を増大させないための設定です。

低遅延配信では「捨てる」ことが重要

ここまでの設定を見ると、共通した思想があります。

それは、

古いデータをなるべく保持しない

ということです。

通常の動画再生では、

パケットロスさせない
フレームを落とさない
映像を滑らかにする

ことが重要です。

しかしリアルタイム映像では事情が違います。

例えばゲーム画面やカメラ映像を表示するとき、

3秒前の映像を完璧に表示

することより、

多少フレームが飛んでも100ms前後の映像を表示

できるほうが有用な場合があります。

そのため今回の設定では、

小さい入力キュー
↓
Bフレームなし
↓
QSVの非同期深度を削減
↓
muxerの待ち時間を削減
↓
UDP
↓
ffplayでもバッファ削減
↓
遅れたらframe drop

という形で、パイプラインの各段階から待ち時間を削っています。

遅延はどこで発生するのか

低遅延化するときは、ネットワークだけを見るのではなく、

Capture
↓
Queue
↓
Filter
↓
Encode
↓
Mux
↓
Network
↓
Demux
↓
Decode
↓
Render

というパイプライン全体を見る必要があります。

例えばLANのpingが、

1ms

だったとしても、

エンコーダー 100ms
プレイヤーバッファ 500ms

なら、ネットワークをいくら改善しても大きな効果はありません。

むしろリアルタイム動画の場合、

ネットワークそのものよりエンコーダー・デコーダー・プレイヤー内部のバッファが大きな遅延源になる

ことがあります。

今回多数の低遅延オプションを指定しているのはそのためです。

さらに遅延を詰めたい場合

この設定でもまだ遅延が気になる場合、いくつか試せるポイントがあります。

まずffplayのRTSP受信では、UDPパケットの並び替え用バッファが存在します。FFmpegドキュメントでは、UDP受信時のpacket reorderingをmax_delayを0にすることで無効化できるとされています。

例えば、

ffplay \
  -fflags nobuffer \
  -flags low_delay \
  -framedrop \
  -rtsp_transport udp \
  -max_delay 0 \
  rtsp://x.x.x.x:8554/hdmi

という設定も試せます。

ただしこれはパケット順序の乱れに対する耐性をさらに削るため、ネットワーク品質によっては映像が不安定になります。

また、

-g 30

を、

-g 15

などへ縮めることもできます。

ただしGOPを短くするほど一般に圧縮効率は悪化します。

低遅延化には常に、

遅延
画質
帯域
安定性
CPU/GPU負荷

のトレードオフがあります。

UDPだから必ず低遅延、ではない

注意したいのが、

UDP = 必ず低遅延

ではないということです。

UDPにすると再送待ちを避けやすい一方、ネットワーク品質が悪い場合は、

packet loss
↓
映像破損
↓
次の復旧可能なフレームまで待つ

ということもあります。

したがって実際には、

有線LAN + UDP

のような、低ロスかつ安定したネットワークで使うのが理想的です。

Wi-Fi環境ならUDPとTCPを両方試し、

実際の遅延
映像の乱れ
安定性

を比較したほうがよいでしょう。

まとめ

今回の構成では、

HDMI
↓
V4L2 / ALSA
↓
FFmpeg
↓
Intel QSV H.264
↓
RTSP / UDP
↓
MediaMTX
↓
LAN
↓
ffplay

というパイプラインを作りました。

低遅延化のポイントは、単に高速なエンコーダーを使用することではありません。

各段階で発生する、

「念のため少し溜めておく」バッファを可能な限り取り除くこと

が重要です。

今回の主要な設定をまとめると、

-fflags nobuffer
    入力側のバッファリングを削減

-flags low_delay
    コーデックを低遅延方向へ

-thread_queue_size
    キャプチャ入力のキューを小さくする

-c:v h264_qsv
    Intel QSVで高速にH.264エンコード

-preset veryfast
    エンコード速度優先

-async_depth 1
    QSV内部の非同期処理深度を削減

-bf 0
    Bフレームを無効化

-g 30
    30fpsなら約1秒GOP

-rtsp_transport udp
    再送待ちを避ける方向へ

-muxdelay 0
    muxer側の待ち時間を削減

-framedrop
    再生が遅れたら古いフレームを捨てる

となります。

低遅延映像配信で大切なのは、

「すべてのフレームを確実に届ける」ことと「今の映像を届ける」ことは別の目標

だと理解することです。

録画ならフレームを失わないことが重要です。

一方、リアルタイムモニター、遠隔操作、ゲーム画面、カメラ監視などでは、古い映像が完全に届くよりも、多少フレームが欠けても最新の映像が表示されることのほうが重要です。

その方針でキャプチャ・エンコード・ネットワーク・プレイヤーのすべてを調整すると、RTSPでもかなり低遅延な映像伝送を構成できます。

Automatically Renewing Tailscale HTTPS Certificates on PiKVM

vast cow — Mon, 10 Aug 2026 07:08:34 +0000

It is appropriate to continue using

ssl_certificate /etc/kvmd/nginx/ssl/server.crt;
ssl_certificate_key /etc/kvmd/nginx/ssl/server.key;

in /etc/kvmd/nginx/ssl.conf, with a systemd timer checking the certificate expiration and updating these two files only when necessary.

The official PiKVM documentation also describes placing the Tailscale certificate in /etc/kvmd/nginx/ssl/server.{crt,key}, setting the group to kvmd-nginx, and then restarting kvmd-nginx. (Pikvm) Also, certificates obtained as files using tailscale cert are not automatically renewed, so users need to implement their own renewal process. --min-validity is also officially available in the current CLI. (Tailscale)

Configuration

Normally, the setup looks like this.

Tailscale
   │
   │ 100.x / MagicDNS
   ▼
PiKVM nginx :443
   │
   ├─ /etc/kvmd/nginx/ssl/server.crt
   └─ /etc/kvmd/nginx/ssl/server.key

Do not use tailscale serve.

tailscale serve --https=443 off

The certificate renewal process will be:

Timer runs once a day
        │
        ▼
Check current server.crt
        │
        ├─ FQDN is correct
        │  and at least 30 days remain
        │       → Do nothing
        │
        └─ Less than 30 days / no certificate / hostname mismatch
                │
                ▼
               rw
                │
                ▼
        tailscale cert
                │
                ▼
        Validate cert/key
                │
                ▼
        Replace nginx files
                │
                ▼
        nginx -t
                │
                ▼
        restart kvmd-nginx
                │
                ▼
               ro

Let’s Encrypt certificates are valid for 90 days, so attempting renewal starting 30 days before expiration provides plenty of margin. (Tailscale)

1. Renewal Script

Create /usr/local/sbin/pikvm-tailscale-cert-renew.

#!/usr/bin/env bash
set -Eeuo pipefail

export PATH=/usr/local/sbin:/usr/local/bin:/usr/bin

CERT="/etc/kvmd/nginx/ssl/server.crt"
KEY="/etc/kvmd/nginx/ssl/server.key"

# 30 days
MIN_VALIDITY_SECONDS=$((30 * 24 * 60 * 60))
TS_MIN_VALIDITY="720h"

TMP=""
MADE_RW=0


log() {
    echo "pikvm-tailscale-cert-renew: $*"
}


cleanup() {
    rc=$?

    trap - EXIT INT TERM

    rm -f "${CERT}.new" "${KEY}.new" 2>/dev/null || true

    if [[ -n "${TMP:-}" ]]; then
        rm -rf "$TMP"
    fi

    if (( MADE_RW )); then
        sync

        if ! ro; then
            log "ERROR: failed to restore read-only filesystem"
            rc=1
        fi
    fi

    exit "$rc"
}

trap cleanup EXIT INT TERM


#
# Get the Tailscale FQDN
#
DOMAIN="$(
    tailscale status --json |
        jq -er '.Self.DNSName | rtrimstr(".") | select(length > 0)'
)"

log "Tailscale DNS name: ${DOMAIN}"


#
# Check the certificate currently used by nginx
#
cert_is_current() {
    [[ -s "$CERT" ]] || return 1
    [[ -s "$KEY" ]] || return 1

    # Check whether the hostname matches
    openssl x509 \
        -in "$CERT" \
        -noout \
        -checkhost "$DOMAIN" \
        >/dev/null 2>&1 || return 1

    # Check whether at least 30 days remain
    openssl x509 \
        -in "$CERT" \
        -noout \
        -checkend "$MIN_VALIDITY_SECONDS" \
        >/dev/null 2>&1 || return 1

    return 0
}


if cert_is_current; then
    log "certificate is valid for more than 30 days; nothing to do"
    exit 0
fi

log "certificate renewal is required"


#
# Use /tmp for the temporary directory.
# The root filesystem is still RO at this point.
#
TMP="$(mktemp -d /tmp/pikvm-tailscale-cert.XXXXXX)"


#
# Switch the PiKVM root filesystem to RW only when necessary.
#
ROOT_OPTS="$(findmnt -no OPTIONS /)"

case ",${ROOT_OPTS}," in
    *,rw,*)
        log "root filesystem is already read-write"
        ;;
    *)
        log "switching root filesystem to read-write"
        rw
        MADE_RW=1
        ;;
esac


#
# Obtain the certificate from Tailscale.
#
# --min-validity=720h requests a certificate
# that is valid for at least 30 days.
#
log "requesting certificate for ${DOMAIN}"

tailscale cert \
    --min-validity="$TS_MIN_VALIDITY" \
    --cert-file="$TMP/server.crt" \
    --key-file="$TMP/server.key" \
    "$DOMAIN"


#
# Validate the obtained certificate
#

# hostname
openssl x509 \
    -in "$TMP/server.crt" \
    -noout \
    -checkhost "$DOMAIN"

# expiration
openssl x509 \
    -in "$TMP/server.crt" \
    -noout \
    -checkend "$MIN_VALIDITY_SECONDS"

# Verify that the certificate and private key have the same public key
if ! cmp -s \
    <(
        openssl x509 \
            -in "$TMP/server.crt" \
            -pubkey \
            -noout |
        openssl pkey \
            -pubin \
            -outform DER 2>/dev/null
    ) \
    <(
        openssl pkey \
            -in "$TMP/server.key" \
            -pubout \
            -outform DER 2>/dev/null
    )
then
    log "ERROR: certificate and private key do not match"
    exit 1
fi


#
# Back up the current certificate
#
if [[ -e "$CERT" ]]; then
    cp -a "$CERT" "$TMP/old.crt"
fi

if [[ -e "$KEY" ]]; then
    cp -a "$KEY" "$TMP/old.key"
fi


rollback() {
    log "rolling back certificate"

    if [[ -e "$TMP/old.crt" ]]; then
        cp -a "$TMP/old.crt" "$CERT"
    else
        rm -f "$CERT"
    fi

    if [[ -e "$TMP/old.key" ]]; then
        cp -a "$TMP/old.key" "$KEY"
    else
        rm -f "$KEY"
    fi
}


#
# Prepare the files for nginx, then rename them.
#
# nginx itself continues holding the old certificate until it is
# reloaded/restarted, so even if the crt/key files briefly do not match
# between the two renames, this does not affect the running nginx process.
#
install \
    -o root \
    -g kvmd-nginx \
    -m 0644 \
    "$TMP/server.crt" \
    "${CERT}.new"

install \
    -o root \
    -g kvmd-nginx \
    -m 0640 \
    "$TMP/server.key" \
    "${KEY}.new"

mv -f "${KEY}.new" "$KEY"
mv -f "${CERT}.new" "$CERT"


#
# Validate using the actual nginx configuration generated by PiKVM
#
if ! nginx -t -c /run/kvmd/nginx.conf; then
    log "ERROR: nginx configuration test failed"
    rollback
    exit 1
fi


#
# Restart according to the official PiKVM documentation.
#
if ! systemctl restart kvmd-nginx; then
    log "ERROR: kvmd-nginx restart failed"

    rollback

    # Attempt recovery after restoring the old certificate
    nginx -t -c /run/kvmd/nginx.conf || true
    systemctl restart kvmd-nginx || true

    exit 1
fi


log "certificate successfully installed"

openssl x509 \
    -in "$CERT" \
    -noout \
    -subject \
    -issuer \
    -dates

exit 0

With this method, the normal daily operation consists only of:

openssl x509 -checkhost ...
openssl x509 -checkend ...

so the root filesystem remains RO.

It switches to rw only when fewer than 30 days remain.

Additionally, because tailscale cert --min-validity=720h is used, Tailscale is also instructed to “return a certificate that is valid for at least 30 days.” This flag is part of the current Tailscale CLI specification. (Tailscale)

2. systemd Service

/etc/systemd/system/pikvm-tailscale-cert-renew.service

[Unit]
Description=Renew Tailscale TLS certificate for PiKVM nginx
Wants=network-online.target
After=network-online.target tailscaled.service
Requires=tailscaled.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/pikvm-tailscale-cert-renew
TimeoutStartSec=5min

There is no need to add kvmd-nginx.service to Requires=.

The reason is that even if kvmd-nginx has stopped because of a broken certificate, this unit should still be able to repair the certificate independently and then run systemctl restart kvmd-nginx.

3. systemd Timer

/etc/systemd/system/pikvm-tailscale-cert-renew.timer

[Unit]
Description=Periodic Tailscale TLS certificate check for PiKVM

[Timer]
OnBootSec=15min
OnUnitActiveSec=1d
RandomizedDelaySec=30min
AccuracySec=1min
Unit=pikvm-tailscale-cert-renew.service

[Install]
WantedBy=timers.target

Persistent=true is intentionally omitted here.

Since this configuration starts renewing a 90-day certificate 30 days before expiration, missing a single check while the device is powered off is not a problem. The certificate will be checked roughly 15–45 minutes after boot, and then approximately once per day thereafter.

4. Installation

Switch PiKVM to RW only while creating the configuration files.

rw

chmod 755 /usr/local/sbin/pikvm-tailscale-cert-renew

systemctl daemon-reload

systemctl enable pikvm-tailscale-cert-renew.timer

ro

Then completely disable tailscale serve.

tailscale serve --https=443 off

PiKVM’s own nginx will listen on port 443.

The official PiKVM documentation also uses the approach of updating server.crt/server.key and running systemctl restart kvmd-nginx when installing a Tailscale certificate directly into nginx. (Pikvm)

5. Starting and Checking Status

systemctl start pikvm-tailscale-cert-renew.service

Check:

systemctl status pikvm-tailscale-cert-renew.service

journalctl \
    -u pikvm-tailscale-cert-renew.service \
    -n 100 \
    --no-pager

Certificate:

openssl x509 \
    -in /etc/kvmd/nginx/ssl/server.crt \
    -noout \
    -subject \
    -issuer \
    -dates \
    -ext subjectAltName

If it succeeds and contains:

DNS:{hostname}.{tsnet}.ts.net

then everything is OK.

After that, start the timer.

systemctl start pikvm-tailscale-cert-renew.timer

Check:

systemctl list-timers pikvm-tailscale-cert-renew.timer

Access URL

With this configuration, the certificate name is:

{hostname}.{tsnet}.ts.net

so in the browser, always use:

https://{hostname}.{tsnet}.ts.net/

For https://{hostname}/ or [https://100.x.x.x/](https://100.x.x.x/), the connection itself may reach nginx, but the certificate name will not match. Tailscale also explicitly states that HTTPS certificates are for fully qualified *.ts.net names, not HTTPS certificates for bare hostnames. (Tailscale)

In other words, this approach completely eliminates Serve, handles port 443 using only PiKVM’s standard nginx, keeps the filesystem RO during normal operation, and switches it to RW only when the certificate actually needs to be renewed. It also does not conflict with the automatic generation of /run/kvmd/nginx.conf.

PiKVM で Tailscale HTTPS 証明書を自動更新する

/etc/kvmd/nginx/ssl.conf では、引き続き

ssl_certificate /etc/kvmd/nginx/ssl/server.crt;
ssl_certificate_key /etc/kvmd/nginx/ssl/server.key;

を使用し、systemd タイマーで証明書の有効期限を確認して、必要な場合にのみこの 2 ファイルを更新する構成が適切です。

PiKVM の公式ドキュメントでも、Tailscale の証明書を /etc/kvmd/nginx/ssl/server.{crt,key} に配置し、グループを kvmd-nginx に設定したうえで kvmd-nginx を再起動する方法が説明されています。(Pikvm) また、tailscale cert でファイルとして取得した証明書は自動更新されないため、ユーザー側で独自の更新処理を実装する必要があります。現在の CLI では --min-validity も公式に利用できます。(Tailscale)

構成

通常、構成は次のようになります。

Tailscale
   │
   │ 100.x / MagicDNS
   ▼
PiKVM nginx :443
   │
   ├─ /etc/kvmd/nginx/ssl/server.crt
   └─ /etc/kvmd/nginx/ssl/server.key

tailscale serve は使用しません。

tailscale serve --https=443 off

証明書の更新処理は次のようになります。

タイマーを 1 日 1 回実行
        │
        ▼
現在の server.crt を確認
        │
        ├─ FQDN が正しく、
        │  かつ有効期限が 30 日以上残っている
        │       → 何もしない
        │
        └─ 残り 30 日未満 / 証明書なし / ホスト名不一致
                │
                ▼
               rw
                │
                ▼
        tailscale cert
                │
                ▼
        証明書/鍵を検証
                │
                ▼
        nginx のファイルを置換
                │
                ▼
        nginx -t
                │
                ▼
        kvmd-nginx を再起動
                │
                ▼
               ro

Let’s Encrypt の証明書は 90 日間有効なので、有効期限の 30 日前から更新を試みれば十分な余裕があります。(Tailscale)

1. 更新スクリプト

/usr/local/sbin/pikvm-tailscale-cert-renew を作成します。

#!/usr/bin/env bash
set -Eeuo pipefail

export PATH=/usr/local/sbin:/usr/local/bin:/usr/bin

CERT="/etc/kvmd/nginx/ssl/server.crt"
KEY="/etc/kvmd/nginx/ssl/server.key"

# 30 日
MIN_VALIDITY_SECONDS=$((30 * 24 * 60 * 60))
TS_MIN_VALIDITY="720h"

TMP=""
MADE_RW=0


log() {
    echo "pikvm-tailscale-cert-renew: $*"
}


cleanup() {
    rc=$?

    trap - EXIT INT TERM

    rm -f "${CERT}.new" "${KEY}.new" 2>/dev/null || true

    if [[ -n "${TMP:-}" ]]; then
        rm -rf "$TMP"
    fi

    if (( MADE_RW )); then
        sync

        if ! ro; then
            log "ERROR: 読み取り専用ファイルシステムへの復元に失敗しました"
            rc=1
        fi
    fi

    exit "$rc"
}

trap cleanup EXIT INT TERM


#
# Tailscale の FQDN を取得
#
DOMAIN="$(
    tailscale status --json |
        jq -er '.Self.DNSName | rtrimstr(".") | select(length > 0)'
)"

log "Tailscale DNS 名: ${DOMAIN}"


#
# nginx が現在使用している証明書を確認
#
cert_is_current() {
    [[ -s "$CERT" ]] || return 1
    [[ -s "$KEY" ]] || return 1

    # ホスト名が一致しているか確認
    openssl x509 \
        -in "$CERT" \
        -noout \
        -checkhost "$DOMAIN" \
        >/dev/null 2>&1 || return 1

    # 有効期限が 30 日以上残っているか確認
    openssl x509 \
        -in "$CERT" \
        -noout \
        -checkend "$MIN_VALIDITY_SECONDS" \
        >/dev/null 2>&1 || return 1

    return 0
}


if cert_is_current; then
    log "証明書の有効期限は 30 日以上残っています。処理は不要です"
    exit 0
fi

log "証明書の更新が必要です"


#
# 一時ディレクトリには /tmp を使用。
# この時点ではルートファイルシステムはまだ RO。
#
TMP="$(mktemp -d /tmp/pikvm-tailscale-cert.XXXXXX)"


#
# 必要な場合にのみ PiKVM のルートファイルシステムを RW に切り替える。
#
ROOT_OPTS="$(findmnt -no OPTIONS /)"

case ",${ROOT_OPTS}," in
    *,rw,*)
        log "ルートファイルシステムはすでに読み書き可能です"
        ;;
    *)
        log "ルートファイルシステムを読み書き可能に切り替えます"
        rw
        MADE_RW=1
        ;;
esac


#
# Tailscale から証明書を取得。
#
# --min-validity=720h により、少なくとも 30 日間
# 有効な証明書を要求する。
#
log "${DOMAIN} の証明書を要求しています"

tailscale cert \
    --min-validity="$TS_MIN_VALIDITY" \
    --cert-file="$TMP/server.crt" \
    --key-file="$TMP/server.key" \
    "$DOMAIN"


#
# 取得した証明書を検証
#

# ホスト名
openssl x509 \
    -in "$TMP/server.crt" \
    -noout \
    -checkhost "$DOMAIN"

# 有効期限
openssl x509 \
    -in "$TMP/server.crt" \
    -noout \
    -checkend "$MIN_VALIDITY_SECONDS"

# 証明書と秘密鍵の公開鍵が同一であることを確認
if ! cmp -s \
    <(
        openssl x509 \
            -in "$TMP/server.crt" \
            -pubkey \
            -noout |
        openssl pkey \
            -pubin \
            -outform DER 2>/dev/null
    ) \
    <(
        openssl pkey \
            -in "$TMP/server.key" \
            -pubout \
            -outform DER 2>/dev/null
    )
then
    log "ERROR: 証明書と秘密鍵が一致しません"
    exit 1
fi


#
# 現在の証明書をバックアップ
#
if [[ -e "$CERT" ]]; then
    cp -a "$CERT" "$TMP/old.crt"
fi

if [[ -e "$KEY" ]]; then
    cp -a "$KEY" "$TMP/old.key"
fi


rollback() {
    log "証明書をロールバックしています"

    if [[ -e "$TMP/old.crt" ]]; then
        cp -a "$TMP/old.crt" "$CERT"
    else
        rm -f "$CERT"
    fi

    if [[ -e "$TMP/old.key" ]]; then
        cp -a "$TMP/old.key" "$KEY"
    else
        rm -f "$KEY"
    fi
}


#
# nginx 用のファイルを準備してからリネームする。
#
# nginx 自体はリロード/再起動されるまで古い証明書を保持し続けるため、
# 2 回のリネームの間に crt/key ファイルが一時的に一致しない状態になっても、
# 稼働中の nginx プロセスには影響しない。
#
install \
    -o root \
    -g kvmd-nginx \
    -m 0644 \
    "$TMP/server.crt" \
    "${CERT}.new"

install \
    -o root \
    -g kvmd-nginx \
    -m 0640 \
    "$TMP/server.key" \
    "${KEY}.new"

mv -f "${KEY}.new" "$KEY"
mv -f "${CERT}.new" "$CERT"


#
# PiKVM が生成した実際の nginx 設定を使用して検証
#
if ! nginx -t -c /run/kvmd/nginx.conf; then
    log "ERROR: nginx の設定テストに失敗しました"
    rollback
    exit 1
fi


#
# PiKVM 公式ドキュメントに従って再起動。
#
if ! systemctl restart kvmd-nginx; then
    log "ERROR: kvmd-nginx の再起動に失敗しました"

    rollback

    # 古い証明書を復元した後、復旧を試みる
    nginx -t -c /run/kvmd/nginx.conf || true
    systemctl restart kvmd-nginx || true

    exit 1
fi


log "証明書を正常にインストールしました"

openssl x509 \
    -in "$CERT" \
    -noout \
    -subject \
    -issuer \
    -dates

exit 0

この方法では、通常の日次処理で実行されるのは次の確認だけです。

openssl x509 -checkhost ...
openssl x509 -checkend ...

したがって、ルートファイルシステムは RO のまま維持されます。

rw に切り替わるのは、有効期限の残りが 30 日未満になった場合だけです。

さらに、tailscale cert --min-validity=720h を使用しているため、Tailscale に対しても「少なくとも 30 日間有効な証明書を返す」よう指定しています。このフラグは現在の Tailscale CLI 仕様に含まれています。(Tailscale)

2. systemd サービス

/etc/systemd/system/pikvm-tailscale-cert-renew.service

[Unit]
Description=PiKVM nginx 用 Tailscale TLS 証明書を更新
Wants=network-online.target
After=network-online.target tailscaled.service
Requires=tailscaled.service

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/pikvm-tailscale-cert-renew
TimeoutStartSec=5min

Requires= に kvmd-nginx.service を追加する必要はありません。

理由は、証明書の破損によって kvmd-nginx が停止していたとしても、このユニットは独立して証明書を修復し、その後 systemctl restart kvmd-nginx を実行できるようにしておくべきだからです。

3. systemd タイマー

/etc/systemd/system/pikvm-tailscale-cert-renew.timer

[Unit]
Description=PiKVM 用 Tailscale TLS 証明書の定期チェック

[Timer]
OnBootSec=15min
OnUnitActiveSec=1d
RandomizedDelaySec=30min
AccuracySec=1min
Unit=pikvm-tailscale-cert-renew.service

[Install]
WantedBy=timers.target

ここでは意図的に Persistent=true を省略しています。

この構成では、90 日間有効な証明書について有効期限の 30 日前から更新を開始するため、デバイスの電源が切れている間に 1 回チェックできなくても問題ありません。起動後およそ 15～45 分以内に証明書がチェックされ、その後はおよそ 1 日に 1 回チェックされます。

4. インストール

設定ファイルを作成している間だけ PiKVM を RW に切り替えます。

rw

chmod 755 /usr/local/sbin/pikvm-tailscale-cert-renew

systemctl daemon-reload

systemctl enable pikvm-tailscale-cert-renew.timer

ro

その後、tailscale serve を完全に無効化します。

tailscale serve --https=443 off

PiKVM 自身の nginx がポート 443 で待ち受けます。

PiKVM の公式ドキュメントでも、Tailscale の証明書を nginx に直接インストールする場合、server.crt/server.key を更新して systemctl restart kvmd-nginx を実行する方法が使用されています。(Pikvm)

5. 起動とステータス確認

systemctl start pikvm-tailscale-cert-renew.service

確認：

systemctl status pikvm-tailscale-cert-renew.service

journalctl \
    -u pikvm-tailscale-cert-renew.service \
    -n 100 \
    --no-pager

証明書：

openssl x509 \
    -in /etc/kvmd/nginx/ssl/server.crt \
    -noout \
    -subject \
    -issuer \
    -dates \
    -ext subjectAltName

成功し、次の内容が含まれていれば問題ありません。

DNS:{hostname}.{tsnet}.ts.net

その後、タイマーを開始します。

systemctl start pikvm-tailscale-cert-renew.timer

確認：

systemctl list-timers pikvm-tailscale-cert-renew.timer

アクセス URL

この構成では、証明書名は次のようになります。

{hostname}.{tsnet}.ts.net

したがって、ブラウザでは常に次を使用します。

https://{hostname}.{tsnet}.ts.net/

https://{hostname}/ または https://100.x.x.x/ の場合、接続自体は nginx に到達する可能性がありますが、証明書名は一致しません。Tailscale も、HTTPS 証明書は完全修飾された *.ts.net 名を対象とするものであり、単純なホスト名に対する HTTPS 証明書ではないことを明示しています。(Tailscale)

つまり、この方法では Serve を完全に排除し、ポート 443 を PiKVM 標準の nginx のみで処理し、通常時はファイルシステムを RO のまま維持し、実際に証明書の更新が必要になった場合にのみ RW に切り替えることができます。また、/run/kvmd/nginx.conf の自動生成とも競合しません。

Setting Up and Troubleshooting FFmpeg + Intel QSV on Rocky Linux 9

vast cow — Fri, 07 Aug 2026 08:31:28 +0000

If you want to accelerate FFmpeg H.264 / HEVC encoding using the integrated GPU in an Intel CPU, you can use Intel Quick Sync Video (QSV).

However, on Linux—especially on RHEL-based distributions such as Rocky Linux 9—simply seeing:

FFmpeg recognizes h264_qsv

does not mean QSV will actually work.

In fact, on Rocky Linux 9, I encountered errors like the following:

[AVHWDeviceContext @ 0x562042595380] Failed to initialise VAAPI connection: -1 (unknown libva error).
[h264_qsv @ 0x56204258e140] Failed to create a VAAPI device.
Error initializing output stream 0:0

Even when explicitly specifying the Intel GPU with -qsv_device, I got:

[AVHWDeviceContext @ 0x55ac9a494500] Failed to initialise VAAPI connection: -1 (unknown libva error).
Device creation failed: -5.
Failed to set value '/dev/dri/renderD128' for option 'qsv_device': Input/output error

This article explains how to set up FFmpeg + QSV on Rocky Linux 9 and the order in which these types of errors should be isolated and diagnosed.

Understanding the Layers Required for QSV to Work

The first important point is that QSV is not a standalone FFmpeg feature.

On Linux, access to the Intel GPU conceptually passes through several layers:

FFmpeg
↓
QSV
↓
Intel Media SDK / oneVPL
↓
Intel Media Driver
↓
VA-API / libva
↓
/dev/dri/renderD128
↓
i915 / xe
↓
Intel GPU

Therefore, even if:

ffmpeg -encoders | grep qsv

shows:

h264_qsv
hevc_qsv

that alone does not mean the GPU is actually usable.

For example, QSV will not work if there is a problem at any one of these points:

Linux does not detect the Intel GPU
nomodeset is configured
i915 / xe is not loaded
/dev/dri/renderD128 cannot be accessed
libva is missing
Intel Media Driver is missing or cannot be loaded
The Media SDK / oneVPL runtime does not match
FFmpeg itself was not built with QSV support

Therefore, the basic troubleshooting approach is to verify each layer from the bottom up.

1. Check Whether Linux Detects the Intel GPU

First, check the PCI devices.

lspci -nn | grep -Ei 'VGA|Display'

In this environment, the result was:

00:02.0 VGA compatible controller [0300]:
Intel Corporation GeminiLake [UHD Graphics 605] [8086:3184] (rev 03)

This confirms that the Intel UHD Graphics 605, i.e. the Gemini Lake GPU, is detected.

Next, check the kernel driver.

lspci -nnk | grep -A4 -Ei 'VGA|Display'

The result in this case was:

00:02.0 VGA compatible controller [0300]: Intel Corporation GeminiLake [UHD Graphics 605] [8086:3184] (rev 03)
DeviceName: Onboard - Video
Subsystem: Elitegroup Computer Systems Device [1019:a94d]
Kernel driver in use: i915
Kernel modules: i915

The important line here is:

Kernel driver in use: i915

Gemini Lake uses i915.

On newer Intel GPUs, xe may be used depending on the configuration.

You can also verify this with:

lsmod | grep -E 'i915|xe'

2. Remove `nomodeset` If It Is Configured

When using an Intel iGPU with QSV / VA-API, specifying nomodeset in the kernel boot options can prevent the GPU driver from initializing correctly and can make QSV unusable.

First, check the current kernel command line.

cat /proc/cmdline

If it contains:

nomodeset

remove it.

nomodeset disables Kernel Mode Setting (KMS). Because it interferes with the normal initialization of DRM/KMS drivers such as i915, which are used with Intel GPUs, it can prevent /dev/dri/renderD128 from being created or cause VA-API initialization to fail even if a GPU device appears to exist.

On Rocky Linux 9, check the GRUB configuration.

sudo grubby --info=ALL | grep args

If nomodeset is configured, you can remove it from all kernel entries.

sudo grubby --update-kernel=ALL --remove-args="nomodeset"

After changing the setting, reboot.

sudo reboot

After rebooting, check again.

cat /proc/cmdline

After confirming that nomodeset is gone, run:

lspci -nnk | grep -A4 -Ei 'VGA|Display'

and confirm that it shows:

Kernel driver in use: i915

Then check the DRM devices as well.

ls -l /dev/dri/

At a minimum, confirm that entries such as:

card0
renderD128

have been created.

3. Check `/dev/dri/renderD128`

Next, check the DRM devices.

ls -l /dev/dri/

In this environment, the output was:

drwxr-xr-x. 2 root root         80 Aug  7 16:04 by-path
crw-rw----. 1 root video  226,   0 Aug  7 16:04 card0
crw-rw-rw-. 1 root render 226, 128 Aug  7 16:04 renderD128

For server-side QSV and VA-API usage, the especially important device is:

/dev/dri/renderD128

Even on a server that is not running X11 or Wayland, hardware encoding is possible as long as renderD128 is accessible.

In other words:

No GUI = QSV cannot be used

is not true.

QSV can also be used on headless servers.

4. Check Permissions on renderD128

A typical device node looks like this:

crw-rw---- 1 root render ... /dev/dri/renderD128

In that case, add the user running FFmpeg to the render group.

sudo usermod -aG render $USER

Depending on the environment, membership in video may also be required, so this is also acceptable:

sudo usermod -aG video,render $USER

After logging in again, verify with:

id

If FFmpeg is launched from a systemd service, the required permissions must be granted not to the login user, but to the user running the service.

The same point matters when using Jellyfin, Plex, or custom transcoding workflows combined with MediaMTX.

In this environment, the device permissions were:

crw-rw-rw-. 1 root render ... renderD128

so a simple Unix permission problem was unlikely.

5. Enable EPEL and RPM Fusion

The standard Rocky Linux 9 repositories may not contain all packages needed for FFmpeg and the Intel Media Driver stack.

First, add EPEL.

sudo dnf install -y epel-release

Then add RPM Fusion Free / Nonfree.

sudo dnf install -y \
https://download1.rpmfusion.org/free/el/rpmfusion-free-release-9.noarch.rpm \
https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-9.noarch.rpm

Then update the system.

sudo dnf update -y

6. Install Intel Media Driver

For relatively recent Intel GPUs, Intel Media Driver—the iHD driver—is used as the VA-API driver.

With Rocky Linux 9 + RPM Fusion, install:

sudo dnf install -y intel-media-driver

Intel Media Driver provides the VA-API backend:

/usr/lib64/dri/iHD_drv_video.so

The Intel UHD Graphics 605 / Gemini Lake used here is also supported by Intel Media Driver.

7. Install libva and vainfo

vainfo is extremely useful for verifying VA-API operation.

sudo dnf install -y libva libva-utils

After installation, run:

vainfo

However, on a server without a GUI, it is more reliable to specify the DRM device explicitly.

vainfo --display drm --device /dev/dri/renderD128

If everything is working correctly, the output should look roughly like this:

libva info: VA-API version ...
libva info: Trying to open /usr/lib64/dri/iHD_drv_video.so
libva info: Found init function __vaDriverInit_...
libva info: va_openDriver() returns 0
vainfo: Driver version: Intel iHD driver ...

8. Explicitly Set `LIBVA_DRIVER_NAME=iHD`

If automatic detection does not work correctly, you can explicitly specify the VA-API driver to use.

LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

If you want to set it persistently, you can also use:

export LIBVA_DRIVER_NAME=iHD

9. Intel Media SDK vs. oneVPL

Several names appear around QSV:

Intel Media SDK
libmfx
oneVPL
libvpl
intel-vpl-gpu-rt

Intel's newer software stack has transitioned from the legacy Intel Media SDK to oneVPL.

However, when deciding what to install for FFmpeg on Rocky Linux 9, it is important to check which API stack your FFmpeg build was compiled against.

For the RPM Fusion FFmpeg 5.1.10 used here:

ffmpeg -version

showed that it had been built with:

--enable-libmfx

And when checking:

rpm -qa | grep -Ei 'libva|intel-media|libmfx|vpl'

the result was:

libva-2.22.0-1.el9.x86_64
intel-mediasdk-21.3.5-1.el9.x86_64
libva-utils-2.11.1-1.el9.x86_64

In this environment, FFmpeg uses QSV through libmfx, i.e. Intel Media SDK.

Therefore, it is safer not to assume that "Rocky 9 always requires libvpl + intel-vpl-gpu-rt."

First, check the configure options shown by:

ffmpeg -version

10. Install FFmpeg

Install FFmpeg from RPM Fusion.

sudo dnf install -y ffmpeg

Verify it.

ffmpeg -version

11. Check Whether FFmpeg Supports QSV

First, check the list of hardware acceleration methods.

ffmpeg -hwaccels

For the FFmpeg build used here, the result was:

Hardware acceleration methods:
vdpau
cuda
vaapi
qsv
drm
opencl
vulkan

Here, you can confirm:

vaapi
qsv

Next, check the QSV encoders.

ffmpeg -hide_banner -encoders | grep -E 'qsv|vaapi'

In this environment, the output was:

V..... h264_qsv     H.264 / AVC ... (Intel Quick Sync Video acceleration)
V....D h264_vaapi   H.264/AVC (VAAPI)
V..... hevc_qsv     HEVC (Intel Quick Sync Video acceleration)
V....D hevc_vaapi   H.265/HEVC (VAAPI)
V..... mjpeg_qsv    MJPEG (Intel Quick Sync Video acceleration)
V....D mjpeg_vaapi  MJPEG (VAAPI)
V..... mpeg2_qsv    MPEG-2 video (Intel Quick Sync Video acceleration)
V....D mpeg2_vaapi  MPEG-2 (VAAPI)
V....D vp8_vaapi    VP8 (VAAPI)
V....D vp9_vaapi    VP9 (VAAPI)
V..... vp9_qsv      VP9 video (Intel Quick Sync Video acceleration)

Seeing h264_qsv in the list and actually being able to use the GPU are two different things.

12. Get `vainfo` Working First

When troubleshooting QSV, it is usually faster to get:

vainfo --display drm --device /dev/dri/renderD128

working first rather than repeatedly changing FFmpeg options.

In this environment, it returned:

libva info: VA-API version 1.22.0
libva info: Trying to open /usr/lib64/dri/iHD_drv_video.so
libva info: va_openDriver() returns -1
libva info: Trying to open /usr/lib64/dri/i965_drv_video.so
libva info: va_openDriver() returns -1
vaInitialize failed with error code -1 (unknown libva error),exit

Because the GPU was detected, i915 was in use, and /dev/dri/renderD128 existed, this narrowed the problem down to the libva / Intel Media Driver area.

13. Check Which RPM Provides `iHD_drv_video.so`

ls -l /usr/lib64/dri/iHD_drv_video.so

Then use:

rpm -qf /usr/lib64/dri/iHD_drv_video.so

to check which RPM provides the file.

If you do not know which RPM contains it, you can also search with:

dnf provides '*/iHD_drv_video.so'

The expected provider is an intel-media-driver package.

sudo dnf install -y intel-media-driver

One important point is that intel-mediasdk and intel-media-driver are different packages.

14. Check the Driver's Library Dependencies

ldd /usr/lib64/dri/iHD_drv_video.so

If this output contains:

not found

then a required dependency is missing.

15. Check Package Sources and Versions

rpm -qi libva libva-utils intel-mediasdk intel-media-driver

Or use:

dnf repoquery --installed \
--qf '%{name} %{version}-%{release} %{repoid}' \
libva libva-utils intel-mediasdk intel-media-driver

16. Explicitly Test with iHD

LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

If it is working correctly, the output should include:

Trying to open /usr/lib64/dri/iHD_drv_video.so
Found init function ...
va_openDriver() returns 0

17. Run a Standalone QSV Test

Once vainfo works correctly, test QSV encoding using a generated test pattern that is unrelated to any input video.

ffmpeg \
-qsv_device /dev/dri/renderD128 \
-f lavfi \
-i testsrc2=size=1280x720:rate=30 \
-t 5 \
-c:v h264_qsv \
-global_quality 23 \
-f null -

If this succeeds, you can conclude that the H.264 QSV encoding path is functioning.

18. Isolate the Problem with VAAPI Encoding

ffmpeg \
-vaapi_device /dev/dri/renderD128 \
-f lavfi \
-i testsrc2=size=1280x720:rate=30 \
-vf 'format=nv12,hwupload' \
-t 5 \
-c:v h264_vaapi \
-f null -

VAAPI	QSV	Possible Cause
NG	NG	VA-API / Intel Media Driver / GPU device side
OK	NG	Media SDK / oneVPL / QSV runtime side
OK	OK	GPU stack is healthy. Investigate the original FFmpeg command
NG	OK	An unusual configuration that is normally uncommon

19. Encode H.264 with QSV

ffmpeg \
-qsv_device /dev/dri/renderD128 \
-i input.mp4 \
-c:v h264_qsv \
-global_quality 23 \
-c:a copy \
output.mp4

20. Encode HEVC / H.265 with QSV

ffmpeg \
-qsv_device /dev/dri/renderD128 \
-i input.mp4 \
-c:v hevc_qsv \
-global_quality 25 \
-c:a copy \
output.mp4

21. QSV Decode + QSV Encode

ffmpeg \
-qsv_device /dev/dri/renderD128 \
-hwaccel qsv \
-hwaccel_output_format qsv \
-i input.mp4 \
-c:v h264_qsv \
-global_quality 23 \
-c:a copy \
output.mp4

For troubleshooting, it is easier to isolate problems by starting with CPU decode + QSV encode.

22. The `yuv420p` → `nv12` Warning Is Not a Fatal Error

Incompatible pixel format 'yuv420p' for codec 'h264_qsv',
auto-selecting format 'nv12'

This is unrelated to the VA-API error discussed here.

If necessary, you can explicitly specify:

-pix_fmt nv12

23. ALSA `Thread message queue blocking` Is Also a Separate Issue

If you see:

[alsa] Thread message queue blocking;
consider raising the thread_queue_size option

specify something like:

-thread_queue_size 1024

before the ALSA input.

24. Example Rocky Linux 9 Setup

sudo dnf install -y epel-release
sudo dnf install -y \
https://download1.rpmfusion.org/free/el/rpmfusion-free-release-9.noarch.rpm \
https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-9.noarch.rpm
sudo dnf install -y \
ffmpeg \
libva \
libva-utils \
intel-media-driver

In an environment like this one where ffmpeg -version includes:

--enable-libmfx

this package is also a candidate:

sudo dnf install -y intel-mediasdk

For Gemini Lake + RPM Fusion FFmpeg 5.1.x, a straightforward starting configuration is roughly:

sudo dnf install -y \
ffmpeg \
libva \
libva-utils \
intel-media-driver \
intel-mediasdk

25. Final Verification Checklist

# 0. nomodeset
cat /proc/cmdline

# 1. GPU / kernel driver
lspci -nnk | grep -A4 -Ei 'VGA|Display'

# 2. Kernel module
lsmod | grep -E 'i915|xe'

# 3. DRM
ls -l /dev/dri/

# 4. Intel Media Driver
rpm -q intel-media-driver

# 5. iHD driver
ls -l /usr/lib64/dri/iHD_drv_video.so
rpm -qf /usr/lib64/dri/iHD_drv_video.so

# 6. VA-API
LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

# 7. FFmpeg HW acceleration
ffmpeg -hwaccels

# 8. QSV encoders
ffmpeg -hide_banner -encoders | grep _qsv

# 9. QSV decoders
ffmpeg -hide_banner -decoders | grep _qsv

# 10. QSV encode test
ffmpeg \
-qsv_device /dev/dri/renderD128 \
-f lavfi \
-i testsrc2=size=1280x720:rate=30 \
-t 5 \
-c:v h264_qsv \
-global_quality 23 \
-f null -

The verification order is easiest to understand as follows:

Presence of nomodeset
↓
Intel GPU
↓
i915 / xe
↓
/dev/dri/renderD128
↓
VA-API / libva
↓
Intel Media Driver
↓
Media SDK / oneVPL
↓
FFmpeg

What We Learned with Gemini Lake / UHD Graphics 605

On the actual system used here:

Intel Corporation GeminiLake [UHD Graphics 605]
Kernel driver in use: i915

and /dev/dri/renderD128 was also present.

In addition, FFmpeg had been built with --enable-libmfx, recognized qsv / vaapi, and could list encoders such as h264_qsv, hevc_qsv, and vp9_qsv.

However:

vainfo --display drm --device /dev/dri/renderD128

returned:

Trying to open /usr/lib64/dri/iHD_drv_video.so
va_openDriver() returns -1
Trying to open /usr/lib64/dri/i965_drv_video.so
va_openDriver() returns -1

The QSV test also failed with:

Failed to initialise VAAPI connection
Device creation failed

This shows that the problem is not with FFmpeg encoding options, but with the VA-API / Intel Media Driver layer.

In this situation, investigate the Intel Media Driver installation and dependencies in this order:

rpm -qf /usr/lib64/dri/iHD_drv_video.so
ldd /usr/lib64/dri/iHD_drv_video.so
LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

Summary

When using FFmpeg + Intel QSV on Rocky Linux 9, seeing h264_qsv in ffmpeg -encoders does not mean the setup is complete.

The required layers are roughly as follows:

Component	Requirement	Role
Disable `nomodeset`	Important	Allows DRM/KMS to initialize correctly
Intel GPU	Required	Hardware
`i915` / `xe`	Required	Kernel GPU driver
`/dev/dri/renderD128`	Required	DRM render node
`libva`	Important in Linux QSV environments	VA-API
`intel-media-driver`	Important for supported Intel GPUs	`iHD_drv_video.so`
`intel-mediasdk`	For libmfx-based setups	Legacy QSV runtime
`libvpl`	For oneVPL-based setups	oneVPL dispatcher
`intel-vpl-gpu-rt`	For supported newer-generation GPUs	oneVPL GPU implementation
QSV-enabled FFmpeg	Required	`h264_qsv` / `hevc_qsv`, etc.

In particular, if you see:

Failed to initialise VAAPI connection
Failed to create a VAAPI device

the fastest approach is to check:

cat /proc/cmdline
vainfo --display drm --device /dev/dri/renderD128

before changing encoding options.

If nomodeset is still present, remove it. If vainfo does not work correctly, fix the VA-API / Intel Media Driver problem first.

When building a QSV environment on Rocky Linux 9, keep the following layers in mind:

nomodeset
↓
GPU
↓
Kernel driver
↓
DRM
↓
VA-API
↓
Intel Media Driver
↓
Media SDK / oneVPL
↓
FFmpeg

The most reliable setup method is to verify proper operation one layer at a time, from the bottom up.

Rocky Linux 9 で FFmpeg + Intel QSV を使うためのセットアップとトラブルシューティング

Intel CPU の内蔵 GPU を使って FFmpeg の H.264 / HEVC エンコードを高速化したい場合、Intel Quick Sync Video（QSV）が利用できます。

しかし Linux、特に Rocky Linux 9 のような RHEL 系ディストリビューションでは、

FFmpeg が h264_qsv を認識している

だけでは QSV は動きません。

実際、今回 Rocky Linux 9 上で次のようなエラーに遭遇しました。

[AVHWDeviceContext @ 0x562042595380] Failed to initialise VAAPI connection: -1 (unknown libva error).
[h264_qsv @ 0x56204258e140] Failed to create a VAAPI device.
Error initializing output stream 0:0

さらに -qsv_device で Intel GPU を明示しても、

[AVHWDeviceContext @ 0x55ac9a494500] Failed to initialise VAAPI connection: -1 (unknown libva error).
Device creation failed: -5.
Failed to set value '/dev/dri/renderD128' for option 'qsv_device': Input/output error

となりました。

この記事では、Rocky Linux 9 で FFmpeg + QSV をセットアップする方法と、こうしたエラーをどの順番で切り分けるべきかをまとめます。

QSV が動くまでのレイヤを理解する

最初に重要なのは、QSV は FFmpeg 単体の機能ではないということです。

Linux では概念的に次のような複数のレイヤを通って Intel GPU にアクセスします。

FFmpeg
  ↓
QSV
  ↓
Intel Media SDK / oneVPL
  ↓
Intel Media Driver
  ↓
VA-API / libva
  ↓
/dev/dri/renderD128
  ↓
i915 / xe
  ↓
Intel GPU

そのため、

ffmpeg -encoders | grep qsv

で

h264_qsv
hevc_qsv

が表示されても、それだけでは GPU が実際に使えることを意味しません。

例えば、

Intel GPU を Linux が認識していない
nomodeset が設定されている
i915 / xe がロードされていない
/dev/dri/renderD128 にアクセスできない
libva がない
Intel Media Driver がない、またはロードできない
Media SDK / oneVPL runtime が合っていない
FFmpeg 自体が QSV 対応でビルドされていない

といったどこか一箇所でも問題があると、QSV は動きません。

したがって、下から順番に確認していくのがトラブルシューティングの基本です。

1. Intel GPU を Linux が認識しているか確認する

まず PCI デバイスを確認します。

lspci -nn | grep -Ei 'VGA|Display'

今回の環境では、

00:02.0 VGA compatible controller [0300]:
Intel Corporation GeminiLake [UHD Graphics 605] [8086:3184] (rev 03)

となりました。

Intel UHD Graphics 605、つまり Gemini Lake の GPU が認識されています。

次に、カーネルドライバを確認します。

lspci -nnk | grep -A4 -Ei 'VGA|Display'

今回の結果は、

00:02.0 VGA compatible controller [0300]: Intel Corporation GeminiLake [UHD Graphics 605] [8086:3184] (rev 03)
        DeviceName: Onboard - Video
        Subsystem: Elitegroup Computer Systems Device [1019:a94d]
        Kernel driver in use: i915
        Kernel modules: i915

でした。

ここで重要なのは、

Kernel driver in use: i915

です。

Gemini Lake では i915 が使われます。

最近の Intel GPU では構成によって xe が使われることもあります。

念のため、

lsmod | grep -E 'i915|xe'

でも確認できます。

2. `nomodeset` を設定している場合は外す

Intel iGPU を QSV / VA-API で使用する場合、カーネルの起動オプションに nomodeset を指定していると、GPU ドライバが正常に初期化されず、QSV が使えない原因になることがあります。

まず現在のカーネルコマンドラインを確認します。

cat /proc/cmdline

ここに、

nomodeset

が含まれている場合は削除します。

nomodeset は Kernel Mode Setting（KMS）を無効化するオプションです。Intel GPU で使用する i915 などの DRM/KMS ドライバの正常な初期化を妨げるため、/dev/dri/renderD128 が生成されない、あるいは GPU デバイスが存在していても VA-API の初期化に失敗する原因になり得ます。

Rocky Linux 9 では GRUB の設定を確認します。

sudo grubby --info=ALL | grep args

nomodeset が設定されている場合は、全カーネルエントリから削除できます。

sudo grubby --update-kernel=ALL --remove-args="nomodeset"

設定後、再起動します。

sudo reboot

再起動後、もう一度確認します。

cat /proc/cmdline

nomodeset が消えていることを確認した上で、

lspci -nnk | grep -A4 -Ei 'VGA|Display'

を実行し、

Kernel driver in use: i915

となっていることを確認します。

続いて DRM デバイスも確認します。

ls -l /dev/dri/

最低限、

card0
renderD128

などが生成されていることを確認します。

3. `/dev/dri/renderD128` を確認する

次に DRM デバイスを確認します。

ls -l /dev/dri/

今回の環境では、

drwxr-xr-x. 2 root root         80 Aug  7 16:04 by-path
crw-rw----. 1 root video  226,   0 Aug  7 16:04 card0
crw-rw-rw-. 1 root render 226, 128 Aug  7 16:04 renderD128

となっていました。

QSV や VA-API のサーバ用途で特に重要なのが、

/dev/dri/renderD128

です。

X11 や Wayland を起動していないサーバでも、renderD128 にアクセスできればハードウェアエンコードできます。

つまり、

GUI がない = QSV が使えない

ではありません。

ヘッドレスサーバでも利用可能です。

4. renderD128 の権限を確認する

典型的には次のようになっています。

crw-rw---- 1 root render ... /dev/dri/renderD128

この場合、FFmpeg を実行するユーザーを render グループへ追加します。

sudo usermod -aG render $USER

環境によっては video も必要になるため、

sudo usermod -aG video,render $USER

としても構いません。

再ログイン後、

id

で確認します。

systemd サービスから FFmpeg を起動する場合には、ログインユーザーではなくサービスを実行しているユーザーに権限が必要です。

Jellyfin、Plex、MediaMTX と組み合わせた独自トランスコード処理などでも、この点には注意が必要です。

今回の環境では、

crw-rw-rw-. 1 root render ... renderD128

だったため、単純な Unix パーミッション不足である可能性は低い状態でした。

5. EPEL と RPM Fusion を有効にする

Rocky Linux 9 の標準リポジトリだけでは FFmpeg や Intel Media Driver 周辺のパッケージが不足する場合があります。

まず EPEL を追加します。

sudo dnf install -y epel-release

続いて RPM Fusion Free / Nonfree を追加します。

sudo dnf install -y \
  https://download1.rpmfusion.org/free/el/rpmfusion-free-release-9.noarch.rpm \
  https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-9.noarch.rpm

その後更新しておきます。

sudo dnf update -y

6. Intel Media Driver をインストールする

Intel の比較的新しい GPU では、VA-API ドライバとして Intel Media Driver、つまり iHD ドライバを使用します。

Rocky Linux 9 + RPM Fusion なら、

sudo dnf install -y intel-media-driver

をインストールします。

Intel Media Driver は VA-API バックエンドとなる、

/usr/lib64/dri/iHD_drv_video.so

を提供します。

今回使用した Intel UHD Graphics 605 / Gemini Lake も Intel Media Driver の対象です。

7. libva と vainfo をインストールする

VA-API の動作確認には vainfo が非常に便利です。

sudo dnf install -y libva libva-utils

インストール後、

vainfo

を実行します。

ただし GUI のないサーバでは、DRM デバイスを明示したほうが確実です。

vainfo --display drm --device /dev/dri/renderD128

正常なら、概ね次のようになります。

libva info: VA-API version ...
libva info: Trying to open /usr/lib64/dri/iHD_drv_video.so
libva info: Found init function __vaDriverInit_...
libva info: va_openDriver() returns 0

vainfo: Driver version: Intel iHD driver ...

8. `LIBVA_DRIVER_NAME=iHD` で明示する

自動判定がうまくいかない場合には、使用する VA-API ドライバを明示できます。

LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

恒久的に指定したければ、

export LIBVA_DRIVER_NAME=iHD

としても構いません。

9. Intel Media SDK と oneVPL の違い

QSV 周りでは、

Intel Media SDK
libmfx
oneVPL
libvpl
intel-vpl-gpu-rt

といった名前が登場します。

Intel の新しいソフトウェアスタックは、従来の Intel Media SDK から oneVPL へ移行しています。

ただし Rocky Linux 9 の FFmpeg で何を入れるべきかは、使用している FFmpeg がどちらに対してビルドされているか確認することが重要です。

今回使用した RPM Fusion の FFmpeg 5.1.10 は、

ffmpeg -version

を見ると、

--enable-libmfx

でビルドされていました。

そして実際に、

rpm -qa | grep -Ei 'libva|intel-media|libmfx|vpl'

を確認すると、

libva-2.22.0-1.el9.x86_64
intel-mediasdk-21.3.5-1.el9.x86_64
libva-utils-2.11.1-1.el9.x86_64

となっていました。

この環境では FFmpeg が libmfx、つまり Intel Media SDK 経由の QSV を使用する構成です。

したがって、「Rocky 9 なら必ず libvpl + intel-vpl-gpu-rt をインストールする」と考えないほうが安全です。

まず、

ffmpeg -version

の configure オプションを確認してください。

10. FFmpeg をインストールする

RPM Fusion から FFmpeg を入れます。

sudo dnf install -y ffmpeg

確認します。

ffmpeg -version

11. FFmpeg が QSV 対応か確認する

まずハードウェアアクセラレーション一覧を確認します。

ffmpeg -hwaccels

今回の FFmpeg では、

Hardware acceleration methods:
vdpau
cuda
vaapi
qsv
drm
opencl
vulkan

となっていました。

ここで、

vaapi
qsv

が確認できます。

次に QSV エンコーダを確認します。

ffmpeg -hide_banner -encoders | grep -E 'qsv|vaapi'

今回の環境では、

V..... h264_qsv     H.264 / AVC ... (Intel Quick Sync Video acceleration)
V....D h264_vaapi   H.264/AVC (VAAPI)
V..... hevc_qsv     HEVC (Intel Quick Sync Video acceleration)
V....D hevc_vaapi   H.265/HEVC (VAAPI)
V..... mjpeg_qsv    MJPEG (Intel Quick Sync Video acceleration)
V....D mjpeg_vaapi  MJPEG (VAAPI)
V..... mpeg2_qsv    MPEG-2 video (Intel Quick Sync Video acceleration)
V....D mpeg2_vaapi  MPEG-2 (VAAPI)
V....D vp8_vaapi    VP8 (VAAPI)
V....D vp9_vaapi    VP9 (VAAPI)
V..... vp9_qsv      VP9 video (Intel Quick Sync Video acceleration)

となりました。

h264_qsv が一覧にあることと、実際に GPU が使用できることは別問題です。

12. まず `vainfo` を正常にする

QSV のトラブルシューティングでは、いきなり FFmpeg のオプションを変更し続けるより、

vainfo --display drm --device /dev/dri/renderD128

を最初に正常化したほうが早いです。

今回の環境では、

libva info: VA-API version 1.22.0
libva info: Trying to open /usr/lib64/dri/iHD_drv_video.so
libva info: va_openDriver() returns -1
libva info: Trying to open /usr/lib64/dri/i965_drv_video.so
libva info: va_openDriver() returns -1
vaInitialize failed with error code -1 (unknown libva error),exit

となっていました。

GPU は認識され、i915 も使用され、/dev/dri/renderD128 も存在しているため、問題は libva / Intel Media Driver 付近にあると切り分けられます。

13. `iHD_drv_video.so` がどの RPM に含まれるか確認する

ls -l /usr/lib64/dri/iHD_drv_video.so

さらに、

rpm -qf /usr/lib64/dri/iHD_drv_video.so

で、どの RPM が提供しているファイルか確認できます。

RPM が分からなければ、

dnf provides '*/iHD_drv_video.so'

でも検索できます。

期待するのは intel-media-driver 系の RPM です。

sudo dnf install -y intel-media-driver

ここで注意したいのが intel-mediasdk と intel-media-driver は別物だということです。

14. ドライバの依存ライブラリを確認する

ldd /usr/lib64/dri/iHD_drv_video.so

ここに、

not found

があれば、その依存ライブラリが不足しています。

15. パッケージの出所とバージョンも確認する

rpm -qi libva libva-utils intel-mediasdk intel-media-driver

または、

dnf repoquery --installed \
  --qf '%{name} %{version}-%{release} %{repoid}' \
  libva libva-utils intel-mediasdk intel-media-driver

を使用します。

16. iHD を明示してテストする

LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

正常なら、

Trying to open /usr/lib64/dri/iHD_drv_video.so
Found init function ...
va_openDriver() returns 0

となります。

17. QSV 単体テストをする

vainfo が正常になったら、入力動画とは無関係なテスト映像で QSV エンコードを確認します。

ffmpeg \
  -qsv_device /dev/dri/renderD128 \
  -f lavfi \
  -i testsrc2=size=1280x720:rate=30 \
  -t 5 \
  -c:v h264_qsv \
  -global_quality 23 \
  -f null -

これが成功すれば H.264 QSV エンコード経路が動作していると判断できます。

18. VAAPI エンコードでも切り分ける

ffmpeg \
  -vaapi_device /dev/dri/renderD128 \
  -f lavfi \
  -i testsrc2=size=1280x720:rate=30 \
  -vf 'format=nv12,hwupload' \
  -t 5 \
  -c:v h264_vaapi \
  -f null -

VAAPI	QSV	考えられる原因
NG	NG	VA-API / Intel Media Driver / GPU デバイス側
OK	NG	Media SDK / oneVPL / QSV runtime 側
OK	OK	GPU スタックは正常。元の FFmpeg コマンドを調査
NG	OK	通常はあまりない特殊な構成

19. QSV で H.264 をエンコードする

ffmpeg \
  -qsv_device /dev/dri/renderD128 \
  -i input.mp4 \
  -c:v h264_qsv \
  -global_quality 23 \
  -c:a copy \
  output.mp4

20. HEVC / H.265 を QSV でエンコードする

ffmpeg \
  -qsv_device /dev/dri/renderD128 \
  -i input.mp4 \
  -c:v hevc_qsv \
  -global_quality 25 \
  -c:a copy \
  output.mp4

21. QSV decode + QSV encode

ffmpeg \
  -qsv_device /dev/dri/renderD128 \
  -hwaccel qsv \
  -hwaccel_output_format qsv \
  -i input.mp4 \
  -c:v h264_qsv \
  -global_quality 23 \
  -c:a copy \
  output.mp4

トラブルシューティングでは、まず CPU decode + QSV encode から始めるほうが切り分けやすくなります。

22. `yuv420p` → `nv12` の警告は致命的エラーではない

Incompatible pixel format 'yuv420p' for codec 'h264_qsv',
auto-selecting format 'nv12'

これは今回の VA-API エラーとは別問題です。

必要なら、

-pix_fmt nv12

を指定できます。

23. ALSA の `Thread message queue blocking` も別問題

[alsa] Thread message queue blocking;
consider raising the thread_queue_size option

が出る場合は ALSA 入力の前に、

-thread_queue_size 1024

などを指定します。

24. Rocky Linux 9 のセットアップ例

sudo dnf install -y epel-release

sudo dnf install -y \
  https://download1.rpmfusion.org/free/el/rpmfusion-free-release-9.noarch.rpm \
  https://download1.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-9.noarch.rpm

sudo dnf install -y \
  ffmpeg \
  libva \
  libva-utils \
  intel-media-driver

今回のように ffmpeg -version に、

--enable-libmfx

がある環境では、

sudo dnf install -y intel-mediasdk

も候補になります。

Gemini Lake + RPM Fusion FFmpeg 5.1 系であれば、概ね、

sudo dnf install -y \
  ffmpeg \
  libva \
  libva-utils \
  intel-media-driver \
  intel-mediasdk

という構成から始めるのが分かりやすいでしょう。

25. 最終確認チェックリスト

# 0. nomodeset
cat /proc/cmdline

# 1. GPU / kernel driver
lspci -nnk | grep -A4 -Ei 'VGA|Display'

# 2. Kernel module
lsmod | grep -E 'i915|xe'

# 3. DRM
ls -l /dev/dri/

# 4. Intel Media Driver
rpm -q intel-media-driver

# 5. iHD driver
ls -l /usr/lib64/dri/iHD_drv_video.so
rpm -qf /usr/lib64/dri/iHD_drv_video.so

# 6. VA-API
LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

# 7. FFmpeg HW acceleration
ffmpeg -hwaccels

# 8. QSV encoders
ffmpeg -hide_banner -encoders | grep _qsv

# 9. QSV decoders
ffmpeg -hide_banner -decoders | grep _qsv

# 10. QSV encode test
ffmpeg \
  -qsv_device /dev/dri/renderD128 \
  -f lavfi \
  -i testsrc2=size=1280x720:rate=30 \
  -t 5 \
  -c:v h264_qsv \
  -global_quality 23 \
  -f null -

確認順序は次のように考えると分かりやすくなります。

nomodeset の有無
↓
Intel GPU
↓
i915 / xe
↓
/dev/dri/renderD128
↓
VA-API / libva
↓
Intel Media Driver
↓
Media SDK / oneVPL
↓
FFmpeg

今回の Gemini Lake / UHD Graphics 605 で分かったこと

今回の実機では、

Intel Corporation GeminiLake [UHD Graphics 605]
Kernel driver in use: i915

であり、/dev/dri/renderD128 も存在していました。

さらに FFmpeg は --enable-libmfx 付きで、qsv / vaapi を認識し、h264_qsv、hevc_qsv、vp9_qsv なども列挙できました。

しかし、

vainfo --display drm --device /dev/dri/renderD128

では、

Trying to open /usr/lib64/dri/iHD_drv_video.so
va_openDriver() returns -1

Trying to open /usr/lib64/dri/i965_drv_video.so
va_openDriver() returns -1

となっていました。

QSV テストでも、

Failed to initialise VAAPI connection
Device creation failed

となりました。

このことから、問題は FFmpeg のエンコードオプションではなく、VA-API / Intel Media Driver 層にあると切り分けられます。

このような場合は、

rpm -qf /usr/lib64/dri/iHD_drv_video.so
ldd /usr/lib64/dri/iHD_drv_video.so

LIBVA_DRIVER_NAME=iHD \
vainfo --display drm --device /dev/dri/renderD128

の順で Intel Media Driver の導入状態・依存関係を調べます。

まとめ

Rocky Linux 9 で FFmpeg + Intel QSV を使う場合、単に ffmpeg -encoders に h264_qsv が表示されれば完了、というわけではありません。

必要になるレイヤは概ね次の通りです。

コンポーネント	必要性	役割
`nomodeset` 無効化	重要	DRM/KMS を正常に初期化
Intel GPU	必須	ハードウェア
`i915` / `xe`	必須	Kernel GPU driver
`/dev/dri/renderD128`	必須	DRM render node
`libva`	Linux QSV 環境で重要	VA-API
`intel-media-driver`	対応 Intel GPU で重要	`iHD_drv_video.so`
`intel-mediasdk`	libmfx 構成	Legacy QSV runtime
`libvpl`	oneVPL 構成	oneVPL dispatcher
`intel-vpl-gpu-rt`	対応する新世代 GPU	oneVPL GPU implementation
QSV 対応 FFmpeg	必須	`h264_qsv` / `hevc_qsv` 等

特に、

Failed to initialise VAAPI connection
Failed to create a VAAPI device

が出た場合には、エンコードオプションを変更する前に、

cat /proc/cmdline
vainfo --display drm --device /dev/dri/renderD128

を確認するのが近道です。

nomodeset が残っていれば外し、vainfo が正常に動かなければ VA-API / Intel Media Driver の問題を先に解決します。

Rocky Linux 9 で QSV を構築するときは、

nomodeset
↓
GPU
↓
Kernel driver
↓
DRM
↓
VA-API
↓
Intel Media Driver
↓
Media SDK / oneVPL
↓
FFmpeg

というレイヤを意識して、下から一段ずつ正常動作を確認するのが最も確実なセットアップ方法です。

Launching MSYS2 Inside a WSL tmux Session

vast cow — Wed, 05 Aug 2026 07:47:59 +0000

This setup allows you to start a WSL tmux session from MSYS2 and then launch an interactive MSYS2 shell inside that tmux session. It combines the convenience of running tmux in WSL with the familiar MSYS2 environment.

Purpose

The main goal is to keep tmux running in WSL while using MSYS2 as the interactive shell inside each tmux pane or window. This approach lets you manage terminal sessions with WSL tmux while continuing to work with MSYS2 tools.

The launcher script starts WSL, connects to a dedicated tmux server, and passes the required environment variables so that MSYS2 starts correctly.

Launcher Script

The launcher script performs the following tasks:

Exports the environment variables required by both WSL and MSYS2.
Prevents automatic path conversion where it is not desired.
Starts tmux inside the target WSL distribution.
Uses a dedicated tmux socket and configuration file.

With this script, you can launch or attach to the tmux session directly from MSYS2.

tmux Configuration

The tmux configuration changes the default command so that every new pane starts an MSYS2 shell instead of a Linux shell.

Before launching MSYS2, the configuration clears the PWD environment variable and updates WSLENV so that the necessary environment variables are available inside the MSYS2 process. It then starts an interactive MSYS2 Bash session.

The configuration also adds MSYSTEM and WSLENV to tmux's update-environment list. This ensures that newly created panes inherit the correct environment.

How to Use

Save the launcher script and make it executable.
Place the tmux configuration in the specified configuration file.
Run the launcher script from MSYS2.
A WSL tmux session will start, and each new pane or window will automatically open an MSYS2 shell.

This setup provides a simple way to use WSL tmux as the session manager while working in the MSYS2 environment.

Please write a simple article in English about the content below labeled “---- content ----”.

Write the title as a level-1 heading using #.
You may use ##, ###, and #### to denote sections, subsections, and sub-subsections.
Do not include any questions asking for additional suggestions.
Focus on the purpose and how to use it, and keep technical explanations to a minimum.

wrapper executed on msys2:

#!/usr/bin/env bash
set -euo pipefail

export WSLENV="MSYSTEM${WSLENV:+:$WSLENV}"
export MSYS2_ARG_CONV_EXCL='*'
export MSYS2_ENV_CONV_EXCL="WSLENV;TMUX;TMUX_PANE${MSYS2_ENV_CONV_EXCL:+;$MSYS2_ENV_CONV_EXCL}"

exec wsl.exe -d tmux --exec tmux \
    -L msys2 \
    -f /path/to/tmux-msys2.conf \
    "$@"

tmux-msys2.conf inside WSL:

set-option -g default-command '
unset PWD
WSLENV="MSYSTEM:PWD/p:$WSLENV"
exec /mnt/c/msys64/usr/bin/bash.exe --login -i
'
set-option -ag update-environment MSYSTEM
set-option -ag update-environment WSLENV

Keeping Rocky Linux 9 Up to Date with `dnf-automatic`

vast cow — Tue, 04 Aug 2026 06:50:08 +0000

Keeping your system updated is one of the most important steps for maintaining security, stability, and performance. On Rocky Linux 9.6, the dnf-automatic package can periodically check for available updates and either notify administrators, download packages, or install updates automatically.

This guide covers installation, configuration, automatic updates, and a notification-only configuration that uses MOTD without downloading or installing packages.

1. Install `dnf-automatic`

The dnf-automatic tool is not installed by default. Install it with:

sudo dnf install -y dnf-automatic

2. Configure `dnf-automatic`

The main configuration file is:

/etc/dnf/automatic.conf

Open it with your preferred text editor:

sudo nano /etc/dnf/automatic.conf

Key options

Upgrade type

The upgrade_type setting controls which updates are detected:

[commands]
upgrade_type = security

Available values include:

default — all available updates
security — only updates associated with security advisories

Download updates

To allow automatic package downloads:

download_updates = yes

To prevent automatic package downloads:

download_updates = no

Apply updates automatically

To install available updates automatically:

apply_updates = yes

To prevent automatic installation:

apply_updates = no

When apply_updates = yes is configured, packages must also be downloaded.

Emitters

The [emitters] section controls how results are reported. Available mechanisms include standard output, email, custom commands, and MOTD.

For example, to report results through MOTD:

[emitters]
emit_via = motd

The MOTD emitter writes the update report to /etc/motd, allowing administrators to see it when logging in through SSH or a local console.

3. Enable Automatic Updates

The generic dnf-automatic.timer follows the behavior configured in /etc/dnf/automatic.conf.

For example, to download and install security updates automatically, configure:

[commands]
upgrade_type = security
download_updates = yes
apply_updates = yes

Then enable and start the timer:

sudo systemctl enable --now dnf-automatic.timer

This causes dnf-automatic to check for and process updates according to the configuration file.

4. Notification Only with MOTD

To notify administrators about available updates without downloading or installing any packages, configure dnf-automatic to use the MOTD emitter.

Edit /etc/dnf/automatic.conf:

sudo nano /etc/dnf/automatic.conf

Use the following settings:

[commands]
upgrade_type = security
download_updates = no
apply_updates = no

[emitters]
emit_via = motd

This configuration:

Checks repository metadata for available security updates
Does not download update packages
Does not install update packages
Writes the result to /etc/motd

Enable the notification-only timer:

sudo systemctl enable --now dnf-automatic-notifyonly.timer

The dnf-automatic-notifyonly.timer unit overrides the download and installation behavior and performs notification only. The explicit download_updates = no and apply_updates = no settings are retained in the configuration for clarity and as a safe default when the generic timer is used.

Disable download and installation timers

To ensure that no other dnf-automatic timer downloads or installs packages, disable the generic, download, and installation timers:

sudo systemctl disable --now dnf-automatic.timer
sudo systemctl disable --now dnf-automatic-download.timer
sudo systemctl disable --now dnf-automatic-install.timer

Then enable only the notification timer:

sudo systemctl enable --now dnf-automatic-notifyonly.timer

Verify the enabled timers:

systemctl list-timers --all | grep dnf-automatic

Only dnf-automatic-notifyonly.timer should be enabled for the notification-only configuration.

Check the MOTD output

Run the service manually to test the configuration:

sudo systemctl start dnf-automatic-notifyonly.service

Display the generated MOTD:

cat /etc/motd

The message will also be displayed during the next SSH or console login, provided the system's login configuration displays /etc/motd.

Note: Checking for updates still requires refreshing or reading repository metadata. The notification-only configuration prevents RPM packages from being downloaded; it does not eliminate repository metadata traffic.

5. Other Timer Modes

dnf-automatic provides several systemd timers for different operating modes.

Follow `/etc/dnf/automatic.conf`

sudo systemctl enable --now dnf-automatic.timer

Notify only

Checks for updates and reports the result without downloading or installing packages:

sudo systemctl enable --now dnf-automatic-notifyonly.timer

Download without installation

Downloads available packages but does not install them:

sudo systemctl enable --now dnf-automatic-download.timer

Download and install

Downloads and installs available updates:

sudo systemctl enable --now dnf-automatic-install.timer

The specialized timer units override the corresponding download and installation settings in /etc/dnf/automatic.conf.

6. Verification and Troubleshooting

Check the notification-only timer:

systemctl status dnf-automatic-notifyonly.timer

Check when it will run next:

systemctl list-timers --all | grep dnf-automatic

Check the service logs:

journalctl -u dnf-automatic-notifyonly.service

Check recent logs for all dnf-automatic units:

journalctl -u 'dnf-automatic*'

Confirm which timers are enabled:

systemctl is-enabled dnf-automatic.timer
systemctl is-enabled dnf-automatic-notifyonly.timer
systemctl is-enabled dnf-automatic-download.timer
systemctl is-enabled dnf-automatic-install.timer

For a notification-only system, the expected result is:

disabled
enabled
disabled
disabled

Conclusion

Rocky Linux 9.6 can use dnf-automatic in several modes:

Automatic installation for systems that should remain patched without manual intervention
Automatic download for systems where installation is performed separately
Notification only for controlled environments where administrators review updates before taking action

For a notification-only configuration with no package downloads, use:

[commands]
upgrade_type = security
download_updates = no
apply_updates = no

[emitters]
emit_via = motd

Enable only:

sudo systemctl enable --now dnf-automatic-notifyonly.timer

This configuration reports available security updates through MOTD while leaving package download and installation under manual control.

`dnf-automatic` を使用して Rocky Linux 9 を最新の状態に保つ

システムを最新の状態に維持することは、セキュリティ、安定性、およびパフォーマンスを確保するために最も重要な作業の一つです。Rocky Linux 9.6 では、dnf-automatic パッケージを使用することで、利用可能な更新を定期的に確認し、管理者への通知、パッケージのダウンロード、または更新の自動インストールを実行できます。

このガイドでは、インストール、設定、自動更新の構成、およびパッケージのダウンロードやインストールを行わずに MOTD を使用して通知のみを行う構成について説明します。

1. `dnf-automatic` をインストールする

dnf-automatic はデフォルトではインストールされていません。次のコマンドでインストールします。

sudo dnf install -y dnf-automatic

2. `dnf-automatic` を設定する

メインの設定ファイルは次の場所にあります。

/etc/dnf/automatic.conf

お好みのテキストエディタで開きます。

sudo nano /etc/dnf/automatic.conf

主な設定項目

更新の種類

upgrade_type は、どの種類の更新を検出するかを指定します。

[commands]
upgrade_type = security

指定できる値は次のとおりです。

default — 利用可能なすべての更新
security — セキュリティアドバイザリに関連付けられた更新のみ

更新パッケージのダウンロード

パッケージを自動的にダウンロードする場合は、次のように設定します。

download_updates = yes

自動ダウンロードを無効にする場合は、次のように設定します。

download_updates = no

更新の自動適用

利用可能な更新を自動的にインストールする場合は、次のように設定します。

apply_updates = yes

自動インストールを無効にする場合は、次のように設定します。

apply_updates = no

apply_updates = yes を設定する場合は、パッケージのダウンロードも有効になっている必要があります。

Emitters（通知方法）

[emitters] セクションでは、結果の通知方法を指定します。利用できる通知方法には、標準出力、メール、カスタムコマンド、および MOTD があります。

たとえば、MOTD を使用して通知する場合は次のように設定します。

[emitters]
emit_via = motd

MOTD エミッターは更新結果を /etc/motd に書き込み、SSH やローカルコンソールでログインした際に管理者が確認できるようにします。

3. 自動更新を有効にする

汎用の dnf-automatic.timer は、/etc/dnf/automatic.conf に設定された内容に従って動作します。

たとえば、セキュリティ更新を自動的にダウンロードしてインストールする場合は、次のように設定します。

[commands]
upgrade_type = security
download_updates = yes
apply_updates = yes

その後、タイマーを有効化して起動します。

sudo systemctl enable --now dnf-automatic.timer

これにより、dnf-automatic は設定ファイルに従って更新を確認し、必要な処理を実行します。

4. MOTD を使用した通知のみの構成

パッケージをダウンロードまたはインストールせず、利用可能な更新だけを管理者へ通知する場合は、dnf-automatic を MOTD エミッターで構成します。

/etc/dnf/automatic.conf を編集します。

sudo nano /etc/dnf/automatic.conf

次のように設定します。

[commands]
upgrade_type = security
download_updates = no
apply_updates = no

[emitters]
emit_via = motd

この構成では次の動作を行います。

利用可能なセキュリティ更新を確認する
更新パッケージはダウンロードしない
更新パッケージはインストールしない
結果を /etc/motd に書き込む

通知専用タイマーを有効にします。

sudo systemctl enable --now dnf-automatic-notifyonly.timer

dnf-automatic-notifyonly.timer は、ダウンロードおよびインストール動作を上書きし、通知のみを実行します。download_updates = no および apply_updates = no を設定ファイルに明示的に記述しておくことで、設定内容が分かりやすくなり、汎用タイマーを使用した場合でも安全なデフォルトとして機能します。

ダウンロードおよびインストール用タイマーを無効にする

他の dnf-automatic タイマーによってパッケージがダウンロードまたはインストールされないようにするため、汎用タイマー、ダウンロードタイマー、およびインストールタイマーを無効にします。

sudo systemctl disable --now dnf-automatic.timer
sudo systemctl disable --now dnf-automatic-download.timer
sudo systemctl disable --now dnf-automatic-install.timer

その後、通知専用タイマーのみを有効にします。

sudo systemctl enable --now dnf-automatic-notifyonly.timer

有効になっているタイマーを確認します。

systemctl list-timers --all | grep dnf-automatic

通知専用構成では、dnf-automatic-notifyonly.timer のみが有効になっていることを確認してください。

MOTD の出力を確認する

設定をテストするためにサービスを手動で実行します。

sudo systemctl start dnf-automatic-notifyonly.service

生成された MOTD を表示します。

cat /etc/motd

システムのログイン設定で /etc/motd が表示されるようになっていれば、次回 SSH またはローカルコンソールでログインした際にも同じ内容が表示されます。

注: 更新の確認では、リポジトリメタデータの更新または読み込みが必要です。通知専用構成では RPM パッケージのダウンロードは行われませんが、リポジトリメタデータの通信自体は発生します。

5. その他のタイマーモード

dnf-automatic には、用途に応じた複数の systemd タイマーが用意されています。

`/etc/dnf/automatic.conf` の設定に従う

sudo systemctl enable --now dnf-automatic.timer

通知のみ

更新を確認し、ダウンロードやインストールを行わずに結果だけを通知します。

sudo systemctl enable --now dnf-automatic-notifyonly.timer

ダウンロードのみ

利用可能な更新パッケージをダウンロードしますが、インストールは行いません。

sudo systemctl enable --now dnf-automatic-download.timer

ダウンロードとインストール

更新パッケージをダウンロードし、そのままインストールします。

sudo systemctl enable --now dnf-automatic-install.timer

これらの専用タイマーは、/etc/dnf/automatic.conf に設定されたダウンロードおよびインストールに関する項目を必要に応じて上書きして動作します。

6. 動作確認とトラブルシューティング

通知専用タイマーの状態を確認します。

systemctl status dnf-automatic-notifyonly.timer

次回の実行予定を確認します。

systemctl list-timers --all | grep dnf-automatic

サービスログを確認します。

journalctl -u dnf-automatic-notifyonly.service

dnf-automatic に関連するすべてのログを確認します。

journalctl -u 'dnf-automatic*'

各タイマーが有効かどうかを確認します。

systemctl is-enabled dnf-automatic.timer
systemctl is-enabled dnf-automatic-notifyonly.timer
systemctl is-enabled dnf-automatic-download.timer
systemctl is-enabled dnf-automatic-install.timer

通知専用構成では、期待される結果は次のとおりです。

disabled
enabled
disabled
disabled

まとめ

Rocky Linux 9.6 では、dnf-automatic を次のような用途に応じて利用できます。

手動操作なしで常に最新の状態を維持したいシステム向けの自動インストール
インストールは別途実施し、事前にパッケージだけを取得したい環境向けの自動ダウンロード
更新内容を管理者が確認したうえで適用する運用向けの通知のみ

パッケージをダウンロードせず、通知のみを行う構成は次のとおりです。

[commands]
upgrade_type = security
download_updates = no
apply_updates = no

[emitters]
emit_via = motd

有効にするタイマーは次のものだけです。

sudo systemctl enable --now dnf-automatic-notifyonly.timer

この構成では、利用可能なセキュリティ更新が MOTD を通じて通知され、パッケージのダウンロードおよびインストールは手動管理のまま維持されます。

How to Install UEK and bcache-tools on Rocky Linux 9

vast cow — Sun, 02 Aug 2026 06:11:33 +0000

Strategy

Keep Rocky Linux 9 BaseOS/AppStream unchanged, and only retrieve the following from the Oracle Linux side:

UEK itself: kernel-uek and its dependent subpackages
bcache-tools
Do not install Oracle Linux userland, oraclelinux-release-el9, Oracle's glibc, etc.

The Oracle Linux Yum Server officially provides instructions for use from RHEL-compatible distributions, but the configuration of running UEK on Rocky Linux is not considered officially supported by either Oracle or Rocky. (Oracle Linux Yum Server)

The following assumes x86_64.

UEK R7 or R8

As of August 2026, the following are available for Oracle Linux 9:

Series	Kernel Series	Selection Criteria
UEK R7	5.15	Relatively conservative in mixed configuration with Rocky 9
UEK R8	6.12	Prioritize newer hardware/features

Oracle's current UEK R8 repository contains 6.12 series kernel-uek, kernel-uek-core, and various modules packages. (Oracle Linux Yum Server)
UEK R7 is 5.15 series. (Oracle Linux Yum Server)

Here, to slightly reduce mixed configuration risk, we'll use UEK R7 as an example. To switch to R8, replace UEKR7 with UEKR8 in the URLs.

1. Pre-check

cat /etc/rocky-release
uname -m
findmnt /boot
findmnt /boot/efi 2>/dev/null || true
mokutil --sb-state 2>/dev/null || true

Do not remove the existing Rocky kernel. It serves as recovery if UEK fails to boot.

Before working, update Rocky to its normal state.

sudo dnf upgrade --refresh
sudo reboot

After reboot:

uname -r

2. Register Oracle Linux 9 Signing Key

Place Oracle's official OL9 key.

sudo curl -fsSL \
  https://yum.oracle.com/RPM-GPG-KEY-oracle-ol9 \
  -o /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9

Verify the fingerprint.

gpg --show-keys --with-fingerprint \
  /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9

Confirm it matches at least the following fingerprints published by Oracle:

3E6D 826D 3FBA B389 C2F3 8E34 BC4D 06A0 8D8B 756F
9822 3175 9C74 6706 5D0C E9B2 A7DD 0708 8B4E FBE6

The OL9 key acquisition source and fingerprints are published by Oracle. (Oracle Linux Yum Server)

Also import into the RPM database.

sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9

3. Create a Minimally Restricted Oracle Repository

Do not install oraclelinux-release-el9; create your own repo file with just two entries.

sudo tee /etc/yum.repos.d/oracle-uek-minimal.repo >/dev/null <<'EOF'
[oracle-uek-r7-minimal]
name=Oracle Linux 9 UEK R7 - restricted
baseurl=https://yum.oracle.com/repo/OracleLinux/OL9/UEKR7/$basearch/
enabled=0
gpgcheck=1
repo_gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9
includepkgs=kernel-uek,kernel-uek-core,kernel-uek-modules,kernel-uek-modules-extra
metadata_expire=6h
skip_if_unavailable=0

[oracle-baseos-bcache-minimal]
name=Oracle Linux 9 BaseOS - bcache-tools only
baseurl=https://yum.oracle.com/repo/OracleLinux/OL9/baseos/latest/$basearch/
enabled=0
gpgcheck=1
repo_gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9
includepkgs=bcache-tools
metadata_expire=6h
skip_if_unavailable=0
EOF

Two important points:

enabled=0: Normal dnf upgrade won't use Oracle repositories
includepkgs=: Prevents packages other than explicitly listed ones from being obtained from Oracle

The Oracle Linux 9 BaseOS URL is the same as what Oracle recommends for RHEL-compatible environments. (Oracle Linux Yum Server)

If Using UEK R8

Instead of R7, use the following UEK entry:

[oracle-uek-r8-minimal]
name=Oracle Linux 9 UEK R8 - restricted
baseurl=https://yum.oracle.com/repo/OracleLinux/OL9/UEKR8/$basearch/
enabled=0
gpgcheck=1
repo_gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9
includepkgs=kernel-uek,kernel-uek-core,kernel-uek-modules-core,kernel-uek-modules,kernel-uek-modules-extra
metadata_expire=6h
skip_if_unavailable=0

R8 has different package splitting from R7, including kernel-uek-modules-core. (Oracle Linux Yum Server)

4. Verify Packages Visible from Oracle

First, check candidates without installing.

sudo dnf clean metadata

sudo dnf \
  --disablerepo='oracle-*' \
  --enablerepo=oracle-uek-r7-minimal \
  repoquery --available 'kernel-uek*'

Also check bcache-tools.

sudo dnf \
  --disablerepo='oracle-*' \
  --enablerepo=oracle-baseos-bcache-minimal \
  repoquery --available --info bcache-tools

On Oracle Linux 9, bcache-tools is provided as an Oracle BaseOS additional package. (Oracle Docs)

Verify Sources

sudo dnf repoquery \
  --available \
  --qf '%{name}-%{evr}.%{arch} <- %{repoid}' \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

5. Pre-check the Transaction

First, use --assumeno.

sudo dnf install --assumeno \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

Check these points:

Only kernel-uek* and bcache-tools come from Oracle
glibc, systemd, dracut, grub2, etc. are not replaced with Oracle versions
Rocky BaseOS/AppStream packages are not removed
--allowerasing is not required

Abort if any unexpected Oracle packages appear.

For a stricter check:

sudo dnf install --assumeno -v \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

6. Install UEK and bcache-tools

If the pre-check passes, execute.

sudo dnf install \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

The kernel-uek meta package installs kernel-uek-core and modules as dependencies. The UEK R7 repository contains these at the same version. (Oracle Linux Yum Server)

Verify:

rpm -qa | grep -E '^(kernel-uek|bcache-tools)' | sort

Also verify the vendor:

rpm -q \
  --qf '%{NAME} %{VERSION}-%{RELEASE} | %{VENDOR}\n' \
  kernel-uek bcache-tools

Check all Oracle-origin packages:

rpm -qa \
  --qf '%{NAME} %{VERSION}-%{RELEASE} | %{VENDOR}\n' |
grep -i oracle |
sort

Confirm there are no unintended Oracle userland packages.

7. Verify initramfs and bcache Module

Installing UEK usually generates initramfs.

List installed UEK:

rpm -q kernel-uek-core
ls -lh /boot/vmlinuz-*uek /boot/initramfs-*uek.img

Check if bcache module exists in the UEK kernel.

UEK_VER="$(rpm -q --qf '%{VERSION}-%{RELEASE}.%{ARCH}\n' \
  kernel-uek-core | sort -V | tail -1)"

echo "$UEK_VER"
modinfo -k "$UEK_VER" bcache

If modinfo returns information, the UEK has the bcache module.

To explicitly include it in initramfs:

sudo dracut --force \
  --add-drivers bcache \
  "/boot/initramfs-${UEK_VER}.img" \
  "$UEK_VER"

However, if the root filesystem is not on bcache, forcing inclusion in initramfs at boot is usually unnecessary. You can modprobe bcache after boot.

8. Verify Registration in GRUB

sudo grubby --info=ALL |
grep -E '^(index|kernel|title)='

Identify the UEK entry.

sudo grubby --info=ALL |
grep -B2 -A3 'el9uek'

It's safer not to set UEK as default initially; instead, select UEK from the GRUB menu once for booting.

To make the GRUB menu easier to display:

sudo grub2-editenv - unset menu_auto_hide

9. Test Boot with UEK

After rebooting, select the entry containing el9uek from GRUB.

sudo reboot

After booting:

uname -r

Expected example:

5.15.0-...el9uek.x86_64

Check bcache:

sudo modprobe bcache
lsmod | grep '^bcache'

Check tools:

make-bcache --version
bcache-super-show --help

Also check kernel logs.

sudo journalctl -b -k -p warning
sudo dmesg -T | grep -iE 'bcache|error|failed|firmware'

Verify network, storage, console, and SELinux.

ip addr
findmnt
getenforce
systemctl --failed

10. Make UEK Default if No Issues

To make the currently booting UEK the default:

sudo grubby --set-default "/boot/vmlinuz-$(uname -r)"
sudo grubby --default-kernel

Or, specify the latest installed UEK:

UEK_KERNEL="$(ls -1 /boot/vmlinuz-*el9uek* | sort -V | tail -1)"
sudo grubby --set-default "$UEK_KERNEL"
sudo grubby --default-kernel

Keep the Rocky standard kernel.

rpm -q kernel-core
ls -1 /boot/vmlinuz-*

11. Update Method

Oracle repositories remain disabled, so normal updates target only Rocky.

sudo dnf upgrade

Only enable Oracle repositories explicitly when updating UEK and bcache-tools.

sudo dnf upgrade \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  'kernel-uek*' bcache-tools

To be more cautious, pre-check each time.

sudo dnf upgrade --assumeno \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  'kernel-uek*' bcache-tools

Avoid `dnf upgrade --enablerepo=oracle-...` Alone

It's safer not to run unspecified updates like:

# Not recommended
sudo dnf upgrade --enablerepo=oracle-uek-r7-minimal

Currently restricted by includepkgs, but explicitly specifying update targets prevents accidents.

12. Secure Boot Considerations

When Secure Boot is enabled, the main issue is not RPM signatures but whether Rocky's shim/firmware trusts Oracle's kernel signature.

Check:

mokutil --sb-state

If SecureBoot enabled, UEK may fail to boot with errors like:

Verification failed
Security Violation
Bad shim signature

In this mixed configuration, it's practical to test with one of the following:

Disable Secure Boot during verification
Properly register the Oracle kernel signing certificate in MOK

The latter requires certificate acquisition, verification, and MOK enrollment, which is not resolved by simply registering the Oracle RPM GPG key. RPM package signing keys and UEFI Secure Boot kernel signing certificates are different.

13. Minimum Precautions Before Using bcache

make-bcache destroys existing data on target devices. Verify device names thoroughly.

lsblk -o NAME,SIZE,MODEL,SERIAL,TYPE,FSTYPE,MOUNTPOINTS

Example:

# SSD cache side
sudo make-bcache --cache /dev/nvme0n1p1

# HDD backend side
sudo make-bcache --bdev /dev/sdb

This writes the bcache superblock to the specified devices. Before substituting actual device names, ensure backups and console access.

According to Linux kernel documentation, bcache supports writethrough and writeback, with writeback disabled by default. (Linux Kernel Documentation)

For initial testing, using writethrough is more appropriate to minimize write loss risk.

Rollback

If UEK fails to boot, select the Rocky standard kernel from GRUB.

Return the Rocky kernel to default:

ROCKY_KERNEL="$(ls -1 /boot/vmlinuz-*el9_* 2>/dev/null |
  grep -v el9uek |
  sort -V |
  tail -1)"

sudo grubby --set-default "$ROCKY_KERNEL"
sudo grubby --default-kernel

Remove UEK:

sudo dnf remove 'kernel-uek*'

If bcache-tools is also unnecessary:

sudo dnf remove bcache-tools

Disable or remove the repo file:

sudo mv \
  /etc/yum.repos.d/oracle-uek-minimal.repo \
  /etc/yum.repos.d/oracle-uek-minimal.repo.disabled

Recommended Final Configuration

Rocky BaseOS/AppStream: always enabled
Oracle UEK repo: enabled=0
Oracle BaseOS repo: enabled=0
Oracle side includepkgs:
- kernel-uek
- kernel-uek-core
- Modules packages required for the UEK series
- bcache-tools
Rocky standard kernel: always keep at least one generation
UEK updates: manually execute by specifying package names
Secure Boot: pre-verification required
DKMS/kmod products: individually verify UEK ABI compatibility

This method effectively limits Oracle-origin packages to the kernel set and bcache-tools, preventing Oracle-ization of the Rocky userland.

Rocky Linux 9へUEKを導入する手順（Oracleリポジトリ最小利用）

方針

Rocky Linux 9のBaseOS/AppStreamはそのまま維持し、Oracle Linux側からは次だけ取得します。

UEK本体: kernel-uekと、その依存サブパッケージ
bcache-tools
Oracle Linuxの通常ユーザーランド、oraclelinux-release-el9、Oracle版glibcなどは導入しない

Oracle Linux yum serverはRHEL互換ディストリビューションからの利用方法を公式に案内していますが、Rocky Linux上でUEKを動かす構成自体はOracle/Rocky双方の正式サポート対象とは考えないでください。(Oracle Linux Yum Server)

以下は x86_64 前提です。

UEK R7かR8か

2026年8月時点では、Oracle Linux 9向けに以下があります。

系列	カーネル系列	選択基準
UEK R7	5.15	Rocky 9との混成構成では比較的保守的
UEK R8	6.12	新しいハードウェア・機能を優先

Oracleの現行UEK R8リポジトリには、6.12系のkernel-uek、kernel-uek-core、各種modulesパッケージが収録されています。(Oracle Linux Yum Server)
UEK R7は5.15系です。(Oracle Linux Yum Server)

ここでは、混成リスクを少し抑えるため UEK R7 を例にします。R8へ変更する場合はURL中のUEKR7をUEKR8へ置き換えます。

1. 事前確認

cat /etc/rocky-release
uname -m
findmnt /boot
findmnt /boot/efi 2>/dev/null || true
mokutil --sb-state 2>/dev/null || true

既存Rockyカーネルは削除しません。UEKが起動できない場合の復旧用です。

作業前に、Rocky側を通常の状態へ更新します。

sudo dnf upgrade --refresh
sudo reboot

再起動後:

uname -r

2. Oracle Linux 9署名鍵を登録

Oracle公式のOL9用鍵を配置します。

sudo curl -fsSL \
  https://yum.oracle.com/RPM-GPG-KEY-oracle-ol9 \
  -o /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9

フィンガープリントを確認します。

gpg --show-keys --with-fingerprint \
  /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9

少なくとも、Oracle公式掲載の次のフィンガープリントと一致することを確認します。

3E6D 826D 3FBA B389 C2F3 8E34 BC4D 06A0 8D8B 756F
9822 3175 9C74 6706 5D0C E9B2 A7DD 0708 8B4E FBE6

Oracleが公開しているOL9鍵の取得先とフィンガープリントです。(Oracle Linux Yum Server)

RPMデータベースにも登録します。

sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9

3. 最小限に制限したOracleリポジトリを作成

oraclelinux-release-el9はインストールせず、自前のrepoファイルを2エントリだけ作ります。

sudo tee /etc/yum.repos.d/oracle-uek-minimal.repo >/dev/null <<'EOF'
[oracle-uek-r7-minimal]
name=Oracle Linux 9 UEK R7 - restricted
baseurl=https://yum.oracle.com/repo/OracleLinux/OL9/UEKR7/$basearch/
enabled=0
gpgcheck=1
repo_gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9
includepkgs=kernel-uek,kernel-uek-core,kernel-uek-modules,kernel-uek-modules-extra
metadata_expire=6h
skip_if_unavailable=0

[oracle-baseos-bcache-minimal]
name=Oracle Linux 9 BaseOS - bcache-tools only
baseurl=https://yum.oracle.com/repo/OracleLinux/OL9/baseos/latest/$basearch/
enabled=0
gpgcheck=1
repo_gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9
includepkgs=bcache-tools
metadata_expire=6h
skip_if_unavailable=0
EOF

重要なのは次の2点です。

enabled=0: 通常のdnf upgradeではOracleリポジトリを使わない
includepkgs=: 明示したパッケージ以外をOracleから取得できないようにする

Oracle Linux 9のBaseOS URLは、OracleがRHEL互換環境向けに案内しているものと同じです。(Oracle Linux Yum Server)

UEK R8を使う場合

R7の代わりに、UEKエントリを次のようにします。

[oracle-uek-r8-minimal]
name=Oracle Linux 9 UEK R8 - restricted
baseurl=https://yum.oracle.com/repo/OracleLinux/OL9/UEKR8/$basearch/
enabled=0
gpgcheck=1
repo_gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-oracle-ol9
includepkgs=kernel-uek,kernel-uek-core,kernel-uek-modules-core,kernel-uek-modules,kernel-uek-modules-extra
metadata_expire=6h
skip_if_unavailable=0

R8ではパッケージ分割がR7と異なり、kernel-uek-modules-coreが存在します。(Oracle Linux Yum Server)

4. Oracleから見えるパッケージを確認

まずインストールせず、候補だけ確認します。

sudo dnf clean metadata

sudo dnf \
  --disablerepo='oracle-*' \
  --enablerepo=oracle-uek-r7-minimal \
  repoquery --available 'kernel-uek*'

bcache-toolsも確認します。

sudo dnf \
  --disablerepo='oracle-*' \
  --enablerepo=oracle-baseos-bcache-minimal \
  repoquery --available --info bcache-tools

Oracle Linux 9ではbcache-toolsがOracleによるBaseOS追加パッケージとして提供されています。(Oracle Docs)

取得元を確認

sudo dnf repoquery \
  --available \
  --qf '%{name}-%{evr}.%{arch} <- %{repoid}' \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

5. トランザクションを事前確認

最初は--assumenoを付けます。

sudo dnf install --assumeno \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

確認すべき点:

Oracleから入るものがkernel-uek*とbcache-toolsだけ
glibc、systemd、dracut、grub2などがOracle版へ置換されない
RockyのBaseOS/AppStreamパッケージが削除されない
--allowerasingを要求されない

想定外のOracleパッケージが表示された場合は中止します。

より厳密に確認するには:

sudo dnf install --assumeno -v \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

6. UEKとbcache-toolsをインストール

事前確認に問題がなければ実行します。

sudo dnf install \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  kernel-uek bcache-tools

kernel-uekメタパッケージが、対応するkernel-uek-coreとmodulesを依存関係として導入します。UEK R7リポジトリにはこれらが同一バージョンで収録されています。(Oracle Linux Yum Server)

確認:

rpm -qa | grep -E '^(kernel-uek|bcache-tools)' | sort

ベンダーも確認します。

rpm -q \
  --qf '%{NAME} %{VERSION}-%{RELEASE} | %{VENDOR}\n' \
  kernel-uek bcache-tools

Oracle由来パッケージ全体の確認:

rpm -qa \
  --qf '%{NAME} %{VERSION}-%{RELEASE} | %{VENDOR}\n' |
grep -i oracle |
sort

ここで、意図しないOracle版ユーザーランドがないことを確認します。

7. initramfsとbcacheモジュールを確認

UEKのインストールで通常はinitramfsが生成されます。

インストール済みUEK一覧:

rpm -q kernel-uek-core
ls -lh /boot/vmlinuz-*uek /boot/initramfs-*uek.img

UEKカーネル内にbcacheモジュールがあるか確認します。

UEK_VER="$(rpm -q --qf '%{VERSION}-%{RELEASE}.%{ARCH}\n' \
  kernel-uek-core | sort -V | tail -1)"

echo "$UEK_VER"
modinfo -k "$UEK_VER" bcache

modinfoが情報を返せば、そのUEKにbcacheモジュールがあります。

initramfsへ明示的に入れる場合:

sudo dracut --force \
  --add-drivers bcache \
  "/boot/initramfs-${UEK_VER}.img" \
  "$UEK_VER"

ただし、ルートファイルシステムをbcache上に置かないのであれば、通常は起動時initramfsへの強制追加は不要です。起動後にmodprobe bcacheできます。

8. GRUBへ登録されているか確認

sudo grubby --info=ALL |
grep -E '^(index|kernel|title)='

UEKエントリを特定します。

sudo grubby --info=ALL |
grep -B2 -A3 'el9uek'

最初からデフォルトにはせず、まず一度だけGRUBメニューからUEKを選択して起動するのが安全です。

GRUBメニューを表示しやすくする場合:

sudo grub2-editenv - unset menu_auto_hide

9. UEKでテスト起動

再起動後、GRUBからel9uekを含むエントリを選択します。

sudo reboot

起動後:

uname -r

想定例:

5.15.0-...el9uek.x86_64

bcacheを確認:

sudo modprobe bcache
lsmod | grep '^bcache'

ツール確認:

make-bcache --version
bcache-super-show --help

カーネルログも確認します。

sudo journalctl -b -k -p warning
sudo dmesg -T | grep -iE 'bcache|error|failed|firmware'

ネットワーク、ストレージ、コンソール、SELinuxも確認します。

ip addr
findmnt
getenforce
systemctl --failed

10. 問題なければUEKをデフォルトにする

現在起動中のUEKをデフォルトにするなら:

sudo grubby --set-default "/boot/vmlinuz-$(uname -r)"
sudo grubby --default-kernel

または、インストール済み最新UEKを指定:

UEK_KERNEL="$(ls -1 /boot/vmlinuz-*el9uek* | sort -V | tail -1)"
sudo grubby --set-default "$UEK_KERNEL"
sudo grubby --default-kernel

Rocky標準カーネルは残してください。

rpm -q kernel-core
ls -1 /boot/vmlinuz-*

11. 更新方法

Oracleリポジトリは無効のままなので、通常の更新はRockyだけが対象です。

sudo dnf upgrade

UEKとbcache-toolsを更新するときだけ明示的に有効化します。

sudo dnf upgrade \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  'kernel-uek*' bcache-tools

より慎重にするなら、毎回事前確認します。

sudo dnf upgrade --assumeno \
  --enablerepo=oracle-uek-r7-minimal \
  --enablerepo=oracle-baseos-bcache-minimal \
  'kernel-uek*' bcache-tools

`dnf upgrade --enablerepo=oracle-...`だけは避ける

次のような無指定更新は実行しない方が安全です。

# 非推奨
sudo dnf upgrade --enablerepo=oracle-uek-r7-minimal

現状はincludepkgsで制限されていますが、更新対象を明示する方が事故を防げます。

12. Secure Bootの注意

Secure Bootが有効な場合、最大の問題はRPM署名ではなく、Rockyのshim/ファームウェアがOracleのカーネル署名を信頼するかです。

確認:

mokutil --sb-state

SecureBoot enabledの場合、UEKが次のようなエラーで起動できない可能性があります。

Verification failed
Security Violation
Bad shim signature

この混成構成では、まず以下のどちらかで検証するのが現実的です。

検証段階ではSecure Bootを無効化する
Oracleカーネルの署名証明書をMOKへ適切に登録する

後者は証明書の取得・検証・MOK登録が必要で、単純にOracle RPM GPG鍵を登録するだけでは解決しません。RPMパッケージ署名鍵とUEFI Secure Boot用カーネル署名証明書は別物です。

13. bcacheを使い始める前の最低限の注意

make-bcacheは対象デバイスの既存データを破壊します。デバイス名を十分に確認してください。

lsblk -o NAME,SIZE,MODEL,SERIAL,TYPE,FSTYPE,MOUNTPOINTS

例として:

# SSDキャッシュ側
sudo make-bcache --cache /dev/nvme0n1p1

# HDDバックエンド側
sudo make-bcache --bdev /dev/sdb

この操作は指定デバイスへbcacheスーパーブロックを書き込みます。実デバイス名へ読み替える前に、バックアップとコンソールアクセスを確保してください。

Linuxカーネル文書によると、bcacheはwritethroughとwritebackをサポートし、writebackは既定で無効です。(Linuxカーネルドキュメント)

初期検証では、書き込み損失リスクを抑えるためwritethroughのまま使う方が妥当です。

ロールバック

UEKで起動できない場合は、GRUBからRocky標準カーネルを選択します。

Rockyカーネルをデフォルトへ戻す:

ROCKY_KERNEL="$(ls -1 /boot/vmlinuz-*el9_* 2>/dev/null |
  grep -v el9uek |
  sort -V |
  tail -1)"

sudo grubby --set-default "$ROCKY_KERNEL"
sudo grubby --default-kernel

UEKを削除:

sudo dnf remove 'kernel-uek*'

bcache-toolsも不要なら:

sudo dnf remove bcache-tools

repoファイルを無効化または削除:

sudo mv \
  /etc/yum.repos.d/oracle-uek-minimal.repo \
  /etc/yum.repos.d/oracle-uek-minimal.repo.disabled

推奨する最終構成

Rocky BaseOS/AppStream: 常時有効
Oracle UEK repo: enabled=0
Oracle BaseOS repo: enabled=0
Oracle側のincludepkgs:
- kernel-uek
- kernel-uek-core
- UEK系列に必要なmodulesパッケージ
- bcache-tools
Rocky標準カーネル: 最低1世代を常に保持
UEK更新: パッケージ名を指定して手動実行
Secure Boot: 事前検証必須
DKMS/kmod製品: UEK ABI対応を個別確認

この方法なら、Oracle由来パッケージをカーネル一式とbcache-toolsへ実質的に限定し、RockyユーザーランドのOracle化を防げます。

Exposing Supermicro X11DPI (ATEN IPMI) with Tailscale Serve: Use `socat` or Nginx `stream` Instead of an HTTP Reverse Proxy

vast cow — Fri, 31 Jul 2026 11:01:26 +0000

While trying to expose the IPMI interface (ATEN-based) on a Supermicro X11 series motherboard using Tailscale Services (tailscale serve --service), I ran into an unexpected pitfall.

The conclusion is straightforward:

When exposing ATEN IPMI through Tailscale Serve, a TCP-level proxy (such as socat or Nginx stream) should be your first choice instead of an HTTP reverse proxy.

What I Wanted to Do

I wanted to expose the IPMI interface on my LAN under a service name like:

https://x11dpi-ipmi.<tailnet>.ts.net/

With Tailscale Services, this can be configured as:

tailscale serve \
  --service=svc:x11dpi-ipmi \
  --https=443 \
  https+insecure://x.x.x.x

However, the HTML5 KVM console did not work correctly.

My First Suspect: WebSockets

The HTML5 KVM console uses WebSockets.

My initial assumptions were:

Maybe Tailscale Serve doesn't fully support WebSockets.
Maybe the Upgrade header isn't being forwarded correctly.

However, my own aiohttp WebSocket server worked perfectly through the same setup.

That meant there was nothing inherently wrong with the combination of:

Tailscale
WebSockets
The browser

The Actual Cause

After inserting Nginx as an HTTP reverse proxy for debugging, I found this error:

upstream sent invalid header: "\x20..."

resulting in:

502 Bad Gateway

The request flow looked like this:

Browser
    ↓
Tailscale
    ↓
Nginx HTTP Proxy
    ↓
ATEN IPMI

This indicates that Nginx rejects the HTTP response headers returned by the ATEN IPMI firmware as invalid.

Simple GET requests work, but CGI requests such as:

POST /cgi/ipmi.cgi

fail.

For example:

op=UID_SUPPORT.XML

returns 502 Bad Gateway when sent via POST.

Meanwhile:

GET /cgi/ipmi.cgi

works without issue.

In other words, this is an HTTP protocol compatibility issue.

This Is Not a WebSocket Problem

Since only the HTML5 KVM console initially appeared to fail, WebSockets seemed like the obvious culprit.

In reality, however:

The HTTP parser fails while processing the CGI POST response.

The browser never reaches the stage where WebSocket communication becomes relevant because HTTP communication with the IPMI interface has already failed.

Solution 1: `socat` (Recommended)

Instead of interpreting HTTP at all, simply forward TCP traffic:

Tailscale
    ↓ TLS termination
TCP
    ↓
socat
    ↓ TLS
IPMI

For example:

socat \
  TCP4-LISTEN:8082,bind=127.0.0.1,reuseaddr,fork \
  OPENSSL:x.x.x.x:443,verify=0

Then configure Tailscale Serve:

tailscale serve \
  --service=svc:x11dpi-ipmi \
  --tls-terminated-tcp=443 \
  tcp://127.0.0.1:8082

With this configuration, everything worked correctly:

CGI
Cookies
WebSockets
HTML5 KVM

Because no HTTP headers are parsed, ATEN's non-standard HTTP implementation is passed through unchanged.

Solution 2: Nginx `stream`

Nginx can achieve the same result by using the stream module instead of the HTTP module.

stream {
    server {
        listen 127.0.0.1:8082;

        proxy_ssl on;
        proxy_ssl_verify off;

        proxy_pass x.x.x.x:443;
    }
}

Since stream operates as a TCP proxy, it never parses HTTP headers.

As a result, it avoids compatibility issues with the ATEN IPMI firmware.

Why I Don't Recommend an HTTP Reverse Proxy

The conventional approach would be something like:

proxy_pass https://x.x.x.x;

However, with ATEN IPMI this can result in:

upstream sent invalid header

This happens before considerations such as:

Host headers
Origin
WebSockets

The HTTP response itself is rejected by Nginx's parser.

Adjusting buffer sizes or disabling buffering (for example, proxy_buffering off) does not resolve the problem.

Why `socat` Works

socat does not understand HTTP.

It simply forwards TCP streams.

Therefore, even if the ATEN IPMI firmware returns unconventional HTTP responses, socat passes them through unchanged.

Modern browsers are apparently tolerant enough to process those responses successfully.

Conclusion

When exposing an ATEN-based Supermicro X11 IPMI interface through Tailscale Services, my recommended order is:

socat + tailscale serve --tls-terminated-tcp
Nginx stream + tailscale serve --tls-terminated-tcp
Nginx HTTP reverse proxy (not recommended)

For most web applications, an HTTP reverse proxy is the default choice.

ATEN IPMI is an exception.

A TCP-level proxy that forwards traffic without inspecting HTTP is significantly more reliable than an HTTP-aware reverse proxy.

If you encounter errors such as upstream sent invalid header or 502 Bad Gateway, don't assume the problem is with WebSockets or Tailscale. First, check whether you're routing the traffic through an HTTP reverse proxy.

Supermicro X11DPI (ATEN IPMI) を Tailscale Serve で公開するなら、Nginx HTTP Proxy ではなく socat / Nginx stream を使う

Supermicro X11世代のIPMI（ATENベース）を Tailscale Services (tailscale serve --service) で公開しようとしたところ、意外な落とし穴にはまりました。

結論から言うと、

ATEN IPMIを Tailscale Serve 経由で公開する場合は、HTTPリバースプロキシではなく TCPレベルで中継する構成（socat または Nginx stream）が第一選択です。

やりたかったこと

LAN内のIPMIを

https://x11dpi-ipmi.<tailnet>.ts.net/

のようなサービス名で公開したい。

Tailscale Services を使えば、

tailscale serve \
  --service=svc:x11dpi-ipmi \
  --https=443 \
  https+insecure://x.x.x.x

のような構成が作れます。

しかし、実際にはHTML5 KVMが正常に動作しませんでした。

最初に疑ったのはWebSocket

HTML5 KVMはWebSocketを使用しています。

そのため、

Tailscale ServeがWebSocketに対応していないのでは？
Upgradeヘッダーが落ちているのでは？

と考えました。

しかし、自作の aiohttp WebSocketサーバーでは正常に動作しました。

つまり、

Tailscale
WebSocket
ブラウザ

の組み合わせ自体には問題がありません。

実際の原因

NginxをHTTPリバースプロキシとして挟いて調査すると、

upstream sent invalid header: "\x20..."

というエラーが出ました。

つまり、

502 Bad Gateway

になっています。

これは

ブラウザ
    ↓
Tailscale
    ↓
Nginx HTTP Proxy
    ↓
ATEN IPMI

という構成で、

ATEN IPMIが返すHTTPレスポンスヘッダーをNginxが不正と判断して拒否している

ことを意味します。

GETでは問題なくても、

POST /cgi/ipmi.cgi

のようなCGIでは失敗します。

例えば、

op=UID_SUPPORT.XML

をPOSTすると502になります。

一方、

GET /cgi/ipmi.cgi

は正常に返ります。

つまり、

HTTPレベルの互換性問題です。

これはWebSocketの問題ではない

最初はHTML5 KVMだけが失敗するのでWebSocketを疑いました。

しかし実際には、

CGIのPOSTレスポンスの時点でHTTPパーサが失敗していました。

そのため、

HTML5 KVM以前にIPMIとのHTTP通信自体が成立していません。

解決策1: socat（おすすめ）

HTTPを一切解釈せず、

Tailscale
    ↓ TLS終端
TCP
    ↓
socat
    ↓ TLS
IPMI

という構成にします。

例えば

socat \
  TCP4-LISTEN:8082,bind=127.0.0.1,reuseaddr,fork \
  OPENSSL:x.x.x.x:443,verify=0

そして

tailscale serve \
  --service=svc:x11dpi-ipmi \
  --tls-terminated-tcp=443 \
  tcp://127.0.0.1:8082

とします。

この構成では、

CGI
Cookie
WebSocket
HTML5 KVM

すべて正常に動作しました。

HTTPヘッダーを解析しないため、ATEN独自の実装にも影響されません。

解決策2: Nginx stream

NginxでもHTTPではなくstreamモジュールを使えば同様です。

stream {
    server {
        listen 127.0.0.1:8082;

        proxy_ssl on;
        proxy_ssl_verify off;

        proxy_pass x.x.x.x:443;
    }
}

streamはTCPプロキシなので、

HTTPヘッダーを解析しません。

そのためATEN IPMIとの相性問題を回避できます。

Nginx HTTP Proxyはおすすめしない

一般的には

proxy_pass https://x.x.x.x;

というHTTPリバースプロキシを書きたくなります。

しかしATEN IPMIでは、

upstream sent invalid header

になるケースがあります。

これは

Hostヘッダー
Origin
WebSocket

以前に、

HTTPレスポンス自体がNginxに拒否されるためです。

バッファサイズや proxy_buffering off などでは改善しません。

なぜsocatが動くのか

socatはHTTPを理解していません。

単なるTCP中継です。

そのため、

ATEN IPMIが多少変わったHTTPレスポンスを返しても、

そのままブラウザへ転送します。

結果として、

ブラウザは問題なく処理できます。

結論

ATENベースのSupermicro X11 IPMIをTailscale Servicesで公開する場合のおすすめ順位は次の通りです。

socat + tailscale serve --tls-terminated-tcp
Nginx stream + tailscale serve --tls-terminated-tcp
Nginx HTTP Proxy（非推奨）

一般的なWebアプリではHTTPリバースプロキシが第一選択ですが、ATEN IPMIでは事情が異なります。

HTTPを解析するプロキシよりも、TCPレベルでそのまま中継する構成の方が安定して動作します。

もし upstream sent invalid header や 502 Bad Gateway に遭遇した場合は、WebSocketやTailscaleを疑う前に、HTTPプロキシを経由していないか確認してみてください。

Why NVIDIA Open-Sourced Its Linux GPU Kernel Modules

vast cow — Fri, 31 Jul 2026 03:20:24 +0000

The biggest reason NVIDIA began providing GPL-licensed kernel modules is that its driver architecture evolved to the point where Linux integration, distribution, and maintenance could be greatly simplified while keeping the GPU's critical intellectual property in firmware and user-space components.

To be precise, NVIDIA did not open-source its entire driver stack. The components that became open are primarily the following Linux kernel modules:

nvidia.ko
nvidia-drm.ko
nvidia-uvm.ko
nvidia-modeset.ko

User-space components such as CUDA, OpenGL, Vulkan, and the GSP firmware remain proprietary. (NVIDIA Developer)

1. To make integration with Linux distributions easier

Previously, NVIDIA's proprietary kernel modules had to be built, signed, and distributed separately from the Linux kernel. A DKMS-based workflow, which rebuilds modules after every kernel update, commonly led to problems such as:

Kernel modules failing to build after kernel updates
Unsigned modules being blocked by Secure Boot
Linux distributions having difficulty maintaining the driver as an official package
Increased complexity when integrating with custom kernels or cloud environments

By publishing the source code, distributions such as Ubuntu, Red Hat, and SUSE can integrate NVIDIA's kernel modules into their own packaging, signing, and update infrastructure much more easily. NVIDIA itself cites tighter OS integration and simpler signing and distribution as key motivations. (NVIDIA Developer)

2. To improve debugging and security review

Kernel modules interact with deep parts of the operating system, including memory management, interrupts, inter-process synchronization, PCI Express, and display subsystems.

With the source code available, Linux distribution developers and enterprise users can:

Trace where execution stops inside the kernel
Analyze interactions between GPU events and workloads
Fix incompatibilities with custom kernels
Review security-related issues
Submit patches to NVIDIA

NVIDIA states that community and partner review can improve both driver quality and security. (NVIDIA Developer)

3. Because functionality moved into the GSP

The key technical turning point is the GSP (GPU System Processor).

Previously, much of the GPU control logic ran inside the host CPU's kernel driver. On newer GPUs, however, the internal GSP firmware performs critical tasks such as hardware initialization and management.

Conceptually, the architecture changed as follows:

Previous:

Linux kernel module
        ↓ Direct low-level hardware control
GPU

Current:

Linux kernel module
        ↓ Commands / RPC
GSP firmware
        ↓
GPU hardware

This allows hardware-specific complexity and sensitive implementation details to remain inside signed firmware while exposing only the Linux-facing kernel interface. NVIDIA explicitly identifies the gradual adoption of the GSP driver architecture as the technical foundation that made the initial open-source kernel modules possible. (NVIDIA Developer)

In other words, NVIDIA did not simply change corporate policy—it redesigned the driver architecture in advance so that the kernel-facing portion could be released as open source.

4. To simplify AI, cloud, and data center deployments

Today, NVIDIA GPUs are used not only in desktop systems but also in:

Kubernetes clusters
AI training servers
Cloud virtual machines
Grace Hopper systems
Confidential Computing environments
Unified memory architectures

In these environments, it is essential to integrate GPU drivers into OS images and container platforms automatically and securely.

The open kernel modules also introduced support for technologies such as HMM, Confidential Computing, and coherent memory on the Grace platform. On some newer platforms, including Grace Hopper and Blackwell, the open kernel modules are mandatory. (NVIDIA Developer)

This provides NVIDIA with a clear business advantage by reducing the operational cost of deploying AI and cloud infrastructure on Linux.

5. Better collaboration with the Linux ecosystem, including Nouveau

The release of the source code, together with the introduction of the GSP firmware, also makes it easier to improve Nouveau, the open-source NVIDIA driver included in the Linux ecosystem, particularly for features such as power management and clock management.

NVIDIA explains that Nouveau developers can use the published code as a reference and can also utilize the same GSP firmware. (NVIDIA Developer)

However, NVIDIA's open kernel modules have not been fully merged into the upstream Linux kernel. NVIDIA explains that its driver codebase is shared across multiple operating systems and does not currently conform to Linux kernel upstream coding conventions, preventing direct inclusion. (NVIDIA Developer)

Why is it dual-licensed under "MIT/GPL"?

The MIT/GPL designation means the code is dual-licensed, allowing it to be used under either GPLv2 or the MIT License. (NVIDIA Docs)

Broadly speaking, the purposes are:

GPLv2: Ensures compatibility with the Linux kernel's licensing model.
MIT: Allows more permissive reuse, porting, and redistribution.

Because NVIDIA shares portions of its codebase across Linux, other operating systems, multiple GPU families, and Jetson platforms, allowing an MIT option in addition to GPL is a practical choice. However, NVIDIA has not officially stated that this is the sole motivation; this conclusion is inferred from the published code structure and licensing model. (NVIDIA Developer)

In summary

Rather than suddenly adopting a company-wide policy of making everything open source, NVIDIA's actual approach is better summarized as follows:

By moving hardware control into the GSP firmware and open-sourcing only the Linux kernel interface, NVIDIA simplified distribution, signing, maintenance, and cloud deployment while keeping its core GPU intellectual property proprietary.

Regarding the previous question, NVIDIA's current official policy is that open GPU kernel modules are the default and recommended option for supported Turing-generation and newer GPUs. This became the default starting with the R560 driver series. Maxwell, Pascal, and Volta GPUs still require the proprietary driver. (NVIDIA Developer)

NVIDIAがGPL系のモジュールを提供するようになった最大の理由は、Linuxとの統合・配布・保守を容易にしつつ、GPUの重要な知的財産はファームウェアやユーザー空間に残せる技術構成が整ったからです。

なお、正確には「NVIDIAドライバー全体をGPL化した」のではありません。オープンになったのは主に以下のLinuxカーネルモジュールです。

nvidia.ko
nvidia-drm.ko
nvidia-uvm.ko
nvidia-modeset.ko

CUDA、OpenGL、Vulkanなどのユーザー空間コンポーネントとGSPファームウェアは、引き続きプロプライエタリです。(NVIDIA Developer)

1. Linuxディストリビューションに組み込みやすくするため

従来のプロプライエタリモジュールは、Linuxカーネルとは別にビルド・署名・配布する必要がありました。カーネル更新のたびにDKMSで再ビルドする構成では、以下が問題になりやすくなります。

カーネル更新後にモジュールがビルドできない
Secure Bootで署名されていないモジュールをロードできない
ディストリビューション側が正式パッケージとして管理しにくい
カスタムカーネルやクラウド環境への組み込みが複雑

ソースを公開することで、Ubuntu、Red Hat、SUSEなどがNVIDIAモジュールを自分たちのパッケージング、署名、更新機構に統合しやすくなりました。NVIDIA自身も「OSとのより緊密な統合」「署名と配布の容易化」を目的として挙げています。(NVIDIA Developer)

2. 障害解析とセキュリティレビューを改善するため

カーネルモジュールは、メモリ管理、割り込み、プロセス間同期、PCI Express、ディスプレイなど、OSの深い部分に関わります。

ソースが見えることで、ディストリビューション開発者や企業ユーザーは、次のような調査が可能になります。

カーネル内のどこで停止しているか追跡する
GPUイベントとワークロードの相互作用を解析する
カスタムカーネルとの非互換性を修正する
セキュリティ上の問題をレビューする
パッチをNVIDIAに提案する

NVIDIAは、コミュニティやパートナーからのレビューによってドライバーの品質とセキュリティを改善できると説明しています。(NVIDIA Developer)

3. GSPへの機能移動で、公開しやすくなったため

技術的な転換点が GSP（GPU System Processor） です。

以前は、GPU制御の多くをホストCPU上のカーネルドライバーが実行していました。しかし新しいGPUでは、GPU内部のGSPファームウェアが、初期化やハードウェア管理などの重要な処理を担当する構成へ移行しました。

概念的には次のような変化です。

従来:
Linuxカーネルモジュール
    ↓ ハードウェアを直接細かく制御
GPU

現在:
Linuxカーネルモジュール
    ↓ コマンド／RPC
GSPファームウェア
    ↓
GPUハードウェア

これにより、ハードウェア固有の複雑な制御や機密性の高い部分を署名済みファームウェア側に置きながら、Linuxと接続するカーネル側を公開しやすくなりました。NVIDIAも、最初のオープンモジュールが実現した技術的背景としてGSPドライバーアーキテクチャの段階的導入を明示しています。(NVIDIA Developer)

つまり、単に方針を変えたのではなく、ソース公開可能なドライバー構造へ事前に設計変更していたということです。

4. AI・クラウド・データセンター運用を簡単にするため

NVIDIAのGPUは現在、デスクトップ用途だけでなく、以下の環境で大量に使われます。

Kubernetesクラスタ
AI学習サーバー
クラウドVM
Grace Hopperシステム
Confidential Computing
統合メモリアーキテクチャ

このような環境では、GPUドライバーをOSイメージやコンテナ基盤に自動的かつ安全に組み込めることが重要です。

オープンモジュールでは、HMM、Confidential Computing、Graceプラットフォームのコヒーレントメモリなど、新しい機能も実装されました。Grace HopperやBlackwellなど、一部の新しいプラットフォームではオープンカーネルモジュールが必須になっています。(NVIDIA Developer)

これは、Linux上のAI・クラウド展開における運用コストを下げるという、NVIDIAにとって明確な事業上の利点があります。

5. NouveauなどLinux側との協調

ソース公開とGSPファームウェアの利用によって、Linuxカーネル内のオープンソースドライバーであるNouveauも、電力管理やクロック管理などの機能を改善しやすくなりました。

NVIDIAは、公開コードをNouveau改善の参考にでき、Nouveauからも同じGSPファームウェアを利用できると説明しています。(NVIDIA Developer)

ただし、NVIDIAの公開モジュールそのものがLinuxカーネル本体に完全統合されたわけではありません。NVIDIAは、コードベースが複数OSで共有されており、Linuxカーネルの設計慣例に適合していないため、そのままではupstreamに入れられないと説明しています。(NVIDIA Developer)

なぜ「MIT/GPL」のデュアルライセンスなのか

表示される MIT/GPL は、GPLv2またはMITライセンスの条件で利用できるデュアルライセンスです。(NVIDIA Docs)

大まかな役割は次のとおりです。

GPLv2：Linuxカーネルのライセンス体系との親和性を確保する
MIT：より制約の少ない再利用、移植、再配布を可能にする

NVIDIAのコードはLinuxだけでなく、複数のOS、GPU、Jetson向けに共有されているため、GPLだけに限定せずMITも選択可能にすることには合理性があります。ただし、この部分はNVIDIAが公式に単一の動機として説明したものではなく、公開されているコード構成とライセンス方式からの推論です。(NVIDIA Developer)

要するに

NVIDIAが急に「すべてをオープンソースにする企業方針」へ変わったというより、

GSPファームウェアにハードウェア制御を移し、Linuxとの接点となるカーネル部分を公開することで、配布・署名・保守・クラウド展開を容易にした

というのが実態に近いです。

なお、前の質問に関しては、現在のNVIDIA公式方針では、Turing以降の対応GPUではオープンカーネルモジュールがデフォルトかつ推奨です。R560系列以降、この方針に移行しています。Maxwell、Pascal、Voltaではプロプライエタリ版が必要です。(NVIDIA Developer)

Limiting SATA Link Speed to 3 Gbps on Linux Using libata.force

vast cow — Thu, 30 Jul 2026 13:55:58 +0000

You can use the Linux kernel boot parameter libata.force to limit the link speed of a specific ATA port to SATA 3 Gbps (Gen2) instead of 6 Gbps (Gen3).

Example Configuration

If the target port is recognized as ata2 in Linux, add the following kernel parameter:

libata.force=2:3.0G

The format is PORT:SPEED, where PORT is the numeric portion of ata2. To configure multiple ports, separate them with commas:

libata.force=2:3.0G,5:3.0G

According to the official kernel documentation, libata.force=[ID:]VAL can be used to limit the SATA link speed on a per-port basis to either 1.5Gbps or 3.0Gbps. (Linux Kernel Documentation)

Identifying the Target Port

First, check the boot log to determine which ATA port the disk is connected to:

sudo dmesg | grep -E 'ata[0-9]+: SATA link'

Example output:

ata2: SATA link up 6.0 Gbps
ata5: SATA link up 6.0 Gbps

You can also verify the mapping to block devices with:

ls -l /dev/disk/by-path/ | grep ata

The important point is to specify the ataN number reported by Linux, not /dev/sda or the motherboard's physical "SATA Port 2" label.

Making the Setting Persistent with GRUB

Add the parameter to the existing kernel command line in /etc/default/grub:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash libata.force=2:3.0G"

On Debian- and Ubuntu-based systems, then run:

sudo update-grub
sudo reboot

On distributions that generate the GRUB configuration differently, use either grub-mkconfig or grub2-mkconfig, depending on your environment.

Verifying the Configuration

After rebooting:

cat /proc/cmdline

Then verify the negotiated link speed:

sudo dmesg | grep 'ata2: SATA link'

Expected output:

ata2: SATA link up 3.0 Gbps

You can also check via sysfs:

cat /sys/class/ata_link/link2/sata_spd
cat /sys/class/ata_link/link2/sata_spd_limit

/sys/class/ata_link/.../sata_spd reports the current link speed, while sata_spd_limit reports the maximum speed imposed by libata. These files are read-only, so the limit is normally configured through the kernel boot parameter rather than changed at runtime with echo. (Linux Kernel Archive)

Notes

This does not throttle bandwidth; it limits the maximum SATA PHY link negotiation speed to 3 Gbps.
The ataN numbering may change if controllers are added, BIOS settings are modified, or the kernel or drivers change.
If your BIOS/UEFI provides a per-port "SATA Speed" or "Gen2" option, that may be a clearer way to configure the physical port.
This method may not apply to disks connected through USB-to-SATA adapters, NVMe, SAS, or hardware RAID controllers.

PiKVM Setup and Basic Usage

vast cow — Thu, 30 Jul 2026 09:34:26 +0000

PiKVM is a remote KVM solution that lets you view video output, control the keyboard and mouse, and boot from virtual media even when the target computer's operating system is not running.

This guide walks through the entire process in the order you would actually perform it, from writing the OS image to an SD card, through initial configuration, virtual media setup, remote access with Tailscale, and finally operating the target machine.

Keep in mind that the interface and some features vary depending on the PiKVM model and KVMD version. The virtual media sections in this article primarily assume PiKVM V2 or later.

Understanding the Read-Only Filesystem

PiKVM OS normally operates with its filesystem mounted as read-only to reduce SD card wear and protect against filesystem corruption caused by unexpected power loss. After making configuration changes, you should always return the filesystem to read-only mode.

An important point is that PiKVM provides two different commands for enabling writes, each serving a different purpose.

Comparison of Write Mode Commands

Command	Target	Primary Purpose	Enable Writes	Return to Read-Only
`rw` / `ro`	PiKVM OS root filesystem	Changing passwords, installing packages, editing files under `/etc`, changing the hostname	`rw`	`ro`
`kvmd-helper-otgmsd-remount rw` / `ro`	Virtual media area at `/var/lib/kvmd/msd`	Uploading, deleting, or modifying ISO and IMG files	`kvmd-helper-otgmsd-remount rw`	`kvmd-helper-otgmsd-remount ro`

The key point is that running rw does not necessarily make the virtual media area writable. Likewise, running kvmd-helper-otgmsd-remount rw does not allow you to modify system configuration files such as those under /etc.

Use the appropriate command depending on what you are modifying.

1. Write the Image to the SD Card

First, write the appropriate PiKVM OS image for your PiKVM model to an SD card.

After writing completes—but before booting PiKVM—open the first FAT32 partition on the SD card. This partition contains the pikvm.txt file used for first-boot configuration.

2. Configure Wi-Fi Before the First Boot

If wired Ethernet is unavailable, configuring Wi-Fi before the first boot makes the initial setup much easier.

Add the following lines to pikvm.txt:

WIFI_ESSID='Your Wi-Fi SSID'
WIFI_PASSWD='Your Wi-Fi Password'
WIFI_REGDOM='JP'

WIFI_REGDOM='JP' specifies Japan as the wireless regulatory domain.

If the following line already exists in pikvm.txt immediately after writing the image, leave it unchanged:

FIRST_BOOT=1

FIRST_BOOT=1 instructs PiKVM to generate SSH host keys, certificates, and other first-boot resources.

If your Wi-Fi password contains a backslash, it must be escaped by doubling it:

WIFI_PASSWD='abc\\def'

After the configuration has been applied, pikvm.txt is automatically deleted.

Also note that configurations based on the Raspberry Pi Zero 2 W cannot use 5 GHz Wi-Fi.

Safely eject the SD card, insert it into the PiKVM, and power it on.

3. Find the PiKVM IP Address

PiKVM normally obtains an IP address using DHCP.

After booting, the assigned IP address is displayed on the monitor connected to PiKVM, making it the easiest way to find it.

If no monitor is attached, check your router's management interface or DHCP lease table to identify the assigned address.

Throughout this guide, the PiKVM IP address will be represented as:

192.168.1.100

4. Connect to PiKVM via SSH

By default, the Linux administrator account is configured as follows:

Item	Default
Username	`root`
Password	`root`

Connect using an SSH client:

ssh root@192.168.1.100

On the first connection, SSH asks you to verify the host key. Confirm that you are connecting to the correct device before accepting it.

PiKVM also has a separate admin account for the Web UI. By default, both the username and password are admin.

The Linux root account and the Web UI admin account are completely independent, so both passwords must be changed.

5. Change Both Default Passwords First

Running PiKVM with its default passwords is insecure. Change them before configuring networking or installing additional features.

First, remount the root filesystem as writable:

rw

Change the Linux root password:

passwd root

Next, change the Web UI admin password:

kvmd-htpasswd set admin

After both passwords have been updated, return the filesystem to read-only mode:

ro

The complete sequence is:

rw
passwd root
kvmd-htpasswd set admin
ro

If you forget to run rw before changing passwords, the changes cannot be saved.

The official documentation also recommends changing both passwords between rw and ro.

6. Change the Hostname

If you manage multiple PiKVM devices, assigning meaningful hostnames based on their location or purpose makes administration easier.

For example, a PiKVM managing the first server in a server room might use:

pikvm-server01

Change the hostname using:

rw
systemctl restart systemd-hostnamed
hostnamectl set-hostname pikvm-server01
ro
reboot

After rebooting, both the SSH prompt and the network hostname reflect the new name.

The official FAQ also recommends restarting systemd-hostnamed, then running hostnamectl set-hostname, followed by rebooting PiKVM.

If you plan to install Tailscale, configuring the hostname first makes devices easier to identify in the Tailscale admin console.

7. Update PiKVM OS

After the initial configuration is complete, update PiKVM OS.

pikvm-update

Normally you do not need to manually run rw or ro; pikvm-update is the recommended update method.

However, updates are never completely risk-free. The official documentation recommends performing updates while you still have physical access to the PiKVM, in case the SD card must be reflashed. Avoid updating a PiKVM that is only reachable over a VPN unless necessary.

If you're using an older image that doesn't include pikvm-update, install it first:

rw
pacman -Syy
pacman -S pikvm-os-updater
pikvm-update

Reboot afterward if required.

8. Install Tailscale on PiKVM

If you intend to access PiKVM over the Internet, using a private networking solution such as Tailscale is much safer and easier to manage than exposing the Web UI or SSH directly.

PiKVM provides a dedicated package called tailscale-pikvm.

After running pikvm-update, install it in the following order:

rw
pacman -S tailscale-pikvm
systemctl enable --now tailscaled
tailscale up --qr
ro

Running tailscale up --qr displays a QR code for the authentication URL directly in the terminal. This is especially convenient when using a remote console where copying long URLs is difficult. --qr is an officially supported option in the current Tailscale CLI.

Using PiKVM as an Exit Node

If you want to use PiKVM as an Exit Node, enable the Exit Node feature in Tailscale.

rw

tailscale set \
  --advertise-exit-node \
  --advertise-routes=192.168.0.0/24

ro

For --advertise-routes, specify the LAN subnet that is reachable from the PiKVM. For example, if your managed network is 192.168.0.0/24, use the command above.

After applying the configuration, open the device in the Tailscale admin console and approve both Exit Node and Subnet routes.

You can then select the PiKVM as the Exit Node from your Tailscale client. In addition to routing Internet traffic through the PiKVM, you'll also be able to access devices on the LAN connected to the PiKVM.

Configuring UDP GRO on Raspberry Pi

When using a Raspberry Pi as an Exit Node, it is recommended to enable the Linux kernel's UDP GRO settings.

On PiKVM, you can create the following systemd service to apply the required settings automatically at boot.

rw

cat > /etc/systemd/system/apply-udp-gro.service <<'EOF'
[Unit]
Description=Configure UDP GRO forwarding
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/ethtool -K eth0 rx-udp-gro-forwarding on rx-gro-list off
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now apply-udp-gro.service

ro

This service runs the following command each time the PiKVM boots, ensuring that the UDP GRO settings persist across reboots.

ethtool -K eth0 rx-udp-gro-forwarding on rx-gro-list off

After configuring the service, you can verify the current settings with:

ethtool -k eth0 | grep -E 'rx-udp-gro-forwarding|rx-gro-list'

The expected output is:

rx-gro-list: off
rx-udp-gro-forwarding: on

If your PiKVM uses a network interface other than eth0, replace it with the appropriate interface name for your environment.

9. Upload Virtual Media to PiKVM

PiKVM can present ISO and IMG files to the target machine as either a virtual CD/DVD drive or a virtual USB flash drive.

Image files are stored in:

/var/lib/kvmd/msd

Uploading through the Web UI's Drive menu is usually the simplest approach.

If you prefer using SCP or rsync manually, first remount the virtual media partition as writable:

kvmd-helper-otgmsd-remount rw

Transfer the ISO from your local computer:

scp installer.iso root@192.168.1.100:/var/lib/kvmd/msd/

After the transfer completes, remount the partition as read-only:

kvmd-helper-otgmsd-remount ro

The official documentation recommends the following sequence:

Run kvmd-helper-otgmsd-remount rw
Copy files into /var/lib/kvmd/msd
Run kvmd-helper-otgmsd-remount ro

Keeping the virtual media partition read-only during normal operation helps prevent corruption caused by unexpected power loss.

Is `chown kvmd:kvmd` Necessary for ISO Files?

Files uploaded via SCP are normally owned by root.

ls -l /var/lib/kvmd/msd/

For example:

-rw-r--r-- 1 root root ... installer.iso

As long as the file is readable by everyone, changing ownership is not necessarily required for read-only ISO usage.

In other words, you do not need to mechanically run:

chown kvmd:kvmd installer.iso

for every uploaded ISO.

What actually matters is that the kvmd user has permission to read the file. If necessary, set the permissions like this:

kvmd-helper-otgmsd-remount rw
chmod 644 /var/lib/kvmd/msd/installer.iso
kvmd-helper-otgmsd-remount ro

On the other hand, if the image will be presented as a writable virtual flash drive, write permissions are also required. The official documentation uses:

chmod 666 /var/lib/kvmd/msd/flash.img

for writable flash images.

If you prefer consistent ownership across all files, you may use:

kvmd-helper-otgmsd-remount rw
chown kvmd:kvmd /var/lib/kvmd/msd/installer.iso
chmod 644 /var/lib/kvmd/msd/installer.iso
kvmd-helper-otgmsd-remount ro

However, for read-only ISOs, the essential requirement is that the kvmd user can read the file—not that the file is owned by kvmd.

10. Boot the Target Machine from Virtual Media

After uploading an ISO, open the PiKVM Web UI and select the desired image from the Drive menu.

The basic workflow is:

Open the Drive menu.
Select the ISO or IMG file.
Choose the media type.
Connect the image.
Reboot the target machine.
Select the virtual media from the BIOS or UEFI boot menu.

PiKVM can present virtual media in the following formats:

Mode	Appears as	Typical Use
CD/DVD	Optical drive	Standard OS installation ISOs and rescue media
Flash	USB flash drive	UEFI compatibility workarounds and writable disk images

In most cases, ISO images should be connected as CD/DVD.

However, some UEFI implementations cannot boot correctly from virtual optical drives. If that happens, reconnecting the same image as Flash may allow the firmware to recognize it.

This is a compatibility workaround for specific systems, not a universal requirement.

PiKVM virtual media is accessible from both BIOS and UEFI, and the connection mode can be switched between CD/DVD and Flash through the Web UI.

Precautions When Using Virtual Media

Do not power off PiKVM while an image is being uploaded or while a writable virtual image is connected to the target machine.

Interrupting power during an upload or write operation can corrupt the image file or the filesystem.

11. Send Ctrl+Alt+Del

Since web browsers often intercept keys such as Ctrl and Alt, special key combinations should be sent from the PiKVM Web UI.

To send Ctrl+Alt+Del, open the Shortcuts menu at the top of the Web UI and select Ctrl+Alt+Del.

If the desired shortcut is unavailable, you can also use PiKVM's Magic Key shortcut mechanism. According to the current official documentation, you press and release the Magic Key, then press and release Ctrl, Alt, and Del in sequence.

12. Install Tailscale on the Target Machine

If you also want to install Tailscale on the computer you're controlling through PiKVM, the following command is particularly convenient on Linux:

tailscale up --qr

Scan the QR code displayed on the screen with your smartphone to complete Tailscale authentication.

This eliminates the need to manually type long authentication URLs or rely on clipboard sharing, making it especially useful immediately after installing an operating system or in environments without a graphical desktop.

Recommended Setup Order

To minimize rework, perform the initial setup in the following order:

Write the PiKVM OS image to the SD card.
Configure Wi-Fi in pikvm.txt before the first boot.
Boot PiKVM and determine its IP address.
Connect via SSH as root.
Change the Linux root password.
Change the Web UI admin password.
Change the hostname.
Run pikvm-update while physical access is available.
Install Tailscale if needed.
Upload ISO and IMG files to the virtual media storage.
Connect to the target machine through the Web UI.
Attach virtual media and perform OS installation or recovery.

Summary

The most common source of confusion when using PiKVM is switching between the two write modes.

When modifying system configuration, use:

rw
# Make configuration changes
ro

When uploading ISO or IMG files, use:

kvmd-helper-otgmsd-remount rw
# Upload or remove ISO/IMG files
kvmd-helper-otgmsd-remount ro

Understanding the distinction between these two mechanisms and always returning to read-only mode afterward is fundamental to operating PiKVM safely.

Also, immediately after the first boot, be sure to change both the Linux and Web UI passwords. If you need remote access from outside your local network, it is generally better to use a private networking solution such as Tailscale rather than exposing the PiKVM Web UI directly to the Internet.

Bridging Ethernet with NetworkManager on Rocky Linux 9 While Preserving DHCP and the MAC Address

vast cow — Tue, 28 Jul 2026 12:31:43 +0000

On Ubuntu, it is common to use Netplan to attach an Ethernet interface to a Linux bridge. On Rocky Linux 9, however, NetworkManager typically manages networking.

Instead of Netplan, Rocky Linux uses nmcli to create a bridge and attach the physical network interface to it.

This article explains how to achieve the equivalent of an Ubuntu Netplan bridge configuration on Rocky Linux 9.

Network Topology

For example, if your wired network interface is:

eth0

the final configuration will look like this:

          DHCP Server
               │
        Ethernet Switch
               │
             eth0
               │
         Linux Bridge
             br0
               │
      IP Address (DHCP)
               │
         hostapd (AP)
               │
        Wi-Fi Clients

With this configuration:

The physical NIC becomes a member port of the bridge.
The bridge (br0) owns the IP address.
hostapd is attached to the bridge.
Wi-Fi clients join the same Layer 2 network as the wired LAN.

Create the Bridge

First, create the bridge.

sudo nmcli connection add \
    type bridge \
    ifname br0 \
    con-name br0

Preserve the Bridge MAC Address

Depending on the environment, a newly created bridge may receive a different MAC address.

To preserve the existing network identity, configure the bridge to use the same MAC address as the original Ethernet interface.

sudo nmcli connection modify br0 \
    bridge.mac-address xx:xx:xx:xx:xx:xx

Configure DHCP on the Bridge

The bridge—not the physical NIC—should obtain the IP address.

sudo nmcli connection modify br0 \
    ipv4.method auto \
    ipv6.method disabled

Add the Ethernet Interface to the Bridge

sudo nmcli connection add \
    type bridge-slave \
    ifname eth0 \
    master br0

If an existing Ethernet connection profile already exists, delete or disable it.

nmcli connection show

sudo nmcli connection delete "<existing-profile-name>"

Activate the Bridge

Bring the bridge online.

sudo nmcli connection up br0

Verify the configuration.

ip addr show br0

bridge link

The expected state is:

eth0 is attached as master br0.
br0 owns the IP address.
DHCP runs on br0.
The bridge uses the same MAC address as the original Ethernet interface.

Why Preserve the MAC Address?

When a bridge is created, it may be assigned a new MAC address.

If the MAC address changes:

The DHCP server may recognize the system as a different device.
A new DHCP lease may be assigned.
MAC address–based access control may no longer work as expected.
Neighboring devices may need to refresh their ARP caches.

To minimize the impact on the existing network, configure the bridge to use the same MAC address as the original NIC.

bridge.mac-address xx:xx:xx:xx:xx:xx

Using the Bridge with hostapd

After creating the bridge, specify it in hostapd.conf.

interface=wlp2s0
bridge=br0

This allows:

Wired LAN devices
Wi-Fi clients
The DHCP server

to operate on the same Layer 2 network, enabling Wi-Fi clients to obtain IP addresses directly from the existing DHCP server.

The Configuration Persists Across Reboots

A bridge created with nmcli is not a temporary configuration.

NetworkManager stores connection profiles as .nmconnection files under:

/etc/NetworkManager/system-connections/

These profiles are automatically restored after a reboot.

For example, running:

sudo nmcli connection add type bridge ifname br0 con-name br0

creates a configuration file similar to:

/etc/NetworkManager/system-connections/br0.nmconnection

Bridge slave connections are stored in the same way.

Using nmcli is therefore the standard method for creating persistent bridge configurations.

By contrast, a bridge created only with the ip command:

ip link add br0 type bridge

is temporary and disappears after a reboot.

Precautions When Reconfiguring Over SSH

Ubuntu's Netplan provides:

sudo netplan try

which temporarily applies a configuration and automatically rolls it back if connectivity is lost.

NetworkManager does not provide an equivalent automatic rollback mechanism.

When changing network settings over SSH, it is recommended to:

Ensure you have access to an out-of-band management console such as IPMI or iLO.
Use tmux or screen to reduce the risk of losing your session.
Verify that the bridge is functioning correctly before deleting the original connection profile.

Netplan and NetworkManager Comparison

Netplan	NetworkManager (`nmcli`)
`bridges:`	`type bridge`
`interfaces:`	`bridge-slave`
`dhcp4: true`	`ipv4.method auto`
`dhcp6: false`	`ipv6.method disabled`
`macaddress:`	`bridge.mac-address`
`netplan apply`	`nmcli connection up br0`
`netplan try`	No equivalent feature

Summary

On Rocky Linux 9, you can use NetworkManager's nmcli to build the same bridge configuration that is commonly implemented with Netplan on Ubuntu.

The key points are:

Assign the IP address to the bridge rather than the physical NIC.
Configure the bridge to use the same MAC address as the original Ethernet interface.
Point hostapd to the bridge.
Bridge configurations created with nmcli are persistent across reboots.
Unlike Netplan, NetworkManager does not provide an automatic rollback feature similar to netplan try, so exercise caution when making network changes over SSH.

With this setup, wired LAN devices and Wi-Fi clients share the same Layer 2 network, allowing Wi-Fi clients to obtain IP addresses directly from the existing DHCP server.

Bridging Ethernet with Netplan While Preserving DHCP and the MAC Address

vast cow — Tue, 28 Jul 2026 12:23:28 +0000

When using a Linux machine as a Wi-Fi access point with hostapd, you may want Wi-Fi clients to join the same Layer 2 (L2) network as your existing wired LAN.

A common approach is to add the Ethernet interface to a Linux bridge and assign the IP address to the bridge instead of the physical interface.

Example Netplan Configuration

For example, if your Ethernet interface is eth0, configure it as follows:

network:
  version: 2
  renderer: networkd

  ethernets:
    eth0:
      dhcp4: false
      dhcp6: false

  bridges:
    br0:
      interfaces:
        - eth0
      dhcp4: true
      dhcp6: false
      macaddress: xx:xx:xx:xx:xx:xx

This configuration does the following:

Makes eth0 a member port of the bridge.
Allows br0 to obtain its IP address via DHCP.
Sets the MAC address of br0 to match the original Ethernet interface.

Why Fix the MAC Address?

When a bridge is created, some environments assign a new MAC address to br0.

If the MAC address changes, it may result in:

The DHCP server recognizing it as a new client.
A different DHCP lease being assigned.
MAC address–based access control rules no longer matching.
ARP caches being refreshed.

To minimize the impact on the existing network, explicitly configure the bridge to use the original Ethernet interface's MAC address:

macaddress: xx:xx:xx:xx:xx:xx

Safely Testing the Configuration

When modifying network settings over a remote SSH session, an incorrect configuration can cause you to lose connectivity.

Instead of immediately running netplan apply, it is safer to use netplan try:

sudo netplan try --timeout 30

This command temporarily applies the configuration. If you confirm that everything is working within 30 seconds, the changes become permanent.

If the connection is lost or you do not confirm the changes, Netplan automatically restores the previous configuration after the timeout expires.

This makes it much safer to test network configuration changes over SSH.

Using the Bridge with hostapd

After creating the bridge, configure hostapd to use it:

interface=wlp2s0
bridge=br0

With this configuration, Wi-Fi clients connect to the wired LAN through br0, placing them on the same Layer 2 network.

As a result:

Wired devices
Wi-Fi devices
The DHCP server

all operate on the same network segment, allowing Wi-Fi clients to obtain IP addresses directly from the existing DHCP server.

Summary

When using hostapd on Linux, a bridged network configuration is a simple and maintainable solution.

To minimize disruption to your existing network, keep these three points in mind:

Assign the IP address to the bridge rather than the physical Ethernet interface.
Configure the bridge to use the same MAC address as the original Ethernet interface.
Use netplan try during remote administration to safely test configuration changes before committing them.

DEV Community: vast cow

Streaming Video Over a Network with the Lowest Possible Latency Using FFmpeg + MediaMTX

Configuration

MediaMTX Configuration

Start FFmpeg Only When Needed with runOnDemand

Minimize Input-Side Buffers

-fflags nobuffer

-flags low_delay

Capture Video and Audio from Separate Devices

Keep thread_queue_size Small

Encode with Intel Quick Sync Video

Reduce Encoder “Lookahead” as Well

-preset veryfast

async_depth 1 Is Important

Do Not Use B-Frames

Use a One-Second GOP

global_quality:v 35

Audio Is Opus at 192 kbps

Use UDP for RTSP

muxdelay 0

Do Not Make MediaMTX Encode the Video

Reduce Buffering on the ffplay Side as Well

-fflags nobuffer

-flags low_delay

-framedrop

In Low-Latency Streaming, “Dropping” Is Important

Where Does Latency Occur?

If You Want to Reduce Latency Even Further

UDP Does Not Automatically Mean Low Latency

Summary

FFmpeg + MediaMTXで映像をできるだけ低遅延にネットワーク配信する

構成

MediaMTXの設定

runOnDemandで必要なときだけFFmpegを起動する

入力側のバッファを極力小さくする

-fflags nobuffer

-flags low_delay

映像と音声を別デバイスから入力する

thread_queue_sizeを小さくする

Intel Quick Sync Videoでエンコードする

エンコーダーでも「先読み」を減らす

-preset veryfast

async_depth 1が重要

Bフレームを使わない

GOPを1秒にする

global_quality:v 35

音声はOpus 192kbps

RTSPはUDPを使う

muxdelay 0

MediaMTX自身にはエンコードさせない

ffplay側でもバッファを削る

-fflags nobuffer

-flags low_delay

-framedrop

低遅延配信では「捨てる」ことが重要

遅延はどこで発生するのか

さらに遅延を詰めたい場合

UDPだから必ず低遅延、ではない

まとめ

Automatically Renewing Tailscale HTTPS Certificates on PiKVM

Configuration

1. Renewal Script

2. systemd Service

3. systemd Timer

4. Installation

5. Starting and Checking Status

Access URL

PiKVM で Tailscale HTTPS 証明書を自動更新する

構成

1. 更新スクリプト

2. systemd サービス

3. systemd タイマー

4. インストール

5. 起動とステータス確認

アクセス URL

Setting Up and Troubleshooting FFmpeg + Intel QSV on Rocky Linux 9

Understanding the Layers Required for QSV to Work

1. Check Whether Linux Detects the Intel GPU

2. Remove nomodeset If It Is Configured

3. Check /dev/dri/renderD128

Start FFmpeg Only When Needed with `runOnDemand`

`-fflags nobuffer`

`-flags low_delay`

Keep `thread_queue_size` Small

`-preset veryfast`

`async_depth 1` Is Important

`global_quality:v 35`

`muxdelay 0`

`-fflags nobuffer`

`-flags low_delay`

`-framedrop`

`runOnDemand`で必要なときだけFFmpegを起動する

`-fflags nobuffer`

`-flags low_delay`

`thread_queue_size`を小さくする

`-preset veryfast`

`async_depth 1`が重要

`global_quality:v 35`

`muxdelay 0`

`-fflags nobuffer`

`-flags low_delay`

`-framedrop`

2. Remove `nomodeset` If It Is Configured

3. Check `/dev/dri/renderD128`

8. Explicitly Set `LIBVA_DRIVER_NAME=iHD`

12. Get `vainfo` Working First

13. Check Which RPM Provides `iHD_drv_video.so`

22. The `yuv420p` → `nv12` Warning Is Not a Fatal Error

23. ALSA `Thread message queue blocking` Is Also a Separate Issue

2. `nomodeset` を設定している場合は外す

3. `/dev/dri/renderD128` を確認する

8. `LIBVA_DRIVER_NAME=iHD` で明示する

12. まず `vainfo` を正常にする

13. `iHD_drv_video.so` がどの RPM に含まれるか確認する

22. `yuv420p` → `nv12` の警告は致命的エラーではない

23. ALSA の `Thread message queue blocking` も別問題

1. Install `dnf-automatic`

2. Configure `dnf-automatic`