Migrating from GreenRADIUS v3.1.6.7 to v4.1.3.4


GreenRADIUS version is equipped with a tool to migrate users, tokens, and settings from v3.1.6.7. This document describes how to use the migration tool, detailing the steps to perform. It also covers how to deal with certain configurations not covered by the migration tool.

The following configuration is migrated with this tool:

  1. Database tables containing general configuration, user-token assignments, user information, domain information, directory server information, RADIUS clients, token states, token secrets, etc.
  2. Certificates
  3. License file
  4. RADIUS configuration

Additionally, the following configuration can optionally be migrated as well:

  1. Onboard firewall configuration
  2. Onboard OpenLDAP server configurations
  3. Network configuration migration, including DHCP settings and (if applicable) static IP address
  4. Hostname
  5. Time zone


  1. The GreenRADIUS instance to migrate from must be running GreenRADIUS v3.1.6.7
  2. A fresh GreenRADIUS v4.1.3.4 must be deployed as the migration target
  3. The v4.X instance must be able to reach the v3.1.6.7 instance
  4. On the GreenRADIUS v3.1.6.7 instance, the gradmin command line user account (not the web admin interface account) needs to have a password that does not include special characters
  5. The Docker containers auto-start on boot. If the containers have been stopped manually, they need to be restarted before beginning the migration.
  6. For on-board OpenLDAP server configuration migration, a resolvable hostname/FQDN must be configured in GreenRADIUS v4.X as follows:
    • Log in to GreenRADIUS.
    • Navigate to Global Configuration→Certificate
    • Set the value in the Server Hostname/FQDN field.
    • Under the Create Certificate tab, enter a common name matching the hostname/FQDN configured in the above step. Click the Create and Install button.


Once GreenRADIUS v4.1.3.4 is running, invoke the migration script from the command line:

$ cd /home/gradmin/GRS-Migration-Tool/
$ sudo python migration.py

This will produce a dialog of migration options like this:

Migration Options

The migration tool prompts for the hostname or IP address of a v3.1.6.7 instance.

It will then request an administrator username and password of a command-line user on the v3.1.6.7 instance.

You will be prompted as to whether you wish to migrate on-board firewall configuration, on-board LDAP configuration, hostname, network, and timezone settings.

The migration process may take some time. When it is finished, a completion message will be displayed:

Migration Complete

If your v3.1.6.7 instance was configured not to use DHCP, then the v4.1.3.4 instance will try to use its IP address the next time it starts (if you selected to migrate the network configuration.) To prevent the GreenRADIUS instances from colliding over the IP address, you should shut both down and then reboot only the v4.1.3.4 instance without rebooting the v3.1.6.7 one.

After reboot, you will find that most settings from your v3.1.6.7 instance have been migrated.

IMPORTANT NOTE: If there are multiple servers configured in synchronization, one GreenRADIUS v4.1.3.4 instance should be deployed for each v3.1.6.7 instance and migration from each v3.1.6.7 instance should be done to the corresponding v4.1.3.4 server instance. Once the migration is done, the server entries in the synchronization configuration should be deleted and re-added on each of the v4.1.3.4 server instances.

Additionally, in some cases, the network configuration is not migrated.
In such cases, manually configure the network by following our network configuration guide.

Settings to Check and Configure Manually

Not all settings are migrated. Please be sure to check the following settings and make changes as necessary:

  1. YubiKey OATH-HOTP OTP length (in case YubiKeys programmed in OATH-HOTP mode are being used, this setting is found under Global Configuration→General)
  2. User portal OATH algorithm for soft tokens (in case Google Authenticator or similar soft tokens are being used, a setting of TOTP is recommended, this setting is found under Global Configuration→User Portal)
  3. Temporary tokens must be re-established for those users assigned temporary tokens
  4. LDAP server certificates (in the Directory Server tab of the GreenRADIUS domain) if you are using secure connection (over port 636)
  5. Local web admin console user accounts and settings

Contact Green Rocket Security for further instructions to upgrade from v4.1.3.4 to the latest GreenRADIUS version

Web Analytics Made Easy -

Updated 2021-10-21
© 2024 Green Rocket Security Inc. All rights reserved.