Database Scripts

Important
In the following examples, we use --provider SunJCE and --type JCEKS, even though Java 11 recommends switching to --provider SUN and --type PKCS12.

ekm_backup

Generates an encrypted backup of the CORE database share that is located on the server.

Prerequisites

  • For the encryption, it uses a public key that must be provided in the Java keystore file.
  • The CORE backup procedure must be done separately on an EP and its partner server.

On each server, this command creates two files in the Database Backup Folder:

  • The database_<DATE-TIME>.tar.gz archive. It includes the encrypted share of the database and its metadata, including the digest.
  • The database_<DATE-TIME>_digest.bin file. It contains a backup inventory record that is used by ekm_verify_backup.

Syntax:

ekm_backup
[-a,--algorithm <arg>] key store algorithm.
-p,--provider <arg> security provider name
-t,--type <arg> key store type - as specified by your provider
[-f,--file <arg> key store file] - mandatory when using with -t JCEKS
[-w,--password <arg> key store password (storepass)] - mandatory with -t JCEKS
-n,--name <arg> backup encryption key-name (known as "alias") in the keystore
[-s,--self <arg>] Server's Certified-IP
[-o,--port <arg>] Server's Bootstrap-Port
[-d,--directory <arg>] absolute path to the backup file's folder.

Examples (Java-8 and Java-11) using encryption key in JKSClosedA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption. keystore:

  • Linux:

    sudo /opt/ekm/bin/ekm_backup.sh -p SunJCE -t JCEKS \
    -f ./EpBackup.jks -w EpBackup1! -n EpBackupKey

    Backup file: /opt/ekm/../../var/lib/ekm/data/backup/database_2017-09-05-05-53-05.tar.gz

  • Window:

    C:\Progra~1\Dyadic\ekm\tomcat\bin\ekm_backup.bat -p SunJCE -t JCEKS \
    -f ./EpBackup.jks -w EpBackup1! -n EpBackupKey

    Backup file: C:\ProgramData\dyadic\ekm\data\backup\database_2017-09-12-14-23-04.tar.gz

Note
To run the ekm_backup.sh in sudo-less installation, see Running CORE Scripts in Sudo-less Installation

ekm_set_backup_params

This script stores the backup parameters in the Backup Info File for CORE Backup RESTClosedRepresentational State Transfer (REST) - an architectural style that defines a set of constraints and properties based on HTTP. Web Services that conform to the REST architectural style, or RESTful web services, provide interoperability between computer systems on the Internet. API use. In particular, it is used by the UI Backup procedure.

Prerequisites

  • This procedure must be done separately on an EP and its partner server.

The set of parameters is identical to the ekm_backup, yet the output is the Backup Info File that includes:

  • Specification of the keystore that contains the backup encryption public key.
  • Name of the key and (if applied) the passphrase required to obtain the key.
  • The backup encryption algorithm.

Syntax:

ekm_set_backup_params
[-a,--algorithm <arg>] key store algorithm.
-p,--provider <arg> security provider name
-t,--type <arg> key store type - as specified by your provider
[-f,--file <arg> key store file] - mandatory when using with -t JCEKS
[-w,--password <arg> key store passphrase (storepass)] - mandatory with -t JCEKS
-n,--name <arg> backup encryption key-name (known as "alias") in the keystore
[-s,--self <arg>] Server's Certified-IP
[-o,--port <arg>] Server's Bootstrap-Port.

Java-8 and Java-11 example:

sudo /opt/ekm/bin/ekm_set_backup_params.sh -p SunJCE -t JCEKS -f ./EpBackup.jks -w EpBackup1! -n EpBackup1

Operation completed successfully

The result is recorded in the Backup Info File. For example:

sudo cat /var/lib/ekm/data/key_backup.info #Thu May 02 12:57:28 UTC 2019 store_file=/home/ubuntu/BR/./EpBackup.jks store_type=JCEKS algorithm=RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING provider_name=SunJCE key_name=EpBackup1 store_password=*******

ekm_verify_backup

Use this script to confirm that the provided backup archives are matching EP and Partner archives.

Prerequisites. Verification must be done on an appliance with installed CORE server software.

To use the script:

  1. Obtain and untar both database archives and extract the digest files.
  2. Run the script.
  3. /opt/ekm/bin/ekm_verify_backup.sh
    -d1,--digest1 <arg> the first digest file
    -d2,--digest2 <arg> the first digest file
    [-o,--port <arg>] server's Bootstrap-Port

Example:

/opt/ekm/bin/ekm_verify_backup.sh -d1 ep1/ep1_digest.bin -d2 partner1_backup/partner1_digest.bin

DB verification success
Operation completed successfully

ekm_restore

Perform the CORE restore procedure when none of the server pairs in a cluster have the required database.

Prerequisites:

  • Two servers. If the selected servers have CORE software residues, uninstall the CORE software.
  • Install CORE server software release that matches the backup release.
  • Do not bootstrap the servers.
  • Pay attention to which server is restored with the EP backup and which with Partner backup.

Syntax:

/opt/ekm/bin/ekm_restore.sh
[-a,--algorithm <arg>] the key store algorithm
-p,--provider <arg> the security provider name
-t,--type <arg> the key store type
-f,--file <arg> the key store file
-w,--password <arg> the key store password (storepass)
-n,--name <arg> the key name (alias)
-b,--backup <arg> the backup tar.gz file
[-v,--verbose] verbose mode

The default key-store algorithm is RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING.

Example (Java-8 and Java-11) using JKSClosedA Java KeyStore (JKS) is a repository of security certificates – either authorization certificates or public key certificates – plus corresponding private keys, used for instance in SSL encryption.:

  • Linux:
  • sudo /opt/ekm/bin/ekm_restore.sh \
    -p SunJCE -t JCEKS -f ./EpRestore.jks -w EpRestore1! -n EpRestoreKey \
    -b ./backup/database_2017-09-05-05-53-05.tar.gz

  • Windows:
  • C:\Progra~1\Dyadic\ekm\tomcat\bin\ekm_restore.bat \
    -p SunJCE -t JCEKS -f ./EpRestore.jks -w EpRestore1! -n EpRestoreKey \
    -b .\backup\database_2017-09-12-14-17-12.tar.gz

ekm_sync_key

This script fixes database mirroring issues in a CORE cluster. For example, assume the following case:

  • A cluster with two pairs: [ep1,partner1] and [ep2,partner2
  • A certain UID from partition P1 exists only in the [ep1,partner1] pair.

To push this key to the database of [ep2,partner2], run the following from the ep1 server:

sudo /opt/ekm/bin/ekm_sync_key.sh --uid <missing in ep2 pair> --partition P1 --target ep2

Syntax:

/opt/ekm/bin/ekm_sync_key.sh -u,--uid <arg> // the key to be pushed to the <target> [-p --partition <arg>] // the name of the partition> -t,--target <arg> // EP of the pair that is missing the key [-o,--port <arg>] // EP Bootstrap-Port