Jibri Recording Subsystem: Fleet Setup and Fix Guide

Jibri Fleet Deployment and Troubleshooting: A Simple Guide

If you run your own Jitsi Meet server, sooner or later someone will ask, “Can we record this meeting?” That is when you meet the Jibri recording subsystem. It is the part of Jitsi that records meetings and streams them to platforms like YouTube. It is also the part that breaks most often, and it can be hard to debug the first time.

This guide walks you through how Jibri works, how to build a small fleet of Jibri servers, and how to fix the problems that come up most often. I have kept the language plain and the steps practical. You do not need to be a Jitsi expert to follow along, but basic Linux skills will help.

What Is Jibri and Why Does It Need Its Own Servers?

Jibri stands for Jitsi Broadcasting Infrastructure. It does not record the meeting on the Jitsi Videobridge. Instead, Jibri joins your meeting like a normal user, but a hidden one. It opens the meeting in a real Chrome browser, captures the screen and sound, and sends that to ffmpeg. Ffmpeg then writes a video file or pushes a stream to an RTMP address.

This explains why Jibri is heavy. Each Jibri instance runs a full browser, a virtual screen, a virtual sound card, and a video encoder, all at the same time. Because of that, one Jibri server can handle only one recording or stream at a time. That is a hard rule, not a setting you can change.

So if you want three meetings recorded at the same moment, you need three Jibri instances. A group of these instances is what people call a Jibri fleet.

How the Jibri Recording Subsystem Works Behind the Scenes

Before you build anything, it helps to know the moving parts. When something breaks, you will know where to look.

The main pieces

• Jicofo is the Jitsi Conference Focus. It decides which Jibri gets a job.
• Prosody is the XMPP server. Jibri talks to Jicofo through it.
• The brewery room is a special chat room where every idle Jibri waits. Jicofo looks in this room to find a free one.
• Chrome and ChromeDriver open the meeting and act as the “viewer.”
• Xorg with a dummy display gives Chrome a screen to draw on, even though the server has no monitor.
• ALSA loopback gives Chrome a fake sound card so audio can be captured.
• ffmpeg takes the screen and audio and creates the recording or stream.

The basic flow

• A user clicks “Start recording” in the meeting.
• Jicofo looks in the brewery room for a Jibri that says it is idle.
• Jicofo sends the job to that Jibri.
• Jibri opens Chrome, joins the meeting through a hidden account, and starts ffmpeg.
• When the user stops the recording, Jibri saves the file, runs your finalize script if you have one, and goes back to idle.

If any of these steps fails, the recording fails. Most Jibri trouble comes from a small mistake in one of these links.

Planning Your Jibri Fleet Deployment

A little planning saves hours later. Think about these points first.

Server size

Jibri is hungry for CPU. As a starting point, plan for at least 4 vCPUs and 8 GB of RAM for each Jibri instance. Recording a 1080p meeting on a weak machine leads to choppy video, out-of-sync audio, and sometimes a crash. If you are streaming to a live platform, give it even more room.

How many Jibri instances do you need?

Count the number of meetings you expect to record at the same time during your busiest hour, then add one or two spare instances. If you never record more than two meetings at once, three Jibris is a comfortable number.

Operating system and kernel

Jibri works best on Ubuntu LTS releases. It also needs the snd-aloop kernel module for the virtual sound card. This is where many people get stuck. Cloud providers often use special kernels that do not include this module. Before you build anything, check that your kernel supports it:

sudo modprobe snd-aloop
lsmod | grep snd_aloop

If the module loads, you are fine. If it does not, install the extra modules package for your kernel:

sudo apt install linux-modules-extra-$(uname -r)

Some very minimal or custom cloud kernels cannot run it at all. If that happens, switch to a standard kernel or a different image.

Keep Jibri separate from the rest of Jitsi

Do not run Jibri on the same machine as your Jitsi Videobridge or Jicofo. It uses too much CPU, and it will hurt the quality of your live meetings. Give Jibri its own servers.

Step-by-Step Jibri Fleet Deployment

This section covers a manual setup on Ubuntu. The steps are the same for every node in the fleet, so once you have one working, you can copy it.

Step 1: Prepare Prosody for Jibri

On your main Jitsi server, you need two accounts and one virtual host. These let Jibri log in and let the recording bot join the meeting quietly.

Add a recorder virtual host in your Prosody config for your domain:

VirtualHost "recorder.meet.example.com"
    modules_enabled = { "ping"; }
    authentication = "internal_hashed"

Then create the two users:

prosodyctl register jibri auth.meet.example.com YOUR_JIBRI_PASSWORD
prosodyctl register recorder recorder.meet.example.com YOUR_RECORDER_PASSWORD

The jibri user is what the Jibri service uses to connect to the control room. The recorder user is the hidden account that joins the actual meeting. Use strong passwords and keep them in a safe place. Restart Prosody after you make changes.

Step 2: Tell Jicofo where the brewery room is

Jicofo needs to know which room to check for free Jibris. In your Jicofo config, add:

jicofo {
  jibri {
    brewery-jid = "JibriBrewery@internal.auth.meet.example.com"
    pending-timeout = 90 seconds
  }
}

The brewery name can be anything, but it must match what you set on the Jibri side. Restart Jicofo after the change.

Step 3: Turn on recording in the Jitsi Meet web config

In your config.js, make sure these lines are set:

fileRecordingsEnabled: true,
liveStreamingEnabled: true,
hiddenDomain: 'recorder.meet.example.com',

If you skip this, the record button will not show up in the meeting menu. This is a very common reason people think Jibri is broken when it is not.

Step 4: Install Jibri on the new server

On each Jibri machine, first add the Jitsi package repository and install Google Chrome stable. Then install Jibri:

sudo apt install jibri

Next, install the matching ChromeDriver. Chrome and ChromeDriver must have the same major version. If they do not match, Jibri fails with an error that mentions a session not being created. Whenever Chrome updates itself, check ChromeDriver too.

Also make sure the jibri user is in the right groups:

sudo usermod -aG adm,audio,video,plugdev jibri

Then make sure the loopback module loads at every boot:

echo "snd_aloop" | sudo tee -a /etc/modules

Step 5: Configure Jibri

Modern Jibri uses the file /etc/jitsi/jibri/jibri.conf. A simple version looks like this:

jibri {
  id = "jibri-node-01"
  single-use-mode = false
  api {
    xmpp {
      environments = [{
        name = "prod"
        xmpp-server-hosts = ["meet.example.com"]
        xmpp-domain = "meet.example.com"
        control-muc {
          domain = "internal.auth.meet.example.com"
          room-name = "JibriBrewery"
          nickname = "jibri-node-01"
        }
        control-login {
          domain = "auth.meet.example.com"
          username = "jibri"
          password = "YOUR_JIBRI_PASSWORD"
        }
        call-login {
          domain = "recorder.meet.example.com"
          username = "recorder"
          password = "YOUR_RECORDER_PASSWORD"
        }
        strip-from-room-domain = "conference."
        usage-timeout = 0
        trust-all-xmpp-certs = true
      }]
    }
  }
  recording {
    recordings-directory = "/srv/recordings"
    finalize-script = "/opt/jitsi/jibri/finalize.sh"
  }
}

Two details to watch. First, every node needs a unique id and a unique nickname. If two nodes share a name, the brewery room gets confused. Second, the room name and domains must match what you set in Jicofo and Prosody exactly. One missing letter is enough to break the whole chain.

Step 6: Start the services and test

sudo systemctl enable --now jibri
sudo systemctl status jibri

Then start a meeting, click the record button, and watch the log on the Jibri server:

tail -f /var/log/jitsi/jibri/log.0.txt

If you see Jibri go from idle to busy and a file appears in the recordings folder, your first node works.

Step 7: Clone the node to grow the fleet

Once one Jibri works, turn it into an image or a template. For each new node, change only the id and nickname in jibri.conf. Everything else stays the same. Start the service, and the new Jibri will show up in the brewery room by itself.

Scaling Your Jibri Fleet Without Pain

Running five or ten Jibri servers all day is expensive, especially since most of them sit idle. Many teams set up autoscaling so servers start when demand goes up and stop when it goes down.

Jitsi has an open-source autoscaler and sidecar tool for this. The sidecar runs on each Jibri node and reports its status. The autoscaler decides when to add or remove nodes based on how many Jibris are idle. If you go this route, some things to keep in mind:

• Use a prebuilt image so a new node is ready in a couple of minutes.
• Set a minimum number of idle Jibris so users never wait.
• Never shut down a node that is in the middle of a recording. Wait until it is idle.
• Keep your finalize script simple, and make it upload the file somewhere safe before the node is removed.

If autoscaling feels like too much at first, start with a fixed fleet. Add automation later, when you understand your usage pattern.

Where Do Recordings Go?

By default, Jibri saves files on its own local disk. That is fine for a test, but it is a bad plan for a fleet, because when a node is deleted, the recordings go with it.

Use the finalize script to move the files. This script runs when a recording ends and gets the folder path as its first argument. A simple one can copy the video to cloud storage or a network share and then delete the local copy:

#!/bin/bash
RECORDINGS_DIR=$1
# copy to your storage here, then clean up

Make sure the script is executable, and test it by hand before you trust it. Also watch your disk space. A full disk is a quiet way for recordings to fail.

Jibri Troubleshooting: The Problems You Will Actually See

Here is the part most people came for. Jibri errors can look scary, but most of them fall into a few groups.

Where to look first

Jibri writes several logs in /var/log/jitsi/jibri/:

• log.0.txt is the main log. Start here.
• ffmpeg.0.txt shows what the encoder is doing.
• browser.0.txt shows Chrome’s own messages.

Also check the Jicofo log on the main server. Between these files, you can usually tell which link in the chain broke.

Problem 1: The record button is missing

Cause: Recording is not turned on in config.js, or the Jibri is not connected to the brewery room.

Fix: Check that fileRecordingsEnabled and hiddenDomain are set. Then confirm at least one Jibri is idle in the brewery room. If Jicofo sees no free Jibri, the button can stay hidden or the request fails.

Problem 2: “Recording unavailable” or no Jibri available

Cause: Every Jibri is busy, or none are connected.

Fix: Check systemctl status jibri on each node. Look at the Jicofo log for the brewery room. If the room name in Jicofo and in jibri.conf are different, Jicofo will never find your nodes. Copy and paste the value rather than typing it twice.

Problem 3: Jibri cannot log in to Prosody

Cause: A wrong password, a wrong domain, or a certificate problem.

Fix: Test the login details again. Make sure the jibri user was created on auth. and the recorder user on recorder.. If your Prosody certificate is self-signed, trust-all-xmpp-certs should be true, or you must add the certificate to the Jibri server.

Problem 4: Chrome fails to start

Cause: Chrome and ChromeDriver versions do not match, or Chrome cannot run because of missing permissions.

Fix: Run these and compare the major version numbers:

google-chrome --version
chromedriver --version

If they differ, update the older one. Also make sure Chrome has the managed policy file that Jibri expects, and that the jibri user can use the display.

Problem 5: The recording has no sound

Cause: The snd-aloop module is not loaded, or the ALSA settings are wrong.

Fix: Run lsmod | grep snd_aloop. If nothing shows up, load the module and add it to /etc/modules. After a kernel update, check again, because the extra modules package can be missing for the new kernel version. This one catches many people after a routine reboot.

Problem 6: Choppy video or out-of-sync audio

Cause: Not enough CPU.

Fix: Look at CPU use while a recording runs. If it stays near the maximum, move to a bigger machine. You can also lower the recording resolution or frame rate in your Jibri settings. Also make sure no other heavy process runs on the same server.

Problem 7: Livestream fails to start

Cause: A wrong RTMP address, a wrong stream key, or a blocked outbound port.

Fix: Check ffmpeg.0.txt. It usually tells you plainly if the connection was refused or rejected. Confirm the server can reach the streaming address on port 1935. Also make sure the stream key was copied without extra spaces. For YouTube, the stream must also be ready on their side before you start.

Problem 8: A Jibri gets stuck in a busy state

Cause: A crash in the middle of a job left the service in a bad state.

Fix: Restart the Jibri service. Some teams set single-use-mode = true, which makes Jibri shut down after every recording so it always starts clean. This works well with autoscaling, since a fresh node replaces the used one.

Problem 9: Recordings stop after a few minutes

Cause: A full disk, a memory shortage, or a network drop.

Fix: Check free space with df -h and memory with free -m. Also check whether the Jibri lost its connection to Prosody, which would show in the main log.

A quick health check

Jibri has a small HTTP API for health checks, on port 2222 by default. You can call it from a monitoring tool to see whether a node is healthy. Plug that into whatever you use for alerts. It is much better to learn about a broken Jibri from a monitor than from an angry user.

Good Habits That Prevent Most Problems

After you fix a few Jibri issues, you start to see a pattern. These habits will save you time:

• Pin your versions. Automatic Chrome updates are a common cause of sudden failures. Control when Chrome updates on your Jibri nodes.
• Test after every update. Do a quick 30-second test recording after any kernel, Chrome, or Jibri update.
• Use unique names. Every node needs its own ID and nickname.
• Monitor idle Jibris. Alert when the count of free Jibris drops to zero.
• Move files off the node. Never depend on the local disk for anything you care about.
• Keep notes. Write down your config, passwords location, and steps. Your future self will thank you.
• Check the official docs. Jibri changes over time, so compare this guide with the current Jitsi documentation before a big rollout.

Conclusion

The Jibri recording subsystem looks complicated at first, but it follows a clear path. A user starts a recording, Jicofo finds a free Jibri in the brewery room, Jibri opens Chrome and ffmpeg, and the file is saved. When something fails, you can walk down that same path and find the broken link.

To sum up the key points: give Jibri its own servers with enough CPU, make sure the snd-aloop module works, match your Chrome and ChromeDriver versions, keep every domain and room name identical across Prosody, Jicofo, and Jibri, and move your recordings off the local disk. Start with a small fixed fleet, learn how it behaves, and add autoscaling once you are comfortable.

Ready to build yours? Set up one Jibri node today, run a short test recording, and then clone it into a fleet. If you get stuck, go back to the logs. They almost always tell you what is wrong.