2. Installing YottaDB¶
Contents
This chapter describes the installation procedure for YottaDB. Always read the release notes for special instructions before installing YottaDB.
Obtaining YottaDB Distribution Media¶
YottaDB LLC prefers to distribute YottaDB online via the Internet. YottaDB for selected platforms, including GNU/Linux on the popular x86 architecture and Raspberry Pi hardware, can be downloaded under the terms of the Affero GNU General Public License (AGPL) version 3, from GitLab (https://gitlab.com/YottaDB/DB/YDB/blob/master/sr_unix/ydbinstall.sh). Contact YottaDB Support (info@yottadb.com) to obtain a copy of a YottaDB distribution for other platforms or on physical media.
Before You Begin¶
Before you begin installing YottaDB, perform the following tasks:
Read the YottaDB Release Notes Documentation. The release documents contain the latest information that may be critical for installing and configuring YottaDB. They are located under the Tags in the YottaDB GitLab repository and can also be reached from the Documentation page on the YottaDB website
Determine whether or not YottaDB access is restricted to a specific group. Keep the group name handy as you will have to enter it during the installation process.
Set the environment variable ydb_log to a directory where YottaDB should create log files. If you do not set ydb_log, YottaDB creates log files in a directory in /tmp. However, this is not recommended because it makes YottaDB log files vulnerable to the retention policy of a temporary directory.
Note
In the latest version, gtmsecshr logs its messages in the system log and the environment variable ydb_log is ignored.
If you need to perform UTF-8 mode operations in YottaDB, you must have at least ICU version 3.6 installed. YottaDB uses ICU 3.6 (or above) to provide support for Unicode. YottaDB generates the distribution for Unicode only if ICU 3.6 (or above) is installed on your system. By default, YottaDB uses the most current version of ICU. YottaDB expects ICU to have been built with symbol renaming disabled and issues an error at startup if the currently installed version of ICU has been built with symbol renaming enabled. If you intend to use a version of ICU built with symbol renaming enabled or any version other than the default, keep the MAJOR VERSION and MINOR VERSION numbers ready as you will have to enter it as MajorVersion.MinorVersion (for example “3.6” to denote ICU-3.6) during the installation process.
Note
Installing YottaDB on an NFS mounted directory is not recommended. Several NFS characteristics violate YottaDB database design assumptions which may manifest themselves as hard to diagnose problems. If you still choose to install and operate YottaDB from an NFS mounted directory, there are chances that at some point you will face significant problems with performance and response time. While you should never operate the YottaDB database and journal files from an NFS mounted directory you can safely, except on Linux, use an NFS mounted directory for keeping source and object code modules and performing sequential file IO. While NFS mounted files may work for you, historically they have not provided sufficient support for file locking over NFS to prevent intermittent errors when you have significant concurrent file activity.
Installation Procedure¶
Create a temporary directory and change to it, e.g.: mkdir /tmp/tmp ; cd /tmp/tmp
Get the YottaDB installer: wget https://gitlab.com/YottaDB/DB/YDB/raw/master/sr_unix/ydbinstall.sh
Make it executable: chmod +x ydbinstall.sh
Run it with your choice of directory where you want it installed (omit the –verbose option for less output):
sudo ./ydbinstall.sh --installdir /opt/yottadb/ --utf8 default --verbose
yottadb -version
provides a detailed report on the YottaDB build, e.g.,$ yottadb -version YottaDB release: r1.30 Upstream base version: GT.M V6.3-008 Platform: Linux x86_64 Build date/time: 2020-08-11 20:55 Build commit SHA: 177eb8e48098204dafe564cac2bcb84312b2853a $
Compiling the Reference Implementation Plugin¶
Compile the reference implementation plugin as follows:
Install the development headers and libraries for libgcrypt, libgpgme, libconfig, and libssl. On Linux, the package names of development libraries usually have a suffix such as -dev or -devel and are available through the package manager. For example, on Ubuntu_x86_64, the following command installs the required development libraries:
sudo apt-get install libgcrypt11-dev libgpgme11-dev libconfig-dev libssl-dev
The package names vary by distribution/version.
Note
$ydb_dist
points to the absolute path for the directory where YottaDB is installed.
Unpack $ydb_dist/plugin/gtmcrypt/source.tar to a temporary directory, for example:
mkdir /tmp/plugin-build cd /tmp/plugin-build cp $ydb_dist/plugin/gtmcrypt/source.tar . tar -xvf source.tar
Follow the instructions in the README.
Open Makefile with your editor; review and edit the common header (IFLAGS) and library paths (LIBFLAGS) in the Makefile to reflect those on your system.
Define the ydb_dist environment variable to point to the absolute path for the directory where YottaDB is installed
Copy and paste the commands from the README to compile and install the encryption plugin with the permissions defined at install time
Compare the permissions of $ydb_dist/libyottadb.so to the newly installed shared libraries in $ydb_dist/plugin. Adjust the permission of the newly installed libraries as necessary.
ydbinstall Script¶
ydbinstall is a stand-alone YottaDB installation script that installs YottaDB using reasonable defaults. ydbinstall is a part of the YottaDB binary distribution and you can use it to install YottaDB from the temporary directory in which you unpack the YottaDB distribution. It allows considerable customization using the following command line switches:
Command Line Switches |
* |
Description |
---|---|---|
--build-type buildtype |
* |
Type of YottaDB build, default is pro |
--copyenv dirname |
Copy ydb_env_set and gtmcshrc files to dirname; incompatible with linkenv |
|
--copyexec dirname |
Copy ydb script to dirname; incompatible with linkexec |
|
--debug |
* |
Turn on debugging option with set -x |
--distrib dirname or URL |
Source directory for YottaDB distribution tarball, local or remote |
|
--dry-run |
Do everything short of installing YottaDB, including downloading the distribution |
|
--encplugin |
† |
Download and install the YottaDB encryption plugin |
--from-source reponame |
Clone the repository specified by reponame in current directory and change to YDB/ subdirectory |
|
--group group |
Group that should own the YottaDB installation |
|
--group-restriction |
Limit execution to a group; defaults to unlimited if not specified |
|
--gtm |
Install GT.M instead of YottaDB |
|
--help |
Print this usage information |
|
--installdir dirname |
Directory where YottaDB is to be installed (defaults to /usr/local/lib/yottadb/version) |
|
--keep-obj |
Keep .o files of M routines (normally deleted on platforms with YottaDB support for routines in shared libraries); |
|
--linkenv dirname |
Create link in dirname to ydb_env_set and gtmcshrc files; incompatible with copyenv |
|
--linkexec dirname |
Create link in dirname to ydb script; incompatible with copyexec |
|
--octo |
† |
Download and install Octo® a YottaDB plugin for SQL access to databases. --octo implies --posix. |
--overwrite-existing |
Install into an existing directory, overwriting contents; defaults to requiring new directory |
|
--plugins-only |
Add or update specified plugins to an existing YottaDB installation. This option requires the --overwrite-existing option as the YottaDB directory must already exist. |
|
--posix |
† |
Download and install the YottaDB POSIX plugin |
--prompt-for-group |
* |
YottaDB installation script prompts for group; default is yes |
--ucaseonly-utils |
Install only upper case utility program names; defaults to both if not specified |
|
--user username |
User who should own YottaDB installation; default is root |
|
--utf8 ICU_version |
Install UTF-8 support using specified major.minor ICU version; specify default to use default version |
|
--verbose |
* |
Output diagnostic information as the script executes; default is to run quietly |
--zlib |
Download and install the YDBzlib plugin |
Options that take a value (e.g, --group) can be specified as either --option=value or --option value
Options marked with * are likely to be of interest primarily to YottaDB developers
Options marked with † require Internet access as well as that
gcc
and required libraries be installed.Version is defaulted from the yottadb file if one exists in the same directory as the installer
This script must run as root.
ydbinstall
/ ydbinstall.sh
creates usr/share/pkgconfig
(the directory where pkg-config
by default tracks packages) if it does not exist. Note that this was added effective release r1.34.
Examples¶
sudo ./ydbinstall.sh
This example installs the latest YottaDB release in a subdirectory of /usr/local/lib/yottadb
, e.g., /usr/local/lib/yottadb/r130
.
sudo ./ydbinstall.sh --utf8 default --verbose
This example installs the latest YottaDB release with added support for UTF-8 and outputs diagnostic information as the script executes.
sudo ./ydbinstall.sh --installdir /r120 r1.20
This example installs YottaDB release r1.20 in the r120 directory.
sudo ./ydbinstall.sh --gtm
This example installs the latest GT.M version in a subdirectory of /usr/local/lib/yottadb/
.
The --encplugin
, --octo
and --posix
options were added to the ydbinstall
/ ydbinstall.sh
script effective release r1.30.
If the build of any plugin (those installed by --encplugin
, --octo
, --posix
, and --zlib
command line options) does not succeed, the ydbinstall
script retains the directory where it built the plugin.
The --plugins-only
option was added to the ydbinstall
/ ydbinstall.sh
script effective release r1.34. It adds or updates specified plugins to an existing YottaDB installation. Note that this option requires the --overwrite-existing
option as the YottaDB directory must already exist.
With the --from-source <repo>
option, the ydbinstall
/ ydbinstall.sh
script clones the repository specified by <repo>
using git clone <repo>
in the current directory, and changes to the YDB/
subdirectory.
If --branch <branch>
is specified, it executes git checkout -B <branch>
to specify a branch other than the default. Then it builds YottaDB, and if successful, installs the built YottaDB using sudo ydbinstall
of the ydbinstall
script of the built YottaDB, passing it all command line options except the --from-source
and --branch
options. The sudo ydbinstall
prompts for a password as required.
For example, ydbinstall --from-source https://gitlab.com/ydbuser/YDB.git --branch working --utf8 default --aim --install-directory /usr/local/lib/yottadb/devel_$(date +%Y%m%d)
will checkout, build, and install the working
branch of YottaDB from the YDB repository of GitLab user ydbuser
in a date-stamped directory, along with the Application Independent Metadata plugin.
This was added effective release r1.34.