MooseFS PRO only.
Divide a new cluster into locations
This procedure divides a new cluster into locations, one per site, before any data is written to it. It starts where first mount and verification ends. The packages are in place at every site (install the server components). The cluster runs and is mounted on a machine. The decisions that the steps carry out are made in planning. When locations help answers whether to divide at all. Quorum across sites answers which site holds the default location. The WAN cost of writes answers what the link between the sites has to carry. Dividing a cluster that already holds data, and every later change to the division, are location tasks.
The division is kept in the metadata of the Master Server, not in a configuration file. The location tools change the division through a mounted MooseFS. Run the tools inside a mount, or point them at a mount with -M. Every change takes effect at once, reaches every Master Server with the rest of the metadata, and survives restarts. There is nothing to distribute to the other machines and nothing to reload. Since 5.2.0, every tool that changes the division needs a mount whose export entry has the admin option (access control). mfslocationlist works from any mount.
The examples below deploy two sites: west on 192.0.2.0/24 and east on 198.51.100.0/24.
Create the locations and switch them on
A new cluster runs with a single location named default, already ON. Create one location for each additional site with the mfslocadmin tools (mfslocadmin(1)), and rename default after the site that keeps that location:
mfslocationcreate east
mfslocationrename default west
A location is created in the OFF state, so switch it on before you map anything into it:
mfslocationstate -s ON east
The three states are described on the Location page. The maximum number of locations in a cluster is listed in Limits.
Map each site's addresses into its location
The location of a module follows its IP address. A module joins a location other than the default only when its address is mapped there. An address that is not mapped anywhere belongs to the default location. Map the addresses of every machine at every site: Master Servers, Chunkservers, Metaloggers, and the machines that mount the cluster.
mfslocationmap -i 192.0.2.0/24 west
mfslocationmap -i 198.51.100.0/24 east
A range can also be written as a single address or as both ends of a span (-i 198.51.100.11-198.51.100.26). mfslocadmin(1) lists the forms. A mapping that overlaps a range that belongs to another location is refused. With -f, the mapping moves the overlapping addresses instead of being refused. Each mapping applies immediately. The Master Server resolves the location of every connected module again. A Chunkserver whose location changed is disconnected and reconnects in its new location.
If the Master Server remaps server addresses (REMAP_BITS, REMAP_SOURCE_IP_CLASS, REMAP_DESTINATION_IP_CLASS, MULTILAN_BITS, or MULTILAN_CLASSES in mfsmaster.cfg, or a mfsipmap.cfg file), map every address a Chunkserver answers on to its location, not only the address it connects from. The Master Server resolves the location of the remapped address as well, and disconnects a Chunkserver whose addresses resolve to different locations.
Put the default location where the plan says
One location is always the default. The default location includes every unmapped module. The vote of the default location breaks a tie in leader election. If the plan puts the default location at a site other than the site that the initial default became, move the default location:
mfslocationsetdefault east
The move is refused if any Chunkserver known to the Master Server is not mapped anywhere. So this step comes after the mapping step. Map those Chunkservers first. The move is also refused when the target location is OFF. The Master Servers need no step of their own. The Leader and every Follower joined their locations through the mapping, like every other module. The election counts votes by location from then on (leader election and the role of DNS).
Give the first Storage Class a placement per location
A Storage Class defines placement separately for each location. In mfsscadmin (mfsscadmin(1)), -l names the location that the definitions after it apply to. A definition given without -l applies to the default location. The example below creates a class that keeps two copies at each site and sets it on a working directory with mfssetsclass:
mfsscadmin create -l west -K 2 -l east -K 2 twosites
mkdir /mnt/mfs/data
mfssetsclass twosites /mnt/mfs/data
A label expression written for a location is matched only against the Chunkservers of that location (label expressions and matching). So every location that a class names needs Chunkservers of its own. Designing the real classes, assigning them, and checking what they require are data placement tasks.
Verify where everything landed
mfslocationlist prints every location with its state, names the default, and lists the mappings:
location: west, state: ON
location: east, state: ON
default location: west
ip mapping: 192.0.2.0 - 192.0.2.255 -> west
ip mapping: 198.51.100.0 - 198.51.100.255 -> east
mfscli -SLO shows the same division with a health column and the count of connected clients, Chunkservers, Follower Master Servers, and Metaloggers in each location. The Locations table in the GUI also shows the assigned IP ranges. The Chunkserver, Master Server, and Metalogger listings (mfscli -SCS, -SIM, -SML) each have a location column. So a machine that ended up in the wrong location is visible in its row. The Leader Master Server also logs a notice, with the module and its address, every time an unmapped module connects. After all machines are up, that notice in the system log names exactly what the mapping missed.
Then write a file into the directory that has the class, and ask mfsfileinfo where the copies of the file are stored. With locations active, every copy and every Erasure Coding (EC) part is printed with its location and the state of that location:
dd if=/dev/zero of=/mnt/mfs/data/test.bin bs=1M count=64
mfsfileinfo /mnt/mfs/data/test.bin
/mnt/mfs/data/test.bin:
chunk 0: 0000000000000041_00000001 / (id:65 ver:1) ; mtime:1787227200 (2026-08-20 14:00:00)
copy 1: 192.0.2.21:9422 ; location:west:ON ; status:VALID
copy 2: 198.51.100.31:9422 ; location:east:ON ; status:VALID
A copy at each site, on the addresses mapped there, shows that the division works.