Server Administration Manual
Table of contents
- Do I need to run a Server?
- Basic requirements
- Server Types
- Installation and Configuration
- Servers on the desktop
- Server Setup
- Command line options
- Running an Unregistered Server
- Backing up the Server
Do I need to run a Server?
No. You can use the Servers listed by the built in Directories and use Jamulus without running a Server or choose a third party hosting service. If you just want an undisturbed session, use the soloing technique described on the Tips and Tricks page. If you decide you cannot use any of the Servers listed by the built in Directories, you may be able to use a Server (either Registered in a Custom Directory, or Unregistered - see Server Types) hosted by a third party. Doing so will save you the trouble of setting one up yourself.
While setting up a Server isn’t difficult, it’s a good idea to read the following background information to avoid some problems:
Speed and latency
The capability of the Server itself (and the network it’s on) is NOT the main determinant of the quality of a Jamulus session!
Usually, problems are on the Client side and should be fixed there. Have a look at the Troubleshooting page if needed.
However, various problems can also arise when setting up Servers - especially when run on a low-bandwidth home connection. It’s usually fine to have less than 5 players on a slower-speed home connection (eg 10 Mbit/s down and 1 Mbit/s up). You can read more about network requirements at different quality settings here.
Consider using a cloud host, not your home internet connection, to get better ping times if you’re having problems.
- Any Server should have at least 1.6GHz CPU frequency and 1GB RAM
- Running a Server may require you to adjust any firewalls running on or outside of your machine or cloud host.
- Running an Unregistered Server at home will require you to port forward on your router. When running a Registered Server, port forwarding should not be necessary in most cases, but it’s advisable to do so because some networks may not work properly with Jamulus in its default mode.
- Jamulus only has limited IPv6 support which needs to be enabled with a command line argument on the Client and Server. (There are plans to expand IPv6 support.)
You can run your Server in different ways (either at home or on a 3rd party host):
Your Server will be listed in a Directory. By default, Jamulus has a list of built-in Directories that Clients can connect to. If you register with one of these, anyone can then discover and connect to your Server. You can also have your Server listed on a Custom Directory, if that better meets your needs.
This is the default when starting a Server for the first time. Unregistered Servers are not listed by Directories, so only musicians who know your Server’s address to will be able to connect to it. This is useful because Jamulus does not let you control who can connect to a Server.
If you are running an unregistered server behind a home internet connection, you might need to enable port forwarding as described below.
If you want to run a number of Servers, possibly also behind a firewall or on a LAN, you may want to run your Server as a Directory. Examples include online events, music associations, sectional rehearsals or music lessons for schools.
To run a Directory read this guide
Installation and Configuration
Most people run Jamulus as a “pure” Server on hardware without audio (e.g. on a 3rd party/cloud host) running Linux. The following steps assume you are familiar with the command line and Debian/Ubuntu or similar distribution using systemd. To run a server on Windows or on the desktop with a graphical user interface, see this section.
If you want to run a Server on a Raspberry Pi (or a different armhf/arm64 debian-based device), you will need to download the
.deb files for 32 bit
armhf or 64 bit
arm64, not the default
amd64 ones you’d use on an Intel/AMD based machine.
- Download the latest headless (amd64) .deb file or, if you use a Raspberry Pi etc. download the latest armhf .deb file or the latest arm64 .deb file
- Update apt to make sure you have a current list of standard packages:
sudo apt update
- Install the Jamulus package:
sudo apt install ./jamulus-headless_3.9.1_ubuntu_amd64.debor for RasPi etc. armhf:
sudo apt install ./jamulus-headless_3.9.1_ubuntu_armhf.deb; arm64:
sudo apt install ./jamulus-headless_3.9.1_ubuntu_arm64.deb
- Enable the headless Server process via systemd:
sudo systemctl enable jamulus-headless
- Add your desired command line options to the
ExecStartline in the systemd service file by running
sudo systemctl edit --full jamulus-headless(By default you will be running an Unregistered Server).
- Reload the systemd files
sudo systemctl daemon-reloadand restart the headless Server:
sudo systemctl restart jamulus-headless
- Check all is well with
systemctl status jamulus-headless(hit
qto get back to the command prompt).
You can control Jamulus with the
systemctl command. For example, to stop the Server cleanly:
sudo systemctl stop jamulus-headless
To upgrade your Server, just repeat the steps above.
Running in Registered mode
The following minimum setup is required to run a Registered Server:
jamulus --nogui --server \ --directoryserver genreServer:port \ --serverinfo "yourServerName;yourCity;[country ID]"
Note: Semicolon and newline characters are not allowed in
yourCity within the
To register with one of the Directories built into the Jamulus Client, replace
genreServer:port in the example above with one of the following options:
|Any Genre 1|
|Any Genre 2|
|Any Genre 3|
You can also specify a Directory in the same way from the command line, providing the Server Address in the same format.
Running as a Directory
Viewing The Logs
Jamulus will log to the system log file if you left the
StandardOutput=journal setting in the unit file.
To view the log, use
journalctl (to exit press Ctrl-C). For example, to read the system log file, filtered for the Jamulus service:
journalctl -f -u jamulus-headless
When using the recording function with the
-R command line option, if the Server receives a SIGUSR1 signal during a recording, it will start a new recording in a new Directory. SIGUSR2 will recording enabled on/off.
To send these signals using systemd, create the following two
.service files in
/etc/systemd/system, calling them something appropriate (e.g.
Note: You will need to save recordings to a path outside of the jamulus home Directory, or remove
ProtectHome=true from your systemd unit file (be aware that doing so is however a potential security risk).
For turning recording on or off (depending on the current state):
[Unit] Description=Toggle recording state of Jamulus Server Requisite=Jamulus-Server [Service] Type=oneshot ExecStart=/bin/systemctl kill -s SIGUSR2 Jamulus-Server
For starting a new recording:
[Unit] Description=Start a new recording on Jamulus Server Requisite=Jamulus-Server [Service] Type=oneshot ExecStart=/bin/systemctl kill -s SIGUSR1 Jamulus-Server
Note: The Jamulus service name in the
ExecStart line needs to be the same as the
.service file name you created when setting systemd to control your Jamulus Server. So in this example it would be
sudo systemctl daemon-reload to register them for first use.
Now you can run these with the
systemctl command, for example:
sudo systemctl start jamulusTogglerec (assuming you named your unit file
You can see the result of these commands if you run
systemctl status jamulus, or by viewing the logs.
Servers on the desktop
Jamulus can be run in Server mode from the desktop. This gives you a graphical user interface to control most of the settings.
- Windows users - Use the “Jamulus Server” icon in the Windows Start menu.
- macOS users - Double-click the “Jamulus Server” icon in Applications (assuming you put the files from the install there as per these instructions).
- Linux users - Launch the “Jamulus Server” shortcut. Or you can open a terminal window (
CTRL+ALT+ton Debian and related distros), type
jamulus -sand hit return.
The Directory list
None: By default, you will not be connected to a Directory and will be running in unregistered mode. Read these instructions to have other people connect to your Server in this mode.
Genre: To allow other people to see your Server on one of the Directories built into the Client, select your desired genre Directory. You should see a confirmation message saying whether your Server has registered successfully. If not, and you leave your Server running, it will keep trying to register until a free slot becomes available.
Custom: This allows you to specify a custom directory on which to be listed. See the “Options” tab for the Custom Directory address you want to use.
To run your Server as a Directory, you need to set the Custom Directory address as
127.0.0.1 and set the “Genre” to “Custom”. Read this guide for further details.
My Server Info
When running as a Registered Server this displays the Server’s name, city and country so that other users can easily identify it in the Directory listing.
Chat Welcome Message
The text entered here appears to all users when they join the Server (the chat window will open automatically for them). HTML is also supported.
This sets the path to where the Server’s recordings will be stored. With this path set, the “Enable Jam Recorder” function in the Server Setup tab will make recording start once the first person connects to the Server, and stops when the last person leaves. Use the “New Recording” button to create a new sub-directory in which the recordings will be stored from then on. Note that Recordings are per track in Audacity
.lof format and REAPER
.rpp. Open the respective files to listen to them in those applications.
Note: When your Server is recording, Clients will display a message that recording is on.
Custom Directory Address
Leave this field empty unless you need to list your Server on a Custom Directory or run a Directory.
Server List Filename
Leave this field empty unless you need to run your Server as a Directory. When in use, this holds the list of registered Servers whilst restarting the Directory. This prevents the server list appearing “empty” until the Servers re-register.
This option uses small differences in sound arrival time between the two ears. It produces a stereo effect similar to natural human hearing when compared to normal “volume” panning.
Windows users - If you want the Server to start automatically on system start, enable the corresponding check box.
Server status icon
When the Server is running, the operating system will show an icon in the system tray or status area to represent whether the Server is active:
The Server is empty
The Server is occupied
Command line options
Most common functions in Jamulus can be set using the GUI, but these and others can also be set using options given in a terminal window. Exactly how you do this will depend on your operating system.
For example on Windows, to use a specific settings file, right-click on the Jamulus shortcut and choose “Properties” > Target. Add the necessary arguments to Jamulus.exe:
"C:\Program Files\Jamulus\Jamulus.exe" --serverbindip 192.168.0.100
For macOS, start a Terminal window and run Jamulus with the desired options like this:
/Applications/Jamulus.app/Contents/MacOS/Jamulus --serverbindip 192.168.0.100
Note: Command line options will set the Server’s defaults at startup. You can override them with their corresponding GUI controls while the Server is running.
--discononquitDisconnect all Clients on quit. Normally, when a Server is stopped or restarted, any Clients that have not used their “Disconnect” buttons will re-establish connection when the Server comes back up again. Using this option forces Clients to manually re-establish their connections to the Server.
--directoryserverRegister the Server on a Directory (e.g. to set its genre (see also
-o)). See Server Types for further information.
--directoryfileRemember registered Servers even if the Directory is restarted. Directory Servers only. See this guide for further information.
--listfilterWhitelist Servers registering on the Server list, format
ip address 1[;ip address 2]Directories only.
--fastupdateReduces latency if Clients connect with “Enable Small Network Buffers” option. Requires faster CPU to avoid dropouts, and more bandwidth to enabled Clients.
--logEnable logging, set path and file name
--licenceShow an agreement window before users can connect
--htmlstatusEnable HTML status file, set path and file name
--serverinfoLocation details in the format:
[name];[city];[country as two-letter ISO country code or Qt5 Locale](see two-letter ISO country codes or Qt5 Locale values) Registered Servers only
--delaypanStart with delay panning enabled See notes
--recordingSet server recording directory; Server will record when a session is active by default. See Options.
--norecordSet server not to record by default (when recording is configured e.g via
--serverStart in Server mode
--serverbindipSpecify the IP address to bind to
--multithreadingUse multithreading to make better use of multi-core CPUs to support more Clients
--numchannelsMaximum number of channels (Clients)
--welcomemessageWelcome message on connect. Can be given as a string or filename, and can contain HTML.
--serverpublicipThe public IP address of the Server if connecting to a Directory behind the same NAT. See Notes on Directories
--helpDisplay help text
--inifileSet location of initialization file (overrides default)
--noguiDisable GUI (for use in headless mode)
--portSets the local UDP port number. Default is 22124
--jsonrpcportEnables JSON-RPC API server to control the app, set TCP port number (EXPERIMENTAL, APIs might change; only accessible from localhost). Please see the JSON-RPC API Documentation file.
--jsonrpcsecretfileRequired when using
--jsonrpcport. Sets a path to a text file containing an authentication string for getting access to the JSON-RPC API.
--qosSets the quality of service DS Field byte. Default is 128 (DSCP/CS4). QoS is ignored by Windows. To enable it, see this page
--notranslationDisable UI language translations
--enableipv6Enable IPv6 addressing (IPv4 is always enabled)
--versionOutput version information and exit
Running an Unregistered Server
It is highly recommended to test your Server by registering it on one of the built-in Directories first so as to narrow down any subsequent problems in unregistered mode.
Setting up a Server behind a home router
If you set up your server at home, you will probably need to change some settings in your router/firewall:
People from outside your home network will not be able to see things inside it. To let external Jamulus clients connect to your server, you need to set up port forwarding in your Router’s settings. The exact setup differs for every router. For help see your Router’s documentation or portforward.com.
Note: The default port for the current version of Jamulus is UDP (not TCP) port 22124. You will usually forward the port 22124 from outside your network to the port 22124 of the machine running the Server.
Note: Your home router may change the IP address of the machine you’re running your Server on. Depending on your router, you might need to give this machine a static IP address (often under DHCP settings of your router).
Getting the external IP
To allow others to connect to your Server from the internet, get your external (WAN) IP address e.g. by using Google and give it to them. You yourself should connect using the local network (LAN) address of the machine the Server is running on. If you are running a Client on the same machine as your Server, that would be
Dynamic DNS and why you will probably need it
Most domestic internet connections change their external IP address after a short period. To avoid problems with this, you might want to set up “dynamic DNS” to get a static (sub-)domain you can share with others. Please research how to do that for your specic set up. Your router might support some “dynamic DNS” providers out of the box. If this is not the case, set up a dynamic DNS client as described by the dynamic DNS provider you chose.
Backing up the Server
Note that headless Servers do not use
.ini files. All configuration is given as command line options.
Once installed and running, you may want to keep a copy of your settings. Having a backup is always a good idea, and settings files are not backwardly compatible between versions of Jamulus. So if you want to go back to the previous version, you will need to restore the settings you had.
To find your settings file on Windows, type
%APPDATA% into the search bar and look for a folder named
Jamulus. There will be one or more
.ini files in this folder. Now back up Jamulus’ settings.
For all other platforms, run the following from the command line to find where they live and copy the files to another location:
find ~ -name Jamulus.ini -ls
If you used the
--inifile parameter to save an inifile to a different location, don’t forget to also backup these files. Points to note
- Do not back up or restore settings files when Jamulus is running.
- It is not recommended to manually edit settings files (they’re not designed for that).
- You can revert all settings to their defaults by just deleting the settings file (after closing Jamulus).
If you are having other problems, see this guide.