Mercurial > hg > digilib

comparison doc/src/site/markdown/digilib-config.md @ 1216:bd7dfa8b164e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
move new digilib doc from https://it-dev.mpiwg-berlin.mpg.de/hg/digilib-doc into main repo.
author robcast
date Fri, 06 Sep 2013 10:25:05 +0200
parents
children 3017ade24bbb
comparison
equal deleted inserted replaced
1215:68625b3c5341 1216:bd7dfa8b164e
1 # Configuring digilib
2
3 ## digilib-config.xml
4
5 The main configuration for digilib is `digilib-config.xml` in the `WEB-INF`
6 directory in the webapp.
7 (If you really need a different location you can define it in the `config-file`
8 init-parameter to the Servlet.)
9
10 In the XML-based configuration file you can set several paths and options.
11
12 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
14 path following the conventions of your operating system (a relative path
15 is taken to be relative to the web application directory).
16
17 You need only one directory if you don't want to provide pre-scaled low resolution
18 versions of your images. If you have pre-scaled images the directory with the
19 high-resolution images must be the first entry in the list.
20
21 Documentation on the directory layout and on using pre-scaled images is
22 [here](image-directories.md).
23
24 A minimal configuration looks like this:
25
26 <!-- Digilib servlet config file -->
27 <digilib-config>
28 <!-- List of directories where images are searched.
29 The authoritative directory with the high-resolution images
30 is first in list. -->
31 <parameter name="basedir-list" value="/docuserver/images" />
32 </digilib-config>
33
34 A more customized configuration may look like this (for a full list of
35 configuration options use the source:
36 [1](http://hg.berlios.de/repos/digilib/file/default/common/src/main/java/digilib/conf/DigilibConfiguration.java)
37 [2](http://hg.berlios.de/repos/digilib/file/default/servlet/src/main/java/digilib/conf/DigilibServletConfiguration.java)
38 [3](http://hg.berlios.de/repos/digilib/file/default/servlet3/src/main/java/digilib/conf/DigilibServlet3Configuration.java)
39 ):
40
41 <!-- Digilib servlet config file -->
42 <digilib-config>
43 <!-- Image to be sent to indicate general failure. -->
44 <parameter name="error-image" value="/docuserver/images/icons/broken.gif" />
45
46 <!-- Image to be sent to indicate authorization failure. -->
47 <parameter name="denied-image" value="/docuserver/images/icons/alert.red.gif" />
48
49 <!-- Image to be sent to indicate file-not-found. -->
50 <parameter name="notfound-image" value="/docuserver/images/icons/notfound.gif" />
51
52 <!-- List of directories where images are searched.
53 The authoritative directory with the high-resolution images
54 is first in list. -->
55 <parameter name="basedir-list" value="/docuserver/images:/docuserver/scaled/small" />
56
57 <!-- mimimum amount of scaling done with antialiasing -->
58 <parameter name="subsample-minimum" value="2"/>
59
60 <!-- default interpolation quality (0=worst) -->
61 <parameter name="default-quality" value="2"/>
62
63 <!-- is sending whole image files with mo=file allowed? -->
64 <parameter name="sendfile-allowed" value="true" />
65
66 <!-- the a maximum size of any sent image. (0 means no limit) -->
67 <parameter name="max-image-size" value="0" />
68
69 <!-- number of working threads -->
70 <parameter name="worker-threads" value="2" />
71
72 <!-- number of waiting requests in queue -->
73 <parameter name="max-waiting-threads" value="20" />
74
75 <!-- Restrict access to authorized users.
76 User authentication and roles are provided by the servlet container
77 (see tomcat-users.xml).
78 Authorization for resources (directories) is evaluated by the servlet
79 (see auth-file). -->
80 <parameter name="use-authorization" value="false"/>
81
82 <!-- Location of XML file with authorization requirements. -->
83 <parameter name="auth-file" value="digilib-auth.xml"/>
84
85 <!-- Part of URL to indicate authenticated access to Tomcat. -->
86 <parameter name="auth-url-path" value="authenticated/"/>
87
88 <!-- use mapping of "virtual directories" to real directories on the server -->
89 <parameter name="use-mapping" value="false"/>
90
91 <!-- location of XML mapping file -->
92 <parameter name="mapping-file" value="digilib-map.xml"/>
93
94 <!-- location of logger config file -->
95 <parameter name="log-config-file" value="log4j-config.xml"/>
96 </digilib-config>
97
98 You can supply your own icons for the "error" and "access denied"
99 messages by the servlet. Standard images will be used if these
100 parameters are not defined.
101
102 You can specify the Java toolkit implementation with the `docuimage-class`
103 parameter. The `ImageLoaderDocuImage` usually gives best performance
104 and works with JDK 1.4 and up.
105
106 You can see a summary of your running digilib configuration at the URL
107 [http://localhost:8080/digitallibrary/server/dlConfig.jsp](http://localhost:8080/digitallibrary/server/dlConfig.jsp)
108
109
110 ## digilib-auth.xml
111
112 The digilib access authorization is defined in the file defined by the `auth-file`
113 parameter (default: `digilib-auth.xml` in `WEB-INF` ).
114
115 The file has two parts `diglib-paths` and `diglib-addresses`. It looks like this:
116
117 <auth-config>
118
119 <digilib-paths>
120 <!--
121 A user must supply one of the roles under "role"
122 to access the directory "name".
123 Roles under "role" must be separated by comma only (no spaces).
124 -->
125 <path name="histast/eastwood-collection" role="eastwood-coll" />
126 <path name="ptolemaios_geo" role="ptolemaios-geo" />
127 </digilib-paths>
128
129 <digilib-addresses>
130 <!--
131 A computer with an ip address that matches "ip"
132 is automatically granted all roles under "role".
133 The ip address is matched from the left (in full quads).
134 Roles under "role" must be separated by comma only (no spaces).
135 -->
136 <address ip="127" role="local" />
137 <address ip="130.92.68" role="eastwood-coll,ptolemaios-geo" />
138 <address ip="130.92.151" role="ALL" />
139 </digilib-addresses>
140
141 </auth-config>
142
143 `diglib-paths` defines restricted directories and the roles needed
144 for access. The roles are defined with the users in `tomcat-users.xml`
145 (see above). All subdirectories of the given directories have the same
146 restrictions. All directories not listed here (and not subdirectories of listed
147 directories) are freely accessible.
148
149 `diglib-addresses` defines hosts or networks of computers that are
150 automatically authenticated without username and password. Hosts can be assigned
151 roles. The special keyword `ALL` authorizes for everything. If the
152 role assigned to the computer is not sufficient to access a resource the user
153 will be asked for username and password.
154