Installing Subsonic on a QNAP NAS

Musical goodness at work and at home.

Update: 13/Aug/2016 — I hope this article remains useful for some people, but the annoyances and straight up technical problems I’m having with my QNAP 451 have led me to look for other storage solutions. If you’re looking to buy a QNAP, I would highly recommend you also look for other solutions. You can find out why here.

For several years my home server was a 2009 Mac Mini with various external hard drives connected to it. It worked reasonably well, providing iTunes Home Sharing and a network iPhoto library. Apple’s Home Sharing lets users stream music on their local network, but it doesn’t stream over the Internet, so I eventually test drove (and then purchased) Subsonic, a cross-platform Java app that streams music and video via an attractive web interface. I could stream my 600GB music library to work, and all was right with the world. However, over time the (already old) Mac Mini started running more slowly. Its operating system was stuck on Snow Leopard, and it couldn’t use any more than the 4GB of RAM I installed when I got it. It was also an eyesore, with multiple drives octopussing out of it. I had been thinking about getting an integrated NAS system for a while, and over Black Friday picked up the QNAP 451-US on sale, stuffed it with four 5 TB hard drives (plus 8GB of RAM), and began to replicate the Mac Mini’s functionality on it.

However, since the QNAP runs a weird Linux variant, things weren’t quite as easy as on the Mac. The QNAP firmware also has gone through several revisions meaning that much of the documentation online is out of date (for this guide, I’m using the 4.2.0 build released 1/19/2016, by the way). My posts on the Subsonic and Madsonic forums went unanswered, while posts on the QNAP user forums are often met with hostility (I didn’t even dare ask there). After a few weeks of struggle and frustration, I got it working but not before I considered wiping the whole system and installing Debian on it. Luckily it didn’t come to that, but I wanted to document that process. Keep in mind that while the instructions should be broadly applicable, the 451-US is an x86 based device (QNAP also sells Atom based NAS systems) and is focused on similar products.

There are three ways to install Subsonic (or Madsonic, a fork of Subsonic that provides a few extra power-user features).

  • From a QPKG available from QNAP’s App Center
  • As a Tomcat package
  • As a standalone WAR package

I tried all three and only got the last method to work with my two requirements — that Japanese filenames and ID3 tags (in addition to other non-English characters) be scanned (about 1/3 of my music is Japanese and I wasn’t planning on renaming or retagging it) and that both FLAC and M4A (Apple’s lossless music format) be usable. Also worth noting is that QNAP’s OS uses a normal Unix directory structure but appears to wipe a lot of directories clean on reboot, meaning a normal install of either app has its preferences at /var/subsonic or /var/madsonic deleted when the system reboots (more on working around that below).

This is by far the easiest method to get Subsonic (or rather the Madsonic fork) installed on a QNAP. One simply has to visit the QNAP’s App Store (accessible once the device is set up) and search for Madsonic (as well as the Java Run Time Environment, or JRE). Once both are installed it should be accessible at your QNAP’s address on port 4040. The device installs the software in a safe hidden directory that isn’t deleted on reboot.

One click and you’re good to go (sort of).

However, I had two issues with this installation. Most notably, the QPKG installed from the App Center is version 5.0. The latest stable release (as I write this) is Madsonic 5.1.5260 with both version 6.0 and 6.1 (which uses HTML 5 rather than Flash) being publicly tested. Even the step-up from 5.0 to 5.1 is steep, with a lot of polish being added in the later version. The software has no method for updating itself, and when I tried to install a newer version (even just 5.1) over the QPKG installed version I borked the installation every time. Unfortunately, the QPKG is put together by a third party (neither QNAP nor the Madsonic developer is involved). It hasn’t been updated in some time, so the future outlook doesn’t look good.

I also could not get transcoders — small Unix programs that convert M4A, FLAC, and other filetypes to MP3 for streaming — to work correctly with this install. Madsonic provides LAME, ffmpeg, and xmp on its site in a transcoder pack, which can be added to Madsonic’s local transcode folder, but even after changing the files’ permissions I could not get Madsonic to use them. I think if I had worked at it a little more I probably could have figured out what was wrong, but I didn’t think it was worth investing time into an older version of Madsonic.

Tomcat Package
Tomcat is an open source web server provided by Apache and it can be used to deploy Subsonic (or Madsonic — I’ll just say Subsonic unless there’s a difference). The benefit here is that you’re getting the latest version of the software and can pretty easily upgrade. Transcoders also seem to work with this installation method. Unfortunately, I could not get non-English characters working using this method.

Like the Madsonic QPKG, Tomcat can easily be installed via QNAP’s App Center. Instructions on installing the package and initial configuration can be found here. You’ll also need the Java Runtime Environment (JRE) available on the App Center. Detailed instructions on installing Tomcat and Subsonic (which is applicable to Madsonic as well) are available on the Subsonic forum (I used these instructions but they’re a little out of date). Per that link, you may also need to install Entware, which replaces the outdated Optware package, and can be used to install Unix utilities on the device. You’re doing this because you may need to install an editor like nano to edit configuration files.

To configure Tomcat and Subsonic, you’ll need to be access the QNAP’s filesystem and edit some files. There are two ways to do this, either by sshing into the QNAP and using a command line file editor or SFTPing and using local tools. For the first method, you will first need to SSH into the device.

On a Mac open up Terminal and type the following:

ssh admin@<your QNAP’s IP address>

You will be prompted for the admin password you use to login to your NAS. If you’re going to edit configuration files on the command line, you’ll need to have installed Entware. You can then use the following command to install the nano text editor.

opkg install nano

Once that’s installed, you may have to cd .. up to the root directory, and then to


Please note that this differs from the instructions I linked to above, since the directory listed there is /share/MD0_DATA/.qpkg/Tomcat/tomcat/conf/tomcat-users.xml. I’m not sure whether this because I’m running RAID6 (in which case if you use a different RAID setup, you may have the MD0_DATA directory instead) or because QNAP made some changes to the file system in firmware updates since the instructions were published (I suspect this was changed due to the heartbleed vulnerability). In any case, CACHEDEV1_DATA isn’t wiped on reboot. Therefore we’ll be using it through the rest of the guide to save Subsonic files (as I mentioned above, a hidden subdirectory in CACHEDEV1_DATA is where the QPKG version is also saved — if the system itself is saving there, I assume it’s safe).

In any case, (assuming nano is installed) from there you can now use the following command to edit Tomcat’s preferences.

nano tomcat-users.xml

You can edit multiple users for Tomcat, but I never got it working. For security’s sake, it is important to at least change the admin password though. Look for this line, and once you have added your password, use CTRL+X and then CTRL+Y to save and quit.

<user username=”admin” password=”<password for user manager>”

Instead of installing Entware and nano, you can also use an FTP client to SFTP into the NAS (this is usually my preferred method). I’ve been using Cyberduck to connect via port 22, which allowed me to edit the files locally via Sublime Text. Since the .qpkg directory is hidden, make sure to show hidden files (under the View menu in Cyberduck).

After installing and configuring Tomcat, download the Tomcat installation on the Subsonic or Madsonic download pages, open up Tomcat and click Tomcat Manager (this will prompt for the user/password you configured above). The following page allows you to upload the package to Tomcat. Scroll down and find the button to “Select WAR file to upload,” choose the package, and click Deploy.

Tomcat will grind along for a few moments and then if everything went well, Subsonic will be deployed and running. Like the above method you can now access the server at <your NAS’s IP>:4040. However, there are still two issues. First, the NAS will delete the Subsonic’s preferences on reboot — so all your configuration files will be gone when you reboot the NAS. Second, the app won’t support non-English characters.

It’s possible to work around the first problem. The NAS will remove files from /var/ on reboot, which will wipe out Subsonic’s preferences. The best way I found to resolve this is the method described by Morkeleb in the Subsonic forum post; symlinking Subsonic’s preferences to a location that won’t be removed. First copy the existing preferences to a safer directory (remember if you’re using Madsonic the directory will be “madsonic” rather than “subsonic”.

cp -r /var/subsonic /share/CACHEDEV1_DATA/subsonic

Then remove the original preferences directory

rm -rf /var/subsonic

Then create the symlink

ln -s /share/CACHEDEV1_DATA/subsonic /var/subsonic

Even this little bit of Unix magic won’t do the trick because the symlink itself will be removed on reboot. You’re allowed to begin crying here. I know I was frustrated. However, there is a work around for the symlink — Tomcat’s startup file can be used to re-create the symlink. Use nano to open up Tomcat’s startup script (or use Cyberduck).

nano /etc/init.d/

With the file open, look for the following text:

case “$1” in

and add the following lines into the loop:

### Create Subsonic link in /var
if [ ! -e /var/subsonic ]; then
ln -s /share/CACHEDEV1_DATA/subsonic /var/subsonic
### End of Subconic link creation

Assuming you’re using nano, when you’re done, use CTRL+X and CRTL+Y to save and quit.

I got this working correctly, and if you don’t have music that uses non-English characters (mostly Japanese for me, but it also includes things like umlauts — according to Shane Trapp, even Beyoncé’s accented e!) it may be enough. Unfortunately though, while I could see through Subsonic’s logs that when it scanned my music collection it couldn’t add Japanese music. Try as I might, I could not get the Tomcat installation of Subsonic to support UTF-8 characters (using the methods I’ll describe below). I suspect this is because Tomcat itself doesn’t, by default, support UTF-8. I tried fixing that on Tomcat, but no matter what I did Subsonic would not pick up music with non-English characters.

Standalone Method
Since the QNAP is basically a Linux system, it’s also possible to manually install a version of Subsonic with the server components already included. The good news was I found instructions on how to do so. Unfortunately for most people those instructions are in Japanese. However, since I read Japanese I was able adapt the guide to our situation.

Like the Tomcat method, you’ll need the Java Environment (JRE) installed. Simply open up QNAP’s App Center and search for JRE. Then hop over to the Subsonic (or Madsonic) download page and download the “stand alone” version (also grab the transcoder pack from the Madsonic site while you’re there). Unzip the stand-alone directory, (I’d rename it simply “subsonic” or “madsonic”) and get it onto your QNAP (I prefer to use Cyberduck). The Japanese instructions posted by tranphonic suggest using /share/HDA_DATA/usr/share/ but the HDA_DATA directory didn’t work for me. I used CACHEDEV1_DATA instead so that my root directory for the app was:


The stand-alone directory will include a file called (or Make sure all your file permissions are at least 755 (you can do this in Cyberduck by right-clicking a file, choosing Info, and then the Permissions tab). We’ll have to make some edits to that file to configure our installation. Use nano or Cyberduck to open the file.

The top of the file contains options that look like this:


The most important line for us is the first. You’ll want to change it to /share/CACHEDEV1_DATA/subsonic. You can also configure the default directories Subsonic uses and change the port the server uses, if you wish. will look similar (using “Madsonic” instead of “Subsonic” of course, and with an additional options for uploaded music and import/export playlist directories). I keep my music on the root directory in a folder named “Music” so I changed the default music folder to /share/Music.

We can also fix the UTF-8 issues using this file too. I added the following lines underneath the block above.

### UTF-8 Support
export LANG=”en_US.UTF-8"
export LC_CTYPE=”en_US.UTF-8"
export LC_ALL=”en_US.UTF-8"
export LC_MESSAGE=”en_US.UTF-8"

This will allow Subsonic to pick up files with non-English characters (it also works with Madsonic of course, even the QPKG installation method above). The Japanese instructions recommends setting the values to LANG=ja_JP.UTF-8 which should work, but requires the extra step of installing a Japanese locale on the QNAP system. UTF-8 works well enough, even allowing me to set Subsonic’s UI to Japanese, so I went with that path of least resistance.

Subsonic can then be started using the startup script.


After a few moments, Subsonic should be accessible at your QNAP’s IP address at 4040 (unless you changed the port in the configuration file).

The Japanese instructions offer some additional tips. First, it’s possible to configure the system to support starting and stop the Subsonic daemon. Create the following file:


and add the text here to that file:

#! /bin/sh
# Provides: subsonic

export PATH=\

DESC="Subsonic Daemon"

export LANG=en_US.UTF-8
export LC_ALL=$LANG
export PATH=$PATH:/opt/bin:/opt/sbin
export JAVA_HOME=/usr/local/jre
export PATH=$PATH:$JAVA_HOME/bin


kill `cat $PIDFILE`
rm -f $PIDFILE

case "$1" in
/sbin/log_tool -a "Starting $DESC" "$NAME"

Make sure the file permission is set to 755 and you should be able to use

/etc/init.d/ start

to start Subsonic. I haven’t gotten this working consistently, and sometimes the Qnap will balk at starting using the “/share/CACHEDEV1_DATA/subsonic/” command (it spits back a file not found error, despite the file clearly being there). If this happens, cd into the subsonic directory and use “./”, and you should be able to start the server.

The Japanese instructions also have a method to auto-start Subsonic when the device boots. Open the following file:


(config is a symlink on my system, and qpkg.conf should already have a few entries itself) and add the following lines:

Name = subsonic
Version = 5.3
Author = me
Date = 2015–02–12
Shell = /share/CACHEDEV1_DATA/subsonic/
Install_Path = /share/CACHEDEV1_DATA/subsonic
Enable = TRUE

The next step is to get the transcoders added so that the server can use them. Without those little applications, Subsonic can’t play M4A or FLAC, and will display an error on some config pages. Simply enough, grab the transcoder pack (x64 should work on the 451-US, though I think x86 will work on any x86 based device) from Madsonic’s page, decompress it, and add the three files, ffmpeg, lame, and xmp, to Subsonic’s transcode directory.


Make sure the files’ permissions are set to 755, and you should bet set.

The only other issue I had with Subsonic was trying to access it outside my home network. The whole point of using the server was so I could easily stream my music at work, so this was something I needed to resolve. Subsonic itself has an option to auto-configure UPNP so that it can work with your router (Settings/Network). If for some reason this doesn’t work, use your router’s Port Trigger settings to trigger outside calls to 4040 to your NAS’s internal IP address. My issue here was that my old port trigger for the Mac Mini server was still on my trigger list, so outside calls to 4040 got sent to a non-existent internal IP address.

Once you’re running, make sure you log into Subsonic. The prompts will guide you through changing the default admin password and adding your media. You should be able to enjoy your music at home, from work, or even your phone using a number of Subsonic compliant apps (I’m using play:Sub and really liking it).

play:Sub in action (also you should listen to this album).

The may seem like a lot of work to install music streaming — especially with options like Google Music and Spotify, but they all had their issues. Spotify doesn’t have much of the music I listen to, and while Google Music will upload MP3 versions of your library it’s a complete black box. The client refuses to upload a number of artists (notably for me lately 水曜日のカンパネラ)and I had no idea why. There is other music streaming software including the NAS’s built-in Music Station and Plex. I really don’t trust Music Station, so didn’t try it. I have tried using Plex, but the software’s music capabilities (especially getting cover art and metadata) are still rather flakey in my experience.

I got used to Subsonic’s quirks with the easy Mac install (indeed, if you’re wanting to test it out, I highly recommend downloading the Mac or Windows install). I think for a higher cost it may have been worth getting a more recent Mac Mini and some kind of local RAID disk array to hook into it. However, once I got over the hump of figuring out how to install the software, it was easy to actually do.

UPDATE 2/20: Enticed by an HTML5 player, I upgraded to Subsonic 6.0 Beta 1. I did this by stopping the existing Subsonic process and replacing the following files from the stand-alone beta install zip in the subsonic directory:


Don’t replace with the one in the zip, or you’ll overwrite your customized preferences. I then cd’d into the subsonic directory and used ./ to restart. After a few minutes, Subsonic was up and running again with a refreshed HTML5 interface and my library.

UPDATE 7/14/2016: Major hat tip to @davilafran. I’m not sure if I made a mistake or something changed with one of QNAP’s firmware updates but my installation is now using CACHEDEV1_DATA rather than CACHEDEV1_DEV. I’ve changed the article to reflect that difference.