Installing Connections

In this blog we’re going to look at installing a new version of Connections 5.5 then updating it with the latest fixes.

Setting Up The Repository
We start installing Connections by configuring a new repository in Installation Manager. Having extracted the Connections installer the repository.config will be found in the IBM Connections directory.


We opted to deselect the existing repositories that we used to install WebSphere.  We may need them later so deselecting is a better option than removing them entirely.  If however you do delete the installers from your file system you should remove them from the list of repositories as well


What Are We Installing?
The only product we can install is IBM Connections Version  Don’t worry about the fixes and updates at this point, we are just doing a base install initially.


Since we have never installed Connections on this machine Installation Manager will create a new package group to track the software.  The previous package group is used for WebSphere products only.


The next page has a list of features that can be installed as part of Connections.  By default all are selected and I would always install all for a standard  Connections build.  If you scroll down this list there are “Optional Components” such as Connections Content Manager which are not selected by default.  This would require additional licensing.


The next few screens take us through the Connections install and validate we have everything else in place.  You need to have installed and configured WebSphere as well as DB2 (or SQL/Oracle), created the databases and preferably populated them before you can install Connections.

Connecting To The Deployment Manager
On the first screen the installer needs to validate that WebSphere is in place and that it can login  The account listed here as “Administrator User ID” will by default be given access to all the Connections applications as they install.  You can’t click “next” on this screen until you click “Validate” and that changes to “Validated“.  To achieve that the installer will try to login to the deployment manager using the credentials you show.

Make sure the deployment manager is running or the installer will not be able to login.



You may receive a warning at this point that application security is not enabled and that will prevent the installer from validating.  If that happens, leave the installer on this screen and log back into the ISC on https://hostname:9043/ibm/console.

Go to Security – Global Security and choose “Enable application security”.  By default the box is unchecked. It needs to be checked as shown below and the configuration saved, then restart Deployment manager and go back to your Installer screen to try validating again.


If you receive a warning about missing SSO configuration when you try to enable application security simply click on “Single Sign-on (SSO)” under “Web and SIP security” on the right and enter the domain you are using for this environment as shown below.


So.. back to our installer screen and we have the nice “Validated” button at the bottom so we can now click “Next”


Where Do The Applications Go?
The topology page is where we choose how to deploy the Connections applications onto which servers.  IBM tries to help you here by asking what size deployment you want

You should only ever choose a “Small” deployment where every application is on a single WAS server instance for a test or development environment.  Bear in mind the server will be slow to start as every application will be on it. Also finding debug information in the logs may be harder since each log file will contain all content for all applications.

The most common option is “Medium” where the applications are spread across multiple server clusters.  Each server has its own allocation of memory and runs only the applications assigned to it.  In addition if we wanted to grow the environment by adding a cluster instance, we could choose to do so for only the most under demand servers/applications. IBM provide a suggestion for which applications should be assigned to which servers but it’s only a suggestion – you know your business and your requirements best.  Bear in mind it’s a good idea to spread the applications that will be under heavy load across different servers.

The “Large” deployment creates one server per application which could mean 20 or more server instances.  This would only be done for extremely large Enterprise deployments and will need to be planned carefully across multiple nodes.


For Connections101 we have chosen a “Medium” topology so IBM offers to create four individual server clusters to put the applications on.  Since our environment currently has only one node , all those instances will be created in that node.  This is an opportunity to move applications around between servers and even rename servers if we want.

You should already have a design in mind before you get to this point of the install.  If not stop now and think about how you want the applications deployed across how many servers.


Verifying The Databases
Our third page is where we tell the installer where the database server and databases are.  The installer will take the settings you provide here and attempt to access each database using those settings and credentials.  If you created a LCUSER account to use when running the DBWizard you would use those credentials here.  In the past on Linux there have been issues with case sensitivity for the account name so make sure if the account you create is ‘lcuser” you enter “lcuser” in lower case for the credentials.

See the earlier blog on the DBWizard for how to create the lcuser account


Defining The HTTP Server
On the fourth page we can choose to tell the installer about the IBM HTTP Server we created earlier.  This is a good idea and will save you work post install as the installer will ensure all the mappings for the applications to use IHS as a front end are in place including in the LotusConnections-Config.xml.  If you haven’t already created an IHS instance then you can choose “Do Later”.

Since we have already created the IHS node in our earlier blog and called it webserver1 all we have to do is choose “Do now” and the installer will select our server automatically.



Cognos. Leave it for now 🙂
We would always recommend installing Cognos later. The steps involved are fairly complex and take us away from the base Connections application install.  Once Connections is installed and updated (and backed up / snapshotted), we can come back and install Cognos.

Choosing not to install Cognos does not prevent the installer for installing the Metrics application which gathers activity for Cognos and other 3rd party tools to use so you will not lose data if Cognos isn’t immediately deployed.


Where Is The Data Going To Go?
On the content store page the installer needs to be told where to create and store data.  There are two content stores that need to be defined and both are used by every server.

  • a shared network content store.  The location of which must be accessible by every server regardless of platform.  Each server must use the identical path to find the content store so the path we choose to enter here has to be visible and accessible to each server.  If you have a mixed Windows and Linux environment or choose to put your content store on a Linux share, ensure that there is a single path that can reach that store from every server.
  • a local network content store.  The data in the local store is only used by the server on that machine and should be unique to each machine, however the path to the local store should be identical for each server.  We can workaround this post-install by modifying environment variables later on but for now we should plan for the path to the local store to be consistent.

The validation check on this page only verifies that the paths and directories exist to the installer.  It doesn’t verify that all servers can see them or even that they are writable as well as readable locations.  That’s something you need to confirm yourself


Mail Notifications And Replies
On the next tab we can configure the mail notifications.  This is something that is fairly straightforward to do post-install so if you haven’t considered how you want notifications to work you can stop and do that now.  If you think you might want to change things in the future then come back to it later.

We chose to have notifications (emails) to users as well as granting users the ability to reply to mail.  Since WebSphere has no mailboxes of its own the reply to messages must be delivered to an IMAP accessible mailbox on a server.


When defining how to find a mail server to send mail we have two choices We can use WebSphere’s own built in mail session to have SMTP mail sent to a specific server or we can rely on MX records in DNS to route mail for onward delivery. These options can also be easily changed post install.

Always use a dedicated account for sending and collecting mail and if possible use secure SMTP so the credentials cannot be intercepted en route.  The reason I prefer to use a dedicated account is to ensure the account is only used by Connections. It’s far too easy for a shared account to be renamed, deleted or even have its password changed without anyone thinking to tell the Connections admin!


Role Mapping
This is a new and much welcome feature in 5.5.  Here the installer gives us the option of adding users from our LDAP directory who will automatically be assigned administrative rights to each application (rather than just the connadmin account i’m using for the install).  Similarly we can add individual users as moderators and those will be granted the correct rights to provide moderation across applications.

One of the first things we used to do post install is go into each of the 20 or so applications and manually add additional administrative users and moderators so telling the installer now to do it for us saves a lot of time.  However, what I really want to do is add groups not individuals.  That way I could have a LDAP group called “ConnectionsAdmins” and have that added here.

If you are going to want to use groups rather than users for security it’s best to leave these options empty as this point and go back post install to manually add the groups.


We can now complete the install.  This could take anywhere from 20 minutes to 2 hours depending on the complexity of your environment, disk and network speed.


The lovely green tick is what we hope to see.  If the install fails, open the install log and read it carefully.  In my experience the install can often fail for three reasons

1. The person running the install doesn’t have the authority to write to the WebSphere servers or the file system

2. You run out of disk space on a partition during the install

3. There are old files hanging around from an earlier failed installed that need to be removed


Checking Everything Installed
Once the install says it completed successfully, we login to the ISC and verify all the applications are listed under “Enterprise Applications”


We also check all the servers we asked to be created on the topology page of the installer do now exist.


So that’s the install.  However before you go any further you are going to want to install any and all patches that have come out since the base 5.5 version of Connections was released.

Applying Fixes
Even if you think you have all the most recent fixes, now is the time to go to Fix Central and check there are no new updates for Connections 5.5


If you find new updates you should download them to your file system.  The very first thing we need to do is extract the updater file and find the .zip or .tar file within that.  That compressed file will itself extract into a directory called updateInstaller.

The updateInstaller must be extracted under the Connections install directory which in our environment is /opt/IBM/Connections.  Once extracted it looks like the screenshot below.


Any other fixes (jar files) that you download from fix central should be copied to the “fixes” directory here.

To run the update wizard for Connections, which applies all the fixes we run / bat but first we need to do two things

  1. Run setupcmdline from the Dmgr bin directory so /opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin/
  2. Set the WAS_HOME variable (as shown above)

Now we can run updateWizard


The Update Wizard can both install and remove updates.  That’s useful to us because there may be some cases when we may want to easily remove an update once it has been applied.

In this case we’re going to Install updates.  The updater lets us choose where the fixes are located so in theory we could put them anywhere and not just in the “fixes” directory under “/Connections/updateInstaller” however it’s safest to put them there and work from that directory.


The installer finds any fixes that were in that directory and asks us which ones to deploy showing the application affected (if it’s just a single application) and the release date of the fix.  skitch.2

In this case, because we went to apply all fixes at once, the upgrade wizard warns us that some of the fixes are already obsolete so we can go back to the previous screen and deselect those.


The update wizard gives us a final warning that we need to backup our customisation directory. At this point we are on a new install and have no customisations so we can go ahead and say we have made no changes.

If you have made changes, even if you don’t think the update you’re applying should affect those changes, make sure you manually back them up.


Finally it will run and apply all the updates.  During this process it will remove applications, add new applications, change configuration settings, clear out temporary data etc. In fact it could be completing a lot more work than happens during an install – this could take a long time.

If you are concerned about the progress of the updater it will be creating log files in the Connections install directory under the version / log location e.g /opt/IBM/Connections/version/log.  You can monitor this directory to see each update as it happens and reassure yourself things are progressing.

If you have problems with Connections after an upgrade IBM will want to see those log files so do not delete them.

Finally the updater will finish and confirm what it managed to successfully complete.


Confirming What Version Is Installed

If you’re a control freak like me you might now like to confirm the version of Connections you’re on by running the updateSilent command from the file system.  It can be found in the updateInstaller directory where we ran the wizard from and the syntax is

updateSilent -fix -installDir as shown in the screenshot below


and we’re done.  Now go make yourself a coffee and relax before we go onto the next step !


Running The Population Wizard

The first thing we’re going to want to do once the Connections applications successfully install is test them by logging in as a regular user.  To do that the user must have a profile in the PEOPLEDB or Connections will throw an error and the easiest way to ensure that exists is to run the Population Wizard.

The Population Wizard is a simple tool that asks a series of questions such as where is your LDAP directory, where are your DB2 databases, and where is TDI and uses those answers to run a one off script using TDI to import all users into Connections, creating them a profile along the way.  It’s designed to work in only one direction (you can pull information from LDAP to databases only, not the other way around).

For a test environment or a very small manually-maintained environment you could run the PopulationWizard to update the databases whenever you want but for production it’s not really workable.  However, this is just to ensure we have some data in place that we can use for testing.  We will work with the custom TDI scripts later to fine tune what we want.

To run the population wizard look in the “Wizards” directory from the ConnectionsWizards download.  The file will be called (or populationWizard.bat).



The JDBC drive path must contain the drivers for your database platform.  If you aren’t running TDI on the same server as your databases you will need to copy the drivers from the database server to the TDI server to reference them here.

The User ID is the account granted full rights to the PEOPLEDB database.  This can often be a custom account and not (as in this case) the instance owner.


Here we tell the wizard where our LDAP server is and how to connect to it.  If you are using a secure port such as 636 make sure you check the box for “Use SSL communication”


These are the bind credentials to login and query LDAP.  They aren’t stored anywhere in this activity or used for any purpose other than running this one-off wizard so any credentials would do.


This shows the sample mapping of LDAP attributes to database fields. For example “mail” in LDAP will map to the field “Office Email”.  On this screen we can choose what attributes to map where and even if we want to map attributes at all.  Anything we don’t map won’t be populated with data and will appear as empty in Connections.

Once the populationWizard completes it should report that it imported your users.  To do this it wrote instructions to properties files and ran script files stored in the location:

/Wizards/TDIPopulation/linux/TDI –

The files it wrote our instructions to are:

The script files it ran were:

The activity is recorded in /Wizards/TDIPopulation/linux/TDI/Logs.

We’ll come back to this later when we start customising our syncing activity.

Installing TDI

Tivoli Directory Integrator is used to move data between our LDAP source (in this case Domino) and our DB2 (or SQL or Oracle) profiles database (PEOPLEDB).  IBM supply a range of Wizards and batch files to achieve this and they all depend on having TDI installed somewhere.

Once the TDI installer is extracted we run ./ in Linux (or launchpad.exe in Windows) to start installing TDI.

On linux this may fail because there is a script that validates if a supported browser version is installed.  The script is a bit old and only checks for Firefox numbers beginning 1x and 2x – we’re currently on Firefox 35 and growing. To workaround that validation modify the file in the launchpad directory as follows


The regedit syntax using [1-9][0-9] should cover any version Mozilla release for a couple of years 🙂

Now should run



I choose a custom install because we only need a limited set of features installed for our purposes.


In theory I only need the Server component – the CE (Configuration Editor) is for creating and managing AssemblyLines.  In a simple install we don’t use it but I like to install it regardless and it’s very likely we will use it to customise our directory sync activity.


The working directory should not be a static choice. Each time one of our TDI scripts runs, the parameters for that script will come from the directory it exists in.  By not setting a working directory we are able to run multiple scripts from different locations with different settings.

Once TDI 7.1.1 is installed we need to patch it to fixpack 5 before doing anything further. After downloading the fixpack ( and extracting it there will be a file called UpdateInstaller.jar in the extracted directory.

Copy the new UpdateInstaller.jar file to /opt/IBM/TDI/V7.1.1/maintenance

Copy the extracted fix to a convenient location – in this case I’m using the directory where I’m going to run the update from /opt/IBM/TDI/V7.1.1/bin


To apply the fixpack we run ./ -update <fixpackfilelocation>



Once the updates have been applied we can verify it ran successfully using:

./ -queryreg

which shows us both components installed and patch levels for each.

In our environment we are installing TDI on the same server where DB2 is installed but if we weren’t we would have to copy the DB2 library files over to the TDI server so the two can communicate.

Setting Up An LDAP Repository

Before we do anything else we now need to make sure our users can login.

WebSphere only has an internal file repository that will only contain the “wasadmin” entry we created when installing.  The users and groups we want to be able to use Connections aren’t in that File Repository, they are in a LDAP directory (or directories) somewhere.  We need to tell WebSphere’s deployment manager where to find and authenticate those users.

First we need to consider where our directory is going to be and if there will be one or multiple directories (if all users aren’t held in one place).  For instance, if all my users login to Active Directory I might use that, or I might use Domino which itself could be running Directory Assistance.

When deciding on LDAP directory configuration:

  1. As few directories as possible should be referenced
  2. Every user should have a unique key in the directory
  3. If you use multiple directories each user should appear only once with their unique key. If my key is my email,, then there should only be one entry with that name across all the directories we reference.
  4. The directory should be a trusted source with strong password validation

In this case we’re going to choose a single Domino LDAP server but we could have just as easily chosen Active Directory or many other LDAP directory sources.

Adding external directories in WebSphere is known as adding Federated Repositories. Before modifying or adding any federated repository I like to take a backup of the Deployment Manager.  Very often if the LDAP configuration is wrong you can end up locking yourself out of WebSphere entirely and you will need to restore from that backup.

To backup go to the /bin directory under /profiles/Dmgr01 and run:

./ <locationofzipfile> -nostop


To add or modify a Federated Repository we go to Global Security in the ISC and choose “Configure” next to the “Available realm definitions – Federated repositories”:


We are going to add an LDAP repository:


Here we enter the details of the LDAP directory source we’re going to use.  In this case I have a Domino server running LDAP on hostname and secure port 636.  Note how the “Require SSL Communications” checkbox is enabled, you must select this if you are connecting to LDAP securely.

Choosing the right Directory type from the drop down list ensures that the LDAP query syntax is correctly formed for the directory you are accessing. Selecting “IBM Lotus Domino” when pointing to an Active Directory server will prevent the directory from working.

I do not recommend using bind credentials to login to your LDAP directory unless you are also using a secure SSL protocol to connect. If you are connecting using 389 or another non-encrypted port I would suggest an anonymous bind.

The field “Federated repository properties for login” will determine what values can be used to login.  These are all LDAP attributes that map to fields in the source directories. If possible in a Connections environment we want to have “uid” listed first.  UID maps to the value ‘shortname’ in Domino LDAP, ‘mail’ maps to the internet mail address and ‘cn’ maps to my fullname.  With the values set here as uid,mail,cn I will be able to login using variations of my name including:

Gabriella Davis
Gabriella Davis/Turtle

Finally the value for failover server can be used to point to other identical directories. Although many customers use a separate load balancer to handle LDAP failover, WebSphere actually responds faster to multiple LDAP failover servers entered here rather than waiting for a load balancer to return a new host.

WebSphere will attempt to validate all the information on this screen including hostname, bind credentials and port when we save. The next step is to define the Unique Distinguished Name for entries in this repository. Whatever we choose here, it must be unique across all directories.skitch.6

For this directory I could use the value O=Turtle and that will restrict valid users to just those with a hierarchical name containing the Turtle organisation e.g Gabriella Davis/Turtle.  In a Domino directory, unique for LDAP sources, not all entries are hierarchical (groups names for instance are flat) so with this configuration WebSphere won’t recognise any Domino groups.  One option to workaround that is to use the value “root” for the Unique distinguished name which will tell WebSphere to recognise all organisations and even flat names or groups.


We also need to make sure the Group definitions are correct for the directory type we are using.  For Domino the attribute use for defining a group is called “dominoGroup” not the default “groupofNames” and the member attribute is called “member”.

Once the repository is configured we log out of the ISC and restart the deployment manager, then we log back in and go to Users and Groups – Manage Users / Manage Groups to confirm that all our LDAP users and groups are found and displayed.

If I can’t log back in after a restart I can rollback to the earlier backed up instance of the deployment manager and start over.


Now that the Federated Repository is set up the next thing we want to do is add additional accounts that can administer the ISC, including a LDAP account which will become the Connections Administrator.  Here we are using an account called “connadmin” that I created in the Domino directory.  Once the account is added we can test that it works by logging out of the ISC and attempting to login as “connadmin”.

Creating The Databases For Connections

Before we can install the Connections applications we must create the databases they will use.  The database server can be DB2, SQL or Oracle but the licensing for DB2 is part of your Connections licensing whereas SQL and Oracle would need to be separately licensed.  I tend to use whatever server the customer feels most comfortable supporting, if they are a big SQL or Oracle house I’ll use that.  For our purposes, and if the customer has no preference I like to use DB2.  One note about high availability, the license for DB2 includes the rights to use active/passive HADR for DB2  which means creating two servers which sync with each other but with only one active at a time. To make the active server passive and make the passive server active requires a manual switchover and will entail some amount of downtime.  For additional license cost DB2 offer a full HADR active/active solution but I won’t be discussing that on this blog.

We already installed DB2 so now we just need to run the DBWizard to create the databases.  It’s important to use the db2inst1 account we created during install as “owner” of the DB2 instance (on Windows it’s probably called db2admin) to create the databases. This ensures that the db2inst1 has the right security access to the databases and that later, when the Connections applications attempt to write to the databases, everything works.

Now I can login as db2inst1.  Don’t use “su” as that can throw errors, always login to the server as the db2inst1 (or in Windows db2admin) account.

Setting The Environment

The first thing we should do is make sure the instance of DB2 can run all the Connections databases.  Run the command

db2 update dbm cfg using numdb 20 to allow up to 20 databases to run in this single instance.  That’s a high number but in a reasonably small environment (less than 1000 concurrent users say) it’s fine. 

We also need to set the DB2 instance to use unicode before Connections installs, we can do that whilst we’re here by typing

db2set db2codepage=1208

Then stop and start DB2 to make both the above changes take effect


Creating The Databases

IBM released Day 1 fixes for the DBWizards and you need to find and use these not the ones that shipped with 5.5.  They are on fixcentral and their filenames are


Using my root account I extract the tar file to a directory like this

mkdir /home2/db2inst1/DBWizard
cd /home/db2inst1/DBWizard
tar -xvf /opt/Software/ chown -R db2inst1 * (this recursively makes the file owner of all files in that directory db2inst1)


Launch the ./ from the terminal session.  This has a graphical interface so if you don’t have one configured you will need to create a response file and run ./db2Wizard -silent -nameofresponsefile insteaad



The same dbWizard is used to create, update and delete databases, it can also just generate the SQL commands to enable you to manually do these activities yourself.  Depending on the complexity of the enviornment and / or if the Wizard starts throwing errors, I often take the SQL commands and manually run them myself so I can monitor and adjust them if necessary.


The second screen asks for (and defaults to) the location of my DB2 install as well as the account that owns that DB instance.  I am running the Wizard using that account to ensure there are no security issues with permissions on the newly created databases.


I have chosen not to create either the Cognos or the Connections Content Manager databases at this time beacuse I will not yet be installing those features.  When I come to install them later I will re-run this Wizard (or the latest version of this Wizard) and create them then.


The final screen shows all the commands that the Wizard is about to run to create each of the databases. These commands point to .sql files that were extracted into the DBWizard directory and hold instructions on how to build each database for each application.  I can save those commands to a file and keep them for reference or use them manually later.

If you want to look at what they are doing, the sql files and routines are under the connections.sql directory in the extracted Wizard location.


The wizard will now run through creating every database and logging the activity to the /home/db2inst1/lcwizard/log/dbWizard directory with one log file for each sql routine.  I like to review the log file activity as it progresses in case there are any issues – the entire process can take anywhere from 30 minutues to 2hrs depending on the speed of your disk.


Once the Wizard has finished, try to connect to one of the newly created databases from a terminal window to confirm the database is there and db2inst1 has the right access to it.


For example to connect to the Activities database I use
db2 connect to opnact

Next step: configuring LDAP and populating the profiles database

Installing IHS

Connections uses IBM HTTP Server as a front end webserver, this is because WebSphere servers and their applications don’t listen on regular HTTP(S) ports 80/443 – each of the WebSphere servers I install will assign itself dedicated ports (see the earlier post on WebSphere installation).  If I install three WebSphere servers I will have three secure and three non secure ports that the applications may be listening on.  Blogs may be listening on a totally different port than Communities for instance.  As you can imagine that would make it very difficult to manage and route client requests.  By putting a webserver in front of the applications I can route all traffic through the standard HTTPS/443 port.

IBM HTTP Server is part of the WebSphere Supplemental installers.  I extracted those files and configured my Installation Manager (IM) repository to find them


IM now has references to two repositories, the WebSphere installers and the WAS Supplemental installers.


There are a lot of programs in the supplemental package but I want to find IBM HTTP Server so I use my filter at the top to help me find it.  Make sure the “show all versions” checkbox is ticked so earlier versions like fixpack 6 display.  I also want to find and install the Webserver Plugins for WebSphere as we’ll need these to integrate IHS with the installed Connections applications later.


Since I’ve chosen two products to install I need to set two directories to install into. The first directory is for the IHS server itself and this defaults to /opt/IBM/HTTPServer, you can change this if you want. I usually don’t unless there’s an issue wtih the /opt partition.


To verify and change the second directory for the web server plug-ins I have to click on that entry in the package group screen.  The plugins can be installed anywhere but I’ll need to remember where I put them for later !


On the next screen I can choose the features to install.  The installer will default to the correct architecture for the OS


The standard webserver port is 80 (this is for HTTP not HTTPS).


.. aaanndd IHS is installed.

I can’t run it yet and my work isn’t done.  I still have to

  1. configure the admin interface
  2. add the webserver to our ISC
  3. configure the http server
  4. create a SSL keyfile and enable SSL

I’m going to go ahead and complete steps 1 and 2 now and come back to steps 3 and 4 after I have Connections installed.

Configure The Admin Interface

To set up the admin interface I need to have an account in Linux I can use.

adduser ihsadmin

I need to set the admin password for IHS. From the directory /opt/IBM/HTTPServer/bin I type

./htpasswd -c /opt/IBM/HTTPServer/conf/admin.passwd ihsadmin

and I will be prompted to set the admin password for ihsadmin

The command to start the admin interface is ./adminctl start but that won’t work until I complete the admin.conf configuration in the /opt/IBM/HTTPServer/conf directory

vi admin.conf

search for @ symbols that you will need to replace with ports, for example



The default admin port is 8008.  To verify if I have the configuration file correct I type

/opt/IBM/HTTPServer/bin/adminctl configtest

To start the admin server I use

/opt/IBM/HTTPServer/bin/adminctl start

To verify it has started type netstat -tulvn |grep :8008 and I should see the server listening on that port.

Adding The WebServer To ISC

Log into the ISC at https:<hostname>:9043/ibm/console


Choose “Nodes” under “System administration”.  Currently I have two nodes for the Deployment Manager and the Application server profiles I already created on the previous post where I installed WebSphere. I want to “Add Node” to add a new node.


Since I’m not adding a WebSphere server but an IHS web server there’s going to be no way for WebSphere’s Deployment Manager to actually manage it so I need to add this as an “unmanaged node”.  Only WebSphere servers can be added as “managed nodes”


My unmanaged node properties are the

  • Name – which is only used within the ISC itself and never presented to the users so can be anything unique
  • Host Name – the host where the IHS is installed.  This hostname must be resolvable from the Dmgr.  In this case I installed the IHS on the same server as the Dmgr so they share a hostname
  • Platform


Once completed my new unmanaged node is shown in the list of nodes but as you can see the status column is empty because that column refers to WebSphere sync status and this node is not for a WebSphere server.


Now I’m ready to add my new IHS server on the new unmanaged node to ISC.  Go to Servers – Server Types – Web Servers and select “New” to create a new Webserver instance


Now I can choose the unmanaged node I just created and name the server (choose webserver1 as the name if you can since WebSphere often “assumes” that) and then choose the “Type” (IBM HTTP Server always)


On the next screen I need to tell WebSphere how to connect to the admin interface of IHS.  I just set that up using account ihsadmin and port 8008.  If the admin service isn’t started or the ihsadmin account isn’t set up correctly WebSphere won’t be able to “talk” to IHS at all..


Since I chose IBM HTTP Server on the earlier screen WebSphere knows there’s only one template I can use.


My install is now complete and my IHS web server is now part of my WebSphere cell.


The WebSphere Integrated Solutions Console

Once WebSphere is installed I want to do two things, login to the admin interface and backup the environment so I have a “start point”

WebSphere’s admin interface is called the Integrated Solutions Console and is the same regardless of what product you are working with.

To login to the ISC

:9060 which is the non secure port will redirect to 9043


Login here using the credentials created during the original WebSphere install, these credentials are created and stored in the WebSphere default repository during install (and will always be your “backdoor” into the server).


Once logged in I know that WebSphere is correctly installed and running and I can logout and move onto my next task and come back to here later.


At this point, and before I start further configuration I like to take a backup of the WebSphere environment.  This is simple to do using the backupconfig command.

From the Dmgr profile location
/opt/IBM/WebSphere/AppServer/profiles/Dmgr01/bin type
./ /opt/Backups/ -nostop

The location and filename of the backup can be anything.

The -nostop option tells WebSphere not to stop its services before it does a backup.  By default it will stop the Dmgr to avoid anyone making any updates whilst it is backing up but since I know I am the only one working on here I’m happy to take a “live” backup instead.



Installing WebSphere

We can’t install Connections until both WebSphere and the DB2 (or Oracle or SQL) databases are in place so let’s start with WebSphere.  On previous posts we looked at installing Installation Manager (IM) and setting up a software repository to point to the WebSphere installers


My first check is to decide what version and fixpack I need and I do that by checking the System Requirements. These can change any time so I make a point to check them just before doing an install.   According to the current requirements Connections 5.5 needs a minimum of WebSphere Application Server Network Deployment 8.5.5 Fixpack 6. Since the requirement is a minimum I could install the most recent Fixpack 8 but for my purposes I’m sticking with Fixpack 6 today.


Even though at this point I’m not installing IHS I can see on the system requirements that it only supports 8.5.5 fixpack 6 of IHS.  This is something I need to remember later.


When  launching IM and clicking “Install” I am presented with serveral products with their latest versions and options.  I have to click the checkbox “Show All Versions” to choose an earlier fixpack such as Fixpack 6


There are now hundreds of products and versions to choose from so to make it easier I type “network deployment” in the search bar at the top to filter the product choices (and so I don’t accidentally choose the wrong one). I then select as the version I want to install. I haven’t downloaded, only 8.5.5 so I’m relying on IM to get the fixpack from the Passport Advantage site.


There are already several fixes available for but, having checked the System Requirements to ensure there are no specifics fixes I need, I let IM choose the recommended ones only.


I now identify two locations, The first is the location for the shared resources directory used by IM.  This is the location for IM to store the installers, fixes and rollback files, not the location of the WebSphere program itself.


Now I can tell IM where to install WebSphere.  The default “WebSphere” directory will always be /IBM/WebSphere/AppServer and I would only change this if I was installing multiple WebSphere versions on the same machine (unlikely).  On Linux this defaults to /opt/IBM/WebSphere/AppServer and on Windows I try to put it on a separate drive partition from the OS such as D:\IBM\WebSphere\AppServer.  This location is your “WebSphere program directory” that is referred to in documentation.


These are the standard features I install for Connections.  At this point the total install size should be about 2.5GB across both directories.


Our confirmation screen just before the install starts shows what products will be installed into which locations.  Read the target location details at the top of this screen to confirm you have entered them correctly.


Our WebSphere install is now complete (love that big green tick) but now I need to create profiles to set up the servers.  Selecting OK here will launch the profile management GUI tool but this can also be launched later off the GUI menu or you can create profiles by using the /opt/IBM/WebSphere/AppServer/bin/ command


Since this is the first server in my deployment I need to create a new cell which will include both a deployment manager and an application server.  I often like to create the deployment manager standalone on its own machine if I’m building a HA cluster but for our purposes in Connections101 I’m just locating both the deployment manager and my first application server together.  These are the first servers on “bogart” as shown below.  If I were creating an additional Application Sever on “marlowe” then I would be creating an Application Server profile only at this point.




Often during profile creation I would just choose the “Typical” option which is a far simpler series of choices with some default settings.  I’m choosing Advanced profile creation here to show you all the settings available to you.  The difference between “Typical” and “Advanced” is purely the ability to custom set options like ports, certificates and passwords – all of which can also be changed later after the profile already exists.


I always want to deploy the administrative console if I’m deploying a new cell because that’s how I’m going to manage all the servers.  If I add an existing Application server into an existing cell by federating it, its administrative console will be removed so it can be managed only by the deployment manager.

I often choose not to deploy the default applications for security reasons because it just gives me more things to have to lock down.  It can be useful for WAS troubleshooting but I rarely use it.


The first deployment manager on a node is usually put in a profile Dmgr01, similarly the first application server is put in the profile AppSrv01.  You can change both of these to something more meaningful if you want.  I never usually do. One thing to note in WebSphere world is to stay away from anything that could be a special character for path names or passwords.  As I mentioned on the previous post, all WAS configuration is stored in XML files and often encrypted so decrypting those special characters can fail and cause WebSphere itself to stop working.

Specific special characters to avoid for anything WebSphere related include


but I like to avoid anything that could be problematic including accented characters.  Longer passwords can be just as effective.


The hostname for the server is picked up from the server’s local settings or host file. You need to make sure it’s a fully qualified name and not just “bogart”.  It also needs to be fully resolvable with an IPV4 address from itself and any other server.  The default deployment manager and application node names will be “servername”CellManager01 and “servername”Node01.  This is important because the servers will be installed with these names and a lot of nested directories will use the names.  IBM recommend your server name is no longer than 8 characters for this reason (avoiding creating very very long filepaths) but if your servername is long you can change the node names here to something shorter..

The cell name and node names cannot be changed post install and will be used to reference the servers internally.  It will always be possible to add another resolvable fully qualified hostname like “” as an alias later but you can never fully remove these names.


When WebSphere is installed new SSL certificates are created using an IBM internal Certificate Authority and the servers’ hostnames and roles.  These certificates are usually replaced by me post install with valid SSL certificates from a public or internal provider.  If however you have a wildcard certificate for your organisation already you could add it during the install and avoid having to replace the internal IBM certificate later.  You would still need to add the trusted root though and I’m a control freak so I like to let IBM create its certificates then manually go in and replace them later.


The default certificates that are created (assuming you didn’t choose to replace them on the previous screen) will have keystore passwords of WebAS.  This is well known as IBM’s  default keystore password and for that reason WebSphere will see it as a security issue if you don’t change the password for keystores on a running server.

Again I prefer to let it install and then change it later but you can change it here during the install process.


There are three pages of ports that WebSphere will use for different services.  Unless there’s a specific reason you can’t use one of the default ports I suggest leaving these as they are (in a “Typical” install you never see these screens).  If you must change them I would suggest only incrementing them by “1” until you get to a port number you are happy with.


On Linux and Windows you are presented with the option to add the Deployment Manager to run as a service when the server starts.  You don’t get that option for either the nodeagent or any of the application servers which you will have to add manually after all the install work is complete.


Finally I get the option to create an IHS server definition.  I will need to do this at some point since we are going to put IHS in front of our Connections servers but I haven’t installed IHS yet and so I’m going to leave this for later.

That’s our WebSphere install complete.  It should take anywhere from 15 mins to an hour depending on your disk write speed.


Once installed, if you have a GUI, you will see IBM Websphere on the Application menu. From here you can find the profiles that were created as well as create new ones and start or stop individual servers.


The above screenshot shows me checking the install completed successfully.

First I do an “ls” to see there are both profiles there.  The system shows me Dmgr01 (the deployment manager profile) and AppSrv01 (the application server profile).  That’s good.

Now I navigate to /opt/IBM/WebSphere/AppServer/Dmgr01/bin and run ./ (note case sensitivity).  This should start the deployment manager from within its own profile.

Once it has started I want to check it’s listening and I know the deployment manager listens on port 9043 for the Integrated Solutions Console so I type

netstat -tulvn |grep :9043 to find if that service is listening.

We now have WebSphere installed.  If you are setting up multiple servers on different boxes you would now need to go and repeat the install but this time choosing to create only an Application Server profile on each of those boxes.  Remember to keep your WAS version on every server in your cell aligned at

A WebSphere Primer..

Before you start installing WebSphere you should really understand some core concepts behind its architecture and options. This is going to make it easier to decide where and how to build servers.

Connections uses WebSphere 8.5.5 Network Deployment.  When you go to install your Connections applications you’re going to need at least one instance of WAS to install onto, however a single WAS install may be running multiple independent servers each running different applications. Our Connections environment could therefore be a single host machine with multiple WebSphere servers or multiple host machines each with single WebSphere servers.

Every WAS server must be installed into what is called a Node  and similarly each Node must exist inside what is called a Cell. For Connections101 I am building two “nodes” on two physical hosts with each running multiple WAS instances hosting different applications.

Each Cell has one process called a Deployment Manager whose job it is to manage the configuration settings and changes for all servers in its cell.

Each server then also has another parent process called the Node Agent. Its job is to talk to the Deployment Manager and receive the latest sync information (XML files) for the server it is managing. It’s also responsible for starting and stopping the server.  You cannot start any WAS server unless its corresponding node agent is also running.  You can’t stop any WAS server unless its corresponding node agent is also running.

Here’s an example diagram of how the architecture for Connections101 might be designed. In this design I have built a deployment manager and two separate nodes which are full clusters of each other.


In WebSphere terms only individual servers need to be clustered, not entire nodes so I could easily just cluster the busiest components in my environment such as Cluster2 which contains search , homepage and profiles.  This is why it’s important to think about WebSphere design as well as the locations of the applications and which ones you may want to cluster, before starting the install.

The Deployment Manager directory holds XML files for every server.  It copies those files into the individual server directories when you Sync the servers.   You do all your configuration by logging into the administrative interface for the deployment manager (the Integrated Solutiions Console) and from there any changes push out to the managed servers.

Based on this there are important things to bear in mind

  1. Each server will have only one node agent
  2. Each node agent can manage multiple servers
  3. So from this we know that every single WAS cell will have, at minimum, one deployment manager, one node agent and the application server itself.
  4. Changes made to server configuration on the deployment manager will need to sync down to the nodes before the server itself will pick them up
  5. Syncing basically results in copies of the XML files for a server being sent from the Deployment Manager’s directory to the Server’s directory
  6. This means there will be at least 2 copies of every configuration file for a server, one owned by the Deployment Manager and one by the Server
  7. If you try and change a server setting in the Deployment Manager without syncing, the server won’t take the change
  8. If you try and change a server setting directly on the server without updating the Deployment Manager, it will be overwritten
  9. If you install the deployment manager and server on the same machine, it still has to sync to push out changes.  From a file system perspective, there are multiple copies of the same files.  If the servers are on different boxes the files will be too,  WAS is designed to work as if all servers are physically different and isolated from each other regardless of hardware infrastructure.  Sometimes you will be asked to locate a certain file, and you may find more than one.  It’s important to learn the locations of files and their purposes (i.e are you looking at the deployment manager’s copy of the file, or the servers’).  We will get to file locations in a later post.
  10. There are a lot of restarting servers required when working with WebSphere since server changes don’t just happen on the fly, they require a sync and a server restart to take effect as the XML files can be read as the server starts up.

Working With Installation Manager

Now we have Installation Manager (IM) installed it’s going to be our primary go to place for installing everything else so let’s have a look at how it works.


If you use a GUI you should see IBM Installation Manager added to the programs menu and you can run it from there, but you can also run it from the command line.  Navigate to the install directory /opt/IBM/Installation Manager/eclipse (beware case sensitivity) and run ./IBMIM.  I am using sudo to run it with the appropriate (root) rights because I’m not logged in as a root user.




The Installation Manager main menu gives us several options for working with software

Install:  adding new software such as WebSphere or Connections itself

Update: applying fixes and updates to already installed software

Modify:  changing the options for already installed software such as adding or removing features

Roll back: taking software back to an earlier release level for example rolling back WebSphere from an applied fix or IF

Uninstall: there’s no way back from this, uninstall the software and it’s gone completely


The file menu on the IM allows us to view what software , versions and locations exist.  We also use this menu to set up file repositories where IM can find installers.  We’ll look at that on our next blog entry “Installing WebSphere”.

As you can see, running our installs and updates through IM gives us much more flexibility and control over versions and upgrades.  Since IM maintains records of all installed software, location, patches and features it can’t be uninstalled whilst the owned software is still in place.  And by “can’t” I mean “won’t”.  If you try and uninstall IM it will simply refuse to uninstall itself until you have used its “uninstall” option to remove its owned software.

Installation Manager takes only a few minutes to install but think carefully about who installs it, who has rights to run it, and most importantly its install location

Setting Up Repositories

For IM to install software you must first tell it where to find the software you want to install.  Let’s take WebSphere as an example.

The WebSphere New Deployment installers come in 3 compressed files.  We extract all of those to the same directory using the syntax

unzip filename (eg -d {directoryname]

if you don’t use -d as a parameter the file will unzip into the directory you are currently running the command in.



Unzipped you should have 3 folders disk1, disk2 and disk3 and a repository.config file.  The repository.config is what IM looks for to determine how to install the software.


You want to add repositories for any software you plan to install by choosing File – Preferences from the IM menu and then “Add Repository”


Browse to the location of the extracted installers and find the repository.config file then select it.




One of the advantages of IM is that it can store previous versions of the software to enable you to rollback at any point, however the files needed for rollback need to stored on the file system and take up space.  You can go into this section of IM and choose to remove the saved rollback files at any point once you know you won’t need to rollback. If you do remove the files it should still be possible to rollback but you will need to be able to supply the original versions of the installers you want to rollback to.


When updating or installing software you can optionally be prompted for credentials to Passport Advantage in order for IM to find the files online.  This tells IM to find any updates available on Passport Advantage. It saves you the trouble of finding and downloading WAS fixes and patches but does require that the server has access to the internet.


Now when you go to Install or Update software IM will prompt you to login to Passport Advantage and optionally save the credentials so it won’t ask again.

Now we’re ready to install WebSphere.