Search This Blog
Saturday, December 24, 2011
New email
Từ ngày 1/1/2012 do không tiếp tục làm việc tại Công ty CP tin học Tân Dân nên email NSNguyen@tandan.com.vn sẽ không còn tồn tại nữa. Mọi người có thể liên hệ theo địa chỉ NSNguyen@vsd.com.vn hoặc NguyenSTV@gmail.com
Tuesday, December 6, 2011
Moving an IIS SSL certificate to a Domino Keyring File
www.turtleweb.com
Today I had a support call from a customer who had bought an SSL certificate from Verisign to cover their entire domain. Verisign had issued the certificate and it had been applied to their existing IIS servers however they now wanted to use it on their Domino web server as well. The scope of the certifier covered the Domino server (same wildcard domain) but Verisign wouldn't process another request from a Domino keyring file as they had already issued the key in response to the IIS request. They agreed to cancel the IIS certificate and issue a new one for Domino but according to their tech support "the use of the wildcard domain covers you for up to 10 servers so long as you can copy the same certificate between the servers. As Domino and IIS are incompatible you have to buy a new certificate"
Well that seemed like a gyp so I decided to prove it could be done. With the help of some related IBM technotes this is what I did to get it working.
- Created an exported pfx file from IIS
- Went to a domino server and from a prompt found the directory \domino\jvm\bin directory and ran the file "ikeyman" within it
- Created a new Key DB file by browsing to the IIS exported pfx file and importing it as PKCS
- Examined the imported certificate and noted the certificate settings such as Organisation, OU, L etc
- Closed ikeyman
- Created a new key ring file using the Secure Certificate Admin db on Domino
- Gave it the exact same settings as the original IIS certificate noted down in step 4.
- Installed the trusted root certificate into the key ring file
- Copied the .kyr and .sth files to the server where ikeyman ran and where the PKCS file generated in step 3 was located
- Downloaded gsk version of ikeyman to handle Domino key ring files from here ftp://ftp.software.ibm.com/software/lotus/tools/Domino/gsk5-ikeyman.zip
- Extracted zip file to folder 'gsk' on server (folder can be called anything but no spaces)
- Ran "gskregmod.bat Add" from command prompt within extracted folder
- Launched the ikeyman from dos prompt in the newly extracted folder by typing "runikeyman.bat"
- Chose Key Database File - Open and selected the kyr file I copied to the server in step 9
- Go to Personal Certificates and click 'Import' then choose 'PKCS' and import the file generated in step 3
You should now have a .kyr file that contains the certificate and can be copied back to your destination Domino server along with its .sth file.
Thursday, December 1, 2011
Configuring Microsoft Windows single sign-on on IBM WebSphere and Domino platforms
Introduction
Microsoft® Windows® single sign-on (SSO) allows the client in an Active Directory domain to be authenticated with the server, without being prompted for a user name and password, by leveraging Simple and Protected GSS-API Negotiation Mechanism (SPNEGO).
As of WebSphere® Application Server version 6.1, WebSphere provides the native support for Windows SSO by SPNEGO trust association interceptor (TAI). In version 7.0, WebSphere introduced better support for Kerberos, including the Kerberos mechanism for server-to-server authentication, as well Kerberos Web Authenticator.
As of version 8.5.1, Lotus Domino also started to support Windows SSO, though only on the Windows platform. In this article we introduce the Windows SSO configuration process on both the WebSphere and Domino platforms.
Common configurations
Windows SSO is based on Kerberos/SPNEGO protocols, and there are some steps we need to do on Kerberos before configuring either WebSphere Application Server or Lotus Domino. These common configurations include time synchronization and register service principal names (SPN) for the Web application.
Time synchronization
Timestamp is a critical factor in Kerberos authentication, and Kerberos requires the clocks of the involved hosts to be synchronized. Thus, the time of WebSphere Application Server or Domino in the SSO domain must be synchronized with the domain controller; otherwise, the Kerberos authentication will probably fail.
You can use the domain controller as the time server and run the Windows schedule task on all participating nodes to synchronize the time with the domain controller. For more information about how to use the domain controller as the time server, refer to the Microsoft Support document, “How to configure an authoritative time server in Windows Server.” For more information about running the Windows schedule task, see “Time synchronization may not succeed when you try to synchronize with a non-Windows NTP server in Windows Server 2003.”
For example, if lotus.ibm.com is both the domain controller and the Network Time Protocol (NTP) time server, then the TimeSyn.bat file would contain the following commands:
- w32tm /config /manualpeerlist:lotus.ibm.com,0x8 /syncfromflags:MANUAL
net stop w32time
net start w32time
w32tm /resync
Register SPN for Web applications
An SPN uniquely identifies a service in the Kerberos environment, and you must create an SPN to identify the Web application you want to enable with Windows SSO.
An SPN is typically composed of a service name, a fully qualified host name, and a realm name, for instance HTTP/lotus.ibm.com@IBM.COM. For Web applications, the service name is always HTTP. To register an SPN for the application, perform the following steps:
- Log in to the Windows Domain Controller. You must know which server is the domain controller and have an administrative-level user name and password.
- In Active Directory Users and Computers settings, select Action – New – User, to create a new service account that holds the SPN.
- In the New Object - User window, enter an account name into the User logon name field and specify the domain in the corresponding field. For example, in the User logon name field, you could add appuser01, and in the domain field, you could select @ibm.com. Click Next.
- Enter a password for the account in the Password field and Confirm password.
- Select the User cannot change password and Password never expires check boxes. By preventing the password from expiring, you avoid having to recreate the keytab file (which you do in the next step) after the password is changed. Click Next and Finish, to save the new user information.
- Map the SPN to the user account you just created, and then generate a keytab file by running the ktpass command on the domain controller. To run the ktpass utility, you must have Windows Support Tools installed (refer to Install Windows Support Tools for more details). Run the ktpass command as follows:
ktpass –princ <SPN> -out <path_to_keytab> -mapuser <account_name> -mapOp set –pass <account_password>
where you provide values for the following variables:
- <SPN>: The Kerberos SPN, which is composed of the “HTTP/” prefix and host name through which your Web application is accessed. Note that, in a network deployment, if your Web application is accessed via the IBM HTTP server, you should specify the host name of the HTTP server in SPN.
- <path_to_keytab>: File path in which you want to store the generated keytab file.
- <account_name>: The service account name you created in the previous step.
- <account_password>: Password associated with the service account. Note that, if you are configuring Windows SSO on WebSphere Application Server, you may optionally use the -rndPass option of ktpass utility, to generate a random password for better security.
For example:
ktpass -princ HTTP/lotus.ibm.com@IBM.COM -out c:\keytab
-mapuser appuser01 -mapOp set -pass mypassword
You will need the keytab file when configuring Windows SSO for WebSphere Application Server.
Configuring SSO on WebSphere Application Server
In this section we describe the steps to enable Windows SSO on WebSphere Application Server, covering the configurations for both WebSphere Application Server V6.1 and V7.0. Because WebSphere Application Server is based on JavaTM Virtual Machine (JVM), the configuration process includes the steps to enable JVM with Kerberos and the WebSphere-specific configuration for inbound Web requests.
Create a Kerberos configuration file
To enable the JVM in WebSphere Application Server with Kerberos capabilities, you must create a Kerberos configuration file, which is normally named krb5.conf. The wsadmin utility in WebSphere Application Server can help you create this file.
NOTE: If you are in a network deployment environment, once you generate the configuration file, you must copy the configuration file to \java\jre\lib\security\krb5.conf on all servers in the cell.
On the wsadmin command line, enter the following command:
$AdminTask createKrbConfigFile
{
-krbPath <appserver>\java\jre\lib\security\krb5.conf
-realm <REALM>
-kdcHost <kdc_hostname>
-dns <dns_hostname>
-keytabPath <path_to_keytab>
}
where you provide values for the following variables:
- <appserver>: The path to the WebSphere Application Server root directory. The krbPath parameter defines where the resulting krb5.conf configuration file is stored. It is recommended to use \java\jre\lib\security\krb5.conf, as it is the default location for krb5.conf. However, if you want to use a non-default location for the krb5.conf file, you MUST specify a java.security.krb5.conf custom property for each JVM in the WebSphere Application Server cell.
- <REALM>: The Kerberos realm. Specify the realm in all uppercase letters.
- <kdc_hostname>: The name of the Active Directory key distribution center host. This name is typically the domain controller server.
- <dns_hostname>: The DNS server name of the domain controller server.
- <path_to_keytab>: The path to the keytab file. If you are in a network deployment environment, after you have generated the keytab, you must copy the keytab file to the same location on all servers in the cell, or use a unified path that points to a shared location on the network.
Listing 1 shows a sample configuration file.
Listing 1. Sample configuration file
[libdefaults]
default_realm = IBM.COM
default_keytab_name = FILE:C:\keytab
default_tkt_enctypes = des-cbc-md5 rc4-hmac
default_tgs_enctypes = des-cbc-md5 rc4-hmac
kdc_default_options = 0x54800000
# forwardable = true
# proxiable = true
# noaddresses = true
[realms]
IBM.COM = {
kdc = ibm.com:88
default_domain = ibm.com
}
[domain_realm]
.lotus.ibm.com = IBM.COM
Once the krb5.conf file is ready, you must restart WebSphere Application Server, to pick up the configurations and enable the underlying JVM with Kerberos capabilities. To verify the Kerberos configurations, type the following command to determine whether it can successfully get the Kerberos ticket:
<appserver>/java/jre/bin/kinit -k HTTP/lotus.ibm.com@IBM.COM
Create an HTML page
There are cases in which SPNEGO is not supported by browsers, or the clients have not logged into the Active Directory domain. In those cases, it is commonly desired that users can still log into the Web application with their user name and password via traditional form-based authentication.
Listing 2 shows a static HTML file that is used to redirect users whose Web browsers do not support SPNEGO to a non-SPNEGO-protected page that asks for authentication credentials. You should store the HTML file on a public place that is accessible to all the servers in the cell.
Listing 2. HTML file to redirect users
<!DOCTYPE HTML PUBLIC "-//W3C/DTD HTML 4.0 Transitional//EN">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html">
<!--
Notes:
- This file should be served from an unprotected Web site. Alternatively,
it can be loaded from the WebSphere Application Server file system.
- Any embedded graphics/javascript/css MUST BE loaded from an unprotected
Web site.
- This file will be loaded after when the WebSphere Application Server is
initialized. If changes to this file are necessary, the Application Server
should be restarted.
- This file is returned whenever the SPNEGO TAI receives an NTLM
token for ANY application in the cell. In other words, this file is
generic for all applications. However, by using the JavaScript
document.location, we can get the original URL, and redirect to that
original URL with the "?noSPNEGO" text added - thus forcing the standard
application userid/password challenge.
-->
<html>
<script language="javascript">
var origUrl=""+document.location;
if (origUrl.indexOf("noSPNEGO")<0) {
if (origUrl.indexOf('?')>=0) origUrl+="&noSPNEGO";
else origUrl+="?noSPNEGO";
}
function redirTimer() {
self.setTimeout("self.location.href=origUrl;",0);
}
</script>
<META HTTP-EQUIV = "Pragma" CONTENT="no-cache">
<script language="javascript">
document.write("<title> Redirect to "+origUrl+ " </title>");
</script>
<head>
</head>
<body onLoad="redirTimer()"/>
</html>
Enable SPNEGO TAI (version 6.1 only)
In WebSphere Application Server 6.1, SPNEGO TAI is used to perform the SPNEGO authentication. Perform the following steps to enable SPNEGO TAI in WebSphere Application Server:
- Log into the WebSphere Application Server Integrated Solutions Console, if you have a standalone deployment, or into the Deployment Manager, if you have a network deployment.
- Add custom properties to the Web Security settings by completing the following steps:
- Expand Security and then select Secure administration, applications, and infrastructure. Expand Web Security, and then click Trust association.
- Select Enable trust association.
- Select Interceptors – com.ibm.ws.security.spnego.TrustAssociationInterceptorImpl – Custom properties.
- Click New, to add each property, and then enter the details of the following properties:
com.ibm.ws.security.spnego.SPN1.hostName=<hostname>
com.ibm.ws.security.spnego.SPN1.NTLMTokenReceivedPage=<TAIRedirectPage_location>
com.ibm.ws.security.spnego.SPN1.spnegoNotSupportedPage=<TAIRedirectPage_location>
com.ibm.ws.security.spnego.SPN1.filter=request-url!=noSPNEGO;<other_product_specific_filters>
com.ibm.ws.security.spnego.SPN1.filterClass=com.ibm.ws.security.spnego.HTTPHeaderFilter
- where
<hostname>: Name of the server from which your Web applications are accessed. It should be the same as the hostname used in the SPN.
<TAIRedirectPage_location>: File path to the HTML redirect file that you created in the previous step. The path should always start with file://. For example, file:///c:/share/TAIRedirect.html.
- e. Click OK and then Save, to save each new custom property.
3. From the main Integrated Solutions Console, expand Servers, and then select Application servers.
4. Click the server name (for example, server1), expand Java and Process Management, and then select Process Definition – Java Virtual Machine – Custom Properties.
5. Add the custom property, com.ibm.ws.security.spnego.isEnabled = true.
6. Click OK and then Save, to save the custom property.
7. Repeat steps 3 through 6 for each server in the WebSphere Application Server cell.
Enable SPNEGO Web Authenticator (version 7.0 only)
SPNEGO Web Authenticator was introduced in WebSphere Application Server version 7.0 as the successor to SPNEGO TAI. Although SPENGO TAI still works, it is recommended to move to the SPNEGO Web Authenticator as it expand the capability of SPNEGO TAI.
To configure SPNEGO Web Authenticator, perform these steps:
- Log in to the WebSphere Application Server Integrated Solutions Console if you have a standalone deployment, or into the Deployment Manager, if you have a network deployment.
- Expand Security, select Global Security, and in the Authentication section, expand Web and SIP Security, and click SPNEGO Web authentication.
- In the SPNEGO filter section, click New, to create a new filter and specify the following properties:
- In the Host name field specify the name of the server from which your Web applications are accessed. It should be the same as the one used in SPN.
- In the Kerberos realm name field specify the Kerberos realm name, for instance IBM.COM.
- In the Filter criteria field specify request-url!=noSPNEGO;. Specific Lotus products might have different filter configurations.
- In the Filter class field enter com.ibm.ws.security.spnego.HTTPHeaderFilter.
- In the SPNEGO not supported error page URL and NTLM token received error page URL fields specify the shared location of the static HTML page created in Section 3.2 above. Note that the page URL should start with file://.
- Put a check mark in the Trim Kerberos realm from principal name and Enable delegation of Kerberos credentials check boxes.
4. Click OK and Save, to save the new filter.
5. On the SPNEGO web authentication page, select the Dynamically update SPNEGO, Enable SPNEGO, and Allow fall back to application authentication mechanism check boxes.
6. In the Kerberos configuration file with full path field, specify the location of krb5.conf that was generated in Section 3.1 above.
7. You can leave the Kerberos keytab file name with full path field blank, to use the default keytab specified in krb5.conf, or specify the location of the keytab file generated in Section 2.2.
Authenticate on an unprotected URI (optional)
By default, SPNEGO TAI and SPNEGO Web Authenticator will authenticate the user once a URI is accessed, regardless of whether it requires authenticated access or not. However, in many cases, it is desirable to authenticate only when needed; for instance, when a user requests a protected page or resource.
The steps below describe how to avoid SPNEGO authentication on an unprotected URI by setting the performTAIForUnprotectedURI custom property.
To set a custom property that disables SPNEGO-TAI authentication when an unprotected URI is accessed in WebSphere Application Server 6.1:
- Select Security – Secure administration, applications, and infrastructure – Custom properties.
- Click New and enter the custom property:
- com.ibm.websphere.security.performTAIForUnprotectedURI=false
NOTE: This configuration works only from WebSphere Application Server version 6.1.0.21. Refer to IBM Support document #PK64013 for more detailed information.
To set a custom property that disables SPNEGO-TAI authentication when an unprotected URI is accessed in WebSphere Application Server 7.0:
- Select Security – Global Security – Custom properties.
- Click New and enter the custom property:
- com.ibm.websphere.security.performTAIForUnprotectedURI=false
NOTE: This configuration works only from WebSphere Application Server version 7.0.0.13. See IBM Support document #4027626 for more details.
Generate SPN for WebSphere Application Server (version 7.0 optional)
A Kerberos authentication mechanism for server-to-server communication was introduced in WebSphere Application Server 7.0. Although most of time Kerberos authentication is not required, we believe it is a good practice, to achieve a more secure deployment.
Below are the instructions to enable Kerberos authentication for server-to-server communications. The steps are generally the same as generating an SPN for WebSphere applications.
- Log in to the Windows Domain Controller. You must know which server is the domain controller and have an administrative-level user name and password.
- In Active Directory Users and Computers settings, select Action – New – User, to create a new service account that holds the SPN.
- In the New Object - User window, enter an account name in the User logon name field and specify the domain in the corresponding field. For example, in the User logon name field, you could add wasuser01, and in the domain field, you could select @ibm.com. Click Next.
- Enter a password for the account in the Password field and Confirm password.
- Select the User cannot change password and Password never expires check boxes. By doing this, you avoid having to recreate the keytab file (which is done in the next step) after the password is changed. Click Next and Finish, to save the new user information.
- Map the SPN to the user account you just created, and then generate a keytab file by running the ktpass command on the domain controller. To run ktpass command you must have Window Support Tools installed (refer to Install Windows Support Tools for more details). Run the ktpass command as follows:
ktpass –princ <SPN> -out <path_to_keytab> -mapuser <account_name> -mapOp set –pass <account_password>
- where you provide values for the following variables:
- <SPN>: The Kerberos SPN for WebSphere Application Server, which is composed of the “WAS/” prefix and the host name of WebSphere Application Server in the cell.
- <path_to_keytab>: File path in which you want to store the generated keytab file.
- <account_name>: The service account name you created in the previous step.
- <account_password>: Password associated with the service account.
8. Merge all the generated keytabs into one keytab file created in the previous steps, using the ktab utility provided in JVM:
<appserver>/java/jre/bin/ktab -m <generated-keytab> <keytab-destination>
9. Once you merge the keytabs, use the klist utility to list the merged keytab file and verify whether all the merged keytab entries are shown in the output.
<appserver>/java/jre/bin/klist -k
10. If you are in a network deployment environment, once you merge the keytab, you must copy the merged keytab file to the same location on all servers in the cell, which will override the original keytab file created in Section 2.2.
Enable WebSphere Application Server for Kerberos (version 7.0 optional)
Beginning in WebSphere Application Server version 7.0, SPNEGO can be used for communications between the Deployment Manager and server nodes in WebSphere Application Server cells. It is a suggested configuration, and is not necessary in all deployments. To do this:
- Log in to the WebSphere Application Server Integrated Solutions Console, if you have a standalone deployment, or the Deployment Manager, if you have a network deployment.
- Expand Security, select Global Security, and click Kerberos configuration in the Authentication section.
- In the Kerberos Authentication Mechanism section, specify the following:
- In the Kerberos service name field, enter WAS as the service name, which is the default value.
- In the Kerberos configuration file with full path field, specify the location of the krb5.conf that was generated in Section 3.1 above.
- Leave the Kerberos keytab file name with full path field blank, to use the default keytab specified in krb5.conf, or specify the location of the keytab file generated in Section 3.6 above.
- Place a check mark in the Trim Kerberos realm from principal name and Enable delegation of Kerberos credentials check boxes.
- In the Kerberos realm name field, specify the Kerberos realm name, for instance IBM.COM. Click OK and Save, to save the changes.
Configuring on Lotus Domino
In this section, we introduce the steps to enable Windows SSO on Windows Domino as well as the Windows SSO solution for non-Windows Domino.
NOTE: Before configuring Windows SSO on Lotus Domino, make sure you have configured SSO based on Ltpa Token. For more details, refer to the wiki article titled, “Configuring single sign-on with an LTPA token on IBM WebSphere and IBM Lotus Domino platforms.”
Enable Windows SSO on Lotus Domino
In Lotus Domino, once you have configured SSO, you can quite easily enable Windows SSO in the Web SSO Configuration document, using these steps:
- In the Domino Directory, select Configuration – Web – Web Configurations.
- Double-click the Web SSO Configuration document, for example, Web SSO Configuration for LtpaToken.
- In the Basic tab, set the Windows single sign-on integration (if available) option to be Enabled.
- Click Save and Close to save the configurations.
Run Domino server with specific account
To successfully validate the Kerberos service tickets, the Domino server must be able to obtain the credential for the SPN generated for the Domino Web service, which means that the Domino server process must be run with the account that holds the SPN.
This is quite different from WebSphere Application Server, which uses a keytab file to hold the credential instead of retrieving it from runtime. There are two ways to achieve this. If your Domino server is registered as a Windows service:
- In Windows, select Start – Control Panel – Administrative Tools – Services.
- In the Windows services list, locate Lotus Domino Server, and double-click it to open the Properties dialog box.
- In the Log on tab, specify the account that was chosen to hold the SPN in the previous steps and the password to that account.
- Click OK to save the change and restart the Domino service.
Mapping Kerberos log-on name to a Notes user (optional)
When configuring Windows SSO on Domino, normally you can opt to use Active Directory as the LDAP service for Domino using Directory Assistance; however, it is not a must. You can also use the Domino directory to map the Kerberos log-on name to a Notes user.
To enable the mapping, perform the following steps:
- In the Domino Directory, select People – By Organization.
- Select the Notes user from the right-hand-side list and click Edit Person.
- On the Administration tab, specify the Active Directory (Kerberos) logon name for this Notes user, in the Client Information section.
- Click Save & Close to save the changes.
- Repeat Steps 1—4 for all users in the Domino Directory who have a Kerberos logon name.
- Create a full-text index for the Domino Directory, to optimize searches of the Active Directory (Kerberos) logon name field.
- Open the Notes.ini file in the Domino data directory and add WIDE_SEARCH_FOR_KERBEROS_NAMES=1 at the end of the configuration file.
Configure Windows SSO for non-Windows Domino (optional)
Due to the mechanism Domino used to retrieve service credentials, Windows SSO only works for Domino on the Windows platform. However, there is an open source project on www.openntf.org that provides a way to configure Windows SSO for non-Windows Domino.
The basic steps include enabling SSO between Windows Domino and non-Windows Domino, redirecting authentication requests to Windows Domino for Windows SSO, and then redirecting the requests back to non-Windows Domino. By this means, non-Windows Domino provides the Windows SSO capability by leveraging the capability on Windows Domino.
You can access the project, “SSO for Web for non Windows Servers,” for detailed information and instructions.
Browser configurations
For successful Windows SSO, users not only need to log in to the Active Directory domain but also need to enable the Windows SSO feature on their browsers. Below are the configuration instructions for both Microsoft Internet Explorer and Mozilla Firefox.
Microsoft Internet Explorer
- From the Internet Explorer menu, select Tools – Internet Options, and then click the Security tab.
- Click the Local intranet icon, and then click Sites.
- Click Advanced, and then add the Web address of the host name of your Web applications –- typically the host name of HTTP server -– into the Add this website to the zone field. For example, *.enterprise.example.com.
- Click OK to save the change and return to the main Security page.
- Click Custom level, scroll to find User Authentication – Logon, and then select Automatic logon only in Intranet zone. Click OK to save the change and return to the main Security page.
- On the Advanced tab, scroll to find Security, and then select Enable Integrated Windows Authentication. Click OK to save the change.
- Restart the Web browser to apply the configuration changes.
Mozilla Firefox
Use the following steps to add the Web address of your Web application to the list of sites that are permitted to engage in SPNEGO authentication with the browser:
- Open Firefox, and then type about:config in the location bar.
- Type network.n into the Filter field, double-click network.negotiate-auth.trusted-uris, and then type the protocol and host name of the server that hosts your Web application. For example, http://enterprise.example.com, or https://enterprise.example.com, if you want to use HTTPS. To specify more than one server, separate them with a comma.
- Click OK to save the change.
- If the deployed SPNEGO solution is using the advanced Kerberos feature of Credential Delegation, double-click network.negotiate-auth.delegation-uris. This preference defines the sites for which the browser can delegate user authorization to the server. Enter a comma-delimited list of trusted domains or URLs.
- Restart Firefox to apply the configuration change.
Conclusion
In this article we introduced the Windows SSO configurations on both WebSphere Application Server and Lotus Domino. The configurations include the common steps for Kerberos of time synchronization and SPN registration, and the platform-specific configurations owing to the different approaches that WebSphere and Lotus Domino use SPN credentials.
For WebSphere, the keytab file and krb5.conf file are used to enable JVM with Kerberos capabilities, and for Lotus Domino, the Domino server is run with the account under which the SPN is registered. Also included were some optional configurations that might be helpful to fulfill the requirements in your specific deployment. To incorporate with the Web server, we also provided the client browser configurations for successful Windows SSO.
Streamlining passwords and achieving SSO for users on Windows platforms
This article provides in-depth configuration settings for leveraging Active Directory to authenticate users, allowing elimination of Domino Internet passwords for users on Windows platform. This configuration is useful for Web only users, as well as for users who also access Domino with Notes. These settings can be used in combination with the 8.5.1 Notes shared login feature that eliminates the user's Notes password.
Single sign-on (SSO) can mean many things, but in general the goal is to reduce the number of password prompts that users must respond to. From an administrative standpoint, the goal also includes reducing the number of passwords required for users to remember, since fewer password problems will result in fewer help desk calls and lower administrative cost. In IBM Lotus Notes and Domino products, we have a variety of features which can be used together to reduce administration cost. Customers on Microsoft® Windows® platforms can take advantage of SSO features including Notes shared login, and Windows single sign-on for Web clients. For your users who are both Notes users as well as Domino Web users, you can achieve SSO and reduce administrative cost by eliminating both Notes passwords and Domino Internet passwords. For any authentication scenarios requiring password verification, you can choose to rely on Microsoft Windows Active Directory passwords already in place for all Windows users.
Eliminating Notes passwords vs. synchronizing passwords
When using Notes on Windows, the Notes shared login feature in release 8.5.1 allows users to start Notes without having to provide a Notes password. Users only need to log in to Windows using their Windows password. In this scenario, the important password for the user to remember and manage is the Windows password.
Many customers want their users to deal with the Windows password only, and historically may have deployed the old Notes 'single logon' feature that synchronized the Windows password with the Notes password, while optionally also synchronizing the Domino Internet password (if configured in the user's security policy). While it previously made sense to try to keep the three passwords (Windows, Notes, and Domino Internet password) in synch, the 8.5.1 Notes shared login feature effectively eliminates the Notes password so that there isn't a Notes password to keep synchronized with a Windows password. This is good news! Now you don't need password synchronization, which often is an administrative headache!
If your goal is to streamline the number of passwords, we recommend the Notes shared login feature that eliminates Notes passwords. Additionally you can eliminate Domino Internet passwords, so that there is no further need to synchronize any password with Windows. You can set up Web users to be authenticated directly against the Windows password managed in Microsoft Active Directory, which is described below.
This article does not cover the Notes shared login configuration itself, or Notes ID vault which can conveniently be used in conjunction to manage id synchronization and id backup. If you are deploying Notes shared login to eliminate Notes passwords, see instructions here: Using Notes shared login to eliminate Notes password prompts at the IBM Lotus Notes and Domino Information Center.
Eliminating Domino Internet passwords
The Domino 8.5.1 release included Windows single sign-on for Web clients. This feature allows a Web user to access Domino resources without providing an Internet password. The underlying technology does not use the Windows password per se, but rather leverages the user's Windows operating system login (i.e. Kerberos security) credentials. The result is that a logged in Windows user is not challenged for a password when browsing to Domino on the Web. Windows single sign-on for Web clients is targeted to your Domino server on the Windows platform. Where Windows single sign-on is operational, the Domino Internet password is unused.
Independent of whether you deploy Windows single sign-on for Web clients (or any other Domino Multi-server session authentication SSO feature), it is important to note that passwords are still needed in some Web scenarios. The Windows single sign-on for Web clients feature eliminates the need for a Domino password only for intranet access scenarios. In order to leverage the user's Windows Kerberos security credentials, the Windows single sign-on feature requires that the user's Windows machine can directly interface with the Windows domain controller. Windows single sign-on cannot be used in Internet scenarios (e.g. user login to Domino across a firewall), and obviously not in cases where a Domino server does not offer the Windows single sign-on feature, therefore in some scenarios a Web user needs to supply a password. If you prefer the user to supply the Windows password rather than a Domino Internet password, you can set up Web users to be authenticated directly against the Windows password managed in Active Directory (see below).
This article does not cover all instructions to configure Web SSO for Domino, or the Windows single sign-on for Web clients feature. See instructions here in the Notes/Domino Information Center: Setting up Windows single sign-on for Web clients
Leveraging Active Directory to authenticate users
If you prefer a Web user to supply the Windows password rather than a Domino Internet password, you can set up Web users to be authenticated directly against the Windows password managed in Microsoft Active Directory. This configuration requires setting up Directory Assistance to Active Directory, as well as an appropriate supporting directory configuration.
The configuration ensures that a user's directory record is found in Active Directory in order that the Active Directory password information can be used to authenticate the user. Also the configuration must ensure that the user's Active Directory record is associated with any corresponding Person record found for the user in Domino Directory. While the user can be authenticated against the Active Directory password, the association between Active Directory and Domino Directory allows the user's name to be mapped to the Notes name found on Domino database ACLs (Access Control Lists). To enable the user's successful authorization to access Domino resources, the Domino server must recognize the user according to the Notes name contained on the Domino ACL.
Usually the Domino server would be configured for Multi-server session authentication SSO, but SSO is not strictly required.
Follow the steps below to manage Web user authentication in Active Directory and eliminate Domino Internet passwords. This configuration requires you to add users' Notes distinguished names to Active Directory user accounts.
Step 1
The Domino server must be configured to use a directory assistance database. In the directory assistance database, create an LDAP directory assistance document to use to connect to the Active Directory server. The following table describes some of the most important fields to configure in the LDAP directory assistance document.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| |
|
|
|
|
- If Multi-server session authentication (SSO) is deployed for Web access to your Domino server, you will also need to consider the following item in the LDAP directory assistance document:
- Required only if there is an IBM SSO server authenticating users against Active Directory so that users' LTPA tokens contain their Active Directory names.
- Requires "Map names in LTPA token" to be enabled in the Web SSO Configuration document.
|
|
|
|
|
|
| |
- For use within the intranet, if Windows Single Sign-on for Web clients is being deployed as a Multi-server session authentication (SSO) option on your Domino web server, the following items in the LDAP directory assistance document should also be configured:
- Enables efficient name lookups based on users' Active Directory logon (Kerberos) names. In combination with "Attribute to be used as Notes Distinguished Name", allows the user's Kerberos identity to be associated with the Domino name.
- Specify in upper case characters, for example, AD.ACME.COM.
|
|
|
|
|
|
| |
|
|
| |
Step 2
If a user has a Person document in the Domino Directory, make the following edits to the Person document to set up for authenticating the user for Internet access using the Active Directory password. Person documents are optional for Web users who are not LotusiNotes users.
|
|
|
|
|
|
|
|
|
|
|
|
Step 3
If a user has a Domino Person document but you have removed the Domino Internet password, disable the following Internet password settings in users' effective Security Settings policy document:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Step 4
Specify the following setting in the Server documents of participating Domino servers:
|
|
|
|
|
|
|
|
Step 5
If Multi-server session authentication (SSO) is deployed for Web access, additional configuration is needed in the Domino Directory Web SSO Configuration document. If the SSO servers are authenticating users against Active Directory, specify the following setting in the Web SSO Configuration document:
|
|
|
|
|
|
|
|
Monday, November 28, 2011
Quick guide to setting up SSL using Domino as the Certificate Authority
Question
What steps can you follow to set up SSL on a Lotus® Domino® server using Domino as the Certificate Authority? Is there a quick guide other than the detailed steps in the Lotus Domino Administrator help?
Answer
Below are the steps to configure SSL on a Lotus Domino server using Domino as the Certificate Authority (CA). This method takes advantage of the Domino CA's keyring form that automatically creates the server key ring and the server certificate request, signs it with the CA certificate, then installs the CA certificate and the signed server certificate into the server key ring. For detailed steps and information, refer to the Domino Administrator Help section "Using a Domino 5 certificate authority."
Note: This method of configuring SSL does not use the server task called the CA Process. For information on that method of configuring SSL, which was introduced in Domino 6, refer to "Quick guide to securing a Domino server with SSL using the CA process" (#1193730).
Steps to create the files:
1. Create the Domino Certificate Authority database from the Domino R5 Certificate Authority (cca50.ntf) template if needed.
2. Open the Certificate Authority database (from the Domino Administrator, click Files, and open the Domino Certificate Authority application). Select the first option "1. Create Certificate Authority Key Ring & Certificate."
3. Fill in the required fields on the form to create the key ring file for your Certificate Authority. Enter a unique name for the Common Name field of the form to identify the Certificate Authority.
Picture of Key Ring form
![](https://www-304.ibm.com/support/docview.wss?uid=swg21114148&aid=2)
4. Click the button "Create Certificate Authority Key Ring." This creates a key ring file (by default named CAkey.kyr) for the Domino Certificate Authority.
5. From the main menu, select "2. Configure Certificate Authority Profile" to set a profile for the Certificate Authority. Most of the information on this page does not need to change, and the fields that are blank are optional and can be left blank if desired. Be sure that the caKey.kyr (or the name entered on for the Key Ring File Name in Step 3) is listed at the top. The last entry, "Default validity period", has a default value of 2 years. The maximum for this is 10, but the validity period defined must result in an end date earlier than the validity date of the Certificate Authority's key ring itself. Verify the information on the page is correct, then click Save and Close.
6. From the main menu, select the third option, "3. Create Server Key Ring & Certificate." You also start from this option when you want to make an additional server's key ring.
7. Fill in the required fields on the Create CA Server Key Ring form. Be sure to enter the fully qualified host name in the "Common Name" field. This host name should be identical to the name Web users will be entering to access the server.
The CA Certificate Label field should be "CAKeyPair" if you initially used "1. Create Certificate Authority Key Ring & Certificate."
(Note: You use this form to create any subsequent key ring files for other servers that need SSL enabled.) Picture of the Server Key Ring form
![](https://www-304.ibm.com/support/docview.wss?uid=swg21114148&aid=3)
8. Once the form is complete, select "Create Server Key Ring." Domino then creates the server key ring (by default keyfile.kyr), creates the server certificate request, signs it with the CA certificate, then installs the CA certificate and the signed server certificate into the server key ring.
9. Copy the key ring files (by default named keyfile.kyr and keyfile.sth) to the Data directory of the Domino server on which you wish to enable SSL. You can find these files in the data directory of the Notes client that you used to create them.
Steps to configure SSL on the server:
1. Verify that the key ring files created previously are in the Data directory of the Domino server.
2. Open the Server document for this server. Go to the Ports -> Internet Ports tab.
3. If necessary, change the entry in the SSL key file name field to reflect the name of the server key ring file.
4. Make sure that SSL port status is set to enabled. Optionally, to force SSL to be used for all connections, change "TCP/IP Port Status" to "Redirect to SSL."
5. Save and close the Server document.
6. Restart the HTTP task at the server console.
Steps for Web browser (optional):
Because you are using a private Certificate Authority, in some cases when a Web browser user access the server using HTTPS, the user might see the following warning message:
Picture of complete warning message
![](https://www-304.ibm.com/support/docview.wss?uid=swg21114148&aid=4)
To resolve this warning, you have to trust the Certificate Authority. Once you have trusted the Certificate Authority into your browser, the security check is cleared and any subsequent access does not result in a security alert.
1. To trust the Domino Certificate Authority, open the Certificate Authority database in your Web browser.
2. Select "Accept This Authority In Your Browser" and follow the on-screen steps to install the trusted root into your browser.
Or you can execute steps in the Web browser to accept the certificate. Steps for commonly used Web browsers are provide below.
For Microsoft Internet Explorer 6:
1. Click "View Certificate"
2. Click "Install Certificate"
3. Follow the on-screen prompts
For Microsoft Internet Explorer 7:
The warning message that appears is "There is a problem with this website's security certificate."
1. In the warning message, click "Continue to this website"
2. In the next window, click the Certificate Error next to the address bar to launch a pop-up dialog in which you click "View Certificates"
3. Click on the "Certification Path" tab, and select the top-most entry, which should have red X. Then click "View Certificate"
4. Click "Install Certificate"
5. Follow the on-screen prompts in the installation wizard
For Firefox:
1. Click "Accept this certificate permanently"
2. Click Ok
Note: This method of configuring SSL does not use the server task called the CA Process. For information on that method of configuring SSL, which was introduced in Domino 6, refer to "Quick guide to securing a Domino server with SSL using the CA process" (#1193730).
Steps to create the files:
1. Create the Domino Certificate Authority database from the Domino R5 Certificate Authority (cca50.ntf) template if needed.
2. Open the Certificate Authority database (from the Domino Administrator, click Files, and open the Domino Certificate Authority application). Select the first option "1. Create Certificate Authority Key Ring & Certificate."
- Picture of Setup options:
3. Fill in the required fields on the form to create the key ring file for your Certificate Authority. Enter a unique name for the Common Name field of the form to identify the Certificate Authority.
Picture of Key Ring form
4. Click the button "Create Certificate Authority Key Ring." This creates a key ring file (by default named CAkey.kyr) for the Domino Certificate Authority.
5. From the main menu, select "2. Configure Certificate Authority Profile" to set a profile for the Certificate Authority. Most of the information on this page does not need to change, and the fields that are blank are optional and can be left blank if desired. Be sure that the caKey.kyr (or the name entered on for the Key Ring File Name in Step 3) is listed at the top. The last entry, "Default validity period", has a default value of 2 years. The maximum for this is 10, but the validity period defined must result in an end date earlier than the validity date of the Certificate Authority's key ring itself. Verify the information on the page is correct, then click Save and Close.
6. From the main menu, select the third option, "3. Create Server Key Ring & Certificate." You also start from this option when you want to make an additional server's key ring.
7. Fill in the required fields on the Create CA Server Key Ring form. Be sure to enter the fully qualified host name in the "Common Name" field. This host name should be identical to the name Web users will be entering to access the server.
The CA Certificate Label field should be "CAKeyPair" if you initially used "1. Create Certificate Authority Key Ring & Certificate."
(Note: You use this form to create any subsequent key ring files for other servers that need SSL enabled.) Picture of the Server Key Ring form
8. Once the form is complete, select "Create Server Key Ring." Domino then creates the server key ring (by default keyfile.kyr), creates the server certificate request, signs it with the CA certificate, then installs the CA certificate and the signed server certificate into the server key ring.
9. Copy the key ring files (by default named keyfile.kyr and keyfile.sth) to the Data directory of the Domino server on which you wish to enable SSL. You can find these files in the data directory of the Notes client that you used to create them.
Steps to configure SSL on the server:
1. Verify that the key ring files created previously are in the Data directory of the Domino server.
2. Open the Server document for this server. Go to the Ports -> Internet Ports tab.
3. If necessary, change the entry in the SSL key file name field to reflect the name of the server key ring file.
4. Make sure that SSL port status is set to enabled. Optionally, to force SSL to be used for all connections, change "TCP/IP Port Status" to "Redirect to SSL."
5. Save and close the Server document.
6. Restart the HTTP task at the server console.
Steps for Web browser (optional):
Because you are using a private Certificate Authority, in some cases when a Web browser user access the server using HTTPS, the user might see the following warning message:
- "The security certificate was issued by a company you have not chosen to trust..."
Picture of complete warning message
To resolve this warning, you have to trust the Certificate Authority. Once you have trusted the Certificate Authority into your browser, the security check is cleared and any subsequent access does not result in a security alert.
1. To trust the Domino Certificate Authority, open the Certificate Authority database in your Web browser.
2. Select "Accept This Authority In Your Browser" and follow the on-screen steps to install the trusted root into your browser.
Or you can execute steps in the Web browser to accept the certificate. Steps for commonly used Web browsers are provide below.
For Microsoft Internet Explorer 6:
1. Click "View Certificate"
2. Click "Install Certificate"
3. Follow the on-screen prompts
For Microsoft Internet Explorer 7:
The warning message that appears is "There is a problem with this website's security certificate."
1. In the warning message, click "Continue to this website"
2. In the next window, click the Certificate Error next to the address bar to launch a pop-up dialog in which you click "View Certificates"
3. Click on the "Certification Path" tab, and select the top-most entry, which should have red X. Then click "View Certificate"
4. Click "Install Certificate"
5. Follow the on-screen prompts in the installation wizard
For Firefox:
1. Click "Accept this certificate permanently"
2. Click Ok
ibm.com
Friday, November 25, 2011
Lotus Domino SSL Certificates Installation
SSL Certificate Installation in Lotus Domino
Note: Installing SSL Certificates on Lotus Domino Web Server requires that the Certificate files be merged into the same Key Ring that was used to generate the CSR. If you do not have this Key Ring then you will need to have a new certificate issued with a new CSR from a new Key Ring. The certificates must be installed to the Key Ring in the correct order (see example of order below):
TrustedRoot.crtDigiCertCA2.crt (if included in your zip file)
DigiCertCA.crt
your_domain_name.crt
- Open Domino Server Certificate Administration (CERTSRV.NSF). This is in the System Databases in the administration panel of Notes.
- Choose "Install Trusted Root Certificate into Key Ring". Enter the file name of the key ring that was made when you created your CSR, then install the Trusted Root Certificate (TrustedRoot.crt). You may get a message that the root certificate is already installed as a trusted root. If you receive this message continue to step 3.
- Again choose "Install Trusted Root Certificate into Key Ring". Enter the file name of the key ring, then install your Intermediate Certificate(s). If your zip file includes DigiCertCA2.crt, install that file first, and then install repeat this process and install DigiCertCA.crt next to this same location. Otherwise, you only need to install the DigiCertCA.crt file here.
- This time choose "Install Certificate into Key Ring". Enter the file name of the Key Ring, then install your Primary Certificate (your_domain_name.crt) using the "Merge Certificate into Key Ring" button.
Your SSL Certificate now installed to your Key Ring and it is ready for use on your Lotus Domino Server.
http://www.digicert.com
Saturday, November 19, 2011
DAOS Backup and Restore
Table of Contents
This article describes how to refine your backup and restore procedures when using the popular Domino Attachment and Object Service (DAOS) feature, also known as "attachment consolidation."
In a standard Notes® database (NSF), the attachments are stored inside of the NSF file itself, and the database is self-contained. In order to back up a standard Notes database, only the NSF file itself needs to be backed up. After you introduce DAOS, the NSFs that participate in DAOS contain only references to the NLO files where the attachment content is stored. As a result, backing up the NSF alone is no longer enough. The NLO data needs to be backed up as well.
When performing standard NSF backups, there are two main approaches. The individual NSF being backed up can be taken offline (or the entire server can be stopped) so that no changes occur to the NSF over the duration of the backup operation. The other method allows the NSF and server to remain active, but requires using a backup utility program that interacts with the Domino® backup/restore API. Using a utility ensures that a consistent copy of the NSF contents is recorded, despite any changes that occur to the NSF over the duration of the backup operation. If you are using a backup utility that does not use the backup/restore API, you must stop the Domino server and all Domino-related applications for the duration of the backup.
None of the processing for NSF backups needs to change for DAOS. The change needed to accommodate DAOS is simply a procedural addition: in addition to backing up the NSF data, you must also back up the NLO data.
Backing up the NLO files in the DAOS repository can be done either while the Domino server is down, or when it is up and running. The backup does not require the use of any Domino API-based utilities. Once NLO files are written initially, Domino never modifies their contents, so the backup mechanism does not have to work around file-write activity. NLO files can be backed up as any other generic file on the file system. Only the NLO files that are complete and not in the process of being written to or renamed need to be backed up. Any that are busy can be skipped until the next backup. Most backup applications will automatically skip files that they can not read because of other activity.
If you shut down the Domino server during the backup process, the NSF and NLO files can be backed up in any order. If you must keep the Domino server up and running during the backup process, it is important to back up all the NSF data before backing up the NLO files. The reason has to do with the addition of references to new NLO files in an active system, described in this section.
When you back up an NSF that participates in DAOS, there are some number of NLO references contained in that NSF at the time of the backup. Since there is some duration to the backup operation for all NSFs, the number of references to NLO files may be increasing over that duration in a system that is operating during the backup process. If there were (for example) 10,000 NLO files referenced collectively by all the NSFs at the beginning of the NSF backup process, there could be 10,100 by the time the last NSF is backed up.
Likewise, the backup of the NLO data has a duration as well, so while there might have been 10,100 NLO files at the beginning of the NLO backup process, there could be 10,200 by the time the last NLO is backed up.
In this scenario, the backed up version of the NSFs could reference at most only 10,100 NLO files. Because the NLO backup was done after the NSF backup process, the NLO backup included at least that many, but may have as many as 10,200 NLO files. Worst case, there are more NLO files backed up than strictly necessary to satisfy the NSF references. Since all accesses to the NLO files are done through the NSFs, and the NSFs were done first, all of the referenced NLO files are guaranteed to exist in the set of NLO files that were backed up. If there is an error accessing an NLO file in order to back it up because it's in use, that can safely be ignored. If the file is being written, the activity must have occurred after the NSF was backed up; therefore, this NLO file does not need to be in the corresponding set of NLO files, and will be backed up as part of the next cycle.
The deferred deletion interval should be set to a period longer than your chosen backup cycle. In this way, the NLOs are not pruned (physically deleted) prior to the next backup. Instead, the actual deletion is deferred until they've aged accordingly.
If you were to have a shorter or nonexistent deletion interval—the feature can be disabled by setting it to zero in the DAOS tab of the server document—it opens a window of time during which a deleted attachment is non-recoverable, as the NLO file has been physically deleted before the backup has occurred.
Avoid pruning NLO files from the repository (by issuing a prune command at the Domino console) before they have had a chance to be backed up; you will prevent them from being recoverable. When an attachment is deleted, and the associated NLO file's reference count goes to zero, it becomes a candidate for deletion. The deferred deletion interval determines when the deletion actually occurs. If the deferred deletion interval is set (as recommended) to be longer than the backup cycle, all NLOs will be in existence for at least one backup cycle, and therefore any NLO can be recovered later.
After the initial full backup of the NLO files in the DAOS repository, you can perform incremental backups, which save only the data that has changed since the last backup. NLO files are ideal candidates for incremental backup because there are no changes to them after their initial creation.
One NLO file is created for each unique attachment, so it is possible to have a very large number of NLO files in large deployments. The maximum number of files per numbered DAOS subdirectory is 40,000, and there can be 1000 subdirectories, for a maximum total of 40 million NLO files. Check with your backup utility specifications to see if there is a limit on the total number of files it will manage, and monitor the growth of the DAOS directory file population accordingly.
The daos.cfg and daoscat.nsf files should not be backed up. (Note that this is a change from earlier recommendations) These two index files can be re-created from the DAOS repository and the NSFs participating in DAOS if necessary. If these files become corrupted, they can be safely deleted while Domino is not running. They will be created on startup automatically.
The daos.cfg file helps manage the files in the DAOS repository. The NLO files are stored in subdirectories (0001, 0002, and so forth) underneath the base DAOS directory. For several reasons (including performance), DAOS limits the number of NLO files in each subdirectory. The daos.cfg file keeps track of how many files are currently in each subdirectory so that DAOS puts new files in subdirectories where the count of files is below that limit. As NLOs are deleted, the corresponding file count is decremented, allowing backfilling of older subdirectories. The daos.cfg file is expendable, and will be re-created at Domino startup time if it is missing.
The daoscat.nsf file contains two indexes. One is a list of all NSFs that are holding NLO references (DAOS ID Table, or DIT.) The second is a list of all NLOs that exist, and the DAOS repository subdirectory they exist in (DAOS Object Index, or DOI). There are no externally visible parts to this NSF, and there are no privileges that apply to change that. The DIT is modified when an NSF acquires its first NLO reference. The DOI is modified when a new (unique) NLO is created. The daoscat.nsf file is expendable, and will be re-created at Domino startup time if it is missing. Since a full resync can take a significant amount of time, only empty indexes are created by this process at startup. A resync operation should be done as soon as it is convenient, however.
In some cases it could be necessary to fully reboot the server until the daoscat.nsf and the daos.cfg are re-created.
A DAOS resync operation (“tell daosmgr resync”) fully re-populates these two indexes from scratch. You can also run the command “[n]daosmgr resync”if you want to perform a resync operation with the Domino server shut down.
Because all NSFs that participate in DAOS have to also participate in transaction logging, the contents of all their attachments will be included in the log. Any NLO files that are created as a result of activity to the NSF will be re-created if the log is replayed.
Using the Tivoli Storage Manager (TSM), the command to back up the DAOS repository would be:
where the path specified is the full one to the DAOS repository.
Since the NLO files are being backed up incrementally, the initial backup will be quite large, but subsequent ones will be much smaller. The total footprint of the DAOS directory will be written out during the first backup.
Once a Domino server has DAOS enabled, and NSFs are selected to participate in DAOS, their attachments are stored in the DAOS repository. If DAOS is subsequently disabled, the attachments that were in DAOS remain in DAOS until they are re-integrated into the NSF. Any DAOS references that remain in the NSF will continue to be serviced by DAOS, even if it is disabled. An NSF that contains DAOS references is not self-contained, and must continue to be treated as an active DAOS participant as long as it has DAOS references. To re-integrate the DAOS attachments into an NSF and remove the DAOS references, you can process the NSF with the “compact -c -daos off” command. Once that is done, the NSF will be self-contained again, and can be treated as a normal NSF.
Furthermore, to ensure that the DAOS enablement change takes effect completely, the Domino server as well as all processes that use the Domino API (compact, resync, backup, etc) are stopped. This allows the API to terminate completely, so the status change can be picked up at the next startup.
The disk footprint savings with DAOS continues into the backup processing as well. The NLO files represent the static data that used to reside in the NSF, and was backed up every cycle even though it hadn't changed. In a typical mail environment, a large reduction in the NSF footprint plus a very small amount of NLO data means the reduction in the NSF footprint translates almost directly into a reduction in the backup footprint. Not only is the duplicate data being eliminated, the mailfile data is being separated into static and dynamic components. By applying an incremental backup regimen to the static (NLO) data, only the NLO files created since the last backup cycle need to be processed. That represents typically a very small amount of data compared with the entire set of NLO files.
Using DAOS enables backup software solutions to optimally backup the NLO files. This is because once an NLO is written to disk, it never changes. Therefore, the file need only be backed up once in its lifetime. Based on the example shown in the DAOS Estimator document [link], the space saving per full backup would be 38.8 GB, roughly equal to the number of shared NLO's times the average NLO size.
In the incremental backup case, duplicate NLO's will not be backup up again. Thus, the space savings from DAOS is directly proportional to the numbe r of duplicate NLO's seen in the environment, and the backup time savings is the product of the space saved and the backup throughput.
A well-preserved DAOS repository makes for fast and easy restoration. And, while not really a backup mechanism, the default deferred deletion interval allows for accidentally deleted attachments to be saved from physical deletion up to 30 days after a mishap. Simply pull the document out of the trash folder, if soft deletion is enabled. If it's too late for that, restore from backup, then resynchronize the DAOS catalog using the server console command "tell daosmgr resync force" -- DAOS will once again recognize that the NLO has references.
Although an NLO will survive for the period of time specified by the deferred deletion interval, if soft deletion is disabled or a backup of the referencing document has not been made, there is no way to get at the contents of the NLO, especially if encryption is enabled (the default).
To restore either a full NSF or a single document, the process starts off the same. You must first restore the database and then the missing NLOs. To do this using Tivoli Data Protection for Domino, you would issue the command:
To determine which missing NLO files to bring back from the Domino server console, run
The resulting missing.txt file is then fed into the restore command With the Tivoli Storage Manager (TSM), the command would be
If you are restoring the entire NSF, you are done. Note that any restoration operation will put the DAOS catalog into the Needs Resync state, so a resync operation should be performed as soon as convenient.
If you need only one document, you can now copy and paste it to its intended destination.
For a complete recovery after a catastrophic failure, the NSF and NLO files can be restored, followed by replaying the archived transaction logs. This will result in the most up-to-date recovery situation.
If an NSF is damaged, and you have clustered servers or replicas of the NSF on another server, you have several options.
The need for restoring NLO files depends partly on the deferred deletion interval. If the restore is happening from a snapshot that's within the interval (for example, the interval is 30 days, and the NSF is being restored from last week's backup) it's not possible for any of the NLOs to have been deleted yet, so there shouldn't be a need to restore any NLOs. If the NSF being restored is older than the interval (for example, the interval is 30 days, but the NSF being restored is from 3 months ago), it's possible that some of the NLOs have been deleted, and would need to be restored.
Some of this also depends on what the reason for the restore is. If it's a catastrophic failure, you should restore the NSF(s) and run 'tell daosmgr listnlo missing filename.nsf' to get a list of all of the NLOs needed to make it whole again. That list should then be fed into the restore utility to restore those NLOs as well.
If it's just a matter of getting a single document with attachments back, you don't really need everything to be made whole to access just that one set of attachments. In the spirit of “Work smarter not harder,” you can restore the NSF, and then attempt to access the desired document (and attachments, if any) and finally deal with any missing NLOs that are mentioned during that operation. If there aren't any attachments on the document, there's no other work to be done. If there are attachments, the NLOs may still be there, so it's worth trying to access them before doing anything else. If any are missing, you'll get a console message that mentions the name of the NLO, at which point you can restore only what you need.
For offline archival purposes, it is recommended that the attachments be re-integrated into the NSF using a 'compact -c -daos off' operation prior to archiving. That eliminates the need to archive all the individual NLO files referred to by the NSF also. For example, if an employee was leaving the company, and their mail account was being closed and archived, this approach would be appropriate.
- 1 Backup considerations for DAOS
- 2 Order matters
- 3 DAOS index files
- 4 Transaction logging
- 5 Command examples
- 6 DAOS enable and disable considerations
- 7 Space and time savings
- 8 Restoring DAOS objects
- 9 Restoring documents or NSF files with DAOS attachments
- 10 Dealing with damaged files and clusters
- 11 Options for restoration
- 12 Offline archival
This article describes how to refine your backup and restore procedures when using the popular Domino Attachment and Object Service (DAOS) feature, also known as "attachment consolidation."
Backup considerations for DAOS
In a standard Notes® database (NSF), the attachments are stored inside of the NSF file itself, and the database is self-contained. In order to back up a standard Notes database, only the NSF file itself needs to be backed up. After you introduce DAOS, the NSFs that participate in DAOS contain only references to the NLO files where the attachment content is stored. As a result, backing up the NSF alone is no longer enough. The NLO data needs to be backed up as well.
When performing standard NSF backups, there are two main approaches. The individual NSF being backed up can be taken offline (or the entire server can be stopped) so that no changes occur to the NSF over the duration of the backup operation. The other method allows the NSF and server to remain active, but requires using a backup utility program that interacts with the Domino® backup/restore API. Using a utility ensures that a consistent copy of the NSF contents is recorded, despite any changes that occur to the NSF over the duration of the backup operation. If you are using a backup utility that does not use the backup/restore API, you must stop the Domino server and all Domino-related applications for the duration of the backup.
None of the processing for NSF backups needs to change for DAOS. The change needed to accommodate DAOS is simply a procedural addition: in addition to backing up the NSF data, you must also back up the NLO data.
Backing up the NLO files in the DAOS repository can be done either while the Domino server is down, or when it is up and running. The backup does not require the use of any Domino API-based utilities. Once NLO files are written initially, Domino never modifies their contents, so the backup mechanism does not have to work around file-write activity. NLO files can be backed up as any other generic file on the file system. Only the NLO files that are complete and not in the process of being written to or renamed need to be backed up. Any that are busy can be skipped until the next backup. Most backup applications will automatically skip files that they can not read because of other activity.
Order matters
If you shut down the Domino server during the backup process, the NSF and NLO files can be backed up in any order. If you must keep the Domino server up and running during the backup process, it is important to back up all the NSF data before backing up the NLO files. The reason has to do with the addition of references to new NLO files in an active system, described in this section.
When you back up an NSF that participates in DAOS, there are some number of NLO references contained in that NSF at the time of the backup. Since there is some duration to the backup operation for all NSFs, the number of references to NLO files may be increasing over that duration in a system that is operating during the backup process. If there were (for example) 10,000 NLO files referenced collectively by all the NSFs at the beginning of the NSF backup process, there could be 10,100 by the time the last NSF is backed up.
Likewise, the backup of the NLO data has a duration as well, so while there might have been 10,100 NLO files at the beginning of the NLO backup process, there could be 10,200 by the time the last NLO is backed up.
In this scenario, the backed up version of the NSFs could reference at most only 10,100 NLO files. Because the NLO backup was done after the NSF backup process, the NLO backup included at least that many, but may have as many as 10,200 NLO files. Worst case, there are more NLO files backed up than strictly necessary to satisfy the NSF references. Since all accesses to the NLO files are done through the NSFs, and the NSFs were done first, all of the referenced NLO files are guaranteed to exist in the set of NLO files that were backed up. If there is an error accessing an NLO file in order to back it up because it's in use, that can safely be ignored. If the file is being written, the activity must have occurred after the NSF was backed up; therefore, this NLO file does not need to be in the corresponding set of NLO files, and will be backed up as part of the next cycle.
The deferred deletion interval should be set to a period longer than your chosen backup cycle. In this way, the NLOs are not pruned (physically deleted) prior to the next backup. Instead, the actual deletion is deferred until they've aged accordingly.
If you were to have a shorter or nonexistent deletion interval—the feature can be disabled by setting it to zero in the DAOS tab of the server document—it opens a window of time during which a deleted attachment is non-recoverable, as the NLO file has been physically deleted before the backup has occurred.
Avoid pruning NLO files from the repository (by issuing a prune command at the Domino console) before they have had a chance to be backed up; you will prevent them from being recoverable. When an attachment is deleted, and the associated NLO file's reference count goes to zero, it becomes a candidate for deletion. The deferred deletion interval determines when the deletion actually occurs. If the deferred deletion interval is set (as recommended) to be longer than the backup cycle, all NLOs will be in existence for at least one backup cycle, and therefore any NLO can be recovered later.
After the initial full backup of the NLO files in the DAOS repository, you can perform incremental backups, which save only the data that has changed since the last backup. NLO files are ideal candidates for incremental backup because there are no changes to them after their initial creation.
One NLO file is created for each unique attachment, so it is possible to have a very large number of NLO files in large deployments. The maximum number of files per numbered DAOS subdirectory is 40,000, and there can be 1000 subdirectories, for a maximum total of 40 million NLO files. Check with your backup utility specifications to see if there is a limit on the total number of files it will manage, and monitor the growth of the DAOS directory file population accordingly.
DAOS index files
The daos.cfg and daoscat.nsf files should not be backed up. (Note that this is a change from earlier recommendations) These two index files can be re-created from the DAOS repository and the NSFs participating in DAOS if necessary. If these files become corrupted, they can be safely deleted while Domino is not running. They will be created on startup automatically.
The daos.cfg file helps manage the files in the DAOS repository. The NLO files are stored in subdirectories (0001, 0002, and so forth) underneath the base DAOS directory. For several reasons (including performance), DAOS limits the number of NLO files in each subdirectory. The daos.cfg file keeps track of how many files are currently in each subdirectory so that DAOS puts new files in subdirectories where the count of files is below that limit. As NLOs are deleted, the corresponding file count is decremented, allowing backfilling of older subdirectories. The daos.cfg file is expendable, and will be re-created at Domino startup time if it is missing.
The daoscat.nsf file contains two indexes. One is a list of all NSFs that are holding NLO references (DAOS ID Table, or DIT.) The second is a list of all NLOs that exist, and the DAOS repository subdirectory they exist in (DAOS Object Index, or DOI). There are no externally visible parts to this NSF, and there are no privileges that apply to change that. The DIT is modified when an NSF acquires its first NLO reference. The DOI is modified when a new (unique) NLO is created. The daoscat.nsf file is expendable, and will be re-created at Domino startup time if it is missing. Since a full resync can take a significant amount of time, only empty indexes are created by this process at startup. A resync operation should be done as soon as it is convenient, however.
In some cases it could be necessary to fully reboot the server until the daoscat.nsf and the daos.cfg are re-created.
A DAOS resync operation (“tell daosmgr resync”) fully re-populates these two indexes from scratch. You can also run the command “[n]daosmgr resync”if you want to perform a resync operation with the Domino server shut down.
Transaction logging
Because all NSFs that participate in DAOS have to also participate in transaction logging, the contents of all their attachments will be included in the log. Any NLO files that are created as a result of activity to the NSF will be re-created if the log is replayed.
Command examples
Using the Tivoli Storage Manager (TSM), the command to back up the DAOS repository would be:
dsmc incremental c:\lotus\domino\data\daos
where the path specified is the full one to the DAOS repository.
Since the NLO files are being backed up incrementally, the initial backup will be quite large, but subsequent ones will be much smaller. The total footprint of the DAOS directory will be written out during the first backup.
DAOS enable and disable considerations
Once a Domino server has DAOS enabled, and NSFs are selected to participate in DAOS, their attachments are stored in the DAOS repository. If DAOS is subsequently disabled, the attachments that were in DAOS remain in DAOS until they are re-integrated into the NSF. Any DAOS references that remain in the NSF will continue to be serviced by DAOS, even if it is disabled. An NSF that contains DAOS references is not self-contained, and must continue to be treated as an active DAOS participant as long as it has DAOS references. To re-integrate the DAOS attachments into an NSF and remove the DAOS references, you can process the NSF with the “compact -c -daos off” command. Once that is done, the NSF will be self-contained again, and can be treated as a normal NSF.
Furthermore, to ensure that the DAOS enablement change takes effect completely, the Domino server as well as all processes that use the Domino API (compact, resync, backup, etc) are stopped. This allows the API to terminate completely, so the status change can be picked up at the next startup.
Space and time savings
The disk footprint savings with DAOS continues into the backup processing as well. The NLO files represent the static data that used to reside in the NSF, and was backed up every cycle even though it hadn't changed. In a typical mail environment, a large reduction in the NSF footprint plus a very small amount of NLO data means the reduction in the NSF footprint translates almost directly into a reduction in the backup footprint. Not only is the duplicate data being eliminated, the mailfile data is being separated into static and dynamic components. By applying an incremental backup regimen to the static (NLO) data, only the NLO files created since the last backup cycle need to be processed. That represents typically a very small amount of data compared with the entire set of NLO files.
Using DAOS enables backup software solutions to optimally backup the NLO files. This is because once an NLO is written to disk, it never changes. Therefore, the file need only be backed up once in its lifetime. Based on the example shown in the DAOS Estimator document [link], the space saving per full backup would be 38.8 GB, roughly equal to the number of shared NLO's times the average NLO size.
In the incremental backup case, duplicate NLO's will not be backup up again. Thus, the space savings from DAOS is directly proportional to the numbe r of duplicate NLO's seen in the environment, and the backup time savings is the product of the space saved and the backup throughput.
Restoring DAOS objects
A well-preserved DAOS repository makes for fast and easy restoration. And, while not really a backup mechanism, the default deferred deletion interval allows for accidentally deleted attachments to be saved from physical deletion up to 30 days after a mishap. Simply pull the document out of the trash folder, if soft deletion is enabled. If it's too late for that, restore from backup, then resynchronize the DAOS catalog using the server console command "tell daosmgr resync force" -- DAOS will once again recognize that the NLO has references.
Although an NLO will survive for the period of time specified by the deferred deletion interval, if soft deletion is disabled or a backup of the referencing document has not been made, there is no way to get at the contents of the NLO, especially if encryption is enabled (the default).
Restoring documents or NSF files with DAOS attachments
To restore either a full NSF or a single document, the process starts off the same. You must first restore the database and then the missing NLOs. To do this using Tivoli Data Protection for Domino, you would issue the command:
domdsmc restore -into
To determine which missing NLO files to bring back from the Domino server console, run
tell daosmgr listnlo -o missing.txt MISSING restoreddatabasename.nsf
The resulting missing.txt file is then fed into the restore command With the Tivoli Storage Manager (TSM), the command would be
dsmc restore -filelist=missing.txt -inact
If you are restoring the entire NSF, you are done. Note that any restoration operation will put the DAOS catalog into the Needs Resync state, so a resync operation should be performed as soon as convenient.
If you need only one document, you can now copy and paste it to its intended destination.
For a complete recovery after a catastrophic failure, the NSF and NLO files can be restored, followed by replaying the archived transaction logs. This will result in the most up-to-date recovery situation.
Dealing with damaged files and clusters
If an NSF is damaged, and you have clustered servers or replicas of the NSF on another server, you have several options.
- Replicate each entire NSF – New replicas can be created from the existing NSFs on the clustermate(s). Each new replica should be marked as DAOS enabled. As the replication occurs, the associated attachments will be saved to DAOS.
- Copy NSFs, replicate missing attachments – All of the necessary NSFs are copied from the clustermate(s) to the server being repaired. This will create a copy of the document data without attachment data. Fixup -j -D is then run, deleting all documents that contain DAOS references to NLO files that do not exist. Subsequent replication will re-create those documents along with the associated attachments, which will be stored in DAOS.
- Copy NSFs, copy/restore NLOs - All of the necessary NSFs are copied from the clustermate(s) to the server being restored. The command 'tell daosmgr listnlo missing somefile.nsf' is then issued for each individual NSF to generate a list of the NLO files that do not exist in the DAOS repository. Those NLO files are then restored from backup, or copied from the clustermate(s). (Note that copying the NLO files from another Domino server will work only if DAOS encryption is turned off. DAOS encryption is on by default, and uses the server key to do the encryption; therefore enc rypted NLO files are not portable between Domino servers.)
- Copy full NSFs and re-extract – If you have a replica on another server that is not DAOS-enabled, the NSF can be copied to the server being restored. The attachments will be inline in that copy of the NSF, and 'compact -c -daos on' can be issued to extract the inline attachments out to DAOS.
- Reintegrate NSFs and re-extract – If you have a replica on another server that is DAOS-enabled, but encryption prevents using the NLO files directly, you can run a 'compact -c -daos off' on the other server to re-integrate the attachments into the NSF. Once that is done, the NSF can be copied to the server being restored, and you can use 'compact -c -daos on' to extract the attachments to DAOS again.
Options for restoration
The need for restoring NLO files depends partly on the deferred deletion interval. If the restore is happening from a snapshot that's within the interval (for example, the interval is 30 days, and the NSF is being restored from last week's backup) it's not possible for any of the NLOs to have been deleted yet, so there shouldn't be a need to restore any NLOs. If the NSF being restored is older than the interval (for example, the interval is 30 days, but the NSF being restored is from 3 months ago), it's possible that some of the NLOs have been deleted, and would need to be restored.
Some of this also depends on what the reason for the restore is. If it's a catastrophic failure, you should restore the NSF(s) and run 'tell daosmgr listnlo missing filename.nsf' to get a list of all of the NLOs needed to make it whole again. That list should then be fed into the restore utility to restore those NLOs as well.
If it's just a matter of getting a single document with attachments back, you don't really need everything to be made whole to access just that one set of attachments. In the spirit of “Work smarter not harder,” you can restore the NSF, and then attempt to access the desired document (and attachments, if any) and finally deal with any missing NLOs that are mentioned during that operation. If there aren't any attachments on the document, there's no other work to be done. If there are attachments, the NLOs may still be there, so it's worth trying to access them before doing anything else. If any are missing, you'll get a console message that mentions the name of the NLO, at which point you can restore only what you need.
Offline archival
For offline archival purposes, it is recommended that the attachments be re-integrated into the NSF using a 'compact -c -daos off' operation prior to archiving. That eliminates the need to archive all the individual NLO files referred to by the NSF also. For example, if an employee was leaving the company, and their mail account was being closed and archived, this approach would be appropriate.
lotus.com
Subscribe to:
Posts (Atom)