Administration

• 1: Automated Backup
• 2: Security Considerations
• 3: Anonymous Data Collection

1 - Automated Backup

Navidrome version 0.54.x introduces a backup feature that allows the music server’s data to get periodically exported. This guide will walk you through configuring backups using both a configuration file and environment variables, where to locate the backups, and how to restore from a backup.

Configuring Backup with config.toml

To configure backups using the navidrome.toml file, insert the following lines to set up backups:

[Backup]
Path = "/path/to/backup/folder"
Count = 7
Schedule =  "0 0 * * *"

• Backup.Path: The directory where backups will be stored. Replace “/path/to/backup/folder” with the desired path.
• Backup.Count: The number of backup files to keep.
• Backup.Schedule: cron-like syntax to define how often backups occur. The example above schedules a backup every 24 hours at midnight.

Configuring Backup with Environment Variables

Alternatively, you can configure backups using environment variables ND_BACKUP_PATH, ND_BACKUP_SCHEDULE, and ND_BACKUP_COUNT.

environment:
  ND_BACKUP_PATH: /backup
  ND_BACKUP_SCHEDULE: "0 0 * * *"
  ND_BACKUP_COUNT: 7
volumes:
  - ./data:/data
  - ./backup:/backup

Manually Creating a Backup

You can manually create a backup via the navidrome backup create command:

sudo navidrome backup create

If you use docker compose, you can do the same with:

sudo docker compose run <service_name> backup create
# service_name is usually `navidrome` 

When manually creating a backup, no prune cycle is run, so none of the existing backups will be pruned. However, next time the automated backup process runs, the normal prune cycle will run and potentially remove several backups until the number of backups is down to the configured backup count setting. To manually run a prune cycle, use the navidrome backup prune command:

sudo navidrome backup prune

If you use docker compose, you can do the same with:

sudo docker compose run <service_name> backup prune
# service_name is usually `navidrome`

Locating Backup

Once configured, Navidrome will store backups in the directory specified by the BackupFolder or ND_BACKUP_PATH setting. To verify the location:

• Check the Config File: If using a configuration file, look for the Backup config node and confirm that all three options are configured.
• Check Environment Variables: If using environment variables, ensure that all three variables is set correctly.

Restoring a Backup

When you restore a backup, the existing data in the database is wiped and the data in the backup gets copied into the database.

Note: YOU MUST BE SURE TO RUN THIS COMMAND WHILE THE NAVIDROME APP IS NOT RUNNING/LIVE.

Restore a backup by running the navidrome backup restore command.

Additional Resources

For more detailed configuration options and examples, refer to the Navidrome Configuration Options page. This resource provides comprehensive guidance on customizing Navidrome to fit your needs.

By following this guide, you can effectively set up and manage backups for your Navidrome music server, ensuring your data is protected and easily recoverable.

2 - Security Considerations

Permissions

You should NOT run Navidrome as root. Ideally you should have it running under its own user. Navidrome only needs read-only access to the Music Folder, and read-write permissions to the Data Folder.

Encrypted passwords

To be able to keep compatibility with the Subsonic API and its clients, Navidrome needs to store user’s passwords in its database. By default, Navidrome encrypts the passwords in the DB with a shared encryption key, just for the sake of obfuscation as this key can be easily found in the codebase.

This key can be overridden by the config option PasswordEncryptionKey. Once this option is set and Navidrome is restarted, it will re-encrypt all passwords with this new key. This is a one-time only configuration, and after this point the config option cannot be changed anymore or else users won’t be able to authenticate.

Network configuration

Even though Navidrome comes with an embedded, full-featured HTTP server, you should seriously consider running it behind a reverse proxy (Ex: Caddy, Nginx, Traefik, Apache) for added security, including setting up SSL. There are tons of good resources on the web on how to properly setup a reverse proxy.

When using Navidrome in such configuration, you may want to prevent Navidrome from listening to all IPs configured in your computer, and only listen to localhost. This can be achieved by setting the Address flag to localhost.

Externalized authentication

When externalized authentication is enabled, Navidrome trusts the authenticated user header (configured with the ExtAuth.UserHeader option, by default Remote-User).

In principle, the authenticated user header is ignored if requests don’t come from a reverse proxy trusted with the ExtAuth.TrustedSources option. This check can however be fooled by requests with a forged source IP address if the reverse proxy can be bypassed (e.g. a request sent by a compromised service running next to Navidrome).

When using externalized authentication in a fresh installation, the first user created through this method will automatically be granted admin privileges, consistent with the behavior when creating the first user through the web interface.

Listening on a UNIX socket

If you are listening on a UNIX socket (Address option) and enable externalized authentication (ExtAuth.TrustedSources configured with the special value @), any process able to write to the socket can forge authenticated requests.

Make sure to properly protect the socket with user access controls (see the UnixSocketPerm option).

Reverse proxy with a dynamic IP address

Navidrome does not support resolving hostnames in the ExtAuth.TrustedSources configuration option.

In scenarios where the reverse proxy has a dynamic IP address, for example when you use docker, you might consider using 0.0.0.0/0 to allow requests from the reverse proxy. This essentially disables the check, so you have to make sure that only the reverse proxy can send requests to Navidrome.

In particular with docker and docker-compose, without extra configuration containers are usually placed on the same default network and can therefore freely communicate.

Potential HPP vulnerability

When externalized authentication is enabled, Navidrome currently does not disable the other authentication methods. This could potentially create an HTTP Parameter Pollution vulnerability if the reverse proxy is misconfigured, or due to a bug or oversight in Navidrome.

You should make sure that the authenticated user header is always set for requests against protected endpoints. As a rule of thumb, for an externalized authentication setup, the only endpoints that are not protected are /rest/* (depending on whether your proxy can handle the subsonic authentication scheme) and /share/*.

Transcoding configuration

To configure transcoding, Navidrome’s WebUI provide a screen that allows you to edit existing transcoding configurations and to add new ones. That is similar to other music servers available in the market that provide transcoding on-demand.

The issue with this is that it potentially allows an attacker to run any command in your server. This married with the fact that some Navidrome installations don’t use SSL and/or run it as a super-user (root or Administrator), is a recipe for disaster!

In an effort to make Navidrome as secure as possible, we decided to disable the transcoding configuration editing in the UI by default. If you need to edit it (add or change a configuration), start Navidrome with the ND_ENABLETRANSCODINGCONFIG set to true. After doing your changes, don’t forget to remove this option or set it to false.

Limit login attempts

To protect against brute-force attacks, Navidrome is configured by default with a login rate limiter, It uses a Sliding Window algorithm to block too many consecutive login attempts. It is enabled by default and you don’t need to do anything. The rate limiter can be fine tuned using the flags AuthRequestLimit and AuthWindowLength and can be disabled by setting AuthRequestLimit to 0, though it is not recommended.

3 - Anonymous Data Collection

Overview

Navidrome includes an anonymous usage statistics feature designed to help improve the project for all users. This page explains what data is collected, how it is used, and how to opt out if you prefer not to participate.

Key Principles

• Anonymous Data Only: Navidrome collects only non-personal, anonymous data to guide future improvements.
• What’s Collected: See Collected Data.
• What’s NOT Collected: No emails, IP addresses, usernames, or other identifiable data. See Excluded Data.
• Opt-Out Available: Enabled by default, but you can disable it anytime.
• In-House Data Handling: Collected data goes to an open-source server hosted by the project—no third-party services.
• Full Transparency: Logs and UI indicators show when data is sent and what it contains.

What Will Be Collected?

Below is a plain-English explanation of what each field is generally intended to represent. Each field corresponds to a piece of information about the running application or its environment:

Top-level Fields

• InsightsID: A unique, randomly generated identifier for a given Navidrome instance. It’s a random ID that allows reports from the same instance to be grouped together. It is NOT directly connected to any of your data, and it cannot be used to directly identify you or your instance.

• Version: Shows which Navidrome version each report came from. In aggregate analysis, this tells you how many users are on a particular version and can highlight upgrade patterns.

• Uptime: The amount of time an instance has been running. When aggregated, this helps gauge the overall stability and average runtime before restarts across the community.

Build Information

Information about custom builds. Aggregated, this can reveal common build configurations used by the community, and if there are any issues (e.g. performance impact or high memory usage) specific to certain build configurations.

• Build.Settings: Key-value pairs representing the compile-time settings for Navidrome (build tags, compiler options, etc.).

• Build.GoVersion: The version of Go used to compile Navidrome.

OS Information

• OS.Type: Operating system type (e.g., “linux”, “windows”, “darwin”). When aggregated, this shows the distribution of OS usage.

• OS.Distro: OS distribution name for Linux-based systems (e.g., “ubuntu”, “debian”). Useful in aggregate form to see which Linux distributions are most common.

• OS.Version: The version of the operating system or distribution. Aggregating these versions helps track environment trends and legacy OS usage.

• OS.Containerized: Whether Navidrome is running in a containerized environment (Docker, Kubernetes, etc..)

• OS.Arch: CPU architecture (e.g., “amd64”, “arm”). This allows to understand how Navidrome is typically deployed (e.g., on Raspberry Pis vs. standard x86 servers).

• OS.NumCPU: The number of logical CPUs available. Aggregated, it helps form a picture of typical hardware profiles used across deployments.

Memory Information

Aggregated memory usage helps analyze typical resource consumption patterns and, together with other metrics, help identify causes for memory leaks.

• Mem.Alloc: Current memory allocated by the Go runtime (in bytes).

• Mem.TotalAlloc: Memory allocated over the lifetime of the application.

• Mem.Sys: Total memory requested from the underlying system.

• Mem.NumGC: Number of completed garbage collection runs. Collected in aggregate, this shows a high-level overview of how Navidrome manages memory across various deployments.

File System Information

Each FS-related field captures information about the directories or storage mediums used by Navidrome. Aggregating this data can help understand how frequently different types of storage are configured and where media content is commonly stored. This information is just the type of the filesystem (ex: nfs, ext4, ntfs…) used for each type of storage, not the actual path.

• FS.Music: File system type for storing music files.

• FS.Data: File system type storing Navidrome’s database.

• FS.Cache: File system type storing cached data.

• FS.Backup: The file system type for backups.

Each of these includes Type, describing the kind of storage (e.g., local disk, network mount). Aggregating them shows how widely different storage setups are used, and their impact on performance.

Library Information

These fields represent aggregate counts of media items and user data within each instance’s library. Across many deployments, they help illustrate general usage trends of the Navidrome library functionality.

• Library.Tracks: Total number of songs (tracks).

• Library.Albums: Total number of albums.

• Library.Artists: Count of distinct artists.

• Library.Playlists: Number of playlists.

• Library.Shares: Number of shares (public links).

• Library.Radios: The count of radio station entries or streaming sources.

• Library.ActiveUsers: Number of currently active users in the last 7 days. This helps understand the average load the server is operating under.

• Library.ActivePlayers: Number of currently active players in the last 7 days. This allows to understand what are the most used players.

Configuration Settings

These are various Navidrome configuration flags and settings. In aggregate, they help show which features are commonly enabled or how the service is typically set up across the community. These are mostly boolean flags or simple settings, NO identifiable data is collected (paths, ids, tokens, etc..). For a reference of what each one represents, take a look at the configuration options page in the documentation.

• Config.LogLevel
• Config.LogFileConfigured
• Config.TLSConfigured
• Config.ScanSchedule
• Config.TranscodingCacheSize
• Config.ImageCacheSize
• Config.EnableArtworkPrecache
• Config.EnableDownloads
• Config.EnableSharing
• Config.EnableStarRating
• Config.EnableLastFM
• Config.EnableListenBrainz
• Config.EnableSpotify
• Config.EnableMediaFileCoverArt
• Config.EnableJukebox
• Config.EnablePrometheus
• Config.SessionTimeout
• Config.SearchFullString
• Config.RecentlyAddedByModTime
• Config.PreferSortTags
• Config.BackupSchedule
• Config.BackupCount
• Config.DefaultBackgroundURL
• Config.DevActivityPanel
• Config.EnableCoverAnimation

In Summary:
When gathered from many Navidrome instances, these metrics and settings are invaluable in understanding the aggregate patterns of usage, deployment environments, media collections, and configuration preferences. This aggregated data is not intended for diagnosing single-instance issues; rather, it provides a high-level view of how Navidrome is deployed and used by its community overall.

Here’s a sample of the data sent: https://gist.github.com/deluan/1c8944fb92329c1658d96bb72a8e8db4

Data Retention

• Sent daily
• Retained for 30 days, then permanently deleted.

What Will NOT Be Collected?

To protect your privacy, the following will not be collected:

• No Personal Information: No emails, usernames, or anything identifiable.
• No Network Information: No IP addresses or device fingerprints.
• No Detailed Playback History: Individual song plays are not tied to specific users.
• No Library Details: Song/artist/album/playlist names are excluded.
• No Sensitive Configuration Data: Passwords, tokens, or logs with personal info are never collected.

Why Collect This Data?

Collecting anonymous usage statistics helps:

• Identify popular platforms and configurations.
• Prioritize features and fixes based on usage patterns.
• Ensure updates don’t unintentionally disrupt the majority of users.

Privacy and Transparency

Transparency Measures

1. Human-Readable Documentation: This page explains all details in a clear, accessible way.
2. Log Transparency: Each data submission logs:
   • The exact payload sent.
   • The destination URL. Example:

   Sent Insights data (for details see http://navidrome.org/docs/getting-started/insights  data="{\"id\":\"4c457065-101a-435a-b158-244b573579cd\",\"version\":\"0.53.3-SNAPSHOT (7f47e0a53)\",\"uptime\":0,\"build\":{\"settings\":{\"-buildmode\":\"exe\",\"-compiler\":\"gc\",\"-ldflags\":\"-extldflags '-static -latomic' -w -s         -X github.com/navidrome/navidrome/consts.gitSha=7f47e0a53         -X github.com/navidrome/navidrome/consts.gitTag=v0.53.3-SNAPSHOT\",\"-tags\":\"netgo\",\"CGO_ENABLED\":\"1\",\"GOAMD64\":\"v1\",\"GOARCH\":\"amd64\",\"GOOS\":\"linux\",\"vcs\":\"git\",\"vcs.modified\":\"true\",\"vcs.revision\":\"7f47e0a5373d1ea067de8929c828ee0cd85a0795\",\"vcs.time\":\"2024-12-15T02:01:46Z\"},\"goVersion\":\"go1.23.4\"},\"os\":{\"type\":\"linux\",\"distro\":\"qts\",\"version\":\"5.2.2\",\"arch\":\"amd64\",\"numCPU\":4},\"mem\":{\"alloc\":2750544,\"totalAlloc\":9076584,\"sys\":14243080,\"numGC\":4},\"fs\":{\"music\":{\"type\":\"ext2/ext3/ext4\"},\"data\":{\"type\":\"ext2/ext3/ext4\"},\"cache\":{\"type\":\"ext2/ext3/ext4\"},\"backup\":{\"type\":\"ext2/ext3/ext4\"}},\"library\":{\"tracks\":85200,\"albums\":6255,\"artists\":1319,\"playlists\":26,\"shares\":19,\"radios\":7,\"activeUsers\":1},\"config\":{\"logLevel\":\"debug\",\"transcodingCacheSize\":\"100GB\",\"imageCacheSize\":\"50GB\",\"enableArtworkPrecache\":true,\"enableDownloads\":true,\"enableSharing\":true,\"enableStarRating\":true,\"enableLastFM\":true,\"enableListenBrainz\":true,\"enableMediaFileCoverArt\":true,\"enableSpotify\":true,\"enableCoverAnimation\":true,\"sessionTimeout\":\"168h0m0s\",\"recentlyAddedByModTime\":true,\"backupSchedule\":\"5 4 * * *\",\"backupCount\":5,\"devActivityPanel\":true,\"defaultBackgroundURL\":true}}" server="https://insights.navidrome.org/collect" status="200 OK"
   

3. UI Indicator: You will be able to see the last submission date/time in the About dialog:

   

How to Opt-Out

Data collection is enabled by default, but you can disable it anytime, by setting the new config option EnableInsightsCollector (or ND_ENABLEINSIGHTSCOLLECTOR env var) to false. If you have EnableExternalServices set to false, it will also disable the insights collection.

Detailed instructions will be provided in the release notes.

Data Collection Server

The data collection server is open-source and hosted by the Navidrome project, ensuring secure, in-house handling. Check it out: Navidrome Insights Server.

Thank You for Your Support

By allowing anonymous usage statistics, you’re contributing to the future of Navidrome. Your trust is invaluable, and if you’re uncomfortable, you can always opt out—no questions asked.

For questions or concerns, feel free to reach out via:

• Discord
• GitHub Discussions
• Reddit

Thank you for being part of the Navidrome community!

Deluan
Navidrome Developer