What an X-Road migration involves
This service covers two different kinds of migration, and the plan for each is different. The first moves existing point-to-point integrations, where two organizations call each other's services directly, onto X-Road services that run through Security Servers. The second moves a Security Server itself to a new host, a new operating system or a remote PostgreSQL database while your connections to other members keep working. Decide early which kind you are doing, because the second touches live trust relationships and cannot be tested in isolation.
Common triggers include aging hosts, an operating system approaching end of support, database consolidation, a move to new data centers or cloud accounts, and consolidation of several integrations onto fewer Security Servers. For a server move, the target must be a supported platform: Ubuntu Server 22.04 or 24.04 LTS, or Red Hat Enterprise Linux 8 or 9, on x86-64. Confirm the current minimum memory and disk requirements with the installation guide for your release, and confirm whether a remote PostgreSQL service, such as a managed offering, is supported for your version before you commit to the design.
Connections usually break at the network layer, not in the application. Other members reach your Security Server on TCP 5500 for message exchange and 5577 for OCSP, so new addresses, load balancers and firewall rules must be in place and tested before cutover. Admin access on TCP 4000 and information system access on 8080 or 8443 are internal and need their own rules. If your keys sit in a hardware security module, confirm the PKCS#11 driver, the hardware token package and key access on the new host before any production traffic moves.
Many teams with strong Linux and PostgreSQL operations run a host or database move in-house, particularly when the change is limited to the platform. A partner is more often brought in when several integrations must be re-pointed, cutover windows are tight, or the change needs coordination with other members. The member side depends on parties outside your control, including their Security Server operators and their governance and trust service arrangements. Agree the cutover sequence, test plan and rollback steps with them in writing before work starts.
What the work includes
The migration is split into work packages that can be scoped separately, so each one can be checked against your current servers, member connections and integrations before anything moves. The scope is agreed in writing before work starts.
Integration inventory and X-Road mapping
We list each point-to-point integration, its endpoint, its authentication method and its data consumers, then map it to the X-Road service, member and security server it will use. Gaps are recorded before cutover, not discovered during it. Check that every consumer that depends on a current endpoint is named in the inventory.
Security Server rebuild or move
We rebuild the Security Server on a new host or move it, keeping the member identity, certificates and service configuration intact. The target must meet the supported platform and resource requirements from the installation guide. Confirm that the new host can reach the Central Server and the members you exchange data with before the old one is retired.
OS release change
Where the move also changes the operating system, we plan the release change as its own step, covering the supported Ubuntu Server LTS or Red Hat Enterprise Linux releases and the Security Server package versions that run on them. Confirm the current support status of your target release and the X-Road version it is paired with before scheduling.
PostgreSQL relocation
The Security Server database can move from local PostgreSQL to a remote server, including a managed service such as AWS RDS or Azure Database for PostgreSQL. We check network paths, credentials, TLS settings and backup ownership for the new location. Confirm who is responsible for patching and backups of a managed database, since that changes the operating model.
HSM token re-attachment
Where keys sit on a hardware security module, we re-attach the token through the PKCS#11 driver and the xroad-addon-hwtokens package on the new host. The check that matters is that the signing keys are used from the same token after the move, with RSA or EC keys tested end to end. Confirm the HSM vendor supports the new operating system before the move.
Admin access and firewall port changes
We update firewall rules and admin access for the ports the Security Server uses: TCP 5500 and 5577 from external networks, and TCP 4000, 8080 or 8443 from internal networks. Rules are tested from each network zone so that member traffic keeps flowing and admin access stays limited to approved hosts. Confirm which internal systems call the information system ports before changing them.
Cutover and rollback
We agree a cutover window, the order of steps and a rollback point for each component, and rehearse the sequence in a non-production environment where one is available. The rollback is tested as well as the forward path. Confirm with your member peers how they will be notified and what they should expect during the change.
Handover to your team
We train the operators who will run the migrated estate, walk through runbooks and confirm access to monitoring and backups. The handover closes when your team has run the core procedures without DeployOpen present. Check that named owners exist for certificates, database and HSM access before the engagement ends.
What drives cost and duration
This table lists the factors that most change the effort of an X-Road migration, why each one matters, and how to keep it under control.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Number and protocols of current integrations | Each point-to-point integration needs mapping to an X-Road service, and older protocols may need adapter work before they can move. | Inventory every integration with its protocol, owner and data flow, then migrate in groups by protocol and risk. |
| Member connections that must not drop | Every live connection is a cutover risk, and each one needs its counterparty's testing and sign-off. | Run old and new paths in parallel where possible and move one connection at a time with a tested rollback. |
| Number of Security Servers and environments | Each Security Server and each of production, staging and test needs its own install, configuration, certificates and verification. | Build one repeatable configuration and automate installs, so later environments repeat the tested steps. |
| Starting OS and target OS release | Moving to a different Ubuntu or RHEL release changes package sources, prerequisites and hardening, and may require a fresh host. | Confirm the target is a supported Ubuntu 22.04 or 24.04 LTS or RHEL 8 or 9 release, and state the X-Road version such as 7.8.3. |
| Database size and network change | A remote PostgreSQL move or a cross-network move adds data transfer, connectivity, firewall and timing work. | Measure the database early, rehearse the transfer, and confirm firewall rules for ports 5500, 5577 and 4000 before cutover. |
| Software keys versus HSM-backed keys | HSM-backed keys need PKCS#11 setup, token handling and key access checks, and key migration needs careful planning. | Decide the key model before design, and test HSM access on the target host in staging first. |
| Admin users and directory integration | Admin accounts, roles and LDAP or Active Directory groups must be recreated and tested on the new servers. | Export current role assignments, map them to the five X-Road roles, and verify logins before cutover. |
| Change windows agreed with other members | Other members set their own maintenance slots, which can limit how many cutovers fit in a period. | Agree a window calendar with members early and bundle connections that share a window. |
| Quality of existing documentation | Undocumented integrations and configurations take longer to discover, and gaps often surface during testing. | Document the current state first, and ask the client to name owners who can confirm each integration. |
Project phases and outputs
The sequence moves each integration and Security Server from its current host to the target without interrupting member connections, with a documented output at every phase.
Discover and inventory integrations and servers
DeployOpen's engineers and your integration owners list every point-to-point government integration, its counterparties, message flows and certificates, and record each Security Server's current X-Road version, operating system and database. The inventory is complete when every integration has a named owner and every server has its version, OS and database recorded.
Design the target architecture and network plan
DeployOpen designs the target hosts, the X-Road release and OS pairing, the port and firewall plan for message exchange, OCSP and admin access, and how the Security Server connects to a local or remote PostgreSQL database. Work with your network team to confirm the external and internal port rules. The design is signed off when the architecture, port plan and database connection design are approved by your security and network owners.
Build and test in a non-production environment
DeployOpen rebuilds the Security Server in a non-production environment, loads a copy of the production configuration and tests service calls, certificate chains, HSM-backed keys where used, and admin roles. Member test partners are needed for this step, so confirm their availability early. The step closes when the rebuilt server passes the agreed test cases against the configuration copy.
Rehearse member and integration cutover
The cutover is rehearsed in full, including member coordination, the order of switching integrations, DNS and certificate changes and the checks after each switch. Timing depends on member coordination windows, which you should agree with each counterparty before the rehearsal is scheduled. The rehearsal closes with a runbook and written rollback criteria that the change owners accept.
Execute the production cutover
DeployOpen carries out the approved runbook during the agreed window, running the verification checks after each integration moves and stopping to roll back if a rollback criterion is met. Your change board and member contacts follow the live status. The step closes with a signed-off change record that lists the versions, hosts, integrations moved and verification results.
Hand over with hypercare and operations documentation
After cutover, DeployOpen monitors the migrated servers and integrations through an agreed hypercare period, resolves issues found in live traffic and retires the old hosts once you confirm they are no longer needed. The handover includes operations documentation for backups, upgrades, monitoring and the database connection. The step is complete when your operations team accepts the documentation and the hypercare exit criteria are met.
What teams keep in-house and what they outsource
This table shows, for each part of an X-Road migration, who usually owns the work, what they must be able to do, and which skills the internal team needs to keep after handover.
| Work part | Usual owner | Skills needed |
|---|---|---|
| Which integrations move to X-Road and when | In-house, with business owners of each integration | Knowledge of each point-to-point flow, its data owners and its consumers, and the authority to set cutover order |
| Member and governance coordination | In-house, with the trust service or governance owner | Contacts with other members, change approval, and agreement on member onboarding and certificate changes |
| Linux administration on RHEL or Ubuntu | Shared: partner builds and hardens hosts, internal team takes over operations | Package management, systemd, patching, log review and the supported OS versions for the Security Server |
| PostgreSQL administration and migration | Partner usually plans and executes the move, internal DBA owns the target database | Dump and restore or replication-based moves, connection and privilege setup for a local or remote database, backup and restore testing |
| Security Server installation and configuration | Partner usually leads, internal team pairs and then runs changes | X-Road Security Server installation, backup and restore of configuration, service and client registration, and version upgrades |
| HSM and PKCS#11 integration | Partner or HSM specialist with internal security team approval | PKCS#11 driver setup with the xroad-addon-hwtokens package, key ceremony handling, and HSM vendor support contacts |
| LDAP or PAM alignment for admin logins | Shared: partner configures PAM and SSSD, internal directory team owns groups | LDAP group design, SSSD configuration, mapping directory groups to the five X-Road administrative roles, and access reviews |
| Firewall and network changes | Internal network team owns approval, partner supplies the port list | Knowledge of required ports for message exchange, OCSP, admin UI and information system access, and change control |
| Testing and cutover execution | Partner usually runs test plans and cutover, internal business owners sign off | Test design for member connections, rollback planning, and monitoring during the switch |
| Documentation and runbooks | Partner drafts, internal team owns and maintains | Writing runbooks for upgrades, backups, key rotation and incident response, and keeping them current after changes |
What usually goes wrong
These are the failures that most often stall or reverse an X-Road move. Each card names the check to run before the change window.
Credentials that do not survive the move
Certificates, trust settings, HSM tokens and admin accounts are tied to the original host and directory setup. After a host change, trust configuration can be left inconsistent, PKCS#11 tokens may need re-provisioning, and admin logins can disappear during directory changes. Inventory every credential and admin role before cutover, and confirm each one works on the new host.
PostgreSQL connection and permission gaps
Moving the Security Server to a remote or managed PostgreSQL database changes network paths, authentication and grants. Connections can fail, or the application user can lack rights it had on the local database. Take a configuration backup, rehearse connection and privilege checks on a staging copy, and confirm the endpoint and TLS settings before the change window.
Firewall rules for 5500, 5577 and admin ports
Port 5500 carries message exchange and 5577 serves OCSP from external networks, while the admin UI on 4000 and information system access on 8080 or 8443 belong to internal networks. Opening these ports too widely exposes admin surfaces, and a missed rule blocks member traffic. Write the rules from this port list, test each path from both sides, and review them during the change freeze.
OS release differences that break the build
The Security Server is supported on Ubuntu Server 22.04 and 24.04 LTS and on Red Hat Enterprise Linux 8 and 9, so moving between releases changes packages, dependencies and service handling. A build that worked on one release can fail on another. Confirm the target release is on the supported list, rebuild in a rehearsal environment, and record package versions before cutover.
Integrations tied to undocumented endpoints
Point-to-point integrations often call a fixed host address or an endpoint that no one documented. When traffic moves onto X-Road services, those callers either break or keep reaching the old server. Inventory every caller with its source, destination and credentials, including scheduled jobs, and move each one through a planned cutover step.
Cutover without rehearsal, rollback or member testing
A cutover without a rehearsed rollback leaves no tested way back if member connections fail. Skipping connection tests with other members means faults surface in production instead of before go-live. Set rollback criteria in writing before the window, keep a restorable configuration backup, freeze unrelated changes, and run test exchanges with each member before going live.
How the work changes by starting point
Moving an existing point-to-point integration to X-Road services changes the plan from a data-flow exercise into a trust and access exercise. Each current connection must be mapped to a provider service, a consumer access rule and the certificates that identify both members.
- Plan: inventory every endpoint, credential and data flow, then sequence cutovers one consumer at a time.
- Testing: run old and new paths in parallel, confirm message exchange end to end and test each access rule, including a denied case.
- Rollback: define how each consumer returns to the legacy path if a cutover fails.
- Confirm: member and service codes, which trust services are in place, and which legacy authentication can be retired and when.
Moving a Security Server to a new host on the same OS release keeps the software stack stable, so the work centers on identity, keys and network reachability. The server's configuration, keys and database must arrive intact, and peers must see the same member identity afterward.
- Plan: back up configuration and keys, restore onto the new host, then repoint DNS, firewall rules and any HSM access.
- Testing: verify the restored instance in staging, then confirm message exchange and OCSP responses from peer members after cutover.
- Ports: confirm TCP 5500 and 5577 are reachable from external networks, and TCP 4000 is reachable only from admin networks.
- Confirm: the new host meets the minimum of 3 GB RAM and 3 GB free disk, runs the same OS release as the current host, and has the required HSM driver if one is used.
Moving from an older OS release to RHEL 8 or 9, or Ubuntu Server 22.04 or 24.04 LTS, is a platform change that also affects the X-Road packages, the HSM driver and the database client. The plan must treat the OS change and any X-Road version change as one controlled event.
- Plan: decide between an in-place upgrade and a rebuild on the target release, then fix the X-Road version that will run on it.
- Testing: repeat full message exchange, backup restore and HSM token detection on the new OS before any production change.
- Architecture: Security Server support covers x86-64 only, so confirm the hardware architecture first.
- Confirm: the target OS release and the X-Road version are both on the vendor's supported lists, and that the PKCS#11 driver supports the new OS.
Moving the Security Server database to a remote PostgreSQL service, including a managed service such as AWS RDS or Azure Database for PostgreSQL, adds a network dependency that the server cannot function without. The migration plan must cover data transfer, connection behavior and who owns backups.
- Plan: export and import the database under a maintenance window, then verify row counts and configuration after the move.
- Testing: test restart with the remote database, loss of connectivity, and latency under message load.
- Operations: agree how backups, patching and failover of the managed service are handled and how restores are proven.
- Confirm: the PostgreSQL version against the X-Road release notes, the network path and firewall rules between the Security Server and the database, and whether the service grants the privileges the installation needs.
Working in an air-gapped or restricted network changes how software, updates and trust services reach the Security Server. Anything the installation normally fetches from outside the network must be supplied from inside it, and the plan must prove that no hidden external dependency remains.
- Plan: build an internal package mirror, transfer packages through an approved process, and document each dependency.
- Testing: perform the install and a message exchange with outbound access blocked, and check that time synchronization works internally.
- Trust services: confirm how certificate status, time-stamping and global configuration are reached from the restricted zone.
- Confirm: which network zones host each component, which ports must cross each boundary, and the approved route for security patches.
What the client needs to provide
The migration cannot be scoped or sequenced until the client supplies a set of inputs. The most important are named owners: one accountable person for each integration and for each member connection, plus the people who can approve a change on the other side of every connection. Without them, a cutover stalls the moment a counterpart's certificate, endpoint or service definition needs a decision.
Next, provide access to the current configuration and backups of every Security Server and the Central Server, along with the current X-Road and operating system versions on each host. Include the database details for each server (local or remote PostgreSQL, host, version, and who administers it), and the HSM details if keys are held in hardware through PKCS#11, including the token model and the key labels in use. Confirm the target OS release and its supported X-Road version against the official X-Road release and Security Server installation documentation before any host is rebuilt, because the supported combinations decide whether an in-place upgrade or a fresh build is the realistic path.
Also provide the directory details used for administrator login, the network diagrams showing every Security Server, firewall and load balancer in the message path, and the firewall change process with its lead times. The migration depends on the message exchange, OCSP and admin ports staying reachable in the right direction during the move, so the firewall team's approval steps belong in the plan from day one. Agree the change windows and the rollback criteria that will govern each one.
Frequently asked questions
What drives the cost of an X-Road migration and what should a quote include?
The main cost drivers are the number of Security Servers and Central Server components in scope, how many point-to-point integrations must be re-pointed to X-Road services, and how much existing configuration, certificates and keys must be carried over or rebuilt. Hardware, HSM work, change windows and the number of member organizations that must test also add effort. A quote should list each server and host, each integration with its owner, the target OS (Ubuntu or RHEL), the PostgreSQL target, test and rollback steps, cutover support and the documentation delivered. Ask which items are one-time and which recur, such as support after go-live.
How long does an X-Road migration take for our environment?
Duration follows the same drivers as cost: integration count, number of connected members and their test availability, change-freeze windows, and whether the target host or database is new. DeployOpen does not give a duration without a written scope, and no supplied source gives a standard timeline for X-Road migrations, so ask for a schedule tied to named milestones. Ask the partner which steps depend on outside parties, such as trust service providers or connected organizations, because those dependencies often set the calendar more than the installation does. Confirm any target date against your own change calendar before committing.
Can our own team migrate X-Road integrations without a partner?
Often yes, if your engineers already run Linux servers, PostgreSQL and certificate workflows. The harder part is coordination, because the cutover depends on testing with each connected organization and on a tested rollback. Your team needs people who can plan the cutover, run those tests and make the go or no-go call. DeployOpen plans, implements, documents and supports self-hosted platforms in your infrastructure under a fixed written scope, so you can hand over the whole migration, one part such as the database move, or testing support. Ask which tasks your team would own after go-live.
Will member connections drop during an X-Road Security Server cutover?
Connections can be interrupted if the new Security Server takes over before its certificates, trust configuration and firewall rules are verified. A well-planned cutover reduces that risk by building and testing the new host in parallel, confirming message exchange and OCSP reachability, then switching traffic in a short, announced window with a documented rollback. The external network must allow TCP 5500 and 5577, and the admin and information system ports must match your internal access rules. Ask the partner for the test matrix, the rollback criteria and the list of connected organizations notified before the window.
Can X-Road Security Server use a remote PostgreSQL database after migration?
Yes, the Security Server requires PostgreSQL and supports a remote instance, including managed services such as AWS RDS and Azure Database for PostgreSQL. Moving the database is a separate step from moving the server, so plan it with a verified backup, a maintenance window, network access from the Security Server to the database host and a tested restore. Confirm the exact steps and supported PostgreSQL versions against the installation guide for your X-Road release before you start, because supported versions can change between releases. Ask the partner to show the rollback path for the database move.
Does moving to X-Road 8 change our migration plan?
It can, mainly in timing and in what you build now. X-Road 8 "Spaceship" is available for testing as 8.0.0 Beta 2, with the production release scheduled for December 2026. X-Road 7.8.0, released at the beginning of February 2026, is the last new-feature release of X-Road 7. NIIS intends to maintain X-Road 7 with bug fixes and security patches beyond 2026, but the length of that period has not been decided. For upgrade paths and support options, see the sibling topic on X-Road upgrades and support, including X-Road 8.
How DeployOpen delivers X-Road migrations
DeployOpen plans and carries out X-Road migrations of integrations and servers inside your own infrastructure, moving point-to-point connections onto X-Road services and moving Security Servers to new hosts, RHEL or Ubuntu releases, or a remote PostgreSQL database. Engagements are fixed-scope, with the written scope setting what changes and how member connections are protected during the cutover.
How we scope
- The written scope lists each integration to move, the Security Servers affected and the target operating system or database.
- We inventory current endpoints, certificates, member connections and firewall rules before any change is approved.
- Supported platform targets are confirmed against the X-Road Security Server requirements for Ubuntu 22.04 or 24.04 LTS and RHEL 8 or 9.
How we build
- We build the target hosts or remote PostgreSQL database first and test connectivity while the current servers keep serving members.
- Each integration moves in a planned sequence with a rollback path, and key material, including any HSM-backed keys, is handled explicitly.
- We test message exchange, OCSP and admin access on ports 5500, 5577, 4000 and 8080 or 8443 before each cutover is accepted.
How we hand over
- Deliverables include the as-built architecture, configuration records, cutover runbooks and the test results agreed in the scope.
- We document how admin roles, PAM and any LDAP group mapping are set up on the new servers so your team can operate them.
- Your team receives a walkthrough of the runbooks, with open items and follow-up actions recorded in writing.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Support can cover X-Road 7 patch levels, since 7.8.3, 7.7.4 and 7.6.5 are the supported versions, and planning for the move to X-Road 8.
- Confirm with us during scoping which post-handover responsibilities sit in the retainer and which remain with your team.
