KLYRN
Install Free
KLYRN Web

    All documentation
    1. Home
    2. Docs
    3. KLYRN to KLYRN

    KLYRN to KLYRN: the Move

    Two KLYRN servers need no root SSH login between them. The source mints a grant for one account, and the destination redeems it over the pinned panel port.

    Proven and unproven

    A move has never crossed a real link. It has been run between two full KLYRN installs in two containers on one machine, over a virtual link through the host. Each install had its own configuration, database, panel certificate and port. That proves the protocol, the fidelity, the refusals and the grant's destination binding. It proves nothing about latency, loss or throughput, so no numbers are published.

    • rsync over a move is not built. A move uses the manifest strategy. A stream that breaks at 90% of a 4 GB video re-sends that video.
    • There is no panel screen for a move. CLI and API only.
    • Resume after a break has not been demonstrated live. TCP retransmits survived a deliberate six-second link cut. The pass never failed, and move resume correctly reported nothing to resume.
    • The destination cannot suspend the source. The move prints the command and records that it was not run.

    Before you start

    Both servers running KLYRN
    The source's panel port, 7443 by default, must be reachable from the destination. SSH on the source can stay closed.
    Three strings from the source
    The panel address, the certificate fingerprint and the token. The token is printed once.

    On the source, as an administrator:

    klyrn move grant --account shop --to <destination install id> --hours 24 --note "new box"
klyrn move grants
klyrn move revoke 4

    On the destination, as an administrator:

    export KLYRN_MOVE_TOKEN=klyrnmv_12.…
klyrn move preflight --from panel.old.example.com:7443 --fingerprint SHA256:…
klyrn move start     --from panel.old.example.com:7443 --fingerprint SHA256:…
klyrn move status 1
klyrn move sync 1        # the final pass
klyrn move abort 1

    Prefer the environment variable to --token. A flag lands in /proc/<pid>/cmdline, which is world-readable on a stock Linux. /proc/<pid>/environ is not. --token still works.

    The grant

    One subject
    An account, or a single site.
    One taker
    The destination's install id. Without --to, any server holding the token can take the subject until it expires.
    Bounded
    24 hours by default, a week at most.
    Revocable
    Every stream re-checks it, so klyrn move revoke stops a running move.
    Hashed
    Only the SHA-256 of the secret is stored. Mint another if the token is lost.
    Read-only
    The caller names a stream and a subject, never a command.

    The channel is TLS to the source's panel, pinned to the fingerprint in the grant: SHA256: and the base64 SHA-256 of the certificate’s public key information. A renewal that keeps the same key keeps the grant valid. klyrn move grants shows each grant's first use, last use and use count.

    What migrates

    The destination asks the source for a configuration document and applies it.

    Files
    The whole document root, by the ownership rules of every migration.
    Databases and their users
    Re-prefixed to the destination account. Passwords are regenerated and written into wp-config.php and .env.
    Site configuration
    Domains, aliases, redirects and www mode. The PHP version and per-site pool limits. nginx rules. Custom certificates, with key and chain. Cron, account-level and per-site.
    The resource policy
    Within the destination's entitlement limits, and only when a package of that name exists there.
    Container applications
    Definitions, routes and volumes. The destination pulls the exact image digest from the registry and refuses different bytes.

    What arrived is compared against the source. Both servers list the tree, and the listings are compared on path, size, mtime to the second, the owner's permission bits and symlink target. Content is not read.

    What does not migrate

    Each of these is named on the preflight and in the move's status:

    • Backup history, logs, metrics and resource history. The destination takes its own first backup after cut-over.
    • Mail. No mailbox is carried and no MX record is touched.
    • Certificates KLYRN issued. Re-issued once DNS points at the destination.
    • Site secrets. They are sealed with the source's own key. The configuration document counts them.
    • Deployment history. Only the release that is serving travels.
    • The basic-auth password file. Set the password again on the destination.
    • A Node application's code. The site is refused.

    Downtime

    klyrn move start is the pre-copy. klyrn move sync is the final pass, and its wall time is the downtime. The status then prints its seconds, bytes and file count.

    • Files. Only those whose size or mtime differ travel.
    • Databases. A fresh snapshot of each, in full.

    Sites move one at a time, each resumable on its own. Account-level settings are applied once at the start.

    Preflight and refusals

    klyrn move preflight creates nothing. klyrn move start runs the same checks again.

    “example.com already exists on this server, under account other”
    Remove or rename it here, or leave that site out with --site. A claimed alias or redirect name refuses the same way.
    “runs a Node application, whose code lives outside the document root and cannot travel over a move grant”
    The refusal prints the start command, Node version, port, memory limit and health path. Deploy the site here from git, then name each remaining site with --site.
    “2 database(s) of that name already exist here”
    Move into another account with --account, or remove them here.
    The licence limit
    A free edition that allows five sites and has four cannot take three.
    “there is not enough room on this server”
    The move's size plus 15% is needed.
    “this grant does not reach a site called ”
    The message names what the grant covers.
    “there is nothing to move”
    No sites selected and no applications to carry.
    A container runtime that cannot take the applications
    Not installed, not reachable, or speaking an API version KLYRN does not pin.

    Three warnings:

    • An account of that name exists here. The moved sites are added to it.
    • A system user of that name exists outside KLYRN. The account is renamed and the database names re-prefixed.
    • A PHP version is not installed here. The site runs on this server's default.

    Cut-over

    1. Pre-copyklyrn move start. klyrn move status shows where each site is. Look at the sites here.
    2. Lower the TTLHours before the switch.
    3. Final syncklyrn move sync <id>. It ends with the cross-server comparison, and prints any mismatch file by file.
    4. Suspend the old copy yourselfOn the source: klyrn account suspend <name> or klyrn site suspend <domain>.
    5. Point DNS at the destinationThen klyrn move revoke <id> on the source.

    Rollback

    The source is never written to.

    1. Roll back the destinationklyrn move abort <id> removes only the sites, files and databases the move created here. It refuses while a job for the move is running.
    2. If you had suspended the sourceUnsuspend it there and point DNS back.
    3. To stop a move in flightRevoke the grant.

    Troubleshooting

    “the grant is no longer held (klyrn-core restarted); pass --token to resume or sync”
    Or set KLYRN_MOVE_TOKEN.
    “that is not a move token”
    The token looks like klyrnmv_12.<secret>.
    “a move will not run over plain http”
    Use the https address the grant printed. A self-signed certificate is fine.
    The move stops after the grant was revoked
    Mint a new grant and klyrn move resume.
    “DIFFERS” in the verified column
    klyrn move status prints each entry that is missing, extra or different. Resume the move.
    “a job for this move is still running; wait for it to stop before rolling back”
    Wait, then abort.
    A site arrives suspended
    It was suspended on the source.
    The panel port is closed to the destination
    Use the SSH route.
    Discord WhatsApp