You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by rh...@apache.org on 2007/03/06 20:41:08 UTC
svn commit: r515270 - in /db/derby/docs/trunk/src/adminguide:
derbyadmin.ditamap tadmincbdjhhfd.dita tadminnetservbasic.dita
tadminnetservcustom.dita tadminnetservopen.dita tadminnetservrun.dita
Author: rhillegas
Date: Tue Mar 6 11:41:07 2007
New Revision: 515270
URL: http://svn.apache.org/viewvc?view=rev&rev=515270
Log:
DERBY-2372: Commit derby-2372-01.diff, edits to the Admin Guide describing the secure-by-default server.
Added:
db/derby/docs/trunk/src/adminguide/tadminnetservbasic.dita (with props)
db/derby/docs/trunk/src/adminguide/tadminnetservcustom.dita (with props)
db/derby/docs/trunk/src/adminguide/tadminnetservopen.dita (with props)
Modified:
db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap
db/derby/docs/trunk/src/adminguide/tadmincbdjhhfd.dita
db/derby/docs/trunk/src/adminguide/tadminnetservrun.dita
Modified: db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap?view=diff&rev=515270&r1=515269&r2=515270
==============================================================================
--- db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap (original)
+++ db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap Tue Mar 6 11:41:07 2007
@@ -189,7 +189,10 @@
<topicref collection-type="family" href="cadminadvtops.dita" navtitle="Derby Network Server advanced topics">
<topicref href="cadminnetservsecurity.dita" navtitle="Network Server security">
</topicref>
-<topicref href="tadminnetservrun.dita" navtitle="Running the Network Server under the security manager">
+<topicref collection-type="family" href="tadminnetservrun.dita" navtitle="Running the Network Server under the security manager">
+<topicref href="tadminnetservbasic.dita" navtitle="Basic Network Server security policy"></topicref>
+<topicref href="tadminnetservcustom.dita" navtitle="Customizing the Network Server's security policy"></topicref>
+<topicref href="tadminnetservopen.dita" navtitle="Running the Network Server without a security policy"></topicref>
</topicref>
<topicref href="tadminconfiguringthenetworkserver.dita" navtitle="Configuring the Network Server to handle connections">
</topicref>
Modified: db/derby/docs/trunk/src/adminguide/tadmincbdjhhfd.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/tadmincbdjhhfd.dita?view=diff&rev=515270&r1=515269&r2=515270
==============================================================================
--- db/derby/docs/trunk/src/adminguide/tadmincbdjhhfd.dita (original)
+++ db/derby/docs/trunk/src/adminguide/tadmincbdjhhfd.dita Tue Mar 6 11:41:07 2007
@@ -31,6 +31,20 @@
after use, because failure to do so might result in unpredictable side-effects,
such as blocked ports on the server.</note></context>
<example>
+<p>
+The following examples all assume that you have configured user
+authentication via properties set in derby.properties. That is because
+the Network Server tries to come up with some default security enabled
+when you boot it as the VM's entry point. In particular, the Network
+Server attempts to install a default Java security manager and the
+Network Server checks to make sure that user authentication has been
+turned on. If, for some reason, you want to run your Network Server
+without these security checks, you can disable them. For details on
+how to disable these checks, please see
+<xref href="tadminnetservopen.dita"></xref>.
+For details on how to configure user authentication, please consult
+the "Working with user authentication" section in the Developer's Guide.
+</p>
<p>You can start the Network Server in any of the following ways:</p>
<ul>
<li><p>If you are relatively new to the Java programming language, follow the
Added: db/derby/docs/trunk/src/adminguide/tadminnetservbasic.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/tadminnetservbasic.dita?view=auto&rev=515270
==============================================================================
--- db/derby/docs/trunk/src/adminguide/tadminnetservbasic.dita (added)
+++ db/derby/docs/trunk/src/adminguide/tadminnetservbasic.dita Tue Mar 6 11:41:07 2007
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "../dtd/task.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<task id="tadminnetservbasic" xml:lang="en-us">
+<title>Basic Network Server security policy</title>
+<prolog><metadata>
+<keywords><indexterm>Network Server<indexterm>basic policy</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<taskbody>
+<context>
+<p>
+If you boot the Network Server without specifying a security manager,
+the Network Server will install a default Java security manager
+enforcing a Basic policy. This happens if you boot the Network Server
+as your VM's entry point, e.g.:
+</p>
+
+<codeblock>
+java org.apache.derby.drda.NetworkServerControl start ...
+</codeblock>
+
+<p>
+Note that the Network Server expects that you will run your
+client/server application with user authentication enabled. If you do
+not enable user authentication, then the Network Server will raise an
+error and exit. For details on how to enable user authentication,
+please see the section titled "Derby Security" in the Derby
+Developer's Guide.
+</p>
+
+<p>
+Some of your application code may run as procedures and functions
+which you have declared using the CREATE PROCEDURE and CREATE FUNCTION
+statements. You will need to add privileged blocks to your declared procedures
+and functions if they perform sensitive operations such as file and
+network i/o,
+classloading, system property reading, etc..
+</p>
+
+<p>
+If for some reason you do not want to run your client/server
+application under a security manager, you may override the Network
+Server's impulse to install a default policy. For details on how to do
+this, please see
+<xref href="tadminnetservopen.dita"></xref>.
+</p>
+
+<p>
+Note that the Network Server attempts to install a security manager
+only if you boot the server as the entry point of your VM. The Network
+Server will not attempt to install a security manager if you start the
+server from your application using the programmatic API
+described in the following section:
+<xref href="tadminconfig814963.dita"></xref>.
+</p>
+
+<p>
+You will find a copy of the Network Server's Basic policy in the Derby
+distribution at
+<i>demo/templates/server.policy</i>. Most likely, you will want to
+customize this policy. For example, probably you will want to restrict
+the server's liberal file i/o permissions which let the server
+backup/restore to/from any location in the local file system. For
+details on how to customize the default policy, please see
+<xref href="tadminnetservcustom.dita"></xref>.
+A copy of the Basic policy follows:
+</p>
+
+<codeblock>
+grant codeBase "${derby.install.url}derby.jar"
+{
+//
+// These permissions are needed for everyday, embedded Derby usage.
+//
+ permission java.lang.RuntimePermission "createClassLoader";
+ permission java.util.PropertyPermission "derby.*", "read";
+ permission java.io.FilePermission "${derby.system.home}","read";
+ permission java.io.FilePermission "${derby.system.home}${/}-", "read,write,delete";
+
+//
+// This permission lets you backup and restore databases
+// to and from arbitrary locations in your file system.
+//
+// This permission also lets you import/export data to and from
+// arbitrary locations in your file system.
+//
+// You may want to restrict this access to specific directories.
+//
+ permission java.io.FilePermission "<<ALL FILES>>", "read,write,delete";
+};
+
+grant codeBase "${derby.install.url}derbynet.jar"
+{
+//
+// This permission lets the Network Server manage connections from clients.
+//
+ permission java.net.SocketPermission "${derby.drda.host}:*", "accept";
+};
+</codeblock>
+</context>
+</taskbody>
+</task>
Propchange: db/derby/docs/trunk/src/adminguide/tadminnetservbasic.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/adminguide/tadminnetservcustom.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/tadminnetservcustom.dita?view=auto&rev=515270
==============================================================================
--- db/derby/docs/trunk/src/adminguide/tadminnetservcustom.dita (added)
+++ db/derby/docs/trunk/src/adminguide/tadminnetservcustom.dita Tue Mar 6 11:41:07 2007
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "../dtd/task.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<task id="tadminnetservcustom" xml:lang="en-us">
+<title>Customizing the Network Server's security policy</title>
+<prolog><metadata>
+<keywords><indexterm>Network Server<indexterm>custom policy</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<taskbody>
+<context>
+<p>
+The Network Server's Basic security policy is documented in a previous
+section of this manual:
+<xref href="tadminnetservbasic.dita"></xref>.
+Most likely, you will want to
+customize this policy and install your own security manager. For example, probably you will want to restrict
+the server's liberal file i/o permissions which let the server
+backup/restore to/from any location in the local file system.
+Customizing the Basic policy is simple:
+</p>
+
+<ul>
+<li>The Basic policy lives in the Derby distribution at
+<i>demo/templates/server.policy</i>. Copy it from this location to
+your own file, say <i>myCustomized.policy</i>. All of the following
+edits take place in your custom file.</li>
+<li>Replace the <i>${derby.install.url}</i> variable with the location
+of the Derby jars in your local file system.</li>
+<li>Replace the <i>${derby.system.home}</i> variable with the location
+of your Derby system directory. Alternatively, rather than replacing
+this variable, you can simply set the value of the
+<i>derby.system.home</i> system property when you boot the server.</li>
+<li>Replace the <i>${derby.drda.host}</i> variable with the location
+of your Derby system directory. Alternatively, rather than replacing
+this variable, you can simply set the value of the
+<i>derby.drda.host</i> system property when you boot the server.</li>
+<li>Refine the file permissions needed by backup/restore,
+import/export, and the loading of application jars.</li>
+</ul>
+
+<p>
+A sample, customized policy file follows:
+</p>
+
+<codeblock>
+grant codeBase "file:/usr/local/share/sw/derby/lib/derby.jar"
+{
+//
+// These permissions are needed for everyday, embedded Derby usage.
+//
+ permission java.lang.RuntimePermission "createClassLoader";
+ permission java.util.PropertyPermission "derby.*", "read";
+ permission java.io.FilePermission "/usr/local/shoppingCartApp/databases","read";
+ permission java.io.FilePermission "/usr/local/shoppingCartApp/databases/-", "read,write,delete";
+
+//
+// This permission lets you backup and restore databases
+// to and from a selected branch of the local file system:
+//
+ permission java.io.FilePermission "/usr/local/shoppingCartApp/backups/-", "read,write,delete";
+//
+// This permission lets you import data from
+// a selected branch of the local file system:
+//
+ permission java.io.FilePermission "/usr/local/shoppingCartApp/imports/-", "read";
+//
+// This permission lets you export data to
+// a selected branch of the local file system:
+//
+ permission java.io.FilePermission "/usr/local/shoppingCartApp/exports/-", "write";
+//
+// This permission lets you load your databases with jar files of
+// application code
+//
+ permission java.io.FilePermission "/usr/local/shoppingCartApp/lib/*", "read";
+};
+
+grant codeBase "file:/usr/local/share/sw/derby/lib/derbynet.jar"
+{
+//
+// This permission lets the Network Server manage connections from clients.
+//
+ permission java.net.SocketPermission "buyCoolStuff.acme.com:*", "accept";
+};
+</codeblock>
+
+<p>
+After customizing the Basic policy, you may bring up the Network
+Server as follows:
+</p>
+
+<codeblock>
+java -Djava.security.manager -Djava.security.policy=/usr/local/shoppingCartApp/lib/myCustomized.policy org.apache.derby.drda.NetworkServerControl start -h localhost
+</codeblock>
+
+</context>
+</taskbody>
+</task>
Propchange: db/derby/docs/trunk/src/adminguide/tadminnetservcustom.dita
------------------------------------------------------------------------------
svn:eol-style = native
Added: db/derby/docs/trunk/src/adminguide/tadminnetservopen.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/tadminnetservopen.dita?view=auto&rev=515270
==============================================================================
--- db/derby/docs/trunk/src/adminguide/tadminnetservopen.dita (added)
+++ db/derby/docs/trunk/src/adminguide/tadminnetservopen.dita Tue Mar 6 11:41:07 2007
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="utf-8"?>
+
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
+ "../dtd/task.dtd">
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<task id="tadminnetservopen" xml:lang="en-us">
+<title>Running the Network Server without a security policy</title>
+<prolog><metadata>
+<keywords><indexterm>Network Server<indexterm>no security manager</indexterm></indexterm>
+</keywords>
+</metadata></prolog>
+<taskbody>
+<context>
+<p>
+You may override the Network Server's impulse to install a security
+manager if, for some reason, you need to run your application outside
+Java's security protections.
+</p>
+
+<note othertype="" type="caution">
+You incur a severe security risk by opening
+up the server to all clients without limiting access via a security policy.
+</note>
+
+<p>
+Use the <i>-noSecurityManager</i> option to force the Network Server
+to come up without a security manager. E.g.:
+</p>
+
+<codeblock>
+java org.apache.derby.drda.NetworkServerControl start -h localhost -noSecurityManager
+</codeblock>
+
+</context>
+</taskbody>
+</task>
Propchange: db/derby/docs/trunk/src/adminguide/tadminnetservopen.dita
------------------------------------------------------------------------------
svn:eol-style = native
Modified: db/derby/docs/trunk/src/adminguide/tadminnetservrun.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/tadminnetservrun.dita?view=diff&rev=515270&r1=515269&r2=515270
==============================================================================
--- db/derby/docs/trunk/src/adminguide/tadminnetservrun.dita (original)
+++ db/derby/docs/trunk/src/adminguide/tadminnetservrun.dita Tue Mar 6 11:41:07 2007
@@ -25,50 +25,13 @@
</keywords>
</metadata></prolog>
<taskbody>
-<context> <p>You should run the Network Server under the Java security manager.
-An sample security policy file is shown in the following examples. Fine tune
-this policy to suit your needs.</p><note othertype="" type="caution">Opening
-up the server to all clients without limiting access by using a policy similar
-to the one in the following example is a severe security risk.</note><codeblock>//Recommended set of permissions to start and use the Network Server,
-//assuming the 'd:/<ph conref="adminconrefs.dita#prod/productlowercase"></ph>/lib' directory has been secured.
-//Fine tune based on your environment settings
-grant codeBase "file:d:/<ph conref="adminconrefs.dita#prod/productlowercase"></ph>/lib/-" {
-permission java.io.FilePermission "${derby.system.home}${/}-",
- "read, write, delete";
-permission java.io.FilePermission "${derby.system.home}","read";
-permission java.io.FilePermission "${user.dir}${/}-", "read, write, delete";
-permission java.util.PropertyPermission "derby.*", "read";
-permission java.util.PropertyPermission "user.dir", "read";
-permission java.lang.RuntimePermission "createClassLoader";
-permission java.net.SocketPermission "myclientmachine", "accept";
-};
-
-//Required set of permissions to stop the Network Server, assuming you have
-// secured the 'd:/<ph conref="adminconrefs.dita#prod/productlowercase"></ph>/lib' directory
-//Remember to fine tune this as per your environment.
-grant codeBase "file:d:/<ph conref="adminconrefs.dita#prod/productlowercase"></ph>/lib/-" {
-//Following is required when server is started with "-h localhost"
-//or without the -h option
-permission java.net.SocketPermission "localhost", "accept, connect, resolve";
-permission java.net.SocketPermission "127.0.0.1", "accept, connect, resolve";
-//The following is only required if the server is started with the -h <host>
-//option (else shutdown access will be denied).
-permission java.net.SocketPermission "<host>:*", "accept, connect, resolve";
-};</codeblock> </context>
-<example><ul>
-<li>The following example shows how to start the Network Server in the default
-security manager (listening to clients from <codeph>localhost</codeph> only,
-which is the default behavior if the <codeph>-h</codeph> option is not used
-to start the server). This example assumes that the policy file exists in <filepath>d:/nwsvr.policy</filepath>.<codeblock>java -Djava.security.manager -Djava.security.policy=d:/nwsvr.policy
-org.apache.derby.drda.NetworkServerControl start </codeblock></li>
-<li>You can also achieve the same behavior by using the <codeph>-h</codeph> option
-when starting the server as shown in the following example:<codeblock>java -Djava.security.manager -Djava.security.policy=d:/nwsvr.policy
-org.apache.derby.drda.NetworkServerControl start -h localhost</codeblock></li>
-<li>The following example shows how to start the Network Server (assuming
-that you start the server on the host machine <i>myserver</i>) in the default
-security manager (listening to client requests originating from other machines
-only). This example assumes that the policy file exists in <filepath>d:/nwsvr.policy</filepath>.<codeblock>java -Djava.security.manager -Djava.security.policy=d:/nwsvr.policy
-org.apache.derby.drda.NetworkServerControl start -h <i>myserver</i></codeblock></li>
-</ul></example>
+<context>
+<p>
+By default, the Network Server boots with a Basic security policy. You
+are encouraged to customize this policy to fit the security needs of
+your application and its runtime environment. You may also run the
+Network Server without a security manager, although this is not recommended.
+</p>
+</context>
</taskbody>
</task>