Project

General

Profile

1
Configuring Metacat
2
===================
3

    
4
.. contents::
5
  
6
When Metacat (Tomcat) is started, the Metacat servlet checks to see if it is 
7
configured. If not, Metacat will automatically send you to the configuration 
8
pages. 
9

    
10
If the installation is new, or the previous version is before 1.9.0, pay close 
11
attention to the configuration values. If you have upgraded Metacat, and the 
12
previous version is 1.9.0 or later, Metacat will pull existing configuration 
13
settings from a backup location. You should still verify that the values are 
14
correct.
15

    
16
To access your Metacat, open a Web browser and type::
17

    
18
  http://<your_context_url>
19

    
20
Where <your_context_url> is the URL of the server hosting the Metacat followed 
21
by the name of the WAR file (i.e., the application context) that you installed.
22
For instance, the context URL for the KNB Metacat is: http://knb.ecoinformatics.org/knb
23

    
24
You can always open the configuration screen from within Metacat by typing::
25

    
26
  http://<your_context_url>/admin
27

    
28
Initial Configuration
29
---------------------
30
Before you can log in to the Metacat and configure it, you are required to 
31
confirm Metacat's back-up location and authentication configuration (if not 
32
already configured). Metacat will automatically attempt to locate an existing 
33
back-up directory, but you may need to correct the value or specify a directory 
34
(if the installation is new, or if Metacat was unable to determine the location 
35
of an existing back-up directory). The authentication configuration is required 
36
for logging in to the Metacat and for defining administrative accounts. 
37
Instructions for `Changing Authentication Configuration without Authentication`_ 
38
are included at the end of this section.
39

    
40
Back-up Configuration
41
~~~~~~~~~~~~~~~~~~~~~
42
To preserve its configuration settings, Metacat backs up crucial configuration details to 
43
a directory outside the application directories. Because a new installation/upgrade 
44
does not know where this external directory is, Metacat uses a discovery 
45
algorithm to locate it. If Metacat cannot identify a backup directory, you will 
46
see the Backup Directory Configuration screen.
47

    
48
.. Note:: 
49
  
50
  If the metacat.properties file has many custom settings, it should be manually 
51
  backed up before any Metacat upgrade as deploying a new Metacat war file will overwrite
52
  the existing file.
53

    
54
.. figure:: images/screenshots/image011.png
55
   :align: center
56

    
57
   Configuring the Backup Directory.
58
   
59
Authentication Configuration
60
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61
Whether you are installing or upgrading the Metacat servlet, you will 
62
automatically be sent to the Authentication Configuration page. You can also 
63
reach the Authentication Configuration page from a running Metacat by typing::
64
  
65
  http://<your_context_url>/admin
66

    
67
Metacat uses either an internal password file or LDAP as its authentication mechanism.
68
You can choose the authentication mechanism by selecting either AuthFile or AuthLdap class.
69
We will only allow trusted partners to access the NCEAS LDAP server to ensure the security of our user base.
70
If you are not in the trusted partner list, you may choose the internal password file authentication 
71
or set up your own LDAP server. You also can define your own authentication mechanism by creating a Java 
72
class that implements ``AuthInterface``.
73

    
74
Required configuration values for the password file authentication are:
75

    
76
  ::
77
   
78
    Authentication Class
79
    Metacat Administrators
80
    Users Management URL
81
    Password File Path.
82

    
83
Required configuration values for LDAP authentication are:
84

    
85
  ::
86
   
87
    Authentication Class
88
    Metacat Administrators
89
    Users Management URL
90
    Authentication URL
91
    Authentication Secure URL. 
92

    
93

    
94
Make sure that your user account information is entered into the Metacat 
95
Administrators field (e.g., uid=daigle,o=nceas,dc=ecoinformatics,dc=org). You 
96
will not be allowed to continue with configuration if this is missing. Multiple 
97
accounts can be entered, separated by the colon (:) character.
98

    
99
.. Note:: 
100
  
101
  To create an account on the password file, please see the section called :doc:`authinterface`.
102
  To create an LDAP account on the KNB LDAP server (specified as the default LDAP server), 
103
  go to https://identity.nceas.ucsb.edu and select the "create a new user account" link.
104

    
105
If you make changes to the authentication settings, you must restart Tomcat to 
106
put them into effect.
107

    
108
.. figure:: images/screenshots/image071.png
109
   :align: center
110

    
111
   Configuring Password File Authentication Values.
112

    
113
.. figure:: images/screenshots/image009.png
114
   :align: center
115

    
116
   Configuring LDAP Authentication Values.
117

    
118
Changing Authentication Configuration without Authentication
119
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
120
If you need to change or add authentication information and cannot authenticate 
121
using the existing authentication settings (e.g., the existing Metacat 
122
administrator is no longer available or you forgot the administrator password), 
123
you must edit the Metacat configuration file by hand. This ensures that only a 
124
person who has access to the Metacat server and the configuration files on that 
125
server will be able to change the administrator accounts.
126

    
127
To edit the authentication configuration file:
128

    
129
1. Stop Tomcat and edit the Metacat properties (``metacat.properties``) file in the
130
   Metacat context directory inside the Tomcat application directory. The 
131
   Metacat context directory is the name of the application (usually metacat):
132

    
133
  ::
134
  
135
    <tomcat_app_dir>/<context_dir>/WEB-INF/metacat.properties
136

    
137
2. Change the following properties appropriately:
138

    
139
  ::
140
  
141
    auth.administrators - a colon separated list of administrators 
142
    auth.url - the authentication server URL 
143
    auth.surl - the authentication secure server URL
144
    auth.file.path  - the authentication password file path
145

    
146
3. Save the ``metacat.properties`` file and start Tomcat.
147

    
148

    
149
Logging in to Metacat
150
---------------------
151
In order to configure Metacat, you must log in with an administrative account 
152
that has been configured in the Authentication Configuration settings. If you 
153
did not set up the correct administrative user there, you must change the 
154
authentication configuration by hand before you can log in.
155

    
156
In the log-in screen enter your user name and password and click 
157
the "Login" button.
158

    
159
.. figure:: images/screenshots/image015.png
160
   :align: center
161

    
162
   Logging into Metacat.
163
   
164
Required Configuration
165
----------------------
166
All required Metacat settings can be accessed from the Metacat Configuration 
167
utility, which becomes available after the initial configurations 
168
have been specified and an authorized administrator logs in. 
169

    
170
.. figure:: images/screenshots/image017.png
171
   :align: center
172

    
173
   Metacat configuration menu, showing each configuration section.  Once all
174
   sections are marked as green ``configured``, metacat can be accessed.
175

    
176
The configuration settings are grouped into five sections (Metacat Global 
177
Properties, Authentication Configuration, Skins Specific Properties, Database 
178
Installation/Upgrade, Geoserver, DataONE, and Replication Configuration), 
179
each of which is listed with its current status (see table).
180

    
181
==============  =============================================================
182
Status          Description
183
==============  =============================================================
184
unconfigured    The section has yet to be configured 
185
configured      The section has been configured. 
186
bypassed        The administrator 
187
                can choose not to configure or skip the section.
188
==============  =============================================================
189
 
190
To the right of each configuration section is one of the following options: 
191
Configure Now, Reconfigure Now, Configure Global Properties First, or 
192
Version:X.X.X. If the option is linked (e.g., Configure Now or Reconfigure Now), 
193
you can select the link to open the associated configuration settings and edit them. 
194
If the option is not linked (e.g., Configure Global 
195
Properties First), the settings cannot be specified until the global properties 
196
are set. Once the global properties are configured, the option to configure this 
197
section becomes available. The Version:X.X.X option is used only for the 
198
Database Installation/Upgrade section. If the database schema version detected 
199
by Metacat matches the application version (eg, 1.9.0), then no further database 
200
configuration is required.
201

    
202
All settings must be in a configured or bypassed state in order to run Metacat. 
203
For new installations or upgrades, click the "go to metacat" link that appears 
204
after configuration is complete to go directly to Metacat. Note that Metacat 
205
indexes at start-up time, so the initial start-up may take some time depending 
206
on the amount of data in your database and wheter or not you have opted to regenerate the spatial cache. 
207
If you are reconfiguring a running 
208
version of Metacat, you must restart the Tomcat server for the changes to 
209
take effect.
210
   
211
.. figure:: images/screenshots/image019.png
212
   :align: center
213

    
214
   The Metacat settings as they appear after having been configured.
215
   
216
Global Properties (server, ports, etc)
217
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
218
The Metacat configurations included under Global Properties represent the bulk 
219
of the settings required to run Metacat. Click a blue question-mark 
220
icon beside any setting for detailed instructions. More information about each 
221
property is also included in the :doc:`metacat-properties`.
222

    
223
.. figure:: images/screenshots/image021.png
224
   :align: center
225

    
226
   The Metacat Global Properties editing screen.
227
   
228
When you save global properties, Metacat also saves a back-up file that is 
229
located in ``/var/metacat/.metacat`` (on Linux) or 
230
``C:\Program Files\metacat\.metacat`` (on Windows). When you update Metacat, 
231
the system automatically locates the back-up file so you do not have to re-enter 
232
the configuration settings.
233

    
234
The first time you install Metacat, the system attempts to automatically detect 
235
the values for a number of settings (see table). It is important to ensure that 
236
these values are correct.
237

    
238
================  ============================================================
239
Property          Description
240
================  ============================================================
241
Metacat Context   The name of the deployed Metacat WAR file (minus the .war 
242
                  extension). E.g., "metacat"
243
Server Name       The DNS name of the server hosting Metacat, not including 
244
                  port numbers or the protocol ("http://"). 
245
HTTP Port         The non-secure port where Metacat will be available.
246
HTTP SSL Port     The secure port where Metacat will be available. 
247
Deploy Location   The directory where the application is deployed. 
248
================  ============================================================
249

    
250
Authentication Configuration
251
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
252
Because you must specify the Authentication settings before you can access the 
253
main configuration page, the settings will always be configured when you view 
254
them in the admin interface. If you wish to change the authentication settings, 
255
you must restart Metacat to put the changes into effect. For more information 
256
about the Authentication configurations, please see Initial Configurations.
257

    
258
Skins Configuration 
259
~~~~~~~~~~~~~~~~~~~   
260
Customizing the look and feel of Metacat's web interface is done via skins or
261
MetacatUI themes, however as of Version 2.2.0, skins have been deprecated. 
262
Use MetacatUI themes instead. Themes can be deployed separately from the 
263
Metacat server allowing easier independent user interface customization.
264

    
265
MetacatUI Themes
266
................
267
Themes are applied in the Skins Configuration section. If you have installed 
268
the optional Registry, which provides a web interface for creating, editing, 
269
and submitting content to Metacat, you can also choose which form fields 
270
appear in that interface and which are required. Note that if you do not have 
271
a custom theme AND you are not using the Registry, you can simply save the 
272
``metacatui`` default configuration.
273

    
274
To use the new MetacatUI theming system, select ``metacatui`` and click the 
275
``Make metacatui default`` radio button. Metacat will open a list of options 
276
that apply to the Registry interface. For more information about creating 
277
custom themes, see the section called :doc:`themes`.
278

    
279
.. figure:: images/screenshots/image070.png
280
   :align: center
281

    
282
   Configuring Metacat themes.
283

    
284
Skins
285
................
286
.. deprecated:2.2.0
287
   Use themes instead
288
   
289
If your Metacat has a customized skin, it will appear as a choice in the 
290
Skins Configuration settings (see below screenshot). Select the checkbox next 
291
to your customized skin or and click the ``Make <skin_name> default`` radio button. 
292
If you do not have a custom skin, select the ``default`` skin. 
293

    
294
Once you have selected a skin, Metacat will open a list of options that apply to the Registry 
295
interface. For more information about creating skins, see the Creating a Custom Skin
296
section in :doc:`themes`.
297

    
298
.. figure:: images/screenshots/image023.png
299
   :align: center
300

    
301
   Configuring Metacat skins.
302
   
303
Select the checkbox next to your customized skin or and click the 
304
``Make <skin_name> default`` radio button. If you do not have a custom skin, 
305
select the ``default`` skin. Once you have selected a skin, Metacat will open 
306
a list of options that apply to the Registry interface.
307

    
308
.. figure:: images/screenshots/image025.png
309
   :align: center
310

    
311
   Configuring Metacat skins.
312

    
313
Select the lists and modules that you would like to appear in the Registry 
314
form-interface by checking the box beside each. When you save the configuration, 
315
the customized interface will appear to site visitors.
316

    
317
Database Configuration
318
~~~~~~~~~~~~~~~~~~~~~~
319
Because the Database Configuration is dependent on values specified in the 
320
Global Properties section, the link to these settings does not become active 
321
until after the global settings have been saved. Once the global settings have 
322
been saved, Metacat automatically detects the database schema version and 
323
upgrades it if necessary (and with your permission). 
324

    
325
* New Installation
326
* Upgrade
327

    
328
New Installation
329
................
330
If Metacat determines that your database is new, the Database Install/Upgrade 
331
utility lists the SQL scripts that will run in order to create a database 
332
schema for the new version of Metacat.
333

    
334
.. figure:: images/screenshots/image027.png
335
   :align: center
336

    
337
   Database installation creates tables needed for Metacat.
338
   
339
If the database is not new, or if you have any questions about whether it is 
340
new or not, choose Cancel and contact support at knb-help@nceas.ucsb.edu. 
341

    
342
When you choose Continue, Metacat runs the listed scripts and creates the 
343
database schema.
344

    
345
Upgrade
346
.......
347
If Metacat identifies a previous database schema, the Database Install/Upgrade 
348
utility notes the existing version and lists the SQL scripts that will run in 
349
order to update the schema for the new version of Metacat.
350

    
351
If the detected schema version is incorrect, or if you have any questions about 
352
whether it is correct or not, click the Cancel button and contact support at 
353
knb-help@nceas.ucsb.edu.When you choose to continue, Metacat runs the listed 
354
scripts and updates the database schema.
355

    
356
.. figure:: images/screenshots/image029.png
357
   :align: center
358

    
359
   Upgrading an existing database.
360
   
361
Additional upgrade tasks may also run after the database upgrade is complete.
362
For systems hosting large amounts of data, these upgrade routines can take time to complete.
363
It is important to let the process complete before using Metacat otherwise your deployment may become unstable.
364
   
365

    
366
Geoserver Configuration (Highly Recommended)
367
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
368
.. sidebar:: Manual Geoserver Update
369

    
370
  Alternatively, you can change the Geoserver username and password manually by 
371
  directly logging in to the Geoserver. To configure the credentials manually: 
372

    
373
  1. Go to the Geoserver admin page: http://<your_context_url>/geoserver/ 
374
  2. Log in using the default username and password ( admin / geoserver ) 
375
  3. Navigate to the Password Change Page.  Enter a new user and password and click Submit. 
376
  4. Click Apply then Save to save your new password. 
377
  
378
Metacat comes bundled with a Web Mapping Service called Geoserver, which 
379
converts spatial data into Web-deliverable map images. Geoserver installs with 
380
a default administrative username and password. *We highly recommend that you 
381
change the default credentials so that only local administrators can make 
382
changes to your Geoserver.* For more information about Geoserver, 
383
see :doc:`geoserver`.
384

    
385
When you choose the Geoserver Configuration link from the main configuration 
386
screen, Metacat will prompt you for a few important details about your Geoserver 
387
installation. The data directory and context settings allow Geoserver and 
388
Metacat to share the same spatial data store and render maps within Metacat skins. 
389
The security configuration prompts for a new admin password. After you enter 
390
the new settings, Metacat writes the information to the Geoserver deployment.
391

    
392
The default settings are typically appropriate for most Metacat deployments, 
393
but if you wish to skip the Geoserver configuration, click the Bypass button. 
394
Geoserver (if deployed) will remain with a default configuration and the main 
395
Metacat configuration screen will display the "bypassed" status beside the 
396
Geoserver settings. You will be able to run Metacat, but maps will not be 
397
rendered.
398

    
399
.. figure:: images/screenshots/image031.png
400
   :align: center
401

    
402
   Configuring Geoserver.
403

    
404
DataONE Configuration
405
~~~~~~~~~~~~~~~~~~~~~
406
Metacat can be configured to operate as a Member Node within the DataONE
407
federation of data repositories.  See :doc:`dataone` for background and details
408
on DataONE and details about configuring Metacat to act as a DataONE Member Node.
409

    
410
Replication Configuration
411
~~~~~~~~~~~~~~~~~~~~~~~~~
412
Metacat can be configured to replicate its metadata and/or data content to another
413
Metacat instance for backup and redundancy purposes, as well as to share data across
414
sites.  This feature has been used to create the Knowledge Network for Biocomplexity
415
(KNB), as well as other networks.  See :doc:`replication` for details on
416
the replication system and how to configure Metacat to replicate with another node.
417

    
418
.. Note:: 
419
  
420
  Note that much of the functionality provided by the replication subsystem in Metacat
421
  has now been generalized and standardized by DataONE, so consider utilizing the
422
  DataONE services for replication as it is a more general and standardized approach
423
  than this Metacat-specific replication system.  The Metacat replication system
424
  will be supported for a while longer, but will likely be deprecated in a future
425
  release in favor of using the DataONE replication approach. 
426

    
427
Additional Configuration
428
------------------------
429
The most dynamic Metacat properties are managed and modified with the 
430
form-based Metacat Configuration utility. These configuration properties can 
431
also be accessed directly (along with additional static properties) via 
432
Metacat's property files: ``metacat.properties`` (which contains global 
433
properties, e.g., authorization and database values) and 
434
``<SKIN_NAME>.properties`` (which contains skin-specific properties). Each of 
435
these property files is discussed in more depth in this section.
436

    
437
The ``metacat.properties`` file
438
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
439
Metacat's ``metacat.properties`` file contains all of Metacat's global 
440
properties, both the dynamic properties, which are managed with the 
441
Configuration utility, as well as the more static properties, which can only 
442
be modified manually in this file. The ``metacat.properties`` file also contains 
443
optional properties that are only relevant when optional Metacat features 
444
(such as the harvester or replication) are enabled. The `
445
`metacat.properties file`` is found here::
446

    
447
  <CONTEXT_DIR>/WEB_INF/metacat.properties
448

    
449
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
450
lives (e.g., ``/var/lib/tomcat6/webapps/metacat``). The path is a combination 
451
of the Web application directory (e.g., ``/var/lib/tomcat6/webapps/``) and 
452
the Metacat context directory (e.g., ``metacat``). Both values depend upon how your 
453
system was set up during installation.
454

    
455
For information about each property and default or example settings, please 
456
see the :doc:`metacat-properties`. Properties that can only be edited manually 
457
in the metacat.properties file are highlighted in the appendix.
458

    
459
<SKIN_NAME>.properties
460
~~~~~~~~~~~~~~~~~~~~~~
461
The ``<SKIN_NAME>.properties`` file contains skin-specific properties 
462
(e.g., template information). For each skin, the skin-specific properties are 
463
found here::
464

    
465
  <CONTEXT_DIR>/style/skins/<SKIN_NAME>/<SKIN_NAME>.properties
466

    
467
Where ``<CONTEXT_DIR>`` is the directory in which the Metacat application code 
468
lives (described above) and ``<SKIN_NAME>`` is the name of the skin 
469
(e.g., ``default`` or ``nceas``).
(3-3/23)