Automatic Configuration

This page covers the policy file that drives the mango-jbof service, the standard procedure for putting the appliance into service, and how to pin a configuration so it survives a reboot. This is the recommended way to operate Mango BoostX™ NRT: the appliance configures itself at boot, and the only file you edit is the policy file.

info

The service itself, and the network settings inside the policy file, are covered in Software Setup. If you need a layout the policy file cannot express, or you are diagnosing a problem, use the individual commands in Manual Configuration instead.

The Policy File

/etc/mango-cli/mango_jbof_config.yaml is the only file you are expected to edit. Nothing else rewrites it, so comments you add to it are preserved.

/etc/mango-cli/mango_jbof_config.yaml

# Config schema version: 1.0

network:
  mode: "static"                  # "dhcp" | "static"
  interfaces:
    - name: "eth0"
      address: "200.1.1.100/24"   # CIDR or "dhcp"

nvme_discovery:
  scan_interval_sec: 3            # hot-plug scan period
  vendor_policy: "any"            # "any" | "specific"
  allowed_vendors:                # used only when vendor_policy is "specific"
  #  - 0x144d                     # Samsung
  #  - 0x1e0f                     # Kioxia
  #  - 0xcc53                     # ScaleFlux
  skip_faulty_devices: true       # exclude SSDs reporting Buffer I/O error in dmesg

nvmf_service:
  enabled: true
  transport: "rdma"               # NRT hardware supports RDMA only
  port: 4420
  startup_retry_max: 3            # start attempts at boot
  subsystem:
    nqn: "nqn.2022-02.io.mangoboost:subsys"   # an index (0..N-1) is appended
    max_devices_per_subsystem: 1  # 1 = one subsystem per SSD / a number / "max"
    # device_assignments:         # pin a PCI address to a subsystem index
    #   "0000:04:00.0": 0
    #   "0000:06:00.0": 1
    allow_any_host: true
    allowed_host_nqns:            # required when allow_any_host is false
    #  - "nqn.2014-08.org.nvmexpress:uuid:..."

# Logging defaults to INFO in /var/log/mango (10 MB per file, 5 files kept).
# Uncomment to override; DEBUG is verbose and meant for diagnosing a problem.
# logging:
#   level: "DEBUG"
#   dir: "/var/log/mango"
#   max_size_mb: 10
#   max_backups: 5

The network block is described in Software Setup → Network Configuration. The remaining blocks are described below.

SSD Discovery

scan_interval_sec is how often the PCIe bus is re-scanned, which is also how hot-plugged SSDs are picked up.

vendor_policy is any by default. Set it to specific and list PCI vendor IDs under allowed_vendors to export only the SSDs of those vendors.

warning

Keep skip_faulty_devices: true. With it disabled, the service attaches an SSD that is already reporting I/O errors, and attaching a failing device can panic the kernel. With it enabled, such a device is logged and skipped, and the remaining healthy SSDs are still exported.

Subsystem Layout

max_devices_per_subsystem decides how the discovered SSDs are grouped:

• 1 — one subsystem per SSD. Three SSDs produce three subsystems, each with one namespace.
• a number N — up to N SSDs per subsystem.
• "max" — every SSD is placed in a single subsystem as separate namespaces.

A subsystem holds at most 26 namespaces. SSDs beyond that limit are reported as a warning and left unexported.

device_assignments pins a PCI address to a subsystem index, so that SSD lands in the same subsystem across reboots regardless of discovery order. SSDs that are not listed are assigned automatically, starting after the highest index you pinned. A pinned device is honoured even if it pushes its subsystem past max_devices_per_subsystem, up to the 26-namespace limit.

nqn is the base NQN. The subsystem index is appended, so the default produces nqn.2022-02.io.mangoboost:subsys0, ...:subsys1, and so on.

Access Control

With allow_any_host: true any initiator may connect. To restrict access, set it to false and list the permitted host NQNs under allowed_host_nqns. You can read a host's NQN from /etc/nvme/hostnqn on that host.

Read the host NQN on the initiator

(initiator) ~$ cat /etc/nvme/hostnqn
nqn.2014-08.org.nvmexpress:uuid:a734913e-15f4-4bcb-9c1b-1ef805909638

Logging

The logging block is commented out and defaults to INFO in /var/log/mango. Raise it to DEBUG only while diagnosing a problem, or when MangoBoost support asks for a debug-level log.

Standard Operating Procedure

1. Edit the policy file — at minimum the interface address, and the subsystem NQN, grouping, and access control if the defaults do not match your deployment.

   (target) ~# vi /etc/mango-cli/mango_jbof_config.yaml

2. Restart the service to apply it.

   (target) ~# systemctl restart mango-jbof

3. Confirm the result with nvmf show, as described in Software Setup → Verifying the Export. Every subsystem must have a listener and warnings: must read none.

4. Connect from the host. See Initiator Setup.

5. Optionally pin the configuration so it is restored verbatim after a reboot.

   (target) ~# mango-ctl nvmf autoconfig --commit-state -f

Pinning the Running Configuration

Two files are involved, and the split matters.

File	Written by	Contents
/etc/mango-cli/mango_jbof_config.yaml	You, by hand	The policy: what to export and how
/etc/mango-cli/mango_jbof_nvmf_state.yaml	autoconfig --commit-state only	A snapshot of the configuration that is actually running

If the snapshot file exists, the service restores exactly that topology — your custom NQNs, hosts, listeners, and namespaces — instead of deriving a layout from the policy. If it does not exist, the service applies the policy. Removing the snapshot returns the appliance to policy-driven configuration.

The autoconfig subcommand manages both the service and the snapshot:

(target) ~# mango-ctl nvmf autoconfig --show           # configuration that will be applied
(target) ~# mango-ctl nvmf autoconfig --diff           # committed snapshot vs. running configuration
(target) ~# mango-ctl nvmf autoconfig --enable         # enable and start the service
(target) ~# mango-ctl nvmf autoconfig --disable        # stop and disable the service
(target) ~# mango-ctl nvmf autoconfig --restart        # restart from the stored configuration
(target) ~# mango-ctl nvmf autoconfig --commit-state   # save the running configuration
(target) ~# mango-ctl nvmf autoconfig --clear-state    # delete the snapshot, return to the policy

With no snapshot committed, the two query options report the policy mode:

(target) ~# mango-ctl nvmf autoconfig --show
NVMe-oF auto-config source: /etc/mango-cli/mango_jbof_config.yaml
Mode: policy template - transport=rdma
  base nqn: nqn.2022-02.io.mangoboost:subsys
  max_devices_per_subsystem: 1
  allowed hosts: any

(target) ~# mango-ctl nvmf autoconfig --diff
Committed setup: /etc/mango-cli/mango_jbof_nvmf_state.yaml
Mode: policy template - nothing committed, so there is no committed setup to compare against.
Commit the running setup with --commit-state to pin it.

To keep a configuration you built with the individual commands, build it, commit it, then verify with --diff.

info

--commit-state is refused in a non-interactive context, such as a script or a pipeline, and exits with code 5. Add -f/--force when calling it from automation. The same applies to the other destructive autoconfig operations.

Startup Sequence

Knowing the order the service works in makes its log readable, and tells you which step to look at when the appliance does not come up.

1. Load the mango-core kernel module and wait until its network interfaces appear.
2. Apply the configured address to each of those interfaces — assign the static CIDR, or start a DHCP client.
3. Scan the PCIe bus for NVMe SSDs, apply the vendor policy, and drop devices that dmesg reports as faulty when skip_faulty_devices is set. The scan repeats every scan_interval_sec, so hot-plugged SSDs are picked up later too.
4. Confirm the interface actually provides the configured transport. The service reads this from the interface, and waits rather than failing if it is not available yet.
5. Force a teardown of any target that is still running, so the start always begins from a clean state. A target left over from a previous run — including one you created by hand — would otherwise make the start fail.
6. Start the target with nvmf start -t RDMA -m <queues>. The service divides its RDMA queue budget of 32 by the number of subsystems it is about to create, so a 3-subsystem layout is started with -m 10. This keeps the total number of I/O queues within what the card can serve.
7. Attach each SSD as Nvme0, Nvme1, … and create the planned subsystems, adding the permitted hosts when allow_any_host is false, then the namespaces, then the listener.

If the sequence fails, it is retried startup_retry_max times with a short back-off (1 s, 3 s, then 10 s). After the last attempt the log records that automatic retry is disabled, and the service stops trying until it is restarted. This is why nvmf show can report subsystems 0 for a short period after a reboot.

When a committed snapshot exists, steps 6 and 7 restore that topology instead. The live address of the interface always takes precedence over the address stored in the snapshot, since a stored address may no longer be reachable; a mismatch is written to the log.