Derby
  1. Derby
  2. DERBY-5637

Document Derby's JMX capabilities and how to disable them

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.9.1.0
    • Fix Version/s: 10.9.1.0
    • Component/s: Documentation, JMX
    • Labels:
      None
    • Bug behavior facts:
      Security

      Description

      Derby's JMX beans are useful, although limited. We should document their capabilities as well as how to disable/restrict access to them in security-conscious environments.

      1. radminjmxenabledisable.html
        7 kB
        Kim Haase
      2. DERBY-5637-3.diff
        0.8 kB
        Kim Haase
      3. DERBY-5637-2.zip
        23 kB
        Kim Haase
      4. DERBY-5637-2.stat
        0.4 kB
        Kim Haase
      5. DERBY-5637-2.diff
        11 kB
        Kim Haase
      6. DERBY-5637.zip
        43 kB
        Kim Haase
      7. DERBY-5637.stat
        0.8 kB
        Kim Haase
      8. DERBY-5637.diff
        74 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          I think some JMX work was done as part of DERBY-3540, so this should build on that work, I guess?

          Show
          Kim Haase added a comment - I think some JMX work was done as part of DERBY-3540 , so this should build on that work, I guess?
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          That sounds like a good starting point. Thanks.

          Show
          Rick Hillegas added a comment - Hi Kim, That sounds like a good starting point. Thanks.
          Hide
          Knut Anders Hatlen added a comment -

          > We should document (...) how to disable/restrict access to them in security-conscious environments.

          I'm aware of the following ways to disable the MBeans:

          1) Use the stopManagement() method of ManagementMBean. This method unregisters all of Derby's MBeans except ManagementMBean itself, so it doesn't turn it off completely.

          2) Run the network server with a custom security policy which doesn't grant derby.jar the permissions needed to register MBeans. For example by modifying the network server's basic policy (http://db.apache.org/derby/docs/dev/adminguide/tadminnetservbasic.html) by commenting out this section:

          // Allows access to Derby's built-in MBeans, within the domain
          // org.apache.derby.
          // Derby must be allowed to register and unregister these MBeans.
          // It is possible to allow access only to specific MBeans, attributes or
          // operations. To fine tune this permission, see the javadoc of
          // javax.management.MBeanPermission or the JMX Instrumentation and Agent
          // Specification.
          //
          permission javax.management.MBeanPermission
          "org.apache.derby.*#[org.apache.derby:*]",
          "registerMBean,unregisterMBean";

          If the permission to register MBeans isn't granted to derby.jar, JMXManagementService.jmxRegister() will silently ignore any requests to register MBeans, as can be seen from this catch block in said method:

          } catch (SecurityException se)

          { // If we can't register the MBean then so be it. // The application can later enabled the MBeans // by using org.apache.derby.mbeans.Management }
          Show
          Knut Anders Hatlen added a comment - > We should document (...) how to disable/restrict access to them in security-conscious environments. I'm aware of the following ways to disable the MBeans: 1) Use the stopManagement() method of ManagementMBean. This method unregisters all of Derby's MBeans except ManagementMBean itself, so it doesn't turn it off completely. 2) Run the network server with a custom security policy which doesn't grant derby.jar the permissions needed to register MBeans. For example by modifying the network server's basic policy ( http://db.apache.org/derby/docs/dev/adminguide/tadminnetservbasic.html ) by commenting out this section: // Allows access to Derby's built-in MBeans, within the domain // org.apache.derby. // Derby must be allowed to register and unregister these MBeans. // It is possible to allow access only to specific MBeans, attributes or // operations. To fine tune this permission, see the javadoc of // javax.management.MBeanPermission or the JMX Instrumentation and Agent // Specification. // permission javax.management.MBeanPermission "org.apache.derby.*# [org.apache.derby:*] ", "registerMBean,unregisterMBean"; If the permission to register MBeans isn't granted to derby.jar, JMXManagementService.jmxRegister() will silently ignore any requests to register MBeans, as can be seen from this catch block in said method: } catch (SecurityException se) { // If we can't register the MBean then so be it. // The application can later enabled the MBeans // by using org.apache.derby.mbeans.Management }
          Hide
          Kim Haase added a comment -

          I'm guessing that what I'll mainly need to do for this is to bring the content of the wiki page http://wiki.apache.org/db-derby/DerbyJMXQuickStart into the documentation (probably the Admin Guide), adding the information about disabling the MBeans – does that make sense?

          The quickstart page seems to have been updated a year or so ago. If there's anything outdated in it, please let me know.

          Show
          Kim Haase added a comment - I'm guessing that what I'll mainly need to do for this is to bring the content of the wiki page http://wiki.apache.org/db-derby/DerbyJMXQuickStart into the documentation (probably the Admin Guide), adding the information about disabling the MBeans – does that make sense? The quickstart page seems to have been updated a year or so ago. If there's anything outdated in it, please let me know.
          Hide
          Kim Haase added a comment -

          Should I also add the material in http://wiki.apache.org/db-derby/JMXSecurityExpectations? It's referenced from http://wiki.apache.org/db-derby/DerbyJMXQuickStart#Fine-grained_authorization:_Security_policy. However, it's full of warnings about being possibly outdated. I could put the material in and let you fix it ...

          Show
          Kim Haase added a comment - Should I also add the material in http://wiki.apache.org/db-derby/JMXSecurityExpectations? It's referenced from http://wiki.apache.org/db-derby/DerbyJMXQuickStart#Fine-grained_authorization:_Security_policy . However, it's full of warnings about being possibly outdated. I could put the material in and let you fix it ...
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          I think you should ignore the material at http://wiki.apache.org/db-derby/JMXSecurityExpectations?. We may want to add some of this material once we see your first patch, but we may not need to. Thanks.

          Show
          Rick Hillegas added a comment - Hi Kim, I think you should ignore the material at http://wiki.apache.org/db-derby/JMXSecurityExpectations? . We may want to add some of this material once we see your first patch, but we may not need to. Thanks.
          Hide
          Kim Haase added a comment -

          Thanks, Rick! It is true there is already a lot of security-related information in the quick start.

          Show
          Kim Haase added a comment - Thanks, Rick! It is true there is already a lot of security-related information in the quick start.
          Hide
          Kim Haase added a comment -

          All right! Here's a first draft of Admin Guide topics based on John Embretsen's wiki material, with some changes in cross-references in that book and the Developer's Guide. Attaching DERBY-5637.diff, DERBY-5637.stat, and DERBY-5637.zip, with the following new and changed topics:

          M src/adminguide/cadminconfig86869.dita
          M src/adminguide/tadminconfigsysteminformation.dita
          A src/adminguide/radminjmxjconsole.dita
          A src/adminguide/cadminjmxoverview.dita
          A src/adminguide/radminjmxenabledisable.dita
          A src/adminguide/radminjmxenablesimpleauth.dita
          A src/adminguide/radminjmxenablenoauth.dita
          A src/adminguide/radminjmxenablepwd.dita
          A src/adminguide/radminjmxtroubleshoot.dita
          A src/adminguide/radminjmxenablepwdssl.dita
          M src/adminguide/derbyadmin.ditamap
          A src/adminguide/radminjmxdisable.dita
          A src/adminguide/radminjmxenablepolicy.dita
          A src/adminguide/radminjmxcode.dita
          A src/adminguide/radminjmxintro.dita
          M src/devguide/cdevbabejgjd.dita
          M src/devguide/cdevsetprop824983.dita

          Show
          Kim Haase added a comment - All right! Here's a first draft of Admin Guide topics based on John Embretsen's wiki material, with some changes in cross-references in that book and the Developer's Guide. Attaching DERBY-5637 .diff, DERBY-5637 .stat, and DERBY-5637 .zip, with the following new and changed topics: M src/adminguide/cadminconfig86869.dita M src/adminguide/tadminconfigsysteminformation.dita A src/adminguide/radminjmxjconsole.dita A src/adminguide/cadminjmxoverview.dita A src/adminguide/radminjmxenabledisable.dita A src/adminguide/radminjmxenablesimpleauth.dita A src/adminguide/radminjmxenablenoauth.dita A src/adminguide/radminjmxenablepwd.dita A src/adminguide/radminjmxtroubleshoot.dita A src/adminguide/radminjmxenablepwdssl.dita M src/adminguide/derbyadmin.ditamap A src/adminguide/radminjmxdisable.dita A src/adminguide/radminjmxenablepolicy.dita A src/adminguide/radminjmxcode.dita A src/adminguide/radminjmxintro.dita M src/devguide/cdevbabejgjd.dita M src/devguide/cdevsetprop824983.dita
          Hide
          Knut Anders Hatlen added a comment -

          Thanks Kim, for getting this into the docs, and John, for writing it up in the first place!

          It all looks good to me. Some minor questions/suggestions below. Feel free to commit the patch as-is and address the comments in a follow-up.

          • In the "Using custom Java code to access the Derby MBeans" topic, the sentence "It is assumed that the client JVM supports Java SE 5, 6, or 7" is redundant since the client driver only works on Java SE 5 and newer, starting with Derby 10.9, so the version requirement isn't JMX-specific. Removing the sentence has the additional benefit that we don't have to update it once Java 8 is out.
          • "Disabling access to MBeans" references and shows code from an internal method (JMXManagementService.jmxRegister()). Maybe it's enough to say that without the permissions, Derby will silently skip starting the management service at boot time? Hopefully, the users believe that statement even if we don't include the code to prove it.
          • "Enabling and disabling JMX" topic:
          • Maybe change "running as the same user" to "running as the same operating system user" so that it's not confused with Derby database or system users?
          • Change "If you are using a Java SE 6 or 7 JVM" to "If you are using a Java SE 6 or newer JVM" to prevent need to update as new JVM versions are released?
          • "Introduction to the Derby MBeans" topic: Should we remove the parts marked "(not public)" to keep them private?
          • "Troubleshooting JMX connection issues" topic: "It" (first sentence, after the comma) should not be capitalized.
          • Inconsistent casing: "Platform MBean Server" / "platform MBean server" / "platform MBean Server"
          Show
          Knut Anders Hatlen added a comment - Thanks Kim, for getting this into the docs, and John, for writing it up in the first place! It all looks good to me. Some minor questions/suggestions below. Feel free to commit the patch as-is and address the comments in a follow-up. In the "Using custom Java code to access the Derby MBeans" topic, the sentence "It is assumed that the client JVM supports Java SE 5, 6, or 7" is redundant since the client driver only works on Java SE 5 and newer, starting with Derby 10.9, so the version requirement isn't JMX-specific. Removing the sentence has the additional benefit that we don't have to update it once Java 8 is out. "Disabling access to MBeans" references and shows code from an internal method (JMXManagementService.jmxRegister()). Maybe it's enough to say that without the permissions, Derby will silently skip starting the management service at boot time? Hopefully, the users believe that statement even if we don't include the code to prove it. "Enabling and disabling JMX" topic: Maybe change "running as the same user" to "running as the same operating system user" so that it's not confused with Derby database or system users? Change "If you are using a Java SE 6 or 7 JVM" to "If you are using a Java SE 6 or newer JVM" to prevent need to update as new JVM versions are released? "Introduction to the Derby MBeans" topic: Should we remove the parts marked "(not public)" to keep them private? "Troubleshooting JMX connection issues" topic: "It" (first sentence, after the comma) should not be capitalized. Inconsistent casing: "Platform MBean Server" / "platform MBean server" / "platform MBean Server"
          Hide
          Kim Haase added a comment -

          Thank you, Knut, for the careful review. I'll commit the initial patch so that the incremental changes will be clearer. Feel free, everyone, to provide more edits as you find them.

          Show
          Kim Haase added a comment - Thank you, Knut, for the careful review. I'll commit the initial patch so that the incremental changes will be clearer. Feel free, everyone, to provide more edits as you find them.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5637.diff to documentation trunk at revision 1324773.

          Show
          Kim Haase added a comment - Committed patch DERBY-5637 .diff to documentation trunk at revision 1324773.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-5637-2.diff, DERBY-5637-2.stat, and DERBY-5637-2.zip, with further changes to 9 files:

          M src/adminguide/cadminjmxoverview.dita
          M src/adminguide/radminjmxcode.dita
          M src/adminguide/radminjmxdisable.dita
          M src/adminguide/radminjmxenablenoauth.dita
          M src/adminguide/radminjmxenablepwd.dita
          M src/adminguide/radminjmxenablepwdssl.dita
          M src/adminguide/radminjmxintro.dita
          M src/adminguide/radminjmxjconsole.dita
          M src/adminguide/radminjmxtroubleshoot.dita

          I hope I've incorporated your suggestions. I didn't remove the parts marked "not public" in the MBeans info, but instead changed them to "not in the public API" for clarity. The non-public API is not really hidden, since anyone can check out the code and take a look. Does this make sense? I can remove those items completely if you prefer.

          I found more occurrences of "6 or 7" and changed them to "6 or later".

          The Java SE documentation uses "platform MBean server" so I made the usage consistent with that.

          Thanks again for the great review – even catching the capitalized "It" in midsentence.

          Show
          Kim Haase added a comment - Attaching DERBY-5637 -2.diff, DERBY-5637 -2.stat, and DERBY-5637 -2.zip, with further changes to 9 files: M src/adminguide/cadminjmxoverview.dita M src/adminguide/radminjmxcode.dita M src/adminguide/radminjmxdisable.dita M src/adminguide/radminjmxenablenoauth.dita M src/adminguide/radminjmxenablepwd.dita M src/adminguide/radminjmxenablepwdssl.dita M src/adminguide/radminjmxintro.dita M src/adminguide/radminjmxjconsole.dita M src/adminguide/radminjmxtroubleshoot.dita I hope I've incorporated your suggestions. I didn't remove the parts marked "not public" in the MBeans info, but instead changed them to "not in the public API" for clarity. The non-public API is not really hidden, since anyone can check out the code and take a look. Does this make sense? I can remove those items completely if you prefer. I found more occurrences of "6 or 7" and changed them to "6 or later". The Java SE documentation uses "platform MBean server" so I made the usage consistent with that. Thanks again for the great review – even catching the capitalized "It" in midsentence.
          Hide
          Knut Anders Hatlen added a comment -

          Thanks for making these changes. The patch looks good to me. +1

          Show
          Knut Anders Hatlen added a comment - Thanks for making these changes. The patch looks good to me. +1
          Hide
          Kim Haase added a comment -

          Thanks again, Knut.

          Committed patch DERBY-5637-2.diff to documentation trunk at revision 1325856.

          And then I immediately discovered that I had missed an occurrence of "6 or 7". So I will file and commit another patch before resolving this.

          Show
          Kim Haase added a comment - Thanks again, Knut. Committed patch DERBY-5637 -2.diff to documentation trunk at revision 1325856. And then I immediately discovered that I had missed an occurrence of "6 or 7". So I will file and commit another patch before resolving this.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-5637-3.diff and radminjmxenabledisable.html, with a small change to the "Enabling and disabling JMX" topic. Will commit shortly.

          Show
          Kim Haase added a comment - Attaching DERBY-5637 -3.diff and radminjmxenabledisable.html, with a small change to the "Enabling and disabling JMX" topic. Will commit shortly.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5637-3.diff to documentation trunk at revision 1325866.

          Show
          Kim Haase added a comment - Committed patch DERBY-5637 -3.diff to documentation trunk at revision 1325866.
          Hide
          Kim Haase added a comment -

          Changes have appeared in Latest Alpha Docs.

          Show
          Kim Haase added a comment - Changes have appeared in Latest Alpha Docs.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Rick Hillegas
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development