Server Administration Manual
Table of contents
- Do I need to run a server?
- Server Types
- Bandwidth use
- Starting a server
- Running a Private Server
- Running a headless Linux server
- Backing up the server
- Command line options
- Quality of Service (QoS)
Do I need to run a server?
The short answer is no. For various reasons, you should try to use other people’s servers, at least at first while getting your sound set up with the Jamulus client.
Note that you can have a “private” session with other people on a Public Server by simply soloing each other. You will then not be able to hear anyone else if they enter your server.
If you do decide to run a server, please read the following. Setting up a server is easy, however it is better to know the theory first:
Speed and latency
Many people attribute problems to the server that are in fact problems with the client. Much depends on the clients’ hard/software setup, the networks that they are on, and whether they are sticking to Rule Number One.
The capability of the server itself (and the network it’s on) is NOT the main determinant of the quality of a Jamulus session!
If you plan to be playing regularly with the same people, you are strongly advised to first make sure that each member of the group is set up to use Jamulus properly. Do this by finding a Public Server with a reasonable ping time for all of you (20 ms or less perhaps), all connect to that and work to fix any individual issues (verifying that they can follow Rule Number One in particular). Use the solo technique above to prevent being interrupted if needed.
Once any issues with musicians have been solved in this way, you can then investigate hosting your own server either at home or on a cloud host such as Amazon, which may result in better latency than servers run at home. For example, see this guide for using AWS Lightsail, by Jamulus user Simon Tomlinson (Facebook)
Bandwidth – do you have enough?
Unless you plan on hosting more than about 5 players on a slower-speed home connection (eg 10 Mbit/s down and 1 Mbit/s up), then you are unlikely to run out of bandwidth. You can read more about network requirements at different quality settings later in this document.
Consider using a cloud host 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 a Private Server at home will require you to port forward on your router. When running a Public 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 one of three “modes” (either at home or on a 3rd party host):
Use this mode when you want anyone to join your server, whoever they are.
Your server will be listed in the Directory that clients use by default. Musicians can then discover and connect to your server.
This is the default when starting a server for the first time. Private 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 (in any server mode) let you control who can connect to a server.
For when you want to run a number of Private Servers, possibly also behind a firewall or on a LAN. Examples include online events, music associations, sectional rehearsals or music lessons for schools.
To view servers listed by a custom Directory Server, musicians must enter the address in their client’s “Custom Directory Server” settings field. They will then see a Connection Setup list which is generated by your Directory.
Up to 150 servers can then register with your Directory by setting your Directory address in their
--directoryserver option at startup.
To run a server as a Directory, it should be configured with
--directoryserver localhost (that is, making itself the Directory to query for servers).
Points to note about Directories
If you want to control which servers can register with your Directory, you can enable a whitelist with the
--listfiltercommand line option. See the section on command line options later in this document.
When running a public Directory Server behind a NAT firewall on a private network, use the
--serverpublicipoption to specify the public IP address of the server(s) being listed by your Directory. This is necessary to allow clients on the public Internet to connect to them via NAT. Note that for the servers using this option, you will still need proper port forwarding in your router/firewall.
The audio settings have an impact on the required network bandwidth. The table below summarises network requirements with respect to the configuration of:
- Channels : stereo/mono
- Quality : high/medium/low
- Audio buffer duration : 2.67 ms, 5.33 ms, 10.67 ms, 21.33 ms
With the following units
- ms : milliseconds
- Kbit/s : Kilo-bits per second (Reminder : 1 Mbit/s = 1024 Kbit/s, 1 KByte/s = 8 Kbit/s)
- Mbit/s : Mega-bits per second
|Channels||Quality||Bandwidth (for buffer : 2.67 ms)||Bandwidth (for buffer : 5.33 ms)||Bandwidth (for buffer : 10.67 ms)||Bandwidth (for buffer : 21.33 ms)|
|Stereo||High||894 Kbit/s||657 Kbit/s||541 Kbit/s||483 Kbit/s|
|Stereo||Medium||672 Kbit/s||444 Kbit/s||328 Kbit/s||270 Kbit/s|
|Stereo||Low||606 Kbit/s||372 Kbit/s||256 Kbit/s||198 Kbit/s|
|Mono||High||672 Kbit/s||444 Kbit/s||328 Kbit/s||270 Kbit/s 8|
|Mono||Medium||594 Kbit/s||366 Kbit/s||250 Kbit/s||192 Kbit/s|
|Mono||Low||534 Kbit/s||306 Kbit/s||190 Kbit/s||132 Kbit/s|
There is one upstream (musician sending to the server) and one downstream (server sending back the mix to the musician)
Note also that mean ADSL2 transfer rate is 10 Mbit/s for downstream and 1 Mbit/s for upstream. The actual performance depends on distance to the provider, which may theoretically range from 24 Mbit/s at 0.3 km to 1.5 Mbit/s at 5.2 km for download rate.
Starting a server
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 - Open a terminal window (
CTRL+ALT+ton Ubuntu and related distros) and type
jamulus -s. Hit return and you should see the server control window. You can stop the server by closing the server window, or by using
CTRL+Cin the terminal. (To run a headless server read this guide)
Make My Server Public
By default, you will be running a Private Server and need to read these instructions to have others connect to you in this mode.
When making your server public, 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.
Because there is a limit of 150 servers per Directory, you need to select which Directory Server you want to advertise your server on. Select a genre if you intend to limit players to that style (players can then see your server in their genre list). This will make your server appear in the relevant server list for clients.
My Server Info
Type in the name, city and country so that other users can easily identify you.
Chat Welcome Message
The text entered here appears to all users when they join the server (the chat window will open automatically for them).
This sets the path to where server’s recording will be stored. With this path set, the “Enable Jam Recoder” 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.
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. Note that to achieve the effect, all clients should be set to ‘mono in / stereo out’ (or to ‘stereo’, but only if transmitting a stereo signal).
Custom Directory Server Address
Leave this field empty unless you need to list your server on a private Directory
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
Running a Private Server
It is highly recommended to test your server in public mode first so as to narrow down any subsequent problems in private mode.
Normally, people from outside your home network cannot see things inside it. So if you want to operate a Jamulus server at home, you need to open a hole in your router to let Jamulus clients connect to it.
The default port for the current version of Jamulus is UDP (not TCP) port 22124.
The exact setup of port forwarding differs for every router. For help see portforward.com.
Once you have your router set up, you can get your external (WAN) IP address e.g. by using Google. Give this address to your friends so they can connect to your server (but see also the note on dynamic DNS below). You yourself have to connect to your own computer instead, since your computer runs the server. Therefore only you need to connect to
Dynamic DNS and why you will probably need it
Most domestic Internet connections will change their IP address after a period (hours, days or weeks). To make it easier for people to connect to you, you may therefore also want set up a dynamic DNS address. You can do this on the machine that you are running the Jamulus server on, or preferably your router may support it.
Note also that your home router may also change the IP address of the machine that you are running your server on. In which case you may need either to give that machine a static IP in the router’s DHCP configuration, or simply port forward to all the addresses in your LAN.
Running a headless Linux server
Those wishing to run a server on a Linux cloud or other third party hosting platform should read this guide.
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, look in the
%APPDATA% folder. There will be one or more
.ini files in a folder there named
For all other platforms, run the following from the command line to find where they live:
find ~ -name Jamulus.ini -ls
Points to note
- Do not back up or restore settings files when Jamulus is running.
- It is not recommended to edit settings files by hand (they’re not designed for that).
- You can revert all settings to their defaults by just deleting the settings file (after closing Jamulus).
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.
--directoryfileEnable directory to remember registered servers even if the directory is restarted. You’ll need to specify a path to a writable file location in which server information is stored.
--listfilterWhitelist servers registering on the server list, format
ip address 1[;ip address 2]Directory Servers only. See server types
--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];[locale value](see values) Public servers only
--delaypanStart with delay panning enabled See notes
--recordingInclude a writeable path where the files should be stored (in quotes if needed). See Options.
--norecordDisable recording when enabled by default by
--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
--serverpublicipThe public IP address of the server if connecting to a Directory behind the same NAT. See Notes on Directory Servers
--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
--qosSets the quality of service DSCP value. Default is 128. Disable with 0. QoS is ignored by Windows. To enable it, see section below
--notranslationDisable UI language translations
--enableipv6Enable IPv6 addressing (IPv4 is always enabled)
--versionOutput version information and exit
Quality of Service (QoS)
Jamulus uses DSCP/CS4 opportunistically to deal with buffer bloat, and uses a default DSCP/CS4 value of 128 (or 0x80). This is compatible with IPv4 and IPv6. Other values can be set using the -Q option, eg -Q [0..255] (where 0 disables QoS). If you want to explore the effect of non-default settings, see RFC4594. However, most people will have no need to do this.
Use of QoS on Windows
Jamulus’s QoS settings (including the default) have no effect on Windows because the operating system ignores them. To enable it, you must follow these instructions. Note also that you may need to repeat this procedure every time Jamulus is updated.
In Search box beside Start menu Type: Local Group Policy Editor (enter)
In new window, (click) on the menu icon to display the Actions third panel
Looking at the first panel of the Local Group Policy Editor
Local Computer Policy
Policy-based QoS (click)
Looking at the third panel (Actions) of the Local Group Policy Editor
Create new Policy (click)
Policy Name: Jamulus
Specify DSCP value: 32
This QoS policy applies Only to applications with name Jamulus.exe
(Notice Jamulus policy in center panel may be edited)
Various problems can arise when setting up servers, and we generally ecourage people to use other people’s (public) servers at first to isolate any issues that may in fact be due to client configuration.
If you are having problems, see this guide.