Skip to content

Scordo — Administrator Guide

Purpose

This guide is for node operators, system administrators, and DevOps engineers responsible for building, deploying, and operating the Scordo router and its bundled applications.

Use this guide together with:

  • README.md — source and build quick-reference
  • Docker.md — Docker and Compose setup reference
  • docs/USER_MANUAL.md — end-user guide for the router console and applications
  • docs/production-program/SCORDO_PRODUCTION_PROGRAM.md — production program phase gates
  • SCORDO_OPERATIONAL_TODOS.md — cross-repo governance and ops backlog

1. System Overview

Scordo is the reference Java implementation of a privacy-preserving mesh network router. It provides the transport layer and application suite for an anonymized peer-to-peer overlay network.

Bundled applications:

Application Purpose Default Port
Router Console Web UI for router monitoring and configuration 7657
ScordoMail Anonymous email over the mesh 7659 (SMTP), 7660 (POP3)
ScordoDNS (Addressbook) Distributed naming / host lookup —
Snark Anonymous BitTorrent-compatible file sharing —
HTTP Proxy Outbound proxy for browsing scordosites 4444
SOCKS Proxy SOCKS5 outbound proxy 4444
SAM Bridge Client API for custom applications 7656
I2CP-compatible bridge Legacy client protocol 7654
IRC Tunnel IRC-over-mesh profile 6668
Tunnel Manager Inbound/outbound tunnel configuration 7657 (via console)

Key characteristics:

  • Transport is fully anonymised; the router does not expose originating IP to the mesh
  • All configuration and identity material is stored in the router config directory (default: ~/.scordo on the host, /scordo/.scordo in Docker)
  • First start generates a new router identity and performs initial network integration (bootstrapping takes several minutes)
  • A firewalled state indicates the external port is not reachable from the public internet; set EXT_PORT and ensure the port is forwarded for best performance

2. System Requirements

Component Minimum
Java SDK 17+ (OpenJDK or Oracle JDK recommended)
RAM 512 MB minimum; 1–2 GB recommended for active usage
Disk 100 MB for installation; additional for Snark downloads and netDb growth
Network Open TCP+UDP port for transport (default 12345)
OS Linux, FreeBSD, macOS, Windows

For build only (not required for Docker deployment):

Tool Minimum
Apache Ant 1.9.8+
GNU gettext xgettext, msgfmt, msgmerge
Locale UTF-8

3. Deployment

3.1 Building from source

Ant (primary):

# x86 systems
ant pkg

# Linux non-x86
ant installer-linux

# FreeBSD
ant installer-freebsd

# macOS
ant installer-osx

# See all build targets
ant

Gradle (compile-only; no full installer support yet):

./gradlew assemble

To build through a SOCKS proxy (e.g. Tor), add to ~/.gradle/gradle.properties:

systemProp.socksProxyHost=localhost
systemProp.socksProxyPort=9150

CI builds are available from the continuous integration page.

Javadoc:

ant javadoc
# Open: build/javadoc/index.html

3.2 Docker — quick start

Build image locally:

docker build -t scordo/scordo:local .

Run with persisted config and all ports loopback-only:

docker run -d \
  --name scordo \
  -e JVM_XMX=512m \
  -v scordoconfig:/scordo/.scordo \
  -v scordosnark:/scordosnark \
  -p 127.0.0.1:7657:7657 \
  -p 127.0.0.1:7650:7650 \
  -p 127.0.0.1:7656:7656 \
  -p 127.0.0.1:4444:4444 \
  scordo/scordo:local

Open the router console at http://127.0.0.1:7657.

services:
  scordo:
    image: scordo/scordo:local
    container_name: scordo
    environment:
      JVM_XMX: 512m
      EXT_PORT: 12345
    volumes:
      - ./scordoconfig:/scordo/.scordo
      - ./scordosnark:/scordosnark
    ports:
      - "127.0.0.1:7657:7657"   # Router Console
      - "127.0.0.1:7650:7650"   # HTTP proxy
      - "127.0.0.1:7656:7656"   # SAM bridge
      - "127.0.0.1:4444:4444"   # SOCKS/tunnel
      - "12345:12345/tcp"        # Transport
      - "12345:12345/udp"        # Transport
    restart: unless-stopped

Start:

docker compose up -d

3.4 Standard (non-Docker) installation

Download the installer from https://scordo.net/download and follow INSTALL.txt. The installer creates the Scordo home directory and registers a system service on supported platforms.

4. Configuration

4.1 Config directory

All router configuration, identity keys, tunnel settings, and cached network data are stored in the config directory:

Context Default path
Standard install ~/.scordo/
Docker /scordo/.scordo/ (mount as a persistent volume)

This directory must be persisted across restarts. Deleting it causes the router to generate a new identity — it will be unknown to the network and must re-integrate from scratch.

4.2 Environment variables (Docker)

Variable Default Description
JVM_XMX 512m JVM maximum heap size
EXT_PORT unset External transport port advertised to peers; set to the port forwarded on your NAT/firewall
IP_ADDR auto Container IP address; auto-detected at startup if unset

4.3 Port reference

Port Protocol Default bind Purpose
7650 TCP 127.0.0.1 HTTP proxy / control workflow
7654 TCP 127.0.0.1 I2CP-compatible client protocol
7656 TCP 127.0.0.1 SAM bridge
7657 TCP 127.0.0.1 Router console
7658 TCP 127.0.0.1 Scordosite / webserver tunnel
4444 TCP 127.0.0.1 SOCKS/tunnel listener
6668 TCP 127.0.0.1 IRC tunnel profile
7659 TCP 127.0.0.1 SMTP tunnel profile
7660 TCP 127.0.0.1 POP3 tunnel profile
4445 TCP 127.0.0.1 HTTPS/CONNECT proxy
12345 TCP+UDP 0.0.0.0 Router transport (public)

Bind admin and proxy ports to loopback (127.0.0.1) on any host shared with untrusted users. The transport port (12345 by default) must be reachable from the internet for best router performance; if it cannot be reached, the router operates in a firewalled state.

4.4 Bandwidth and performance tuning

From the router console (Configuration → Bandwidth):

  • Set share bandwidth limits appropriate for the hosting environment.
  • For a floodfill-capable node (mesh infrastructure role), increase tier limits and enable the FloodfillParticipant role in advanced settings.
  • For minimal-footprint deployments, reduce share bandwidth and disable non-essential tunnel profiles.

5. Bootstrap and Reseed

When first starting or after a long offline period, the router must reseed from known nodes to discover the rest of the network.

  • Reseed endpoints are bundled in installer/resources/certificates/reseed/.
  • The router attempts automatic reseed from these endpoints on first start.
  • If automatic reseed fails, manually download a signed scordoseeds.su3 from a known reseed endpoint and import it via Configuration → Reseed in the router console.
  • For a private mesh deployment, operate your own reseed servers (at least 2, geographically distributed) and point new routers at them before enabling external reseed.

6. Certificate and Key Management

Router identity keys are stored in the config directory. Reseed signing certificates are in installer/resources/certificates/reseed/. TLS trust material for reseed HTTPS is in installer/resources/certificates/ssl/.

Key rotation and emergency procedures:

  • Do not delete the router config directory unless intentionally abandoning the identity.
  • For reseed signing key rotation, replace the certificate bundle in installer/resources/certificates/reseed/ and re-sign the scordoseeds.su3 file.
  • In a key compromise event, rotate immediately, notify mesh participants, and rebuild the certificate trust bundle. Document the event in the ops log.

7. Monitoring and Health

7.1 Router console

The router console at http://127.0.0.1:7657 provides:

  • Summary / Home — current network status, tunnel count, bandwidth utilization
  • Network Database — peer count, floodfill status, reseed status
  • Tunnels — active tunnel pools by application
  • Peers — known peer list with status and profile data
  • Graphs — bandwidth, tunnel build success rate, latency
  • Stats — detailed routing statistics

7.2 Container logs

# Follow logs
docker logs -f scordo

# View port mappings
docker port scordo

7.3 Health indicators

Indicator Healthy value
Network status OK or Testing
Active peers > 50 for a well-connected node
Tunnel build success rate > 60%
Reseed status Complete
Firewalled state No (if transport port is forwarded)

If the router shows Firewalled, verify that EXT_PORT matches the port forwarded on the host/NAT and that the firewall rule is active.

8. Upgrades

8.1 Docker upgrade

# 1. Build or pull a new image
docker build -t scordo/scordo:vNEW .

# 2. Stop and remove the old container
docker stop scordo
docker rm scordo

# 3. Start a new container with the same config volume
docker run -d \
  --name scordo \
  -e JVM_XMX=512m \
  -e EXT_PORT=12345 \
  -v scordoconfig:/scordo/.scordo \
  -v scordosnark:/scordosnark \
  [... ports ...] \
  scordo/scordo:vNEW

The config volume preserves router identity, tunnels, and addressbook across the upgrade.

8.2 Standard install upgrade

Use the built-in Update function in the router console (Help → Update), or download a new installer from https://scordo.net/download and run it over the existing installation.

9. Incident Response

Router will not start (Docker)

  1. Check container exit code: docker inspect scordo --format='{{.State.ExitCode}}'
  2. Check startup logs: docker logs scordo
  3. Verify Java version inside the container: docker run --rm scordo/scordo:local java -version
  4. Confirm the config volume exists and is mounted correctly: docker volume inspect scordoconfig
  5. If the config is corrupted, move the config volume aside and allow a fresh start (new router identity will be generated).

Router in firewalled state (no external connectivity)

  1. Confirm EXT_PORT env var matches the port exposed in the Compose/run config.
  2. Confirm the host firewall allows TCP and UDP on that port from the internet.
  3. For NAT environments, confirm port forwarding is active to the host or container IP.
  4. In the router console, check Configuration → Network for the detected external address.

All tunnels failing to build

  1. Check bandwidth: confirm the router has enough allocated share bandwidth.
  2. Check peer count: fewer than 10 active peers indicates a network isolation problem.
  3. Attempt a manual reseed: Configuration → Reseed → Reseed Now.
  4. Restart the router after a successful reseed.

Mesh isolation (private network can't find peers)

  1. Confirm reseed endpoint is reachable from the new router.
  2. Confirm router.networkID policy matches across all mesh participants (private meshes must use a unique network ID not shared with the public Scordo network).
  3. Verify reseed signing certificates match on all nodes.

Out-of-memory / JVM crash

  1. Increase JVM_XMX (e.g. 1g or 2g).
  2. On Linux, confirm the host has enough free memory before starting the container.
  3. Review Snark (torrent) disk usage — large Snark downloads can indirectly stress the JVM through index overhead.

10. Git and CI Policy

The repository uses a local git hook to enforce branch and remote policy.

Install on each clone:

./scripts/bootstrap-git-policy.sh --fix

This configures .githooks/pre-push to:

  • Block pushes to any remote other than origin (https://github.com/cosimoglobal/Scordo.git)
  • Require pull request source branches to use approved prefixes: review/, feat/, fix/, chore/, refactor/, release/, hotfix/, security/, ci/, docs/, dependabot/

CI workflows are in .github/workflows/. The primary Ant CI workflow runs on self-hosted (jfos-mac-mini).

11. Branding and UI Status

The Scordo branding rebranding program is tracked in BRANDING_LEDGER.md, BRANDING_ROADMAP.md, and PRODUCTION_READINESS_STATUS.md. Current status (May 2026): Phase 3 naming refactor complete; visual/UI asset replacement, CSS migration, JSP template updates, and message catalog localisation remain in progress.

Do not remove or replace UI assets without consulting BRANDING_LEDGER.md to avoid mismatches in the phased rebranding program.

12. Documentation Map

  • README.md — source, build, and contact quick-reference
  • Docker.md — Docker and Compose configuration reference
  • docs/ADMINISTRATOR_GUIDE.md — this file
  • docs/USER_MANUAL.md — end-user guide for the router console and applications
  • docs/HACKING.md — developer build environment and source code guide
  • docs/production-program/SCORDO_PRODUCTION_PROGRAM.md — production program phase gates
  • docs/production-program/SCORDO_PRODUCTION_STATUS.md — current production status
  • SCORDO_OPERATIONAL_TODOS.md — operational backlog and governance alignment
  • SCORDO_BRAND_GUIDELINES.md — visual identity standards
  • SCORDO_PROTOCOL_DECISIONS.md — wire protocol decision log