ShowTable of Contents
Introduction
With Domino 8.5.3 and the IBM XWork Server the XPages Extension Library can be deployed using a UpdateSite database (updatesite.ntf). This makes it easier to deploy or update the XPages Extension Library without the need to manually copy the plugins in each Domino Server. This NSF based OSGi bundles that are dynamically contributed to the OSGi runtime. For the NSF, we will leverage the standard updateSite.ntf template.
This new feature is optional and simple to use. By default the dynamic contribution is turned off. To enable it a variable must be added to the notes.ini that will contain the database paths that are allowed to contribute dynamic plugins - OSGI_HTTP_DYNAMIC_BUNDLES=updateSite1.nsf,foo/updateSite2.nsf. For each database specified in OSGI_HTTP_DYNAMIC_BUNDLES, a database based on the updateSite.ntf template needs to be created by the trusted administrator of the server who then can creates replicas in all the servers (upon which the about variable must be set) of the cluster or domain. This enables the deployment of Extension Library almost seamlessly.
Create a UpdateSite Application
For the server’s Administrator the steps to enable this feature are straight forward, though configured in a number of places. The first is to create a database on the server using the Eclipse Update Site ( updateSite.ntf) template.
Select File – Application – New.
This will launch the New Application dialog. From here select a server to where the application is to be created. Then on the same dialog select a server upon which the updateSite.ntf template resides.
Selecting the OK button on this dialog creates the application. Then it is a matter of modifying the application’s access control list for those who are to be allowed to create documents, and so add plugins to the server. Modifying the ACL of the databases to only allow (Author Access at a minimum) trusted users. Everyone else has no access. It is also recommended that "Do not show in Open application dialog" flag is set on the database.
Import the UpdateSite
The application is now ready to begin deploying an XPages Extension Library. On the main view, Main Features, select the ‘Import Local Update Site’ button. This will launch a dialog that allows for the selection of a site.xml file from an Eclipse plugin project.
For the Extension Library this is located in the updateSiteOpenNTF.zip file, which when extracted will contain two folders, ‘features’ and ‘plugins’, and the site.xml. The updateSiteOpenNTF.zip file can be found in the release of the Extension Library that can be downloaded from http://extlib.openntf.org.
Selecting this file and pressing the OK button begins the import process.
And once completed the view of the update site database will be updated with a document representing the import of the plugin.
The default state of the updateSite once installed is for it to be enabled. This same project document can be disabled as well which means that they will not be picked up by the OSGi runtime when the server Http task has been restarted. The same project document can tell the user a lot of information about the updateSite installed, most importantly the project version number.
Set the Notes.INI variable - OSGI_HTTP_DYNAMIC_BUNDLES
All that is left to do here is to put the reference to this Update Site database in the Notes.ini - OSGI_HTTP_DYNAMIC_BUNDLES=updateSite1.nsf – for the example above. And as long as this same notes.ini variable is set on other Domino servers this application can be replicated to these servers and the Extension Library will be deployed here as well.
Restart the server or the Http task
When the notes.ini variable is changed, the Domino server or the server’s http task will have to be restarted using ‘Restart Task HTTP’ command on the server’s console. When the server is restarted the following message will appear on the server console indicating that the NSF based plugin is being installed on the server
restart task http
29/11/2011 11:43:18 Domino Off-Line Services HTTP extension unloaded.
29/11/2011 11:43:18 XSP Command Manager terminated
29/11/2011 11:43:20 HTTP Server: Shutdown
29/11/2011 11:43:23 HTTP Server: Using Web Configuration View
29/11/2011 11:43:31 JVM: Java Virtual Machine initialized.
29/11/2011 11:43:31 HTTP Server: Java Virtual Machine loaded
29/11/2011 11:43:32 HTTP Server: DSAPI Domino Off-Line Services HTTP extension Loaded successfully
29/11/2011 11:43:35 HTTP JVM: CLFAD0330I: NSF Based plugins are being installed in the OSGi runtime. For more information please consult the log
29/11/2011 11:43:53 XSP Command Manager initialized
29/11/2011 11:43:54 HTTP Server: Started
What happens here when the server is restarted is that the OSGi launcher will introspect the updateSite dbs, automatically detect the features and dynamically load the associated plugins in the OSGi runtime. Internally, the OSGi launcher references each plugin using a url with a proprietary protocol that knows how to access the attachment plugin.
The url format is: osginsf://
For example: osginsf:updateSite.nsf/1234567890/com.ibm.extlib.demo_1.0.0_02102011.jar
Plugins not persisted on the server
It should be noted here that the plugins, deployed in this way are not physically installed in the Domino server and that once the http task is shutdown, they are not persisted anywhere in the server. And if there are more than one version of same feature, the Domino OSGi launcher will use the latest version. It will only compare the major, minor and service part of the version. If two features have the same major, minor and service, then the Domino OSGi launcher will rely on the last modified date of the feature document.
Security Safe Guards with this Deployment method
So deploying the NSF plugins is easy but this doesn’t mean that anyone can import plugins to the server. A number of security safe-guards are built in to this feature. With any customer code running from NSF, there needs to be care about who and what code is to be trusted.
The first layer of security is that the server’s administrator can enable/disable NSF based plugin contributions. By default the feature is disabled, to enable it the administrator uses the OSGI_HTTP_DYNAMIC_BUNDLES notes.ini variable containing the list of comma separated NSF paths that are authorized to contribute dynamic plugins.
The next layer of security is the ACL of the each database. One would need sufficient access to post the plugins in the database.
The OSGi runtime will perform document signature checking. Documents storing the plugins and fragments must be signed. If they are not signed or the signature has been tampered with, the OSGi runtime will not load them and a warning message will be added to the log.
For the plugin/fragment to be loaded, the person who signed the document must be included in the "Sign or run unrestricted methods and operations:" field in the security tab of the server document. If that's not the case, the OSGi runtime will add a warning to the log and the plugin will not be loaded.
Conclusion
Deploying the XPages Extension Library or any other extension library has never been easier.