UniFi OS Consoles Wi-Fi Switching Camera Security Phone System Door Access Accessories UISP
Support Resources
Store
Support Resources
UniFi OS Consoles Wi-Fi Switching Camera Security Phone System Door Access Accessories UISP Store

UniFi - Repairing Database Issues on the UniFi Network Application

Overview

After reading through this article readers should expect to have a cursory knowledge about how to identify database issues on the UniFi Network application.

NOTES & REQUIREMENTS: This article includes instructions that require the use of an SSH client such as PuTTY, or native Linux/macOS terminals.

Table of Contents

  1. Introduction and Symptoms
  2. Repairing a Database on Cloud Key
  3. Repairing a Database on Debian-based Linux
  4. Repairing a Database on macOS
  5. Repairing a Database on Windows
  6. Migrating from MMAPv1 to WiredTiger
  7. Related Articles

Introduction and Symptoms

Back to Top

What to look for:

  • Statistics not reporting within the data retention period. Typically the statistics will only record for a few days and then be cut off or intermittent.
  • Not being able to make a backup that includes statistics (7-day, 30-day, etc).
  • If the settings-only backup cannot complete, it may be corruption in the ace database or something else unrelated.
  • Receiving an error 400 when trying to open the UniFi Network application.
  • Network application service not starting due to database errors.
User Tip:
Total data doesn't have to exceed 2GB on the UC-CK, it only needs to be big enough for Mongo to expand. On 64-bit machines not affected by the MongoDB limitation, there can also be overall space issues on the host that can cause issues when trying to repair the database. Check this with df -h in an SSH session to see if the partition where UniFi is storing data is running short on space.

32-bit MongoDB Limitations

32-bit MongoDB collections are limited to a total size of 2GB. While running the MMAPv1 storage engine this can cause issues when trying to shrink the aggregate collection sizes. When running a compact command on the MongoDB, the database is rewritten and defragmented without error correction. This process does not return useable disk space to the UniFi OS Console (or other Network application host) when the storage engine is MMAPv1.

Getting back that valuable disk space on a 32-bit MongoDB instance will require a repair of the database. This repair may be needed for those who are suspecting invalid entries, corruption, or collection scaling issues. To be able to run a database repair, the Cloud Key will have to have enough free disk space equal to the size of the current data set plus 2 gigabytes. If the dataset has already grown too large to proceed with the db.repairDatabase() command there are instructions below to work around that.

NOTE: TheUniFi Cloud Key (UC-CK) utilizes the following:
  • 32-Bit architecture
  • MMAPv1
  • MongoDB Version 2.4.10

How to Repair a Database on Cloud Key

Back to Top

1. Download the mongo pruning script. As written, the script will only keep entries from the past 7 days. It will not remove entries that are required for UniFi administration. Do so by running the following command:

cd /tmp/
wget https://help.ui.com/hc/en-us/article_attachments/360008640574/CK_repair.js

2. Stop the UniFi service

service unifi stop

3. The UniFi service will shut down the mongo process. Make sure that the UniFi service has been completely shut down. Repair the database to compact the data entries and free unused disk space field that is included in the query criteria.

mongod --dbpath /usr/lib/unifi/data/db --smallfiles --logpath /usr/lib/unifi/logs/server.log --repair
NOTE:Steps 4-7 are optional if you need to prune back the database to conserve disk space.

4. Restart mongo with this command:

mongod --dbpath /usr/lib/unifi/data/db --smallfiles --logpath /usr/lib/unifi/logs/server.log --journal --fork
NOTE:Journaling may not be have been enabled in your mongo database. If so, then remove the --journal option in the above command.

5. Execute the script to prune the stat collections that are causing the problem:

mongo < /tmp/CK_repair.js

6. Shut down the mongo server with this command:

mongod --dbpath /usr/lib/unifi/data/db --smallfiles --logpath /usr/lib/unifi/logs/server.log --shutdown
NOTE:The last command in the CK_repair.js script is "db.repairDatabase()". It may result in an error if the stats collections have already grown too large to be repaired while the mongo server is running. If you see such an error running the script then you will need to repair the database from the command line once again by running the command in step 3.

7. Finally, restart the UniFi service:

service unifi start

The Cloud Key should now be able to run the Network application. If you still have database issues please contact Ubiquiti Support. 

How to Repair a Database on Debian-based Linux

1. Stop the UniFi service

service unifi stop

2. In some cases, where the journal is corrupted, it will be helpful to run the following command before repairing the database, to move it to another location:

mv -vi /usr/lib/unifi/data/db/journal /usr/lib/unifi/data/db/journal-$(date -I)

3. Repair the database with this command:

mongod --dbpath /usr/lib/unifi/data/db --smallfiles --logpath /usr/lib/unifi/logs/server.log --repair

4. Finally, restart the UniFi service:

service unifi start
NOTE:If this process was performed as root the file ownership may have changed. This can be changed with:
chown -R unifi:unifi /usr/lib/unifi/data/db/
chown -R unifi:unifi /usr/lib/unifi/logs/server.log

If you still have suspected database issues please contact Ubiquiti Support.

How to Repair a Database on macOS

1. Working Directory: Create a temporary working directory. For repair purposes, we will call this directory /repair. In terminal:

mkdir ~/repair

2. Download MongoDB: The macOS UniFi installer does not include the mongo binary. Visit the MongoDB official download website, and download the .tgz release that corresponds to your server's CPU architecture. You can also download 2.4.14 here directly: 2.4.14.tgz. 

3. Extract Mongo: Move the downloaded package to your working directory, and extract it by double-clicking it or using the application of your choice.

4. Move Mongo to Working Directory: Locate the bin/mongo binary file, and copy it to your working directory.  At this point, the downloaded .tgz package and any extra extracted files can be deleted as we only need the mongo binary.

5. Terminal and commands: Open Terminal and move to your working directory

cd ~/repair

6. Close/Stop UniFi.

7. Repair the Mongo Database:

mongod --dbpath ~/Library/Application\ Support/UniFi/data/db --smallfiles --logpath ~/Library/Application\ Support/UniFi/logs/server.log --repair

8. Open the UniFi application from Finder:

open -n /Applications/UniFi.app

If you still have suspected database issues please contact Ubiquiti Support. 

How to Repair a Database on Windows

1. Download MongoDB: The Windows UniFi installer does not include the mongo binary. Visit the MongoDB official download website, and download the .zip release that corresponds to your CPU architecture.
NOTE: The recommended MongoDB version is 3.4.x. You can download 3.4.23 directly here: 3.4.23.zip.

2. Extract Mongod.exe

Extract \bin\mongod.exe to a working directory of your choice.  In this example, we will use C:\repair\ You may ignore all other files included in the .zip.

3. Close/Stop UniFi

4. Open Command Prompt: Open the command prompt by pressing WINDOWS + R.  In the popup, type cmd, and press ENTER.

5. Enter Working Directory

cd C:\repair\

6. Close/Stop UniFi.

7. Repair the Mongo Database 

mongod.exe --dbpath "%userprofile%\Ubiquiti UniFi\data\db" --smallfiles --logpath "%programfiles%\Ubiquiti UniFi\logs\server.log" –repair

8. Open the UniFi application

If you still have suspected database issues please contact Ubiquiti Support. 

How to Migrate from MMAPv1 to WiredTiger

ATTENTION: This section does not apply to 32-bit architecture hosts including the UC-CK G1.

After the Network application is functional again a user may wish to migrate it to the WiredTiger storage engine.

To verify how much space is used, run the following command:

du -shc /usr/lib/unifi/data/db/ace* /usr/lib/unifi/data/db/journal/* /usr/lib/unifi/data/db/local* | grep total

To verify which MongoDB version is being used, run the following:

mongod --version | grep "db version"

To verify what storage engine version is being used, run the following two commands:

mongo localhost:27117
db.serverStatus().storageEngine.name

How to migrate to WiredTiger

1. Create a backup under Settings > Maintenance > Backup with the desired retention settings.

2. Uninstall UniFi from Windows or macOS. Purge UniFi from Debian-based Linux with the command:

sudo dpkg -P unifi

3. Reinstall UniFi on Windows or macOS. Reinstall UniFi on Debian-based Linux with the commands:

cd /tmp/
wget <https link to download>
sudo dpkg -i unifi_sysvinit_all.deb

4. In the UniFi Setup Wizard restore the backup from step 1.

Related Articles

Back to Top

UniFi - How to Remove (Prune) Older Data and Adjust Mongo Database Size

UniFi - Troubleshooting Offline Cloud Key and Other Stability Issues

Was this article helpful?
67 out of 203 found this helpful