Server Administration Manual

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.

Basic requirements

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.

General notes

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

Server Types

You can run your Server in different ways (either at home or on a 3rd party host):

1. Registered

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.

2. Unregistered

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.

3. Directory

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.

Installation

1. 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
2. Update apt to make sure you have a current list of standard packages: sudo apt update
3. Install the Jamulus package: sudo apt install ./jamulus-headless_3.9.1_ubuntu_amd64.deb or 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
4. Enable the headless Server process via systemd: sudo systemctl enable jamulus-headless
5. Add your desired command line options to the ExecStart line in the systemd service file by running sudo systemctl edit --full jamulus-headless (By default you will be running an Unregistered Server).
6. Reload the systemd files sudo systemctl daemon-reload and restart the headless Server: sudo systemctl restart jamulus-headless
7. Check all is well with systemctl status jamulus-headless (hit q to 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.

Configuration

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 yourServerName and yourCity within the --serverinfo argument

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:

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

If you wish to run a Directory please see this guide.

Maintenance

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

Controlling Recording

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

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 Jamulus-Server.service

Run 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 jamulusTogglerec.service)

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+t on Debian and related distros), type jamulus -s and hit return.

Server Setup

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 localhost or 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.

Options

Recording Directory

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.

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.

Start Minimised

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.

• -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 Remember registered Servers even if the Directory is restarted. Directory Servers only. See this guide for further information.
• -f or --listfilter Whitelist Servers registering on the Server list, format ip address 1[;ip address 2] Directories only.
• -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];[country as two-letter ISO country code or Qt5 Locale] (see two-letter ISO country codes or Qt5 Locale values) Registered Servers only
• -P or --delaypan Start with delay panning enabled See notes
• -R or --recording Set server recording directory; Server will record when a session is active by default. See Options.
• --norecord Set server not to record by default (when recording is configured e.g via -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. Can be given as a string or filename, and can contain HTML.
• -z or --startminimized Start minimized
• --serverpublicip The public IP address of the Server if connecting to a Directory behind the same NAT. See Notes on Directories

• -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
• --jsonrpcport Enables 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.
• --jsonrpcsecretfile Required when using --jsonrpcport. Sets a path to a text file containing an authentication string for getting access to the JSON-RPC API.
• -Q or --qos Sets the quality of service DS Field byte. Default is 128 (DSCP/CS4). QoS is ignored by Windows. To enable it, see this page
• -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

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:

Port forwarding

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

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

Troubleshooting

If you are having other problems, see this guide.