Customer Setup — On-Premise License Installation

This guide is for on-premise customers who receive a license token from the vendor and need to deploy it to their Yabanin gateway or admin server.

What You Receive

From your vendor contact, you will get:

1. License token file — a JSON file (e.g., acme-corp.json) containing your org identifier, expiry date, and cryptographic signature.
2. Root public key — 64 hex characters (32 bytes) representing the vendor's Ed25519 root public key. This is embedded in every production binary at build time.
3. (Optional) Intermediate certificate file — intermediate.json
4. (Optional) CRL (Certificate Revocation List) file — crl.json

Step 1 — Place the License File

Copy the license token to your server:

mkdir -p /etc/yabanin/license
cp acme-corp.json /etc/yabanin/license/
chmod 600 /etc/yabanin/license/acme-corp.json   # restrict access

Step 2 — Configure Environment Variables

Add the following environment variables to your service's environment:

For systemd services

Edit /etc/systemd/system/yabanin-admin.service (or yabanin-gateway.service):

[Service]
Environment="YABANIN_LICENSE_FILE=/etc/yabanin/license/acme-corp.json"
Environment="YABANIN_LICENSE_ROOT_PUBKEY=a1b2c3d4e5f6a1b2c3d4e5f6..."
# Optional:
Environment="YABANIN_LICENSE_CRL_FILE=/etc/yabanin/license/crl.json"

Then reload and restart:

systemctl daemon-reload
systemctl restart yabanin-admin

For Docker / docker-compose

In your docker-compose.yml:

services:
  admin:
    environment:
      - YABANIN_LICENSE_FILE=/data/license/acme-corp.json
      - YABANIN_LICENSE_ROOT_PUBKEY=a1b2c3d4e5f6a1b2c3d4e5f6...
      - YABANIN_LICENSE_CRL_FILE=/data/license/crl.json
    volumes:
      - ./license:/data/license:ro

For direct binary execution

export YABANIN_LICENSE_FILE=/etc/yabanin/license/acme-corp.json
export YABANIN_LICENSE_ROOT_PUBKEY=a1b2c3d4e5f6a1b2c3d4e5f6...
./yabanin-admin

Step 3 — Verify Startup

After starting the service, check the logs:

# Successful startup:
# License verified successfully
# admin panel running addr=:8086

# Failed startup (license invalid):
# FATAL: LICENSE INVALID — license expired at 2025-01-01T00:00:00Z — service cannot start without a valid license
# (exit code 1)

Step 4 — Verify License Validity (Optional)

You can independently verify the license before or after deployment:

./yabanin license verify \
  --license-file=/etc/yabanin/license/acme-corp.json \
  --root-pubkey=a1b2c3d4e5f6a1b2c3d4e5f6... \
  --crl-file=/etc/yabanin/license/crl.json

# Output: LICENSE VALID

License Expiry and Grace Period

Time since expiry	Behavior
Not expired	Full operation
0 — 7 days	Degraded mode (logged as "expired")
> 7 days	Hard-expired; service refuses to start

The 7-day grace period allows time to request a renewed license from the vendor without immediate service disruption.

Renewing Your License

When your license approaches expiry:

1. Contact your vendor with your customer_id (found in the license JSON).
2. The vendor issues a new token with an updated expiry date.
3. Replace the old file and restart the service:

cp new-license.json /etc/yabanin/license/acme-corp.json
systemctl restart yabanin-admin

Troubleshooting

Symptom	Cause & Fix
"LICENSE INVALID — license expired"	Token expired. Request a new one from vendor.
"LICENSE INVALID — intermediate verification"	Root public key mismatch. Confirm the hex value matches what vendor provided for this binary build.
"read license file: no such file or directory"	Check YABANIN_LICENSE_FILE path and file permissions (must be readable by the service user).
"parse root pub: encoding/hex: invalid byte"	Root public key hex is malformed — must be exactly 64 hex characters, no spaces.
"intermediate cert serial X is revoked"	Vendor published a CRL revoking your intermediate. Request a new license from vendor.

Security Best Practices

• File permissions: Keep the license file at 0600 (owner read/write only).
• Read-only mount: If using Docker, mount the license directory as :ro.
• Never commit license files to version control.
• Rotate promptly when receiving a renewed token — old tokens remain valid until their expiry date.