Data Exchange Layer’s X-Road Toolkit – automated management scripts for the security server
With the automated management scripts (X-Road Toolkit) of the Data Exchange Layer, you can configure one or more security servers. Automated configuration of the security server is easier and the chances of making errors are smaller.
What is X-Road Toolkit?
X-Road Toolkit is a Python-based tool for automated security server installation and management. It can be used to configure all Data Exchange Layer security server options (RHEL, Ubuntu, Docker). X-Road Toolkit enables you to configure one or more security servers at a time.
Automated scripts are only suitable for use in the Data Exchange Layer. This means that for example, certificates created with the scripts are only fit for use in Finland.
X-Road Toolkit has been released as a Python Package Index (PyPI).
Watch a demovideo of how you can configure a security server with X-Road ToolkitOpens in a new window..
What does X-Road Toolkit enable?
X-Road Toolkit enables basic configuration of one or more security servers. Configuring the security server with X-Road Toolkit is easier and quicker than manual configuration. Automated configuration saves time and reduces the likelihood of errors. Automated scripts also facilitate the use of the security server management interface released as part of X-Road version 6.24.0. In other words, they allow remote management of the security server.
X-Road Toolkit also allows you to create installation packages. For example, you can set up services in the YAML configuration file, in which case you only need to edit the basic organisation-specific information separately, such as the name of the organisation.
The basic configuration of the security server includes the following commands:
- Initializing the security server and adding the configuration anchor
- Tokens. Token for login, list of tokens.
- Setting the security server timestamp service
- Certificates: Signing, authentication and TLS certificates. Creating a signing and authentication key and certificate requests, installing received certificates on the security server, registering and activating the authentication certificate, downloading internal TLS certificates.
- Subsystems. Creating and registering one or more subsystems.
- Services. Creating one or more services. Service type: REST API Base Path, REST OpenAPI 3, or WSDL. Setting service parameters and access rights.
In addition to basic configuring, you can:
- Configure high availability implementation. The implementation uses the built-in load balancing of the security server, and for this purpose, you must configure the same subsystem or service for at least two security servers. Read more about high availability implementation in GithubOpens in a new window..
- Renew certificates. Instructions on renewing certificatesOpens in a new window..
- Manage your organisation’s subsystems and services
- Manage backups
Read more about commands in GithubOpens in a new window..
Implementing X-Road Toolkit
You can find instructions on how to install X-Road Toolkit on GithubOpens in a new window..
Please note that you must open the necessary ports on your server before configuring the Security Server. For more information about firewall openings, see section 2 of the deployment instructions.
Prerequisites for using Toolkit:
1. The host server on which the security server software will be installed has:
- RHEL (8) or Ubuntu (24.04LTS) operating system installed
- or Docker installed on any Linux distribution
2. The host server has security server installation packages installed, either for
- RHEL or Ubuntu based security server
- or Docker based Security Server Sidecar
3. Python version 3.6 or later is used
Read more about the prerequisites for implementing ToolkitOpens in a new window..
The required function and details of the Toolkit are specified in the YAML configuration. Information to be specified includes:
- Security server details, such as its FQDN and
- the details of the security server owner, such as the type of organisation.
Read more about the editing of YAML configuration fileOpens in a new window..
The actions specified in the Toolkit configuration can be run all together or one by one
- You can run the entire configuration in one single action with xrdsst apply command
- Parts of the configuration can be run one by one with subcommands. For example, xrdsst init downloads the configuration anchor and initializes the security server data.
In the Data Exchange Layer, subsystems are registered automatically, which means that you can run the entire process in two stages.
- The first configuration run with xrdsst apply command ends with a notification that the certificates must be signed.
- Download the certificate requests with xrdsst cert download-csrs command and send them for signature topalveluvayla@palveluvayla.fi.
- After you have received the signed certificates from Data Exchange Layer support, add a path to signed certificates in the configuration file and continue the running of the configuration with xrdsst apply command.
If any errors occur during the configuration of the security server, configuration stops on the error message. The error message explains where the error occurred and how to correct it. If the error message does not help or you are unable to correct the error, contact Data Exchange Layer support at palveluvayla@palveluvayla.fi.
NOTE! If you configure Sidecar Slim with X-Road Toolkit, you will receive an error message saying that the timestamping service could not be configured. This happens because Sidecar Slim does not have logging or timestamping service thus they cannot be configured. The security server and the configuration functions regardless of the error, which means you can ignore the error message.
Read more about errors and failure recoveryOpens in a new window..
Want to know more?
Read more about the technical documentation of X-Road Toolkit in GithubOpens in a new window..
If you have any questions about automated scripts, please contact our maintenance at palveluvayla@palveluvayla.fiOpens in a new window..