# OminiFS

**Repository Path**: cdevel/omini-fs

## Basic Information

- **Project Name**: OminiFS
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-20
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OmniFS

OmniFS is a clustered file-system project for shared block-device
environments. It provides a native `libominifs` File API, a durable MDS
metadata plane, and a direct client data path over locally visible block
devices.

The project is under active production-readiness development. Architecture
notes, deployment guides, operations runbooks, and design decisions live under
[`docs/`](docs/).

## Status

The current development profile focuses on a local three-node, six-disk
readiness environment:

- durable MDS metadata with Raft-backed mutation paths
- MDS RPC with manifest-declared security
- file-layer Manifest & Journal ownership of dirty/valid ranges
- direct block I/O from `libominifs`
- SPDK target exposure with Linux NVMe/TCP client devices
- fio external ioengine readiness and runtime gates
- structured exception logging under `/var/log/ominifs`

The default production-readiness verdict is reported by:

```text
build/127-readiness/result.env
```

The strict acceptance field is:

```text
production_ready=1
```

## Getting The Source

```bash
git clone https://gitee.com/cdevel/omini-fs.git
cd omini-fs
```

This repository does not vendor large external source trees. Local kernel
checkouts, generated indexes, temporary evidence, and external benchmark
outputs should stay outside the repository.

## Prerequisites

The normal development build expects:

- CMake 3.22 or newer
- a C++20 compiler
- OpenSSL development headers
- `pkg-config`
- Linux `io_uring` support

Optional gates use additional host tools:

- `fio` and a configured fio source tree for the external ioengine
- `nvme-cli` and Linux NVMe-oF kernel support for the stable block-exposure gate
- SPDK for target-side lifecycle and block exposure tests
- ublk kernel support only when explicitly testing the ublk profile

See the deployment guide for host setup details.

## Building

```bash
cmake -S . -B build/dev
cmake --build build/dev -j"$(nproc)"
```

To build only the fio ioengine targets:

```bash
cmake --build build/dev --target ominifs_fio dev_fio_engine_runtime -j"$(nproc)"
```

The fio build/runtime scripts use a real fio source tree. By default they look
under `build/fio-src/fio-*`; set `OMINIFS_FIO_SOURCE_DIR` to use another
configured fio source tree.

## Local Readiness

Run the main local readiness suite:

```bash
OMINIFS_FIO_RUNTIME_PROFILE=stable \
OMINIFS_FIO_RUNTIME_MIN_IOPS=1 \
OMINIFS_FIO_RUNTIME_MAX_P99_US=200000 \
OMINIFS_FIO_RUNTIME_MAX_P999_US=200000 \
OMINIFS_READINESS_LINUX_NVMF_SOAK_ROUNDS=10 \
bash dev/run-127-readiness-suite.sh
```

Inspect the result:

```bash
grep -E '^(status|steps_failed|production_ready|production_blockers)=' \
  build/127-readiness/result.env
```

Expected result for the default production profile:

```text
status=ok
steps_failed=0
production_ready=1
production_blockers=-
```

`spdk_ublk_file_io` is optional in the default profile. The stable profile uses
SPDK target-side exposure and Linux NVMe/TCP client devices.

## Tests

Common checks:

```bash
bash dev/check-terminology.sh
bash dev/check-logging-coverage.sh
bash tests/scripts/run-cmake-product-targets-test.sh
```

fio checks:

```bash
bash tests/scripts/run-fio-engine-build-test.sh
bash tests/scripts/run-fio-readiness-test.sh
bash tests/scripts/run-fio-engine-runtime-test.sh
```

MDS cluster readiness:

```bash
bash dev/run-metadata-cluster-readiness.sh
```

## Documentation

Start here:

- [Documentation Map](docs/README.md)
- [Deployment Guide](docs/ominifs-vms-like-deployment-guide.md)
- [Architecture and I/O Flow](docs/ominifs-architecture-io-flow-analysis.md)
- [MDS Raft Production Model](docs/mds-raft-production-model.md)
- [Native File Layout Design](docs/ominifs-vms-like-native-file-layout-design.md)
- [State Machines and Protocols](docs/ominifs-vms-like-state-machines-and-protocols.md)
- [SPDK I/O Path](docs/ominifs-spdk-io-path.md)
- [Exception Logging Standard](docs/operations/exception-logging-standard.md)
- [MDS TLS Operations Runbook](docs/operations/mds-tls-ops-runbook.md)
- [ADR Index](docs/adr/README.md)

Research notes are kept under [`research/`](research/).

## Repository Layout

```text
include/ominifs/   public C ABI headers
src/               product implementation
tests/             unit and script tests
dev/               local readiness and smoke harnesses
docs/              design docs, ADRs, and runbooks
research/          curated research notes
```

`dev/` is for local development and readiness tooling. Product hot paths live
under `include/` and `src/`.

## Naming

- Project name: `OmniFS`
- C++ namespace: `ominifs`
- C/C++ symbol prefix: `ominifs_`
- CLI tools: `ominifs_mds`, `mkfs_ominifs`, `ominifs_admin`

## License

OmniFS is licensed under the Apache License, Version 2.0. See
[`LICENSE`](LICENSE).