Skip to content

GeoFence configuration

Jump to bottom Edit New page
Emanuele Tajariol edited this page Nov 7, 2024 · 11 revisions

There are different aspects in GeoFence that may be configured:

  • the backend DBMS and related database,
  • the LDAP server,
  • the background map in the client (for the standalone GeoFence version)

All configurations are performed by providing a property file to GeoFence, in which the various configurations will be set.

Providing a configuration file

GeoFence comes with some default values which are quite good for a test run. You will want anyway to reconfigure at least the backend database. Since the custom configuration will override the default values, the configuration file will also be called the override file.

There are a couple of ways to setup the GeoFence override file:

  • If you are using the embedded version, you may use the fixed file inside the GeoServer data dir. It's located at data/geofence/geofence-datasource-ovr.properties.

  • You may use a file located anywhere in the file system. You will set the file path using a system property named geofence-ovr. Such property can be set like that:

    java .... -Dgeofence-ovr=file:/PATH/TO/OVR/FILE.properties ...

    This way of configuring the override file can be used both in the embedded and in the standalone version.

    Please note that tomcat will run the file CATALINA_BASE/bin/setenv.sh if such file exists, so that's a good place to set system properties.

    e.g.:

    export CATALINA_HOME=/usr/local/java/tomcat
export CATALINA_BASE=/var/tomcat/geofence
export JAVA_OPTS="-Dgeofence-ovr=file:${CATALINA_BASE}/conf/gf-ovr.properties"

Database configuration

By default GeoFence uses H2 as the backend DBMS; the database data files are created in the directory geofence_db/, created in the current directory (i.e. the directory selected at the moment of the launch of the webapp).

You may configure the H2 db location, or configure a completely different DBMS backend (supported DBMS are PostgreSQL+postGIS and Oracle Spatial).

In order to configure a particular DBMS, you need to:

  1. specify the DBMS driver, dialect and DB access info in the ovr property file
  2. provide the JDBC drivers and the dialect jars to the webapp.

Jar files

The web application uses the jar files contained in the WEB-INF/lib directory.

JDBC drivers

Some JDBC drivers are free and are already bundled in the geofence.war file (version number may change):

  • for H2
    • h2-1.3.172.jar
  • for PostGreSQL+PostGIS
    • postgis-jdbc-1.3.3.jar (also downloadable from here)
    • postgresql-8.4-702.jdbc3.jar

No JDBC drivers are provided for Oracle, since they are not free and you need to sign a license agreement before downloading them from the Oracle website.
If you need to use Oracle, please download the jdbc jar file and put it into WEB-INF/lib directory.

Hibernate dialects

Jar files for different dialects can not be placed in the lib/ directory at the same time (at least for hibernate spatial 1.x), since this would cause issues in class loading.

This means that, if you need to use a DBMS different to the default one (that is H2), you need to provide the webapp the proper dialect jar file. You may do this by either:

  • building a .war file for that database type (look at building instructions to learn how to get a .war for your database);
  • replacing the default H2 hibernate spatial driver (hibernate-spatial-h2-geodb-XXX.jar) in WEB-INF/lib with the one related to the DBMS you are going to use.

For your convenience, the geofence .war file already packs some dialect jar files. You only need to replace the default one with the one you need.

In WEB-INF/spatial-lib/ you will find these files:

  • hibernate-spatial-h2-geodb-1.1.3.2.jar (also downloadable from here)
  • hibernate-spatial-oracle-1.1.3.2.jar (also downloadable from here)
  • hibernate-spatial-postgis-1.1.3.2.jar (also downloadable from here)

Database configuration

These are the main properties you need to configure in order to use a specific DBMS (this sample is for configuring a PostGIS DB):

geofenceVendorAdapter.databasePlatform=org.hibernatespatial.postgis.PostgisDialect
geofenceDataSource.driverClassName=org.postgresql.Driver
geofenceDataSource.url=jdbc:postgresql://localhost:5432/geofence
geofenceDataSource.username=geofence
geofenceDataSource.password=geofence
geofenceEntityManagerFactory.jpaPropertyMap[hibernate.default_schema]=gfschema
  • the dialect tells the DB library how it should talk to the underlying DB; please make sure you have the proper jar file in your lib/ directory;
  • the driver is needed to perform the connection to the DB; you need the proper JDBC driver in you lib/ directory;
  • the url is a DBMS-specific way to set the target database instance
  • the schema is the DB schema where the GeoFence tables will be located; the configured user should have insert/select/update grants on it; if hibernate is also requested to create the schema, some higher privileges are needed
  • username and password are the access credentials to the db.

DB Schema creation

GeoFence should handle the creation of the database schema by itself; hibernate will do de magic, thanks to this configuration line in one of the override property files:

   geofenceEntityManagerFactory.jpaPropertyMap[hibernate.hbm2ddl.auto] = update

This property should be set to update only when first starting the GeoFence logic, then it can be set to validate or left blank. If you redefined the override files, you may have lost this setting, so you should put this line back in you configuration file. Also refer to the comments in this file.

In order not to rely on automatic schema update, which is usually not recommended in production envs, there used to be some sql init files, but they are quite outdated and not aligned to the current model.

H2 configuration

GeoFence is configured to use H2 as default DBMS, so you don't need to redefine all of the DB properties in order to make it work.

If you only need to configure the H2 DB file location, you only need to redefine the DB URL in the ovr file:

geofenceDataSource.url=jdbc:h2:/ABSOLUTE/DIRECTORY/PATH/FILENAME_TEMPLATE

PostGIS configuration

  • jdbc jar: should already be in the geofence webapp.
  • hibernate spatial jar file: replace the dialect as explained above
  • sample config:
geofenceVendorAdapter.databasePlatform=org.hibernatespatial.postgis.PostgisDialect
geofenceDataSource.driverClassName=org.postgresql.Driver
geofenceDataSource.url=jdbc:postgresql://localhost:5432/geofence
geofenceDataSource.username=geofence
geofenceDataSource.password=geofence
geofenceEntityManagerFactory.jpaPropertyMap[hibernate.default_schema]=gfschema

Oracle Spatial configuration

  • jdbc jar: Oracle jdbc drivers are not freely distributable, so you'll need to download the one you need from the Oracle website.
  • hibernate spatial jar file: replace the dialect as explained above
  • sample config:
geofenceVendorAdapter.databasePlatform=org.hibernatespatial.oracle.OracleSpatial10gDialect
geofenceDataSource.driverClassName=
geofenceDataSource.url=
geofenceDataSource.username=geofence
geofenceDataSource.password=geofence
geofenceEntityManagerFactory.jpaPropertyMap[hibernate.default_schema]=gfschema

LDAP server configuration

Basic connection configuration to LDAP server:

geofenceLdapSource.url=ldap://localhost:10389
geofenceLdapSource.base=dc=example,dc=com
geofenceLdapSource.userDn=uid=admin,ou=system
geofenceLdapSource.password=secret

Enabling LDAP DAOs:

geofence_dao_registry.selectedType=LDAP

Configuring user DAO:

gsUserDAO_LDAP.searchBase=ou=people
gsUserDAO_LDAP.memberFilter=member={0}
gsUserDAO_LDAP.enableHierarchicalGroups=true

These are the available properties:

  • searchBase: root for searching users
  • searchFilter: filter searching users
  • memberFilter (e.g. memberFilter=member={0}): filter for membership (groups to users)
  • nestedMemberFilter: filter for membership of groups inside other groups (defaults to memberFilter value)
  • enableHierarchicalGroups (true / false): fetches groups in a hierarchical way
  • maxLevelGroupsSearch: (defaults to inifinite): how deep to navigate groups hierarchically
  • attributesMapper: mapping of LDAP attributes to user attributes, should be set on the geofenceLdapUserMapper object
geofenceLdapUserMapper.map[id] = distinguishedName
geofenceLdapUserMapper.map[username] = cn
geofenceLdapUserMapper.map[email] = mail
geofenceLdapUserMapper.map[name] = givenName
geofenceLdapUserMapper.map[surname] = sn

Configuring usergroup DAO:

userGroupDAO_LDAP.searchBase=ou=groups
userGroupDAO_LDAP.searchFilter=objectClass=groupOfNames

These are the available properties:

  • searchBase: root for searching groups
  • searchFilter: filter searching groups
  • attributesMapper: mapping of LDAP attributes to group attributes, should be set on the geofenceLdapGroupMapper object
geofenceLdapGroupMapper.map[id] = distinguishedName
geofenceLdapGroupMapper.map[groupname] = cn
geofenceLdapGroupMapper.map[member] = member

Background layers configuration

You may want to configure the base layer in the map client in GeoFence.
These are the keys you have to set in the ovr file; the values you see here are the default values:

geofenceGlobalConfiguration.baseLayerURL=http://vmap0.tiles.osgeo.org/wms/vmap0
geofenceGlobalConfiguration.baseLayerName=Vmap0
geofenceGlobalConfiguration.baseLayerTitle=OSGeo base map
geofenceGlobalConfiguration.baseLayerFormat=image/png
geofenceGlobalConfiguration.baseLayerStyle=
geofenceGlobalConfiguration.mapCenterLon=0
geofenceGlobalConfiguration.mapCenterLat=0
geofenceGlobalConfiguration.mapZoom=2

Password encryption

In case you are using GeoFence's own DB to store users (so it means we are in the standalone scenario), please note that it is possible (and highly advisable) to use a custom key for encrypting the credentials passwords in the DB by specifying the GEOFENCE_PWENCODER_KEY system property.

To do so, add -DGEOFENCE_PWENCODER_KEY=<your-key> to the JAVA_OPTS variable; for example in your CATALINA_BASE/bin/setenv.sh:

export JAVA_OPTS="$JAVA_OPTS -DGEOFENCE_PWENCODER_KEY=<your-key>"

Your custom key must be 16 characters long, or it will be ignored.

Please note that if this property is added or modified after users are added to the DB, such users will not be able to authenticate properly, since the passwords can't be decrypted with a different encoding key.

This means that in case you need to set up this property, you have to do it before adding any user to GeoFence, or you'll need to set the passwords again for all the users.

Other config

Please look at this file
https://github.com/geoserver/geofence/blob/master/src/gui/web/src/main/resources/geofence-datasource-ovr.properties.sample
to find out other more specific available configuration.

Add a custom footer
Clone this wiki locally