From 70605bfea11ae0e60fff2517cc22862bacb99b5c Mon Sep 17 00:00:00 2001 From: Bimal Jha Date: Wed, 11 Dec 2024 21:06:03 +0530 Subject: [PATCH] doc: update installation and SSL connection info --- INSTALL.md | 131 +++++++++++++++++++++++++---------------------------- README.md | 126 ++++++++++++++++++++++++++++----------------------- 2 files changed, 131 insertions(+), 126 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index ebde896..b2786cb 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -34,9 +34,24 @@ Following are the steps to installation in your system. This go_ibm_db driver has been tested on 64-bit/32-bit IBM Linux, MacOS and Windows. +### 1.1 clidriver info for MacOS +* Latest version of clidriver available for MacOS x64 system is: v11.5.9 +* By default on Intel Chip Macos, clidriver of v11.5.9 will get downloaded. +* First version of clidriver supported on MacOS ARM64 system is: v12.1.0 +* On MacOS M1/M2/M3 Chip system, by default clidriver of v12.1.0 will get downloaded. +### 1.2 License requirement to connect to Db2 for z/OS and Db2 for iSeries servers +* Please read [this doc](https://github.com/ibmdb/go_ibm_db/blob/master/README.md#for-zos-and-iseries-connectivity-and-sql1598n-error) for detail info about license requiremnet and resolving SQL1598N error during connection. +* clidriver v12.1.0 requires db2connect v12.1 license to connect z/OS or iSeries severs. +* MacOS Silicon Chip (arm64 processor) is supported using v12.1 clidriver only and hence require db2connect v12.1 license. +* You can force go_ibm_db driver to use older version of clidirver by setting system level environment varialbe CLIDRIVER_DOWNLOAD_VERSION or explicitly setting IBM_DB_DOWNLOAD_URL to point path of clidriver.tar.gz file. +``` + export CLIDRIVER_DOWNLOAD_VERSION=v11.5.9 + export IBM_DB_DOWNLOAD_URL=https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/v11.5.9/linuxx64_odbc_cli.tar.gz + go run setup.go +``` ## 2. Go_ibm_db Installation on Linux. @@ -44,12 +59,14 @@ This go_ibm_db driver has been tested on 64-bit/32-bit IBM Linux, MacOS and Wind Download the [GoLang Linux binaries](https://golang.org/dl) or [Go Latest binaries](https://go.dev/dl) and -extract the file, for example into `/mygo`: +extract the file, for example into `$HOME/mygo`: ``` -cd /mygo -wget -c https://golang.org/dl/go1.20.5.linux-amd64.tar.gz -tar -xzf go1.20.5.linux-amd64.tar.gz +cd $HOME/mygo +wget -c https://golang.org/dl/go1.22.1.linux-amd64.tar.gz +tar -xzf go1.22.1.linux-amd64.tar.gz +export GOROOT=$HOME/mygo/go +export GOPATH=$HOME/mygo ``` Set PATH to include Go: @@ -69,7 +86,13 @@ using directory `/goapp` for example. 2. cd goapp 3. go install github.com/ibmdb/go_ibm_db/installer@latest or - go install github.com/ibmdb/go_ibm_db/installer@v0.4.3 + go install github.com/ibmdb/go_ibm_db/installer@v0.5.2 +4. ls $GOPATH/pkg/mod/github.com/ibmdb + go_ibm_db@v0.5.2 +5. cd $GOPATH/pkg/mod/github.com/ibmdb/go_ibm_db@v0.5.2/installer +6. go run ./setup.go +7. export IBM_DB_HOME=$GOPATH/pkg/mod/github.com/ibmdb/clidriver +8. source ./setenv.sh ``` It's Done. @@ -77,36 +100,23 @@ It's Done. #### 2.2.2 Manual Installation by using git clone. ``` -1. mkdir goapp +1. mkdir $HOME/goapp 2. cd goapp 3. git clone https://github.com/ibmdb/go_ibm_db/ +4. go env GOPATH +5. cd go_ibm_db/installer +6. go run ./setup.go +7. export IBM_DB_HOME=$HOME/goapp/clidriver +8. source ./setenv.sh ``` -### 2.3 Download clidriver - -Download clidriver in your system, use below command: -go to installer folder where go_ibm_db is downloaded in your system -(Example: /home/uname/go/src/github.com/ibmdb/go_ibm_db/installer or /home/uname/goapp/go_ibm_db/installer -where uname is the username) and run setup.go file (go run setup.go) - - -### 2.4 Set environment variables to clidriver directory path - -#### 2.4.1 Manual +If IBM_DB_HOME is already set or, sourcing setenv.sh fails, create below environment variables: ``` -export IBM_DB_HOME=/home/uname/clidriver export CGO_CFLAGS=-I$IBM_DB_HOME/include export CGO_LDFLAGS=-L$IBM_DB_HOME/lib -export LD_LIBRARY_PATH=/home/uname/clidriver/lib -or -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$IBM_DB_HOME/lib +export LD_LIBRARY_PATH=$IBM_DB_HOME/lib:$LD_LIBRARY_PATH ``` -#### 2.4.2 Script file -``` -cd .../go_ibm_db/installer -source setenv.sh -``` ## 3. Go_ibm_db Installation on MacOS x64 and arm64 Systems ### 3.1 Install GoLang for Mac @@ -123,9 +133,9 @@ extract the file. 2. cd goapp 3. go install github.com/ibmdb/go_ibm_db/installer@latest or - go install github.com/ibmdb/go_ibm_db/installer@v0.5.1 + go install github.com/ibmdb/go_ibm_db/installer@v0.5.2 4. go env GOPATH -5. cd $GOPATH/pkg/mod/github.com/ibmdb/go_ibm_db@v0.5.1/installer +5. cd $GOPATH/pkg/mod/github.com/ibmdb/go_ibm_db@v0.5.2/installer 6. go run setup.go 7. export IBM_DB_HOME=$GOPATH/pkg/mod/github.com/ibmdb/clidriver 8. source ./setenv.sh @@ -148,41 +158,23 @@ It's Done. 11. go run main.go ``` -### 3.3 Download clidriver - -To download clidriver in your system, use below command: -Cd to installer folder where go_ibm_db is downloaded in your system -(Example: /home/uname/go/src/github.com/ibmdb/go_ibm_db/installer or /home/uname/goapp/go_ibm_db/installer -where uname is the username) and run setup.go file (`go run setup.go`) +### 3.3 Set environment variables to clidriver directory path -#### 3.3.1 downloaded driver version - -* Latest version of clidriver available for MacOS x64 system is: v11.5.9 -* By default on Intel Chip Macos, clidriver of v11.5.9 will get downloaded. -* First version of clidriver supported on MacOS ARM64 system is: v12.1.0 -* On MacOS M1/M2/M3 Chip system, by default clidriver of v12.1.0 will get downloaded. - - -### 3.4 Set environment variables to clidriver directory path - -#### 3.4.1 Manual +#### 3.3.1 Manual ``` export IBM_DB_HOME=/home/uname/clidriver export CGO_CFLAGS=-I$IBM_DB_HOME/include export CGO_LDFLAGS=-L$IBM_DB_HOME/lib - -export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/home/uname/go/src/github.com/ibmdb/clidriver/lib -or export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$IBM_DB_HOME/lib ``` -#### 3.4.2 Script file +#### 3.3.2 Script file ``` cd .../go_ibm_db/installer source setenv.sh ``` -#### 3.4.3 Disable SIP or create symlink of libdb2 on MacARM64 sysem +#### 3.3.3 Disable SIP or create symlink of libdb2 on MacARM64 sysem * New MacOS systems comes with System Integrity Protection(SIP) enabled which discards setting of DYLD_LIBRARY_PATH env variable * Disable SIP if your Go app gives error that: file `libdb2.dylib` not found. @@ -210,34 +202,33 @@ using directory `/goapp` for example. 2. cd gopapp 3. go install github.com/ibmdb/go_ibm_db/installer@latest or - go install github.com/ibmdb/go_ibm_db/installer@v0.4.3 + go install github.com/ibmdb/go_ibm_db/installer@v0.5.2 +4. go env GOPATH +5. cd %GOPATH%\pkg\mod\github.com\ibmdb\go_ibm_db@v0.5.2\installer +6. go run setup.go +7. + set IBM_DB_HOME=%GOPATH%\pkg\mod\github.com\ibmdb\clidriver + set CGO_CFLAGS=-I%IBM_DB_HOME%\include + set CGO_LDFLAGS=-L%IBM_DB_HOME%\lib + set LIB=%IBM_DB_HOME%\lib;%LIB% ``` #### 4.2.2 Manual Installation by using git clone. ``` -1. mkdir goapp +1. mkdir %HOME%\goapp 2. cd goapp 3. git clone https://github.com/ibmdb/go_ibm_db/ +4. go env GOPATH +5. cd go_ibm_db\installer +6. go run setup.go +7. + set IBM_DB_HOME=%HOME%\goapp\clidriver + set CGO_CFLAGS=-I%IBM_DB_HOME%\include + set CGO_LDFLAGS=-L%IBM_DB_HOME%\lib + set LIB=%IBM_DB_HOME%\lib;%LIB% ``` -### 4.3 Download clidriver - -Download clidriver in your system, go to installer folder where go_ibm_db is downloaded in your system, use below command: -(Example: C:\Users\uname\go\src\github.com\ibmdb\go_ibm_db\installer or C:\goapp\go_ibm_db\installer - where uname is the username ) and run setup.go file (go run setup.go). - - -### 4.4 Set environment variables to clidriver directory path - -#### 4.4.1 Manual -``` -set IBM_DB_HOME=C:\Users\uname\go\src\github.com\ibmdb\clidriver -set PATH=%PATH%;C:\Users\uname\go\src\github.com\ibmdb\clidriver\bin -or -set PATH=%PATH%;%IBM_DB_HOME%\bin -``` - -### 4.4.2 Script file +### 4.3 Script file ``` cd .../go_ibm_db/installer Run setenvwin.bat diff --git a/README.md b/README.md index a58f328..8b01294 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ yum install go git tar libpam ### Note: * Environment variable `DB2HOME` is changed to `IBM_DB_HOME`. -* **SQL1598N Error** - It is expected in absence of valid db2connect license. Please click [here](#Licenserequirements) and read instructions about license requirement and how to apply the license. +* **SQL1598N Error** - It is expected in absence of valid db2connect license. Please click [here](#for-zos-and-iseries-connectivity-and-sql1598n-error) and read instructions about license requirement and how to apply the license. * go_ibm_db@v0.5.1 is the last version to download v11.5.9 clidriver by defualt and first version to support MacOS arm64 platform using v12.1.0 clidriver. * There is no MacOS Intel Chip clidriver from v12.1.0 onwards. @@ -33,7 +33,7 @@ yum install go git tar libpam ``` go get -d github.com/ibmdb/go_ibm_db go install github.com/ibmdb/go_ibm_db/installer@latest -go install github.com/ibmdb/go_ibm_db/installer@v0.5.1 +go install github.com/ibmdb/go_ibm_db/installer@v0.5.2 ``` - You can optionally specify a specific cli driver by setting the IBM_DB_DOWNLOAD_URL environment variable @@ -43,25 +43,34 @@ cli driver instead of the latest one, set the variable as below: export IBM_DB_DOWNLOAD_URL=https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/v11.5.4/macos64_odbc_cli.tar.gz ``` -- If you already have a clidriver available in your system, add the path of the same to your +- You can instruct go_ibm_db driver to download specific version of clidriver by setting environment variable `CLIDRIVER_DOWNLOAD_VERSION=` before running `setup.go` file. f.e. `export CLIDRIVER_DOWNLOAD_VERSION=v11.5.9` + +- If you already have a dsdriver/db2client/db2server or clidriver with include directory available in your system, add the path of the same to your PATH windows environment variable. Example: -`set PATH = "C:\Program Files\IBM\IBM DATA SERVER DRIVER\bin";%PATH%` +``` + set PATH="C:\Program Files\IBM\IBM DATA SERVER DRIVER\bin";%PATH% + set LIB="C:\Program Files\IBM\IBM DATA SERVER DRIVER\lib";%LIB% +``` + +- Note that the `clidriver` or Runtime Client (RTCL) downloaded from IBM Fix Central do not have `include` directory and do not work with `go_ibm_db` driver. Download `IBM Data Sever Driver Package` or `IBM Data Server Client` (CLNT) from fix central and install. - If you do not have a clidriver in your system, go to installer folder where `go_ibm_db` is downloaded in your system, use below command: (Example: C:\Users\uname\go\src\github.com\ibmdb\go_ibm_db\installer or C:\Users\uname\go\pkg\mod\github.com\ibmdb\go_ibm_db\installer where uname is the username ) and run setup.go file (`go run setup.go`). + setup.go file will automatically download clidriver from IBM hosted site under parent directory of go_ibm_db. ``` Set IBM_DB_HOME to clidriver downloaded path and set this path to your PATH windows environment variable (Example: Path=C:\Users\uname\go\src\github.com\ibmdb\clidriver) set IBM_DB_HOME=C:\Users\uname\go\src\github.com\ibmdb\clidriver -set PATH=%PATH%;C:\Users\uname\go\src\github.com\ibmdb\clidriver\bin -or -set PATH=%PATH%;%IBM_DB_HOME%\bin +set PATH=%IBM_DB_HOME%\bin;%PATH% +set LIB=%IBM_DB_HOME%\lib;%LIB% +set CGO_CFLAGS=%IBM_DB_HOME%\include +set CGO_LDFLAGS=%IBM_DB_HOME%\bin ``` - Script file to set environment variable @@ -77,54 +86,10 @@ setenvwin.bat ``` go get -d github.com/ibmdb/go_ibm_db go install github.com/ibmdb/go_ibm_db/installer@latest -go install github.com/ibmdb/go_ibm_db/installer@v0.5.1 -``` - -- You can optionally specify a specific cli driver by setting the IBM_DB_DOWNLOAD_URL environment -variable to the full path of your desired driver. For example, if you want to install the 64-bit -macos v11.5.4 cli driver instead of the latest one, set the variable as below: -``` -export IBM_DB_DOWNLOAD_URL=https://public.dhe.ibm.com/ibmdl/export/pub/software/data/db2/drivers/odbc_cli/v11.5.4/macos64_odbc_cli.tar.gz -``` - -- If you already have a clidriver available in your system, set the below environment variables with the clidriver path -``` -export IBM_DB_HOME=/home/uname/clidriver -export CGO_CFLAGS=-I$IBM_DB_HOME/include -export CGO_LDFLAGS=-L$IBM_DB_HOME/lib -Linux: -export LD_LIBRARY_PATH=/home/uname/clidriver/lib -or -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$IBM_DB_HOME/lib -Mac: -export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/Applications/clidriver/lib +go install github.com/ibmdb/go_ibm_db/installer@v0.5.2 ``` -- If you do not have a clidriver available in your system, use below commands. -(Example: /home/uname/go/src/github.com/ibmdb/go_ibm_db/installer - or /home/uname/go/pkg/mod/github.com/ibmdb/go_ibm_db/installer -where uname is the username) and run setup.go file (`go run setup.go`) - -``` -export IBM_DB_HOME=/home/uname/go/src/github.com/ibmdb/clidriver -export CGO_CFLAGS=-I$IBM_DB_HOME/include -export CGO_LDFLAGS=-L$IBM_DB_HOME/lib -Linux: -export LD_LIBRARY_PATH=/home/uname/go/src/github.com/ibmdb/clidriver/lib -or -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$IBM_DB_HOME/lib -Mac: -export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/home/uname/go/src/github.com/ibmdb/clidriver/lib -or -export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$IBM_DB_HOME/lib -``` - -- Script file to set environment variables in Linux/Mac - -``` -cd .../go_ibm_db/installer -source setenv.sh -``` +Please check https://github.com/ibmdb/go_ibm_db/blob/master/INSTALL.md for detailed installation instructions. - For Docker Linux Container, use below commands: ``` @@ -138,8 +103,6 @@ rm /usr/bin/gofmt cp /usr/local/go/bin/go /usr/bin/ cp /usr/local/go/bin/gofmt /usr/bin/ -go install github.com/ibmdb/go_ibm_db/installer@v0.5.1 -or go install github.com/ibmdb/go_ibm_db/installer@latest ``` @@ -254,7 +217,9 @@ EOF - `ibm_db` returns SQL1598N error in absence of a valid db2connect license. SQL1598N error is returned by the Db2 Server to client. To suppress this error, Db2 server must be activated with db2connectactivate utility OR a client side db2connect license file must exist. -- Db2connect license can be applied on database server or client side. A **db2connect license of version 11.5** is required for ibm_db. +- Db2connect license can be applied on database server or client side. A **db2connect license of version 11.5** is required for go_ibm_db. + +- For MacOS M1/M2/M3 Chip System (ARM64 processor), db2connect license of version **12.1** is required for go_ibm_db. - For activating server side license, you can purchase either `Db2 Connect Unlimited Edition for System z®` or `Db2 Connect Unlimited Edition for System i®` license from IBM. @@ -536,6 +501,55 @@ go_ibm_db/testdata/config.json file. * To run a particular test case (use "go test sample_test.go main.go", example "go test Arraystring_test.go main.go") +For Secure Database Connection using SSL/TSL +============================================ + +> go_ibm_db supports secure connection to Database Server over SSL same as ODBC/CLI driver. If you have SSL Certificate from server or an CA signed certificate, just use it in connection string as below: + +``` +connStr := "DATABASE=database;HOSTNAME=hostname;PORT=port;Security=SSL;SSLServerCertificate=;PROTOCOL=TCPIP;UID=username;PWD=passwd;"; +``` +> Note the two extra keywords **Security** and **SSLServerCertificate** used in connection string. `SSLServerCertificate` should point to the SSL Certificate from server or an CA signed certificate. Also, `PORT` must be `SSL` port and not the TCPI/IP port. Make sure Db2 server is configured to accept connection on SSL port else `go_ibm_db` will throw SQL30081N error. + +> Value of `SSLServerCertificate` keyword must be full path of a certificate file generated for client authentication. + It normally has `*.arm` or `*.cert` or `*.pem` extension. `ibm_db` do not support `*.jks` format file as it is not a + certificate file but a Java KeyStore file, extract certificate from it using keytool and then use the cert file. + +> `go_ibm_db` uses IBM ODBC/CLI Driver for connectivity and it do not support a `*.jks` file as keystoredb as `keystore.jks` is meant for Java applications. + Note that `*.jks` file is a `Java Key Store` file and it is not an SSL Certificate file. You can extract SSL certificate from JKS file using below `keytool` command: + ``` + keytool -exportcert -alias your_certificate_alias -file client_cert.cert -keystore keystore.jks + ``` + Now, you can use the generated `client_cert.cert` as the value of `SSLServerCertificate` in connection string. + +> `go_ibm_db` supports only ODBC/CLI Driver keywords in connection string: https://www.ibm.com/docs/en/db2/11.5?topic=odbc-cliodbc-configuration-keywords + +> Do not use keyworkds like `sslConnection=true` in connection string as it is a JDBC connection keyword and go_ibm_db + ignores it. Corresponding ibm_db connection keyword for `sslConnection` is `Security` hence, use `Security=SSL;` in + connection string instead. + +* To connect to dashDB in IBM Cloud, use below connection string: +``` +connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=passwd;Security=SSL" +``` +> We just need to add **Security=SSL** in connection string to have a secure connection against Db2 server in IBM Cloud. + +**Note:** You can also create a KeyStore DB using GSKit command line tool and use it in connection string along with other keywords as documented in [DB2 Infocenter](http://www.ibm.com/support/knowledgecenter/en/SSEPGG_11.5.0/com.ibm.db2.luw.admin.sec.doc/doc/t0053518.html). + +If you have created a KeyStore DB using GSKit using password or you have got *.kdb file with *.sth file, use +connection string in below format: +``` +connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=dbuser;PWD=db2pwd;" + + "Security=SSL;SslClientKeystoredb=C:/client.kdb;SSLClientKeystash=C:/client.sth;" +OR, +connStr = "DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=dbuser;PWD=db2pwd;" + + "Security=SSL;SslClientKeystoredb=C:/client.kdb;SSLClientKeystoreDBPassword=kdbpasswd;" +``` + +> If you have downloaded `IBMCertTrustStore` from IBM site, ibm_db will not work with it; you need to + download `Secure Connection Certificates.zip` file that comes for IBM DB2 Command line tool(CLP). + `Secure Connection Certificates.zip` has *.kdb and *.sth files that should be used as the value of + `SSLClientKeystoreDB` and `SSLClientKeystash` in connection string. Logging: ========