Local Plug-in Library Isolation

Introduction

Third-party libraries deployed and utilized by the vCenter Server appliance (VCSA) for its own needs that are currently exposed to partner plugins will be restricted and no longer available, effective with vSphere 8.0.

In the versions of vSphere up to 7.0, local plugins can import packages from third-party libraries deployed for the needs of the vSphere Client platform. This is problematic for multiple reasons, such as:

• Changes to internal vSphere Client APIs could break plugin compatibility.

• Changes to a particular vSphere Client dependency (e.g. to consume security updates) could impact plugin compatibility.

• Unnecessary 3rd-party dependencies decrease performance of the vSphere Client. (Most plugins need only libraries related to the Spring framework.)

• Partner plugins can fail when VMware updates third-party libraries in response to security vulnerabilities.

For these reasons, VMware will require plugin developers to supply their own OSGi Java dependencies. Any Spring Framework, JSON/XML serialization, Apache utilities, etc. will have to be provided as part of the plugin: either as separate OSGi bundles or included in an existing plugin bundle's class path.

The library isolation will be in effect from vSphere 8.0.

Following are detailed guides on how to comply with the new OSGi requirements. A local setup refers to when a developer runs the vSphere Client process on their developer machine in contrast to CloudVM setup, where the vSphere Client process runs inside the vCenter Server Appliance.

Step-by-step guide on how to move to full isolated plugin (local setup)

Prerequisites

• ZIP edit tool

• Telnet client

• Registered plugin

• Knowledge about using the OSGi Console. See the Using the OSGi console section here: https://www.vogella.com/tutorials/OSGi/article.html#access-to-the-osgi-console-foryour-eclipse-application

Procedure

1. Place osgi.fullIsolation.debug=true in webclient.properties.

2. Open the .war archive with ZIP edit tool: <address of your sdk>/server/webapps/h5- bridgewebapp.war

3. Remove the XML comments around console in /WEB-INF/web.xml

4. (Re)start server.

5. Open your telnet client and connect to localhost, port 2401

6. The OSGi console opens up

   1. Use ss or lb to list currently deployed bundles

   2. Search for the bundle symbolic name/bundle id of the plugins bundle (if using ss command)

7. Use diag <bundle id> to display the missing dependencies of your plugin's bundles.

8. If you're not certain which bundle/jar provides a package missing for your bundles, you can use the packages <package name> command.

9. Add missing bundle dependencies in your libraries folder (a sibling to the plugins folder).

10. (Re)start server and repeat the Console procedure until all your bundles successfully resolve their dependencies.

Step-by-step guide on how to move to full isolated plugin (VCSA/CloudVM setup)

Prerequisites

• Telnet client - Windows: Putty, Mac: use brew [brew install telnet], Linux: use package manager of choice to install telnet

• Secure Copy Protocol (SCP) tool - Windows: WinSCP, Mac: Cyberduck or scp command, Linux: scp command

• Basic vi knowledge, see http://heather.cs.ucdavis.edu/~matloff/UnixAndC/Editors/ViIntro.html

Procedure

Important:

These steps should be undertaken only in a non-production test environment, that preferably doesn't have outside internet access. Using these steps in a production environment with Internet access constitutes a security risk.

1. ssh to the test VCSA

2. Place your plugin files in /usr/lib/vmware-vsphere-ui/plugin-packages (we'll use the simple-plugin-package as an example).

   
   

3. Make sure that the files of your plugin are owned by the vsphere-ui OS user and the directories are secured as shown in the following illustration.

   • cd /usr/lib/vmware-vsphere-ui/plugin-packages/
   • chown vsphere-ui simple-plugin-package/ -R
   • The resulting file permissions and ownership should be as follows:

   
   

4. Add osgi.fullIsolation.debug=true in webclient.properties

   • vi /etc/vmware/vsphere-ui/webclient.properties

   
   

5. Enable the OSGi Console, as follows:

   1. cd /usr/lib/vmware-vsphere-ui/server/webapps

   2. Unzip the /WEB-INF/web.xml file unzip -j "h5-bridge-webapp.war" "WEB-INF/web.xml" -d "/usr/lib/vmwarevsphere-ui/server/webapps/WEB-INF"

   3. Edit the WEB-INF/web.xml by removing the the XML comments around the init-param commandline

      • vi WEB-INF/web.xml
      • The web.xml should look like this:

      
      

      • Save the file.

   4. Modify the h5-bridge-webapp.war with the modified web.xml

      • zip -u h5-bridge-webapp.war WEB-INF/web.xml
      • Be sure that the output of the zip command is "updating", not adding.

   5. Make sure that the files of the archive are owned by the vsphere-ui OS user

      • chown vsphere-ui h5-bridge-webapp.war
      • Check filesystem permissions, using ls -lah

      
      

6. Open ports on the VCSA

   • iptables -A INPUT --dport 2401 -j ACCEPT

7. Restart the vsphere-ui:

   • service-control --restart vsphere-ui

8. Telnet to <VCSA IP/hostname> port 2401

   • telnet <vc_ip> 2401

9. Use the ss command to list all bundles and look for the bundles belonging to your plugin.

   • (You can make them out by their symbolic names)

   
   

   • We can observe that the bundles of your plugin are in the INSTALLED state, meaning they weren't resolved and could not be started.

10. Use diag <bundle id> to diagnose missing dependencies

    
    

    • The command will list all unresolved Import-Package/Require-Bundle requirements.

11. If you're not sure which bundle/jar provides a package that your plugin requires you can use the following OSGi console command:

    • packages <required package>

    
    

    • Typically, the bundle-symbolic-name is going to be a good orientation point to bundle that provides a required package. Use the bundle-symbolic-name to search maven.org for a matching jar name. For instance, if we make a search for jackson-core, we'll likely hit the jar that is required. https://search.maven.org/search?q=jackson-core

12. Add missing OSGi dependencies

    Note:

    • Dependencies should be placed in a new folder libraries, a sibling to the plugins folder. These dependencies in the libraries folder are going to be skipped in 6.7 and 7.0, but picked up in 8.0, making it possible to run the same plugin release in 6.7, 7.0 and 8.0 without any changes to the plugin.
    Note:

    • If you use Spring MVC controllers in your plugin the following list provides a latest picture (at time of writing) of the bundles required to resolve Spring MVC dependencies:

    • org.apache.servicemix.bundles.aopalliance-1.0_6

    • org.apache.servicemix.bundles.spring-aop-5.2.22.RELEASE_1

    • org.apache.servicemix.bundles.spring-beans-5.2.22.RELEASE_1

    • org.apache.servicemix.bundles.spring-context-5.2.22.RELEASE_1

    • org.apache.servicemix.bundles.spring-context-support-5.2.22.RELEASE_1

    • org.apache.servicemix.bundles.spring-core-5.2.22.RELEASE_1

    • org.apache.servicemix.bundles.spring-expression-5.2.22.RELEASE_1

    • org.apache.servicemix.bundles.spring-web-5.2.22.RELEASE_1

    • org.apache.servicemix.bundles.spring-webmvc-5.2.22.RELEASE_1

    • The plugins and libraries folders will look like:

    
    

13. Restart vsphere-ui, so we can make another iteration and see any other missing dependencies

    • service-control --restart vsphere-ui

14. Telnet will disconnect. Connect again to the OSGi console:

    • telnet <vc_ip> 2401
    • This time our plugin looks like the following:

    
    

    • We can observe that only one war is not resolved. We'll repeat steps 9-12.

15. Use diag <bundle id> to diagnose remaining missing dependencies

    Note:

    • The id of the simple-front-end bundle is now different after the last restart of the vsphere-ui. That is due to the random nature in which plugin bundles are installed in the OSGi runtime.

16. Continue adding required bundles in your libraries directory until all your plugin bundles are resolved.

17. Make the necessary changes to your build to include the OSGi bundles identified as missing dependencies in the libraries folder of your plugin package.

Additional Notes

Note 1

Troubleshooting

If runtime requests to your plugin endpoints fail with: "org.springframework.http.converter.HttpMessageNotWritableException: No converter found for return value of type: class XXX", then your plugin code is probably expecting HTTP responses with Content-Type: application/json. Spring Framework supports application/json serialization if you include the following jars in your libraries folder:

https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotations/2.13.2

https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind/2.13.2

https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotations/2.13.2

These are the latest versions at the time of writing of this document. Always use the latest versions to consume the latest security fixes.

Note 2

Some jars posted in the Maven Central repository are not OSGi bundles. If you happen to require such a jar, use Spring's bundle or BND to convert the jar to an OSGi bundle:

https://docs.spring.io/s2-bundlor/1.0.x/user-guide/htmlsingle/user-guide.html

https://github.com/bndtools/bnd/tree/master/maven/bnd-maven-plugin

Some jars have different artifact IDs to denote that they are OSGi bundles. For instance, Apache's http client: https://search.maven.org/artifact/org.apache.httpcomponents/httpclient-osgi is an OSGI bundle, but https://search.maven.org/artifact/org.apache.httpcomponents/httpclient is not an OSGi bundle.

Note 3

If your plugins require the following packages: com.vmware.vise.messaging.endpoints and com.vmware.vise.messaging.remoting, you should remove them. Those packages are not exported in full isolation mode and are no longer needed.

Note 4

Apache ServiceMix provides OSGi versions of Spring and other popular libraries. See: https://mvnrepository.com/artifact/org.apache.servicemix.bundles.