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.

• -a - the keystore algorithm. Default: RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING.
• -o - server's Bootstrap-PortTCP/IP port specified in the UKC server's bootstrap procedure. Default: 443..

Note
To back up a server that was bootstrapped before the 1806 release, specify the port parameter -o 8443.

• -d - absolute path to the backup file's folder. Default: Database Backup Default Folder.
• -w - password. See Inline Password Options.

Examples (Java-8 and Java-11) using encryption key in JKSA 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 RESTRepresentational 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.

• -a - the keystore algorithm. Default: RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING.
• -w - password. See Inline Password Options.
• -o - server's Bootstrap-PortTCP/IP port specified in the UKC server's bootstrap procedure. Default: 443..

Note
To back up a server that was bootstrapped before the 1806 release, specify the port parameter -o 8443.

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:

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.

/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 JKSA 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:

Syntax: