The IBM Docs Dilemma

IBM Docs is a really nice add on to IBM Connections, what’s more it’s not particularly hard to install.  It does have one requirement, a big one, a show stopping one, a requirement that prevented my customer build from working for about four weeks until IBM and I came up with an agreement for how it could work.  Hopefully this will help you fast forward through that four weeks yourself ..

IBM Docs Infrastructure - The Simple Version

IBM Docs has four component WebSphere servers with applications stored on each

The servers also need access to three data shares; the standard Connections share, a new share for IBM Docs data and a new share for IBM Docs Viewer.  I created the two new shared on the Linux server that currently hosted the CIFS Connections share and installed Samba to enable a Windows server to access them.

I had one problem where it consistently failed during install if I didn’t use capital letters for the mapped drives.  It didn’t refuse to accept lower case letters, it just failed the install.  If your install fails make sure you aren’t using lower case letters.


The key requirement for IBM Docs to actually work is that

1. The shares must use mapped drive letters and those drives letters must exist prior to the IBM Docs elements being started

2. The IBM recommendation for achieving this is to create a batch file on the IBM Docs OS (which must be partially if not wholly Windows) to do the drive mapping and have that load in Windows task scheduler on startup.

3. The WAS servers must then be run as services not using a system account but using a named Windows account that matches the one assigned to run the batch file in task scheduler

This solution had two problems, I hated it, and it didn’t work.

I hated this idea because my customer doesn’t run AD at all and their share was a samba share on a Linux box using CIFS.  That means there is no account that can be used to start the services that can also be used to map the drives. There is no easy way to have Windows pass credentials to mount the shares without storing both the name and password that samba recognises in the batch file - like this

net use m: \\hubshared\ibmdocsdata sambapassword /user:sambaaccount
net use n: \\hubshared\ibmdocsview sambapassword /user:sambaaccount
net use l: \\hubshared\conntestshare sambapassword /user:sambaaccount

Unfortunately after several weeks of different ideas from L3 support we admitted defeat to allow me to move on with the install.  I have minimised risk by ensuring the account isn’t a linux account and only has access to the samba shares.

The second part of the solution is the assumption that if you map the drives through task scheduler owned by a Windows user and that same Windows user starts the WAS services - the WAS services will be able to see the mapped drives.  To everyone’s disappointment that absolutely didn’t work because Microsoft kindly mapped the drives from the batch file in a different session to the one where it started the WAS services.  The servers couldn’t see the mapped drives.

So the install was simple but getting everything running securely and without the customer having to manually do anything held us up for weeks.  In the end I opted for a solution where I created a batch file to both map the drives and then start the WAS servers in a scheduled startup script.  That worked beautifully and this is what it looks like

net use m: \\hubshared\ibmdocsdata sambapassword /user:sambaaccount
net use n: \\hubshared\ibmdocsview sambapassword /user:sambaaccount
net use l: \\hubshared\conntestshare sambapassword /user:sambaaccount

Call “c:\IBM\WebSphere\AppServer\profiles\IBMDocs\bin\startnode”
Call “c:\IBM\WebSphere\AppServer\profiles\IBMConversion\bin\startnode”
Call “c:\IBM\WebSphere\AppServer\profiles\IBMViewer\bin\startnode”
Call “c:\IBM\WebSphere\AppServer\profiles\IBMDocsProxy\bin\startnode”

As you can see I only start the nodeagents. The servers themselves and the applications on them are bootstrapped to the start of those. To do that modify the server’s monitoring policy which is found under Java and Process Management for each server

Then set the “Node Restart State” to “RUNNING”

bootstrap nodeagents

2 thoughts on “The IBM Docs Dilemma

  1. Thank you for testing and improving IBM’s software and moving it toward “production level”.

  2. Development Team Manager: This is the release authorization meeting for IBM Docs. Just a few last things to check before we ship. Integration team: Did you find a way to connect Docs to data on other servers?

    Charlie Coder: Well, it was kind of a surprise when you told us at the last meeting that hard-coding everything to access C:\MyTestDocs wouldn’t pass review.

    Alice spent a couple of days reading Redbooks to look at various standards and best practices, like you suggested. Apparently Windows has been using a standard called the Universal Naming Convention for about 25 years, but Bob is convinced that Microsoft stole UNC from OS/2, so we decided to count that out.

    Alice mentioned a dozen other ways to share files between machines over an IP network, but frankly we were in a bit of a rush. In the end Tony from tech support helped us find a batch file on SourceForge that gives us a way to link to files on another server just by typing a letter with two dots after it, so I think we’re good.

    Alice: He means a colon.

    DTM: Ah, OK, that could work. But people use colons in all sorts of places. Can you make sure the software only accepts capital letters as drive mappings?

    Alice: Sure.

    DTM: If that’s it, we can ship.

    Charlie Coder: We did hit one other issue. The testing was fine when Alice logged in, ran the batch file and then ran our software, but it bombed when we tried to load it automatically. Eventually, we tracked down another batch file that does the drive mappings during startup. It’s really cool. You can type in the username and password and stuff.

    DTM: Wait a sec. I’m sure they said something about hard-coding passwords on that SANS course I went to in Las Vegas…

    Steve Security Reviewer: Nah. Should be fine. We can’t fuss over every “theoretical vulnerability”.

    DTM: Alright, it’s a wrap.

Comments are closed.