[
https://issues.apache.org/jira/browse/DERBY-3585?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Martin Zaun updated DERBY-3585:
-------------------------------
Attachment: DERBY-3585-0.zip
DERBY-3585-0.diff
DERBY-3585-0.stat
Please find attached for review and comments the documentation update
(dita diffs and html) for the network server shutdown authentication.
Having looked into the documentation source for the first time, the
formatting, the usage of the dita-tags in the individual sections, and
the applied level of detail appeared at times somewhat incoherent to me
(in the admin guide, for instance, comparing the network server start with
the shutdown section).
I tried to fit my additions into the existing structure, language, and
formatting, but most certainly there's plenty of chance for improvement by
a native speaker and a dita expert. For instance, I'm not sure if the
codeblock lines have gotten too long with the newly appended "... [-user
username] [-password password]" options.
Summary of changes:
1) adminguide/tadminconfigshuttingdownthenetworkserver.dita
- removed obsolete statements that user must explicitely shut down open
databases before shutting down the server when user authentication is
enabled
+ added that server can be shutdown by invoking script, jar, or class
+ added new user/password command-line options
2) adminguide/tadminconfig815333.dita
+ added jar file invokation usage for server shutdown
+ added username/password command-line options
3) tadminconfig815357.dita
+ added username/password constructor arguments
4) adminguide/derbyadmin.ditamap
adminguide/tadminnetservusrauth.dita
+ added a new section/toc entry "Running the Network Server with User
Authentication" under "Derby Network Server advanced topics"; this
adds a cross-reference to "Working with user authentication" in the
Derby Developer's Guide, which I strongly felt missing. Without this
section (or task?), there's only scattered information in the admin
guide on how to enable user authentication. For instance, there's a
note burried in "Basic Network Server security policy"; however,
enabling user authentication is independent from running with a
security manager. Also, having "user authentication" show up under
the generated links "Related concepts/tasks" might be very helpful
(even if the user will only find a cross-reference to the devguide
there).
5) adminguide/tadminconfig813694.dita
+ added new constructors with user/password arguments
6) adminguide/radminappsclientxmp.dita
+ added cross-reference to devguide's section on "user authentication"
neccessary to understand the examples and context
7) adminguide/tadminconfig814963.dita
- decided not to add new constructor examples here, since they're
described in their own section
8) adminguide/cadminssl.dita
- decided not to address any potential confusion about Derby's user
authentication and authentication with SSL/TLS, which are separate;
we've already identified this as a topic for future refinement and
changes (single login with certificate-based identity).
9) devguide/cdevcsecure36127.dita
- ok, no changes needed
10) devguide/tdevdvlp20349.dita
- found a flatly wrong statement but did NOT correct here since
unrelated to server shutdown authentication:
"You cannot explicitly request that the JVM unload a class, but you
can ensure that the EmbeddedDriver class is unloaded by using a
System.gc() to force it to garbage collect classes that are no longer
needed. Running with -nogc or -noclassgc definitely prevents the class
from being unloaded and makes you unable to restart Derby in the same
JVM."
System.gc() is only a suggestion to the Runtime to garbage-collect, it
cannot be enforced, and there's no guarantee whatsoever that GC has
run and any classes been unloaded. Likewise it's most probably not
guarantueed that -nogc or -noclassgc definitely (!) prevent a class
from being unloaded (a JVM may ignore these options...)
11) refderby, getstartderby, tuningderby, derbytools
- ok, no changes needed
> Document user authentication support for network server shutdown
> ----------------------------------------------------------------
>
> Key: DERBY-3585
> URL: https://issues.apache.org/jira/browse/DERBY-3585
> Project: Derby
> Issue Type: Sub-task
> Components: Documentation
> Reporter: Martin Zaun
> Assignee: Martin Zaun
> Fix For: 10.4.0.0
>
> Attachments: DERBY-3585-0.diff, DERBY-3585-0.stat, DERBY-3585-0.zip,
> releaseNote.html, releaseNote.html, releaseNote.html, releaseNote.html
>
>
> As part of the System Privileges work in DERBY-2109, the support of user
> authentication for network server shutdown was discussed, implemented, and
> committed (revision 632502).
> In order to address a security issue (missing user authentication for
> shutdown), this feature introduces a few incompatibilities with the usage of
> NetworkServerControl, which need to be documented.
> This JIRA is to provide for the user documentation and the release notes
> describing the usage changes and incompatibilities.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
