db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2520) Document new restrictions of database shutdown, encryption and hard upgrade powers
Date Tue, 29 May 2007 18:59:15 GMT

    [ https://issues.apache.org/jira/browse/DERBY-2520?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499890
] 

Kim Haase commented on DERBY-2520:
----------------------------------

I started working on this on Friday -- I hope there's not too much overlap between these and
what Laura finds (two eyes are probably better than one). 

adminguide/cadminappsclient.dita: Fine


devguide/cdevcsecureDbOwner.html (Database owner):

This one's new, right? It's very good. Only a few nits --

I would suggest getting rid of the Latin -- change "e.g" to "for example" (if that is what
is meant), and change "i.e." to "that is". The "cf." is in a bit of a run-on sentence; you
might want to make a separate sentence saying, 

See "SET SCHEMA statement" in <ph conref="../conrefs.dita#pub/citref"></ph>.

Also, in the sentence beginning "When authentication is enabled...", make "shut down" two
words, and change the "and" to "or" ("or to perform a full upgrade").

I would suggest changing the CAVEAT paragraph to a <note type="attention"> or <note
type="important">.


devguide/cdevcsecure36127.html (Enabling user authentication):

The sentence after the second note seems like another way of stating the information in the
first note. Would it be possible to combine the information so it's all in one note?

"If you start a Derby system without defining at least one user, and you enable user authentication
either at startup time or later, problems will occur. When user authentication is enabled
without a user being defined, the default database owner will become "APP", and unless this
is a valid user name, you will not be able to shut down the database, encrypt or reencrypt
the database, or perform a full upgrade of it. You will need to alter shutdown scripts accordingly."

Something like that? And how would you alter the shutdown scripts to recover from this?


devguide/tdevdvlp40464.html (Shutting down Derby or an individual database):

The text "database owner" occurs twice, once inside the xref and once outside.

In the new example, a semicolon is needed at the end of the statement.


devguide/cdevcsecuregrantrevokeaccess.html: Fine
devguide/tdevcsecurenewkeyoverview.html: Fine
devguide/cdevcsecure36595.html: Fine
devguide/tdevcsecureunencrypteddb.html: Fine
devguide/tdevcsecurenewextkey.html: Fine


devguide/tdevcsecurenewbootpw.html: Fine, though there was an existing error in the last sentence:
"new the boot password" instead of "the new boot password" -- that it would be nice to fix.


devguide/rdevcsecure13713.html (User authentication example in a single-user, embedded environment):

The note here is a bit confusing --

 The user name "enduser" must be supplied ...
 
The way to set the username and password is not quite clear here, since it's described in
another topic ("Built-in Derby users"). Also the last phrase turns the sentence into a run-on.
So I would suggest something like this:

The user name (the value specified by the <codeph>derby.user.<i>username</i></codeph>
property) must be supplied when the database is created, even if authentication is not yet
enabled. Otherwise the database owner will have the default name "APP" (see <xref href="cdevcsecureDbOwner.dita#cdevcsecureDbOwner"></xref>
for details).

In the next sentence, it is not clear what "those" refers to any more, because of the inserted
note. How about this?

The following example shows how to provide these properties in a connection URL, although
...


devguide/rdevdvlp22102.html: Fine


ref/rrefattrib15290.html (dataEncryption=true attribute): 

I am not quite sure what the phrase "cf. the property derby.connection.requireAuthentication"
means here. Usually "cf." (confere) means "refer to" or "see", but there's no xref to another
topic. I see that because the description is in another book you can't create an xref. So
you need to do something like

For an existing, unencrypted database for which authentication is enabled, only the <xref
href="rrefattrib26867.dita#rrefattrib26867">database owner</xref> can perform encryption.
See "Enabling user authentication" in the <ph conref="../conrefs.dita#pub/citdevelop"></ph>
for more information.

Similar suggestions -- with appropriate variations in wording -- for

ref/rrefattrib88843.html (encryptionProvider=providerName attribute)
ref/rrefattrib42100.html (bootPassword=key attribute)
ref/rrefattribencryptkey.html (encryptionKey=key attribute)
ref/rrefattribnewencryptkey.html (newEncryptionKey=key attribute)
ref/rrefattribnewbootpw.html (newBootPassword=newPassword attribute)
ref/rrefattrib60346.html (encryptionAlgorithm=algorithm attribute)
ref/rrefattrib16471.html (shutdown=true attribute)


ref/rrefattrib26867.html (create=true attribute):

Same suggestion as above, for that sentence. I would also suggest rephrasing the other two
"cf." phrases. So the whole paragraph would look something like this:

When the database is created, the current authorization identifier becomes the database owner
(see the <i><xref href="rrefattrib10035.dita#rrefattrib10035"></xref></i>).
If authentication is enabled (see "Enabling user authentication" in the <ph conref="../conrefs.dita#pub/citdevelop"></ph>),
only the database owner can <xref href="rrefattrib16471.dita#rrefattrib16471">shut down</xref>
the database, <xref href="rrefattrib15290.dita#rrefattrib15290">encrypt</xref>
it, reencrypt it with a new <xref href="rrefattribnewbootpw.dita#rrefattribnewbootpw">boot
password</xref> or new <xref href="rrefattribnewencryptkey.dita#rrefattribnewencryptkey">encryption
key</xref>, or perform a full upgrade. If authentication is not enabled, and no user
is supplied, the database owner defaults to "APP", which is also the name of the default schema
(see <xref href="rrefsqlj32268.dita#rrefsqlj32268"></xref>).


ref/rrefsqlj24513.html: Fine
ref/rrefsqljrevoke.html: Fine
ref/rrefsqljrenametablestatement.html: Fine
ref/rrefsqlj15446.html: Fine
ref/rrefcreateprocedurestatement.html: Fine
ref/rrefsqlj40506.html: Fine
ref/rrefcreatefunctionstatement.html: Fine
ref/rrefexcept71493.html: Fine
ref/rrefsqlj43125.html: Fine

> Document new restrictions of database shutdown, encryption and hard upgrade powers
> ----------------------------------------------------------------------------------
>
>                 Key: DERBY-2520
>                 URL: https://issues.apache.org/jira/browse/DERBY-2520
>             Project: Derby
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: Dag H. Wanvik
>            Assignee: Dag H. Wanvik
>             Fix For: 10.3.0.0
>
>         Attachments: DERBY-2520.diff, DERBY-2520.stat, DERBY-2520.tar.gz, DERBY-2520.zip
>
>
> Add documentation for the new functionality introduced with DERBY-2264.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message