Personal Blog of Thomas Hampel - Creative Mythbusting in Development and Collaboration

Query results for : Best Practice

Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option- 16 February 2017 - (0) Comments

Thomas Hampel
 16 February 2017

This is the fourth post our of a series of blog posts describing how to move from password based to seamless authentication.
In Level 3 - SPNEGO I have explained how to configure SPNEGO authentication for providing seamless authentication. A drawback of this method was that users can only log in with the current OS user, switching to a different context was not possible. In this level I am providing a solution to switch the user without switching the OS user.

Level 3 - SPNEGO with fallback option

The SPNEGO configuration from Level 3 - SPNEGO alone will automatically log in the user with his OS credentials. There are cases where the machine is used by multiple users which -for whatever reason- share the same OS user, or when the OS user is not member of the ActiveDirectory, or the current OS user does'nt have the required Notes name listed in LDAP..... However, think of kiosk machines, etc. where the OS user has little to no access rights in corporate applications. So we would like to provide them with an option to authenticate with credentials other than the OS user.

Pros and Cons

+ Seamless authentication for browser clients on Windows
+ Ability to switch user without logging off/on from OS
- It's Windows only
- Does'nt work for Traveler and Sametime

Prerequisites
  • You have successfully completed Level 3 - SPNEGO
  • You have (at least) two IP addresses on your Domino server or have at least two Domino servers in your environment

Idea and Concept

Main idea is to handle to handle login and not authenticated errors and redirect user sessions to a fallback authentication page hosted on a Domino server that does not use SPNEGO.
This brief workflow diagram describes how its done:
Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option
The first part of the authentication flow is shown in the "Conceptual Overview" graphic in this article where the sequence is as follows
1
The user is trying to access a protected resource (e.g. “serviceurl.company.com”) by using a web browser. The browser is establishing an SSL session on Port 443 and sends HTTP GET / Post request.
2
Domino returns HTTP401 WWW-Authenticate:Negotiate
3
The Client sends HTTP GET / Post request via SSL with an authorization SPNEGO Token
4
Domino verifies if the token format received from the Browser is SPNEGO
5
Domino validates the ticket against Kerberos Domain Controller to authenticate the user
6
With the Kerberos name is returned, Domino will make an outbound call in order to find the Domino distinguished name (e.g. attribute “mailNickname” ) within ActiveDirectory by looking up the Kerberos name. For successful authentication the result is a Notes User name which will be used for this session, continue with 7a. For unsuccessful authentication the result is HTTP Not Authorized, continue with 7b
7a
Domino returns an LTPAToken to the client and proceeds to the requested resource by verifying access rights in the ACL. At this point the user is authenticated and the process will end here.
7b
Domino returns HTTP403 Not Authorized, The user will be redirected to a custom logon page for non-SPNEGO users, continue with step #9 in the next chapter.



For a concept with a fallback option you'll need at least two internet sites or two Domino servers with a different configuration for each.
Users trying to access a protected resource (e.g. application) that they are not authorized to use, will get a custom error page returned with a javascript that will redirect to a non-SPNEGO site.
This graphic shows two Domino servers where one is using internet sites and one is using an old style web configuration - both use a web SSO configuration document called "LtpaToken".
Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option
8
The user was trying to access a protected resource (e.g. “authenticationURL.company.com”) by using a web browser. The browser is establishing an SSL session on Port 443 and sends HTTP GET / Post request.

Internally Domino is returning HTTP 403 – Not Authorized, which causes Domino to check if a custom error handler has been configured for the requested URL.

9
Domino returns the custom error page configured for this URL. If no custom error handler has been configured only the browser default error message for HTTP403 Not Authorized will be displayed.
10
The browser will render the custom error page, which contains a JavaScript to redirect the client to a fallback authentication page.



Depending on the type of resource, a custom login page will be displayed, either the iNotes login page or a custom one.
Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option

More details:
11
The user is trying to access a protected resource by using a web browser.The browser is establishing an SSL session on Port 443 and sends HTTP GET / Post request
12
Domino returns a username password dialog box which has been configured for this URL. The layout of this form depends on the URL requested. See Domcfg.nsf
13
The user is entering his ActiveDirectory- or DominoHTTP username / password.Credentials are sent via SSL to the server for verification.
14
Domino is verifying credentials against the Directories configured in its directory assitence database. Multiple directories can be specified, Domino will process all of them.

The connection to an Active Directory server is established via LDAP / SSL using its own credentials configured in the directory assistance database.

15
For successfully authenticated users, the AD user object is returned to Domino. Domino will read the attribute “mailNickname” from the user object and will use this as Notes user name for the user session.
16
Domino returns an LTPAToken to the client and will verify access rights in the ACL of the requested resource or will redirect the user back to the URL he wanted to access in the beginning
17
The browser will receive the LTPAToken in form of a cookie which is valid for the DNS Domain defined in the WebSSO key. At this point the user is authenticated. The browser can now present this cookie to any server which is member of this DNS domain to identify himself.



How to...

Assuming LDAP authentication + SPNEGO have been configured already + domcfg.nsf exists, here is what to do:

1. Create a Web SSO Configuration for SPNEGO Enabled

In this example I'm using "DominoSPNEGOEnabled" as the configuration name.
Organization yourCompany
DNS Domain .yourdomain.com
Map names in LTPA tokens Enabled
Require SSL protected communication (HTTPS) Disabled
Restrict use of the SSO token to HTTP/HTTPS Disabled
Configuration Name DominoSPNEGOEnabled
Participating Server Names List of all servers in the Domain
Windows single sign-on integration (if available) Enabled
Token Expiration 180 minutes



2. Create a Web SSO Configuration for SPNEGO Disabled

Copy and paste the document for the SPNEGO enabled configuration, and change the following elements:
  • Configuration Name: DominoSPNEGODisabled
  • Windows single sign-on integration (if available): Disabled
Key is to have the same WebSSO key for both configurations, which is a value computed when creating a new document. So make sure to copy/paste the existing Web SSO Configuration document to obtain the same key. In case the key will be changed, make sure to update the document which you copied accordingly.

3. Create Internet Site Documents

Prerequisite for the configuration is to use internet site documents for Domino servers providing HTTP services.
Each of the Internet Sites configured should be configured to use the Web SSO configuration created before
  • Web SSO Configuration: DominoSPNEGOEnabled
    This is the name of the Web SSO Key created in the previous step.
  • Force login on SSL: Yes
Then create another Internet Site document to be used as authentication URL, which will be using the DominoSPNEGODisabled

Note that you should use an SSL certificate for each domain. When both internet site documents are located on the same server, you'll need one IP addresses for each domain to properly handle the SSL certificate binding
If you only have one IP address per server, you need two servers where one is using internet sites and one is using web configurations.
Hint: To use the same SSO Key for both types you need to copy/paste the WebSSO document and remove (or add) the company field in one of them

4. Create a Custom Login Form Mapping

This will provide a nice looking a new A username/password dialog box is displayed when SPNEGO can not be used,as alternative for authenticating via username / password.
This form can be customized according to your needs, I'm using the iNotes login form here
Target Database : Domcfg.nsf
Target Form : iNotesLoginForm

5. Create a Custom ‘Not Authorized’ Error Form

This form will be displayed to users who have successfully authenticated against Domino/Active Directory but are not allowed to access the application.
Open the file “domcfg.nsf” in your Domino Designer client, and create a new form called “NotAuthorized”
  • Set the Window Title to “Not Authorized”
  • Set the HTML Head Content to client/formula:
Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option
  • Add one new field “database” of type text/computed for display
    Formula : @UrlQueryString( "database" )
  • Add some HTML code to the body of the form indicating that there is no access to this resource, and mark it as passthru-html using the menu “Text\Passthru-HTML”
    Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option
  • Add the following HTML code to the body of the form, note it contains two computed text blocks
    Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option

    where the formula for is : @Name([CN];@UserName)
    and the formula for is : @LowerCase(@RightBack( @LeftBack( @UpperCase(@UrlQueryString( "database" ));".NSF"); "/")) + ".nsf"
  • Enable the flag “Available to Public Access users” in the form properties
    Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option

6. Create a Custom Redirect Form

This form is used for redirecting anonymous users to a different site than users who have authenticated already.
Open the file “domcfg.nsf” in your Domino Designer client, and create a new form called “AnonymousRedirect”
  • Set the Window Title to “Redirecting”
  • Add the following HTML code to the body of the form, and mark it as passthru-html using the menu “Text\Passthru-HTML”
    Where 'Authentication URL' is the defined DNS name of the Domino server which is hosting the nonSPNEGO Web SSO Configuration.
Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option
  • Type the (non-passthru-html) text “Redirecting…” into the body of the form.
    This text will be displayed to users while the redirect is in progress.
  • Add one new field “RedirectTo” of type text/editable with a default value of “/” at the bottom of the form

Note: There are different options to redirect users, this method is based on a simple JavaScript which will redirect anonymous users to another place than users who have already authenticated but are not authorized to access the resource.

7. Custom Error Handler

Within “domcfg.nsf”, a custom error handler for authorization failures will need to be created in order to redirect users who can not participate in SPNEGO.
Use the view “Error and Response Mapping” and click the "Add Mapping" button.
Applies To  : All Web Sites/Entire Server
For Authentication failures and for Authorization failures, use the same mapping:
Target Database : Domcfg.nsf
Target Form : AnonymousRedirect
Image:Domino SingleSignOn - Level 4 - Seamless Kerberos authentication via SPNEGO with fallback option

Result:

Seamless authentication works fine as before but in addition you get propper error handling.
If users are not authenticated, or not allowed to access the resource, they will be redirected to a page that will allow them to log in as different user.

Troubleshooting
  • The following Notes.ini variables will help to analyze problems:
  • Technote 1394592 - Troubleshooting Windows single sign-on for Web clients (SPNEGO)
  • Make sure the LDAP attribute used for name mapping contains the Notes Name of the user in DN format.
    This is the fully canonical name but slash “/” replaced by a comma “,”
    e.g. for “Peter Mueller/Department/Org” this would be: “CN=Peter Mueller,OU=Department,O=Org”
  • Use the developer tools in your internet browser to display your cookies. You should have a LtpaToken Cookie set.
  • Last but not least: drop a mail or call the author of this blog post.

Domino SingleSignOn - Level 3 - Seamless Kerberos authentication via SPNEGO- 15 February 2017 - (0) Comments

Thomas Hampel
 15 February 2017

This is the third post our of a series of blog posts describing how to move from password based to seamless authentication.
In level one and two I explained how to configure Domino for LDAP / Active Directory authentication. Although there is no need to remember the Domino HTTP password anymore, users still have to provide username/password when they log into (e.g.) iNotes. The next level is to automatically authenticate users - this is what I am going to describe in this article.

Level 3 - SPNEGO

At first, some basic information:
SPNEGO is a standard specification defined in RFC 2478 - The Simple and Protected GSS-API Negotiation Mechanism, allowing authentication of browser clients.
It can be used for seamless browser authentication aka Windows Integrated Authentication (WIA). It can not be used for Notes clients, Traveler or Sametime.

Pros and Cons

+ Seamless authentication for browser clients on Windows
- It's Windows only
- Does'nt work for Traveler and Sametime
- You can not really log off or switch users anymore.

Warning:
  • SPNEGO will only work for clients and Domino servers running on Windows and are member of a Windows Domain
  • Each URL must have exactly ONE ActiveDirectory object to match the Service Principle Name.
  • If you plan to run multiple internet sites on the same Domino server, you MUST run the Domino server task using a Domain user account. Image:Domino SingleSignOn - Level 3 - Seamless Kerberos authentication via SPNEGO
  • For clustered internet sites, you MUST run the Domino server task using THE VERY SAME user account.
  • Running Domino with credentials other than the local system account will make your server fully dependent on this user account.
    If its locked out, has expired, or is removed by accident, your Domino servers wont run. All of them... at once!

Prerequisites
How to...
Remarks:
  • Using SPNEGO you can not really log off anymore, nor switch to another user other than by logging off/on at OS level.
    However there is a trick using a custom login form to get this done which I will describe in the next level.
  • Although highly recommended SPNEGO does not require SSL, it works with plain HTTP as well this might be useful for debugging purposes.

Frequently Asked Questions

What to do in a mixed environment?

You can use one machine on Windows as your authentication server and configure Domino Multi-Server-SSO.
Experienced admins will take a look at this OpenNTF project : SSO for Web for non Windows Servers

What to do in Non-Windows environment like Linux, AIX, or what if there is no Windows Domain?

Set up a Domino server on Windows (who wants that?) or skip this level and wait for my blog post desribing SAML authentication.

References and further reading

Domino SingleSignOn - Level 2 - Self Service Password Reset Application - 14 February 2017 - (0) Comments

Thomas Hampel
 14 February 2017

Based on a recent discussion with a customer it seems there still is not enough information on how to simplify authentication for Notes/Domino users.
This is the second post our of a series of blog posts describing how to move from password based to seamless authentication.
Once you have established LDAP Authentication you can approach the next stage:

Level 2 - Self Service Password Reset Application

Combined with a Self Service Password Request HTTP application (or this fancy one ) users can reset Notes password without the help of an administrator just by using a web browser.
Users must be authenticated in order to reset their own password, but due to the configuration done in level 1 they can use Active Directory credentials to log in.
Once authenitcated a user can just define a new password which is applied immediately in the IDVault. And just seconds later the password can be used to log into the Notes Client.
Image:Domino SingleSignOn - Level 2 - Self Service Password Reset Application

Pros and Cons

+ Lost/forgotten passwords on a monday morning are no longer your problem. Users can handle this problem alone.
+ You don't need to distribute NotesID passwords for newly created users.
- There still is a NotesID password to remember
- There still is a password prompt every time you start the Notes client and/or every time you open an encrypted mail in iNotes
- The Self Service Password Request HTTP application does not apply any feedback on password quality or strength.

Prerequisites:
  • Notes ID Vault has been established and contains the NotesID’s of all users
  • User must be authenticated, preferably using Active Directory authentication as described in the previous post level 1
  • Custom Password Reset application template,
    Please note the template provided by IBM as part of the Domino server is not officially supported and is provided as example only. See Technote 1330905

Configuration

Setup instructions have already been provided by IBM, so I'm not describing those steps again.
Once completed you should have a functioning PW reset application. However, I would like to highlight a few important details
  • The agent and the form needs to be signed with an ID which has IDVault Password Reset authority
  • The ACL of this database must have an Administration server defined, the Admin server specified there must be the one that hosts the IDVault.

For improved usability I do recommend a little tuning:
  • Create a URL which users can remember, e.g. by creating a web redirect rule
    http://yourserver.domain.com/passwordreset ==> /pwreset.nsf
  • Modify the form “fmPasswordReset” to display your corporate password rules, e.g.
    “The new password must have a minimum of 8 characters. It must contain a mixture of lowercase alphabetic, uppercase alphabetic, numbers and special characters. Three of these four conditions must be met.”
  • Modify the source code to confirm the password change request has been submitted and to verify if password rules have been followed.
    Without this modification users will not get any feedback if the new password has been applied or not.
    so update the source code of the Form “Password Change” , Sub “OnSubmit” as follows:
var i = 0;
var k = 0;
var h = 0;
var have = [0, 0, 0, 0];
var characters = ["abcdefghijklmnopqrstuvwxyz", "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "0123456789"];
var minLen = 8;
var minDif = 3;
var pw1 = document.forms[0].pw1.value;
var pw2 = document.forms[0].pw2.value;
for (i=0; i {
       h = 3;
       for (k=0; k        {
               if(characters[k].indexOf(pw1.substr(i,1)) >= 0)
               {
                       h = k;
               }
       }
       have[h] = 1;
}

if ( pw1.length < minLen )
{
       alert("You must enter a password with at least " + minLen + " characters");
       return false
}
else if( pw1 != pw2 )
{
       alert("Entered password don't match");
       return false
}
else if( have[0] + have[1] + have[2] + have[3] < minDif )
{
       alert("Password must be more complex,  use Numbers, Lower-, Upper-, Special-Characters");
       return false
}
else
{
       alert("Thank you, your request has been submitted. The new password can be used now.");
       return true
}
  • In order to support clustered environments the source code of the agent “User Password Reset” needs to be updated as follows:
Set Doc = Session.DocumentContext
Call
Session.ResetUserPassword( session.Currentdatabase.Acl .Administrationserver,"",Doc.GetItemValue("pw1")(0))


Conclusion

Self Service Password Reset application combined with LDAP authentication will eliminate the need to distribute Notes ID passwords to end users.
Administrators can register new NotesID's with completely random passwords that they do not need to remember nor need to distribute to end users.
Notes client setup instructions can be simplified so that end users have to define the password themselfes before they can start Notes for the first time.

References:

Domino SingleSignOn - Level 1 - LDAP Authentication- 13 February 2017 - (0) Comments

Thomas Hampel
 13 February 2017

Based on a recent discussion with a customer it seems there still is not enough information on how to simplify authentication for Notes/Domino users.
This is the first post our of a series of blog posts describing how to move from password based to seamless authentication.

Level 1 – LDAP Authentication

Main goal of this level is to provide users with the ability to authenticate with Domino internet protocols such as HTTP using LDAP (e.g.Active Directory) credentials. The Notes Client authentication remains unchanged.
When using a web browser to access a Domino server, users will be prompted for username and password.
This authentication dialog looks like one of the following examples:
Image:Domino SingleSignOn - Level 1 - LDAP AuthenticationImage:Domino SingleSignOn - Level 1 - LDAP Authentication
Credentials entered here will be forwarded to Active Directory for authentication.
Within this process username and password will be sent over the network, so it is highly important to secure the transmission using SSL/TLS.

Pros and Cons

+ Lost/forgotten passwords on a monday morning are no longer your problem. The AD guys have to take care :)
+ No need to manage HTTP passwords and no need to sync HTTP and Notes passwords
- All authentication requests will be forwarded to LDAP/AD, entering wrong passwords multiple times -depending on your policy- will lock out your AD account.

Prerequisites:

In order for Active Directory authentication to work, the Notes user name must be stored within Active Directory (or the AD name must be stored in Domino). This is required to map Active Directory user name to a Notes user name.
  • Within Active Directory, each user object must have a (custom) attribute storing the Notes User name in DN format. This format is described as the full canonical user name of the Notes user (e.g. “CN=Firstname Lastname,OU=Department,O=Company”) where any slash (“/”) is replaced by a comma (“,”)
  • The name of this (custom) attribute of the user object in Active Directory can be any name of your choice, I will be using “mailNickname”, but you can use any other attribute you like.
    This attribute is recommended to be included in the AD Index for performance reasons. For details how to do this, please refer to this article which relates to an older version of AD but is still valid.
  • Synchronization from Domino Directory to Active Directory is done on a regular basis, e.g. by using TDI (which is free for Domino customers) with some AssemblyLines for Domino
  • A non-expiring Active Directory User account is required that will be used by Domino for Single SignOn purposes.
How to...
reconfigure Domino HTTP authentication to use Active Directory for authentication of browser sessions?
If not already done:
  • Import the trusted root certificate of the LDAP server into the key ring file of the Domino server.
    Please note that Domino will be the client for the LDAP session in this case, so the *.kyr file that is being used is the one in the server document!
  • Create a Directory Assistence (DA) database
  • Add the DA to your Domino server document
    Image:Domino SingleSignOn - Level 1 - LDAP Authentication

okay, whats next:
  1. Within the Directory Assistance database, add a new document and configure it like shown below:
    Image:Domino SingleSignOn - Level 1 - LDAP Authentication
    Of course you are supposed to supply your correct Kerberos realm name. If in doubt, ask your AD admin.
  2. Set "Trusted for Credentials" to Yes
    Image:Domino SingleSignOn - Level 1 - LDAP Authentication
  3. Configure how to connect to the LDAP (­) server.
    Image:Domino SingleSignOn - Level 1 - LDAP Authentication
  4. Save & close

Now restart the Domino server and check if LDAP is being shown in the list of directories.
Issue the command "Show xdir" at the server console for details.

Troubleshooting:

Apache LDAP Studio is your friend. Make sure your LDAP credentials are correctly working and that your Base DN is providing the expected results before setting up Directory Assistence towards AD.
Some more hints:
  • You can specify multiple LDAP servers, they will be used one after the other based on the search order you have supplied
  • Search order in the Directory Assistance document must be unique. You can not use the same "Search order" twice.
  • Domino will be the client for the LDAP session in this case, so the *.kyr file that is being used is the one in the server document!
    If you are using Internet sites, then Edit the server document, disable internet sites (without saving) and specify the *.kyr file there. When done, switch back to the basics tab and re-enable Internet Sites.
    The file specified will still be used for all outbound connections, the kyr file specified in the internet sites is used for inbound connections only!
    Image:Domino SingleSignOn - Level 1 - LDAP Authentication
  • Thes Notes.ini variables will increase the log level for further debugging
    debug_directory_assistance=1
    debug_namelookup=1

Result:

When prompted for username/Password you can now use your Active Directory username and AD Password.
Transitioning from Domino HTTP passwords to AD passwords is seamless because users can still use the Domino HTTP password even if LDAP authentication has been configured.
Once the transition is completed you should clear the HTTP password field from the person document.

Checklist for Smartcloud Notes Hybrid Configuration- 12 November 2015 - (0) Comments

Thomas Hampel
 12 November 2015

Your first step towards the cloud is to build a hybrid environment e.g. to support a proof of concept in your environment.
In most cases customers would like to move a few users to the cloud to experience the onboarding process, confirm seamless coexistence of on-premises and cloud environments, and explore new features of the cloud such as IBM Verse.

Although IBM provides a full training course for setting up a hybrid environment, I still would like to (with friendly support of Hagen Bauer) provide a checklist for customers to support this process and getting started as quickly as possible.

Warning:

This checklist may not be perfect, you should still read the documentation and talk to your certified IBM expert of choice.
It is supposed to be a checklist for customers, not for certified onboarding specialists that will move your IBM Notes mail to IBM Cloud.
Suggestions and ideas for further improvement are always welcome.

Overview

This is a graphical overview of a hybrid environment. On top are your (On-Premises) servers, at the bottom are cloud servers and in between (red) the internet.
Image:Checklist for Smartcloud Notes Hybrid Configuration

Steps
  • Check your inventory! Are current servers available? Are they accessible? Are they placed in the network zone they are expected to be?
    See graphic above and verify positioning of:
    #1 = Domino Administrator Client
    #2 = On-Premises Mail Server
    #3 = On-Premises Directory Mail Server
    #4 = Passthru Server in DMZ
  • Complete this table with data from your environment. Make its correct and complete.
  • Configure your Firewall for inbound and outbound traffic.
    Check twice, and verify Firewall settings once again before claiming to be done. A mistake at this point will cause headaches later on.
  • Make sure your passthru server is using the same root certificate as your HUB and MAIL server?
    Can the Admin client (see #1 in the graphic above) access the passthru server?
  • Create a new OrgUnit based on your current Domino certificate. This certificate will be used later on for all your Domino servers in the cloud.
    Example: "/SCN/Company" or "/Cloud/SRV/Company"
  • In your current environment, does your Global Domain Document meet those requirements?
  • Make sure you still have the SmartCloud activation email available. The one that contains the SmartCloud activation link.
    Oh, and make sure the link has not expired.
  • In the SmartCloud Notes account initial setup, did you choose "Hybrid Account" ?
    If not you need to request a full reset of your account by contacting support@collabserv.com
  • Define a name prefix for your cloud mail servers. Choose a short but remarkable prefix and dont pick something too fancy.
    Example: **Cloud-**/SCN/Company
  • Are you prepared to create new and modify existing DNS records for your company domain?
    Make sure you have control over your DNS records.

Conclusion

All of the above steps are part of the documentation, but not in a single place. I hope you can make use of this reference in your SmartCloud onboarding project.
Feedback is very welcome, so drop me a mail or send a tweet

References:

Monitoring IBM Domino Server on Linux via SNMPv3- 5 January 2015 - (0) Comments

Thomas Hampel
 5 January 2015

Monitoring Domino servers via SNMP should be a simple task, if it would be documented properly.
There are quite a few blog posts out there on the internet such as
this nice article by Detev Schuemann which unfortunately is in German.. So I'd like to provide an english translation with a few updates which in my opinion are valuable.

Background

Simple Network Management Protocol (SNMP) is a protocol for monitoring network devices such as routers, switches, servers, printers and much much more.
Vendors of a device are providing a definition of values which can be read or modified in form of a
MIB (Management Information Base). Those values are called OIDs (object identifiers) and are ordered in a hierarchical structure.

MIB definitions for Domino can be found online
http://www.oidview.com/mibs/334/NOTES-MIB.html
A MIB file for IBM Domino can be found in the Domino program directory and is called "domino.mib"

On a Linux server the file can be found here /opt/ibm/domino/notes/latest/linux/domino.mib


Step-by-step Instructions

For each Domino server which you want to monitor, you need to enable SNMP support, the following is a step by step description of what you need to do for a Domino server on Linux.
Instructions for Windows are available here
Examples below are based on
CentOS which is using yum as package manager. For other Linux distributions commands are slightly different, also path references shown in the example below might not be the same for you.

Step 1 - SNMP Master Agent

Although Domino its own snmp master agent, I recommend not to use it because the version supplied with Domino is the rather dated version 5.0.7
.
Currently version 5.7.3 is the latest version available. Check the
net-snmp change log to see what has changed between versions.
Obviously you should prefer using the operating system snmp master agent which comes preinstalled for a number of Linux distributions.
If not already installed, you can install the package net-snmp with the following command.

# yum install net-snmp

The library net-snmp-utils provides some additional tools like snmpwalk, which we will need later on for testing functionality
# yum install net-snmp-utils

To check the version you are running...

$ snmpwalk --version

Image:Monitoring IBM Domino Server on Linux via SNMPv3
Note: Current releases of CentOS and Redhat provide net-snmp version 5.7.2 by default.


Option B - NET-SNMPD v5.0.7 provided by Domino

Domino provides net-snmpd in version 5.0.7  - again, I do not recommend using this version.

However, if really want to use it enter these commands to copy the required files to the /etc directory and make sure the service is started after a reboot.

# cp /opt/ibm/domino/notes/latest/linux/net-snmpd* /etc
# ln –f –s /etc/net-snmpd.sh /etc/init.d/net-snmpd

# chkconfig --add net-snmpd

# chkconfig net-snmpd on

Note that in this type of configuration your settings are stoed in the file  /etc/net-snmpd.conf

Step 2 - Update Configuration

Back up the original config file to a location of your choice

cp /etc/snmp/snmpd.conf /root

Edit the file /etc/snmp/snmpd.conf . Modifying this file is only required if you are using the master agent provided by your OS.

# nano /etc/snmp/snmpd.conf

1.) Search for sysLocation and update it according to your needs as shown here:
sysLocation    YourDataCenterLocation
sysContact     email@yourdomain.com


2.) define a username/password combination for SNMP v3 authentication
Of course the user name and password used in this example are to be changed to fit your needs

createUser SNMPv3UserName MD5 SNMPUserSecretPassword AES


3.) At the end of the same file, add this line:
smuxpeer 1.3.6.1.4.1.334.72 NotesPasswd

Dont forget to save the file


Step 3 - SNMP Startup Script

Although you could add /usr/sbin/snmpd as a service directly, its probably more useful to use a startup script.

Domino already provides such a script - you just need to modify the configuration so that it can be used.


# cp /data/ibm/domino/notes/latest/linux/net-snmpd.sh /etc/init.d/net-snmpd

# nano /etc/init.d/net-snmpd


Update the configuration (starting in line 31) as follows:

INSTDIR=/usr/sbin
PROGNAME=snmpd

PROGPATH=$INSTDIR/$PROGNAME

CONFNAME=snmpd.conf

CONFPATH=/etc/snmp/$CONFNAME

LOGPATH=/var/log/snmpd.log

PROGARGS="-C -c $CONFPATH -l $LOGPATH"

Make sure the startup script runs at next boot

# chkconfig --add net-snmpd
# chkconfig net-snmpd on


Step 4 - Update Firewall Rules

SNMP requires UDP port 161 to be accessible, so you need to open this port on the local firewall.
Do not forget to open this port on any other firewall on your network which is between the monitoring server and your Domino server
# iptables -I INPUT -p udp --dport 161 -j ACCEPT


Step 3 - Testing basic functions

Test basic SNMP functionality
from the local host and also from a remote server.
# snmpwalk -v3 -u SNMPv3UserName -A SNMPUserSecretPassword -a MD5 -l authnoPriv dominoserver.domain.com .1.3.6.1.4.1.2021.100.2.0

As a result you should get the version number of the SMTP master agent

Image:Monitoring IBM Domino Server on Linux via SNMPv3

Step 5 - Enable Domino SNMP Agent

Make sure LNSNMP will be started after a reboot. (Note: change the path to match your configuration!
)
# ln -f -s /opt/ibm/domino/notes/latest/linux/lnsnmp.sh /etc/rc.d/init.d/lnsnmp
# chkconfig --add lnsnmp

# chkconfig lnsnmp on
# service lnsnmp start

In case you get the error  "LOTUSDIR must be set in the environment or in this script." you need to update script so that it can find the path to your Domino server, e.g. LOTUSDIR=/opt/ibm/domino


if everything has worked out, starting the lnsnmp should provide the following output

New sub-agent on server is registering a sub-tree with branch ID:
1.3.6.1.4.1.334.72.3

Sending SNMP "Server Up" trap for server .

service lnsnmp startNew sub-agent on server is registering a sub-tree with branch ID:

1.3.6.1.4.1.334.72.1


Step 6 - Domino Tasks

Start the following tasks from the Domino server console

load quryset
load intrcpt
load collect

"quryset" is required to support SNMP queries

"intrcpt" is required to support SNMP traps for Domino events

"Collect" is required to support statistic threasold traps

Create a program document or add the tasks to the Notes.ini variable "ServerTasks=" so ensure they are started automatically after a server restart.

Step 7 - Testing Domino SNMP agent response

Now its time to test if we can access Domino objects via SNMP, e.g. by reading a single value.

$ snmpget -v3 -u SNMPv3UserName -A SNMPUserSecretPassword -a MD5 -l authnoPriv dominoserver.domain.com .1.3.6.1.4.1.334.72.1.1.6.2.1.0

Should return the fully qualified Domino Server name as a string

Image:Monitoring IBM Domino Server on Linux via SNMPv3

Ok, you're done... the Domino SNMP Agent is configured and can be used.

However, there still is some work to be done on your SNMP management console e.g.
Nagios ,FAN , Cacti (or whatever you are using) in order to monitor Domino via SNMP (for example, server down).

Next Actions:

If you like this post, please let me know via Twitter
@ThomasHampel or by leaving a comment below. Please note that comments are moderated and wont show up before being approved.
Hint... configuring Nagios for Domino monitoring and configuring Cacti for trend analysis is subject of another blog post which I'm already working on.


Troublshooting
  • Check snmpd.log for errors
    # cat /var/log/snmpd.log
  • Error : refused smux peer: oid SNMPv2-SMI::enterprises.334.72, descr Lotus Notes Agent
    see
    IBM Technote 1313318
  • Error - Unknown User
    Either a typo in the user name or you forgot to add the user to the snmpd.conf file in step 1, search the config file for something like this:
    createUser SNMPv3UserName MD5 SNMPUserSecretPassword AES
  • Error in packet. Reason: authorizationError (access denied to that object)
    The user exists and the password worked, but does not have access rights required. Check snmpd.conf to see if you have granted at least read only rights, search the file for a string like this:
    rouser SNMPv3UserName

Tools:

Take a look at
Paessler SMTP Tester (Freeware / Windows)
Image:Monitoring IBM Domino Server on Linux via SNMPv3

Further reading:

The Dummies Guide to 2048 Bit SSL Self Signed Certificates in Domino- 7 May 2014 - (3) Comments

Thomas Hampel
 7 May 2014

Setting up SSL in Domino using Self Signed Certificates is easy, one can choose between SSL using Domino as Certificate Authority or setting up SSL in Domino using the CA Process or even using an IBM HTTP Server in front of Domino
Since I'm still getting questions on how to quickly create a self signed certificate for Domino, here is a guide for dummies....

When working with self signed certificates in Domino, the product documentation wont tell you there's one small problem:
In the standard Domino Server Certificate Administration template (csrv50.ntf) there is no option to specify the key length for self signed certificates, so by default any new keys will be created with a key length of just 512byte, which is not enough for modern browsers nor for Internet Explorer 9 (or above), see
http://technet.microsoft.com/en-us/security/advisory/2661254
Image:The Dummies Guide to 2048 Bit SSL Self Signed Certificates in Domino

So lets get this fixed by applying some small modifications to the template so the key size can be adjusted when needed. At the same time we can also change the default validation time to be configurable.
Continue Reading "The Dummies Guide to 2048 Bit SSL Self Signed Certificates in Domino" »

Domino Program documents and schedule- 6 September 2012 - (1) Comments

Thomas Hampel
 6 September 2012

Problem: A customer reported Domino would not be responding at a specific point in time, but servers dont crash - they are unresponsive.

Analysis
: Looking into the Domino server logs at about the time when the problem reported showed that some scheduled tasks were running.
While scrolling down the logs it became clear that the compact task was blocking access to the server's system databases - in this case log.nsf - which caused the server to ignore incomming requests.

From the end users point of view the server came to an halt while from the servers point of view all was okay.


Action:
Getting Domino program documents scheduled perfect could be a long journey. Here is my recommendation on how to do it right.
Program Command Line Schedule Comments
convert -l mailprimary.ind 18:50 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Generates a list of mail files by reading people's mail files from the Domino Directory and writes the list into an IND file.
compact -A mailprimary.ind 19:00 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Archive data but dont reduce the mail file size, thats because compacting will be done thru another program document.
compact -B -S 20 -w 23:00 each day
Repeat interval of: 0 minutes
Days of week: Fri
Once per week, reduce the file size if there are at least 20% whitespace in the file
Exclude system DB's with option -w , for servers before 8.5.4 this requires the variable DEBUG_ENABLE_COMPACT_8_5=1

Note: Reducing the file size for every file every day will just increase the level of fragmentation and will reduce performance.
compact -b -w 23:00 each day
Repeat interval of: 0 minutes
Days of week: Sun, Sat
Make sure the white space is located at the end of the NSF file for better performance when creating new documents
Note : Do not run on Friday, due to backup.
compact -b log.nsf 04:30 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Special schedule for log.nsf after 04:00 when purge has been completed.
To make sure the white space is located at the end of the NSF file for better performance when creating new documents.
catalog 01:00 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Updates information in catalog.nsf
updall 02:00 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Updates existing views
statlog 05:00 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Record statistics
daosmgr resync 23:30 each day
Repeat interval of: 0 minutes
Days of week: Mon, Wed, Fri
Every second day resync the DAOS repository
collect At server startup only Remark: Make sure the task is not loaded in the Notes.ini via “ServerTasks=”
http At server startup only Remark: Make sure the task is not loaded in the Notes.ini via “ServerTasks=”
rnrmgr At server startup only Remark: Make sure the task is not loaded in the Notes.ini via “ServerTasks=”
(n)server -c "tell sched validate" 02:00 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Rebuilds the clubusy/busytime
(n)server -c "tell mtc purge 7" 00:00 each day
Repeat interval of: 0 minutes
Days of week: Sun, Mon, Tue, Wed, Thu, Fri, Sat
Purge data older than 7 days from the message tracking store





Optional Program Documents for Specific Server Types
Program Command Line Schedule Comments
(n)server -c “tell router compact” 18:00 each day
Repeat interval of: 0 minutes
Days of week: Sun
This will reduce the file size of the mail.box'es, but will increase fragmentation on disk. Not recommended for servers with high mail volume.




Of course noone is perfect, so any comments and suggestions for improvements are very welcome !
Go ElsewhereSubscribe to RSSAboutStay ConnectedAnd More
Thomas Hampel, All rights reserved.