orama global

orama global

Operate the global role.

On the node, as root: install puts the global services on this machine;
start, stop and restart run their units in order, chain first.

bind signs the binding that proves a service key belongs to an operator. The
private key stays in its file; the command writes the public key and the
signature. register, bond, unbond, capacity and retire build the node's chain
messages.

orama global bind [flags]

orama global bond [flags]

Move norama from the operator account into the node's role bond.

The amount is added to the bond that role already holds. The node must already
be registered with that role. Without --node the command prints the sign
document and does not submit it.

orama global capacity [flags]

Declare the storage capacity of a registered node that has the storage role.

The chain refuses a declaration above the capacity the role bond backs, and
below the bytes already reserved by deals. Zero is a declaration of no
capacity. Without --node the command prints the sign document and does not
submit it.

orama global install [flags]

Install global services on this machine: chain, and optionally ipfs,
provider, archiver, indexer, repair, and the roles of the Orama Tor network
(dirauth, relay, relay,exit, onion) and a directory authority's bandwidth
reporter (reporter). The chain is required unless the machine only runs dirauth
or relay: the other services reach it only on this host's loopback RPC. provider
needs ipfs beside it (it pins public deals through the public Kubo). provider
and repair are never installed together. indexer is optional: it serves the chain read API on
loopback for a node that runs an RPC or index endpoint.

For each service it creates the service's system account, copies its binaries
(oramad and this orama CLI for the chain, whose unit runs 'orama global
validator check-sign-floor' before every start; ipfs, Kubo v0.43.1, for ipfs;
orama-global for the others) from --staged-dir into /usr/lib/orama-global/bin
(root-owned, 0755; a symlink in the staged directory is refused, and as root the
directory must be root's and not writable by others). A release archive's bin/
directory (/opt/orama/bin once the release is extracted) is the staged directory,
and the release's manifest (--manifest, /opt/orama/manifest.json) must list every
file the install reads with the digest it has; a file that is not the release's is
refused before anything on the host changes. It writes and enables its
orama-global-* unit, and opens its public port in ufw (31000 tcp+udp for the
chain, 31010 tcp+udp for the public Kubo swarm, 31013 tcp for the provider)
with the comment orama-global. It does not start anything: 'orama global start'
does, chain first.

The chain unit runs oramad under cosmovisor v1.7.3. Stage the official
cosmovisor-v1.7.3-linux-<amd64|arm64>.tar.gz beside the other binaries: its
SHA-256 must equal the pin built into this CLI, and only its cosmovisor file is
installed. oramad itself is placed in the chain home's cosmovisor layout as the
genesis binary, together with the release's shielded verifier (orama-orchard-verifier,
which the release ships beside oramad and whose digest oramad pins): the chain unit
passes oramad the one in the layout's current/bin, so an upgrade brings its own.
The chain home must already have a genesis (--init-chain, or an existing home). A binary already staged there with different bytes is
refused: change the chain binary with 'orama maint global stage-oramad --upgrade'.

The ipfs service is a public Kubo of its own: no swarm.key, its own repo in
/var/lib/orama-global/ipfs, swarm on 31010, RPC on 127.0.0.1:31011 (198.18.0.2:31011 with --colocated) behind a
token only the provider's group can read, and a GC timer. --public-storage-gb
is the capacity you will declare with 'orama global capacity'; Kubo's
StorageMax is that plus 10%. It never touches a private cluster's Kubo.

--init-chain creates the chain home with 'oramad init' as orama-chain and puts
the network's --genesis in place. It is never done without the flag, and it is
refused when the home already has a genesis.

--external-address <public ip>:31000 writes the chain's config.toml and app.toml
(the settings chain/scripts/stagenet/deploy.sh used to sed in): the address the
node announces to its peers (the chain itself listens at the namespace address,
198.18.0.2, which no peer can reach), peer exchange off, Prometheus on 127.0.0.1,
custom pruning (keep 100, every 10 blocks), and a state-sync snapshot every 1000
blocks with two kept. A setting the chain's template no longer has is an error,
not a skipped line. Giving --statesync-rpc twice, with --statesync-trust-height
and --statesync-trust-hash, makes the node restore a snapshot on its first start
instead of replaying the chain: the servers are two nodes' light-client routes
(https://<host>/v1/chain/light), the height and hash a block both agreed on, and
the trust period is 7 days, shorter than the 21-day unbonding. Running it again
with the same flags changes nothing.

An inactive ufw is refused unless --enable-firewall is given; then incoming is
denied by default, --ssh-port is allowed, and ufw is enabled; --ssh-port must
be a port 'sshd -T' reports, or nothing is changed. Running the
command again with the same flags changes nothing but the binaries' bytes.

The roles of the Orama Tor network (orama.network/docs/operator/tor-network) run the distro's tor,
installed from the Tor Project's repository, with a torrc this command writes
from the network's tor-network.json, staged beside the binaries; the network file
is checked before anything on the host changes.
  relay           a relay (ORPort 31020/tcp). --tor-address, --tor-contact and
                  --tor-node-id are required; the nickname is derived from the
                  node id.
  relay,exit      the same relay as an exit, under a reduced exit policy. Opt-in:
                  the network file must say allow_exit. Destinations in
                  /var/lib/orama-global/tor-exit-reject (one CIDR or address, with
                  an optional :port, per line) are refused first.
  dirauth         a directory authority (ORPort 31020/tcp, DirPort 31021/tcp). It
                  is a relay already, so it never goes beside relay. It needs
                  --tor-address to be one of the network's authorities and
                  --tor-authority-keys, its bundle from 'orama global tor
                  ceremony'; a bundle that is not this authority's is refused.
                  A dirauth or relay host needs no chain, unless it also runs
                  the reporter.
  onion           the validator's onion service, forwarding to a tx gate on
                  loopback that serves only account read, broadcast and tx lookup.
                  It publishes no port and needs the chain.
  reporter        the authority's bandwidth reporter, 'orama-global reporter': it
                  reports each closed epoch's relay bandwidth and uptime to x/relay
                  from the authority's votes. It goes beside dirauth and chain, with
                  --tor-reporter-operator. The install writes the reporter's home
                  (/var/lib/orama-global/reporter) with its operator, the
                  authority-id (the v3_ident the network file lists for
                  --tor-address) and the vote-interval (the network file's
                  voting_interval_minutes); the hot key is created when the reporter first
                  starts, and its address still has to be added to x/relay's
                  reporter set and funded.

--colocated installs the services on a machine that already runs a cluster node
(orama node setup first). The global units run in their own network namespace,
orama-global, joined to the root namespace by a veth pair (198.18.0.0/30): they
have their own loopback and port space, cannot reach the cluster's loopback,
WireGuard mesh or any private network, and only the ports they publish are
forwarded in. It writes orama-global-netns.service, two nftables rulesets and a
resolv.conf under /etc/orama-global, and records role both in preferences.yaml.
The machine must have iproute2, nftables, a kernel with network namespaces and
veth, and systemd 242 or newer; otherwise nothing is changed. A machine that is
co-located must keep using --colocated on later installs.

On a co-located machine the chain's RPC and REST API (and the indexer) are
reachable on the namespace address only by root and the cluster node's account.
--chain-client-user <name> (repeatable) also allows a local account, for example
the ssh login that tunnels to the chain or runs 'orama chain'; an unknown account
refuses the install, and the set is kept by later installs.

orama global register [flags]

Build MsgRegisterNode from bindings that 'orama global bind' wrote.

The message names the operator, a node id, roles, a hot key that is not the
operator, the bindings, public endpoints, an optional region and an optional
--asn, the autonomous system number the node declares. The chain cannot verify
the ASN; a protocol deal slot goes only to a node that declared one, and slots
go to distinct ASNs. Reserved, documentation and private-use numbers are
refused. It does not include a tenant list or a cluster secret.

--node is the chain REST API. The command reads the account there, asks the
RootWallet agent to sign this one transaction, and broadcasts it. Without
--node it prints the sign document and does not submit anything.

Each --binding file is the JSON bind printed. Its signature must verify for
this --chain-id and --operator.

orama global restart [service...] [flags]

Stop then start the named global services (all installed ones when none is
named). Restarting the chain restarts every installed service, chain first.

A directory authority is restarted one at a time, at least 30 minutes apart:
see "orama global stop". --force overrides the check. The refusal for an authority
that was started too recently exits with code 9 and changes nothing, so a script that
rolls authorities can wait and ask again on that code alone.

orama global retire [flags]

Retire a global node. The chain records its service pubkeys so they cannot
be bound again. Without --node the command prints the sign document and does
not submit it.

orama global start [service...]

Start the installed orama-global-* units, or only the named ones.

The chain starts first. Before it starts, a validator key migrated to this host
is checked against the sign state it last had on its old host; a state behind
it is refused, since it could sign a step the old host already signed. The other
services start once the chain's loopback RPC answers. Starting ipfs, provider,
archiver, indexer or repair alone needs the chain already running. The public
Kubo's GC timer starts and stops with it.

orama global stop [service...] [flags]

Stop the installed orama-global-* units, or only the named ones, in reverse
start order. Stopping the chain stops every installed service that needs it
first.

A directory authority is not stopped while another has started less than 30
minutes ago: a fresh authority casts no Running vote for that long and a
consensus needs two of the three (website/src/docs/operator/tor-network.mdx, "Directory authorities").
--force overrides it.

orama global tor

Show the Tor roles installed on this node. The authority key ceremony, the vote
archive, the relay monitor and the onion list are maintainer commands: see
'orama maint global tor'.

orama global tor info

For each Tor role installed on this node (directory authority, relay or exit,
validator onion service), print the nickname and fingerprints tor made (what
'MsgRegisterRelay' and a node's onion endpoint need), the onion address, and a
summary of the consensus the process holds: when it is valid, how many relays
it lists, and whether it lists this relay. A role that has not started yet shows
no identity. The root's --json prints the same as a JSON array.

orama global unbond [flags]

Start unbonding norama from one role on a registered global node.

The amount has to be covered by that role's bond. Without --node the command
prints the sign document and does not submit it.

orama maint global

orama maint global edit [flags]

Change a setting of the global layer installed on this node. 'orama edit' runs it over
SSH with the node's own CLI; it declares the same change on the chain from your
machine.

--storage-gb N sizes the public Kubo for N GB of declared capacity (its StorageMax
becomes N plus 10%) and restarts it; the repo, its identity and token stay. The
capacity itself is declared on the chain with MsgDeclareCapacity, which 'orama edit'
sends first: the chain refuses a capacity the role bond does not back, and one below
the bytes already reserved by deals.

--exit=true|false switches the Tor relay between a plain relay and an exit by
rewriting only the exit section of its torrc, then restarts the relay. An exit
needs a network whose file allows exits, and refuses the destinations listed in
the exit reject list.

orama maint global refresh [flags]

Put the staged release's global binaries in place of the installed ones and restart
the services that run them. 'orama upgrade' runs it on every node that has the
global layer, after the node's cluster services are upgraded, one node at a time.

Each binary the installed services need (orama, orama-global, ipfs) is read from
--staged-dir, held to the release manifest, and replaced atomically when its bytes
differ. A service is restarted only if the binary its own process runs was
replaced: the provider, archiver, indexer, repair delegate and reporter run
orama-global, the public Kubo runs ipfs, the onion service's gate runs orama. The
chain and the Tor relay or directory authority are never restarted by a refresh
(the chain runs oramad from the cosmovisor layout; Tor runs the distro's tor).

oramad changes only through a governed upgrade. When the release carries an oramad
other than the one cosmovisor runs, the refresh reads the chain's scheduled
upgrade plan: with one, it stages the release's oramad and shielded verifier for
that plan, and cosmovisor switches to them at the plan's height; without one, it
keeps the running oramad and says so. When the plan's info names a checksum for
this platform's binary, the release's oramad has to be that one or it is not
staged.

The chain indexer refuses an index written in an older layout than the new
orama-global's. So when the indexer is installed, the refresh stops it, runs
'orama-global indexer migrate' as the indexer's own account, not as root (which
renames an old index to <state>/indexer/index.v<layout>-<time> and deletes
nothing, and refuses an index path that is a symlink or not a directory), and starts it again;
the indexer then builds a new index from the chain. An index of the current layout
is left as it is. An indexer that is already crash-looping on an old index is put
right the same way, and one stopped on purpose stays stopped.

A service is restarted when its running process executes a file that has been
replaced (/proc/<pid>/exe is "(deleted)"), not because of what this run replaced:
a refresh that was interrupted is finished by running it again. A service that is
not running is not started by it, except an indexer that was failing on an old index.

orama maint global stage-oramad [flags]

Place an oramad binary where cosmovisor runs it, after it verifies against
the release root adopted at /etc/orama/release-root.json.

--upgrade <name> stages <home>/cosmovisor/upgrades/<name>/bin/oramad for the
upgrade plan <name>; cosmovisor switches to it at the plan's height. --genesis
stages <home>/cosmovisor/genesis/bin/oramad and points current at genesis if
current does not exist yet. A binary already there is refused.

The binary is copied into a root-only staging directory and verified there,
through the descriptor that wrote it, as --release-target in the TUF metadata
in --release-metadata (threshold, timestamp expiry, snapshot rollback, length
and hashes); only then is it linked into place. Every directory on the way is
opened without following symlinks and must be root's; a symlink or a
directory another account owns or may write is refused. Nothing stages
automatically: a validator's operator runs this for every chain upgrade.

The chain unit 'orama global install' writes runs cosmovisor, which reads this
layout; install places the first oramad here as the genesis binary.

orama maint global tor

The Orama Tor network is a separate anonymity network built from unmodified
upstream Tor code, run by Orama's own directory authorities (orama.network/docs/operator/tor-network).
The roles are installed by 'orama global install --services dirauth|relay|relay,exit|onion'.

orama maint global tor archive [flags]

Copy the consensus the authority holds, the votes that made it and, with
--bandwidth-file, the bandwidth file it voted with, from --data-dir into
--archive-dir/<valid-after>/ with a MANIFEST.json of SHA-256 digests. Every vote,
consensus and bandwidth file of the network is then recomputable by anyone who
holds the archive. Running it again changes nothing for a period that is
archived; a consensus is replaced only by the same consensus with more
signatures.
Before the authority's first consensus (up to one voting interval after the
authorities start) there is nothing to archive, and the run succeeds saying so.

With --export-votes-dir it also copies the authority's own vote of that period
to <dir>/<valid-after>.vote, the files the bandwidth reporter reads. The
directory must exist (the install makes it, shared read-only with the
reporter's group); nothing else of the data directory is copied there.

orama maint global tor authority-keys [flags]

Make the keys of ONE directory authority on this machine, which will run it: the
relay identity (tor --list-fingerprint) and the authority identity key, signing key and
12-month certificate (tor-gencert), the same programs and key handling as
'orama maint global tor ceremony'. The tor package of the Tor Project's repository
is installed first if it is missing.

Below --dir (default /var/lib/orama-tor-authority, root only) it writes
  offline/<nickname>/authority_identity_key   the identity key, encrypted, mode 0400
  offline/<nickname>/passphrase               its passphrase, generated here, mode 0400
  deploy/<nickname>/keys/                     the signing key, the certificate and the
                                              relay identity: what 'orama global
                                              install --services dirauth' reads, with
                                              --tor-authority-keys deploy/<nickname>
Nothing secret is printed or leaves the machine. The identity key is never in the
bundle and never in a tor DataDirectory.

It prints the public identity as one line of JSON: the nickname, address, ports, v3
identity, relay fingerprint, ed25519 identity, the certificate's expiry and whether
this run made the keys. Running it again reads the keys back and checks them; keys
are never made over keys, and a directory that holds part of a set is an error.

This is how 'orama setup --create-network' makes the authorities of a new network's own Tor
network, on a test network. The passphrase beside the key is that arrangement's trade-off:
a production network runs the ceremony on an offline machine instead.

orama maint global tor ceremony [flags]

Generate the keys of a set of directory authorities with the upstream tor and
tor-gencert, which must be installed on this machine, and write the network file.

Run it on an air-gapped machine. For each --authority NICKNAME=IPv4 it writes,
below --out:
  offline/<nickname>/authority_identity_key   the identity key, encrypted with the
                                              passphrase; it signs certificates and
                                              nothing else. Move it to offline media
                                              (encrypted, in two places, or an HSM)
                                              and delete it from this machine.
  deploy/<nickname>/keys/                     what the authority host installs: the
                                              signing key and its 12-month
                                              certificate, and the relay identity.
and once tor-network.json (public: the authority list every relay and client
needs, to stage beside the release) and TRANSCRIPT.txt (the fingerprints to read
aloud and sign). --out must not exist or be empty: a ceremony never writes over
keys.

--passphrase-file holds the identity-key passphrase (at least 16 characters, one
line, mode 0600). Authority ports are fixed at 31020 (ORPort) and 31021 (DirPort),
the ports the global firewall opens. --bootstrap (default) writes the network file
with bootstrap true, which a new network needs for its first consensus; set it to
false in the file once the first consensus is signed. --allow-exit puts allow_exit
in the file: only a network whose owner runs exits sets it.

orama maint global tor monitor [flags]

Write <home>/monitor.json with whether the consensus the relay or directory authority
holds lists it: {"in_consensus": true|false}. 'orama status node' shows it on the Global
line and the node report raises a warning when the node is not listed. The field is left
out (the file is "{}") while the node has no consensus yet or the one it holds has
expired, so an unknown state is never reported as a no. It reads only the role's own
DataDirectory and writes only monitor.json there.

orama maint global tor onions

orama maint global tor onions add ADDR.onion[:PORT]... [flags]

A validator's onion address exists only once its onion role has started, which
is after the ceremony wrote tor-network.json. Read it on the validator with
'orama global tor info' (as root), then add it to the network file here and
republish the file to clients: orama maint vpn, --onion-network and the relay reporter
all read validator_onions from it.

Each address is checked as a v3 onion address with an optional port (default 80,
the port the onion service answers on). An address already listed is not listed
twice. The file is replaced atomically and must already be a valid network file;
nothing is written when an address is refused. Relays and authorities ignore
validator_onions, so adding an onion never needs a node restart.

orama maint global txgate [flags]

Serve the three calls a wallet needs to submit one transaction (read the signer's
account, broadcast, look the transaction up) from the chain's REST API, and
nothing else. The validator's onion service forwards to this listener, so the
rest of the chain API is not reachable over the onion. Requests arrive from the
local Tor process, so the limits are on the whole gate and no request is logged.
--listen must be a loopback address.

orama maint global validator

orama maint global validator check-sign-floor

The double-sign guard. orama-global-chain.service runs it as root before every
start (ExecStartPre), from /usr/lib/orama-global/bin, where 'orama global
install' puts this CLI. With no sign floor recorded it passes. With one, it
fails when priv_validator_key.json is missing (the key moved to another host)
or priv_validator_state.json is behind the floor.

orama maint global validator edit [flags]

Build x/staking MsgEditValidator for the operator's validator. Only the flags
given change; every other description field is sent as [do-not-modify]. An empty
value clears that field. --commission-rate is a decimal from 0 to 1; x/staking
allows one commission change per 24 hours, within the validator's
max-change-rate. Without --node the command prints the sign document.

orama maint global validator export-key [flags]

Seal priv_validator_key.json to --recipient, an X25519 public key (64 hex
characters), with the same ORBK seal as a namespace backup, and write it to --to.
The node never holds the private half, so it cannot open the file. --to must
not exist.

To restore the key on a new host, run 'orama maint global validator migrate prepare'
there, then 'orama maint global validator reseal' on the machine holding the private
key, then 'orama maint global validator migrate import' on the new host. Restore only
when the old host is gone: two hosts signing with one key is a double sign.

orama maint global validator migrate

Move priv_validator_key.json and priv_validator_state.json from this host to
another, in three steps, each run as root:

  1. on the new host:  orama maint global validator migrate prepare
  2. on the old host:  orama maint global validator migrate export --recipient <key> --to <file>
  3. copy <file> to the new host, then:
                       orama maint global validator migrate import --from <file>

export stops and disables the old host's chain (and stops the services that
need it) before it reads anything. It seals the key and state in memory, records
the state as the old host's sign floor, keeps a copy of the state, moves the key
out of the chain home, and then writes the bundle. The chain unit checks the
floor before every start, so the old host's chain no longer starts: the floor is
recorded and the key is gone. import refuses while the new host's chain runs,
records the old host's last sign state as the new host's floor, writes the
state, and installs the key last; the chain unit then refuses to start from a
state behind the floor. cancel removes a prepared migration key.

A bundle from 'orama maint global validator reseal' (a restored backup) has no sign
state. Its import needs --old-host-destroyed and --floor-height with the
network's latest committed height H. The floor and the state become height H+1,
round 0, before any step: the restored key signs nothing at or below H, in any
round. It can sign at H+1, so a vote the lost host cast at H+1 is excluded only
if that host stopped before H+1 began.

orama maint global validator migrate cancel

orama maint global validator migrate export [flags]

orama maint global validator migrate import [flags]

orama maint global validator migrate prepare

orama maint global validator reseal [flags]

Open a key backup from 'orama maint global validator export-key' with the operator's
X25519 private key (--identity-file, hex, mode 0600) and seal the key to the new
host's migration key (--recipient, printed by 'orama maint global validator migrate
prepare'). Run it on the machine that holds the private key, not on a node. The
bundle carries no sign state: nobody knows what a lost host last signed. Its
import therefore needs --old-host-destroyed and --floor-height <the network's
latest committed height>; the key then signs only above that height.

orama maint global validator unjail [flags]

Build x/slashing MsgUnjail for the validator whose operator account is
--operator (the same bytes as its oramavaloper address), signed by that account.

x/slashing refuses it while the jail period runs, when the validator has no
self-delegation or less than its minimum, and for a tombstoned validator, which
can never unjail. Without --node the command prints the sign document and does
not submit it; with --node the RootWallet agent signs and it is broadcast.