{"id":27011753,"url":"https://github.com/eth-cscs/manta","last_synced_at":"2026-06-14T22:01:16.319Z","repository":{"id":164868488,"uuid":"619809917","full_name":"eth-cscs/manta","owner":"eth-cscs","description":"Another CLI for Alps","archived":false,"fork":false,"pushed_at":"2026-05-30T22:45:20.000Z","size":5545,"stargazers_count":22,"open_issues_count":15,"forks_count":4,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-05-31T00:20:40.647Z","etag":null,"topics":["alps","cli","cscs","csm","productivity"],"latest_commit_sha":null,"homepage":"https://eth-cscs.github.io/manta/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eth-cscs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-27T13:31:03.000Z","updated_at":"2026-05-30T22:45:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"2f538939-cfc0-428b-ad7e-1c4c6169696d","html_url":"https://github.com/eth-cscs/manta","commit_stats":null,"previous_names":[],"tags_count":695,"template":false,"template_full_name":null,"purl":"pkg:github/eth-cscs/manta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-cscs%2Fmanta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-cscs%2Fmanta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-cscs%2Fmanta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-cscs%2Fmanta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eth-cscs","download_url":"https://codeload.github.com/eth-cscs/manta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eth-cscs%2Fmanta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33961254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alps","cli","cscs","csm","productivity"],"created_at":"2025-04-04T11:36:49.105Z","updated_at":"2026-06-14T22:01:16.285Z","avatar_url":"https://github.com/eth-cscs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com)\n\n# MANTA\n\n\u003e **Documentation version:** this README and the sibling docs ([GUIDE.md](GUIDE.md), [CLI.md](CLI.md), [API.md](API.md), [MIGRATING.md](MIGRATING.md)) describe **manta 2.0.0**. For an older release, browse the repository at the matching git tag (e.g. `v1.64.3` for the last v1 release).\n\nAnother CLI tool for [Alps](https://www.cscs.ch/science/computer-science-hpc/2021/cscs-hewlett-packard-enterprise-and-nvidia-announce-worlds-most-powerful-ai-capable-supercomputer).\n\n## TL;DR\n\nA command-line + HTTP API frontend for HPC clusters running [CSM](https://github.com/Cray-HPE/cray-site-init) or [OpenCHAMI](https://www.openchami.org/). Two independent binaries from one Cargo workspace:\n\n- **`manta`** — interactive CLI. Forwards every operation (including auth) to a `manta-server` over HTTPS; never calls the backend directly.\n- **`manta-server`** — Axum HTTPS server. Holds the per-site backend credentials and exposes a Swagger-documented REST + WebSocket API at `https://\u003chost\u003e:8443/api/v1` (default port).\n\n**Get something running locally:**\n\n```bash\n# 1. clone and enter the repo\ngit clone https://github.com/eth-cscs/manta \u0026\u0026 cd manta\n\n# 2. build both binaries\ncargo build -p manta-cli -p manta-server\n\n# 3. drop a minimal cli.toml into manta's config directory.\n#    Linux: ~/.config/manta/   macOS: ~/Library/Application Support/local.cscs.manta/\nCONFIG_DIR=\"${XDG_CONFIG_HOME:-$HOME/.config}/manta\"             # Linux\n# CONFIG_DIR=\"$HOME/Library/Application Support/local.cscs.manta\" # macOS\nmkdir -p \"$CONFIG_DIR\"\ncat \u003e \"$CONFIG_DIR/cli.toml\" \u003c\u003c'EOF'\nlog              = \"info\"\nsite             = \"ochami\"\nparent_hsm_group = \"nodes_free\"\nmanta_server_url = \"https://manta-server.example.com:8443\"   # required\nEOF\n# server.toml is site-specific (TLS certs + per-site backend URLs) —\n# see the Configuration files section below for the full schema.\n\n# 4. start the server, then drive it with the CLI\n./target/debug/manta-server \u0026\n./target/debug/manta get sessions\n```\n\n**Staying current.** Once you have a working `manta` binary,\nthree commands handle the day-to-day install plumbing:\n\n```bash\n# Install shell tab completion to the shell's standard XDG dir\n# (substitute bash / fish for zsh; pass --path \u003cDIR\u003e to override)\nmanta gen-autocomplete --shell zsh\n\n# Install the consolidated `man manta` page (use `/sessions` to search)\n# Defaults to $XDG_DATA_HOME/man/man1 (`~/.local/share/man/man1`)\nmanta gen-man\n\n# Check for a newer release; then apply it\nmanta upgrade --check\nmanta upgrade -y\n```\n\n`manta upgrade` reads the latest `v*` workspace tag from GitHub\nreleases (filtered to the same major version as the running binary)\nand atomically swaps the binary in place. If you installed\nvia Homebrew, prefer `brew upgrade manta-cli` — `manta upgrade` will\nwarn (but not block) when it detects a Homebrew-managed install\npath. See [CLI.md#gen-autocomplete](CLI.md#gen-autocomplete),\n[#gen-man](CLI.md#gen-man), and [#upgrade](CLI.md#upgrade) for the\nfull flag reference.\n\n| Where to look next | For |\n|---|---|\n| [GUIDE.md](GUIDE.md) | common workflows (\"how do I deploy a SAT file?\") |\n| [CLI.md](CLI.md) | per-flag reference for every `manta` subcommand |\n| [API.md](API.md) | REST + WebSocket endpoints, schemas, status codes |\n| [MIGRATING.md](MIGRATING.md) | upgrading from manta v1 to v2 |\n| [ARCHITECTURE.md](ARCHITECTURE.md) | crate layout, module boundaries, security model |\n| [eth-cscs.github.io/manta](https://eth-cscs.github.io/manta/) | rustdoc for the whole workspace (rebuilt on every push to `main`) |\n\n## Repository layout\n\nmanta is a Cargo workspace with three crates:\n\n```\ncrates/\n├── manta-shared/   (lib)  — wire types, common helpers, backend dispatcher\n├── manta-cli/      (bin)  — terminal client (binary: `manta`)\n└── manta-server/   (bin)  — Axum HTTPS server (binary: `manta-server`)\n```\n\nBuild a single crate with `cargo build -p manta-cli` or `cargo build -p manta-server`; the two binaries do not depend on each other. See [ARCHITECTURE.md](ARCHITECTURE.md) for details.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [GUIDE.md](GUIDE.md) | User guide — common workflows and practical examples |\n| [CLI.md](CLI.md) | Full CLI command reference — every command, subcommand, and flag |\n| [API.md](API.md) | HTTP API reference — REST and WebSocket endpoints |\n| [ARCHITECTURE.md](ARCHITECTURE.md) | Codebase architecture — for contributors |\n\nManta is a frontend cli to interact with CSM and OCHAMI.\n\n## Deployment\n\n### Prerequisites\n\nInstall build dependencies\n\n```shell\n$ cargo install cargo-release dist git-cliff\n```\n\n\u003e `dist` is the renamed successor of `cargo-dist`; the old name still installs the same binary but emits a deprecation warning.\n\n### Clone repo\n\n```bash\ngit clone https://github.com/eth-cscs/manta \u0026\u0026 cd manta\n```\n\nThe `main` branch holds the current 2.x line.\n\n### Build container images\n\nThe two binaries ship as two images, each with its own multi-stage Dockerfile alongside its source. **Build from the workspace root in both cases** so the Cargo lockfile and shared sources are in the build context:\n\n```\ndocker build -f crates/manta-cli/Dockerfile    -t manta-cli    .\ndocker build -f crates/manta-server/Dockerfile -t manta-server .\n```\n\nA `.dockerignore` at the workspace root keeps `target/`, `.git/`, and editor state out of the context.\n\n#### Copy configuration file\n\nThe CLI reads `cli.toml`; the HTTP server reads `server.toml`. Both live in manta's config directory (`~/.config/manta/` on Linux, `~/Library/Application Support/local.cscs.manta/` on macOS). Each has its own schema — see the [Configuration files](#configuration-files) section below for the full layout. A minimal CLI config looks like:\n\n```bash\nCONFIG_DIR=\"${XDG_CONFIG_HOME:-$HOME/.config}/manta\"             # Linux\n# CONFIG_DIR=\"$HOME/Library/Application Support/local.cscs.manta\" # macOS\nmkdir -p \"$CONFIG_DIR\"\ncat \u003e \"$CONFIG_DIR/cli.toml\" \u003c\u003cEOF\nlog = \"info\"\n\nsite = \"ochami\"\nparent_hsm_group = \"nodes_free\"\nmanta_server_url = \"https://manta-server.example.com:8443\"   # required\nEOF\n```\n\nThe CLI config has no `[sites.*]` block — per-site backend connection details (URLs, TLS certs, k8s, vault) live in `server.toml`. The CLI's `site = \"...\"` value is just the `X-Manta-Site` header it sends on each request; the server validates it.\n\n#### Start the `ochami` services from the [deployment recipe quickstart](https://github.com/OpenCHAMI/deployment-recipes/tree/main/quickstart).\n\n\u003e [!NOTE]\n\u003e Make sure to set the `ACCESS_TOKEN` environment variable and create a CA certificate in the same directory as the config file. This can be done using the convienience functions from the the OpenCHAMI deployment recipe repository.\n\u003e\n\u003e To set the `ACCESS_TOKEN` environment variable and create/renew the CA certificate (assuming you have cloned the deployment recipe quickstart):\n\u003e ```bash\n\u003e # collection of useful functions\n\u003e ochami_deployment_recipe_quickstart=path/to/quickstart\n\u003e source $ochami_deployment_recipe_quickstart/bash_functions.sh\n\u003e\n\u003e # set environment variable then create the cert\n\u003e export ACCESS_TOKEN=$(gen_access_token)\n\u003e get_ca_cert \u003e \"$CONFIG_DIR/ochami_root_cert.pem\"   # $CONFIG_DIR set above\n\u003e ```\n\n#### Run the CLI with one of the two options mentioned above to confirm that `manta` is working.\n\nThe `manta-cli` image has `manta` as its ENTRYPOINT, so anything after the image tag is forwarded as CLI args:\n\n```bash\ndocker run -it --network=host \\\n  -v \"$CONFIG_DIR\":/root/.config/manta \\\n  -e MANTA_CSM_TOKEN \\\n  manta-cli get redfish-endpoints\n```\n\nThe `manta-server` image runs the HTTPS server; mount your config + TLS material and publish the port:\n\n```bash\ndocker run -p 8443:8443 \\\n  -v \"$CONFIG_DIR\":/root/.config/manta:ro \\\n  -v /etc/manta/tls:/etc/manta/tls:ro \\\n  manta-server\n```\n\n\u003e [!NOTE]\n\u003e Some commands will not work yet with OpenCHAMI services and will sometimes show a message indicating no implementation for the backend.\n\u003e\n\u003e ```bash\n\u003e docker run -it --rm --network=host \\\n\u003e   -v \"$CONFIG_DIR\":/root/.config/manta \\\n\u003e   -e MANTA_CSM_TOKEN \\\n\u003e   manta-cli get sessions\n\u003e ERROR | Get and filter sessions command not implemented for this backend\n\u003e exit status 1\n\u003e ```\n\u003e\n\u003e Some other commands may fail simply because CSM-only services are not part of an OpenCHAMI deployment.\n\n### HTTP server mode\n\nManta can run as an HTTPS server, exposing all CLI operations as a REST + WebSocket API. This is useful for automation, scripting, and integration with other tools without requiring direct CLI access.\n\nThe HTTP server lives in its own binary (`manta-server`) inside the `crates/manta-server` workspace member. Build it with `cargo build -p manta-server`.\n\n**Start the server**\n\nWrite `server.toml` in manta's config directory first — see the [Configuration files](#configuration-files) section below for the path on your platform. Then:\n\n```bash\nmanta-server\n```\n\nEach setting in the `[server]` block can be overridden at runtime:\n\n| Flag | Overrides | Description |\n|------|-----------|-------------|\n| `--port` | `[server].port` | Port to listen on |\n| `--listen-address` | `[server].listen_address` | Bind address |\n| `--cert` | `[server].cert` | TLS certificate path |\n| `--key` | `[server].key` | TLS private key path |\n| `--allow-http` | `[server].allow_http` | Opt in to plain-HTTP listen mode when no cert/key is set. Default fail-closed — the server refuses to start without TLS so bearer tokens can't accidentally land on the wire in cleartext. Set only when TLS terminates upstream. |\n\nBeyond the flags above, two settings are config-only:\n\n- `[server].migrate_backup_root` — absolute filesystem directory that confines `POST /migrate/{backup,restore}` paths. Required for those endpoints to function at all; when unset the server returns `400 BadRequest` even for admin callers. Set, then restart.\n- HSTS (`Strict-Transport-Security: max-age=31536000; includeSubDomains`) is emitted on every response unconditionally. Browsers ignore it over plain HTTP per RFC 6797, so it's a no-op under `allow_http = true` and active otherwise.\n\n\u003e The CLI no longer ships a `manta serve` subcommand — invoke `manta-server` directly.\n\n---\n\n### Configuration files\n\nManta reads two TOML files, one per binary: `cli.toml` for the CLI and `server.toml` for the HTTP server. Both live in manta's config directory:\n\n- Linux: `~/.config/manta/` (or `$XDG_CONFIG_HOME/manta/` if set)\n- macOS: `~/Library/Application Support/local.cscs.manta/`\n\nOverride the path with `MANTA_CLI_CONFIG` / `MANTA_SERVER_CONFIG`.\n\nThe two schemas are **disjoint**: the CLI's `cli.toml` carries only the CLI-side knobs (`site`, `parent_hsm_group`, `manta_server_url`, optional `socks5_proxy`) — it has **no `[sites.*]` block** and no Kafka audit block (audit emission is server-side only). Every per-site backend connection detail (URLs, TLS certs, k8s, vault, per-site SOCKS proxies) lives in `server.toml`, alongside the `[server]` block (TLS, listen address, console timeout, auth rate limit) and the optional `[auditor.kafka]` for the server-side audit stream.\n\n**`cli.toml`**\n\n`manta_server_url` is required: the CLI no longer talks to CSM/OCHAMI backends directly — every operation (including auth) is forwarded to the named manta server. Run `manta-server` on a reachable host first.\n\n```toml\nlog = \"info\"\n\nsite             = \"alps\"                                # active site (X-Manta-Site header)\nmanta_server_url     = \"https://manta-server.cscs.ch:8443\"   # required\nsocks5_proxy         = \"socks5h://127.0.0.1:1080\"            # optional: reaches manta-server\nrequest_timeout_secs = 600                                   # optional: per-request HTTP timeout (seconds). Default 300 for REST calls; streams (SSE log tail, WS console) unlimited. Setting this also caps streams — pick a value larger than your worst-case session if you set it.\n```\n\nAudit emission is server-side only — every CLI command goes through HTTP to `manta-server`, which emits per-`/auth/*` events to its configured `[auditor.kafka]` stream.\n\nThe CLI has no `[sites]` section: it only knows about the one\n`manta-server` it talks to. Per-site backend connection details\n(URLs, TLS certs, k8s, vault, per-site SOCKS proxies) live entirely\nin `server.toml`.\n\n**`server.toml`**\n\n```toml\nlog = \"info\"\n\n[server]\nlisten_address                  = \"0.0.0.0\"   # optional; default 0.0.0.0\nport                            = 8443        # optional; default 8443 if cert+key set, else 8080\ncert                            = \"/etc/manta/tls/server.crt\"\nkey                             = \"/etc/manta/tls/server.key\"\nconsole_inactivity_timeout_secs = 1800\nauth_rate_limit_per_minute      = 60      # per source IP for /api/v1/auth/*; omit to disable\nrequest_timeout_secs            = 300     # global per-route timeout (returns 408); default 300 (5 min)\n\n[auditor.kafka]\nbrokers = [\"kafka.cscs.ch:9095\"]\ntopic   = \"manta-server-audit\"\n\n[sites.alps]\nbackend           = \"csm\"\nshasta_base_url   = \"https://api.alps.cscs.ch\"\nroot_ca_cert_file = \"/etc/manta/certs/alps_root_cert.pem\"\nsocks5_proxy      = \"socks5h://127.0.0.1:1080\"   # optional: per-site backend proxy\n\n[sites.alps.k8s]\napi_url = \"https://10.0.0.10:6443\"\n\n[sites.alps.k8s.authentication.vault]\nbase_url = \"https://vault.cscs.ch:8200\"          # also used by sat-file/session handlers\n```\n\nThe runtime Vault URL is derived from `[sites.X.k8s.authentication.vault].base_url` at startup; the vault secret path is computed from a hard-coded prefix and the site name. No standalone `vault_base_url` / `vault_secret_path` keys.\n\nThe `cat \u003e \"$CONFIG_DIR/cli.toml\" \u003c\u003cEOF` block in [Copy configuration file](#copy-configuration-file) is the minimum a workstation needs; for `server.toml`, the `[sites.\u003cname\u003e]` sub-blocks above are the canonical reference (TLS, k8s, Vault, backend URLs all have their own subsection above).\n\n**Migrating from the pre-split `config.toml`**\n\nThere is no auto-migration command. When either binary starts and finds its config file missing, it prints a minimal example and — if a legacy `config.toml` exists in manta's config directory — a field-by-field mapping of what to copy where. Copy by hand following that mapping. The per-site `sites.X.manta_server_url` field was removed; use the top-level `manta_server_url` in `cli.toml` if you need it.\n\n**Example — list CFS sessions**\n\n```bash\ncurl -sk -H \"Authorization: Bearer $TOKEN\" \\\n  https://localhost:8443/api/v1/sessions | jq .\n```\n\n**Example — open a node console (WebSocket)**\n\n```bash\nwscat -H \"Authorization: Bearer $TOKEN\" \\\n  --connect wss://localhost:8443/api/v1/nodes/x3000c0s1b0n0/console\n```\n\nSee [API.md](API.md) for the full endpoint reference, or browse the interactive Swagger UI at `https://localhost:8443/docs` once the server is running.\n\n---\n\n### Build from sources\n\nInstall Rust toolchain https://www.rust-lang.org/tools/install\n\n```shell\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n\nInstall cross to be able to complile on different platforms\n\n```shell\ncargo install cross\n```\n\nGenerate binary (cross compilation)\n\n```shell\nscripts/build\n```\n\nor\n\n```shell\nrustup target add x86_64-unknown-linux-gnu\ncargo build --target=x86_64-unknown-linux-gnu\n```\n\n### Development\n\n#### Prerequisites\n\nInstall `dist` and `cargo-release`:\n\n```\ncargo install dist\ncargo install cargo-release\n```\n\nConfigure `dist`. Accept default options and only target linux assets:\n\n```\ndist init -t $(uname -m)-unknown-$(uname -s | tr '[:upper:]' '[:lower:]')-gnu\n```\n\nThen remove the assets for macos and windows\n\nMake sure a github workflow is created in `.github/workflows/release.yml`\n\n#### Deployment\n\nThis project is already integrated with github actions through 'cargo release' and 'git cliff'\n\n\u003e git cliff will parse your commits and update the CHANGELOG.md file automatically as long as your commits follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#specification). The commit-type → section mapping lives in the `[git.commit_parsers]` table inside [`cliff.toml`](cliff.toml).\n\n```\ncargo release \u003cbump level\u003e --execute\n```\n\n\u003e choose your [bump level](https://github.com/crate-ci/cargo-release/blob/master/docs/reference.md#bump-level) accordingly\n\nIf everything went well, the binaries will be at `target/x86_64-unknown-linux-gnu/release/manta-cli` and `target/x86_64-unknown-linux-gnu/release/manta-server`.\n\n### Profiling\n\n#### Enable capabilities\n\n```bash\nsudo sysctl -w kernel.perf_event_paranoid=-1\n```\n\n#### Install perf\n\n```bash\nsudo apt-get install linux-tools-common linux-tools-generic linux-tools-`uname -r`\n```\n\n#### Grant access to kernel address map\n\n```bash\nsudo sh -c \" echo 0 \u003e /proc/sys/kernel/kptr_restrict\"\n```\n\n#### Create perf data\n\n```bash\nperf stat -ad -r 100 target/release/manta-cli get sessions\n```\n\n#### Identify bottlenecks and get hotspots for those events\n\n\n```bash\nperf record -g --call-graph=dwarf -F max target/release/manta-cli get sessions\n```\n\n#### Convert perf data file to a format firefox profiles understands\n\n```bash\nperf script -F +pid \u003e manta.perf\n```\n\nGo to https://profiler.firefox.com/ and open manta.perf file\n\n\n\u003c!--\n  DHAT memory profiling used to live here. It required a `dhat-heap`\n  feature in manta-cli's Cargo.toml that no longer exists. If you want\n  to revive it, add `dhat = \"...\"` as an optional dep, expose a\n  `dhat-heap` feature that enables it, and wrap `main` in a\n  `#[cfg(feature = \"dhat-heap\")] let _profiler = dhat::Profiler::new_heap()`.\n  Then `cargo run -r --features dhat-heap -- get sessions` will produce\n  dhat-heap.json viewable at https://nnethercote.github.io/dh_view/dh_view.html\n--\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feth-cscs%2Fmanta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feth-cscs%2Fmanta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feth-cscs%2Fmanta/lists"}