IPFS services settings
Part of the configuration reference. Covers the two
standalone IPFS binaries — sithbit-ipfsd (the self-hosted pin daemon
fleets can share) and sithbit-gateway (the read-only HTTP path gateway)
— plus the [swarm] service-record freshness settings shared by
sithbit-ipfsd and sithbitd’s own embedded node.
sithbit-ipfsd
The self-hosted IPFS node as its own daemon: the same embedded
repo/swarm sithbitd can run in-process, behind a small HTTP pin API
(POST/DELETE /pins/{name}, GET /ipfs/{cid}) for fleets that share
one node via [ipfs] kind = "remote". Config file sithbit_ipfsd.toml
(or SITHBIT_IPFSD_CONFIG), env prefix SITHBIT_IPFSD_. Row markers on
this page’s tables follow the going-public
legend.
| Key | Default | Meaning |
|---|---|---|
bind_addr | "127.0.0.1:8182" | REQUIRED (public). HTTP listen address for the pin API. The loopback default is what keeps that write surface private; any other address exposes it to whatever can route there, so the daemon refuses to start on a non-loopback address unless auth_token is set (IPv4 and IPv6 loopback are exempt) |
auth_token | (unset — open) | REQUIRED (public). Enforced at startup. Bearer token required on every request when set. Unset (or blank), the token check passes every request, so a non-loopback bind_addr would leave the pin API (a write surface that stores and unpins blocks) open to everything that can reach the port — IpfsdConfig::validate refuses that pairing before the daemon listens, naming both settings and the remedy (set the token, or bind loopback). A loopback bind_addr needs no token |
max_pin_bytes | 33554432 (32 MiB) | RECOMMENDED (public). POST body limit; larger uploads are refused with 413. Size it against the largest object your fleet pins rather than inheriting the dev default |
[blobs] | local ipfs/ dir | REQUIRED (public). The local ipfs/ directory is single-host storage; a fleet needs the shared S3/Azure bucket every daemon writes and sithbit-gateway reads. Block/pin storage — the same shape and semantics as sithbitd’s [ipfs.blobs] |
[swarm] | (unset — no swarm) | RECOMMENDED (public). Absent, the node keeps its blocks to itself — decide deliberately whether this daemon joins a public DHT. When it does, identity_file becomes REQUIRED (public): without a persisted identity the PeerId changes on every restart and the DHT forgets the node. Identical to sithbitd’s [ipfs.swarm] (listen/bootstrap/provide/kad_protocol/identity_file); every pin announces to it, and pinned blocks serve over bitswap |
[cluster] | (unset — solo, no GC) | RECOMMENDED (public). Absent means a solo node and no garbage collection, so unreferenced blocks accumulate indefinitely; more than one daemon over one bucket needs the section. Identical to sithbitd’s [ipfs.cluster] (heartbeat/TTL/GC settings): N daemons over one [blobs] bucket heartbeat a membership roster in the bucket, partition the DHT reprovide keyspace by rendezvous hashing, and GC unreferenced blocks. See Scaling out |
[health], [observability] | (the shared defaults) | RECOMMENDED (public). The two shared sections; this binary’s health port is in the Monitoring table |
[swarm] — service-record freshness
When a node advertises itself for decentralized service
discovery — publishing a signed
service record on the DHT so clients
can find its POP/IMAP endpoints without DNS SRV — two settings in the swarm
section govern how fresh that advertisement stays. They live under
[ipfs.swarm] for sithbitd and under [swarm] for sithbit-ipfsd (the same
section that carries listen/bootstrap/provide/identity_file), and both
have in-code defaults, so an empty swarm section is still valid — a plain node
that never advertises a service simply ignores them.
| Key | Default | Meaning |
|---|---|---|
service_record_ttl_secs | 900 (15 min) | How long an advertised record stays fresh from its created_at stamp. Deliberately minutes-scale — service liveness wants minutes, unlike the ~22 h content-reprovide cadence — so a node that stops heartbeating ages out of discovery quickly. Validated on the client’s DHT get, so a lapsed record is dropped before it is ever trusted |
service_heartbeat_interval_secs | 300 (5 min) | How often the node re-stamps created_at and re-publishes its records. Keep it comfortably below service_record_ttl_secs so a record never lapses between heartbeats (the default 5 min ≪ 15 min TTL leaves two missed beats of slack) |
reprovide_interval_secs | 79200 (22 h) | How often the node re-announces its provider records for every pinned block. DHT provider records expire (~24 h on the public network), so long-lived pins must be re-provided inside that window — keep it below the expiry with some slack, as the default does |
kad_protocol | "/ipfs/kad/1.0.0" | Kademlia protocol id to speak. The default is the public IPFS network’s; on a private network set "/ipfs/lan/kad/1.0.0" — Kubo runs a separate LAN DHT under that id for peers without public addresses and filters private-address peers out of the public one |
These settings affect only advertisement freshness. Authority — who may
serve the domain — is proved separately by the node’s
delegation chaining to the
on-chain MailDomain.authority, checked by the client both on the DHT record
and in the self-authenticating TLS
handshake,
never by these timers. A public DHT advertising POP/IMAP endpoints is
enumerable, so the usual [*.server] connection limits and DNSBL/DBL still
apply to the listeners those records point at.
sithbit-gateway
The read-only IPFS HTTP path gateway: GET/HEAD /ipfs/{cid}
(deserialized, plus trustless ?format=raw|car) over the same
block/pin bucket the node writes; locally-absent CIDs answer 404 — it
never fetches from the IPFS network. Config file ipfs_gateway.toml
(or IPFS_GATEWAY_CONFIG), env prefix IPFS_GATEWAY_.
| Key | Default | Meaning |
|---|---|---|
bind_addr | "127.0.0.1:8183" | REQUIRED (public). HTTP listen address; the loopback default serves no remote reader. The surface is read-only, so no auth gate exists — bind it where readers live, behind the TLS-terminating proxy |
public_host | (unset — path gateway only) | RECOMMENDED (public). Set it if browsers will load content from this gateway — subdomain routing is what gives each CID its own browser origin — and leave it unset otherwise. Base domain for the subdomain (Host-based) gateway: set it to also serve <base32-cidv1>.ipfs.<public_host> browser-origin-isolated requests. Unset keeps path routing only |
[blobs] | local ipfs/ dir | REQUIRED (public). The local ipfs/ default is a separate, empty store from the fleet’s, and every lookup against it answers 404. Block/pin storage — the same shape as sithbit-ipfsd’s [blobs]; point it at the shared bucket the node/cluster pins into. The gateway only reads it |
[health], [observability] | (the shared defaults) | RECOMMENDED (public). The two shared sections; this binary’s health port is in the Monitoring table |