MooseFS on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of MooseFS on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. MooseFS is an open source, POSIX compliant distributed file system. It spreads files across a cluster of chunkservers, so a MooseFS volume behaves like an ordinary directory on every client while the data underneath is distributed and, once you add chunkservers, replicated.

The image ships MooseFS 4 Community Edition installed from the official MooseFS repository. A master server, one chunkserver, and the MooseFS FUSE client all run on this single virtual machine, and the filesystem is mounted and ready at /srv/moosefs the moment first boot completes. You can write to it, read from it, and watch the chunks appear in the web monitor without configuring anything.

Single node by design

This image is a single node starter cluster, not a redundant one. One virtual machine runs one chunkserver, so there is exactly one copy of every chunk and no fault tolerance: if this virtual machine or its data disk is lost, the data is lost. That is a deliberate, self contained starting point for evaluation, development, and learning MooseFS.

Real fault tolerance comes from adding chunkservers on separate machines and raising the storage goal. Step 7 walks through exactly how to do that. Until you do, treat this virtual machine like any other single disk server and back it up accordingly.

Security model

Everything that speaks the MooseFS protocol is kept off the network:

• The client control port (9421), which is what grants access to the filesystem, and the metalogger port (9419) are bound to 127.0.0.1.
• The web monitor (9425) is bound to 127.0.0.1 and published only through nginx.
• MooseFS refuses a loopback address for the chunkserver to master link, so the chunkserver ports (9420 and 9422) bind the virtual machine's private address. An nftables table then drops ports 9419 to 9425 on every non loopback interface, so the whole MooseFS protocol surface is unreachable from off the machine regardless of how your network security group is configured.
• mfsexports.cfg permits mounts only from 127.0.0.1/32.

The only published endpoints are TCP 443 (the web monitor, TLS with HTTP Basic Auth) and TCP 80 (a redirect to HTTPS).

On every fresh customer virtual machine, moosefs-firstboot.service generates a per virtual machine web monitor password and a TLS certificate bound to the machine, then records them to /root/moosefs-credentials.txt (mode 0600, root only). The captured image ships an empty password file, so no two virtual machines share credentials and there is no default login at any point.

What is included:

• MooseFS 4 Community Edition: master, chunkserver, CLI tools, and the FUSE client

• moosefs-master, moosefs-chunkserver, moosefs-gui, and moosefs-mount systemd units auto-starting on boot

• A dedicated 40 GiB data volume mounted at /var/lib/mfs holding both the master metadata and the chunk storage

• The MooseFS filesystem mounted at /srv/moosefs

• nginx TLS front publishing the web monitor on :443 with HTTP Basic Auth, and :80 redirecting to HTTPS

• An nftables guard restricting every MooseFS port to this machine

• Ubuntu 24.04 LTS base with latest security patches applied at build time

• Azure Linux Agent for seamless cloud integration and SSH key injection

• 24/7 cloudimg support with guaranteed 24 hour response SLA

Prerequisites

• An active Azure subscription

• A subscription to the MooseFS on Ubuntu 24.04 listing on Azure Marketplace

• An SSH public key for VM authentication

• A virtual network and subnet in the target region

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM) for evaluation and small workloads. The MooseFS master keeps its entire metadata set in RAM, so size the machine by file count rather than by capacity: budget roughly 300 bytes of master RAM per file. Production deployments should use Standard_D2s_v3 or larger and attach additional data disks for chunk storage.

Step 1: Deploy from the Azure Portal

Navigate to Marketplace in the Azure Portal, search for MooseFS, select the cloudimg publisher entry, and click Create.

On the Networking tab attach a network security group that allows inbound TCP 22 from your management IP range and TCP 443 (the web monitor) from your admin networks. You do not need to open any MooseFS protocol port: they are bound to loopback or firewalled to this machine.

Click Review + create, wait for validation, then Create. Deployment takes around two minutes.

Step 2: Connect and confirm the services are running

Connect over SSH using the key you supplied at deployment:

ssh azureuser@<vm-ip>

Confirm every MooseFS component and the TLS front are active:

sudo systemctl is-active moosefs-master moosefs-chunkserver moosefs-gui moosefs-mount nginx

Expected output — five lines, all active:

active
active
active
active
active

Confirm the listening sockets. The client control port and the web monitor are on loopback; only nginx is published:

sudo ss -H -lnt "( sport = :9421 or sport = :9425 or sport = :443 )" | awk '{print $4}'

Expected output:

127.0.0.1:9421
127.0.0.1:9425
0.0.0.0:443

Step 3: Retrieve the per-VM monitor credentials

The web monitor password is generated on this virtual machine at first boot and written to a root-only file:

sudo ls -l /root/moosefs-credentials.txt

Expected output — mode 0600, owned by root:

-rw------- 1 root root 1322 Jul 19 23:34 /root/moosefs-credentials.txt

View the credential keys (the file also records the monitor URL and the mount point):

sudo grep -o '^[A-Z_]*=' /root/moosefs-credentials.txt

Expected output:

GUI_USER=
GUI_PASSWORD=
MOOSEFS_MONITOR_URL=
MOOSEFS_MOUNT_POINT=

Read the full file when you need the actual values:

sudo cat /root/moosefs-credentials.txt

Confirm the MooseFS version:

sudo mfsmaster -v

Expected output:

version: 4.59.2-1 ; build: 2106

Note on the monitor URL. Azure Instance Metadata returns an empty public-IP field for Standard SKU addresses, so MOOSEFS_MONITOR_URL may show this machine's private address. If you are connecting from outside the virtual network, substitute the public IP shown on the virtual machine's Overview blade in the Azure portal. The monitor is served on port 443 either way.

Step 4: Use the filesystem

The MooseFS volume is already mounted. Confirm it is a genuine MooseFS mount rather than an ordinary directory — the source is mfs# followed by the master address:

findmnt -no SOURCE,FSTYPE,TARGET /srv/moosefs

Expected output:

mfs#127.0.0.1:9421 fuse   /srv/moosefs

Write a file and read it back, verifying the content survived the round trip byte for byte:

sudo mkdir -p /srv/moosefs/demo
head -c 4194304 /dev/urandom > ~/demo.bin
sudo cp ~/demo.bin /srv/moosefs/demo/demo.bin
sync
sudo sha256sum ~/demo.bin /srv/moosefs/demo/demo.bin

Expected output — the two checksums are identical:

369cd7031892eabed30550a0e2c5c979d660fbbbda357fa223209246f5949851  /home/azureuser/demo.bin
369cd7031892eabed30550a0e2c5c979d660fbbbda357fa223209246f5949851  /srv/moosefs/demo/demo.bin

Confirm the data really is stored as MooseFS chunks, and see which chunkserver holds each copy:

sudo mfsfileinfo /srv/moosefs/demo/demo.bin

Expected output:

/srv/moosefs/demo/demo.bin:
    chunk 0: 000000000000000F_00000001 / (id:15 ver:1) ; mtime:1784504501 (2026-07-19 23:41:41)
        copy 1: 10.0.0.28:9422 ; status:VALID

copy 1 is the single copy of this chunk on the single chunkserver. On a multi-node cluster you would see copy 2, copy 3 and so on.

Step 5: Inspect the cluster from the command line

List the registered chunkservers:

sudo mfscli -H 127.0.0.1 -SCS

Confirm the capacity of the MooseFS volume and of the dedicated data disk beneath it:

df -h /srv/moosefs /var/lib/mfs

Expected output:

Filesystem          Size  Used Avail Use% Mounted on
mfs#127.0.0.1:9421   38G  302M   37G   1% /srv/moosefs
/dev/sda             40G   46M   38G   1% /var/lib/mfs

The chunks themselves live on the dedicated data volume:

sudo find /var/lib/mfs/chunks -name 'chunk_*.mfs' -type f > ~/mfs-chunks.txt
head -3 ~/mfs-chunks.txt

Step 6: Open the web monitor

Browse to https://<vm-ip>/ and sign in with the GUI_USER and GUI_PASSWORD values from /root/moosefs-credentials.txt. The certificate is self-signed and bound to this virtual machine, so your browser will warn on the first visit.

Verify from the command line that the monitor refuses anonymous access and accepts the per-VM credential:

curl -k -s -o /dev/null -w 'anonymous: %{http_code}\n' https://127.0.0.1/
curl -k -s -o /dev/null -w 'authenticated: %{http_code}\n' -u '<GUI_USER>:<GUI_PASSWORD>' https://127.0.0.1/mfs.cgi

Expected output:

anonymous: 401
authenticated: 200

The Info tab shows the cluster summary: master version and state, total and available space, and the file and chunk counts.

Why the chunk matrix shows chunks as "endangered". On the Info tab the redundancy matrix reports every chunk at redundancy level 0 and colours the count orange. This is correct and expected on a single node cluster: with one chunkserver there is exactly one copy of each chunk, so MooseFS is telling you truthfully that no chunk could survive losing that server. The indicator turns green once you add a second chunkserver and raise the goal, as described in Step 7.

The Chunkservers tab lists each registered chunkserver with its address, version, chunk count, and used and total space.

The Disks tab shows the individual storage directories behind each chunkserver — here the chunk directory on the dedicated data volume, with its chunk count, error status, and capacity.

The Exports tab shows which clients may mount the filesystem. Both entries are restricted to 127.0.0.1, which is the loopback-only export policy this image ships with.

Step 7: Growing into a real cluster

To get genuine fault tolerance you need chunkservers on separate virtual machines, so that losing one machine cannot lose the only copy of a chunk. The outline below is the standard MooseFS procedure; apply your own network and security review before using it in production.

On this master virtual machine, allow the new chunkserver's private address through the nftables guard:

sudo nft insert rule inet cloudimg_moosefs input ip saddr <chunkserver-private-ip> tcp dport 9420 accept

Persist that rule by adding it to /etc/nftables.d/moosefs.nft above the drop rule, and allow TCP 9420 from the new machine in your Azure network security group.

On each new virtual machine, install the chunkserver from the same official repository, point MASTER_HOST in /etc/mfs/mfschunkserver.cfg at this master's private address, list its storage directories in /etc/mfs/mfshdd.cfg, then start moosefs-chunkserver.

Once the new chunkservers appear on the Chunkservers tab, raise the storage goal so MooseFS keeps more than one copy of each chunk:

sudo mfssetgoal -r 2 /srv/moosefs

MooseFS then replicates existing chunks in the background until every chunk meets the new goal, and the redundancy matrix on the Info tab turns green.

To mount the filesystem from other machines you must also widen the export list. Add an entry to /etc/mfs/mfsexports.cfg scoped to the specific client network and protected with a password, then widen MATOCL_LISTEN_HOST in /etc/mfs/mfsmaster.cfg from 127.0.0.1 to the private address and open port 9421 to those clients only:

10.0.0.0/24   /   rw,alldirs,maproot=0,password=<your-secret>

Reload the master to apply export changes:

sudo mfsmaster reload

Do not widen MATOCL_LISTEN_HOST without setting a password. The client control port grants access to the whole filesystem, which is why this image keeps it on loopback by default.

Step 8: Backing up the metadata

The master's metadata is the index of the entire filesystem: lose it and the chunks are unusable. It lives on the dedicated data volume at /var/lib/mfs:

sudo ls -l /var/lib/mfs/metadata.mfs.back /var/lib/mfs/metadata.crc

While the master is running, the current metadata image on disk is metadata.mfs.back, accompanied by the changelog.*.mfs files holding changes since the last save. A plain metadata.mfs appears only while the master is cleanly stopped, so do not treat its absence on a running system as a fault.

For production, run a moosefs-metalogger on a separate machine. The metalogger keeps a continuously updated copy of the master metadata and is the supported way to recover a failed master. The metalogger port (9419) is bound to loopback on this image, so widen MATOML_LISTEN_HOST in /etc/mfs/mfsmaster.cfg and allow 9419 from the metalogger's address only, exactly as for the chunkserver in Step 7.

Azure disk snapshots of the data volume are a useful complement, but take them consistently and treat them as a point in time copy rather than a substitute for a metalogger.

Troubleshooting

The web monitor returns 401 with the correct password. The password is regenerated on first boot. Make sure you are reading the current value from /root/moosefs-credentials.txt on this machine, not a value copied from another virtual machine.

The mount is missing after a reboot. Check the mount unit and the master:

sudo systemctl status moosefs-mount --no-pager
findmnt -no SOURCE,FSTYPE /srv/moosefs

The mount unit uses mfsdelayedinit, so it succeeds and connects in the background even if the master is still starting.

Writes fail with "no space left on device" while df shows free space. MooseFS reserves space per chunkserver. Check the Disks tab in the web monitor for the per-directory capacity and error status.

A chunkserver shows as disconnected. Confirm the master is reachable from the chunkserver on port 9420 — both the nftables guard on this machine and your Azure network security group must allow the chunkserver's address.

Check the first-boot log if the machine did not come up as expected:

sudo cat /var/log/moosefs-firstboot.log

Licensing

MooseFS Community Edition is distributed under the GNU General Public License, version 2. There is no per node or per capacity fee. The cloudimg charge covers packaging, security patching, image maintenance, and 24/7 support.

Support

24/7 cloudimg support with a guaranteed 24 hour response SLA. Contact support@cloudimg.co.uk.