~ibmcharmers/charms/trusty/layer-ibm-mobilefirst-server/devel

« back to all changes in this revision

Viewing changes to README.md

  • Committer: Suchitra Venugopal
  • Date: 2016-05-04 09:59:42 UTC
  • Revision ID: suchvenu@in.ibm.com-20160504095942-f3hp9a4iydhbnw3i
DB2 layered charm

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Charm for IBM DB2 10.5
 
2
 
 
3
Overview
 
4
--------
 
5
 
 
6
IBM DB2
 
7
 
 
8
IBM DB2 Enterprise Server Edition provides scalable database server software to handle the demanding workloads of large and midsize enterprise servers. It delivers high performance across multiple workloads, while helping to reduce administration, storage, development and server costs.
 
9
DB2 Server is provided as part of this charm.
 
10
 
 
11
For details on DB2, as well as information on purchasing, please visit:
 
12
[Product Page LUW][product-page-enterprise] and [Product Page Express][product-page-express]
 
13
 
 
14
More information available at the [IBM Knowledge Center][ibm-db2]
 
15
 
 
16
Usage
 
17
-----
 
18
The user will need to procure the appropriate license to be able to download and use IBM DB2. 
 
19
 
 
20
To acquire and download DB2, follow instructions available at [Product Page LUW][product-page-enterprise] or [Product Page Express][product-page-express].
 
21
The tab `Support&downloads` in [Product Page LUW][product-page-enterprise] gives different options for downloading the packages. 
 
22
 
 
23
Download steps for IBM DB2 10.5 using [Passport Advantage][passport-advantage] is mentioned in [Downloading IBM DB2 10.5 for LUW][download-db2]. The Part Number used is CIXV0ML for X86-64 platform and that for Power is CN3YQML. To get more information on accessing [Passport Advantage][passport-advantage] please visit the link [Accessing Passport Advantage][access-passport-advantage].
 
24
 
 
25
To install the downloaded binaries you must agree to the IBM license. You can view the full license for DB2 by visiting the [Software license agreements search website][license-info]. Search for "DB2 Enterprise Server Edition 10.5.0.5" and choose the license that applies to the version you are using.
 
26
 
 
27
In case you already have an IBM account and cannot download the product or for other error during SW download, please refer to the [IBM Support Site][ibm-support] to solve the error.
 
28
 
 
29
Download of Product Binaries
 
30
----------------------------
 
31
For deploying IBM DB2 charm the user needs to download the correct package as mentioned in the `Usage` section and host it on an SFTP or Web server. The  IBM DB2 charm will connect to the server(either by SFTP or HTTP method) to download and deploy the same. The host server can be any Power Ubuntu/X86 Ubuntu servers and should be copied into a directory structure as below
 
32
 
 
33
`/<path to charm dir>/charm/repository/<productname>/<package.tar>`
 
34
 
 
35
The complete path where the package is stored is a configurable item which needs to be configured before deploying the charm. 
 
36
 
 
37
 
 
38
Memory and Disk Requirements
 
39
----------------------------
 
40
At a minimum, a DB2 database system requires 256 MB of RAM. For a system running just a DB2 product and the DB2 GUI tools, a minimum of 512 MB of RAM is required. However, 1 GB of RAM is recommended for improved performance.
 
41
 
 
42
On Linux and UNIX operating systems, 2 GB of free space in the /tmp directory is recommended. Please make sure this minimum memory configuration is available before deploying the charm. More information on this can be found in [Memory Requirements][db2-memory-disk-requirement]
 
43
 
 
44
Deploy
 
45
------
 
46
To deploy DB2 charm run the following command:
 
47
 
 
48
1. Make sure the appropriate memory requirements are made available
 
49
 
 
50
2. For deploying either use an existing machine, or create a new machine using
 
51
 
 
52
        juju add-machine
 
53
        juju deploy --to <machine number> --repository=<path_to_charms_folder> local:trusty/ibm-db2
 
54
 
 
55
3. Set all required config values like the curl__opts to log into the host machine and curl_url which specifies the url to download the packages, by using juju set command. To provide these run the following command: 
 
56
 
 
57
        juju set ibm-db2 curl_opts=<login credentials>
 
58
        juju set ibm-db2 curl_url=<url to download package and sha value>
 
59
 
 
60
  For eg:
 
61
 
 
62
        juju set ibm-db2 curl_opts="-u user:password"
 
63
        juju set ibm-db2 curl_url="http://<ipaddress>/debs/ibm-db2/DB2_Svr_10.5.0.3_Linux_x86-64.tar.gz?sha512=ae20be99e3cd2cef24d53a28331871d7193cfc7f7c24c580e6e78dc58c9ffb364cbcc69cb3773d2f0135b8c9be7ee40a7dc4e09fec0a4d731c4864bbba87d31e"
 
64
   
 
65
   The command to find the checksum value is `sha512sum <Package Name>`
 
66
 
 
67
 (In the above example sha512 is used, you can use sha256 or md5 as well)
 
68
In the above example, the packages are hosted on webserver, so http protocol is used, if you have placed the packages on sftp server, then replace the protocol with sftp
 
69
 
 
70
4. At this point DB2 install will wait for you to accept the License. To install the downloaded binaries you must agree to the IBM license.  The license file(s) can be found in the product binaries you downloaded.
 
71
 
 
72
If you agree to the license, run the following command :
 
73
 
 
74
    juju set ibm-db2 license_accepted=True
 
75
 
 
76
 
 
77
Juju deploy command will install db2 and will expose the hostname, port number, db2 instance, install path  and userid to the users. 
 
78
 
 
79
 
 
80
Uninstallation of IBM DB2
 
81
---------------------------
 
82
 
 
83
Setting the accept-ibm-db2-license to False will uninstall the product. 
 
84
 
 
85
    juju set ibm-db2 license_accepted=False
 
86
 
 
87
Additional configuration parameters 
 
88
-----------------------------------
 
89
 
 
90
Following shows the different configurable values for ibm-db2 charm:
 
91
 
 
92
* If the user wants to set a different file path used to create databases and logs it can be set using the config value dftdbpath. Use the following command to set it
 
93
 
 
94
        juju set ibm-db2 dftdbpath=<new-path-to-set>
 
95
 
 
96
    For eg:
 
97
 
 
98
        juju set ibm-db2 dftdbpath="/tmp"
 
99
 
 
100
 
 
101
Installation Verification
 
102
------------------------
 
103
Once IBM DB2 charm is deployed, the user can log into the container/machine where it�s deployed using the default user/password (db2inst1/db2inst1). The user can run any db2 commands after this. 
 
104
  
 
105
  * For creating a new DB the user may run the command:
 
106
 
 
107
        db2 create database <db-name>
 
108
 
 
109
  * For listing the DBs created, run the command:
 
110
        
 
111
        db2 list db directory
 
112
 
 
113
  * For getting db2 command prompt just run the command:
 
114
 
 
115
        db2
 
116
 
 
117
Relating with other consumer charms
 
118
----------------------------------
 
119
IBM DB2 charm can be related to other consumer charms using the following command.
 
120
 
 
121
    juju add-relation ibm-db2 <consumer-charm>
 
122
 
 
123
When IBM DB2 charm is related to any consumer charm, it creates a db2instance, username/password as per the service name and will be provided to the consumer charm.(User can also refer to the IBM DB2 charm log to get the DB details passed to the consumer charm). IBM DB2 charm also creates DBs as provided by the consumer charm. The following code will help the consumer charm authors to pass the DB names to the IBM DB2 charm:  
 
124
 
 
125
    @when 'db.connected'
 
126
    function configure_dbs(){
 
127
      dbnames="db1,db2"
 
128
      relation_call --state=db.connected set_dbs $dbnames || true
 
129
     }
 
130
 
 
131
If no DB name is provided by consumer charm, IBM DB2 charm by default creates DBs according to  the service name.
 
132
 
 
133
Also to set relation with IBM DB2 charm and make use of all the features, the consumer charm __should__ pass the ssh key from itself to IBM DB2 charm. The following code will help the consumer charm authors to do this :
 
134
 
 
135
     @when 'db.connected'
 
136
     @when_not 'test.sshconfigured'
 
137
     function configure_sshkeys(){
 
138
     SSH_PATH=/root/.ssh
 
139
     if [ ! -f  $SSH_PATH/id_rsa.pub ]; then
 
140
                juju-log "Setting up SSH keys."
 
141
                ssh-keygen -t rsa -f $SSH_PATH/id_rsa -N ''
 
142
     fi
 
143
     key="`cat $SSH_PATH/id_rsa.pub`"
 
144
     relation_call --state=db.connected set_ssh_keys $key || true`
 
145
     set_state 'test.sshconfigured'
 
146
    }
 
147
 
 
148
Without this IBM DB2 charm will not be ready and will not create the DBs for the related services. 
 
149
 
 
150
Configuration
 
151
-------------
 
152
See config.yaml file for more information.
 
153
 
 
154
  *  `license_accepted`: True to accept license. Before you can use or install IBM DB2, you must accept the terms of International License Agreement for Non-Warranted Programs and additional license information. Please read the license agreement carefully. The license file(s) can be found under the server/db2/license directory after downloading and extracting IBM DB2 there. Set the value of license_accepted to True if you agree to IBM DB2 license.
 
155
 
 
156
 
 
157
  * `dftdbpath`             : This parameter contains the default file path used to create databases under the database manager.  If no path is specified when a database is created, the database is created under the path specified by the dftdbpath parameter.
 
158
 
 
159
  * `curl_url`              : For downloading package we need to set curl_url with following options.
 
160
 
 
161
- *hostname* - The web server host name from which IBM DB2 installation packages can be downloaded.
 
162
- *package_dir* - The package directory path in the server.
 
163
- *package name* - The IBM DB2 Package name.
 
164
- *checksum value* - Checksum value to check integrity of IBM DB2 package. The Charm
 
165
uses sha512sum to check the integrity. If empty, it does not carry out the integrity check. Use 
 
166
`sha512sum <Package Location/Package Name>`
 
167
to find out Checksum value for downloaded package.
 
168
 
 
169
  
 
170
  * `curl_opts`                : We need to set curl_opts with following options.
 
171
- *username* - User name of the host machine.
 
172
- *password* - Password of the host machine.
 
173
 
 
174
 
 
175
Additional product information
 
176
------------------------------
 
177
 
 
178
##### Enabling BLU acceleration for DB2 Advanced Enterprise Server Edition/DB2 Advanced Workgroup Server Edition
 
179
 
 
180
The same DB2 charm(DB2 Enterprise Server Edition) can be extended to enable the BLU acceleration(DB2 Advanced Enterprise Server Edition/DB2 Advanced Workgroup Server Edition)  by following the below section. The DB2 charm has to be deployed first and then few settings need to be done to enable the BLU feature. 
 
181
 
 
182
To upgrade DB2 Enterprise Server Edition (DB2 ESE) to DB2 Advanced Enterprise Server Edition(DB2 AESE) or DB2 Advanced Workgroup Server Edition (DB2 AWSE) the user need to accept the license for the same. Run the following command for accepting the AESE/AWSE license which the user procures on buying the Advanced Enterprise/ Workgroup Server Edition product. The user needs to log in using the configured user name/password to run the below commands.
 
183
 
 
184
    db2licm -a </path/to/license/file/db2aese_u.lic>
 
185
        or
 
186
    db2licm -a </path/to/license/file/db2awse_u.lic>
 
187
    
 
188
`db2licm -l` command will show the license details once you apply the license. 
 
189
Now to enable the BLU feature the DB2_WORKLOAD registry variable has to be set to ANALYTICS and then the DB has to be restarted. The following commands will help the user for this.
 
190
 
 
191
    db2set DB2_WORKLOAD=ANALYTICS
 
192
    db2stop force
 
193
    db2start
 
194
    
 
195
To test that DB2 AESE with BLU acceleration is enabled run the following command:
 
196
    
 
197
    db2 create database <test-db>
 
198
    db2 connect to <test-db> 
 
199
    db2 get db cfg | grep DFT_TABLE_ORG
 
200
    
 
201
The output Default table organization              (DFT_TABLE_ORG) = COLUMN confirms that the DB2 AESE/AWSE with BLU is enabled. If the pre requisites for DB2 for AESE/AWSE is not set (accepting the proper license and setting the registry variable DB2_WORKLOAD) the above command would return Default table organization              (DFT_TABLE_ORG) = ROW.  Column-organized tables store each column on a separate set of pages on disk. Organizing data by column on disk reduces the amount of I/O needed for processing queries because only columns that are referenced in a query need to be accessed. 
 
202
 
 
203
Once this is set all the tables created will be by default COLUMN organized whereas without BLU acceleration the tables will be ROW organized. Also without proper license we cannot create COLUMN organized tables. Once we enable COLUMN organized tables, we can create either ROW enabled or COLUMN enabled tables using the option ORGANIZE BY ROW or ORGANIZE BY COLUMN while creating the tables by running the below commands from db2 command prompt.
 
204
 
 
205
    create table sales_row(tid integer not null, prod_name varchar(30)) ORGANIZE BY ROW
 
206
    create table sales_col(tid integer not null, prod_name varchar(30)) ORGANIZE BY COLUMN
 
207
 
 
208
The following command will convert the ROW organized tables to COLUMN organized if the proper license is accepted. Without having valid license the following command will error out.  
 
209
   
 
210
    db2convert -d       <test-db>
 
211
    
 
212
More details on BLU feature can be found in the link [db2-BLU-acceleration]
 
213
 
 
214
IBM DB2 Links and Contacts
 
215
--------------------------
 
216
 
 
217
(1) General Information
 
218
Information on IBM DB2 available at the [DB2 Knowledgecenter][db2-knowledgecenter]
 
219
 
 
220
(2) Download Information
 
221
Information on procuring DB2 product is available at the [Passport Advantage Site][passport-db2]
 
222
 
 
223
(3) Contact Information
 
224
For issues with this charm, please contact <jujusupp@us.ibm.com>
 
225
 
 
226
 
 
227
<!-- Links -->
 
228
 
 
229
[product-page-express]: http://www-03.ibm.com/software/products/en/db2-express-server-edition
 
230
 
 
231
[product-page-enterprise]: http://www-01.ibm.com/software/data/db2/linux-unix-windows/index.html
 
232
 
 
233
[download-db2]: http://www-01.ibm.com/support/docview.wss?uid=swg21638030
 
234
 
 
235
[passport-advantage]: http://www.ibm.com/software/howtobuy/passportadvantage
 
236
 
 
237
[access-passport-advantage]: http://www-01.ibm.com/support/docview.wss?uid=swg21566554
 
238
 
 
239
[ibm-db2]: http://www-01.ibm.com/support/knowledgecenter/SSEPGG_10.5.0/com.ibm.db2.luw.kc.doc/welcome.html
 
240
 
 
241
[license-info]: http://www-03.ibm.com/software/sla/sladb.nsf/search
 
242
 
 
243
[passport-db2]: http://www-01.ibm.com/software/passportadvantage/
 
244
 
 
245
[db2-knowledgecenter]: http://www-01.ibm.com/support/knowledgecenter/SSEPGG_10.5.0/com.ibm.db2.luw.kc.doc/welcome.html
 
246
 
 
247
[ibm-support]: https://www-947.ibm.com/support/entry/myportal/support
 
248
 
 
249
[db2-BLU-acceleration]: http://www.ibm.com/developerworks/data/library/techarticle/dm-1309db2bluaccel/
 
250
 
 
251
[db2-memory-disk-requirement]: http://www-01.ibm.com/support/knowledgecenter/SSEPGG_9.7.0/com.ibm.db2.luw.qb.server.doc/doc/r0008877.html?cp=SSEPGG_9.7.0%2F
 
252
 
 
253
 
 
254
 
 
255
 
 
256