Mercurial > hg > digilib

comparison doc/src/site/markdown/digilib-config.md @ 1530:70e1225fe08c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added auth* documentation.
author robcast
date Thu, 08 Sep 2016 19:54:38 +0200
parents 7770ac493446
children 7310735dd5b5
comparison
equal deleted inserted replaced
1529:b330eafffed6 1530:70e1225fe08c
1 # Configuring digilib 1 # Configuring digilib
2 2
3 ## digilib-config.xml 3 ## digilib-config.xml
4 4
5 The main configuration for digilib is `digilib-config.xml` in the `WEB-INF` 5 The main configuration for digilib is the XML file `digilib-config.xml` in the `WEB-INF`
6 directory in the webapp. 6 directory in the webapp or a Java properties file `digilib.properties` somewhere in the classpath.
7 (If you really need a different location you can define it in the `config-file` 7 (If you really need a different location for the XML file you can define it in the `config-file`
8 init-parameter to the Servlet.) 8 init-parameter to the Servlet.)
9 9
10 In the XML-based configuration file you can set several paths and options. 10 In the configuration file you can set lots of paths and options. digilib uses
11 default values for all configuration settings that meet most requirements
12 so you have to configure only the settings that you want to change.
11 13
12 You have to adjust the **`basedir-list`** parameter to the directories 14 You have to adjust the **`basedir-list`** parameter to the directories
13 where your images are installed. The directory path has to be an absolute 15 where your images are installed. The directory path has to be an absolute
14 path following the conventions of your operating system (a relative path 16 path following the conventions of your operating system (a relative path
15 is taken to be relative to the web application directory). 17 is taken to be relative to the web application directory).
29 The authoritative directory with the high-resolution images 31 The authoritative directory with the high-resolution images
30 is first in list. --> 32 is first in list. -->
31 <parameter name="basedir-list" value="/docuserver/images" /> 33 <parameter name="basedir-list" value="/docuserver/images" />
32 </digilib-config> 34 </digilib-config>
33 35
34 A more customized configuration may look like this (for a full list of 36 A more customized configuration may look like the following
35 configuration options use the source: 37 (for another commented example see
36 [1](https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java) 38 [digilib-config.xml.template](https://sourceforge.net/p/digilib/code/ci/default/tree/webapp/src/main/webapp/WEB-INF/digilib-config.xml.template),
37 [2](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java) 39 for a full list of
38 [3](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java) 40 configuration options and their default values use the source:
41 [DigilibConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/common/src/main/java/digilib/conf/DigilibConfiguration.java),
42 [DigilibServletConfiguration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java),
43 [DigilibServlet3Configuration](https://sourceforge.net/p/digilib/code/ci/default/tree/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java)
39 ): 44 ):
40 45
41 <!-- Digilib servlet config file --> 46 <!-- Digilib servlet config file -->
42 <digilib-config> 47 <digilib-config>
43 <!-- Image to be sent to indicate general failure. --> 48 <!-- Image to be sent to indicate general failure. -->
67 <parameter name="worker-threads" value="2" /> 72 <parameter name="worker-threads" value="2" />
68 73
69 <!-- number of waiting requests in queue --> 74 <!-- number of waiting requests in queue -->
70 <parameter name="max-waiting-threads" value="20" /> 75 <parameter name="max-waiting-threads" value="20" />
71 76
72 <!-- Restrict access to authorized users. 77 <!-- Restrict access to authorized users -->
73 User authentication and roles are provided by the servlet container
74 (see tomcat-users.xml).
75 Authorization for resources (directories) is evaluated by the servlet
76 (see auth-file). -->
77 <parameter name="use-authorization" value="false"/> 78 <parameter name="use-authorization" value="false"/>
78 79
79 <!-- Location of XML file with authorization requirements. -->
80 <parameter name="auth-file" value="digilib-auth.xml"/>
81
82 <!-- Part of URL to indicate authenticated access to Tomcat. -->
83 <parameter name="auth-url-path" value="authenticated/"/>
84
85 <!-- use mapping of "virtual directories" to real directories on the server --> 80 <!-- use mapping of "virtual directories" to real directories on the server -->
86 <parameter name="use-mapping" value="false"/> 81 <parameter name="use-mapping" value="true"/>
87 82
88 <!-- location of XML name mapping file --> 83 <!-- location of XML name mapping file -->
89 <parameter name="mapping-file" value="digilib-map.xml"/> 84 <parameter name="mapping-file" value="digilib-map.xml"/>
90 85
91 <!-- location of logger config file --> 86 <!-- location of logger config file -->
94 89
95 You can supply your own icons for the "error" and "access denied" 90 You can supply your own icons for the "error" and "access denied"
96 messages by the servlet. Standard images will be used if these 91 messages by the servlet. Standard images will be used if these
97 parameters are not defined. 92 parameters are not defined.
98 93
99 You can specify the Java toolkit implementation with the `docuimage-class` 94 If you need authorization set `use-authorization` to true and read the
100 parameter. The `ImageLoaderDocuImage` usually gives best performance 95 [documentation on authentication and authorization](auth.html).
101 and works with JDK 1.4 and up.
102 96
103 You can see a summary of your running digilib configuration at the URL 97 You can see a summary of your running digilib configuration at the URL
104 [http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp) 98 [http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp)
105 99
106
107 ## digilib-auth.xml
108
109 The digilib access authorization is defined in the file defined by the `auth-file`
110 parameter (default: `digilib-auth.xml` in `WEB-INF` ).
111
112 The file has two parts `diglib-paths` and `diglib-addresses`. It looks like this:
113
114 <auth-config>
115
116 <digilib-paths>
117 <!--
118 A user must supply one of the roles under "role"
119 to access the directory "name".
120 Roles under "role" must be separated by comma only (no spaces).
121 -->
122 <path name="histast/eastwood-collection" role="eastwood-coll" />
123 <path name="ptolemaios_geo" role="ptolemaios-geo" />
124 </digilib-paths>
125
126 <digilib-addresses>
127 <!--
128 A computer with an ip address that matches "ip"
129 is automatically granted all roles under "role".
130 The ip address is matched from the left (in full quads).
131 Roles under "role" must be separated by comma only (no spaces).
132 -->
133 <address ip="127" role="local" />
134 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
135 <address ip="130.92.151" role="ALL" />
136 </digilib-addresses>
137
138 </auth-config>
139
140 `diglib-paths` defines restricted directories and the roles needed
141 for access. The roles are defined with the users in `tomcat-users.xml`
142 (see above). All subdirectories of the given directories have the same
143 restrictions. All directories not listed here (and not subdirectories of listed
144 directories) are freely accessible.
145
146 `diglib-addresses` defines hosts or networks of computers that are
147 automatically authenticated without username and password. Hosts can be assigned
148 roles. The special keyword `ALL` authorizes for everything. If the
149 role assigned to the computer is not sufficient to access a resource the user
150 will be asked for username and password.
151 100