Jamulus Icon. Links to homepage
Navigationsmenü öffnen

Server Administration Manual

Table of contents

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.

In general

  • 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 Private 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.

Server Types

You can run your server in one of three “modes” (either at home or on a 3rd party host):

1. Public

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.

Diagram of connections between clients within a Jamulus Public Server
How Public Servers work

2. Private

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.

Diagram of connections between clients within a Jamulus Private Server
How Private Servers work

3. Directory

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 --listfilter command 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 --serverpublicip option 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.

Bandwidth use

Audio bandwidth

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
ChannelsQualityBandwidth (for buffer : 2.67 ms)Bandwidth (for buffer : 5.33 ms)Bandwidth (for buffer : 10.67 ms)Bandwidth (for buffer : 21.33 ms)
StereoHigh894 Kbit/s657 Kbit/s541 Kbit/s483 Kbit/s
StereoMedium672 Kbit/s444 Kbit/s328 Kbit/s270 Kbit/s
StereoLow606 Kbit/s372 Kbit/s256 Kbit/s198 Kbit/s
MonoHigh672 Kbit/s444 Kbit/s328 Kbit/s270 Kbit/s 8
MonoMedium594 Kbit/s366 Kbit/s250 Kbit/s192 Kbit/s
MonoLow534 Kbit/s306 Kbit/s190 Kbit/s132 Kbit/s

Network bandwidth

There is one upstream (musician sending to the server) and one downstream (server sending back the mix to the musician)

A diagram of Jamulus network bandwidths from different audio qualities ranging from low to high
Calculate bandwidth use

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+t on 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+C in the terminal.

Server Setup

Image of the Jamulus server setup window

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.

Genre

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).

Options

Image of Jamulus server window options

Recording Directory

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.

Delay panning

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

Start Minimised

Windows users - If you want the server to start automatically on system start, enable the corresponding check box.

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.

Port forwarding

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 127.0.0.1.

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.

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 not alter settings made in the GUI.

  • -d or --discononquit Disconnect 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.
  • -e or --directoryserver Register the server on a directory (e.g. to set its genre (see also -o)). See server types for further information.
  • --directoryfile Enable 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.
  • -f or --listfilter Whitelist servers registering on the server list, format ip address 1[;ip address 2] Directory Servers only. See server types
  • -F or --fastupdate Reduces latency if clients connect with “Enable Small Network Buffers” option. Requires faster CPU to avoid dropouts, and more bandwidth to enabled clients.
  • -l or --log Enable logging, set path and file name
  • -L or --licence Show an agreement window before users can connect
  • -m or --htmlstatus Enable HTML status file, set path and file name
  • -o or --serverinfo Location details in the format: [name];[city];[locale value] (see values) Public servers only
  • -P or --delaypan Start with delay panning enabled See notes)
  • -R or --recording Include a writeable path where the files should be stored (in quotes if needed). See Options.
  • --norecord Disable recording when enabled by default by -R
  • -s or --server Start in server mode
  • --serverbindip Specify the IP address to bind to
  • -T or --multithreading Use multithreading to make better use of multi-core CPUs to support more clients
  • -u or --numchannels Maximum number of channels (clients)
  • -w or --welcomemessage Welcome message on connect
  • -z or --startminimized Start minimizied
  • --serverpublicip The public IP address of the server if connecting to a Directory behind the same NAT. See Notes on Directory Servers
  • -h or --help Display help text
  • -i or --inifile Set location of initialization file (overrides default)
  • -n or --nogui Disable GUI (for use in headless mode)
  • -p or --port Sets the local UDP port number. Default is 22124
  • -Q or --qos Sets the quality of service DSCP value. Default is 128. Disable with 0. QoS is ignored by Windows. To enable it, see section below
  • -t or --notranslation Disable UI language translations
  • -6 or --enableipv6 Enable IPv6 addressing (IPv4 is always enabled)
  • -v or --version Output version information and exit

Troubleshooting

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.

Sag uns, was du über Jamulus denkst - fülle unsere anonyme Umfrage aus (English)

Dieses Wiki ist unter einer Creative Commons Lizenz lizenziert. Willst du mithelfen?