Kodi server part 1: Installation and Configuration

Powered by Drupal
Submitted by Sam Hobbs on

This is the first part of a multi-part tutorial describing how to configure the "perfect" Kodi media centre running on top of ubuntu server. Other parts of the tutorial may be found here:

This part of the tutorial deals with basic Kodi installation and network configuration for the server. It sets out some basic configuration to get the system to load Kodi straight away when it boots up, make the media database available to other Kodi clients on the network, enabling the power menu within Kodi's interface, and making sure automatic updates are enabled.


Install ubuntu server 16.04 (later versions will probably work fine too, but I haven't tested them). During the installation, choose the username kodi (or add an additional user called kodi afterwards). Whether you create the user kodi during installation or afterwards, you need to add the user to a few groups to ensure kodi has access to audio and video:

sudo usermod -aG audio,video,render kodi

Configuring networking

To keep things simple, we will configure wifi or ethernet in /etc/network/interfaces instead of using networkmanager. If your server is connected to the internet with an ethernet cable, open /etc/network/interfaces and add the following to the end of the file:

# ethernet connection automatically brought up when cable is plugged in
# with IP address retrieved from the router
allow-hotplug enp3s0
iface enp3s0 inet dhcp

My NUC has a built in WiFi card, and the signal is good enough to stream media files over the network, so I configured WiFi instead. If you have WiFi that is protected with a WPA passphrase, you need to generate a hash that will be used for authentication with the router. First, install the utility that will be used to generate the hash:

sudo apt-get update
sudo apt-get install wpasupplicant

Now generate the hash (substitute your router's SSID and passphrase):

wpa_passphrase SSID passphrase

Since this is sensitive information, the file should only be read by root. Make the file private:

sudo chmod 600 /etc/network/interfaces

Now add the following lines to the end of the file. Substitute your_SSID for your router's SSID, and copy the hash generated by wpa_passphrase into the wpa-psk field:

# WiFi connection that automatically connects when available
# with IP address retrieved from the router
auto wlp2s0
iface wlp2s0 inet dhcp
        wpa-ssid "your_SSID"
        wpa-psk hash_from_wpa_passphrase

Now reload networking:

sudo service networking restart

If you're having problems with this, give me a shout. Things could be different on your network if you have multiple wifi cards etc. One more step: on your router's admin page, give your device a static IP address. This will be important later because this server and other instances of kodi will need the media database and media files to be in a consistent location on the network.

Installing Kodi

Kodi is included in the standard repository, but it's a relatively old version. To ensure we are running the latest version of Kodi, we will add the Kodi development team's PPA. The add-apt-repositories script is in the software-properties-common package, so we need to install that first:

sudo apt-get update
sudo apt-get install software-properties-common

Now add the PPA:

sudo add-apt-repository ppa:team-xbmc/ppa

And install Kodi:

sudo apt-get update
sudo apt-get install kodi

We also need a few dependencies for various purposes:

  • xorg and xserver-xorg-legacy provide the display server needed to run kodi
  • dbus-x11 provides dbus-launch (used to launch kodi)
  • alsa-utils for sound
sudo apt-get install xorg xserver-xorg-legacy dbus-x11 alsa-utils

Starting Kodi automatically

The following systemd unit file will launch kodi automatically. Create it using sudo nano /etc/systemd/system/kodi.service (ctrl + x to exit, save when prompted):

Description = Kodi Standalone (X11) unit file copied from AUR

After = remote-fs.target systemd-user-sessions.service network-online.target nss-lookup.target sound.target bluetooth.target polkit.service upower.service mysqld.service
Wants = network-online.target polkit.service upower.service
Conflicts = getty@tty1.service

User = kodi
Group = kodi
# EnvironmentFile=-/etc/conf.d/kodi-standalone 
ExecStart = /usr/bin/xinit /usr/bin/kodi-standalone -- :0 -quiet -nolisten tcp vt7
ExecStartPost = /usr/bin/sh -c 'DISPLAY=:0 xset s off -dpms'
ExecStop = /usr/bin/killall --user kodi --exact --wait kodi.bin
Restart = on-abort


To make this "service" start automatically boot, we need to enable it:

sudo systemctl enable kodi

You should now find that when you boot up, kodi is launched automatically.

Note: if you have issues with this init file, check out the source of the latest kodi-standalone arch package here:


Download and open the source archive and you should see an updated init file at x86/init/kodi-x11.service inside the archive.

The Environment line is one I've added myself, it passes an environment variable to kodi that tells it to use ALSA for sound instead of pulseaudio - I found that with pipewire installed by default on newer systems, I could only see the default pulseaudio output device and couldn't send the sound opulseaudi

The following line is another one I added myself, to disable display power management:

ExecStartPost = /usr/bin/sh -c 'DISPLAY=:0 xset -dpms'

This should prevent your monitor/TV from displaying 'no signal' when the system is idle for a long time.

Allow kodi to suspend/reboot/shut down the system

Polkit is a tool that enables unprivileged users (i.e. non-root users) to carry out certain actions that affect the whole system, without needing "sudo". We will use this to let kodi suspend/reboot/shut down the system. Create a new rule file using sudo nano /etc/polkit-1/localauthority/50-local.d/kodi.pkla and paste the following information:

[kodi user]

Now reload the polkit daemon so the rule file is read:

sudo service polkitd reload

And then test that you can reboot, suspend, power off etc. the box using the power menu within Kodi.

Allowing auto updates to Kodi

I allow unattended upgrades on my box so that I don't have do as much manual administration. If you didn't allow unattended upgrades during installation of the OS, you can install unattended upgrades like so:

sudo apt-get update
sudo apt-get install unattended-upgrades

If it's already installed, you can re-run the configuration script using:

sudo dpkg-reconfigure unattended-upgrades

This will create a config file at /etc/apt/apt.conf.d/20auto-upgrades with the contents:

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";

By default, only packages in the ubuntu archive are auto updated, but since we installed Kodi from the developers' PPA we won't receive auto updates unless we make a change. To allow auto-updates to kodi, open /etc/apt/apt.conf.d/50unattended-upgrades and edit the Unattended-Upgrade::Allowed-Origins block at the top of the file so it looks like this:

// Automatically upgrade packages from these (origin:archive) pairs
Unattended-Upgrade::Allowed-Origins {
        // Extended Security Maintenance; doesn't necessarily exist for
        // every release and this system may not have it installed, but if
        // available, the policy for updates is such that unattended-upgrades
        // should also install from here by default.
//      "${distro_id}:${distro_codename}-updates";
//      "${distro_id}:${distro_codename}-proposed";
//      "${distro_id}:${distro_codename}-backports";
        // manually added so that auto updates include updates to Kodi

Sharing the media database with other kodi machines on your network

Kodi's libraries can be stored in a mysql database that is made available over the network to other machines. This lets you share your media library and do things like start watching a video on one device, pause it, move rooms and pick up where you left off on the new device. First we need to set up a mysql server:

sudo apt-get update
sudo apt-get install mysql-server

During installation you will be asked to set a root password for database administration. Don't forget it! The next step is to start a mysql shell and create a user and database for kodi. This command will start a shell as the mysql root user (type the password you created during installation to authenticate):

mysql -u root -p

This will give you a mysql shell that looks like this:

mysql >

I've kept the prompt in the commands that follow, to distinguish them from normal shell commands. First, create a database username for kodi:

mysql > CREATE USER 'kodi' IDENTIFIED BY 'kodi';

In the command above, the part IDENTIFIED BY "kodi" is setting the password "kodi" for kodi; choose a different password if you like. Next, give the new user kodi the privileges it needs to create tables and edit them:

mysql > GRANT ALL ON *.* TO 'kodi';

And make the changes take effect:

mysql > flush privileges;

When you are done, type quit and hit enter to exit the mysql shell. Now, to tell Kodi to use the newly created database create the file ~/.kodi/userdata/advancedsettings.xml with contents:




If you chose a different password in the previous step, make sure to change the <pass>kodi</pass> parts. At the moment, this database is only available on the local machine. To make it accessible to other clients on the local network, open /etc/mysql/mysql.conf.d/mysqld.cnf and find the following line under the [mysqld] section:

bind-address =

Change it (or comment it and add a new line) to this:

bind-address =

And restart mysql:

sudo service mysql restart

To verify that mysql is listening for remote connections, try connecting from a different machine using telnet (replace the IP address with the IP of your kodi box):

telnet 192.168.X.X 3306

Now all you need to do to use this kodi library on other boxes is to put the same advancedsettings.xml file we used earlier on the second machine, but replace localhost with the IP address of the kodi box. Stuck? Give me a shout in the comments below. If you're done, move on to the next part of the tutorial.


Hey Sam.

I wanted to bring to your attention a code error in Part 1 of your installing Kodi guide.

This command: sudo service polkitd reload

Has changed and should now be: sudo systemctl restart polkitd.service

Thanks for taking the time to create such a thorough write-up on Kodi installation on Ubuntu 16.04 server. I'm in the process of writing a comprehensive guide to building a custom media server. I was on the fence on whether or not to include Kodi and Plex, because they are effectively viewers versus aggregators, and I am more focused on the latter. I decided to include some info on them since they're great compliments to a media server, and stumbled upon your website during my research of Kodi. The last time I had installed it on Ubuntu was 12.04 server, and both Ubuntu and Kodi have changed substantially since then.

Thank you for your efforts. :D


David, You're very welcome, and thanks for the comments. My servers are running ubuntu 16.04, which version of Ubuntu are you using or are you on some other system? Has the service script actually been removed on your machine? It is meant to be an abstraction layer for the init system, so if you had some other init system like openrc or sysvinit it would still work. It's quite interesting to read actually, have a look if it's still installed (cat /usr/sbin/service). Out of interest, what are you using as an aggregator? Sam

I'm using 16.04.4 server. I installed 16.04.1 and upgraded to 16.04.4. I have quite a few packages installed, but it's still a relatively bare bones system. So, on my server I've found some "service" scripts do work, yes. However, my server requires me to use systemctl to manipulate polki. I thought this was part of the changeover to systemd in 16.04 LTS.

For content aggregation, atm I'm using SABnzbd, SickBeard, Sonarr, Headphones, Couch Potato, Transmission, and Jackett.

Now, to tell Kodi to use the newly created database create the file ~/.kodi/userdata/advancedsettings.xml with contents: how to i create this file no matter what i do it says directory does not exist

I'm setting this up on Ubuntu Desktop, however it will not go to the Kodi screen and instead will always revert to the desktop environment.
Do you have any instructions on how to set it up on Ubuntu Desktop?

I'm new to Kodi, so thanks for the tutorial.
Maybe I missed it, but how do you tell Kodi where your media is located so it can start building its database? I'm using a headless server that I SSH into so there's no GUI to point to the media.
In my case the video and music files are stored on a Synology NAS and shared using nfs (I already mounted the shares on the server that will run Kodi).
Any suggestions are welcome. Thanks!

I think those settings are in ~/.kodi/userdata/Sources.xml. You may also need to trigger a library update; the library should be refreshed when you start kodi but if you don't want to stop/start it or reboot, you can do it remotely like this: https://kodi.wiki/view/HOW-TO:Remotely_update_library Let me know how you get on, your setup is quite unusual so it will be interesting to hear! Sam


I run Kodi on a headless Ubuntu 16.04.x server. You will need to install a windows manager. Then configure your system to automatically boot into Kodi's GUI and login as your Kodi user. From there you can setup the sources via Kodi's UI.


Hi Sam,

Thanks for an extensive write-up! However I can't seem to get it to work. I know it has been some time since you wrote this down, but I still hope you can help me further. I followed your steps up onto registering it as a service, but when I reboot I get this message:

Dec 27 21:01:01 manus systemd[1]: Started Kodi Media Center.
Dec 27 21:01:02 manus systemd[872]: pam_unix(login:session): session opened for user kodi by (uid=0)
Dec 27 21:01:20 manus systemd[1]: kodi.service: Main process exited, code=exited, status=1/FAILURE
Dec 27 21:01:20 manus systemd[1]: kodi.service: Failed with result 'exit-code'.

I tried manually running the service command:
sudo -u kodi /usr/bin/xinit /usr/bin/dbus-launch --exit-with-session /usr/bin/kodi-standalone -- :0 -nolisten tcp

But it yields:

/usr/lib/xorg/Xorg.wrap: Only console users are allowed to run the X server
/usr/bin/xinit: giving up
/usr/bin/xinit: unable to connect to X server: Connection refused
/usr/bin/xinit: server error

Starting Kodi-standalone yields:
sudo -u kodi kodi-standalone
Could not init logging classes. Log folder error (/home/nebula/.kodi/temp/)
ERROR: Unable to create application. Exiting
Could not init logging classes. Log folder error (/home/nebula/.kodi/temp/)
ERROR: Unable to create application. Exiting
Could not init logging classes. Log folder error (/home/nebula/.kodi/temp/)
ERROR: Unable to create application. Exiting
/usr/bin/kodi --standalone has exited in an unclean state 3 times in the last 0 seconds.
Something is probably wrong

It seems to point to my ssh logged in user home? Is this because I started Kodi as that user the first time?

Hopefully you can give me some pointers on as how to proceed!


Jasper, Sorry for the delayed response, it has been a busy week! Is kodi a user you can log in as? It could be something different in 18.04 (my server is still 16.04, I haven't updated it yet) but I doubt it. Sam


I've seen that before. It's most likely a permissions issue and some process is crashing out because it does not have rights to perform a function related to either Kodi or the Xorg video driver. Based on the log data you posted, it looks to me as if it's an Xorg issue since:

1. Kodi process starts
2. Kodi user tries to launch an X window process
3. Kodi gets rejected and Xorg complains the user does not have terminal rights (presumably because your Kodi user was created as a 'no login' user)

Unfortunately, it's rather challenging to solve these issues because a number of things can go wrong.

If you run

sudo systemctl status kodi

Do you get a response that Kodi is not running or that it's dead?

The good news is it looks like Kodi starts and talks to the X-Windows process. So, the issue should be with either 1) Kodi user permissions; or 2) X-Windows settings; or 3) possibly you don't have a Window Manager in between Kodi and Xorg.

Also, you need a Window manager. I haven't read through Sam's guide in some time, but I recall it works well on Ubuntu 16.04, and 18.04 should be a very similar process (though I will say there's a reason I don't use any new OS for at least a year after GM: bugs). LoL. :)

You can find a good list of windows managers here: https://en.wikipedia.org/wiki/Comparison_of_X_window_managers

Personally, I use OpenBox. It's lightweight and quick, and the only reason I need it is for Kodi.

Quite a number of things can also go wrong if you missed a "sudo" during the install/setup process for Kodi. Given all the steps, you could consider implementing "sudo -i" to run everything as root during the setup process.

These commands might help you troubleshoot the current situation:

tail -f -n 50 /var/log/xorg.0.log

journalctl -n 50

Or even open up another terminal session, try to force restart Kodi and watch the log in realtime:

journalctl -f

Hopefully, some of that is helpful. The good news is once you get the bottleneck sorted out it should be rock solid. :)

Hello! Hijacking this reply. I have a similar issue with Kodi service not starting up. I followed your instruction running journalctl and the output after a systemctl restart kodi is:

Feb 26 15:54:33 kodiserver systemd[1]: Started Kodi Media Center.
Feb 26 15:54:33 kodiserver sudo[3065]: pam_unix(sudo:session): session closed for user root
Feb 26 15:54:33 kodiserver systemd[3068]: kodi.service: Failed to determine group credentials: No such process
Feb 26 15:54:33 kodiserver systemd[3068]: kodi.service: Failed at step GROUP spawning /usr/bin/xinit: No such process
Feb 26 15:54:33 kodiserver systemd[1]: kodi.service: Main process exited, code=exited, status=216/GROUP
Feb 26 15:54:33 kodiserver systemd[1]: kodi.service: Failed with result 'exit-code'.

So it seems to be a permission issue?

Hi, thanks for this nice write-up!

I want to add that on Ubuntu Server 18.04 I needed to make this modification in /etc/X11/Xwrapper.config :

In addition I installed xserver-xorg-video-intel as I'm running on an Intel graphics chip. Not sure though if this was necessary at the end.

Hi Sam! Thanks so much for this fantastic write-up. I have virtually zero experience with command line stuff and I was able to follow along through this whole tutorial and understand a solid 1/3 of what I was doing, haha.

Thanks again! I really appreciate it!


Fri, 02/26/2021 - 04:01

Hi ans thanks a lot for this tutorial! I follows all steps except the bit of sharing the database.

Now, first I was surprised to see a desktop when booting. I thought it would just be full text and xorg would allow apps like kodi to show their face.

Second, Kodi didn’t start up on boot. I had to find the app and click.

Is there a way to skip the desktop part and just go straight to Kodi? Also how can I make Kodi start up?

I’m using the latest version (v 20). There was a couple of services, network and polkitd had different names than described above.