An Xray upgrade needs a recoverable binary-and-configuration pair, while a host migration also needs an explicit endpoint and resource-retirement plan. Change one variable at a time, check the target configuration before starting it, and preserve later credential revocations when you roll back.

Key Takeaways:

Inventory the effective service, including drop-ins, runtime user and data files.

Use a fixed official release and keep a trusted old binary with its matching configuration.

Parsing success is not proof of client compatibility or traffic behavior.

What does this Xray upgrade procedure assume?

This guide targets native Xray on Ubuntu 24.04 LTS with systemd, using the FHS-style paths documented by Xray-install. The example target is the official stable Xray-core v26.3.27; it is a fixed example, not a claim that every installation should upgrade to it. Review the intervening release notes from your current version. The article follows official documentation and has not undergone a complete author end-to-end test.［1］［2］

Use the self-hosting operations framework to establish ownership first. Have sudo rights, a verified independent console, a maintenance window, an authorized canary client, protected backups, and the ability to restore the old version. Do not perform these steps on a shared production instance without permission to interrupt it.

This is not a panel-database migration. If a panel, container image or package manager owns your deployment, use its supported backup and lifecycle workflow instead of overwriting its managed files. A database export is not a universal backup of Xray's binary, JSON configuration, credentials, rules and certificates. The Xray and V2Ray component explanation helps identify which executable actually serves your clients.

Choose one branch: upgrade the binary on the existing host while keeping its endpoint, or migrate the existing trusted version to a new host before upgrading later. Combining an OS move, core upgrade, transport change and key rotation makes a failed canary difficult to diagnose. Confirmed compromise is the exception: recover onto trusted infrastructure and rotate affected credentials rather than restoring the compromised identity.

Step 1: Inventory the effective service and recovery pair

Read metadata locally, without printing the full JSON configuration or secret environment values:

/usr/local/bin/xray version
sudo systemctl is-enabled xray
sudo systemctl is-active xray
sudo systemctl show xray -p FragmentPath -p DropInPaths -p User -p Group -p ExecStart
sudo systemctl cat xray

Inspect unit text privately; custom unit arguments may contain secrets and must be redacted before sharing. Record the actual executable and every -config or -confdir input in ExecStart, rather than assuming /usr/local/etc/xray/config.json is the only file. Record runtime identity, capabilities, filesystem access, environment-file paths and asset-directory settings without copying their secret values into the report.［1］［4］

Recovery item	What to preserve	Why it matters
Executable and version	Trusted old binary, architecture, release provenance	A new schema may not run with an old binary
Configuration inputs	Every loaded JSON file and ordering convention	One copied file may omit active inbounds or routing
Service definition	Unit, exact local drop-ins, enablement, user and capabilities	Correct JSON can still run under the wrong identity
Rules and external files	Used geoip/geosite data, referenced files and paths	Missing or changed rules can alter traffic selection
Credentials and certificates	Active credentials, used certificate/key files, renewal ownership	Restoring secrets without their lifecycle can revive access
Network dependencies	DNS records, provider/local firewall and upstream dependencies	They are not contained in the core configuration backup

Keep a separate dated revocation ledger and copies of the active clients' non-secret parameters. Store the backup under root-only permissions, encrypt any off-host copy, and verify it can be read by the recovery operator. Use unique snapshot names and never let an automated panel task overwrite this trusted recovery set. Back up certificate private keys only when they are actually used, and keep renewal secrets under their existing access policy.

Record a rollback trigger and a maximum decision window appropriate to your deployment: startup failure, failure of a required old client, wrong traffic route, or lost management access. A successful process start alone does not close the window. Do not delete the old recovery pair to make space for a new package.

Step 2: Prepare the official target without executing an unknown script

Open the fixed release page, confirm the XTLS project, architecture and relevant release changes, and obtain the matching official asset. Keep its supplied integrity information and verify it through the documented release process. A release checksum is an artifact check, not proof that a random download mirror is trusted. Do not select a prerelease merely because its version string sorts later.［2］

If you use Xray-install, download its script from the official repository into a protected workspace, record the reviewed revision, and read its installation, service and data-file behavior before any execution. Pin the target version; do not run an unaudited curl | bash, enable its beta path, or assume it changes only the executable. This procedure does not require running that installer during preparation.［1］

For the manual upgrade branch, unpack the verified target binary into a root-controlled staging directory separate from /usr/local/bin/xray; the examples call it /root/xray-change/target/xray. Make it executable and verify version before testing. Preserve the old executable at /root/xray-change/backup/xray, with its matching configuration and other recovery items, before replacing anything. These paths are operation-specific examples and must not overwrite a previous recovery workspace.

Stage a copy of all active configuration inputs, remove revoked credentials using the separate ledger, and make only changes required by the target release. Keep production secrets private. Do not publish a merged configuration or use the CLI dump option as a diagnostic shortcut; it can reveal active authentication material.

Step 3: What does an offline configuration check prove?

For a deployment whose effective unit loads one configuration file, test that staged file with the target binary:

sudo /root/xray-change/target/xray version
sudo /root/xray-change/target/xray run -test -config /root/xray-change/target/config.json

Replace the input path with your staged copy. For a directory-based deployment, use the corresponding -confdir instead; for multiple explicit files, preserve their actual inputs and order. The pinned CLI defines -test as configuration testing without launching the server. The command still needs referenced files and appropriate asset paths, so use the deployment's reviewed environment.［3］

A passing check shows that the target can load that configuration in that context. It does not prove the runtime user can read it, bind its port, access certificates, reach dependencies, or interoperate with every client. Check directory traversal and file permissions for the actual unit user without making the entire secret tree world-readable. Preserve existing minimal capabilities instead of switching the service to root to silence an error.

Run the equivalent check with the trusted old binary against the rollback configuration after replaying current revocations. If you cannot prepare a loadable old pair, stop before the cutover. New-only settings may require the old configuration; simply replacing the executable with an older version is not a complete rollback.

Step 4: Cut over either the version or the host

Upgrade on the existing host

Keep the endpoint, protocol and client settings stable unless release notes require a specific change. During the authorized window, stop only xray, install the reviewed target executable and staged configuration into the recorded production paths with the recorded ownership and permissions, and start the same unit. If you changed a unit or drop-in, run daemon-reload first; configuration-only changes do not require it.［4］

The operation should use the platform's reviewed replacement process so an interrupted copy does not leave a partial executable. Do not combine it with a new routing design or unrelated service cleanup. Capture the reported version, unit status and first relevant journal error privately. If start fails, proceed to the paired recovery procedure instead of trying several versions at random.

Migrate Xray server infrastructure

Build the replacement with the trusted current version first. Transfer only the required configuration and recovery material through an authenticated administrative channel with verified host keys; recreate runtime identity, capabilities, asset paths and restricted firewall access. Do not clone an entire host or panel database into an unrelated layout and assume the effective unit remains the same.

Use a separate canary profile pointing to the new endpoint, with the intended server identity and credentials. Change server public parameters, certificate/domain dependencies or REALITY settings only where the selected migration branch requires them. Do not copy certificate renewal ownership blindly, and do not share the new profile publicly. Keep the old endpoint available only if it remains trusted and authorized.

A DNS edit does not force every application to discard its active connection or cached profile. Use the client's documented reconnect or import action and verify the destination actually used. The client profile freshness checks help distinguish a failed new server from a client still using old settings.

Step 5: Verify old clients, traffic and rejected credentials

Test the oldest required client version and each materially different client type you support, recording their versions without promising a universal compatibility matrix. For VLESS/REALITY, compare the required authentication and transport parameters; use the REALITY failure checklist for that branch rather than guessing new field names. Keep certificate verification enabled.

Check method	Expected observation	Failure action
Read running version and effective unit	Selected binary and intended configuration are in use	Correct path or ownership before client testing
Authorized old client makes a required request	Its supported application flow succeeds through the selected instance	Inspect actual profile and version-specific changes
Use a dedicated revoked test credential	It receives no protected proxy service	Stop acceptance and replay revocations everywhere
Check intended public exit and DNS path	Selected applications follow the declared route and resolver	Inspect routing and client coverage separately
Check required UDP, IPv6 and disconnect behavior	Each matches the documented deployment scope	Reject unverified coverage claims and restore safe policy

For an internet proxy, verify the application's public IP through the actual configured application path. A server-side IP check or an unproxied browser is not equivalent. TCP success does not prove UDP forwarding; IPv4 success does not prove IPv6 routing, and an active process does not establish disconnect protection.

Use a legitimate credential as a positive control when testing rejection. Do not attempt unknown users' credentials, and do not call a fallback decoy website proof of successful proxy authentication. If you cannot perform a particular client or negative test, record it as unverified and keep the corresponding acceptance item open.

Step 6: Perform Xray backup restore and retire safely

If the canary fails, stop only the changed instance through the independent console. Restore the trusted old executable together with its matching configuration, required rules, unit/drop-ins and used certificates, according to the recovery inventory. Reapply every subsequent credential revocation before startup. A compromised key or expired certificate must be replaced through its proper recovery process, not resurrected from a convenient backup.

Restore the recorded user, permissions and capabilities; run daemon-reload only for restored unit definitions. Check the old pair with its own configuration-test command, start once, and repeat version, authorized-client, revoked-client and traffic checks. For a host migration, return the canary to the trusted old endpoint and profile, then verify the destination and service again. Stop the replacement when abandoning that migration.

After success, observe the accepted deployment for the agreed window, verify authorized boot persistence, and account for sleeping clients before retiring the old instance. Remove temporary test credentials and migration-specific access rules, retain protected recovery material according to policy, and verify removal. Stop and disable the retired service; cancel provider compute, disks, addresses and snapshots separately. Powering off a process does not close billing.

If repeated maintenance windows exceed the value of running your own exit, weigh VPS control against managed VPN maintenance. That is a change of responsibility, not a way to repair Xray or retire its credentials. The neighboring WireGuard boot-lifecycle checks illustrate service ownership, but their commands do not apply to Xray.

Summary

Preserve a trusted recovery pair and effective service dependencies.
Test configuration first, then actual client and traffic behavior.
Replay revocations before recovery and retire infrastructure deliberately.

FAQ

Is copying config.json enough for a backup?

It is sufficient only if that truly is the entire configuration and all referenced dependencies are preserved separately. Inventory the effective unit before deciding what to copy.

Can I upgrade and migrate in the same window?

Separate those variables when possible so a failure has a clear cause. Move the trusted current version first, accept it, then plan an upgrade independently.

Does run -test prove that the service will work?

It checks configuration loading without starting the server. Runtime permissions, port binding, client compatibility and traffic policy still need separate verification.

Should I automatically choose the newest prerelease?

Use a reviewed supported target for your deployment. This example fixes v26.3.27 and does not establish that a later prerelease suits your clients.

Can I roll back just the executable?

Restore its compatible configuration and dependencies too. An old binary may reject newer settings even when the replacement executable itself is intact.

Will restoring a backup restore deleted users?

An older backup may contain their credentials. Replay the current revocation ledger before startup and verify rejection using an authorized test identity.

Can a panel backup replace this native workflow?

A panel's supported backup is specific to its own managed state. Use its documented restore process rather than mixing its database with manual native-file replacement.

Sources:

XTLS — Xray-install — https://github.com/XTLS/Xray-install
XTLS — Xray-core v26.3.27 release — https://github.com/XTLS/Xray-core/releases/tag/v26.3.27
XTLS — v26.3.27 command-line configuration checks — https://github.com/XTLS/Xray-core/blob/v26.3.27/main/run.go
Ubuntu Noble — systemd.service(5) — https://manpages.ubuntu.com/manpages/noble/man5/systemd.service.5.html

Sources checked 11 October 2026.

Related Articles:

Xray Upgrade and Migration: Backups and Rollback