Factotum: Documentation Handyman

We've updated the Single Host Deployment Example for Communications Suite 7. This example describes how to install the entire Sun Java Communications Suite 7 software "stack" on one computer for a functioning deployment. This document is intended for any evaluator, system administrator, or installation technician who wants to install and evaluate the services delivered by these components.

This example describes how to install and configure the following components:

• Sun Java System Messaging Server 7 Update 3
• Sun Java System Calendar Server 6.3
• Sun Java System Calendar Server 7
  
• Sun Java System Instant Messaging 8 Update 2
• Sun Java System Directory Server 6.3.1
• GlassFish Enterprise Server 2.1 Patch 2 with HADB support
• Delegated Administrator 7
• Sun Convergence 1 Update 3
• Sun Java Indexing and Search Service 1

Give the example a whirl.

Just a heads up, in case you get the following messaging when trying to access a page on the Communications Suite wiki:

Controlled Access Area

You cannot view this page

Page level restrictions have been applied that limit access to this page.

Though this message sounds like we are control freaks, it's just to alert you the page is not publicly available. In general, we want our Wiki documentation to be as open and available as possible. But in some cases, where we are working on updating or improving documentation, we will restrict access until that work is done.

As always, if any readers are looking for information that you cannot find, or if you have any Comms documentation-related questions, feel free to drop us a line and we'll do our best to help you out.

This is cool:

New on docs.sun.com: Recommended Offers

Interesting write-up by one of our TSC engineers, who just completed a Comms 7 Installation. Focus of the writeup is on our new product, Calendar Server 7.

Note: The single host deployment example (for SPARC), referenced in the above blog entry, is not yet publicly available. There is, however, this document for Red Hat Linux, that is available.

I wanted to address an issue that comes up from time to time with documentation for anything: how do you find what you are looking for? And do it quickly? The wikis.sun.com model provides a number of ways to get to information:

• You can browse by page, label, and recent updates.
• You can use the global search, for all wiki spaces, or the site-specific search, which we provide on every page of our Communications Suite wiki sites.
• Yes, you can still google for information, but my recommendation is to use the wikis.sun.com specific ways of getting to the information. Indeed, I find the wikis.sun.com search to be quite fast and effective in finding what I'm looking for.

I put together a summary of the various ways to find the information you are seeking. Give it a read: Finding What You Are Looking For

 I do realize that as a writer of this information, I'm at an advantage, knowing where everything is. It is my job to make it easy for the community to also know where everything is. So leave a comment if you have suggestions for how to improve our wiki docs model, especially if you are having difficulty locating particular information.

Hat Tip David L.

I attended a webinar today on the Communications Suite 7 installer. Passing along some notes.

Installation Is a Two-Step Process

Remember that in the Comms world, "installation" consists of installing the software bits and then configuring them. The Communications Suite installer only lays down the software bits. It does not configure them. Each individual Communications Suite component product has its own configurator that you then run. We wanted to separate these two steps for robustness, as configuration is where the majority of the work actually occurs in a Comms installation.

32-Bit Versus 64-Bit

In Communications Suite 7 and going forward, Messaging Server on Solaris (SPARC and x86) is only available in 64-bit. Messaging Server is only in 32-bit for Red Hat Linux (no 64-bit support yet, this is forthcoming, but no timeframe). Also, Messaging Server has dropped support for Solaris OS 9, Solaris OS 10 32-bit, and Red Hat Linux 3.

Installation for Power Users

Power users: You can use --OSversionOverride switch to install some Communications Suite component products on Solaris OS 9 or other dropped platforms. See http://wikis.sun.com/display/CommSuite7/commpkg+-+General+Syntax+and+Commands for more information. Note that you will only see the products that are runable on that OS platform. For example, you wouldn't see Indexing and Search Service 1 nor Calendar Server 7 on Red Hat Linux 4 32-bit, because those two new component products are not officially supported on that platform. On Solaris OS 9 SPARC, the Communications Suite installer would not show you you Messaging Server 7 Update 3. And so on.

Where's Communications Express 6.3?

Going forward, Communications Express is deprecated in favor of Convergence, so you will not see it in the Communications Suite 7 installer. Communications Express is still supported. If you are looking to install Communications Express now, I guess you'd need to get the Communications Suite 6 Update 2 bits.

New Component Products

Brand new in this release: Calendar Server 7 (our CalDAV product), and Indexing and Search Service 1 (gives you the ability to index and then search your email attachments). Note that you'll continue to see Calendar Server 6.3 in the Communications Suite 7 installer, as Calendar Server 7 is not yet supported by Convergence. Also of interest. You can have a coexistent deployment of Calendar Server 7 and Calendar  6.3. See http://wikis.sun.com/display/CommSuite/Creating+a+Calendar+Server+6+and+Calendar+Server+7+Coexistent+Deployment for more information.

Calendar Server 7 uses MySQL as its backend, and the Communications Suite installer treats it as a shared component. The CI checks if there is an existing MySQL version but will not upgrade or uninstall MySQL. If that's your case, you'll need to refer to the MySQL docs on how to upgrade or uninstall.

Installing Just a Calendar Server 7 Back End

It's a bit tricky, but doable: See http://wikis.sun.com/display/CommSuite7/Communications+Suite+7+Installation+Scenario+-+Calendar+Server+7 for more information. Basically, you preface the Calendar Server 7 component with a tilde (~) to just install its dependent component products, which in this case is just MySQL.

This very cool lip dub:

Led me to What does this have to do with Technical Communication?:

Everything. We need to incorporate more audiovisual media into instructional documentation. Users love this type of content. Voice on video doesn’t need to be recorded in a studio. Our screen demos don’t need to be storyboarded to death, requiring 75 hours to produce a two minute video. As long as the content is there, on target, in sync with user needs, it will fulfill the user’s desire. As tech writers, we should be creating more video — amateur is acceptable. Personal voice is desirable. Bloopers give human appeal. If we can have fun doing it [truly], it will engage our audience even more.

So, any suggestions for the first tune for Communications Suite?

Using Messaging Server 64-bit Edition

Beginning with the release of Messaging Server 6.3, on Solaris OS, you have had the choice to install the 64-bit version of Messaging Server. The Communications Suite Product team now recommends that you install 64-bit Edition for new installations on Solaris OS, and upgrade your existing Solaris OS 32-bit Messaging Server deployments to the 64-bit version as time permits. You should no longer be installing the 32-bit version of Messaging Server on Solaris OS.

Reasons to use or switch to Messaging Server 64-bit Edition include:

• Solves the problems with large store.idx files (described in Large store.idx Files Issue).
• Ability to run a reasonable number of imapd processes instead of running dozens of them.
• Better LDAP cache utilization (see also LDAP Cache Tuning in Messaging Server).

  Read the complete writeup.

Just published: a white paper on designing tiered storage with Messaging Server, with the eye on cutting storage costs. Abstract:

Service providers face unrelenting pressure to increase storage for user mailboxes. This paper explains how using production products, such as Sun Communications Suite software, the Solaris ZFS file system, and a Sun Storage array, can cut storage costs by half, while performance (measured by messages per second) can be increased by more than 50 percent in environments with millions of users. Extensive load testing has shown that this single-rack solution provides a cost-effective message store for two million users. It is easily replicated and highly modular.

It probably goes without saying that these days, with the multitude of applications that users have to access, configuring deployments for Single Sign-On (SSO) is the way to go. By using SSO, a user is able to log in just once and gains access to all systems without being prompted to log in again at each of them. Of course, Sun Convergence provides three type of Single Sign-On (SSO) mechanisms out-of-the-box, but I'm not sure how widely known this is:

1. SSO with Access Manager
2. SSO with OpenSSO (starting with Communications Suite 6 Update 2)
3. Trusted Circle SSO (aka Messaging SSO)

None of the above quite what you need? Convergence provides a plug-in mechanism for you to develop a customized SSO solution.

New and old (updated) Communications Suite docs of interest:

• Best Practices for Messaging Server and ZFS
• Installing Communications Suite 6 Update 2 on a Single Host

Someone was asking me today, "How do you find things on the Comms Doc Wiki?" A valid question, to be sure. I thought about it for a bit, and asked back, "What are you looking for." "Everything, the whole enchilada" came the reply. "I want to browse everything."

Fortunately, wikis.sun.com (by way of the Confluence wiki engine) has an easy way to do this. For the Comms Suite Wiki, we made use of a macro to generate an index of all content, organized A-Z:

CommSuite Doc Index, aka The Whole Enchilada

Much of the deployment experience for Comms Suite involves running individual product configurator tools. That is, when deploying Comms, you do the two-step dance of installing the bits and THEN configuring them.

If you're new to the product, or coming from the world where the installer DOES everything for you, well, that's just not so in Comms. For better or worse, we split up the deployment experience into laying down the product software and then configuring that software.

I'm at the point in the Single Host Deployment Example where I have installed the Comms Suite bits and am now configuring the component products.

You run the component configurators in the following order:

• comm_dssetup.pl to prepare the LDAP directory with Comms schema
• config-commda for Delegated Administrator
  BTW, here's a shot of the DA Console (a feel good that yes, the process is working as documented)
  
• configure for Messaging Server
• csconfigurator.sh for Calendar Server

After running csconfigurator.sh, you need to hand-edit the Calendar Server ics.conf file and a few other Calendar Server files, then reload the service schemas. A really useful error then appeared when trying to stop/restart the Calendar Server:

# ./stop-cal
[30/Apr/2008:19:32:21 -0700] elwood2 [11006]: General Error: func=_configdrv_file_readoption; error=unexpected character after value; data="
ERROR: Could not initialize config system

Okay, after so much smooth sailing, I've got the func FUNK.

I'm thinking, what the heck, and how am I even supposed to begin troubleshooting this with such a helpful error message. (Perhaps to seasoned Calendar Server admins, it's obvious.)

As I had just edited the Calendar Server files, I figured that was a good place to start. Careful examination revealed that I had left off an ending double quote (") on a value in the ics.conf file. Which points out to a real issue with deploying Comms: With all the typing and hand-editing of files involved, human error is a very real problem. So far, that has to be my major complaint with this deployment methodology.

Hmmm, would have been interesting, in hind sight, to have used this Error Rate Calculator, telling you what your typing error rate is - that is, how often you have to hit that Backspace key to correct an entry.

Up Next: On to Instant Messaging.

If you haven't been paying attention to the Comms Wiki of late, then you've missed some exciting Community-sponsored contributions. The following wiki pages were recently authored by Jesse at the University of Wisconsin:

• Filtering out Backscatter and Outscatter
• How Can I Block Mail From Bogus Local Addresses?
• How Can I Require and Restrict HELO or EHLO?
• How Can I Restrict the Characters Used in Envelope From Addresses?

Comments are another area where we are getting great feedback. Contributor Nate has been especially active. Just this morning, he left this tip in the Comments section on the Connector for Outlook FAQ page.

A big thanks to Jesse and Nate, and the rest of the contributors out there. And while I'm at it, a public service reminder to the Comms Community: the Comms Wiki is there for your use. Have a tip or article you'd like to share? Got an interesting configuration you'd like to pass along? Feel free to log in and contribute. Don't yet have a Sun Online Account, with which to log in? Get one here.

One more tip: To keep track of the latest additions and changes to the Comms Wiki, use the Recently Updated Pages link.

As I mentioned previously, I'm trying to eat my own dog food

by using the Comms 6 Single Host Deployment doc. Now, I'm not what you would call a UNIX sysadmin, nor a Comms sysadmin by any stretch of the imagination. Let's just say I'm a jack of all trades, master of none. I know enough where to look for answers and when to ask for help. Guess what I'm saying is that for being somewhat of a novice, I should be able to complete this exercise.

Right now, for the second time, I'm re-uninstalling the Identity Suite components needed for a Comms deployment. That would be Directory Server, Access Manager, and Web Server. Why you ask? Because I can't follow my own instructions. (Big grin.)

Lesson One: Don't cut corners.
When I started this exercise, the first step was to install Application Server 9.1 Update 1. That requires Java 1.5. My system, running Solaris OS 9, only had 1.4. At first I thought I could just download and install the JRE; a smaller download than the entire JDK. Okay, I cut a corner. I installed the JRE (and had to figure out where my PATH was still picking up the older JRE and preventing me from launching the Application Server installer) and ran the Application Server installer. Well, one of the options was the location of the Java 2 SDK 5.0 or higher. Urg. I did need the entire JDK. So I had to exit the Application Server 9.1 Update 1 install, hunt down the new JDK, then download it, then install it. More lost time.

Lesson Two: Read the documentation. Closely.
In my case, I mistakely choose to install all the Identity Suite components (as well as all the multi-national languages, which aren't necessary for my POC, and take up lots more time to install as well). This had the unfortunate effect of installing a second copy of Application Server, version 8.2, which I *think* overlayed my initial installation of Application Server 9.1 Update 1, needed for Convergence (Kendo). If I had followed the doc, I would have skipped installing this second conflicting version. (And as I'm writing, the IS uninstall just finished. It is not a quick process on a slow machine, trust me.)

BTW, finding out how to uninstall the Identity Suite components wasn't an easy Google. I finally found out on a Sun Forum how to do it:
/var/sadm/prod/SUNWident-entsys5u1/uninstall

Much of the time during this exercise, I find myself asking: Is this typical of the customer experience? If so, once again, I'm feeling your pain.

I'm on to reinstalling the Identity Suite components at this point. More later.

BTW, some things I've had to learn along the way:

• Using ssh
• Using scp to copy files to a remote secure host
• Using ssh -X to remote diplay an application
• Finding a Solaris copy of Mozilla (and installing it)
• All the service stop/start commands