MongoDB on FreeBSD: NoSQL Database Review

MongoDB is a document-oriented NoSQL database that stores data as JSON-like documents (BSON) instead of rows and columns. It is one of the most popular databases in the world, widely used for web applications, content management, real-time analytics, and IoT data. On FreeBSD, MongoDB has a complicated history -- official support was dropped and then community-maintained ports filled the gap. This review covers the current state of MongoDB on FreeBSD, installation options, WiredTiger storage engine configuration, replication and sharding, FreeBSD-specific tuning, and the practical considerations for running MongoDB in production on FreeBSD.

MongoDB on FreeBSD: Current Status

MongoDB Inc. officially dropped FreeBSD as a supported platform starting with MongoDB 4.x. The company builds and tests binaries only for Linux, macOS, and Windows. However, MongoDB is open source (Server Side Public License), and the FreeBSD community maintains a port that compiles MongoDB from source for FreeBSD.

The practical implication is that MongoDB on FreeBSD works but comes without vendor support. If you need vendor-backed support, you must run MongoDB on Linux -- potentially in a bhyve VM or Linux jail on your FreeBSD host. If community support and your own operational expertise are sufficient, the FreeBSD port is functional and actively maintained.

Check port availability:

sh
pkg search mongodb

The available versions depend on the current ports tree. As of 2026, MongoDB 7.x and 8.x ports are maintained by the FreeBSD community.

Installation on FreeBSD

Binary Package

sh
pkg install mongodb80

This installs the MongoDB server (mongod), the MongoDB shell (mongosh), and the rc.d service script.

Enable MongoDB:

sh
sysrc mongod_enable="YES"

Ports Installation

For custom build options or the latest version:

sh
cd /usr/ports/databases/mongodb80
make install clean

The ports build takes significant time due to MongoDB's large C++ codebase. Expect 30-60 minutes on modern hardware. If you need a faster path, use the binary package.

Initial Configuration

The default configuration file is at /usr/local/etc/mongodb.conf. Create a minimal production configuration:

sh
cat > /usr/local/etc/mongodb.conf << 'EOF'
storage:
  dbPath: /var/db/mongodb
  journal:
    enabled: true
  wiredTiger:
    engineConfig:
      cacheSizeGB: 2

systemLog:
  destination: file
  path: /var/log/mongodb/mongod.log
  logAppend: true

net:
  bindIp: 127.0.0.1
  port: 27017

security:
  authorization: enabled

processManagement:
  fork: false
  pidFilePath: /var/run/mongodb/mongod.pid
EOF

Create required directories:

sh
mkdir -p /var/db/mongodb /var/log/mongodb /var/run/mongodb
chown mongodb:mongodb /var/db/mongodb /var/log/mongodb /var/run/mongodb

Start MongoDB:

sh
service mongod start

Initial Authentication Setup

Connect to the shell and create an admin user:

sh
mongosh --port 27017 << 'EOF'
use admin
db.createUser({
  user: "admin",
  pwd: "your-secure-password",
  roles: [
    { role: "userAdminAnyDatabase", db: "admin" },
    { role: "readWriteAnyDatabase", db: "admin" },
    { role: "dbAdminAnyDatabase", db: "admin" },
    { role: "clusterAdmin", db: "admin" }
  ]
})
EOF

After creating the admin user and enabling authorization in the config, all connections must authenticate:

sh
mongosh --port 27017 -u admin -p --authenticationDatabase admin

WiredTiger Storage Engine

WiredTiger is MongoDB's default and only production storage engine since MongoDB 4.2. It provides document-level concurrency control, compression, and a write-ahead log for crash recovery.

Cache Configuration

WiredTiger's internal cache is the primary performance lever. By default, it uses 50% of available RAM minus 1 GB. On a dedicated FreeBSD database server with 16 GB of RAM, the default cache is approximately 7 GB.

Set the cache size explicitly for shared servers:

sh
storage:
  wiredTiger:
    engineConfig:
      cacheSizeGB: 4

On FreeBSD, ensure the WiredTiger cache plus other system memory demands do not exceed physical RAM. ZFS ARC also competes for memory -- if you run MongoDB on ZFS, you need to budget RAM between WiredTiger cache and ARC.

Limit ARC to leave room for WiredTiger:

sh
# In /boot/loader.conf
vfs.zfs.arc_max="4294967296"

This caps ARC at 4 GB, leaving the rest for WiredTiger and the operating system on a 16 GB server.

Compression

WiredTiger compresses data and indexes by default:

Collection data: snappy compression (fast, moderate ratio)
Index prefixes: prefix compression enabled by default
Journal: snappy compression

For better compression at the cost of CPU:

sh
storage:
  wiredTiger:
    collectionConfig:
      blockCompressor: zstd

Zstd provides significantly better compression ratios than snappy with acceptable CPU overhead on modern hardware. On FreeBSD systems with fast CPUs and constrained storage, switching to zstd can reduce disk usage by 30-50% compared to snappy.

Journaling

The WiredTiger journal ensures crash recovery. It writes all modifications to a journal before applying them to data files. The journal is flushed every 50 milliseconds by default.

Check journal status:

sh
mongosh --eval "db.serverStatus().wiredTiger.log"

Do not disable journaling in production. The risk of data loss on unexpected shutdown is not worth the marginal performance gain.

Replication

MongoDB's replica sets provide high availability and data redundancy. A replica set consists of a primary node that accepts writes and secondary nodes that replicate the primary's data.

Configuring a Replica Set on FreeBSD

On each FreeBSD server, add the replica set name to the configuration:

sh
replication:
  replSetName: "rs0"

Restart MongoDB on all nodes, then initiate the replica set from the primary:

sh
mongosh --port 27017 << 'EOF'
rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1.example.com:27017" },
    { _id: 1, host: "mongo2.example.com:27017" },
    { _id: 2, host: "mongo3.example.com:27017" }
  ]
})
EOF

Check replica set status:

sh
mongosh --eval "rs.status()"

Read Preference

By default, all reads go to the primary. For read-heavy workloads, distribute reads across secondaries:

sh
mongosh --eval 'db.getMongo().setReadPref("secondaryPreferred")'

Read preferences:

primary -- all reads from primary (default, strongest consistency).
primaryPreferred -- reads from primary if available, secondary otherwise.
secondary -- all reads from secondaries.
secondaryPreferred -- reads from secondaries if available, primary otherwise.
nearest -- reads from the node with lowest network latency.

Sharding

Sharding distributes data across multiple servers for horizontal scaling. Each shard is a replica set, and a config server replica set stores the cluster metadata.

Shard Architecture on FreeBSD

A minimal sharded cluster requires:

2+ shard replica sets (3 nodes each recommended)
1 config server replica set (3 nodes)
1+ mongos routers (query routers, stateless)

Start a mongos router on FreeBSD:

sh
mongos --configdb configReplSet/config1:27019,config2:27019,config3:27019 \
       --bind_ip 0.0.0.0 --port 27017

Add shards through the mongos:

sh
mongosh --port 27017 << 'EOF'
sh.addShard("shard1/mongo1a:27018,mongo1b:27018,mongo1c:27018")
sh.addShard("shard2/mongo2a:27018,mongo2b:27018,mongo2c:27018")
EOF

Enable sharding on a database and collection:

sh
mongosh --port 27017 << 'EOF'
sh.enableSharding("myapp")
sh.shardCollection("myapp.events", { "timestamp": "hashed" })
EOF

Shard Key Selection

The shard key determines how data is distributed. Poor shard key choices cause uneven distribution (hot spots). Good shard keys have:

High cardinality -- many distinct values.
Even distribution -- values spread uniformly.
Query isolation -- common queries target a single shard.

Hashed shard keys provide even distribution but sacrifice range query efficiency. Range-based shard keys support range queries but may create hot spots if the key is monotonically increasing (like timestamps).

FreeBSD-Specific Tuning

File Descriptor Limits

MongoDB opens many file descriptors for connections and data files. Increase the limits:

sh
# In /etc/sysctl.conf
kern.maxfiles=65536
kern.maxfilesperproc=32768

In /etc/login.conf, add or modify the mongodb class:

sh
mongodb:\
    :openfiles=32768:\
    :tc=daemon:

Rebuild the login database:

sh
cap_mkdb /etc/login.conf

Memory Mapping

MongoDB's WiredTiger engine uses memory-mapped files internally. Ensure adequate virtual memory space:

sh
# Check current limits
sysctl vm.max_proc_mmap

ZFS Considerations

Running MongoDB on ZFS requires careful tuning to avoid double caching and write amplification.

Set the ZFS recordsize to match MongoDB's default block size:

sh
zfs create -o recordsize=64k tank/mongodb
zfs set atime=off tank/mongodb
zfs set compression=lz4 tank/mongodb

The 64 KB recordsize aligns with WiredTiger's block allocation patterns. Disabling atime reduces unnecessary metadata updates. LZ4 compression is lightweight and complements WiredTiger's own compression.

Consider placing the journal on a separate, low-latency dataset:

sh
zfs create -o recordsize=128k -o logbias=throughput tank/mongodb-journal

Network Tuning

For replica sets and sharded clusters, tune the network stack:

sh
# In /etc/sysctl.conf
net.inet.tcp.sendspace=262144
net.inet.tcp.recvspace=262144
kern.ipc.maxsockbuf=8388608

Monitoring

Built-in Tools

Check server status:

sh
mongosh --eval "db.serverStatus()" --quiet

Monitor operations in real time:

sh
mongosh --eval "db.currentOp()"

Database statistics:

sh
mongosh --eval "db.stats()"
mongosh --eval "db.collection.stats()"

mongostat and mongotop

These command-line tools provide real-time monitoring:

sh
mongostat --host 127.0.0.1 --port 27017
mongotop --host 127.0.0.1 --port 27017

mongostat shows insert/query/update/delete rates, replication lag, and connection counts. mongotop shows which collections consume the most read and write time.

Profiler

Enable the profiler to log slow queries:

sh
mongosh --eval "db.setProfilingLevel(1, { slowms: 100 })"

Review slow queries:

sh
mongosh --eval "db.system.profile.find().sort({ ts: -1 }).limit(5).pretty()"

Backup Strategies

mongodump

The traditional backup tool:

sh
mongodump --host 127.0.0.1 --port 27017 --out /var/backups/mongodb/$(date +%Y%m%d)

Restore from a backup:

sh
mongorestore --host 127.0.0.1 --port 27017 /var/backups/mongodb/20260409/

ZFS Snapshots

On FreeBSD with ZFS, snapshots provide near-instant, consistent backups:

sh
# Lock writes temporarily for consistency
mongosh --eval "db.fsyncLock()"

# Take the snapshot
zfs snapshot tank/mongodb@backup-$(date +%Y%m%d)

# Unlock writes
mongosh --eval "db.fsyncUnlock()"

The fsyncLock/snapshot/fsyncUnlock sequence takes seconds regardless of database size. This is faster than mongodump for large databases.

Limitations on FreeBSD

No official support -- MongoDB Inc. does not support FreeBSD. You rely on community ports and your own expertise.
Build complexity -- compiling from ports is slow and occasionally breaks when FreeBSD or MongoDB updates introduce incompatibilities.
No official packages -- no MongoDB Atlas, no official RPM/DEB equivalent. Everything comes through FreeBSD ports.
Performance monitoring -- some MongoDB monitoring tools assume Linux and may not work correctly on FreeBSD (e.g., system metrics collection for percona monitoring).
Kernel tuning -- MongoDB documentation focuses on Linux kernel parameters. Translating to FreeBSD equivalents requires FreeBSD expertise.

Verdict

MongoDB on FreeBSD is a viable option for teams with FreeBSD operational expertise who understand the trade-offs. The database itself works well -- WiredTiger is a solid storage engine, replication and sharding are mature, and the document model is genuinely useful for many application patterns. The challenge is the lack of official vendor support, which means you own the entire stack from compilation to production monitoring.

For new FreeBSD deployments where a document database is needed, consider whether your requirements truly need MongoDB's specific features (ad-hoc queries on document structure, aggregation pipeline, change streams) or whether PostgreSQL's JSONB support would suffice. PostgreSQL on FreeBSD is a first-class citizen with full vendor and community support. For applications that specifically require MongoDB -- existing codebases, driver compatibility, specific features like the aggregation framework or change streams -- the FreeBSD port delivers a working installation with respectable performance.

Frequently Asked Questions

Is MongoDB officially supported on FreeBSD?

No. MongoDB Inc. dropped official FreeBSD support starting with MongoDB 4.x. The FreeBSD ports collection maintains community-built packages. These work but come without vendor support or guarantees.

Can I run MongoDB in a FreeBSD jail?

Yes, with caveats. MongoDB requires adequate file descriptor limits and memory-mapped file support within the jail. Configure the jail with allow.mmap=1 and set appropriate resource limits. Some users prefer running MongoDB in a bhyve VM with Linux for cleaner support boundaries.

How much RAM does MongoDB need on FreeBSD?

WiredTiger's cache defaults to 50% of RAM minus 1 GB. A minimum of 4 GB RAM is recommended for development and 8-16 GB for production. On systems shared with ZFS, carefully partition RAM between WiredTiger cache and ZFS ARC.

Should I use ZFS or UFS for MongoDB data on FreeBSD?

ZFS is recommended for its snapshot capabilities and compression. Set recordsize=64k, disable atime, and enable lz4 compression on the MongoDB dataset. Budget RAM carefully between ZFS ARC and WiredTiger cache.

Can MongoDB replace PostgreSQL for my FreeBSD application?

It depends. MongoDB excels at flexible schema, document storage, and horizontal scaling via sharding. PostgreSQL excels at relational integrity, complex queries, and SQL standard compliance. If your data is naturally document-shaped and your queries are mostly by document fields, MongoDB fits well. If you need joins, transactions across collections (though MongoDB now supports multi-document transactions), or complex reporting, PostgreSQL is the better choice.

How do I upgrade MongoDB on FreeBSD?

Upgrade through the ports tree or pkg. Always read the MongoDB release notes for breaking changes before upgrading. Back up your data with mongodump or ZFS snapshots before any upgrade. MongoDB supports rolling upgrades for replica sets -- upgrade secondaries first, then step down and upgrade the primary.